Add docs and rename exit_on_error to throw_on_error

Author: suricactus

README.md

@@ -158,7 +158,7 @@ qfieldcloud-cli upload-files [OPTIONS] PROJECT_ID PROJECT_PATH
 Options:
   --filter TEXT                   Do not upload the whole project, but only
                                   the files which match the glob.
-  --exit-on-error / --no-exit-on-error
+  --throw-on-error / --no-throw-on-error
                                   If any project file upload fails stop
                                   uploading the rest. Default: False
 ```
@@ -173,7 +173,7 @@ qfieldcloud-cli download-files [OPTIONS] PROJECT_ID LOCAL_DIR
 Options:
   --filter TEXT                   Do not download the whole project, but only
                                   the files which match the glob.
-  --exit-on-error / --no-exit-on-error
+  --throw-on-error / --no-throw-on-error
                                   If any project file downloads fails stop
                                   downloading the rest. Default: False
 ```
@@ -186,7 +186,7 @@ Delete QFieldCloud project files.
 qfieldcloud-cli delete-files [OPTIONS] PROJECT_ID PATHS...
 
 Options:
-  --exit-on-error / --no-exit-on-error
+  --throw-on-error / --no-throw-on-error
                                   If any project file delete operations fails
                                   stop, stop deleting the rest. Default: False
 ```
@@ -240,7 +240,7 @@ qfieldcloud-cli package-download [OPTIONS] PROJECT_ID LOCAL_DIR
 Options:
   --filter TEXT                   Do not download the whole packaged project,
                                   but only the files which match the glob.
-  --exit-on-error / --no-exit-on-error
+  --throw-on-error / --no-throw-on-error
                                   If any packaged file downloads fails stop
                                   downloading the rest. Default: False
 ```

src/bin/qfieldcloud-cli

@@ -236,11 +236,11 @@ def delete_project(ctx, project_id):
     help="Do not upload the whole project, but only the files which match the glob.",
 )
 @click.option(
-    "--exit-on-error/--no-exit-on-error",
+    "--throw-on-error/--no-throw-on-error",
     help="If any project file upload fails stop uploading the rest. Default: False",
 )
 @click.pass_context
-def upload_files(ctx, project_id, project_path, filter_glob, exit_on_error):
+def upload_files(ctx, project_id, project_path, filter_glob, throw_on_error):
     """Upload files to a QFieldCloud project."""
 
     log(f'Uploading files "{project_id}" from {project_path}…')
@@ -250,7 +250,7 @@ def upload_files(ctx, project_id, project_path, filter_glob, exit_on_error):
         sdk.FileTransferType.PROJECT,
         project_path,
         filter_glob=filter_glob,
-        exit_on_error=exit_on_error,
+        throw_on_error=throw_on_error,
         show_progress=True,
     )
 
@@ -275,17 +275,17 @@ def upload_files(ctx, project_id, project_path, filter_glob, exit_on_error):
     help="Do not download the whole project, but only the files which match the glob.",
 )
 @click.option(
-    "--exit-on-error/--no-exit-on-error",
+    "--throw-on-error/--no-throw-on-error",
     help="If any project file downloads fails stop downloading the rest. Default: False",
 )
 @click.pass_context
-def download_files(ctx, project_id, local_dir, filter_glob, exit_on_error):
+def download_files(ctx, project_id, local_dir, filter_glob, throw_on_error):
     """Download QFieldCloud project files."""
 
     log(f'Downloading project "{project_id}" files to {local_dir}…')
 
     files = ctx.obj["client"].download_project(
-        project_id, local_dir, filter_glob, exit_on_error, show_progress=True
+        project_id, local_dir, filter_glob, throw_on_error, show_progress=True
     )
 
     if ctx.obj["format_json"]:
@@ -313,16 +313,16 @@ def download_files(ctx, project_id, local_dir, filter_glob, exit_on_error):
 @click.argument("project_id")
 @click.argument("paths", nargs=-1, required=True)
 @click.option(
-    "--exit-on-error/--no-exit-on-error",
+    "--throw-on-error/--no-throw-on-error",
     help="If any project file delete operations fails stop, stop deleting the rest. Default: False",
 )
 @click.pass_context
-def delete_files(ctx, project_id, paths, exit_on_error):
+def delete_files(ctx, project_id, paths, throw_on_error):
     """Delete QFieldCloud project files."""
 
     log(f'Deleting project "{project_id}" files…')
 
-    paths_result = ctx.obj["client"].delete_files(project_id, paths, exit_on_error)
+    paths_result = ctx.obj["client"].delete_files(project_id, paths, throw_on_error)
 
     if ctx.obj["format_json"]:
         print_json(paths_result)
@@ -422,17 +422,17 @@ def package_latest(ctx, project_id):
     help="Do not download the whole packaged project, but only the files which match the glob.",
 )
 @click.option(
-    "--exit-on-error/--no-exit-on-error",
+    "--throw-on-error/--no-throw-on-error",
     help="If any packaged file downloads fails stop downloading the rest. Default: False",
 )
 @click.pass_context
-def package_download(ctx, project_id, local_dir, filter_glob, exit_on_error):
+def package_download(ctx, project_id, local_dir, filter_glob, throw_on_error):
     """Download packaged QFieldCloud project files."""
 
     log(f'Downloading the latest project "{project_id}" package files to {local_dir}…')
 
     files = ctx.obj["client"].package_download(
-        project_id, local_dir, filter_glob, exit_on_error, show_progress=True
+        project_id, local_dir, filter_glob, throw_on_error, show_progress=True
     )
 
     if ctx.obj["format_json"]:

src/qfieldcloud_sdk/sdk.py

@@ -176,7 +176,7 @@ def upload_files(
         upload_type: FileTransferType,
         project_path: str,
         filter_glob: str,
-        exit_on_error: bool = False,
+        throw_on_error: bool = False,
         show_progress: bool = False,
         job_id: str = "",
     ) -> List[Dict]:
@@ -206,7 +206,7 @@ def upload_files(
                 file["status"] = UploadStatus.FAILED
                 file["error"] = err
 
-                if exit_on_error:
+                if throw_on_error:
                     raise err
                 else:
                     continue
@@ -262,7 +262,7 @@ def download_project(
         project_id: str,
         local_dir: str,
         filter_glob: str = None,
-        exit_on_error: bool = False,
+        throw_on_error: bool = False,
         show_progress: bool = False,
     ) -> List[Dict]:
         """Download the specified project files into the destination dir.
@@ -281,7 +281,7 @@ def download_project(
             FileTransferType.PROJECT,
             local_dir,
             filter_glob,
-            exit_on_error,
+            throw_on_error,
             show_progress,
         )
 
@@ -327,9 +327,23 @@ def delete_files(
         self,
         project_id: str,
         glob_patterns: List[str],
-        continue_on_error: bool = False,
+        throw_on_error: bool = False,
         finished_cb: Callable = None,
     ) -> Dict[str, Dict[str, Any]]:
+        """Delete project files.
+
+        Args:
+            project_id (str): Project id
+            glob_patterns (List[str]): Delete only files matching one the glob patterns.
+            throw_on_error (bool, optional): Throw if delete error occurres. Defaults to False.
+            finished_cb (Callable, optional): Deprecated. Defaults to None.
+
+        Raises:
+            QFieldCloudException: if throw_on_error is True, throw an error if a download request fails.
+
+        Returns:
+            Dict[str, Dict[str, Any]]: Deleted files by glob pattern.
+        """
         project_files = self.list_files(project_id)
         glob_results = {}
         self._log(f"Project '{project_id}' has {len(project_files)} file(s).")
@@ -375,7 +389,7 @@ def delete_files(
                         f'File "{file["name"]}" failed to delete:\n{file["error"]}'
                     )
 
-                    if continue_on_error:
+                    if throw_on_error:
                         continue
                     else:
                         raise err
@@ -411,7 +425,7 @@ def package_download(
         project_id: str,
         local_dir: str,
         filter_glob: str = None,
-        exit_on_error: bool = False,
+        throw_on_error: bool = False,
         show_progress: bool = False,
     ) -> List[Dict]:
         """Download the specified project packaged files into the destination dir.
@@ -436,7 +450,7 @@ def package_download(
             FileTransferType.PACKAGE,
             local_dir,
             filter_glob,
-            exit_on_error,
+            throw_on_error,
             show_progress,
         )
 
@@ -447,9 +461,26 @@ def download_files(
         download_type: FileTransferType,
         local_dir: str,
         filter_glob: str = None,
-        exit_on_error: bool = False,
+        throw_on_error: bool = False,
         show_progress: bool = False,
     ) -> List[Dict]:
+        """Download project files.
+
+        Args:
+            files (List[Dict]): A list of file dicts, specifying which files to download.
+            project_id (str): Project id
+            download_type (FileTransferType): File transfer type which specifies what should be the download url.
+            local_dir (str): Local destination directory
+            filter_glob (str, optional): Download only files matching the glob pattern. If None download all. Defaults to None.
+            throw_on_error (bool, optional): Throw if download error occurres. Defaults to False.
+            show_progress (bool, optional): Show progress bar in the console. Defaults to False.
+
+        Raises:
+            QFieldCloudException: if throw_on_error is True, throw an error if a download request fails.
+
+        Returns:
+            List[Dict]: A list of file dicts.
+        """
         if not filter_glob:
             filter_glob = "*"
 
@@ -482,7 +513,7 @@ def download_files(
                 file["status"] = DownloadStatus.FAILED
                 file["error"] = err
 
-                if exit_on_error:
+                if throw_on_error:
                     raise err
                 else:
                     continue
@@ -497,6 +528,21 @@ def download_file(
         remote_filename: Path,
         show_progress: bool,
     ) -> requests.Response:
+        """Download a single project file.
+
+        Args:
+            project_id (str): Project id
+            download_type (FileTransferType): File transfer type which specifies what should be the download URL
+            local_filename (Path): Local filename
+            remote_filename (Path): Remote filename
+            show_progress (bool): Show progressbar in the console
+
+        Raises:
+            NotImplementedError: Raised if unknown `download_type` is passed
+
+        Returns:
+            requests.Response: the response object
+        """
         if download_type == FileTransferType.PROJECT:
             url = f"files/{project_id}/{remote_filename}"
         elif download_type == FileTransferType.PACKAGE:
@@ -532,18 +578,20 @@ def download_file(
 
         return resp
 
-    def get_files_list(
-        self, project_path: str, filter_glob: str
-    ) -> List[Dict[str, Any]]:
+    def get_files_list(self, root_path: str, filter_glob: str) -> List[Dict[str, Any]]:
+        """
+        Returns a list of dicts with information about local files. Usually used before uploading files.
+        NOTE: files and dirs starting with leading zero in the root directory will be ignored.
+        """
         if not filter_glob:
             filter_glob = "*"
 
         files: List[Dict[str, Any]] = []
-        for path in Path(project_path).rglob(filter_glob):
+        for path in Path(root_path).rglob(filter_glob):
             if not path.is_file():
                 continue
 
-            if str(path.relative_to(project_path)).startswith(".qfieldsync"):
+            if str(path.relative_to(root_path)).startswith("."):
                 continue
 
             files.append(