Separate download single file to dedicated API call

Author: varmar05

mergin/cli.py

@@ -29,6 +29,7 @@
     download_project_cancel,
     download_file_async,
     download_file_finalize,
+    download_project_file_async,
     download_project_finalize,
     download_project_is_running,
 )
@@ -348,19 +349,20 @@ def download_file(ctx, filepath, output, version, project):
     mc = ctx.obj["client"]
     if mc is None:
         return
-    if project is None:
-        # no --project given, so we default to the current directory - make sure that's actually a checked out project
-        try:
-            MerginProject(os.getcwd()).project_full_name()
-        except InvalidProject:
-            click.secho(
-                "Current directory is not a Mergin Maps project. Run this command from within a "
-                "checked out project directory, or pass --project <workspace>/<project>.",
-                fg="red",
-            )
-            return
     try:
-        job = download_file_async(mc, project or os.getcwd(), filepath, output, version)
+        if project is not None:
+            job = download_project_file_async(mc, project, filepath, output, version)
+        else:
+            try:
+                MerginProject(os.getcwd()).project_full_name()
+            except InvalidProject:
+                click.secho(
+                    "Current directory is not a Mergin Maps project. Run this command from within a "
+                    "checked out project directory, or pass --project <workspace>/<project>.",
+                    fg="red",
+                )
+                return
+            job = download_file_async(mc, os.getcwd(), filepath, output, version)
         with click.progressbar(length=job.total_size) as bar:
             last_transferred_size = 0
             while download_project_is_running(job):

mergin/client.py

@@ -46,6 +46,7 @@
     download_file_async,
     download_files_async,
     download_files_finalize,
+    download_project_file_async,
     download_diffs_async,
     download_project_finalize,
     download_project_wait,
@@ -1199,7 +1200,7 @@ def download_file(self, project_dir, file_path, output_filename, version=None):
         """
         Download project file at specified version. Get the latest if no version specified.
 
-        :param project_dir: project local directory or a full project name ("<workspace>/<project>")
+        :param project_dir: project local directory
         :type project_dir: String
         :param file_path: relative path of file to download in the project directory
         :type file_path: String
@@ -1212,6 +1213,24 @@ def download_file(self, project_dir, file_path, output_filename, version=None):
         pull_project_wait(job)
         download_file_finalize(job)
 
+    def download_project_file(self, project_path, file_path, output_filename, version=None):
+        """
+        Download a single project file at specified version directly from the server, without
+        needing an existing local project checkout.
+
+        :param project_path: full project name ("<workspace>/<project>")
+        :type project_path: String
+        :param file_path: relative path of file to download in the project directory
+        :type file_path: String
+        :param output_filename: full destination path for saving the downloaded file
+        :type output_filename: String
+        :param version: optional version tag for downloaded file
+        :type version: String
+        """
+        job = download_project_file_async(self, project_path, file_path, output_filename, version=version)
+        pull_project_wait(job)
+        download_file_finalize(job)
+
     def get_file_diff(self, project_dir, file_path, output_diff, version_from, version_to):
         """Create concatenated diff for project file diffs between versions version_from and version_to.
 
@@ -1401,11 +1420,11 @@ def download_files(
         """
         Download project files at specified version. Get the latest if no version specified.
 
-        :param project_dir: project local directory or a full project name ("<workspace>/<project>")
+        :param project_dir: project local directory
         :type project_dir: String
         :param file_path: List of relative paths of files to download in the project directory
         :type file_path: List[String]
-        :param output_paths: List of paths for files to download to. Should be same length of as file_path. Default is `None` which means that files are downloaded into MerginProject at project_dir (only valid when project_dir is an existing local checkout).
+        :param output_paths: List of paths for files to download to. Should be same length of as file_path. Default is `None` which means that files are downloaded into MerginProject at project_dir.
         :type output_paths: List[String]
         :param version: optional version tag for downloaded file
         :type version: String

mergin/client_pull.py

@@ -22,7 +22,7 @@
 import concurrent.futures
 
 
-from .common import CHUNK_SIZE, ClientError, DeltaChangeType, InvalidProject, PullActionType
+from .common import CHUNK_SIZE, ClientError, DeltaChangeType, PullActionType
 from .models import ProjectDelta, ProjectDeltaChange, PullAction
 from .merginproject import MerginProject
 from .utils import cleanup_tmp_dir, is_versioned_file, save_to_file
@@ -82,8 +82,8 @@ def dump(self):
 
 class DownloadScratchContext:
     """
-    Minimal stand-in for MerginProject, used by download_files_async() when downloading files
-    directly by project name ("<workspace>/<project>") without an existing local project checkout.
+    Minimal stand-in for MerginProject used when downloading a file directly by
+    project name ("<workspace>/<project>") without an existing local project checkout.
 
     Provides only what the shared download job code actually needs from MerginProject.
     """
@@ -793,6 +793,23 @@ def download_file_finalize(job):
     download_files_finalize(job)
 
 
+def download_project_file_async(mc, project_path: str, file_path: str, output_file: str, version: str = None):
+    """
+    Starts background download of a single project file at specified version, fetched directly
+    from the server without needing an existing local project checkout.
+    Returns handle to the pending download.
+
+    :param project_path: full project name ("<workspace>/<project>")
+    :param output_file: destination path for the downloaded file
+    """
+    if not output_file:
+        raise ClientError("output_file must be provided when downloading a file without a local project checkout")
+
+    tmp_dir = tempfile.TemporaryDirectory(prefix="python-api-client-")
+    mp = DownloadScratchContext(mc, tmp_dir.name)
+    return _download_files_async(mc, mp, project_path, [file_path], [output_file], version, tmp_dir)
+
+
 def download_diffs_async(mc, project_directory, file_path, versions):
     """
     Starts background download project file diffs for specified versions.
@@ -916,35 +933,29 @@ def download_diffs_finalize(job: PullJob) -> List[str]:
 
 
 def download_files_async(
-    mc, project_dir: str, file_paths: typing.List[str], output_paths: typing.List[str], version: str
+    mc, project_dir: str, file_paths: typing.List[str], output_paths: typing.List[str] = None, version: str = None
 ):
     """
     Starts background download project files at specified version.
     Returns handle to the pending download.
 
-    `project_dir` can either be an existing local project directory (previously fetched with
-    download_project()), or a full project name ("<workspace>/<project>") to download files
-    directly from the server without needing a local checkout. In the latter case, `output_paths`
-    must be provided explicitly, as there is no project directory to place files into by default.
+    `project_dir` must be an existing local project directory.
     """
-    # temporary directory to stage downloaded chunks in
+    mp = MerginProject(project_dir)
+    project_path = mp.project_full_name()
     tmp_dir = tempfile.TemporaryDirectory(prefix="python-api-client-")
+    return _download_files_async(mc, mp, project_path, file_paths, output_paths, version, tmp_dir)
 
-    mp: Union[MerginProject, "DownloadScratchContext"]
-    try:
-        mp = MerginProject(project_dir)
-        project_path = mp.project_full_name()
-    except InvalidProject:
-        # project_dir is not an existing local checkout - treat it as a full project name
-        # ("<workspace>/<project>") and download straight from the server instead
-        if output_paths is None:
-            cleanup_tmp_dir(mc, tmp_dir)
-            raise ClientError(
-                "output_paths must be provided when downloading files without an existing local project checkout"
-            )
-        project_path = project_dir
-        mp = DownloadScratchContext(mc, tmp_dir.name)
 
+def _download_files_async(
+    mc,
+    mp: Union[MerginProject, "DownloadScratchContext"],
+    project_path: str,
+    file_paths: typing.List[str],
+    output_paths: typing.List[str],
+    version: str,
+    tmp_dir: tempfile.TemporaryDirectory,
+):
     ver_info = f"at version {version}" if version is not None else "at latest version"
     mp.log.info(f"Getting [{', '.join(file_paths)}] {ver_info}")
     latest_proj_info = mc.project_info(project_path)

mergin/test/test_client.py

@@ -1371,23 +1371,23 @@ def test_download_file_without_checkout(mc):
     f_downloaded = os.path.join(download_dir, f_updated)
 
     expected_content = "inserted_1_A.gpkg"
-    mc.download_file(project, f_updated, f_downloaded, version="v2")
+    mc.download_project_file(project, f_updated, f_downloaded, version="v2")
     expected = os.path.join(TEST_DATA_DIR, expected_content)
     assert check_gpkg_same_content(MerginProject(project_dir), f_downloaded, expected)
     assert not os.path.exists(os.path.join(download_dir, ".mergin"))
 
-    # output_paths must be provided explicitly when there is no local checkout
-    with pytest.raises(ClientError, match="output_paths must be provided"):
-        mc.download_files(project, [f_updated])
+    # output_file must be provided explicitly when there is no local checkout
+    with pytest.raises(ClientError, match="output_file must be provided"):
+        mc.download_project_file(project, f_updated, None)
 
     # non-existent file in an existing project - same error as with a local checkout
     with pytest.raises(ClientError, match=r"No \[does_not_exist\.gpkg\] exists at version v2"):
-        mc.download_file(project, "does_not_exist.gpkg", f_downloaded, version="v2")
+        mc.download_project_file(project, "does_not_exist.gpkg", f_downloaded, version="v2")
 
     # non-existent / inaccessible project should fail clearly too
     nonexistent_project = create_project_path("this_project_does_not_exist", mc)
     with pytest.raises(ClientError):
-        mc.download_file(nonexistent_project, f_updated, f_downloaded)
+        mc.download_project_file(nonexistent_project, f_updated, f_downloaded)
 
 
 def test_download_diffs(mc):