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

from synapseclient import Synapse
from synapseclient.operations import download_list_files

syn = Synapse()
syn.login()

# Download all files in the cart to a local directory
manifest_path = download_list_files(download_location="./downloads")

API Reference

synapseclient.operations.download_list_files

download_list_files(download_location: Optional[str] = None, *, parallel: bool = False, max_concurrent: int = 10, synapse_client: Optional[Synapse] = None) -> str

Download all files in the Synapse download list (cart) to a local directory.

Files are downloaded individually. The cart is not packaged into a zip because download lists can exceed 100 GB. Only successfully downloaded files are removed from the cart after the full pass completes, so interrupted runs are safely resumable.

Files that cannot be accessed or fail to download are left in the cart and recorded with an error value in the result manifest.

PARAMETER	DESCRIPTION
download_location	Directory to download files to. Defaults to the current working directory. TYPE: Optional[str] DEFAULT: None
parallel	If True, files are downloaded concurrently up to max_concurrent at a time using asyncio.gather. If False (default), files are downloaded sequentially. TYPE: bool DEFAULT: False
max_concurrent	Maximum number of files to download concurrently when parallel=True. Defaults to 10. Has no effect when parallel=False. TYPE: int DEFAULT: 10
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. TYPE: Optional[Synapse] DEFAULT: None

RETURNS	DESCRIPTION
str	Path to the result manifest CSV, which contains all original manifest
str	columns plus path (local file path) and error (error message or
str	empty string) columns.

RAISES	DESCRIPTION
SynapseHTTPError	If the manifest async job fails or the cart is empty ("No files available for download").
SynapseError	If the manifest job completes but produces no local file, or if the downloaded CSV has no headers or contains reserved column names ("path" or "error").

Download all files in the cart

  Download all files in the user's download list to a local directory.

from synapseclient import Synapse
from synapseclient.operations import download_list_files

syn = Synapse()
syn.login()

manifest_path = download_list_files(download_location="./data")

Source code in synapseclient/operations/download_list_operations.py

def download_list_files(
    download_location: Optional[str] = None,
    *,
    parallel: bool = False,
    max_concurrent: int = 10,
    synapse_client: Optional["Synapse"] = None,
) -> str:
    """Download all files in the Synapse download list (cart) to a local directory.

    Files are downloaded individually. The cart is not packaged into a zip because
    download lists can exceed 100 GB. Only successfully downloaded files are removed
    from the cart after the full pass completes, so interrupted runs are safely
    resumable.

    Files that cannot be accessed or fail to download are left in the cart and
    recorded with an error value in the result manifest.

    Arguments:
        download_location: Directory to download files to. Defaults to the
            current working directory.
        parallel: If True, files are downloaded concurrently up to
            max_concurrent at a time using asyncio.gather. If False
            (default), files are downloaded sequentially.
        max_concurrent: Maximum number of files to download concurrently when
            parallel=True. Defaults to 10. Has no effect when
            parallel=False.
        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:
        Path to the result manifest CSV, which contains all original manifest
        columns plus path (local file path) and error (error message or
        empty string) columns.

    Raises:
        SynapseHTTPError: If the manifest async job fails or the cart is empty
            ("No files available for download").
        SynapseError: If the manifest job completes but produces no local file,
            or if the downloaded CSV has no headers or contains reserved column
            names ("path" or "error").

    Example: Download all files in the cart
         
        Download all files in the user's download list to a local directory.
        ```python
        from synapseclient import Synapse
        from synapseclient.operations import download_list_files

        syn = Synapse()
        syn.login()

        manifest_path = download_list_files(download_location="./data")
        ```
    """
    return wrap_async_to_sync(
        coroutine=download_list_files_async(
            download_location=download_location,
            parallel=parallel,
            max_concurrent=max_concurrent,
            synapse_client=synapse_client,
        )
    )

synapseclient.operations.download_list_manifest

download_list_manifest(*, csv_table_descriptor: Optional[CsvTableDescriptor] = None, destination: str = '.', synapse_client: Optional[Synapse] = None) -> str

Generate and download the manifest CSV for the current cart contents.

Submits an async job to Synapse to generate the manifest, then downloads the resulting CSV. The manifest contains the same columns as the zip manifest downloaded from the Synapse web UI.

PARAMETER	DESCRIPTION
csv_table_descriptor	Optional CsvTableDescriptor controlling the format of the generated CSV (separator, quote character, escape character, line ending, and whether the first line is a header). When omitted the Synapse defaults are used. TYPE: Optional[CsvTableDescriptor] DEFAULT: None
destination	Directory to download the manifest CSV to. Defaults to the current working directory. TYPE: str DEFAULT: '.'
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. TYPE: Optional[Synapse] DEFAULT: None

RAISES	DESCRIPTION
SynapseError	If the async job completes without producing a manifest.

RETURNS	DESCRIPTION
str	Path to the downloaded manifest CSV.

Get the download list manifest

  Inspect the cart contents before downloading.

from synapseclient import Synapse
from synapseclient.operations import download_list_manifest

syn = Synapse()
syn.login()

manifest_path = download_list_manifest()

Source code in synapseclient/operations/download_list_operations.py

def download_list_manifest(
    *,
    csv_table_descriptor: Optional[CsvTableDescriptor] = None,
    destination: str = ".",
    synapse_client: Optional["Synapse"] = None,
) -> str:
    """Generate and download the manifest CSV for the current cart contents.

    Submits an async job to Synapse to generate the manifest, then downloads
    the resulting CSV. The manifest contains the same columns as the zip
    manifest downloaded from the Synapse web UI.

    Arguments:
        csv_table_descriptor: Optional CsvTableDescriptor controlling the
            format of the generated CSV (separator, quote character, escape
            character, line ending, and whether the first line is a header).
            When omitted the Synapse defaults are used.
        destination: Directory to download the manifest CSV to. Defaults to
            the current working directory.
        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.

    Raises:
        SynapseError: If the async job completes without producing a manifest.

    Returns:
        Path to the downloaded manifest CSV.

    Example: Get the download list manifest
         
        Inspect the cart contents before downloading.
        ```python
        from synapseclient import Synapse
        from synapseclient.operations import download_list_manifest

        syn = Synapse()
        syn.login()

        manifest_path = download_list_manifest()
        ```
    """
    return wrap_async_to_sync(
        coroutine=download_list_manifest_async(
            csv_table_descriptor=csv_table_descriptor,
            destination=destination,
            synapse_client=synapse_client,
        )
    )

synapseclient.operations.download_list_add

download_list_add(files: list[DownloadListItem], *, synapse_client: Optional[Synapse] = None) -> int

Add files to the Synapse download list.

If a file is added with no version specified, the latest version will be downloaded.

PARAMETER	DESCRIPTION
files	List of DownloadListItem objects identifying the file versions to add. TYPE: list[DownloadListItem]
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. TYPE: Optional[Synapse] DEFAULT: None

RETURNS	DESCRIPTION
int	The number of files added.

Add files to the download list

  Add specific file versions to the cart.

from synapseclient import Synapse
from synapseclient.operations import download_list_add, DownloadListItem

syn = Synapse()
syn.login()

count = download_list_add([
    DownloadListItem(file_entity_id="syn123", version_number=1),
    DownloadListItem(file_entity_id="syn456", version_number=2),
])

Source code in synapseclient/operations/download_list_operations.py

def download_list_add(
    files: list[DownloadListItem],
    *,
    synapse_client: Optional["Synapse"] = None,
) -> int:
    """Add files to the Synapse download list.

    If a file is added with no version specified, the latest version will be downloaded.

    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.

    Example: Add files to the download list
         
        Add specific file versions to the cart.
        ```python
        from synapseclient import Synapse
        from synapseclient.operations import download_list_add, DownloadListItem

        syn = Synapse()
        syn.login()

        count = download_list_add([
            DownloadListItem(file_entity_id="syn123", version_number=1),
            DownloadListItem(file_entity_id="syn456", version_number=2),
        ])
        ```
    """
    return wrap_async_to_sync(
        coroutine=download_list_add_async(files=files, synapse_client=synapse_client)
    )

synapseclient.operations.download_list_remove

download_list_remove(files: list[DownloadListItem], *, synapse_client: Optional[Synapse] = None) -> int

Remove files from the Synapse download list.

If a file was added with a version specified, then that version must be specified to remove it. If a file was added with no version specified, then no version must be specified to remove it.

PARAMETER	DESCRIPTION
files	List of DownloadListItem objects identifying the file versions to remove. TYPE: list[DownloadListItem]
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. TYPE: Optional[Synapse] DEFAULT: None

RETURNS	DESCRIPTION
int	The number of files removed.

Remove files from the download list

  Remove specific file versions from the cart.

from synapseclient import Synapse
from synapseclient.operations import download_list_remove, DownloadListItem

syn = Synapse()
syn.login()

count = download_list_remove([
    DownloadListItem(file_entity_id="syn123", version_number=1),
])

Source code in synapseclient/operations/download_list_operations.py

def download_list_remove(
    files: list[DownloadListItem],
    *,
    synapse_client: Optional["Synapse"] = None,
) -> int:
    """Remove files from the Synapse download list.

    If a file was added with a version specified, then that version must be specified to remove it.
    If a file was added with no version specified, then no version must be specified to remove it.

    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.

    Example: Remove files from the download list
         
        Remove specific file versions from the cart.
        ```python
        from synapseclient import Synapse
        from synapseclient.operations import download_list_remove, DownloadListItem

        syn = Synapse()
        syn.login()

        count = download_list_remove([
            DownloadListItem(file_entity_id="syn123", version_number=1),
        ])
        ```
    """
    return wrap_async_to_sync(
        coroutine=download_list_remove_async(files=files, synapse_client=synapse_client)
    )

synapseclient.operations.download_list_clear

download_list_clear(*, synapse_client: Optional[Synapse] = None) -> None

Clear all files from the Synapse download list (cart).

PARAMETER	DESCRIPTION
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. TYPE: Optional[Synapse] DEFAULT: None

Clear the download list

  Remove all files from the cart.

from synapseclient import Synapse
from synapseclient.operations import download_list_clear

syn = Synapse()
syn.login()

download_list_clear()

Source code in synapseclient/operations/download_list_operations.py

def download_list_clear(
    *,
    synapse_client: Optional["Synapse"] = None,
) -> None:
    """Clear all files from the Synapse download list (cart).

    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.

    Example: Clear the download list
         
        Remove all files from the cart.
        ```python
        from synapseclient import Synapse
        from synapseclient.operations import download_list_clear

        syn = Synapse()
        syn.login()

        download_list_clear()
        ```
    """
    return wrap_async_to_sync(
        coroutine=download_list_clear_async(synapse_client=synapse_client)
    )

---

DownloadListItem

Identifies a specific file version in the download list. Used as input to download_list_add and download_list_remove.

synapseclient.operations.DownloadListItem dataclass

A single item for a user's download list.

https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/download/DownloadListItem.html

ATTRIBUTE	DESCRIPTION
file_entity_id	Synapse ID of the file entity (e.g. "syn123"). TYPE: str
version_number	Version of the file to target. TYPE: Optional[int]

Source code in synapseclient/operations/download_list_operations.py

@dataclass
class DownloadListItem:
    """A single item for a user's download list.

    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/download/DownloadListItem.html>

    Attributes:
        file_entity_id: Synapse ID of the file entity (e.g. "syn123").
        version_number: Version of the file to target.
    """

    file_entity_id: str
    """Synapse ID of the file entity (e.g. "syn123")."""

    version_number: Optional[int] = None
    """Version of the file to target."""

Attributes

file_entity_id instance-attribute

file_entity_id: str

Synapse ID of the file entity (e.g. "syn123").

version_number class-attribute instance-attribute

version_number: Optional[int] = None

Version of the file to target.