SubmissionView

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.models.SubmissionView dataclass

Bases: SubmissionViewSynchronousProtocol, AccessControllable, ColumnMixin, DeleteMixin, GetMixin, QueryMixin, ViewBase, ViewStoreMixin, ViewSnapshotMixin

A SubmissionView object represents the metadata of a Synapse Submission View. https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/SubmissionView.html

ATTRIBUTE	DESCRIPTION
id	The unique immutable ID for this entity. A new ID will be generated for new Entities. Once issued, this ID is guaranteed to never change or be re-issued. TYPE: Optional[str]
name	The name of this entity. Must be 256 characters or less. Names may only contain: letters, numbers, spaces, underscores, hyphens, periods, plus signs, apostrophes, and parentheses. TYPE: Optional[str]
description	The description of this entity. Must be 1000 characters or less. TYPE: Optional[str]
etag	Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an entity is out-of-date. TYPE: Optional[str]
created_on	The date this entity was created. TYPE: Optional[str]
modified_on	The date this entity was last modified. TYPE: Optional[str]
created_by	The ID of the user that created this entity. TYPE: Optional[str]
modified_by	The ID of the user that last modified this entity. TYPE: Optional[str]
parent_id	The ID of the Entity that is the parent of this Entity. TYPE: Optional[str]
version_number	The version number issued to this version on the object. TYPE: Optional[int]
version_label	The version label for this entity. TYPE: Optional[str]
version_comment	The version comment for this entity. TYPE: Optional[str]
is_latest_version	If this is the latest version of the object. TYPE: Optional[bool]
columns	The columns of this submission view. This is an ordered dictionary where the key is the name of the column and the value is the Column object. When creating a new instance of a SubmissionView object you may pass any of the following types as the columns argument: - A list of Column objects - A dictionary where the key is the name of the column and the value is the Column object - An OrderedDict where the key is the name of the column and the value is the Column object The order of the columns will be the order they are stored in Synapse. If you need to reorder the columns the recommended approach is to use the .reorder_column() method. Additionally, you may add, and delete columns using the .add_column(), and .delete_column() methods on your view class instance. You may modify the attributes of the Column object to change the column type, name, or other attributes. For example, suppose you'd like to change a column from a INTEGER to a DOUBLE. You can do so by changing the column type attribute of the Column object. The next time you store the view the column will be updated in Synapse with the new type. from synapseclient import Synapse from synapseclient.models import SubmissionView, Column, ColumnType syn = Synapse() syn.login() submission_view = SubmissionView(id="syn1234").get() submission_view.columns["my_column"].column_type = ColumnType.DOUBLE submission_view.store() Note that the keys in this dictionary should match the column names as they are in Synapse. However, know that the name attribute of the Column object is used for all interactions with the Synapse API. The OrderedDict key is purely for the usage of this interface. For example, if you wish to rename a column you may do so by changing the name attribute of the Column object. The key in the OrderedDict does not need to be changed. The next time you store the view the column will be updated in Synapse with the new name and the key in the OrderedDict will be updated. TYPE: Optional[Union[List[Column], OrderedDict[str, Column], Dict[str, Column]]]
is_search_enabled	When creating or updating a table or view, specifies if full-text search should be enabled. Note that enabling full-text search might slow down the indexing of the table or view. TYPE: Optional[bool]
scope_ids	The list of container IDs that define the scope of this view. For submission views, this is the list of evaluation queues that the view is associated with. TYPE: List[str]
view_entity_type	The API model string for the type of view. This is used to determine the default columns that are added to the table. Must be defined as a ViewEntityType enum. TYPE: ViewEntityType

Create a new SubmissionView.

from synapseclient import Synapse
from synapseclient.models import SubmissionView

syn = Synapse()
syn.login()

my_submission_view = SubmissionView(
    name="My Submission View",
    parent_id="syn1234",
    scope_ids=["syn5678", "syn6789"],  # IDs of evaluation queues
).store()
print(my_submission_view)

Source code in synapseclient/models/submissionview.py

@dataclass
@async_to_sync
class SubmissionView(
    SubmissionViewSynchronousProtocol,
    AccessControllable,
    ColumnMixin,
    DeleteMixin,
    GetMixin,
    QueryMixin,
    ViewBase,
    ViewStoreMixin,
    ViewSnapshotMixin,
):
    """A `SubmissionView` object represents the metadata of a Synapse Submission View.
    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/SubmissionView.html>

    Attributes:
        id: The unique immutable ID for this entity. A new ID will be generated for new
            Entities. Once issued, this ID is guaranteed to never change or be re-issued.
        name: The name of this entity. Must be 256 characters or less. Names may only
            contain: letters, numbers, spaces, underscores, hyphens, periods, plus
            signs, apostrophes, and parentheses.
        description: The description of this entity. Must be 1000 characters or less.
        etag: Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle
            concurrent updates. Since the E-Tag changes every time an entity is updated
            it is used to detect when a client's current representation of an entity is
            out-of-date.
        created_on: The date this entity was created.
        modified_on: The date this entity was last modified.
        created_by: The ID of the user that created this entity.
        modified_by: The ID of the user that last modified this entity.
        parent_id: The ID of the Entity that is the parent of this Entity.
        version_number: The version number issued to this version on the object.
        version_label: The version label for this entity.
        version_comment: The version comment for this entity.
        is_latest_version: If this is the latest version of the object.
        columns: The columns of this submission view. This is an ordered dictionary
            where the key is the name of the column and the value is the Column object.
            When creating a new instance of a SubmissionView object you may pass any of
            the following types as the `columns` argument:
            - A list of Column objects
            - A dictionary where the key is the name of the column and the value is the
                Column object
            - An OrderedDict where the key is the name of the column and the value is
                the Column object
            The order of the columns will be the order they are stored in Synapse. If
            you need to reorder the columns the recommended approach is to use the
            `.reorder_column()` method. Additionally, you may add, and delete columns
            using the `.add_column()`, and `.delete_column()` methods on your view class
            instance.

            You may modify the attributes of the Column object to change the column
            type, name, or other attributes. For example, suppose you'd like to change a
            column from a INTEGER to a DOUBLE. You can do so by changing the column type
            attribute of the Column object. The next time you store the view the column
            will be updated in Synapse with the new type.
            ```python
            from synapseclient import Synapse
            from synapseclient.models import SubmissionView, Column, ColumnType

            syn = Synapse()
            syn.login()

            submission_view = SubmissionView(id="syn1234").get()
            submission_view.columns["my_column"].column_type = ColumnType.DOUBLE
            submission_view.store()
            ```
            Note that the keys in this dictionary should match the column names as they
            are in Synapse. However, know that the name attribute of the Column object is
            used for all interactions with the Synapse API. The OrderedDict key is purely
            for the usage of this interface. For example, if you wish to rename a column
            you may do so by changing the name attribute of the Column object. The key in
            the OrderedDict does not need to be changed. The next time you store the view
            the column will be updated in Synapse with the new name and the key in the
            OrderedDict will be updated.
        is_search_enabled: When creating or updating a table or view, specifies if full-text
            search should be enabled. Note that enabling full-text search might slow down
            the indexing of the table or view.
        scope_ids: The list of container IDs that define the scope of this view. For
            submission views, this is the list of evaluation queues that the view
            is associated with.
        view_entity_type: The API model string for the type of view. This is used to
            determine the default columns that are added to the table. Must be defined as
            a `ViewEntityType` enum.

    Example: Create a new SubmissionView.
        ```python
        from synapseclient import Synapse
        from synapseclient.models import SubmissionView

        syn = Synapse()
        syn.login()

        my_submission_view = SubmissionView(
            name="My Submission View",
            parent_id="syn1234",
            scope_ids=["syn5678", "syn6789"],  # IDs of evaluation queues
        ).store()
        print(my_submission_view)
        ```
    """

    id: Optional[str] = None
    """
    The unique immutable ID for this entity. A new ID will be generated for new Entities.
    Once issued, this ID is guaranteed to never change or be re-issued.
    """

    name: Optional[str] = None
    """
    The name of this entity. Must be 256 characters or less. Names may only contain:
    letters, numbers, spaces, underscores, hyphens, periods, plus signs, apostrophes, and parentheses.
    """

    description: Optional[str] = None
    """
    The description of this entity. Must be 1000 characters or less.
    """

    etag: Optional[str] = field(default=None, compare=False)
    """
    Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates.
    Since the E-Tag changes every time an entity is updated, it is used to detect when a client's
    current representation of an entity is out-of-date.
    """

    created_on: Optional[str] = field(default=None, compare=False)
    """
    The date this entity was created.
    """

    modified_on: Optional[str] = field(default=None, compare=False)
    """
    The date this entity was last modified.
    """

    created_by: Optional[str] = field(default=None, compare=False)
    """
    The ID of the user that created this entity.
    """

    modified_by: Optional[str] = field(default=None, compare=False)
    """
    The ID of the user that last modified this entity.
    """

    parent_id: Optional[str] = None
    """
    The ID of the Entity that is the parent of this Entity.
    """

    version_number: Optional[int] = field(default=None, compare=False)
    """
    The version number issued to this version on the object.
    """

    version_label: Optional[str] = None
    """
    The version label for this entity.
    """

    version_comment: Optional[str] = None
    """
    The version comment for this entity.
    """

    is_latest_version: Optional[bool] = field(default=None, compare=False)
    """
    If this is the latest version of the object.
    """

    columns: Optional[
        Union[List[Column], OrderedDict[str, Column], Dict[str, Column]]
    ] = field(default_factory=OrderedDict, compare=False)
    """
    The columns of this submission view. This is an ordered dictionary where the key is the
    name of the column and the value is the Column object. When creating a new instance
    of a SubmissionView object you may pass any of the following types as the `columns` argument:

    - A list of Column objects
    - A dictionary where the key is the name of the column and the value is the Column object
    - An OrderedDict where the key is the name of the column and the value is the Column object

    The order of the columns will be the order they are stored in Synapse. If you need
    to reorder the columns the recommended approach is to use the `.reorder_column()`
    method. Additionally, you may add, and delete columns using the `.add_column()`,
    and `.delete_column()` methods on your view class instance.

    You may modify the attributes of the Column object to change the column
    type, name, or other attributes. For example, suppose you'd like to change a
    column from a INTEGER to a DOUBLE. You can do so by changing the column type
    attribute of the Column object. The next time you store the view the column
    will be updated in Synapse with the new type.

    ```python
    from synapseclient import Synapse
    from synapseclient.models import SubmissionView, Column, ColumnType

    syn = Synapse()
    syn.login()

    submission_view = SubmissionView(id="syn1234").get()
    submission_view.columns["my_column"].column_type = ColumnType.DOUBLE
    submission_view.store()
    ```

    Note that the keys in this dictionary should match the column names as they are in
    Synapse. However, know that the name attribute of the Column object is used for
    all interactions with the Synapse API. The OrderedDict key is purely for the usage
    of this interface. For example, if you wish to rename a column you may do so by
    changing the name attribute of the Column object. The key in the OrderedDict does
    not need to be changed. The next time you store the view the column will be updated
    in Synapse with the new name and the key in the OrderedDict will be updated.
    """

    _columns_to_delete: Optional[Dict[str, Column]] = field(default_factory=dict)
    """
    Columns to delete when the submission view is stored. The key in this dict is the ID of the
    column to delete. The value is the Column object that represents the column to
    delete.
    """

    activity: Optional[Activity] = field(default=None, compare=False)
    """The Activity model represents the main record of Provenance in Synapse.  It is
    analogous to the Activity defined in the
    [W3C Specification](https://www.w3.org/TR/prov-n/) on Provenance."""

    annotations: Optional[
        Dict[
            str,
            Union[
                List[str],
                List[bool],
                List[float],
                List[int],
                List[date],
                List[datetime],
            ],
        ]
    ] = field(default_factory=dict, compare=False)
    """Additional metadata associated with the submission view. The key is the name of your
    desired annotations. The value is an object containing a list of values
    (use empty list to represent no values for key) and the value type associated with
    all values in the list. To remove all annotations set this to an empty dict `{}`"""

    _last_persistent_instance: Optional["SubmissionView"] = field(
        default=None, repr=False, compare=False
    )
    """The last persistent instance of this object. This is used to determine if the
    object has been changed and needs to be updated in Synapse."""

    is_search_enabled: Optional[bool] = None
    """
    When creating or updating a table or view, specifies if full-text search should be enabled.
    Note that enabling full-text search might slow down the indexing of the table or view.
    """

    scope_ids: List[str] = field(default_factory=list)
    """
    The list of container IDs that define the scope of this view. For submission views,
    this is the list of evaluation queues that the view is associated with.
    """

    view_entity_type: ViewEntityType = ViewEntityType.SUBMISSION_VIEW
    """The API model string for the type of view. This is used to determine the default columns that are
    added to the table. Must be defined as a `ViewEntityType` enum.
    """

    def __post_init__(self):
        self.columns = self._convert_columns_to_ordered_dict(columns=self.columns)

    @property
    def has_changed(self) -> bool:
        """Determines if the object has been changed and needs to be updated in Synapse."""
        return (
            not self._last_persistent_instance
            or self._last_persistent_instance != self
            or (not self._last_persistent_instance.scope_ids and self.scope_ids)
            or self._last_persistent_instance.scope_ids != self.scope_ids
        )

    async def store_async(
        self,
        dry_run: bool = False,
        *,
        job_timeout: int = 600,
        synapse_client: Optional[Synapse] = None,
    ) -> "Self":
        """
        Store information about a SubmissionView including the annotations, columns,
        and scope. Updates to the `scope_ids` attribute will be cause the rows of the
        view to be updated. `scope_ids` is a list of evaluation queues that the view is
        associated with.

        Arguments:
            dry_run: If True, will not actually store the table but will log to
                the console what would have been stored.
            job_timeout: The maximum amount of time to wait for a job to complete.
                This is used when updating the table schema. If the timeout
                is reached a `SynapseTimeoutError` will be raised.
                The default is 600 seconds
            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 SubmissionView instance stored in synapse.

        Example: Create a new submission view.
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import SubmissionView

            syn = Synapse()
            syn.login()

            async def main():
                submission_view = SubmissionView(
                    name="My Submission View",
                    scope_ids=["syn9876543"],  # ID of an evaluation queue
                    parent_id="syn1234",
                )
                submission_view = await submission_view.store_async()
                print(f"Created Submission View with ID: {submission_view.id}")

            asyncio.run(main())
            ```

        Example: Update the scope of an existing submission view.
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import SubmissionView

            syn = Synapse()
            syn.login()

            async def main():
                submission_view = await SubmissionView(id="syn1234").get_async()
                submission_view.scope_ids = ["syn9876543", "syn8765432"]  # Add a second evaluation queue
                submission_view = await submission_view.store_async()
                print("Updated Submission View scope.")

            asyncio.run(main())
            ```
        """
        return await super().store_async(
            dry_run=dry_run,
            job_timeout=job_timeout,
            synapse_client=synapse_client,
        )

    async def get_async(
        self,
        include_columns: bool = True,
        include_activity: bool = False,
        *,
        synapse_client: Optional[Synapse] = None,
    ) -> "Self":
        """Retrieve a SubmissionView from Synapse.

        Arguments:
            include_columns: Whether to include the columns in the returned view.
                Defaults to True. This is useful when updating the columns.
            include_activity: Whether to include the activity in the returned view.
                Defaults to False. Setting this to True will include the activity
                record associated with this view.
            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 SubmissionView instance retrieved from Synapse.

        Example: Retrieving a submission view by ID.
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import SubmissionView

            syn = Synapse()
            syn.login()

            async def main():
                submission_view = await SubmissionView(id="syn1234").get_async()
                print(submission_view)

            asyncio.run(main())
            ```

        Example: Getting a submission view with its columns and activity.
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import SubmissionView

            syn = Synapse()
            syn.login()

            async def main():
                submission_view = await SubmissionView(id="syn1234").get_async(
                    include_columns=True,
                    include_activity=True
                )
                print(submission_view.columns)
                print(submission_view.activity)

            asyncio.run(main())
            ```
        """
        return await super().get_async(
            include_columns=include_columns,
            include_activity=include_activity,
            synapse_client=synapse_client,
        )

    async def delete_async(self, *, synapse_client: Optional[Synapse] = None) -> None:
        """Delete a SubmissionView from Synapse.

        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: Delete a submission view.
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import SubmissionView

            syn = Synapse()
            syn.login()

            async def main():
                submission_view = SubmissionView(id="syn1234")
                await submission_view.delete_async()
                print("Deleted Submission View.")

            asyncio.run(main())
            ```
        """
        return await super().delete_async(synapse_client=synapse_client)

    async def snapshot_async(
        self,
        *,
        comment: Optional[str] = None,
        label: Optional[str] = None,
        include_activity: bool = True,
        associate_activity_to_new_version: bool = True,
        synapse_client: Optional[Synapse] = None,
    ) -> "TableUpdateTransaction":
        """Creates a snapshot of the `SubmissionView` entity.
        Synapse handles snapshot creation differently for `Table`- and `View`-like
        entities. `View` snapshots are created using the asyncronous job API.

        Making a snapshot of a view allows you to create an immutable version of the
        view at the time of the snapshot. This is useful to create checkpoints in time
        that you may go back and reference, or use in a publication. Snapshots are
        immutable and cannot be changed. They may only be deleted.

        Arguments:
            comment: A unique comment to associate with the snapshot.
            label: A unique label to associate with the snapshot. If this is not a
                unique label an exception will be raised when you store this to Synapse.
            include_activity: If True the activity will be included in snapshot if it
                exists. In order to include the activity, the activity must have already
                been stored in Synapse by using the `activity` attribute on the View
                and calling the `store_async()` method on the View instance. Adding an
                activity to a snapshot of a table is meant to capture the provenance of
                the data at the time of the snapshot. Defaults to True.
            associate_activity_to_new_version: If True the activity will be associated
                with the new version of the table. If False the activity will not be
                associated with the new version of the table. Defaults to True.
            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:
            A `TableUpdateTransaction` object which includes the version number of the snapshot.

        Example: Creating a snapshot of a view with an activity
            Create a snapshot of a view and include the activity. The activity must have been stored in
            Synapse by using the `activity` attribute on the SubmissionView and calling the `store_async()`
            method on the SubmissionView instance. Adding an activity to a snapshot of a view is meant
            to capture the provenance of the data at the time of the snapshot.

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import SubmissionView, Activity, UsedURL

            syn = Synapse()
            syn.login()

            async def main():
                view = await SubmissionView(id="syn4567").get_async()
                view.activity = Activity(
                    name="Activity for snapshot",
                    used=[UsedURL(name="Data Source", url="https://example.org")]
                )
                await view.store_async() # Store the activity

                snapshot = await view.snapshot_async(
                    label="Q1 2025",
                    comment="Submissions reviewed in Lab A",
                    include_activity=True,
                    associate_activity_to_new_version=True
                )
                print(snapshot)

            asyncio.run(main())
            ```

        Example: Creating a snapshot of a view without an activity
            Create a snapshot of a view without including the activity. This is used in
            cases where we do not have any Provenance to associate with the snapshot and
            we do not want to persist any activity that may be present on the view to
            the new version of the view.

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import SubmissionView

            syn = Synapse()
            syn.login()

            async def main():
                view = await SubmissionView(id="syn4567").get_async()
                snapshot = await view.snapshot_async(
                    label="Q1 2025",
                    comment="Submissions reviewed in Lab A",
                    include_activity=False,
                    associate_activity_to_new_version=False
                )
                print(snapshot)

            asyncio.run(main())
            ```
        """
        return await super().snapshot_async(
            comment=comment,
            label=label,
            include_activity=include_activity,
            associate_activity_to_new_version=associate_activity_to_new_version,
            synapse_client=synapse_client,
        )

    def _set_last_persistent_instance(self) -> None:
        """Stash the last time this object interacted with Synapse. This is used to
        determine if the object has been changed and needs to be updated in Synapse."""
        del self._last_persistent_instance
        self._last_persistent_instance = dataclasses.replace(self)
        self._last_persistent_instance.activity = (
            dataclasses.replace(self.activity) if self.activity else None
        )
        self._last_persistent_instance.columns = (
            OrderedDict(
                (key, dataclasses.replace(column))
                for key, column in self.columns.items()
            )
            if self.columns
            else OrderedDict()
        )
        self._last_persistent_instance.annotations = (
            deepcopy(self.annotations) if self.annotations else {}
        )
        self._last_persistent_instance.scope_ids = (
            deepcopy(self.scope_ids) if self.scope_ids else []
        )

    def fill_from_dict(self, entity, set_annotations: bool = True) -> "Self":
        """
        Converts the data coming from the Synapse API into this datamodel.

        Arguments:
            synapse_table: The data coming from the Synapse API

        Returns:
            The SubmissionView object instance.
        """
        self.id = entity.get("id", None)
        self.name = entity.get("name", None)
        self.description = entity.get("description", None)
        self.parent_id = entity.get("parentId", None)
        self.etag = entity.get("etag", None)
        self.created_on = entity.get("createdOn", None)
        self.created_by = entity.get("createdBy", None)
        self.modified_on = entity.get("modifiedOn", None)
        self.modified_by = entity.get("modifiedBy", None)
        self.version_number = entity.get("versionNumber", None)
        self.version_label = entity.get("versionLabel", None)
        self.version_comment = entity.get("versionComment", None)
        self.is_latest_version = entity.get("isLatestVersion", None)
        self.is_search_enabled = entity.get("isSearchEnabled", False)
        self.scope_ids = [item for item in entity.get("scopeIds", [])]

        if set_annotations:
            self.annotations = Annotations.from_dict(entity.get("annotations", {}))

        return self

    def to_synapse_request(self):
        """Converts the request to a request expected of the Synapse REST API."""

        entity = {
            "name": self.name,
            "description": self.description,
            "id": self.id,
            "etag": self.etag,
            "createdOn": self.created_on,
            "modifiedOn": self.modified_on,
            "createdBy": self.created_by,
            "modifiedBy": self.modified_by,
            "parentId": self.parent_id,
            "concreteType": concrete_types.SUBMISSION_VIEW,
            "versionNumber": self.version_number,
            "versionLabel": self.version_label,
            "versionComment": self.version_comment,
            "isLatestVersion": self.is_latest_version,
            "columnIds": (
                [
                    column.id
                    for column in self._last_persistent_instance.columns.values()
                ]
                if self._last_persistent_instance
                and self._last_persistent_instance.columns
                else []
            ),
            "isSearchEnabled": self.is_search_enabled,
            "scopeIds": ([item for item in self.scope_ids] if self.scope_ids else []),
        }
        delete_none_keys(entity)
        result = {
            "entity": entity,
        }
        delete_none_keys(result)
        return result

Functions

store_async async

store_async(dry_run: bool = False, *, job_timeout: int = 600, synapse_client: Optional[Synapse] = None) -> Self

Store information about a SubmissionView including the annotations, columns, and scope. Updates to the scope_ids attribute will be cause the rows of the view to be updated. scope_ids is a list of evaluation queues that the view is associated with.

PARAMETER	DESCRIPTION
dry_run	If True, will not actually store the table but will log to the console what would have been stored. TYPE: bool DEFAULT: False
job_timeout	The maximum amount of time to wait for a job to complete. This is used when updating the table schema. If the timeout is reached a SynapseTimeoutError will be raised. The default is 600 seconds TYPE: int DEFAULT: 600
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
Self	The SubmissionView instance stored in synapse.

Create a new submission view.

 

import asyncio
from synapseclient import Synapse
from synapseclient.models import SubmissionView

syn = Synapse()
syn.login()

async def main():
    submission_view = SubmissionView(
        name="My Submission View",
        scope_ids=["syn9876543"],  # ID of an evaluation queue
        parent_id="syn1234",
    )
    submission_view = await submission_view.store_async()
    print(f"Created Submission View with ID: {submission_view.id}")

asyncio.run(main())

Update the scope of an existing submission view.

 

import asyncio
from synapseclient import Synapse
from synapseclient.models import SubmissionView

syn = Synapse()
syn.login()

async def main():
    submission_view = await SubmissionView(id="syn1234").get_async()
    submission_view.scope_ids = ["syn9876543", "syn8765432"]  # Add a second evaluation queue
    submission_view = await submission_view.store_async()
    print("Updated Submission View scope.")

asyncio.run(main())

Source code in synapseclient/models/submissionview.py

async def store_async(
    self,
    dry_run: bool = False,
    *,
    job_timeout: int = 600,
    synapse_client: Optional[Synapse] = None,
) -> "Self":
    """
    Store information about a SubmissionView including the annotations, columns,
    and scope. Updates to the `scope_ids` attribute will be cause the rows of the
    view to be updated. `scope_ids` is a list of evaluation queues that the view is
    associated with.

    Arguments:
        dry_run: If True, will not actually store the table but will log to
            the console what would have been stored.
        job_timeout: The maximum amount of time to wait for a job to complete.
            This is used when updating the table schema. If the timeout
            is reached a `SynapseTimeoutError` will be raised.
            The default is 600 seconds
        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 SubmissionView instance stored in synapse.

    Example: Create a new submission view.
         

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import SubmissionView

        syn = Synapse()
        syn.login()

        async def main():
            submission_view = SubmissionView(
                name="My Submission View",
                scope_ids=["syn9876543"],  # ID of an evaluation queue
                parent_id="syn1234",
            )
            submission_view = await submission_view.store_async()
            print(f"Created Submission View with ID: {submission_view.id}")

        asyncio.run(main())
        ```

    Example: Update the scope of an existing submission view.
         

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import SubmissionView

        syn = Synapse()
        syn.login()

        async def main():
            submission_view = await SubmissionView(id="syn1234").get_async()
            submission_view.scope_ids = ["syn9876543", "syn8765432"]  # Add a second evaluation queue
            submission_view = await submission_view.store_async()
            print("Updated Submission View scope.")

        asyncio.run(main())
        ```
    """
    return await super().store_async(
        dry_run=dry_run,
        job_timeout=job_timeout,
        synapse_client=synapse_client,
    )

get_async async

get_async(include_columns: bool = True, include_activity: bool = False, *, synapse_client: Optional[Synapse] = None) -> Self

Retrieve a SubmissionView from Synapse.

PARAMETER	DESCRIPTION
include_columns	Whether to include the columns in the returned view. Defaults to True. This is useful when updating the columns. TYPE: bool DEFAULT: True
include_activity	Whether to include the activity in the returned view. Defaults to False. Setting this to True will include the activity record associated with this view. 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
Self	The SubmissionView instance retrieved from Synapse.

Retrieving a submission view by ID.

 

import asyncio
from synapseclient import Synapse
from synapseclient.models import SubmissionView

syn = Synapse()
syn.login()

async def main():
    submission_view = await SubmissionView(id="syn1234").get_async()
    print(submission_view)

asyncio.run(main())

Getting a submission view with its columns and activity.

 

import asyncio
from synapseclient import Synapse
from synapseclient.models import SubmissionView

syn = Synapse()
syn.login()

async def main():
    submission_view = await SubmissionView(id="syn1234").get_async(
        include_columns=True,
        include_activity=True
    )
    print(submission_view.columns)
    print(submission_view.activity)

asyncio.run(main())

Source code in synapseclient/models/submissionview.py

async def get_async(
    self,
    include_columns: bool = True,
    include_activity: bool = False,
    *,
    synapse_client: Optional[Synapse] = None,
) -> "Self":
    """Retrieve a SubmissionView from Synapse.

    Arguments:
        include_columns: Whether to include the columns in the returned view.
            Defaults to True. This is useful when updating the columns.
        include_activity: Whether to include the activity in the returned view.
            Defaults to False. Setting this to True will include the activity
            record associated with this view.
        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 SubmissionView instance retrieved from Synapse.

    Example: Retrieving a submission view by ID.
         

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import SubmissionView

        syn = Synapse()
        syn.login()

        async def main():
            submission_view = await SubmissionView(id="syn1234").get_async()
            print(submission_view)

        asyncio.run(main())
        ```

    Example: Getting a submission view with its columns and activity.
         

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import SubmissionView

        syn = Synapse()
        syn.login()

        async def main():
            submission_view = await SubmissionView(id="syn1234").get_async(
                include_columns=True,
                include_activity=True
            )
            print(submission_view.columns)
            print(submission_view.activity)

        asyncio.run(main())
        ```
    """
    return await super().get_async(
        include_columns=include_columns,
        include_activity=include_activity,
        synapse_client=synapse_client,
    )

delete_async async

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

Delete a SubmissionView from Synapse.

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

Delete a submission view.

 

import asyncio
from synapseclient import Synapse
from synapseclient.models import SubmissionView

syn = Synapse()
syn.login()

async def main():
    submission_view = SubmissionView(id="syn1234")
    await submission_view.delete_async()
    print("Deleted Submission View.")

asyncio.run(main())

Source code in synapseclient/models/submissionview.py

async def delete_async(self, *, synapse_client: Optional[Synapse] = None) -> None:
    """Delete a SubmissionView from Synapse.

    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: Delete a submission view.
         

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import SubmissionView

        syn = Synapse()
        syn.login()

        async def main():
            submission_view = SubmissionView(id="syn1234")
            await submission_view.delete_async()
            print("Deleted Submission View.")

        asyncio.run(main())
        ```
    """
    return await super().delete_async(synapse_client=synapse_client)

query_async async staticmethod

query_async(query: str, include_row_id_and_row_version: bool = True, convert_to_datetime: bool = False, download_location=None, quote_character='"', escape_character='\\', line_end=str(linesep), separator=',', header=True, *, synapse_client: Optional[Synapse] = None, **kwargs) -> Union[DATA_FRAME_TYPE, str]

Query for data on a table stored in Synapse. The results will always be returned as a Pandas DataFrame unless you specify a download_location in which case the results will be downloaded to that location. There are a number of arguments that you may pass to this function depending on if you are getting the results back as a DataFrame or downloading the results to a file.

PARAMETER	DESCRIPTION
query	The query to run. The query must be valid syntax that Synapse can understand. See this document that describes the expected syntax of the query: https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/web/controller/TableExamples.html TYPE: str
include_row_id_and_row_version	If True the ROW_ID and ROW_VERSION columns will be returned in the DataFrame. These columns are required if using the query results to update rows in the table. These columns are the primary keys used by Synapse to uniquely identify rows in the table. TYPE: bool DEFAULT: True
convert_to_datetime	(DataFrame only) If set to True, will convert all Synapse DATE columns from UNIX timestamp integers into UTC datetime objects TYPE: bool DEFAULT: False
download_location	(CSV Only) If set to a path the results will be downloaded to that directory. The results will be downloaded as a CSV file. A path to the downloaded file will be returned instead of a DataFrame. DEFAULT: None
quote_character	(CSV Only) The character to use to quote fields. The default is a double quote. DEFAULT: '"'
escape_character	(CSV Only) The character to use to escape special characters. The default is a backslash. DEFAULT: '\\'
line_end	(CSV Only) The character to use to end a line. The default is the system's line separator. DEFAULT: str(linesep)
separator	(CSV Only) The character to use to separate fields. The default is a comma. DEFAULT: ','
header	(CSV Only) If set to True the first row will be used as the header row. The default is True. DEFAULT: True
**kwargs	(DataFrame only) Additional keyword arguments to pass to pandas.read_csv. See https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html for complete list of supported arguments. This is exposed as internally the query downloads a CSV from Synapse and then loads it into a dataframe. 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

RETURNS	DESCRIPTION
Union[DATA_FRAME_TYPE, str]	The results of the query as a Pandas DataFrame or a path to the downloaded
Union[DATA_FRAME_TYPE, str]	query results if download_location is set.

Querying for data

This example shows how you may query for data in a table and print out the results.

import asyncio
from synapseclient import Synapse
from synapseclient.models import query_async

syn = Synapse()
syn.login()

async def main():
    results = await query_async(query="SELECT * FROM syn1234")
    print(results)

asyncio.run(main())

Source code in synapseclient/models/mixins/table_components.py

@staticmethod
async def query_async(
    query: str,
    include_row_id_and_row_version: bool = True,
    convert_to_datetime: bool = False,
    download_location=None,
    quote_character='"',
    escape_character="\\",
    line_end=str(os.linesep),
    separator=",",
    header=True,
    *,
    synapse_client: Optional[Synapse] = None,
    **kwargs,
) -> Union["DATA_FRAME_TYPE", str]:
    """Query for data on a table stored in Synapse. The results will always be
    returned as a Pandas DataFrame unless you specify a `download_location` in which
    case the results will be downloaded to that location. There are a number of
    arguments that you may pass to this function depending on if you are getting
    the results back as a DataFrame or downloading the results to a file.

    Arguments:
        query: The query to run. The query must be valid syntax that Synapse can
            understand. See this document that describes the expected syntax of the
            query:
            <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/web/controller/TableExamples.html>
        include_row_id_and_row_version: If True the `ROW_ID` and `ROW_VERSION`
            columns will be returned in the DataFrame. These columns are required
            if using the query results to update rows in the table. These columns
            are the primary keys used by Synapse to uniquely identify rows in the
            table.
        convert_to_datetime: (DataFrame only) If set to True, will convert all
            Synapse DATE columns from UNIX timestamp integers into UTC datetime
            objects

        download_location: (CSV Only) If set to a path the results will be
            downloaded to that directory. The results will be downloaded as a CSV
            file. A path to the downloaded file will be returned instead of a
            DataFrame.

        quote_character: (CSV Only) The character to use to quote fields. The
            default is a double quote.

        escape_character: (CSV Only) The character to use to escape special
            characters. The default is a backslash.

        line_end: (CSV Only) The character to use to end a line. The default is
            the system's line separator.

        separator: (CSV Only) The character to use to separate fields. The default
            is a comma.

        header: (CSV Only) If set to True the first row will be used as the header
            row. The default is True.

        **kwargs: (DataFrame only) Additional keyword arguments to pass to
            pandas.read_csv. See
            <https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html>
            for complete list of supported arguments. This is exposed as
            internally the query downloads a CSV from Synapse and then loads
            it into a dataframe.
        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 results of the query as a Pandas DataFrame or a path to the downloaded
        query results if `download_location` is set.

    Example: Querying for data
        This example shows how you may query for data in a table and print out the
        results.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import query_async

        syn = Synapse()
        syn.login()

        async def main():
            results = await query_async(query="SELECT * FROM syn1234")
            print(results)

        asyncio.run(main())
        ```
    """

    client = Synapse.get_client(synapse_client=synapse_client)

    if client.logger.isEnabledFor(logging.DEBUG):
        client.logger.debug(f"Running query: {query}")

    # TODO: Implementation should not download CSV to disk, instead the ideal
    # solution will load the result into BytesIO and then pass that to
    # pandas.read_csv. During implmentation a determination on how large of a CSV
    # that can be loaded from Memory will be needed. When that limit is reached we
    # should continue to force the download of those results to disk.
    result, csv_path = await _table_query(
        query=query,
        include_row_id_and_row_version=include_row_id_and_row_version,
        quote_char=quote_character,
        escape_char=escape_character,
        line_end=line_end,
        separator=separator,
        header=header,
        download_location=download_location,
    )

    if download_location:
        return csv_path

    date_columns = []
    list_columns = []
    dtype = {}

    if result.headers is not None:
        for column in result.headers:
            if column.column_type == "STRING":
                # we want to identify string columns so that pandas doesn't try to
                # automatically parse strings in a string column to other data types
                dtype[column.name] = str
            elif column.column_type in LIST_COLUMN_TYPES:
                list_columns.append(column.name)
            elif column.column_type == "DATE" and convert_to_datetime:
                date_columns.append(column.name)

    return csv_to_pandas_df(
        filepath=csv_path,
        separator=separator or DEFAULT_SEPARATOR,
        quote_char=quote_character or DEFAULT_QUOTE_CHARACTER,
        escape_char=escape_character or DEFAULT_ESCAPSE_CHAR,
        row_id_and_version_in_index=False,
        date_columns=date_columns if date_columns else None,
        list_columns=list_columns if list_columns else None,
        **kwargs,
    )

query_part_mask_async async staticmethod

query_part_mask_async(query: str, part_mask: int, *, synapse_client: Optional[Synapse] = None, **kwargs) -> QueryResultOutput

Query for data on a table stored in Synapse. This is a more advanced use case of the query function that allows you to determine what addiitional metadata about the table or query should also be returned. If you do not need this additional information then you are better off using the query function.

The query for this method uses this Rest API: https://rest-docs.synapse.org/rest/POST/entity/id/table/query/async/start.html

PARAMETER	DESCRIPTION
query	The query to run. The query must be valid syntax that Synapse can understand. See this document that describes the expected syntax of the query: https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/web/controller/TableExamples.html TYPE: str
part_mask	The bitwise OR of the part mask values you want to return in the results. The following list of part masks are implemented to be returned in the results: Query Results (queryResults) = 0x1 Query Count (queryCount) = 0x2 The sum of the file sizes (sumFileSizesBytes) = 0x40 The last updated on date of the table (lastUpdatedOn) = 0x80 TYPE: int
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
QueryResultOutput	The results of the query as a QueryResultOutput object.

Querying for data with a part mask

This example shows how to use the bitwise OR of Python to combine the part mask values and then use that to query for data in a table and print out the results.

In this case we are getting the results of the query, the count of rows, and the last updated on date of the table.

import asyncio
from synapseclient import Synapse
from synapseclient.models import query_part_mask_async

syn = Synapse()
syn.login()

QUERY_RESULTS = 0x1
QUERY_COUNT = 0x2
LAST_UPDATED_ON = 0x80

# Combine the part mask values using bitwise OR
part_mask = QUERY_RESULTS | QUERY_COUNT | LAST_UPDATED_ON


async def main():
    result = await query_part_mask_async(query="SELECT * FROM syn1234", part_mask=part_mask)
    print(result)

asyncio.run(main())

Source code in synapseclient/models/mixins/table_components.py

@staticmethod
async def query_part_mask_async(
    query: str,
    part_mask: int,
    *,
    synapse_client: Optional[Synapse] = None,
    **kwargs,
) -> "QueryResultOutput":
    """Query for data on a table stored in Synapse. This is a more advanced use case
    of the `query` function that allows you to determine what addiitional metadata
    about the table or query should also be returned. If you do not need this
    additional information then you are better off using the `query` function.

    The query for this method uses this Rest API:
    <https://rest-docs.synapse.org/rest/POST/entity/id/table/query/async/start.html>

    Arguments:
        query: The query to run. The query must be valid syntax that Synapse can
            understand. See this document that describes the expected syntax of the
            query:
            <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/web/controller/TableExamples.html>
        part_mask: The bitwise OR of the part mask values you want to return in the
            results. The following list of part masks are implemented to be returned
            in the results:

            - Query Results (queryResults) = 0x1
            - Query Count (queryCount) = 0x2
            - The sum of the file sizes (sumFileSizesBytes) = 0x40
            - The last updated on date of the table (lastUpdatedOn) = 0x80

        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 results of the query as a QueryResultOutput object.

    Example: Querying for data with a part mask
        This example shows how to use the bitwise `OR` of Python to combine the
        part mask values and then use that to query for data in a table and print
        out the results.

        In this case we are getting the results of the query, the count of rows, and
        the last updated on date of the table.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import query_part_mask_async

        syn = Synapse()
        syn.login()

        QUERY_RESULTS = 0x1
        QUERY_COUNT = 0x2
        LAST_UPDATED_ON = 0x80

        # Combine the part mask values using bitwise OR
        part_mask = QUERY_RESULTS | QUERY_COUNT | LAST_UPDATED_ON


        async def main():
            result = await query_part_mask_async(query="SELECT * FROM syn1234", part_mask=part_mask)
            print(result)

        asyncio.run(main())
        ```
    """
    loop = asyncio.get_event_loop()

    client = Synapse.get_client(synapse_client=synapse_client)
    client.logger.info(f"Running query: {query}")
    limit = kwargs.get("limit", None)
    offset = kwargs.get("offset", None)

    results = await _table_query(
        query=query,
        results_as="rowset",
        part_mask=part_mask,
        limit=limit,
        offset=offset,
    )

    as_df = await loop.run_in_executor(
        None,
        lambda: _rowset_to_pandas_df(
            query_result_bundle=results,
            synapse=client,
            row_id_and_version_in_index=False,
        ),
    )
    return QueryResultOutput.fill_from_dict(
        result=as_df,
        data={
            "count": results.query_count,
            "last_updated_on": results.last_updated_on,
            "sum_file_sizes": results.sum_file_sizes,
        },
    )

snapshot_async async

snapshot_async(*, comment: Optional[str] = None, label: Optional[str] = None, include_activity: bool = True, associate_activity_to_new_version: bool = True, synapse_client: Optional[Synapse] = None) -> TableUpdateTransaction

Creates a snapshot of the SubmissionView entity. Synapse handles snapshot creation differently for Table- and View-like entities. View snapshots are created using the asyncronous job API.

Making a snapshot of a view allows you to create an immutable version of the view at the time of the snapshot. This is useful to create checkpoints in time that you may go back and reference, or use in a publication. Snapshots are immutable and cannot be changed. They may only be deleted.

PARAMETER	DESCRIPTION
comment	A unique comment to associate with the snapshot. TYPE: Optional[str] DEFAULT: None
label	A unique label to associate with the snapshot. If this is not a unique label an exception will be raised when you store this to Synapse. TYPE: Optional[str] DEFAULT: None
include_activity	If True the activity will be included in snapshot if it exists. In order to include the activity, the activity must have already been stored in Synapse by using the activity attribute on the View and calling the store_async() method on the View instance. Adding an activity to a snapshot of a table is meant to capture the provenance of the data at the time of the snapshot. Defaults to True. TYPE: bool DEFAULT: True
associate_activity_to_new_version	If True the activity will be associated with the new version of the table. If False the activity will not be associated with the new version of the table. Defaults to True. TYPE: bool DEFAULT: True
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
TableUpdateTransaction	A TableUpdateTransaction object which includes the version number of the snapshot.

Creating a snapshot of a view with an activity

Create a snapshot of a view and include the activity. The activity must have been stored in Synapse by using the activity attribute on the SubmissionView and calling the store_async() method on the SubmissionView instance. Adding an activity to a snapshot of a view is meant to capture the provenance of the data at the time of the snapshot.

import asyncio
from synapseclient import Synapse
from synapseclient.models import SubmissionView, Activity, UsedURL

syn = Synapse()
syn.login()

async def main():
    view = await SubmissionView(id="syn4567").get_async()
    view.activity = Activity(
        name="Activity for snapshot",
        used=[UsedURL(name="Data Source", url="https://example.org")]
    )
    await view.store_async() # Store the activity

    snapshot = await view.snapshot_async(
        label="Q1 2025",
        comment="Submissions reviewed in Lab A",
        include_activity=True,
        associate_activity_to_new_version=True
    )
    print(snapshot)

asyncio.run(main())

Creating a snapshot of a view without an activity

Create a snapshot of a view without including the activity. This is used in cases where we do not have any Provenance to associate with the snapshot and we do not want to persist any activity that may be present on the view to the new version of the view.

import asyncio
from synapseclient import Synapse
from synapseclient.models import SubmissionView

syn = Synapse()
syn.login()

async def main():
    view = await SubmissionView(id="syn4567").get_async()
    snapshot = await view.snapshot_async(
        label="Q1 2025",
        comment="Submissions reviewed in Lab A",
        include_activity=False,
        associate_activity_to_new_version=False
    )
    print(snapshot)

asyncio.run(main())

Source code in synapseclient/models/submissionview.py

async def snapshot_async(
    self,
    *,
    comment: Optional[str] = None,
    label: Optional[str] = None,
    include_activity: bool = True,
    associate_activity_to_new_version: bool = True,
    synapse_client: Optional[Synapse] = None,
) -> "TableUpdateTransaction":
    """Creates a snapshot of the `SubmissionView` entity.
    Synapse handles snapshot creation differently for `Table`- and `View`-like
    entities. `View` snapshots are created using the asyncronous job API.

    Making a snapshot of a view allows you to create an immutable version of the
    view at the time of the snapshot. This is useful to create checkpoints in time
    that you may go back and reference, or use in a publication. Snapshots are
    immutable and cannot be changed. They may only be deleted.

    Arguments:
        comment: A unique comment to associate with the snapshot.
        label: A unique label to associate with the snapshot. If this is not a
            unique label an exception will be raised when you store this to Synapse.
        include_activity: If True the activity will be included in snapshot if it
            exists. In order to include the activity, the activity must have already
            been stored in Synapse by using the `activity` attribute on the View
            and calling the `store_async()` method on the View instance. Adding an
            activity to a snapshot of a table is meant to capture the provenance of
            the data at the time of the snapshot. Defaults to True.
        associate_activity_to_new_version: If True the activity will be associated
            with the new version of the table. If False the activity will not be
            associated with the new version of the table. Defaults to True.
        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:
        A `TableUpdateTransaction` object which includes the version number of the snapshot.

    Example: Creating a snapshot of a view with an activity
        Create a snapshot of a view and include the activity. The activity must have been stored in
        Synapse by using the `activity` attribute on the SubmissionView and calling the `store_async()`
        method on the SubmissionView instance. Adding an activity to a snapshot of a view is meant
        to capture the provenance of the data at the time of the snapshot.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import SubmissionView, Activity, UsedURL

        syn = Synapse()
        syn.login()

        async def main():
            view = await SubmissionView(id="syn4567").get_async()
            view.activity = Activity(
                name="Activity for snapshot",
                used=[UsedURL(name="Data Source", url="https://example.org")]
            )
            await view.store_async() # Store the activity

            snapshot = await view.snapshot_async(
                label="Q1 2025",
                comment="Submissions reviewed in Lab A",
                include_activity=True,
                associate_activity_to_new_version=True
            )
            print(snapshot)

        asyncio.run(main())
        ```

    Example: Creating a snapshot of a view without an activity
        Create a snapshot of a view without including the activity. This is used in
        cases where we do not have any Provenance to associate with the snapshot and
        we do not want to persist any activity that may be present on the view to
        the new version of the view.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import SubmissionView

        syn = Synapse()
        syn.login()

        async def main():
            view = await SubmissionView(id="syn4567").get_async()
            snapshot = await view.snapshot_async(
                label="Q1 2025",
                comment="Submissions reviewed in Lab A",
                include_activity=False,
                associate_activity_to_new_version=False
            )
            print(snapshot)

        asyncio.run(main())
        ```
    """
    return await super().snapshot_async(
        comment=comment,
        label=label,
        include_activity=include_activity,
        associate_activity_to_new_version=associate_activity_to_new_version,
        synapse_client=synapse_client,
    )

add_column

add_column(column: Union[Column, List[Column]], index: int = None) -> None

Add column(s) to the table. Note that this does not store the column(s) in Synapse. You must call the .store() function on this table class instance to store the column(s) in Synapse. This is a convenience function to eliminate the need to manually add the column(s) to the dictionary.

This function will add an item to the .columns attribute of this class instance. .columns is a dictionary where the key is the name of the column and the value is the Column object.

PARAMETER	DESCRIPTION
column	The column(s) to add, may be a single Column object or a list of Column objects. TYPE: Union[Column, List[Column]]
index	The index to insert the column at. If not passed in the column will be added to the end of the list. TYPE: int DEFAULT: None

RETURNS	DESCRIPTION
None	None

Adding a single column

This example shows how you may add a single column to a table and then store the change back in Synapse.

from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

table = Table(
    id="syn1234"
).get(include_columns=True)

table.add_column(
    Column(name="my_column", column_type=ColumnType.STRING)
)
table.store()

Adding multiple columns

This example shows how you may add multiple columns to a table and then store the change back in Synapse.

from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

table = Table(
    id="syn1234"
).get(include_columns=True)

table.add_column([
    Column(name="my_column", column_type=ColumnType.STRING),
    Column(name="my_column2", column_type=ColumnType.INTEGER),
])
table.store()

Adding a column at a specific index

This example shows how you may add a column at a specific index to a table and then store the change back in Synapse. If the index is out of bounds the column will be added to the end of the list.

from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

table = Table(
    id="syn1234"
).get(include_columns=True)

table.add_column(
    Column(name="my_column", column_type=ColumnType.STRING),
    # Add the column at the beginning of the list
    index=0
)
table.store()

Adding a single column (async)

This example shows how you may add a single column to a table and then store the change back in Synapse.

import asyncio
from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

async def main():
    table = await Table(
        id="syn1234"
    ).get_async(include_columns=True)

    table.add_column(
        Column(name="my_column", column_type=ColumnType.STRING)
    )
    await table.store_async()

asyncio.run(main())

Adding multiple columns (async)

This example shows how you may add multiple columns to a table and then store the change back in Synapse.

import asyncio
from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

async def main():
    table = await Table(
        id="syn1234"
    ).get_async(include_columns=True)

    table.add_column([
        Column(name="my_column", column_type=ColumnType.STRING),
        Column(name="my_column2", column_type=ColumnType.INTEGER),
    ])
    await table.store_async()

asyncio.run(main())

Adding a column at a specific index (async)

This example shows how you may add a column at a specific index to a table and then store the change back in Synapse. If the index is out of bounds the column will be added to the end of the list.

import asyncio
from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

async def main():
    table = await Table(
        id="syn1234"
    ).get_async(include_columns=True)

    table.add_column(
        Column(name="my_column", column_type=ColumnType.STRING),
        # Add the column at the beginning of the list
        index=0
    )
    await table.store_async()

asyncio.run(main())

Source code in synapseclient/models/mixins/table_components.py

def add_column(
    self, column: Union["Column", List["Column"]], index: int = None
) -> None:
    """Add column(s) to the table. Note that this does not store the column(s) in
    Synapse. You must call the `.store()` function on this table class instance to
    store the column(s) in Synapse. This is a convenience function to eliminate
    the need to manually add the column(s) to the dictionary.


    This function will add an item to the `.columns` attribute of this class
    instance. `.columns` is a dictionary where the key is the name of the column
    and the value is the Column object.

    Arguments:
        column: The column(s) to add, may be a single Column object or a list of
            Column objects.
        index: The index to insert the column at. If not passed in the column will
            be added to the end of the list.

    Returns:
        None

    Example: Adding a single column
        This example shows how you may add a single column to a table and then store
        the change back in Synapse.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        table = Table(
            id="syn1234"
        ).get(include_columns=True)

        table.add_column(
            Column(name="my_column", column_type=ColumnType.STRING)
        )
        table.store()
        ```


    Example: Adding multiple columns
        This example shows how you may add multiple columns to a table and then store
        the change back in Synapse.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        table = Table(
            id="syn1234"
        ).get(include_columns=True)

        table.add_column([
            Column(name="my_column", column_type=ColumnType.STRING),
            Column(name="my_column2", column_type=ColumnType.INTEGER),
        ])
        table.store()
        ```

    Example: Adding a column at a specific index
        This example shows how you may add a column at a specific index to a table
        and then store the change back in Synapse. If the index is out of bounds the
        column will be added to the end of the list.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        table = Table(
            id="syn1234"
        ).get(include_columns=True)

        table.add_column(
            Column(name="my_column", column_type=ColumnType.STRING),
            # Add the column at the beginning of the list
            index=0
        )
        table.store()
        ```

    Example: Adding a single column (async)
        This example shows how you may add a single column to a table and then store
        the change back in Synapse.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        async def main():
            table = await Table(
                id="syn1234"
            ).get_async(include_columns=True)

            table.add_column(
                Column(name="my_column", column_type=ColumnType.STRING)
            )
            await table.store_async()

        asyncio.run(main())
        ```

    Example: Adding multiple columns (async)
        This example shows how you may add multiple columns to a table and then store
        the change back in Synapse.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        async def main():
            table = await Table(
                id="syn1234"
            ).get_async(include_columns=True)

            table.add_column([
                Column(name="my_column", column_type=ColumnType.STRING),
                Column(name="my_column2", column_type=ColumnType.INTEGER),
            ])
            await table.store_async()

        asyncio.run(main())
        ```

    Example: Adding a column at a specific index (async)
        This example shows how you may add a column at a specific index to a table
        and then store the change back in Synapse. If the index is out of bounds the
        column will be added to the end of the list.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        async def main():
            table = await Table(
                id="syn1234"
            ).get_async(include_columns=True)

            table.add_column(
                Column(name="my_column", column_type=ColumnType.STRING),
                # Add the column at the beginning of the list
                index=0
            )
            await table.store_async()

        asyncio.run(main())
        ```
    """
    if not self._last_persistent_instance:
        raise ValueError(
            "This method is only supported after interacting with Synapse via a `.get()` or `.store()` operation"
        )

    if index is not None:
        if isinstance(column, list):
            columns_to_insert = []
            for i, col in enumerate(column):
                if col.name in self.columns:
                    raise ValueError(f"Duplicate column name: {col.name}")
                columns_to_insert.append((col.name, col))
            insert_index = min(index, len(self.columns))
            self.columns = OrderedDict(
                list(self.columns.items())[:insert_index]
                + columns_to_insert
                + list(self.columns.items())[insert_index:]
            )
        else:
            if column.name in self.columns:
                raise ValueError(f"Duplicate column name: {column.name}")
            insert_index = min(index, len(self.columns))
            self.columns = OrderedDict(
                list(self.columns.items())[:insert_index]
                + [(column.name, column)]
                + list(self.columns.items())[insert_index:]
            )

    else:
        if isinstance(column, list):
            for col in column:
                if col.name in self.columns:
                    raise ValueError(f"Duplicate column name: {col.name}")
                self.columns[col.name] = col
        else:
            if column.name in self.columns:
                raise ValueError(f"Duplicate column name: {column.name}")
            self.columns[column.name] = column

reorder_column

reorder_column(name: str, index: int) -> None

Reorder a column in the table. Note that this does not store the column in Synapse. You must call the .store() function on this table class instance to store the column in Synapse. This is a convenience function to eliminate the need to manually reorder the .columns attribute dictionary.

You must ensure that the index is within the bounds of the number of columns in the table. If you pass in an index that is out of bounds the column will be added to the end of the list.

PARAMETER	DESCRIPTION
name	The name of the column to reorder. TYPE: str
index	The index to move the column to starting with 0. TYPE: int

RETURNS	DESCRIPTION
None	None

Reordering a column

This example shows how you may reorder a column in a table and then store the change back in Synapse.

from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

table = Table(
    id="syn1234"
).get(include_columns=True)

# Move the column to the beginning of the list
table.reorder_column(name="my_column", index=0)
table.store()

Reordering a column (async)

This example shows how you may reorder a column in a table and then store the change back in Synapse.

import asyncio
from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table

syn = Synapse()
syn.login()

async def main():
    table = await Table(
        id="syn1234"
    ).get_async(include_columns=True)

    # Move the column to the beginning of the list
    table.reorder_column(name="my_column", index=0)
    table.store_async()

asyncio.run(main())

Source code in synapseclient/models/mixins/table_components.py

def reorder_column(self, name: str, index: int) -> None:
    """Reorder a column in the table. Note that this does not store the column in
    Synapse. You must call the `.store()` function on this table class instance to
    store the column in Synapse. This is a convenience function to eliminate
    the need to manually reorder the `.columns` attribute dictionary.

    You must ensure that the index is within the bounds of the number of columns in
    the table. If you pass in an index that is out of bounds the column will be
    added to the end of the list.

    Arguments:
        name: The name of the column to reorder.
        index: The index to move the column to starting with 0.

    Returns:
        None

    Example: Reordering a column
        This example shows how you may reorder a column in a table and then store
        the change back in Synapse.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        table = Table(
            id="syn1234"
        ).get(include_columns=True)

        # Move the column to the beginning of the list
        table.reorder_column(name="my_column", index=0)
        table.store()
        ```


    Example: Reordering a column (async)
        This example shows how you may reorder a column in a table and then store
        the change back in Synapse.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import Column, ColumnType, Table

        syn = Synapse()
        syn.login()

        async def main():
            table = await Table(
                id="syn1234"
            ).get_async(include_columns=True)

            # Move the column to the beginning of the list
            table.reorder_column(name="my_column", index=0)
            table.store_async()

        asyncio.run(main())
        ```
    """
    if not self._last_persistent_instance:
        raise ValueError(
            "This method is only supported after interacting with Synapse via a `.get()` or `.store()` operation"
        )

    column_to_reorder = self.columns.pop(name, None)
    if index >= len(self.columns):
        self.columns[name] = column_to_reorder
        return self

    self.columns = OrderedDict(
        list(self.columns.items())[:index]
        + [(name, column_to_reorder)]
        + list(self.columns.items())[index:]
    )

delete_column

delete_column(name: str) -> None

Mark a column for deletion. Note that this does not delete the column from Synapse. You must call the .store() function on this table class instance to delete the column from Synapse. This is a convenience function to eliminate the need to manually delete the column from the dictionary and add it to the ._columns_to_delete attribute.

PARAMETER	DESCRIPTION
name	The name of the column to delete. TYPE: str

RETURNS	DESCRIPTION
None	None

Deleting a column

This example shows how you may delete a column from a table and then store the change back in Synapse.

from synapseclient import Synapse
from synapseclient.models import Table

syn = Synapse()
syn.login()

table = Table(
    id="syn1234"
).get(include_columns=True)

table.delete_column(name="my_column")
table.store()

Deleting a column (async)

This example shows how you may delete a column from a table and then store the change back in Synapse.

import asyncio
from synapseclient import Synapse
from synapseclient.models import Table

syn = Synapse()
syn.login()

async def main():
    table = await Table(
        id="syn1234"
    ).get_async(include_columns=True)

    table.delete_column(name="my_column")
    table.store_async()

asyncio.run(main())

Source code in synapseclient/models/mixins/table_components.py

def delete_column(self, name: str) -> None:
    """
    Mark a column for deletion. Note that this does not delete the column from
    Synapse. You must call the `.store()` function on this table class instance to
    delete the column from Synapse. This is a convenience function to eliminate
    the need to manually delete the column from the dictionary and add it to the
    `._columns_to_delete` attribute.

    Arguments:
        name: The name of the column to delete.

    Returns:
        None

    Example: Deleting a column
        This example shows how you may delete a column from a table and then store
        the change back in Synapse.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Table

        syn = Synapse()
        syn.login()

        table = Table(
            id="syn1234"
        ).get(include_columns=True)

        table.delete_column(name="my_column")
        table.store()
        ```

    Example: Deleting a column (async)
        This example shows how you may delete a column from a table and then store
        the change back in Synapse.

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.models import Table

        syn = Synapse()
        syn.login()

        async def main():
            table = await Table(
                id="syn1234"
            ).get_async(include_columns=True)

            table.delete_column(name="my_column")
            table.store_async()

        asyncio.run(main())
        ```
    """
    if not self._last_persistent_instance:
        raise ValueError(
            "This method is only supported after interacting with Synapse via a `.get()` or `.store()` operation"
        )
    if not self.columns:
        raise ValueError(
            "There are no columns. Make sure you use the `include_columns` parameter in the `.get()` method."
        )

    column_to_delete = self.columns.get(name, None)
    if not column_to_delete:
        raise ValueError(f"Column with name {name} does not exist in the table.")

    self._columns_to_delete[column_to_delete.id] = column_to_delete
    self.columns.pop(column_to_delete.name, None)

get_acl_async async

get_acl_async(principal_id: int = None, check_benefactor: bool = True, *, synapse_client: Optional[Synapse] = None) -> List[str]

Get the ACL that a user or group has on an Entity.

Note: If the entity does not have local sharing settings, or ACL set directly on it, this will look up the ACL on the benefactor of the entity. The benefactor is the entity that the current entity inherits its permissions from. The benefactor is usually the parent entity, but it can be any ancestor in the hierarchy. For example, a newly created Project will be its own benefactor, while a new FileEntity's benefactor will start off as its containing Project or Folder. If the entity already has local sharing settings, the benefactor would be itself.

PARAMETER	DESCRIPTION
principal_id	Identifier of a user or group (defaults to PUBLIC users) TYPE: int DEFAULT: None
check_benefactor	If True (default), check the benefactor for the entity to get the ACL. If False, only check the entity itself. This is useful for checking the ACL of an entity that has local sharing settings, but you want to check the ACL of the entity itself and not the benefactor it may inherit from. TYPE: bool DEFAULT: True
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
List[str]	An array containing some combination of ['READ', 'UPDATE', 'CREATE', 'DELETE', 'DOWNLOAD', 'MODERATE', 'CHANGE_PERMISSIONS', 'CHANGE_SETTINGS'] or an empty array

Source code in synapseclient/models/mixins/access_control.py

async def get_acl_async(
    self,
    principal_id: int = None,
    check_benefactor: bool = True,
    *,
    synapse_client: Optional[Synapse] = None,
) -> List[str]:
    """
    Get the [ACL][synapseclient.core.models.permission.Permissions.access_types]
    that a user or group has on an Entity.

    Note: If the entity does not have local sharing settings, or ACL set directly
    on it, this will look up the ACL on the benefactor of the entity. The
    benefactor is the entity that the current entity inherits its permissions from.
    The benefactor is usually the parent entity, but it can be any ancestor in the
    hierarchy. For example, a newly created Project will be its own benefactor,
    while a new FileEntity's benefactor will start off as its containing Project or
    Folder. If the entity already has local sharing settings, the benefactor would
    be itself.

    Arguments:
        principal_id: Identifier of a user or group (defaults to PUBLIC users)
        check_benefactor: If True (default), check the benefactor for the entity
            to get the ACL. If False, only check the entity itself.
            This is useful for checking the ACL of an entity that has local sharing
            settings, but you want to check the ACL of the entity itself and not
            the benefactor it may inherit from.
        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:
        An array containing some combination of
            ['READ', 'UPDATE', 'CREATE', 'DELETE', 'DOWNLOAD', 'MODERATE',
            'CHANGE_PERMISSIONS', 'CHANGE_SETTINGS']
            or an empty array
    """
    return await get_entity_acl_list(
        entity_id=self.id,
        principal_id=str(principal_id) if principal_id is not None else None,
        check_benefactor=check_benefactor,
        synapse_client=synapse_client,
    )

get_permissions_async async

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

Get the permissions that the caller has on an Entity.

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

RETURNS	DESCRIPTION
Permissions	A Permissions object

Using this function:

Getting permissions for a Synapse Entity

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

syn = Synapse()
syn.login()

async def main():
    permissions = await File(id="syn123").get_permissions_async()

asyncio.run(main())

Getting access types list from the Permissions object

permissions.access_types

Source code in synapseclient/models/mixins/access_control.py

async def get_permissions_async(
    self,
    *,
    synapse_client: Optional[Synapse] = None,
) -> "Permissions":
    """
    Get the [permissions][synapseclient.core.models.permission.Permissions]
    that the caller has on an Entity.

    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.

    Returns:
        A Permissions object


    Example: Using this function:
        Getting permissions for a Synapse Entity

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

        syn = Synapse()
        syn.login()

        async def main():
            permissions = await File(id="syn123").get_permissions_async()

        asyncio.run(main())
        ```

        Getting access types list from the Permissions object

        ```
        permissions.access_types
        ```
    """
    from synapseclient.core.models.permission import Permissions

    permissions_dict = await get_entity_permissions(
        entity_id=self.id,
        synapse_client=synapse_client,
    )
    return Permissions.from_dict(data=permissions_dict)

set_permissions_async async

set_permissions_async(principal_id: int = None, access_type: List[str] = None, modify_benefactor: bool = False, warn_if_inherits: bool = True, overwrite: bool = True, *, synapse_client: Optional[Synapse] = None) -> Dict[str, Union[str, list]]

Sets permission that a user or group has on an Entity. An Entity may have its own ACL or inherit its ACL from a benefactor.

PARAMETER	DESCRIPTION
principal_id	Identifier of a user or group. 273948 is for all registered Synapse users and 273949 is for public access. None implies public access. TYPE: int DEFAULT: None
access_type	Type of permission to be granted. One or more of CREATE, READ, DOWNLOAD, UPDATE, DELETE, CHANGE_PERMISSIONS. Defaults to ['READ', 'DOWNLOAD'] TYPE: List[str] DEFAULT: None
modify_benefactor	Set as True when modifying a benefactor's ACL. The term 'benefactor' is used to indicate which Entity an Entity inherits its ACL from. For example, a newly created Project will be its own benefactor, while a new FileEntity's benefactor will start off as its containing Project. If the entity already has local sharing settings the benefactor would be itself. It may also be the immediate parent, somewhere in the parent tree, or the project itself. TYPE: bool DEFAULT: False
warn_if_inherits	When modify_benefactor is True, this does not have any effect. When modify_benefactor is False, and warn_if_inherits is True, a warning log message is produced if the benefactor for the entity you passed into the function is not itself, i.e., it's the parent folder, or another entity in the parent tree. TYPE: bool DEFAULT: True
overwrite	By default this function overwrites existing permissions for the specified user. Set this flag to False to add new permissions non-destructively. TYPE: bool DEFAULT: True
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
Dict[str, Union[str, list]]	An Access Control List object matching https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/AccessControlList.html.

Setting permissions

Grant all registered users download access

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

syn = Synapse()
syn.login()

async def main():
    await File(id="syn123").set_permissions_async(principal_id=273948, access_type=['READ','DOWNLOAD'])

asyncio.run(main())

Grant the public view access

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

syn = Synapse()
syn.login()

async def main():
    await File(id="syn123").set_permissions_async(principal_id=273949, access_type=['READ'])

asyncio.run(main())

Source code in synapseclient/models/mixins/access_control.py

async def set_permissions_async(
    self,
    principal_id: int = None,
    access_type: List[str] = None,
    modify_benefactor: bool = False,
    warn_if_inherits: bool = True,
    overwrite: bool = True,
    *,
    synapse_client: Optional[Synapse] = None,
) -> Dict[str, Union[str, list]]:
    """
    Sets permission that a user or group has on an Entity.
    An Entity may have its own ACL or inherit its ACL from a benefactor.

    Arguments:
        principal_id: Identifier of a user or group. `273948` is for all
            registered Synapse users and `273949` is for public access.
            None implies public access.
        access_type: Type of permission to be granted. One or more of CREATE,
            READ, DOWNLOAD, UPDATE, DELETE, CHANGE_PERMISSIONS.

            **Defaults to ['READ', 'DOWNLOAD']**
        modify_benefactor: Set as True when modifying a benefactor's ACL. The term
            'benefactor' is used to indicate which Entity an Entity inherits its
            ACL from. For example, a newly created Project will be its own
            benefactor, while a new FileEntity's benefactor will start off as its
            containing Project. If the entity already has local sharing settings
            the benefactor would be itself. It may also be the immediate parent,
            somewhere in the parent tree, or the project itself.
        warn_if_inherits: When `modify_benefactor` is True, this does not have any
            effect. When `modify_benefactor` is False, and `warn_if_inherits` is
            True, a warning log message is produced if the benefactor for the
            entity you passed into the function is not itself, i.e., it's the
            parent folder, or another entity in the parent tree.
        overwrite: By default this function overwrites existing permissions for
            the specified user. Set this flag to False to add new permissions
            non-destructively.
        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:
        An Access Control List object matching <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/AccessControlList.html>.

    Example: Setting permissions
        Grant all registered users download access

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

        syn = Synapse()
        syn.login()

        async def main():
            await File(id="syn123").set_permissions_async(principal_id=273948, access_type=['READ','DOWNLOAD'])

        asyncio.run(main())
        ```

        Grant the public view access

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

        syn = Synapse()
        syn.login()

        async def main():
            await File(id="syn123").set_permissions_async(principal_id=273949, access_type=['READ'])

        asyncio.run(main())
        ```
    """
    if access_type is None:
        access_type = ["READ", "DOWNLOAD"]

    return await set_entity_permissions(
        entity_id=self.id,
        principal_id=str(principal_id) if principal_id is not None else None,
        access_type=access_type,
        modify_benefactor=modify_benefactor,
        warn_if_inherits=warn_if_inherits,
        overwrite=overwrite,
        synapse_client=synapse_client,
    )

---