Synapse Factory Operations¶

Contained within this file are experimental interfaces for working with the Synapse Python Client. Unless otherwise noted these interfaces are subject to change at any time. Use at your own risk.

API Reference¶

synapseclient.operations.get_async `async` ¶

get_async(synapse_id: Optional[str] = None, *, entity_name: Optional[str] = None, parent_id: Optional[str] = None, version_number: Optional[int] = None, activity_options: Optional[ActivityOptions] = None, file_options: Optional[FileOptions] = None, table_options: Optional[TableOptions] = None, link_options: Optional[LinkOptions] = None, synapse_client: Optional[Synapse] = None) -> Union[Dataset, DatasetCollection, EntityView, File, Folder, Link, MaterializedView, Project, SubmissionView, Table, VirtualTable]

Factory method to retrieve any Synapse entity by its ID or by name and parent ID.

This method serves as a unified interface for retrieving any type of Synapse entity without needing to know the specific entity type beforehand. It automatically determines the entity type and returns the appropriate model instance.

You can retrieve entities in two ways:

By providing a synapse_id directly
By providing entity_name and optionally parent_id for lookup

PARAMETER	DESCRIPTION
`synapse_id`	The Synapse ID of the entity to retrieve (e.g., 'syn123456'). Mutually exclusive with entity_name. TYPE: `Optional[str]` DEFAULT: `None`
`entity_name`	The name of the entity to find. Must be used with this approach instead of synapse_id. When looking up projects, parent_id should be None. TYPE: `Optional[str]` DEFAULT: `None`
`parent_id`	The parent entity ID when looking up by name. Set to None when looking up projects by name. Only used with entity_name. TYPE: `Optional[str]` DEFAULT: `None`
`version_number`	The specific version number of the entity to retrieve. Only applies to versionable entities (File, Table, Dataset). If not specified, the most recent version will be retrieved. Ignored for other entity types. TYPE: `Optional[int]` DEFAULT: `None`
`file_options`	File-specific configuration options. Only applies to File entities. Ignored for other entity types. TYPE: `Optional[FileOptions]` DEFAULT: `None`
`link_options`	Link-specific configuration options. Only applies when the entity is a Link. Ignored for other entity types. TYPE: `Optional[LinkOptions]` DEFAULT: `None`
`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
`Union[Dataset, DatasetCollection, EntityView, File, Folder, Link, MaterializedView, Project, SubmissionView, Table, VirtualTable]`	The appropriate Synapse entity model instance based on the entity type.

RAISES	DESCRIPTION
`ValueError`	If both synapse_id and entity_name are provided, or if neither is provided.
`ValueError`	If entity_name is provided without this being a valid lookup scenario.
`ValueError`	If the synapse_id is not a valid Synapse ID format.

Note

When using entity_name lookup:

For projects: leave parent_id=None
For all other entities: provide the parent_id of the containing folder/project

Retrieving entities by ID

Get any entity by Synapse ID:

import asyncio
from synapseclient import Synapse
from synapseclient.models import File, Project
from synapseclient.operations import get_async

async def main():
    syn = Synapse()
    syn.login()

    # Works for any entity type
    entity = await get_async(synapse_id="syn123456")

    # The returned object will be the appropriate type
    if isinstance(entity, File):
        print(f"File: {entity.name}")
    elif isinstance(entity, Project):
        print(f"Project: {entity.name}")

asyncio.run(main())

Retrieving entities by name

Get an entity by name and parent:

import asyncio
from synapseclient import Synapse
from synapseclient.operations import get_async

async def main():
    syn = Synapse()
    syn.login()

    # Get a file by name within a folder
    entity = await get_async(
        entity_name="my_file.txt",
        parent_id="syn123456"
    )

    # Get a project by name (parent_id=None)
    project = await get_async(
        entity_name="My Project",
        parent_id=None
    )

asyncio.run(main())

Retrieving a specific version

Get a specific version of a versionable entity:

import asyncio
from synapseclient import Synapse
from synapseclient.operations import get_async

async def main():
    syn = Synapse()
    syn.login()

    entity = await get_async(synapse_id="syn123456", version_number=2)

asyncio.run(main())

Retrieving a file with custom options

Get file metadata with specific download options:

import asyncio
from synapseclient import Synapse
from synapseclient.operations import get_async, FileOptions, ActivityOptions

async def main():
    syn = Synapse()
    syn.login()

    file_entity = await get_async(
        synapse_id="syn123456",
        activity_options=ActivityOptions(include_activity=True),
        file_options=FileOptions(
            download_file=False
        )
    )

asyncio.run(main())

Retrieving a table with activity and columns

Get table with activity and column information:

import asyncio
from synapseclient import Synapse
from synapseclient.operations import get_async, ActivityOptions, TableOptions

async def main():
    syn = Synapse()
    syn.login()

    table_entity = await get_async(
        synapse_id="syn123456",
        activity_options=ActivityOptions(include_activity=True),
        table_options=TableOptions(include_columns=True)
    )

asyncio.run(main())

Following links

Get the target of a link entity:

import asyncio
from synapseclient import Synapse
from synapseclient.operations import get_async, LinkOptions

async def main():
    syn = Synapse()
    syn.login()

    target_entity = await get_async(
        synapse_id="syn123456",
        link_options=LinkOptions(follow_link=True)
    )

asyncio.run(main())

Working with Link entities

Get a Link entity without following it:

import asyncio
from synapseclient import Synapse
from synapseclient.operations import get_async, LinkOptions

async def main():
    syn = Synapse()
    syn.login()

    # Get the link entity itself
    link_entity = await get_async(
        synapse_id="syn123456",  # Example link ID
        link_options=LinkOptions(follow_link=False)
    )
    print(f"Link: {link_entity.name} -> {link_entity.target_id}")

    # Then follow the link to get the target
    target_entity = await get_async(
        synapse_id="syn123456",
        link_options=LinkOptions(follow_link=True)
    )
    print(f"Target: {target_entity.name} (type: {type(target_entity).__name__})")

asyncio.run(main())

Comprehensive File options

Download file with custom location and collision handling:

import asyncio
from synapseclient import Synapse
from synapseclient.operations import get_async, FileOptions

async def main():
    syn = Synapse()
    syn.login()

    file_entity = await get_async(
        synapse_id="syn123456",
        file_options=FileOptions(
            download_file=True,
            download_location="/path/to/download/",
            if_collision="overwrite.local"
        )
    )
    print(f"Downloaded file: {file_entity.name} to {file_entity.path}")

asyncio.run(main())

Table options for table-like entities

Get table entities with column information:

import asyncio
from synapseclient import Synapse
from synapseclient.operations import get_async, TableOptions

async def main():
    syn = Synapse()
    syn.login()

    # Works for Table, Dataset, EntityView, MaterializedView,
    # SubmissionView, VirtualTable, and DatasetCollection
    table_entity = await get_async(
        synapse_id="syn123456",  # Example table ID
        table_options=TableOptions(include_columns=True)
    )
    print(f"Table: {table_entity.name} with {len(table_entity.columns)} columns")

asyncio.run(main())

Combining multiple options

Get a File with both activity and custom download options:

import asyncio
from synapseclient import Synapse
from synapseclient.operations import get_async, FileOptions, ActivityOptions

async def main():
    syn = Synapse()
    syn.login()

    file_entity = await get_async(
        synapse_id="syn123456",
        activity_options=ActivityOptions(include_activity=True),
        file_options=FileOptions(
            download_file=False
        )
    )
    print(f"File: {file_entity.name} (activity included: {file_entity.activity is not None})")

asyncio.run(main())

Working with entity instances

Pass an existing entity instance to refresh or apply new options:

import asyncio
from synapseclient import Synapse
from synapseclient.operations import get_async, FileOptions

async def main():
    syn = Synapse()
    syn.login()

    # Get an entity first
    entity = await get_async(synapse_id="syn123456")
    print(f"Original entity: {entity.name}")

    # Then use the entity instance to get it again with different options
    refreshed_entity = await get_async(
        entity,
        file_options=FileOptions(download_file=False)
    )
    print(f"Refreshed entity: {refreshed_entity.name} (download_file: {refreshed_entity.download_file})")

asyncio.run(main())

Source code in synapseclient/operations/factory_operations.py

async def get_async(
    synapse_id: Optional[str] = None,
    *,
    entity_name: Optional[str] = None,
    parent_id: Optional[str] = None,
    version_number: Optional[int] = None,
    activity_options: Optional[ActivityOptions] = None,
    file_options: Optional[FileOptions] = None,
    table_options: Optional[TableOptions] = None,
    link_options: Optional[LinkOptions] = None,
    synapse_client: Optional["Synapse"] = None,
) -> Union[
    "Dataset",
    "DatasetCollection",
    "EntityView",
    "File",
    "Folder",
    "Link",
    "MaterializedView",
    "Project",
    "SubmissionView",
    "Table",
    "VirtualTable",
]:
    """
    Factory method to retrieve any Synapse entity by its ID or by name and parent ID.

    This method serves as a unified interface for retrieving any type of Synapse entity
    without needing to know the specific entity type beforehand. It automatically
    determines the entity type and returns the appropriate model instance.

    You can retrieve entities in two ways:

    1. By providing a synapse_id directly
    2. By providing entity_name and optionally parent_id for lookup

    Arguments:
        synapse_id: The Synapse ID of the entity to retrieve (e.g., 'syn123456').
            Mutually exclusive with entity_name.
        entity_name: The name of the entity to find. Must be used with this approach
            instead of synapse_id. When looking up projects, parent_id should be None.
        parent_id: The parent entity ID when looking up by name. Set to None when
            looking up projects by name. Only used with entity_name.
        version_number: The specific version number of the entity to retrieve. Only
            applies to versionable entities (File, Table, Dataset). If not specified,
            the most recent version will be retrieved. Ignored for other entity types.
        file_options: File-specific configuration options. Only applies to File entities.
            Ignored for other entity types.
        link_options: Link-specific configuration options. Only applies when the entity
            is a Link. Ignored for other entity types.
        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 appropriate Synapse entity model instance based on the entity type.

    Raises:
        ValueError: If both synapse_id and entity_name are provided, or if neither is provided.
        ValueError: If entity_name is provided without this being a valid lookup scenario.
        ValueError: If the synapse_id is not a valid Synapse ID format.

    Note:
        When using entity_name lookup:

        - For projects: leave parent_id=None
        - For all other entities: provide the parent_id of the containing folder/project

    Example: Retrieving entities by ID
        Get any entity by Synapse ID:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import File, Project
        from synapseclient.operations import get_async

        async def main():
            syn = Synapse()
            syn.login()

            # Works for any entity type
            entity = await get_async(synapse_id="syn123456")

            # The returned object will be the appropriate type
            if isinstance(entity, File):
                print(f"File: {entity.name}")
            elif isinstance(entity, Project):
                print(f"Project: {entity.name}")

        asyncio.run(main())
        ```

    Example: Retrieving entities by name
        Get an entity by name and parent:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.operations import get_async

        async def main():
            syn = Synapse()
            syn.login()

            # Get a file by name within a folder
            entity = await get_async(
                entity_name="my_file.txt",
                parent_id="syn123456"
            )

            # Get a project by name (parent_id=None)
            project = await get_async(
                entity_name="My Project",
                parent_id=None
            )

        asyncio.run(main())
        ```

    Example: Retrieving a specific version
        Get a specific version of a versionable entity:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.operations import get_async

        async def main():
            syn = Synapse()
            syn.login()

            entity = await get_async(synapse_id="syn123456", version_number=2)

        asyncio.run(main())
        ```

    Example: Retrieving a file with custom options
        Get file metadata with specific download options:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.operations import get_async, FileOptions, ActivityOptions

        async def main():
            syn = Synapse()
            syn.login()

            file_entity = await get_async(
                synapse_id="syn123456",
                activity_options=ActivityOptions(include_activity=True),
                file_options=FileOptions(
                    download_file=False
                )
            )

        asyncio.run(main())
        ```

    Example: Retrieving a table with activity and columns
        Get table with activity and column information:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.operations import get_async, ActivityOptions, TableOptions

        async def main():
            syn = Synapse()
            syn.login()

            table_entity = await get_async(
                synapse_id="syn123456",
                activity_options=ActivityOptions(include_activity=True),
                table_options=TableOptions(include_columns=True)
            )

        asyncio.run(main())
        ```

    Example: Following links
        Get the target of a link entity:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.operations import get_async, LinkOptions

        async def main():
            syn = Synapse()
            syn.login()

            target_entity = await get_async(
                synapse_id="syn123456",
                link_options=LinkOptions(follow_link=True)
            )

        asyncio.run(main())
        ```

    Example: Working with Link entities
        Get a Link entity without following it:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.operations import get_async, LinkOptions

        async def main():
            syn = Synapse()
            syn.login()

            # Get the link entity itself
            link_entity = await get_async(
                synapse_id="syn123456",  # Example link ID
                link_options=LinkOptions(follow_link=False)
            )
            print(f"Link: {link_entity.name} -> {link_entity.target_id}")

            # Then follow the link to get the target
            target_entity = await get_async(
                synapse_id="syn123456",
                link_options=LinkOptions(follow_link=True)
            )
            print(f"Target: {target_entity.name} (type: {type(target_entity).__name__})")

        asyncio.run(main())
        ```

    Example: Comprehensive File options
        Download file with custom location and collision handling:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.operations import get_async, FileOptions

        async def main():
            syn = Synapse()
            syn.login()

            file_entity = await get_async(
                synapse_id="syn123456",
                file_options=FileOptions(
                    download_file=True,
                    download_location="/path/to/download/",
                    if_collision="overwrite.local"
                )
            )
            print(f"Downloaded file: {file_entity.name} to {file_entity.path}")

        asyncio.run(main())
        ```

    Example: Table options for table-like entities
        Get table entities with column information:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.operations import get_async, TableOptions

        async def main():
            syn = Synapse()
            syn.login()

            # Works for Table, Dataset, EntityView, MaterializedView,
            # SubmissionView, VirtualTable, and DatasetCollection
            table_entity = await get_async(
                synapse_id="syn123456",  # Example table ID
                table_options=TableOptions(include_columns=True)
            )
            print(f"Table: {table_entity.name} with {len(table_entity.columns)} columns")

        asyncio.run(main())
        ```

    Example: Combining multiple options
        Get a File with both activity and custom download options:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.operations import get_async, FileOptions, ActivityOptions

        async def main():
            syn = Synapse()
            syn.login()

            file_entity = await get_async(
                synapse_id="syn123456",
                activity_options=ActivityOptions(include_activity=True),
                file_options=FileOptions(
                    download_file=False
                )
            )
            print(f"File: {file_entity.name} (activity included: {file_entity.activity is not None})")

        asyncio.run(main())
        ```

    Example: Working with entity instances
        Pass an existing entity instance to refresh or apply new options:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.operations import get_async, FileOptions

        async def main():
            syn = Synapse()
            syn.login()

            # Get an entity first
            entity = await get_async(synapse_id="syn123456")
            print(f"Original entity: {entity.name}")

            # Then use the entity instance to get it again with different options
            refreshed_entity = await get_async(
                entity,
                file_options=FileOptions(download_file=False)
            )
            print(f"Refreshed entity: {refreshed_entity.name} (download_file: {refreshed_entity.download_file})")

        asyncio.run(main())
        ```
    """
    from synapseclient.api.entity_bundle_services_v2 import (
        get_entity_id_bundle2,
        get_entity_id_version_bundle2,
    )
    from synapseclient.api.entity_services import get_child, get_entity_type
    from synapseclient.core.constants import concrete_types
    from synapseclient.models import (
        Dataset,
        DatasetCollection,
        EntityView,
        File,
        Folder,
        Link,
        MaterializedView,
        Project,
        SubmissionView,
        Table,
        VirtualTable,
    )

    activity_options = activity_options or ActivityOptions()
    file_options = file_options or FileOptions()
    table_options = table_options or TableOptions()
    link_options = link_options or LinkOptions()

    # Handle case where an entity instance is passed directly
    entity_types = (
        Dataset,
        DatasetCollection,
        EntityView,
        File,
        Folder,
        Link,
        MaterializedView,
        Project,
        SubmissionView,
        Table,
        VirtualTable,
    )
    if isinstance(synapse_id, entity_types):
        return await _handle_entity_instance(
            entity=synapse_id,
            version_number=version_number,
            activity_options=activity_options,
            file_options=file_options,
            table_options=table_options,
            link_options=link_options,
            synapse_client=synapse_client,
        )

    # Validate input parameters
    if synapse_id is not None and entity_name is not None:
        raise ValueError(
            "Cannot specify both synapse_id and entity_name. "
            "Use synapse_id for direct lookup or entity_name with optional parent_id for name-based lookup."
        )

    if synapse_id is None and entity_name is None:
        raise ValueError(
            "Must specify either synapse_id or entity_name. "
            "Use synapse_id for direct lookup or entity_name with optional parent_id for name-based lookup."
        )

    # If looking up by name, get the synapse_id first
    if entity_name is not None and synapse_id is None:
        synapse_id = await get_child(
            entity_name=entity_name, parent_id=parent_id, synapse_client=synapse_client
        )
        if synapse_id is None:
            if parent_id is None:
                raise SynapseNotFoundError(
                    f"Project with name '{entity_name}' not found."
                )
            else:
                raise SynapseNotFoundError(
                    f"Entity with name '{entity_name}' not found in parent '{parent_id}'."
                )

    entity_header = await get_entity_type(
        entity_id=synapse_id, synapse_client=synapse_client
    )
    entity_type = entity_header.type

    if entity_type == concrete_types.LINK_ENTITY:
        return await _handle_link_entity(
            synapse_id=synapse_id,
            link_options=link_options,
            file_options=file_options,
            synapse_client=synapse_client,
        )

    elif entity_type == concrete_types.FILE_ENTITY:
        return await _handle_file_entity(
            synapse_id=synapse_id,
            version_number=version_number,
            activity_options=activity_options,
            file_options=file_options,
            synapse_client=synapse_client,
        )

    elif entity_type == concrete_types.PROJECT_ENTITY:
        return await _handle_simple_entity(
            entity_class=Project,
            synapse_id=synapse_id,
            version_number=version_number,
            synapse_client=synapse_client,
        )

    elif entity_type == concrete_types.FOLDER_ENTITY:
        return await _handle_simple_entity(
            entity_class=Folder,
            synapse_id=synapse_id,
            version_number=version_number,
            synapse_client=synapse_client,
        )

    elif entity_type == concrete_types.TABLE_ENTITY:
        return await _handle_table_like_entity(
            entity_class=Table,
            synapse_id=synapse_id,
            version_number=version_number,
            activity_options=activity_options,
            table_options=table_options,
            synapse_client=synapse_client,
        )

    elif entity_type == concrete_types.DATASET_ENTITY:
        return await _handle_table_like_entity(
            entity_class=Dataset,
            synapse_id=synapse_id,
            version_number=version_number,
            activity_options=activity_options,
            table_options=table_options,
            synapse_client=synapse_client,
        )

    elif entity_type == concrete_types.DATASET_COLLECTION_ENTITY:
        return await _handle_table_like_entity(
            entity_class=DatasetCollection,
            synapse_id=synapse_id,
            version_number=version_number,
            activity_options=activity_options,
            table_options=table_options,
            synapse_client=synapse_client,
        )

    elif entity_type == concrete_types.ENTITY_VIEW:
        return await _handle_table_like_entity(
            entity_class=EntityView,
            synapse_id=synapse_id,
            version_number=version_number,
            activity_options=activity_options,
            table_options=table_options,
            synapse_client=synapse_client,
        )

    elif entity_type == concrete_types.MATERIALIZED_VIEW:
        return await _handle_table_like_entity(
            entity_class=MaterializedView,
            synapse_id=synapse_id,
            version_number=version_number,
            activity_options=activity_options,
            table_options=table_options,
            synapse_client=synapse_client,
        )

    elif entity_type == concrete_types.SUBMISSION_VIEW:
        return await _handle_table_like_entity(
            entity_class=SubmissionView,
            synapse_id=synapse_id,
            version_number=version_number,
            activity_options=activity_options,
            table_options=table_options,
            synapse_client=synapse_client,
        )

    elif entity_type == concrete_types.VIRTUAL_TABLE:
        return await _handle_table_like_entity(
            entity_class=VirtualTable,
            synapse_id=synapse_id,
            version_number=version_number,
            activity_options=activity_options,
            table_options=table_options,
            synapse_client=synapse_client,
        )

    else:
        from synapseclient import Synapse

        client = Synapse.get_client(synapse_client=synapse_client)
        client.logger.warning(
            "Unknown entity type: %s. Falling back to returning %s as a dictionary bundle matching "
            "https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/entitybundle/v2/EntityBundle.html",
            entity_type,
            synapse_id,
        )

        # This allows the function to handle new entity types that may be added in the future
        if version_number is not None:
            return await get_entity_id_version_bundle2(
                entity_id=synapse_id,
                version=version_number,
                synapse_client=synapse_client,
            )
        else:
            return await get_entity_id_bundle2(
                entity_id=synapse_id, synapse_client=synapse_client
            )

synapseclient.operations.FileOptions `dataclass` ¶

Configuration options specific to File entities when using the factory methods.

This dataclass allows you to customize how File entities are handled during retrieval, including download behavior, file location, and collision handling.

ATTRIBUTE	DESCRIPTION
`download_file`	Whether to automatically download the file content when retrieving the File entity. If True, the file will be downloaded to the local filesystem. If False, only the metadata will be retrieved. Default is True. TYPE: `bool`
`download_location`	The local directory path where the file should be downloaded. If None, the file will be downloaded to the default Synapse cache location. If specified, must be a valid directory path. Default is None. TYPE: `Optional[str]`
`if_collision`	Strategy to use when a file with the same name already exists at the download location. Valid options are: - "keep.both": Keep both files by appending a number to the new file - "overwrite.local": Overwrite the existing local file - "keep.local": Keep the existing local file and skip download Default is "keep.both". TYPE: `str`

Example

Configure file download options:

from synapseclient.operations import FileOptions

# Download file to specific location with overwrite
file_options = FileOptions(
    download_file=True,
    download_location="/path/to/downloads/",
    if_collision="overwrite.local"
)

# Only retrieve metadata, don't download file content
metadata_only = FileOptions(download_file=False)

Source code in synapseclient/operations/factory_operations.py

@dataclass
class FileOptions:
    """
    Configuration options specific to File entities when using the factory methods.

    This dataclass allows you to customize how File entities are handled during
    retrieval, including download behavior, file location, and collision handling.

    Attributes:
        download_file: Whether to automatically download the file content when
            retrieving the File entity. If True, the file will be downloaded to
            the local filesystem. If False, only the metadata will be retrieved.
            Default is True.
        download_location: The local directory path where the file should be
            downloaded. If None, the file will be downloaded to the default Synapse
            cache location. If specified,
            must be a valid directory path. Default is None.
        if_collision: Strategy to use when a file with the same name already
            exists at the download location. Valid options are:
            - "keep.both": Keep both files by appending a number to the new file
            - "overwrite.local": Overwrite the existing local file
            - "keep.local": Keep the existing local file and skip download
            Default is "keep.both".

    Example:
        Configure file download options:

        ```python
        from synapseclient.operations import FileOptions

        # Download file to specific location with overwrite
        file_options = FileOptions(
            download_file=True,
            download_location="/path/to/downloads/",
            if_collision="overwrite.local"
        )

        # Only retrieve metadata, don't download file content
        metadata_only = FileOptions(download_file=False)
        ```
    """

    download_file: bool = True
    download_location: Optional[str] = None
    if_collision: str = "keep.both"

synapseclient.operations.ActivityOptions `dataclass` ¶

Configuration options for entities that support activity/provenance tracking.

This dataclass controls whether activity information (provenance data) should be included when retrieving entities. Activity information tracks the computational steps, data sources, and relationships that led to the creation of an entity.

ATTRIBUTE	DESCRIPTION
`include_activity`	Whether to include activity/provenance information when retrieving the entity. If True, the returned entity will have its activity attribute populated with provenance data (if available). If False, the activity attribute will be None. Including activity may result in additional API calls and slower retrieval times. Default is False. TYPE: `bool`

Example

Configure activity inclusion:

from synapseclient.operations import ActivityOptions

# Include activity information
with_activity = ActivityOptions(include_activity=True)

# Skip activity information (faster retrieval)
without_activity = ActivityOptions(include_activity=False)

Note

Activity information is only available for entities that support provenance tracking (File, Table, Dataset, etc...). For other entity types, this option is ignored.

Source code in synapseclient/operations/factory_operations.py

@dataclass
class ActivityOptions:
    """
    Configuration options for entities that support activity/provenance tracking.

    This dataclass controls whether activity information (provenance data) should
    be included when retrieving entities. Activity information tracks the computational
    steps, data sources, and relationships that led to the creation of an entity.

    Attributes:
        include_activity: Whether to include activity/provenance information when
            retrieving the entity. If True, the returned entity will have its
            activity attribute populated with provenance data (if available).
            If False, the activity attribute will be None. Including activity
            may result in additional API calls and slower retrieval times.
            Default is False.

    Example:
        Configure activity inclusion:

        ```python
        from synapseclient.operations import ActivityOptions

        # Include activity information
        with_activity = ActivityOptions(include_activity=True)

        # Skip activity information (faster retrieval)
        without_activity = ActivityOptions(include_activity=False)
        ```

    Note:
        Activity information is only available for entities that support provenance
        tracking (File, Table, Dataset, etc...). For other entity
        types, this option is ignored.
    """

    include_activity: bool = False

synapseclient.operations.TableOptions `dataclass` ¶

Configuration options for table-like entities when using the factory methods.

This dataclass controls how table-like entities (Table, Dataset, EntityView, MaterializedView, SubmissionView, VirtualTable, and DatasetCollection) are retrieved, particularly whether column schema information should be included.

ATTRIBUTE DESCRIPTION

include_columns

Whether to include column schema information when retrieving table-like entities. If True, the returned entity will have its columns attribute populated with Column objects containing schema information (name, column_type, etc.). If False, the columns attribute will be an empty dict. Including columns may result in additional API calls but provides complete table structure information. Default is True.

TYPE: bool

Example

Configure table column inclusion:

from synapseclient.operations import TableOptions

# Include column schema information
with_columns = TableOptions(include_columns=True)

# Skip column information (faster retrieval)
without_columns = TableOptions(include_columns=False)

Source code in synapseclient/operations/factory_operations.py

@dataclass
class TableOptions:
    """
    Configuration options for table-like entities when using the factory methods.

    This dataclass controls how table-like entities (Table, Dataset, EntityView,
    MaterializedView, SubmissionView, VirtualTable, and DatasetCollection) are
    retrieved, particularly whether column schema information should be included.

    Attributes:
        include_columns: Whether to include column schema information when
            retrieving table-like entities. If True, the returned entity will
            have its columns attribute populated with Column objects containing
            schema information (name, column_type, etc.). If False, the columns
            attribute will be an empty dict. Including columns may result in
            additional API calls but provides complete table structure information.
            Default is True.

    Example:
        Configure table column inclusion:

        ```python
        from synapseclient.operations import TableOptions

        # Include column schema information
        with_columns = TableOptions(include_columns=True)

        # Skip column information (faster retrieval)
        without_columns = TableOptions(include_columns=False)
        ```
    """

    include_columns: bool = True

synapseclient.operations.LinkOptions `dataclass` ¶

Configuration options specific to Link entities when using the factory methods.

This dataclass controls how Link entities are handled during retrieval, particularly whether the link should be followed to return the target entity or if the Link entity itself should be returned.

ATTRIBUTE DESCRIPTION

follow_link

Whether to follow the link and return the target entity instead of the Link entity itself. If True, the factory method will return the entity that the Link points to (e.g., if a Link points to a File, a File object will be returned). If False, the Link entity itself will be returned, allowing you to inspect the link's properties such as target_id, target_version, etc. Default is True.

TYPE: bool

Example

Configure link following behavior:

from synapseclient.operations import LinkOptions

# Follow the link and return the target entity
follow_target = LinkOptions(follow_link=True)

# Return the Link entity itself
return_link = LinkOptions(follow_link=False)

Note

When follow_link=True, the returned entity type depends on what the Link points to (could be File, Project, Folder, etc.)
When follow_link=False, a Link entity is always returned

Source code in synapseclient/operations/factory_operations.py

@dataclass
class LinkOptions:
    """
    Configuration options specific to Link entities when using the factory methods.

    This dataclass controls how Link entities are handled during retrieval,
    particularly whether the link should be followed to return the target entity
    or if the Link entity itself should be returned.

    Attributes:
        follow_link: Whether to follow the link and return the target entity
            instead of the Link entity itself. If True, the factory method will
            return the entity that the Link points to (e.g., if a Link points
            to a File, a File object will be returned). If False, the Link
            entity itself will be returned, allowing you to inspect the link's
            properties such as target_id, target_version, etc. Default is True.

    Example:
        Configure link following behavior:

        ```python
        from synapseclient.operations import LinkOptions

        # Follow the link and return the target entity
        follow_target = LinkOptions(follow_link=True)

        # Return the Link entity itself
        return_link = LinkOptions(follow_link=False)
        ```

    Note:
        - When follow_link=True, the returned entity type depends on what the
          Link points to (could be File, Project, Folder, etc.)
        - When follow_link=False, a Link entity is always returned
    """

    follow_link: bool = True

synapseclient.operations.delete_async `async` ¶

delete_async(entity: Union[str, CurationTask, Dataset, DatasetCollection, EntityView, Evaluation, File, Folder, Grid, JSONSchema, MaterializedView, Project, RecordSet, SchemaOrganization, SubmissionView, Table, Team, VirtualTable], version: Optional[Union[int, str]] = None, version_only: bool = False, *, synapse_client: Optional[Synapse] = None) -> None

Factory method to delete any Synapse entity asynchronously.

This method serves as a unified interface for deleting any type of Synapse entity asynchronously. It automatically applies the appropriate delete logic based on the entity type.

Version Deletion Behavior

The function supports deleting specific versions of entities with the following precedence order:

version parameter (highest priority): When provided, this version number will be used for deletion, overriding any version information from the entity object or the entity ID string.
Entity's version_number attribute (secondary): If the entity object has a version_number attribute set and no explicit version parameter is provided, this version will be used.
version_only parameter: When set to True, indicates that only a specific version should be deleted (not the entire entity). This parameter is only meaningful when combined with a version number from either the version parameter or the entity's version_number attribute.

Supported for version-specific deletion:

String ID with version (e.g., "syn123.4")
File, RecordSet (use version_only=True)
Table, Dataset, DatasetCollection, EntityView, MaterializedView, SubmissionView, VirtualTable (use version_only=True)

Not supported for version-specific deletion:

Project, Folder, Evaluation, Team, SchemaOrganization, CurationTask, Grid

PARAMETER	DESCRIPTION
`entity`	The entity instance to delete, or a Synapse ID string (e.g., "syn123456" or "syn123456.4" for a specific version). Must be one of the supported entity types or a valid Synapse ID. TYPE: `Union[str, CurationTask, Dataset, DatasetCollection, EntityView, Evaluation, File, Folder, Grid, JSONSchema, MaterializedView, Project, RecordSet, SchemaOrganization, SubmissionView, Table, Team, VirtualTable]`
`version`	Optional version number to delete. Takes precedence over any version information in the entity object or ID string. When provided with `version_only=True`, deletes only this specific version. TYPE: `Optional[Union[int, str]]` DEFAULT: `None`
`version_only`	If True, only the specified version will be deleted, not the entire entity. Requires a version number from either the `version` parameter or the entity's `version_number` attribute. This parameter is applicable for entities that support version-specific deletion (File, RecordSet, Table, Dataset, DatasetCollection, EntityView, MaterializedView, SubmissionView, VirtualTable, JSONSchema). TYPE: `bool` DEFAULT: `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. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`None`	None

RAISES	DESCRIPTION
`ValueError`	If the entity is not a supported type or not a valid Synapse ID.
`ValueError`	If version_only is True but no version number is available.

Deleting a file by object

Delete a file from Synapse:

import asyncio
from synapseclient import Synapse
from synapseclient.models import File
from synapseclient.operations import delete_async

async def main():
    syn = Synapse()
    syn.login()

    file = File(id="syn123456")
    await delete_async(file)
    print("File deleted successfully")

asyncio.run(main())

Deleting a specific version of a file

Delete only version 2 of a file, keeping other versions:

import asyncio
from synapseclient import Synapse
from synapseclient.models import File
from synapseclient.operations import delete_async

async def main():
    syn = Synapse()
    syn.login()

    # Method 1: Using version parameter (highest priority)
    file = File(id="syn123456")
    await delete_async(file, version=2, version_only=True)

    # Method 2: Using entity's version_number attribute
    file = File(id="syn123456", version_number=2)
    await delete_async(file, version_only=True)

    # Method 3: Using synapse ID with version
    await delete_async("syn123456.2", version_only=True)
    print("File version 2 deleted successfully")

asyncio.run(main())

Deleting a file by ID string

Delete a file from Synapse using just its ID:

import asyncio
from synapseclient import Synapse
from synapseclient.operations import delete_async

async def main():
    syn = Synapse()
    syn.login()

    await delete_async("syn123456")
    print("Entity deleted successfully")

asyncio.run(main())

Deleting a specific version of a RecordSet

Delete only a specific version of a RecordSet:

import asyncio
from synapseclient import Synapse
from synapseclient.models import RecordSet
from synapseclient.operations import delete_async

async def main():
    syn = Synapse()
    syn.login()

    record_set = RecordSet(id="syn123456", version_number=3)
    await delete_async(record_set, version_only=True)
    print("RecordSet version 3 deleted successfully")

asyncio.run(main())

Source code in synapseclient/operations/delete_operations.py

async def delete_async(
    entity: Union[
        str,
        "CurationTask",
        "Dataset",
        "DatasetCollection",
        "EntityView",
        "Evaluation",
        "File",
        "Folder",
        "Grid",
        "JSONSchema",
        "MaterializedView",
        "Project",
        "RecordSet",
        "SchemaOrganization",
        "SubmissionView",
        "Table",
        "Team",
        "VirtualTable",
    ],
    version: Optional[Union[int, str]] = None,
    version_only: bool = False,
    *,
    synapse_client: Optional["Synapse"] = None,
) -> None:
    """
    Factory method to delete any Synapse entity asynchronously.

    This method serves as a unified interface for deleting any type of Synapse entity
    asynchronously. It automatically applies the appropriate delete logic based on the
    entity type.

    Version Deletion Behavior:
        The function supports deleting specific versions of entities with the following
        precedence order:

        1. **version parameter** (highest priority): When provided, this version number
           will be used for deletion, overriding any version information from the entity
           object or the entity ID string.

        2. **Entity's version_number attribute** (secondary): If the entity object has
           a `version_number` attribute set and no explicit `version` parameter is
           provided, this version will be used.

        3. **version_only parameter**: When set to True, indicates that only a specific
           version should be deleted (not the entire entity). This parameter is only
           meaningful when combined with a version number from either the `version`
           parameter or the entity's `version_number` attribute.

        **Supported for version-specific deletion:**

        - String ID with version (e.g., "syn123.4")
        - File, RecordSet (use version_only=True)
        - Table, Dataset, DatasetCollection, EntityView, MaterializedView,
          SubmissionView, VirtualTable (use version_only=True)

        **Not supported for version-specific deletion:**

        - Project, Folder, Evaluation, Team, SchemaOrganization, CurationTask, Grid

    Arguments:
        entity: The entity instance to delete, or a Synapse ID string (e.g., "syn123456"
            or "syn123456.4" for a specific version). Must be one of the supported
            entity types or a valid Synapse ID.
        version: Optional version number to delete. Takes precedence over any version
            information in the entity object or ID string. When provided with
            `version_only=True`, deletes only this specific version.
        version_only: If True, only the specified version will be deleted, not the
            entire entity. Requires a version number from either the `version` parameter
            or the entity's `version_number` attribute. This parameter is applicable for
            entities that support version-specific deletion (File, RecordSet, Table,
            Dataset, DatasetCollection, EntityView, MaterializedView, SubmissionView,
            VirtualTable, JSONSchema).
        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:
        None

    Raises:
        ValueError: If the entity is not a supported type or not a valid Synapse ID.
        ValueError: If version_only is True but no version number is available.

    Example: Deleting a file by object
        Delete a file from Synapse:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import File
        from synapseclient.operations import delete_async

        async def main():
            syn = Synapse()
            syn.login()

            file = File(id="syn123456")
            await delete_async(file)
            print("File deleted successfully")

        asyncio.run(main())
        ```

    Example: Deleting a specific version of a file
        Delete only version 2 of a file, keeping other versions:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import File
        from synapseclient.operations import delete_async

        async def main():
            syn = Synapse()
            syn.login()

            # Method 1: Using version parameter (highest priority)
            file = File(id="syn123456")
            await delete_async(file, version=2, version_only=True)

            # Method 2: Using entity's version_number attribute
            file = File(id="syn123456", version_number=2)
            await delete_async(file, version_only=True)

            # Method 3: Using synapse ID with version
            await delete_async("syn123456.2", version_only=True)
            print("File version 2 deleted successfully")

        asyncio.run(main())
        ```

    Example: Deleting a file by ID string
        Delete a file from Synapse using just its ID:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.operations import delete_async

        async def main():
            syn = Synapse()
            syn.login()

            await delete_async("syn123456")
            print("Entity deleted successfully")

        asyncio.run(main())
        ```

    Example: Deleting a specific version of a RecordSet
        Delete only a specific version of a RecordSet:

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import RecordSet
        from synapseclient.operations import delete_async

        async def main():
            syn = Synapse()
            syn.login()

            record_set = RecordSet(id="syn123456", version_number=3)
            await delete_async(record_set, version_only=True)
            print("RecordSet version 3 deleted successfully")

        asyncio.run(main())
        ```
    """
    from synapseclient.models import (
        CurationTask,
        Dataset,
        DatasetCollection,
        EntityView,
        Evaluation,
        File,
        Folder,
        Grid,
        JSONSchema,
        MaterializedView,
        Project,
        RecordSet,
        SchemaOrganization,
        SubmissionView,
        Table,
        Team,
        VirtualTable,
    )

    # Handle string synapse ID
    if isinstance(entity, str):
        from synapseclient.core.utils import get_synid_and_version

        synapse_id = is_synapse_id_str(entity)
        if not synapse_id:
            raise ValueError(
                f"Invalid Synapse ID: {entity}. "
                "Expected a valid Synapse ID string (e.g., 'syn123456' or 'syn123456.4')."
            )

        # Check if version is embedded in the string ID (e.g., "syn123.4")
        syn_id, syn_version = get_synid_and_version(synapse_id)

        # Determine final version: explicit version parameter takes precedence
        final_version = version if version is not None else syn_version

        # If there's a version to delete, require version_only=True for safety
        if final_version is not None and not version_only:
            raise ValueError(
                f"Deleting a specific version requires version_only=True. "
                f"Use delete('{entity}', version_only=True) to delete version {final_version}."
            )

        await delete_entity(
            entity_id=syn_id,
            version_number=final_version,
            synapse_client=synapse_client,
        )
        return None

    # Determine final version to use based on precedence
    final_version_for_entity = version
    entity_version = None

    # Check if entity has version_number attribute
    if hasattr(entity, "version_number"):
        entity_version = getattr(entity, "version_number", None)
        if final_version_for_entity is None and entity_version is not None:
            final_version_for_entity = entity_version

    # Emit warning only when there's an actual version conflict (both are set and different)
    if (
        version_only
        and version is not None
        and entity_version is not None
        and version != entity_version
    ):
        from synapseclient import Synapse

        client = Synapse.get_client(synapse_client=synapse_client)
        client.logger.warning(
            f"Version conflict: 'version' parameter ({version}) differs from "
            f"entity's 'version_number' attribute ({entity_version}). "
            "Using 'version' parameter as it takes precedence."
        )

    # Handle entities that support version-specific deletion with version_only parameter
    if isinstance(entity, (File, RecordSet)):
        # Validate that if version_only is True, we have a version number
        if version_only and final_version_for_entity is None:
            raise ValueError(
                "version_only=True requires a version number. "
                "Provide either 'version' parameter or set 'version_number' on the entity."
            )

        # Only pass version_only=True when we actually have a version to delete
        if version_only and final_version_for_entity is not None:
            # Set the entity's version_number to the final version so delete_async uses it
            entity.version_number = final_version_for_entity
            return await entity.delete_async(
                version_only=True, synapse_client=synapse_client
            )
        else:
            return await entity.delete_async(
                version_only=False, synapse_client=synapse_client
            )

    # Handle table-like entities that support version deletion through the API
    elif isinstance(
        entity,
        (
            Table,
            Dataset,
            DatasetCollection,
            EntityView,
            MaterializedView,
            SubmissionView,
            VirtualTable,
        ),
    ):
        # Validate that if version_only is True, we have a version number
        if version_only and final_version_for_entity is None:
            raise ValueError(
                "version_only=True requires a version number. "
                "Provide either 'version' parameter or set 'version_number' on the entity."
            )

        # Only use version-specific deletion when version_only=True AND we have a version
        if version_only and final_version_for_entity is not None:
            # These entities support version deletion through the API
            return await delete_entity(
                entity_id=entity.id,
                version_number=final_version_for_entity,
                synapse_client=synapse_client,
            )
        else:
            # Delete entire entity (DeleteMixin will strip any version from entity.id)
            return await entity.delete_async(synapse_client=synapse_client)

    # Handle entities without version support
    elif isinstance(
        entity,
        (
            Folder,
            Project,
            Evaluation,
            Team,
            SchemaOrganization,
            CurationTask,
            Grid,
        ),
    ):
        if version_only or final_version_for_entity is not None:
            from synapseclient import Synapse

            client = Synapse.get_client(synapse_client=synapse_client)
            client.logger.warning(
                f"{type(entity).__name__} does not support version-specific deletion. "
                "The entire entity will be deleted."
            )
        return await entity.delete_async(synapse_client=synapse_client)

    # JSONSchema supports version parameter
    elif isinstance(entity, JSONSchema):
        if final_version_for_entity is not None:
            return await entity.delete_async(
                version=str(final_version_for_entity), synapse_client=synapse_client
            )
        else:
            return await entity.delete_async(synapse_client=synapse_client)

    else:
        raise ValueError(
            f"Unsupported entity type: {type(entity).__name__}. "
            "Supported types are: str (Synapse ID), CurationTask, Dataset, DatasetCollection, "
            "EntityView, Evaluation, File, Folder, Grid, JSONSchema, MaterializedView, "
            "Project, RecordSet, SchemaOrganization, SubmissionView, Table, Team, VirtualTable."
        )

synapseclient.operations.store_async `async` ¶

store_async(entity: Union[AgentSession, CurationTask, Dataset, DatasetCollection, EntityView, Evaluation, File, Folder, FormData, FormGroup, Grid, JSONSchema, Link, MaterializedView, Project, RecordSet, SchemaOrganization, SubmissionView, Table, Team, VirtualTable], parent: Optional[Union[Folder, Project]] = None, *, file_options: Optional[StoreFileOptions] = None, container_options: Optional[StoreContainerOptions] = None, table_options: Optional[StoreTableOptions] = None, json_schema_options: Optional[StoreJSONSchemaOptions] = None, grid_options: Optional[StoreGridOptions] = None, synapse_client: Optional[Synapse] = None) -> Union[AgentSession, CurationTask, Dataset, DatasetCollection, EntityView, Evaluation, File, Folder, FormData, FormGroup, Grid, JSONSchema, Link, MaterializedView, Project, RecordSet, SchemaOrganization, SubmissionView, Table, Team, VirtualTable]

Factory method to store any Synapse entity asynchronously.

This method serves as a unified interface for storing any type of Synapse entity asynchronously. It automatically applies the appropriate store logic based on the entity type and the options provided.

PARAMETER	DESCRIPTION
`entity`	The entity instance to store. Must be one of the supported entity types. TYPE: `Union[AgentSession, CurationTask, Dataset, DatasetCollection, EntityView, Evaluation, File, Folder, FormData, FormGroup, Grid, JSONSchema, Link, MaterializedView, Project, RecordSet, SchemaOrganization, SubmissionView, Table, Team, VirtualTable]`
`parent`	The parent folder or project to store the entity in. Only applicable for File, Folder, Link, and RecordSet entities. Ignored for other entity types. TYPE: `Optional[Union[Folder, Project]]` DEFAULT: `None`
`file_options`	File-specific configuration options. Only applies to File and RecordSet entities. Ignored for other entity types. TYPE: `Optional[StoreFileOptions]` DEFAULT: `None`
`container_options`	Container-specific configuration options. Only applies to Project and Folder entities. Ignored for other entity types. TYPE: `Optional[StoreContainerOptions]` DEFAULT: `None`
`table_options`	Table-specific configuration options. Only applies to Table-like entities (Table, Dataset, EntityView, MaterializedView, SubmissionView, VirtualTable, DatasetCollection). Ignored for other entity types. TYPE: `Optional[StoreTableOptions]` DEFAULT: `None`
`json_schema_options`	JSONSchema-specific configuration options. Only applies to JSONSchema entities. Required for JSONSchema. Ignored for other entity types. TYPE: `Optional[StoreJSONSchemaOptions]` DEFAULT: `None`
`grid_options`	Grid-specific configuration options. Only applies to Grid entities. Ignored for other entity types. TYPE: `Optional[StoreGridOptions]` DEFAULT: `None`
`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
`Union[AgentSession, CurationTask, Dataset, DatasetCollection, EntityView, Evaluation, File, Folder, FormData, FormGroup, Grid, JSONSchema, Link, MaterializedView, Project, RecordSet, SchemaOrganization, SubmissionView, Table, Team, VirtualTable]`	The stored Synapse entity model instance.

RAISES	DESCRIPTION
`ValueError`	If the entity is not a supported type.

Storing a file

Store a file to Synapse:

import asyncio
from synapseclient import Synapse
from synapseclient.models import File
from synapseclient.operations import store_async

async def main():
    syn = Synapse()
    syn.login()

    file = File(path="/path/to/file.txt", parent_id="syn123456")
    stored_file = await store_async(file)
    print(f"Stored file: {stored_file.name} (ID: {stored_file.id})")

asyncio.run(main())

Storing a file with custom options

Store a file with custom options:

import asyncio
from synapseclient import Synapse
from synapseclient.models import File
from synapseclient.operations import store_async, StoreFileOptions

async def main():
    syn = Synapse()
    syn.login()

    file = File(path="/path/to/file.txt", parent_id="syn123456")
    stored_file = await store_async(
        file,
        file_options=StoreFileOptions(
            synapse_store=True,
            content_type="text/plain",
            merge_existing_annotations=True
        )
    )
    print(f"Stored file: {stored_file.name}")

asyncio.run(main())

Storing a folder

Store a folder to Synapse:

import asyncio
from synapseclient import Synapse
from synapseclient.models import Folder
from synapseclient.operations import store_async

async def main():
    syn = Synapse()
    syn.login()

    folder = Folder(name="My Folder", parent_id="syn123456")
    stored_folder = await store_async(folder)
    print(f"Stored folder: {stored_folder.name} (ID: {stored_folder.id})")

asyncio.run(main())

Storing a project

Store a project to Synapse:

import asyncio
from synapseclient import Synapse
from synapseclient.models import Project
from synapseclient.operations import store_async

async def main():
    syn = Synapse()
    syn.login()

    project = Project(name="My Project")
    stored_project = await store_async(project)
    print(f"Stored project: {stored_project.name} (ID: {stored_project.id})")

asyncio.run(main())

Storing a table

Store a table to Synapse:

import asyncio
from synapseclient import Synapse
from synapseclient.models import Table, Column, ColumnType
from synapseclient.operations import store_async, StoreTableOptions

async def main():
    syn = Synapse()
    syn.login()

    table = Table(
        name="My Table",
        parent_id="syn123456",
        columns=[Column(name="col1", column_type=ColumnType.STRING, maximum_size=50)]
    )
    stored_table = await store_async(
        table,
        table_options=StoreTableOptions(dry_run=False, job_timeout=600)
    )
    print(f"Stored table: {stored_table.name} (ID: {stored_table.id})")

asyncio.run(main())

Storing a link

Store a link to Synapse:

import asyncio
from synapseclient import Synapse
from synapseclient.models import Link
from synapseclient.operations import store_async

async def main():
    syn = Synapse()
    syn.login()

    link = Link(name="My Link", parent_id="syn123456", target_id="syn789")
    stored_link = await store_async(link)
    print(f"Stored link: {stored_link.name} (ID: {stored_link.id})")

asyncio.run(main())

Storing with parent parameter

Store an entity by passing the parent as a parameter:

import asyncio
from synapseclient import Synapse
from synapseclient.models import File, Folder
from synapseclient.operations import store_async

async def main():
    syn = Synapse()
    syn.login()

    parent_folder = Folder(id="syn123456")
    file = File(path="/path/to/file.txt")
    stored_file = await store_async(file, parent=parent_folder)
    print(f"Stored file: {stored_file.name} in folder {parent_folder.id}")

asyncio.run(main())