[SYNPY-1802] Add DownloadList functions

docs/reference/download_list.md

@@ -0,0 +1,42 @@
+[](){ #download-list-reference }
+# Download List
+
+The Synapse Download List (cart) lets you queue files for bulk download via the Synapse
+web UI or API. Files are downloaded individually rather than packaged into a zip because
+download lists can exceed 100 GB. Successfully downloaded files are removed from the cart
+automatically, so interrupted runs are safely resumable.
+
+## Example
+
+```python
+from synapseclient import Synapse
+from synapseclient.models import DownloadList
+
+syn = Synapse()
+syn.login()
+
+# Download all files in the cart to a local directory
+manifest_path = DownloadList().download_files(download_location="./downloads")
+```
+
+## API Reference
+
+::: synapseclient.models.DownloadList
+    options:
+        inherited_members: true
+        members:
+        - download_files
+        - get_manifest
+        - add_files
+        - remove_files
+        - clear
+
+---
+
+[](){ #download-list-item-reference }
+## DownloadListItem
+
+Identifies a specific file version in the download list. Used as input to
+`add_files` and `remove_files`.
+
+::: synapseclient.models.DownloadListItem

mkdocs.yml

@@ -70,6 +70,7 @@ nav:
       - Project: reference/project.md
       - Folder: reference/folder.md
       - File: reference/file.md
+      - Download List: reference/download_list.md
       - Annotations: reference/annotations.md
       - Tables: reference/tables.md
       - Table Schema: reference/table_schema.md

synapseclient/__main__.py

@@ -676,7 +676,12 @@ def submit(args, syn):
 
 def get_download_list(args, syn: synapseclient.Synapse) -> None:
     """Download files from the Synapse download cart"""
-    manifest_path = syn.get_download_list(downloadLocation=args.downloadLocation)
+    from synapseclient.models import DownloadList
+
+    manifest_path = DownloadList().download_files(
+        download_location=args.downloadLocation,
+        synapse_client=syn,
+    )
     syn.logger.info(f"Manifest file: {manifest_path}")
 
 

synapseclient/api/download_list_services.py

@@ -0,0 +1,93 @@
+"""This module is responsible for exposing the services defined at:
+<https://rest-docs.synapse.org/rest/#org.sagebionetworks.repo.web.controller.DownloadListController>
+"""
+
+import json
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from synapseclient import Synapse
+    from synapseclient.models.download_list import DownloadListItem
+
+
+async def clear_download_list_async(
+    *,
+    synapse_client: Optional["Synapse"] = None,
+) -> None:
+    """Clear all files from the user's Synapse download list.
+
+    [Endpoint](https://rest-docs.synapse.org/rest/DELETE/download/list.html)
+
+    Arguments:
+        synapse_client: If not passed in and caching was not disabled by
+            `Synapse.allow_client_caching(False)` this will use the last created
+            instance from the Synapse class constructor.
+    """
+    from synapseclient import Synapse
+
+    client = Synapse.get_client(synapse_client=synapse_client)
+    await client.rest_delete_async("/download/list")
+
+
+async def add_to_download_list_async(
+    files: list["DownloadListItem"],
+    *,
+    synapse_client: Optional["Synapse"] = None,
+) -> int:
+    """Add a batch of specific file versions to the user's Synapse download list.
+
+    [Endpoint](https://rest-docs.synapse.org/rest/POST/download/list/add.html)
+
+    Arguments:
+        files: List of DownloadListItem objects identifying the file versions to add.
+        synapse_client: If not passed in and caching was not disabled by
+            `Synapse.allow_client_caching(False)` this will use the last created
+            instance from the Synapse class constructor.
+
+    Returns:
+        The number of files added to the download list.
+    """
+    from synapseclient import Synapse
+
+    client = Synapse.get_client(synapse_client=synapse_client)
+    batch = [
+        {"fileEntityId": item.file_entity_id, "versionNumber": item.version_number}
+        for item in files
+    ]
+    request_body = {"batchToAdd": batch}
+    result = await client.rest_post_async(
+        "/download/list/add", body=json.dumps(request_body)
+    )
+    return result.get("numberOfFilesAdded", 0)
+
+
+async def remove_from_download_list_async(
+    files: list["DownloadListItem"],
+    *,
+    synapse_client: Optional["Synapse"] = None,
+) -> int:
+    """Remove a batch of specific file versions from the user's Synapse download list.
+
+    [Endpoint](https://rest-docs.synapse.org/rest/POST/download/list/remove.html)
+
+    Arguments:
+        files: List of DownloadListItem objects identifying the file versions to remove.
+        synapse_client: If not passed in and caching was not disabled by
+            `Synapse.allow_client_caching(False)` this will use the last created
+            instance from the Synapse class constructor.
+
+    Returns:
+        The number of files removed from the download list.
+    """
+    from synapseclient import Synapse
+
+    client = Synapse.get_client(synapse_client=synapse_client)
+    batch = [
+        {"fileEntityId": item.file_entity_id, "versionNumber": item.version_number}
+        for item in files
+    ]
+    request_body = {"batchToRemove": batch}
+    result = await client.rest_post_async(
+        "/download/list/remove", body=json.dumps(request_body)
+    )
+    return result.get("numberOfFilesRemoved", 0)

synapseclient/client.py

@@ -3146,15 +3146,68 @@ async def upload_file():
     ############################################################
     #                  Download List                           #
     ############################################################
-    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1439
+    @deprecated(
+        version="4.13.0",
+        reason=(
+            "Use `DownloadList().clear()` instead. "
+            "See synapseclient.models.DownloadList for the new OOP interface."
+        ),
+    )
     def clear_download_list(self):
-        """Clear all files from download list"""
+        """Clear all files from download list
+
+        Example: Migration to new method
+             
+
+            ```python
+            # Old approach (DEPRECATED)
+            # syn.clear_download_list()
+
+            # New approach (RECOMMENDED)
+            from synapseclient import Synapse
+            from synapseclient.models import DownloadList
+
+            syn = Synapse()
+            syn.login()
+
+            # Clear all files from the download list
+            DownloadList().clear()
+            ```
+        """
         self.restDELETE("/download/list")
 
-    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1439
+    @deprecated(
+        version="4.13.0",
+        reason=(
+            "Use `DownloadList().remove_files(files)` instead. "
+            "See synapseclient.models.DownloadList for the new OOP interface."
+        ),
+    )
     def remove_from_download_list(self, list_of_files: typing.List[typing.Dict]) -> int:
         """Remove a batch of files from download list
 
+        Example: Migration to new method
+             
+
+            ```python
+            # Old approach (DEPRECATED)
+            # syn.remove_from_download_list([
+            #     {"fileEntityId": "syn123", "versionNumber": 1},
+            # ])
+
+            # New approach (RECOMMENDED)
+            from synapseclient import Synapse
+            from synapseclient.models import DownloadList, DownloadListItem
+
+            syn = Synapse()
+            syn.login()
+
+            # Remove specific file versions from the download list
+            DownloadList().remove_files([
+                DownloadListItem(file_entity_id="syn123", version_number=1),
+            ])
+            ```
+
         Arguments:
             list_of_files: Array of files in the format of a mapping {fileEntityId: synid, versionNumber: version}
 
@@ -3167,7 +3220,13 @@ def remove_from_download_list(self, list_of_files: typing.List[typing.Dict]) ->
         )
         return num_files_removed
 
-    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1439
+    @deprecated(
+        version="4.13.0",
+        reason=(
+            "Use `DownloadList().get_manifest()` instead. "
+            "See synapseclient.models.DownloadList for the new OOP interface."
+        ),
+    )
     def _generate_manifest_from_download_list(
         self,
         quoteCharacter: str = '"',
@@ -3176,8 +3235,25 @@ def _generate_manifest_from_download_list(
         separator: str = ",",
         header: bool = True,
     ):
-        """
-        Creates a download list manifest generation request
+        """Creates a download list manifest generation request
+
+        Example: Migration to new method
+             
+
+            ```python
+            # Old approach (DEPRECATED)
+            # manifest_handle = syn._generate_manifest_from_download_list()
+
+            # New approach (RECOMMENDED)
+            from synapseclient import Synapse
+            from synapseclient.models import DownloadList
+
+            syn = Synapse()
+            syn.login()
+
+            # Generate and download the manifest CSV
+            manifest_path = DownloadList().get_manifest()
+            ```
 
         Arguments:
             quoteCharacter:  The character to be used for quoted elements in the resulting file.
@@ -3203,10 +3279,34 @@ def _generate_manifest_from_download_list(
             uri="/download/list/manifest/async", request=request_body
         )
 
-    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1439
+    @deprecated(
+        version="4.13.0",
+        reason=(
+            "Use `DownloadList().get_manifest()` instead. "
+            "See synapseclient.models.DownloadList for the new OOP interface."
+        ),
+    )
     def get_download_list_manifest(self):
         """Get the path of the download list manifest file
 
+        Example: Migration to new method
+             
+
+            ```python
+            # Old approach (DEPRECATED)
+            # manifest_path = syn.get_download_list_manifest()
+
+            # New approach (RECOMMENDED)
+            from synapseclient import Synapse
+            from synapseclient.models import DownloadList
+
+            syn = Synapse()
+            syn.login()
+
+            # Generate and download the manifest CSV
+            manifest_path = DownloadList().get_manifest()
+            ```
+
         Returns:
             Path of download list manifest file
         """
@@ -3230,10 +3330,34 @@ def get_download_list_manifest(self):
         )
         return downloaded_path
 
-    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1439
+    @deprecated(
+        version="4.13.0",
+        reason=(
+            "Use `DownloadList().download_files(download_location=...)` instead. "
+            "See synapseclient.models.DownloadList for the new OOP interface."
+        ),
+    )
     def get_download_list(self, downloadLocation: str = None) -> str:
         """Download all files from your Synapse download list
 
+        Example: Migration to new method
+             
+
+            ```python
+            # Old approach (DEPRECATED)
+            # manifest_path = syn.get_download_list(downloadLocation="./downloads")
+
+            # New approach (RECOMMENDED)
+            from synapseclient import Synapse
+            from synapseclient.models import DownloadList
+
+            syn = Synapse()
+            syn.login()
+
+            # Download all files in the cart and get the result manifest path
+            manifest_path = DownloadList().download_files(download_location="./downloads")
+            ```
+
         Arguments:
             downloadLocation: Directory to download files to.
 

synapseclient/core/constants/concrete_types.py

@@ -117,6 +117,11 @@
     "org.sagebionetworks.repo.model.curation.metadata.RecordBasedMetadataTaskProperties"
 )
 
+# Download List
+DOWNLOAD_LIST_MANIFEST_REQUEST = (
+    "org.sagebionetworks.repo.model.download.DownloadListManifestRequest"
+)
+
 # Grid Session Types
 CREATE_GRID_REQUEST = "org.sagebionetworks.repo.model.grid.CreateGridRequest"
 GRID_RECORD_SET_EXPORT_REQUEST = (