Curator¶

API reference¶

synapseclient.models.CurationTask `dataclass` ¶

Bases: CurationTaskSynchronousProtocol

The CurationTask provides instructions for a Data Contributor on how data or metadata of a specific type should be both added to a project and curated.

Represents a Synapse CurationTask.

ATTRIBUTE	DESCRIPTION
`task_id`	The unique identifier issued to this task when it was created TYPE: `Optional[int]`
`data_type`	Will match the data type that a contributor plans to contribute TYPE: `Optional[str]`
`project_id`	The synId of the project TYPE: `Optional[str]`
`instructions`	Instructions to the data contributor TYPE: `Optional[str]`
`task_properties`	The properties of a CurationTask. This can be either FileBasedMetadataTaskProperties or RecordBasedMetadataTaskProperties. TYPE: `Optional[Union[FileBasedMetadataTaskProperties, RecordBasedMetadataTaskProperties]]`
`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`	(Read Only) The date this task was created TYPE: `Optional[str]`
`modified_on`	(Read Only) The date this task was last modified TYPE: `Optional[str]`
`created_by`	(Read Only) The ID of the user that created this task TYPE: `Optional[str]`
`modified_by`	(Read Only) The ID of the user that last modified this task TYPE: `Optional[str]`

Complete curation task workflow

from synapseclient import Synapse
from synapseclient.models import CurationTask, FileBasedMetadataTaskProperties

syn = Synapse()
syn.login()

# Create a new file-based curation task
file_properties = FileBasedMetadataTaskProperties(
    upload_folder_id="syn1234567",
    file_view_id="syn2345678"
)

task = CurationTask(
    project_id="syn9876543",
    data_type="genomics_data",
    instructions="Upload your genomics files and complete metadata",
    task_properties=file_properties
)
task = task.store()
print(f"Created task: {task.task_id}")

# Later, retrieve and update the task
existing_task = CurationTask(task_id=task.task_id).get()
existing_task.instructions = "Updated instructions with new requirements"
existing_task.store()

# List all tasks in the project
for project_task in CurationTask.list(project_id="syn9876543"):
    print(f"Task: {project_task.data_type} - {project_task.task_id}")

Source code in synapseclient/models/curation.py

@dataclass
@async_to_sync
class CurationTask(CurationTaskSynchronousProtocol):
    """
    The CurationTask provides instructions for a Data Contributor on how data or metadata
    of a specific type should be both added to a project and curated.

    Represents a [Synapse CurationTask](https://rest-docs.synapse.org/org/sagebionetworks/repo/model/curation/CurationTask.html).

    Attributes:
        task_id: The unique identifier issued to this task when it was created
        data_type: Will match the data type that a contributor plans to contribute
        project_id: The synId of the project
        instructions: Instructions to the data contributor
        task_properties: The properties of a CurationTask. This can be either
            FileBasedMetadataTaskProperties or RecordBasedMetadataTaskProperties.
        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: (Read Only) The date this task was created
        modified_on: (Read Only) The date this task was last modified
        created_by: (Read Only) The ID of the user that created this task
        modified_by: (Read Only) The ID of the user that last modified this task

    Example: Complete curation task workflow
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import CurationTask, FileBasedMetadataTaskProperties

        syn = Synapse()
        syn.login()

        # Create a new file-based curation task
        file_properties = FileBasedMetadataTaskProperties(
            upload_folder_id="syn1234567",
            file_view_id="syn2345678"
        )

        task = CurationTask(
            project_id="syn9876543",
            data_type="genomics_data",
            instructions="Upload your genomics files and complete metadata",
            task_properties=file_properties
        )
        task = task.store()
        print(f"Created task: {task.task_id}")

        # Later, retrieve and update the task
        existing_task = CurationTask(task_id=task.task_id).get()
        existing_task.instructions = "Updated instructions with new requirements"
        existing_task.store()

        # List all tasks in the project
        for project_task in CurationTask.list(project_id="syn9876543"):
            print(f"Task: {project_task.data_type} - {project_task.task_id}")
        ```
    """

    task_id: Optional[int] = None
    """The unique identifier issued to this task when it was created"""

    data_type: Optional[str] = None
    """Will match the data type that a contributor plans to contribute. The dataType must be unique within a project"""

    project_id: Optional[str] = None
    """The synId of the project"""

    instructions: Optional[str] = None
    """Instructions to the data contributor"""

    task_properties: Optional[
        Union[FileBasedMetadataTaskProperties, RecordBasedMetadataTaskProperties]
    ] = None
    """The properties of a CurationTask"""

    etag: Optional[str] = None
    """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] = None
    """(Read Only) The date this task was created"""

    modified_on: Optional[str] = None
    """(Read Only) The date this task was last modified"""

    created_by: Optional[str] = None
    """(Read Only) The ID of the user that created this task"""

    modified_by: Optional[str] = None
    """(Read Only) The ID of the user that last modified this task"""

    assignee_principal_id: Optional[str] = None
    """The principal ID of the user or team assigned to this task. Null if unassigned. For metadata
    tasks, determines the owner of the grid session. Team members can all join grid sessions
    owned by their team, while user-owned grid sessions are restricted to that user only."""

    _last_persistent_instance: Optional["CurationTask"] = 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."""

    @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
        )

    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 = replace(self)
        self._last_persistent_instance.task_properties = (
            deepcopy(self.task_properties) if self.task_properties else None
        )

    def fill_from_dict(
        self, synapse_response: Union[Dict[str, Any], Any]
    ) -> "CurationTask":
        """
        Converts a response from the REST API into this dataclass.

        Arguments:
            synapse_response: The response from the REST API.

        Returns:
            The CurationTask object.
        """
        self.task_id = (
            int(synapse_response.get("taskId", None))
            if synapse_response.get("taskId", None)
            else None
        )
        self.data_type = synapse_response.get("dataType", None)
        self.project_id = synapse_response.get("projectId", None)
        self.instructions = synapse_response.get("instructions", None)
        self.etag = synapse_response.get("etag", None)
        self.created_on = synapse_response.get("createdOn", None)
        self.modified_on = synapse_response.get("modifiedOn", None)
        self.created_by = synapse_response.get("createdBy", None)
        self.modified_by = synapse_response.get("modifiedBy", None)
        self.assignee_principal_id = synapse_response.get("assigneePrincipalId", None)

        task_properties_dict = synapse_response.get("taskProperties", None)
        if task_properties_dict is None:
            raise ValueError(
                "taskProperties was not found in the Synapse response for this CurationTask. "
                "This means it is likely an older CurationTask from before taskProperties was added. "
                "It is recommended that this task be deleted: task.delete(delete_source=False) "
                "and then recreate the task with the correct taskProperties."
            )
        self.task_properties = _create_task_properties_from_dict(task_properties_dict)

        return self

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        request_dict = {}
        request_dict["taskId"] = self.task_id
        request_dict["dataType"] = self.data_type
        request_dict["projectId"] = self.project_id
        request_dict["instructions"] = self.instructions
        request_dict["etag"] = self.etag
        request_dict["createdOn"] = self.created_on
        request_dict["modifiedOn"] = self.modified_on
        request_dict["createdBy"] = self.created_by
        request_dict["modifiedBy"] = self.modified_by
        request_dict["assigneePrincipalId"] = self.assignee_principal_id

        if self.task_properties is not None:
            request_dict["taskProperties"] = self.task_properties.to_synapse_request()

        delete_none_keys(request_dict)
        return request_dict

    async def get_async(
        self, *, synapse_client: Optional[Synapse] = None
    ) -> "CurationTask":
        """
        Gets a CurationTask from Synapse by ID.

        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:
            CurationTask: The CurationTask object.

        Raises:
            ValueError: If the CurationTask object does not have a task_id.
            ValueError: If the Synapse response does not contain taskProperties.

        Example: Get a curation task asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                task = await CurationTask(task_id=123).get_async()
                print(f"Data type: {task.data_type}")
                print(f"Instructions: {task.instructions}")

            asyncio.run(main())
            ```
        """
        if not self.task_id:
            raise ValueError("task_id is required to get a CurationTask")

        trace.get_current_span().set_attributes(
            {
                "synapse.task_id": str(self.task_id),
            }
        )

        task_result = await get_curation_task(
            task_id=self.task_id, synapse_client=synapse_client
        )
        self.fill_from_dict(synapse_response=task_result)
        self._set_last_persistent_instance()
        return self

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: (
            f"CurationTask_GetStatus: ID: {self.task_id}"
        )
    )
    async def get_status_async(
        self, *, synapse_client: Synapse | None = None
    ) -> "CurationTaskStatus":
        """
        Gets the status of this CurationTask 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.

        Returns:
            The CurationTaskStatus object.

        Raises:
            ValueError: If the CurationTask object does not have a task_id.

        Example: Get the status of a curation task asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                status = await CurationTask(task_id=123).get_status_async()
                print(status.state)

            asyncio.run(main())
            ```
        """
        if not self.task_id:
            raise ValueError("task_id is required to get a CurationTask status")

        status_result = await get_curation_task_status(
            task_id=self.task_id, synapse_client=synapse_client
        )
        return CurationTaskStatus().fill_from_dict(status_result)

    async def delete_async(
        self,
        delete_source: bool = False,
        *,
        synapse_client: Optional[Synapse] = None,
    ) -> None:
        """
        Deletes a CurationTask from Synapse.

        Arguments:
            delete_source: If True, the associated source data (EntityView or RecordSet) will also be deleted
                if the task is a FileBasedMetadataTask or RecordBasedMetadataTask respectively. Defaults to 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.

        Raises:
            ValueError: If the CurationTask object does not have a task_id.
            ValueError: If delete_source is True but the task properties are not properly set
              to identify the source to delete.

        Example: Delete a curation task asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                task = CurationTask(task_id=123)
                await task.delete_async()
                print("Task deleted successfully")

            asyncio.run(main())
            ```

        Example: Delete a curation task and its associated data source asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                task = CurationTask(task_id=123)
                await task.delete_async(delete_source=True)
                print("Task and record set deleted successfully")

            asyncio.run(main())
            ```
        """
        if not self.task_id:
            raise ValueError("task_id is required to delete a CurationTask")

        trace.get_current_span().set_attributes(
            {
                "synapse.task_id": str(self.task_id),
            }
        )

        if delete_source:
            if not self.task_properties:
                await self.get_async(synapse_client=synapse_client)

            if isinstance(self.task_properties, FileBasedMetadataTaskProperties):
                if not self.task_properties.file_view_id:
                    raise ValueError(
                        "Cannot delete Fileview: "
                        "'file_view_id' attribute is missing."
                    )
                from synapseclient.models import EntityView

                await EntityView(id=self.task_properties.file_view_id).delete_async(
                    synapse_client=synapse_client
                )

            elif isinstance(self.task_properties, RecordBasedMetadataTaskProperties):
                if not self.task_properties.record_set_id:
                    raise ValueError(
                        "Cannot delete RecordSet: "
                        "'record_set_id' attribute is missing."
                    )
                from synapseclient.models import RecordSet

                await RecordSet(id=self.task_properties.record_set_id).delete_async(
                    synapse_client=synapse_client
                )

            else:
                raise ValueError(
                    "'task_property' attribute is None. "
                    "Deletion only supports FileBasedMetadataTaskProperties or "
                    "RecordBasedMetadataTaskProperties."
                )

        await delete_curation_task(task_id=self.task_id, synapse_client=synapse_client)

    async def store_async(
        self, *, synapse_client: Optional[Synapse] = None
    ) -> "CurationTask":
        """
        Creates a new CurationTask or updates an existing one on Synapse.

        This method implements non-destructive updates. If a CurationTask with the same
        project_id and data_type exists and this instance hasn't been retrieved from
        Synapse before, it will merge the existing task data with the current instance
        before updating.

        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:
            CurationTask: The CurationTask object.

        Example: Create a new curation task asynchronously
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import CurationTask, FileBasedMetadataTaskProperties

            syn = Synapse()
            syn.login()

            async def main():
                # Create file-based task properties
                file_properties = FileBasedMetadataTaskProperties(
                    upload_folder_id="syn1234567",
                    file_view_id="syn2345678"
                )

                # Create and store the curation task
                task = CurationTask(
                    project_id="syn9876543",
                    data_type="genomics_data",
                    instructions="Upload your genomics files to the specified folder",
                    task_properties=file_properties
                )
                task = await task.store_async()
                print(f"Created task with ID: {task.task_id}")

            asyncio.run(main())
            ```
        """
        if not self.project_id:
            raise ValueError("project_id is required")
        if not self.data_type:
            raise ValueError("data_type is required")

        trace.get_current_span().set_attributes(
            {
                "synapse.data_type": self.data_type or "",
                "synapse.project_id": self.project_id or "",
                "synapse.task_id": str(self.task_id) if self.task_id else "",
            }
        )

        if (
            not self._last_persistent_instance
            and not self.task_id
            and (
                existing_task_id := await _get_existing_curation_task_id(
                    project_id=self.project_id,
                    data_type=self.data_type,
                    synapse_client=synapse_client,
                )
            )
            and (
                existing_task := await CurationTask(task_id=existing_task_id).get_async(
                    synapse_client=synapse_client
                )
            )
        ):
            merge_dataclass_entities(source=existing_task, destination=self)

        if self.task_id:
            task_result = await update_curation_task(
                task_id=self.task_id,
                curation_task=self.to_synapse_request(),
                synapse_client=synapse_client,
            )
            self.fill_from_dict(synapse_response=task_result)
            self._set_last_persistent_instance()
            return self
        else:
            if not self.project_id:
                raise ValueError("project_id is required to create a CurationTask")
            if not self.data_type:
                raise ValueError("data_type is required to create a CurationTask")
            if not self.instructions:
                raise ValueError("instructions is required to create a CurationTask")
            if not self.task_properties:
                raise ValueError("task_properties is required to create a CurationTask")

            task_result = await create_curation_task(
                curation_task=self.to_synapse_request(),
                synapse_client=synapse_client,
            )
            self.fill_from_dict(synapse_response=task_result)
            self._set_last_persistent_instance()
            return self

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: (
            f"CurationTask_UpdateStatus: ID: {self.task_id}"
        )
    )
    async def update_status_async(
        self,
        curation_task_status: "CurationTaskStatus",
        *,
        synapse_client: Synapse | None = None,
    ) -> "CurationTaskStatus":
        """
        Updates the status of this CurationTask on Synapse.

        Arguments:
            curation_task_status: The complete CurationTaskStatus object to update.
            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 updated CurationTaskStatus object.

        Raises:
            ValueError: If the CurationTask object does not have a task_id.

        Example: Update the status of a curation task asynchronously
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import (
                CurationTask,
                TaskState,
            )

            syn = Synapse()
            syn.login()

            async def main():
                task = CurationTask(task_id=123)
                current = await task.get_status_async()
                current.state = TaskState.COMPLETED
                updated = await task.update_status_async(curation_task_status=current)
                print(updated.state)

            asyncio.run(main())
            ```
        """
        if not self.task_id:
            raise ValueError("task_id is required to update a CurationTask status")

        status_result = await update_curation_task_status(
            task_id=self.task_id,
            curation_task_status=curation_task_status.to_synapse_request(),
            synapse_client=synapse_client,
        )
        return CurationTaskStatus().fill_from_dict(status_result)

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: (
            f"CurationTask_SetActiveGridSession: ID: {self.task_id}"
        )
    )
    async def set_active_grid_session_async(
        self,
        active_session_id: str,
        *,
        synapse_client: Synapse | None = None,
    ) -> "CurationTaskStatus":
        """
        Set the active grid session on this CurationTask's status by replacing
        execution_details with a GridExecutionDetails carrying the given session id.

        Arguments:
            active_session_id: The unique identifier of the active grid session to link.
            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 updated CurationTaskStatus object.

        Raises:
            ValueError: If the CurationTask object does not have a task_id.

        Example: Link a grid session to a curation task asynchronously
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import CurationTask, Grid

            syn = Synapse()
            syn.login()

            async def main():
                grid = await Grid(record_set_id="syn1234567").create_async()
                await CurationTask(task_id=123).set_active_grid_session_async(
                    active_session_id=grid.session_id
                )

            asyncio.run(main())
            ```
        """
        status = await self.get_status_async(synapse_client=synapse_client)
        status.execution_details = GridExecutionDetails(
            active_session_id=active_session_id
        )
        return await self.update_status_async(
            curation_task_status=status, synapse_client=synapse_client
        )

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: (
            f"CurationTask_SetTaskState: ID: {self.task_id}"
        )
    )
    async def set_task_state_async(
        self,
        state: "TaskState | str",
        *,
        synapse_client: Synapse | None = None,
    ) -> "CurationTaskStatus":
        """
        Set the state on this CurationTask's status.

        Does not modify execution_details. Fetches the current CurationTaskStatus
        first so the update carries a fresh etag.

        Arguments:
            state: The state to set on this task's status. Accepts a
                TaskState or a string exactly matching one of its members
                (e.g. NOT_STARTED, IN_PROGRESS, COMPLETED, CANCELED).
            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 updated CurationTaskStatus object.

        Raises:
            ValueError: If the CurationTask object does not have a task_id, or
                if state is a string that does not match a TaskState member.

        Example: Mark a curation task as completed asynchronously
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import CurationTask, TaskState

            syn = Synapse()
            syn.login()

            async def main():
                await CurationTask(task_id=123).set_task_state_async(
                    state=TaskState.COMPLETED
                )

            asyncio.run(main())
            ```

        Example: Mark a curation task as completed using a string asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                await CurationTask(task_id=123).set_task_state_async(
                    state="COMPLETED"
                )

            asyncio.run(main())
            ```
        """
        try:
            coerced_state = TaskState(state)
        except ValueError as exc:
            raise ValueError(
                f"{state!r} is not a valid TaskState. "
                f"Expected one of: {[s.value for s in TaskState]}."
            ) from exc

        status = await self.get_status_async(synapse_client=synapse_client)
        status.state = coerced_state
        return await self.update_status_async(
            curation_task_status=status, synapse_client=synapse_client
        )

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: (
            f"CurationTask_CreateGridSession: ID: {self.task_id}"
        )
    )
    async def create_grid_session_async(
        self,
        *,
        owner_principal_id: int | None = None,
        timeout: int = 120,
        synapse_client: Synapse | None = None,
    ) -> "Grid":
        """
        Create a new Grid session for this CurationTask and set it as the active session.

        Picks the Grid seed from this task's task_properties:

        - RecordBasedMetadataTaskProperties uses record_set_id
        - FileBasedMetadataTaskProperties uses an initial_query that selects from
          the file_view_id

        Always creates a new Grid session. To attach an existing session to a task,
        use set_active_grid_session_async instead.

        The new session is created with the task's suggested_authorization_mode
        (from task_properties), which the server uses to determine access:

        - SESSION_OWNER: access is limited to the session owner (owner_principal_id,
          or the caller when not provided) and their team.
        - SOURCE_BENEFACTOR: access is inherited from the benefactor of the source
          entity (anyone with EDIT rights).
        - Unset (legacy): the caller becomes the owner.

        After the Grid is created, updates the CurationTaskStatus to point its
        active_session_id at the new session. If that update fails for any reason,
        the newly created Grid is deleted on a best-effort basis and the original
        exception is re-raised.

        Arguments:
            owner_principal_id: The principal ID (user or team) that will own the
                created grid session. When not provided, the principal ID of the
                caller is used.
            timeout: Seconds to wait for the grid creation job. Defaults to 120.
            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 newly created Grid.

        Raises:
            ValueError: If task_id is unset or task_properties is of an unsupported type.
            SynapseHTTPError: If the RecordSet or EntityView does not exist, or if the
                status update fails. The orphan Grid is deleted on a best-effort basis
                before the error is re-raised.

        Example: Create a grid session for a curation task asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                grid = await CurationTask(task_id=123).create_grid_session_async()
                print(grid.session_id)

            asyncio.run(main())
            ```
        """
        if not self.task_id:
            raise ValueError(
                "task_id is required to create a CurationTask grid session"
            )

        if not self.task_properties:
            await self.get_async(synapse_client=synapse_client)

        if isinstance(self.task_properties, RecordBasedMetadataTaskProperties):
            if not self.task_properties.record_set_id:
                raise ValueError(
                    "Cannot create grid session: "
                    "task_properties.record_set_id is missing."
                )
            from synapseclient.models import RecordSet

            # raises SynapseHTTPError if RecordSet does not exist
            await RecordSet(id=self.task_properties.record_set_id).get_async(
                synapse_client=synapse_client
            )
            grid = Grid(
                record_set_id=self.task_properties.record_set_id,
                owner_principal_id=owner_principal_id,
                authorization_mode=self.task_properties.suggested_authorization_mode,
            )
        elif isinstance(self.task_properties, FileBasedMetadataTaskProperties):
            if not self.task_properties.file_view_id:
                raise ValueError(
                    "Cannot create grid session: "
                    "task_properties.file_view_id is missing."
                )
            from synapseclient.models import EntityView

            # raises SynapseHTTPError if EntityView does not exist
            await EntityView(id=self.task_properties.file_view_id).get_async(
                synapse_client=synapse_client
            )
            grid = Grid(
                initial_query=Query(
                    sql=f"SELECT * FROM {self.task_properties.file_view_id}"
                ),
                owner_principal_id=owner_principal_id,
                authorization_mode=self.task_properties.suggested_authorization_mode,
            )
        else:
            raise ValueError(
                "task_properties must be a FileBasedMetadataTaskProperties or "
                "RecordBasedMetadataTaskProperties to create a grid session"
            )

        grid = await grid.create_async(
            timeout=timeout,
            synapse_client=synapse_client,
        )

        # Only one grid session can be set as the active one on a a given CurationTask
        # at a any time, though multiple sessions can exist.
        # If two users run this concurrently, one will lose the race and
        # receive a 412 (precondition failed). In that case — or if recording the
        # active session fails for any other reason — delete the session we just
        # created so it doesn't become an orphan. If the delete also fails, log a
        # warning so the caller knows manual cleanup is needed, then re-raise the
        # original exception in all cases.
        try:
            await self.set_active_grid_session_async(
                active_session_id=grid.session_id, synapse_client=synapse_client
            )
        except Exception:
            try:
                await grid.delete_async(synapse_client=synapse_client)
            except Exception:
                Synapse.get_client(synapse_client=synapse_client).logger.warning(
                    "Failed to delete orphan grid session %s after status "
                    "update failure; manual cleanup may be required.",
                    grid.session_id,
                )
            raise

        return grid

    @skip_async_to_sync
    @classmethod
    async def list_async(
        cls,
        project_id: str,
        *,
        assigned_to_me: Optional[bool] = None,
        assignee_ids: Optional[list[str]] = None,
        state_filter: Optional[list[Union["TaskState", str]]] = None,
        synapse_client: Optional[Synapse] = None,
    ) -> AsyncGenerator["CurationTask", None]:
        """
        Generator that yields CurationTasks for a project as they become available.

        Arguments:
            project_id: The synId of the project.
            assigned_to_me: When True, only return tasks assigned to the current user.
                Cannot be combined with assignee_ids.
                False does not mean "tasks not assigned to me".
                Defaults to None.
            assignee_ids: Optional list of principal IDs (users or teams) to filter
                tasks by assignee. Cannot be combined with assigned_to_me=True.
                Passing an empty list raises a ValueError; pass None to return tasks
                for any assignee. Defaults to None.
            state_filter: Optional list of TaskState values or exact-case strings to
                filter tasks by their current state (e.g., "IN_PROGRESS"). Defaults to
                None (all states returned). Passing an empty list raises a ValueError;
                pass None to return tasks in any state.
            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.

        Yields:
            CurationTask objects as they are retrieved from the API.

        Raises:
            ValueError: If state_filter is an empty list.
            ValueError: If assignee_ids is an empty list.
            ValueError: If assigned_to_me is True and assignee_ids is also provided.
            ValueError: If any value in state_filter is not a TaskState member or
                an exact-case string matching a TaskState value (e.g., "IN_PROGRESS").
            ValueError: If the Synapse response for any task does not contain
                taskProperties.

        Example: List all curation tasks in a project asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                # List all curation tasks in the project
                async for task in CurationTask.list_async(project_id="syn9876543"):
                    print(f"Task ID: {task.task_id}")
                    print(f"Data Type: {task.data_type}")
                    print(f"Instructions: {task.instructions}")
                    print("---")

            asyncio.run(main())
            ```

        Example: List only curation tasks assigned to the current user asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                async for task in CurationTask.list_async(
                    project_id="syn9876543", assigned_to_me=True
                ):
                    print(f"Task ID: {task.task_id}")
                    print(f"Data Type: {task.data_type}")
                    print("---")

            asyncio.run(main())
            ```

        Example: List only in-progress curation tasks asynchronously
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import CurationTask, TaskState

            syn = Synapse()
            syn.login()

            async def main():
                async for task in CurationTask.list_async(
                    project_id="syn9876543",
                    state_filter=[TaskState.IN_PROGRESS],
                ):
                    print(f"Task ID: {task.task_id}")
                    print(f"Data Type: {task.data_type}")
                    print("---")

            asyncio.run(main())
            ```

        Example: List only in-progress curation tasks using a string state filter asynchronously
            &nbsp;

            state_filter also accepts plain strings matching TaskState names exactly.

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

            syn = Synapse()
            syn.login()

            async def main():
                async for task in CurationTask.list_async(
                    project_id="syn9876543",
                    state_filter=["IN_PROGRESS"],
                ):
                    print(f"Task ID: {task.task_id}")
                    print(f"Data Type: {task.data_type}")
                    print("---")

            asyncio.run(main())
            ```
        """
        if state_filter == []:
            raise ValueError(
                "state_filter must not be empty. Pass None to return tasks in any state."
            )
        if assignee_ids == []:
            raise ValueError(
                "assignee_ids must not be empty. Pass None to return tasks for any assignee."
            )
        if assigned_to_me is True and assignee_ids is not None:
            raise ValueError(
                f"assigned_to_me and assignee_ids are mutually exclusive "
                f"and cannot be used together. Got assignee_ids={assignee_ids!r}."
            )

        if state_filter is not None:
            state_filter = coerce_enum_list(TaskState, state_filter)

        trace.get_current_span().set_attributes(
            {
                "synapse.project_id": project_id,
            }
        )

        async for task_dict in list_curation_tasks(
            project_id=project_id,
            assigned_to_me=assigned_to_me,
            assignee_ids=assignee_ids,
            state_filter=state_filter,
            synapse_client=synapse_client,
        ):
            task = cls().fill_from_dict(synapse_response=task_dict)
            yield task

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: (
            f"CurationTask_SynchronizeActiveGridSession: ID: {self.task_id}"
        )
    )
    async def synchronize_active_grid_session_async(
        self,
        *,
        sync_type: Union["SyncType", str],
        synapse_client: Optional[Synapse] = None,
    ) -> Optional["Grid"]:
        """
        Synchronize this task's active grid session against its source entity.

        If task_properties is not yet populated on this object, it is fetched
        from Synapse first. If the task has no active grid session, a warning
        is logged and None is returned; no new grid session is created.

        `sync_type` is always required, for both task types. FileBasedMetadataTaskProperties
        tasks always perform a SyncType.PULL_PUSH regardless of the value passed in.

        Arguments:
            sync_type: The type of synchronization to perform. Required.

                - SyncType.PULL: Update the grid session with the latest data/schema
                  from the source RecordSet, without writing the grid back to it.
                  Use this to preview an incoming schema or data change in the grid
                  before committing it. Only supported for record-based tasks.
                - SyncType.PULL_PUSH: Update the grid session with the latest data
                  from the source, then write the grid's data back to the source
                  (the source RecordSet for record-based tasks, or the referenced
                  entities for file-based tasks). This commits any in-progress
                  curation in the grid as a new version of the source.

                For record-based tasks, this determines whether the call previews
                (PULL) or commits (PULL_PUSH). For file-based tasks, the value is
                ignored and the call always behaves as SyncType.PULL_PUSH.
            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 synchronized Grid, or None if the task has no active grid session.

        Raises:
            ValueError: If task_id is unset, task_properties is of an unsupported
                type, or sync_type is not provided for a record-based task.

        Example: Synchronize a record-based curation task's grid session
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import CurationTask
            from synapseclient.models.curation import SyncType

            syn = Synapse()
            syn.login()

            async def main():
                grid = await CurationTask(task_id=123).synchronize_active_grid_session_async(
                    sync_type=SyncType.PULL_PUSH
                )
                if grid is not None:
                    print(grid.session_id)

            asyncio.run(main())
            ```

        Example: Synchronize a file-based curation task's grid session
            &nbsp;

            File-based tasks always synchronize with SyncType.PULL_PUSH, so any
            value works here -- but `sync_type` still has to be passed.

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import CurationTask
            from synapseclient.models.curation import SyncType

            syn = Synapse()
            syn.login()

            async def main():
                grid = await CurationTask(task_id=456).synchronize_active_grid_session_async(
                    sync_type=SyncType.PULL_PUSH
                )
                if grid is not None:
                    print(grid.session_id)

            asyncio.run(main())
            ```
        """
        client = Synapse.get_client(synapse_client=synapse_client)

        if not self.task_properties:
            await self.get_async(synapse_client=synapse_client)

        if isinstance(self.task_properties, FileBasedMetadataTaskProperties):
            if sync_type is not None and sync_type != SyncType.PULL_PUSH:
                client.logger.warning(
                    f"Ignoring sync_type={sync_type} for CurationTask "
                    f"{self.task_id}: FileBasedMetadataTaskProperties tasks always "
                    "use SyncType.PULL_PUSH."
                )
            sync_type = SyncType.PULL_PUSH
        elif isinstance(self.task_properties, RecordBasedMetadataTaskProperties):
            if not sync_type:
                raise ValueError(
                    "sync_type must be provided for RecordBasedMetadataTaskProperties"
                )
        else:
            raise ValueError(
                f"Synchronization only supports FileBasedMetadataTaskProperties or "
                f"RecordBasedMetadataTaskProperties, got {type(self.task_properties).__name__}."
            )

        status = await self.get_status_async(synapse_client=synapse_client)
        if (
            status.execution_details is None
            or status.execution_details.active_session_id is None
        ):
            client.logger.warning(
                f"No active grid session found for task {self.task_id}. Skipping "
                "synchronization."
            )
            return None
        active_grid_session_id = status.execution_details.active_session_id

        client.logger.info(
            f"Synchronizing active grid session {active_grid_session_id} for "
            f"task {self.task_id}"
        )
        grid = Grid(session_id=active_grid_session_id)
        return await grid.synchronize_async(
            synapse_client=synapse_client, sync_type=sync_type
        )

Methods:¶

get ¶

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

Gets a CurationTask from Synapse by ID.

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
`CurationTask`	The CurationTask object. TYPE: `CurationTask`

RAISES	DESCRIPTION
`ValueError`	If the CurationTask object does not have a task_id.

Get a curation task by ID

from synapseclient import Synapse
from synapseclient.models import CurationTask

syn = Synapse()
syn.login()

task = CurationTask(task_id=123).get()
print(task.data_type)
print(task.instructions)

Source code in synapseclient/models/curation.py

def get(self, *, synapse_client: Optional[Synapse] = None) -> "CurationTask":
    """
    Gets a CurationTask from Synapse by ID.

    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:
        CurationTask: The CurationTask object.

    Raises:
        ValueError: If the CurationTask object does not have a task_id.

    Example: Get a curation task by ID
        &nbsp;

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

        syn = Synapse()
        syn.login()

        task = CurationTask(task_id=123).get()
        print(task.data_type)
        print(task.instructions)
        ```
    """
    return self

get_status ¶

get_status(*, synapse_client: Synapse | None = None) -> CurationTaskStatus

Gets the status of this CurationTask 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: `Synapse \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`CurationTaskStatus`	The CurationTaskStatus object.

RAISES	DESCRIPTION
`ValueError`	If the CurationTask object does not have a task_id.

Get the status of a curation task

from synapseclient import Synapse
from synapseclient.models import CurationTask

syn = Synapse()
syn.login()

status = CurationTask(task_id=123).get_status()
print(status.state)

Source code in synapseclient/models/curation.py

def get_status(
    self, *, synapse_client: Synapse | None = None
) -> "CurationTaskStatus":
    """
    Gets the status of this CurationTask 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.

    Returns:
        The CurationTaskStatus object.

    Raises:
        ValueError: If the CurationTask object does not have a task_id.

    Example: Get the status of a curation task
        &nbsp;

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

        syn = Synapse()
        syn.login()

        status = CurationTask(task_id=123).get_status()
        print(status.state)
        ```
    """
    return CurationTaskStatus()

update_status ¶

update_status(curation_task_status: CurationTaskStatus, *, synapse_client: Synapse | None = None) -> CurationTaskStatus

Updates the status of this CurationTask on Synapse.

PARAMETER	DESCRIPTION
`curation_task_status`	The complete CurationTaskStatus object to update. TYPE: `CurationTaskStatus`
`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: `Synapse \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`CurationTaskStatus`	The updated CurationTaskStatus object.

RAISES	DESCRIPTION
`ValueError`	If the CurationTask object does not have a task_id.

Update the status of a curation task

from synapseclient import Synapse
from synapseclient.models import (
    CurationTask,
    TaskState,
)

syn = Synapse()
syn.login()

task = CurationTask(task_id=123)
current = task.get_status()
current.state = TaskState.COMPLETED
updated = task.update_status(curation_task_status=current)
print(updated.state)

Source code in synapseclient/models/curation.py

def update_status(
    self,
    curation_task_status: "CurationTaskStatus",
    *,
    synapse_client: Synapse | None = None,
) -> "CurationTaskStatus":
    """
    Updates the status of this CurationTask on Synapse.

    Arguments:
        curation_task_status: The complete CurationTaskStatus object to update.
        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 updated CurationTaskStatus object.

    Raises:
        ValueError: If the CurationTask object does not have a task_id.

    Example: Update the status of a curation task
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import (
            CurationTask,
            TaskState,
        )

        syn = Synapse()
        syn.login()

        task = CurationTask(task_id=123)
        current = task.get_status()
        current.state = TaskState.COMPLETED
        updated = task.update_status(curation_task_status=current)
        print(updated.state)
        ```
    """
    return CurationTaskStatus()

set_active_grid_session ¶

set_active_grid_session(active_session_id: str, *, synapse_client: Synapse | None = None) -> CurationTaskStatus

Set the active grid session on this CurationTask's status by replacing execution_details with a GridExecutionDetails carrying the given session id.

Does not transition the task state.

PARAMETER	DESCRIPTION
`active_session_id`	The unique identifier of the active grid session to link. TYPE: `str`
`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: `Synapse \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`CurationTaskStatus`	The updated CurationTaskStatus object.

RAISES	DESCRIPTION
`ValueError`	If the CurationTask object does not have a task_id.

Link a grid session to a curation task

from synapseclient import Synapse
from synapseclient.models import CurationTask, Grid

syn = Synapse()
syn.login()

grid = Grid(record_set_id="syn1234567").create()
CurationTask(task_id=123).set_active_grid_session(
    active_session_id=grid.session_id
)

Source code in synapseclient/models/curation.py

def set_active_grid_session(
    self,
    active_session_id: str,
    *,
    synapse_client: Synapse | None = None,
) -> "CurationTaskStatus":
    """
    Set the active grid session on this CurationTask's status by replacing
    execution_details with a GridExecutionDetails carrying the given session id.

    Does not transition the task state.

    Arguments:
        active_session_id: The unique identifier of the active grid session to link.
        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 updated CurationTaskStatus object.

    Raises:
        ValueError: If the CurationTask object does not have a task_id.

    Example: Link a grid session to a curation task
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import CurationTask, Grid

        syn = Synapse()
        syn.login()

        grid = Grid(record_set_id="syn1234567").create()
        CurationTask(task_id=123).set_active_grid_session(
            active_session_id=grid.session_id
        )
        ```
    """
    return CurationTaskStatus()

delete ¶

delete(delete_source: bool = False, *, synapse_client: Optional[Synapse] = None) -> None

Deletes a CurationTask from Synapse.

PARAMETER	DESCRIPTION
`delete_source`	If True, the associated source data (EntityView or RecordSet) will also be deleted if the task is a FileBasedMetadataTask or RecordBasedMetadataTask respectively. Defaults to False. 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`

RAISES	DESCRIPTION
`ValueError`	If the CurationTask object does not have a task_id.

Delete a curation task

from synapseclient import Synapse
from synapseclient.models import CurationTask

syn = Synapse()
syn.login()

task = CurationTask(task_id=123)
task.delete()

Delete a curation task and its associated data source

from synapseclient import Synapse
from synapseclient.models import CurationTask

syn = Synapse()
syn.login()

task = CurationTask(task_id=123)
task.delete(delete_source=True)

Source code in synapseclient/models/curation.py

def delete(
    self,
    delete_source: bool = False,
    *,
    synapse_client: Optional[Synapse] = None,
) -> None:
    """
    Deletes a CurationTask from Synapse.

    Arguments:
        delete_source: If True, the associated source data (EntityView or RecordSet) will also be deleted
            if the task is a FileBasedMetadataTask or RecordBasedMetadataTask respectively. Defaults to 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.

    Raises:
        ValueError: If the CurationTask object does not have a task_id.

    Example: Delete a curation task
        &nbsp;

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

        syn = Synapse()
        syn.login()

        task = CurationTask(task_id=123)
        task.delete()
        ```

    Example: Delete a curation task and its associated data source
        &nbsp;

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

        syn = Synapse()
        syn.login()

        task = CurationTask(task_id=123)
        task.delete(delete_source=True)
        ```
    """
    return None

store ¶

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

Creates a new CurationTask or updates an existing one on Synapse.

This method implements non-destructive updates. If a CurationTask with the same project_id and data_type exists and this instance hasn't been retrieved from Synapse before, it will merge the existing task data with the current instance before updating.

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
`CurationTask`	The CurationTask object. TYPE: `CurationTask`

Create a new file-based curation task

from synapseclient import Synapse
from synapseclient.models import CurationTask, FileBasedMetadataTaskProperties

syn = Synapse()
syn.login()

# Create file-based task properties
file_properties = FileBasedMetadataTaskProperties(
    upload_folder_id="syn1234567",
    file_view_id="syn2345678"
)

# Create the curation task
task = CurationTask(
    project_id="syn9876543",
    data_type="genomics_data",
    instructions="Upload your genomics files to the specified folder",
    task_properties=file_properties
)
task = task.store()
print(f"Created task with ID: {task.task_id}")

Create a new record-based curation task

from synapseclient import Synapse
from synapseclient.models import CurationTask, RecordBasedMetadataTaskProperties

syn = Synapse()
syn.login()

# Create record-based task properties
record_properties = RecordBasedMetadataTaskProperties(
    record_set_id="syn3456789"
)

# Create the curation task
task = CurationTask(
    project_id="syn9876543",
    data_type="clinical_data",
    instructions="Fill out the clinical data form",
    task_properties=record_properties
)
task = task.store()
print(f"Created task with ID: {task.task_id}")

Update an existing curation task

from synapseclient import Synapse
from synapseclient.models import CurationTask

syn = Synapse()
syn.login()

# Get existing task and update
task = CurationTask(task_id=123).get()
task.instructions = "Updated instructions for data contributors"
task = task.store()

Source code in synapseclient/models/curation.py

def store(self, *, synapse_client: Optional[Synapse] = None) -> "CurationTask":
    """
    Creates a new CurationTask or updates an existing one on Synapse.

    This method implements non-destructive updates. If a CurationTask with the same
    project_id and data_type exists and this instance hasn't been retrieved from
    Synapse before, it will merge the existing task data with the current instance
    before updating.

    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:
        CurationTask: The CurationTask object.

    Example: Create a new file-based curation task
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import CurationTask, FileBasedMetadataTaskProperties

        syn = Synapse()
        syn.login()

        # Create file-based task properties
        file_properties = FileBasedMetadataTaskProperties(
            upload_folder_id="syn1234567",
            file_view_id="syn2345678"
        )

        # Create the curation task
        task = CurationTask(
            project_id="syn9876543",
            data_type="genomics_data",
            instructions="Upload your genomics files to the specified folder",
            task_properties=file_properties
        )
        task = task.store()
        print(f"Created task with ID: {task.task_id}")
        ```

    Example: Create a new record-based curation task
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import CurationTask, RecordBasedMetadataTaskProperties

        syn = Synapse()
        syn.login()

        # Create record-based task properties
        record_properties = RecordBasedMetadataTaskProperties(
            record_set_id="syn3456789"
        )

        # Create the curation task
        task = CurationTask(
            project_id="syn9876543",
            data_type="clinical_data",
            instructions="Fill out the clinical data form",
            task_properties=record_properties
        )
        task = task.store()
        print(f"Created task with ID: {task.task_id}")
        ```

    Example: Update an existing curation task
        &nbsp;

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

        syn = Synapse()
        syn.login()

        # Get existing task and update
        task = CurationTask(task_id=123).get()
        task.instructions = "Updated instructions for data contributors"
        task = task.store()
        ```
    """
    return self

list `classmethod` ¶

list(project_id: str, *, assigned_to_me: Optional[bool] = None, assignee_ids: Optional[list[str]] = None, state_filter: Optional[list[Union[TaskState, str]]] = None, synapse_client: Optional[Synapse] = None) -> Generator[CurationTask, None, None]

Generator that yields CurationTasks for a project as they become available.

PARAMETER	DESCRIPTION
`project_id`	The synId of the project. TYPE: `str`
`assigned_to_me`	When True, only return tasks assigned to the current user. Cannot be combined with assignee_ids. False does not mean "tasks not assigned to me". Defaults to None. TYPE: `Optional[bool]` DEFAULT: `None`
`assignee_ids`	Optional list of principal IDs (users or teams) to filter tasks by assignee. Cannot be combined with assigned_to_me=True. Passing an empty list raises a ValueError; pass None to return tasks for any assignee. Defaults to None. TYPE: `Optional[list[str]]` DEFAULT: `None`
`state_filter`	Optional list of TaskState values or exact-case strings to filter tasks by their current state (e.g., "IN_PROGRESS"). Defaults to None (all states returned). Passing an empty list raises a ValueError; pass None to return tasks in any state. TYPE: `Optional[list[Union[TaskState, str]]]` DEFAULT: `None`
`synapse_client`	If not passed in and caching was not disabled by Synapse.allow_client_caching(False) this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

YIELDS	DESCRIPTION
`CurationTask`	CurationTask objects as they are retrieved from the API.

RAISES	DESCRIPTION
`ValueError`	If state_filter is an empty list.
`ValueError`	If assignee_ids is an empty list.
`ValueError`	If assigned_to_me is True and assignee_ids is also provided.
`ValueError`	If any value in state_filter is not a TaskState member or an exact-case string matching a TaskState value (e.g., "IN_PROGRESS").

Due to generator semantics, argument validation runs on the first

iteration of the generator, not at the point where list() is called.

List all curation tasks in a project

from synapseclient import Synapse
from synapseclient.models import CurationTask

syn = Synapse()
syn.login()

# List all curation tasks in the project
for task in CurationTask.list(project_id="syn9876543"):
    print(f"Task ID: {task.task_id}")
    print(f"Data Type: {task.data_type}")
    print(f"Instructions: {task.instructions}")
    print("---")

List only curation tasks assigned to the current user

from synapseclient import Synapse
from synapseclient.models import CurationTask

syn = Synapse()
syn.login()

for task in CurationTask.list(project_id="syn9876543", assigned_to_me=True):
    print(f"Task ID: {task.task_id}")
    print(f"Data Type: {task.data_type}")
    print("---")

List only in-progress curation tasks

from synapseclient import Synapse
from synapseclient.models import CurationTask, TaskState

syn = Synapse()
syn.login()

for task in CurationTask.list(
    project_id="syn9876543",
    state_filter=[TaskState.IN_PROGRESS],
):
    print(f"Task ID: {task.task_id}")
    print(f"Data Type: {task.data_type}")
    print("---")

List only in-progress curation tasks using a string state filter

state_filter also accepts plain strings matching TaskState names exactly.

from synapseclient import Synapse
from synapseclient.models import CurationTask

syn = Synapse()
syn.login()

for task in CurationTask.list(
    project_id="syn9876543",
    state_filter=["IN_PROGRESS"],
):
    print(f"Task ID: {task.task_id}")
    print(f"Data Type: {task.data_type}")
    print("---")

Source code in synapseclient/models/curation.py

@classmethod
def list(
    cls,
    project_id: str,
    *,
    assigned_to_me: Optional[bool] = None,
    assignee_ids: Optional[list[str]] = None,
    state_filter: Optional[list[Union["TaskState", str]]] = None,
    synapse_client: Optional[Synapse] = None,
) -> Generator["CurationTask", None, None]:
    """
    Generator that yields CurationTasks for a project as they become available.

    Arguments:
        project_id: The synId of the project.
        assigned_to_me: When True, only return tasks assigned to the current user.
            Cannot be combined with assignee_ids.
            False does not mean "tasks not assigned to me".
            Defaults to None.
        assignee_ids: Optional list of principal IDs (users or teams) to filter
            tasks by assignee. Cannot be combined with assigned_to_me=True.
            Passing an empty list raises a ValueError; pass None to return tasks
            for any assignee. Defaults to None.
        state_filter: Optional list of TaskState values or exact-case strings to
            filter tasks by their current state (e.g., "IN_PROGRESS"). Defaults to
            None (all states returned). Passing an empty list raises a ValueError;
            pass None to return tasks in any state.
        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.

    Yields:
        CurationTask objects as they are retrieved from the API.

    Raises:
        ValueError: If state_filter is an empty list.
        ValueError: If assignee_ids is an empty list.
        ValueError: If assigned_to_me is True and assignee_ids is also provided.
        ValueError: If any value in state_filter is not a TaskState member or
            an exact-case string matching a TaskState value (e.g., "IN_PROGRESS").

    Note: Due to generator semantics, argument validation runs on the first
        iteration of the generator, not at the point where list() is called.

    Example: List all curation tasks in a project
        &nbsp;

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

        syn = Synapse()
        syn.login()

        # List all curation tasks in the project
        for task in CurationTask.list(project_id="syn9876543"):
            print(f"Task ID: {task.task_id}")
            print(f"Data Type: {task.data_type}")
            print(f"Instructions: {task.instructions}")
            print("---")
        ```

    Example: List only curation tasks assigned to the current user
        &nbsp;

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

        syn = Synapse()
        syn.login()

        for task in CurationTask.list(project_id="syn9876543", assigned_to_me=True):
            print(f"Task ID: {task.task_id}")
            print(f"Data Type: {task.data_type}")
            print("---")
        ```

    Example: List only in-progress curation tasks
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import CurationTask, TaskState

        syn = Synapse()
        syn.login()

        for task in CurationTask.list(
            project_id="syn9876543",
            state_filter=[TaskState.IN_PROGRESS],
        ):
            print(f"Task ID: {task.task_id}")
            print(f"Data Type: {task.data_type}")
            print("---")
        ```

    Example: List only in-progress curation tasks using a string state filter
        &nbsp;

        state_filter also accepts plain strings matching TaskState names exactly.

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

        syn = Synapse()
        syn.login()

        for task in CurationTask.list(
            project_id="syn9876543",
            state_filter=["IN_PROGRESS"],
        ):
            print(f"Task ID: {task.task_id}")
            print(f"Data Type: {task.data_type}")
            print("---")
        ```
    """
    yield from wrap_async_generator_to_sync_generator(
        async_gen_func=cls.list_async,
        project_id=project_id,
        assigned_to_me=assigned_to_me,
        assignee_ids=assignee_ids,
        state_filter=state_filter,
        synapse_client=synapse_client,
    )

create_grid_session ¶

create_grid_session(*, owner_principal_id: int | None = None, timeout: int = 120, synapse_client: Synapse | None = None) -> Grid

Create a Grid session for this CurationTask and link it to the task status.

Picks the Grid seed from this task's task_properties:

RecordBasedMetadataTaskProperties uses record_set_id
FileBasedMetadataTaskProperties uses an initial_query that selects from the file_view_id

Always creates a new Grid session. To attach an existing session to a task, use set_active_grid_session instead.

The new session is created with the task's suggested_authorization_mode (from task_properties), which the server uses to determine access:

SESSION_OWNER: access is limited to the session owner (owner_principal_id, or the caller when not provided) and their team.
SOURCE_BENEFACTOR: access is inherited from the benefactor of the source entity (anyone with EDIT rights).
Unset (legacy): the caller becomes the owner.

After the Grid is created, updates the CurationTaskStatus to point its active_session_id at the new session. If that update fails for any reason, the newly created Grid is deleted on a best-effort basis and the original exception is re-raised.

PARAMETER	DESCRIPTION
`owner_principal_id`	The principal ID (user or team) that will own the created grid session. When not provided, the principal ID of the caller is used. TYPE: `int \| None` DEFAULT: `None`
`timeout`	Seconds to wait for the grid creation job. Defaults to 120. TYPE: `int` DEFAULT: `120`
`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: `Synapse \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Grid`	The newly created Grid.

RAISES	DESCRIPTION
`ValueError`	If task_id is unset or task_properties is of an unsupported type.
`SynapseHTTPError`	If the status update fails. The orphan Grid is deleted on a best-effort basis before the error is re-raised.

Create a grid session for a curation task

from synapseclient import Synapse
from synapseclient.models import CurationTask

syn = Synapse()
syn.login()

grid = CurationTask(task_id=123).create_grid_session()
print(grid.session_id)

Source code in synapseclient/models/curation.py

def create_grid_session(
    self,
    *,
    owner_principal_id: int | None = None,
    timeout: int = 120,
    synapse_client: Synapse | None = None,
) -> "Grid":
    """
    Create a Grid session for this CurationTask and link it to the task status.

    Picks the Grid seed from this task's task_properties:

    - RecordBasedMetadataTaskProperties uses record_set_id
    - FileBasedMetadataTaskProperties uses an initial_query that selects from
      the file_view_id

    Always creates a new Grid session. To attach an existing session to a task,
    use set_active_grid_session instead.

    The new session is created with the task's suggested_authorization_mode
    (from task_properties), which the server uses to determine access:

    - SESSION_OWNER: access is limited to the session owner (owner_principal_id,
      or the caller when not provided) and their team.
    - SOURCE_BENEFACTOR: access is inherited from the benefactor of the source
      entity (anyone with EDIT rights).
    - Unset (legacy): the caller becomes the owner.

    After the Grid is created, updates the CurationTaskStatus to point its
    active_session_id at the new session. If that update fails for any reason,
    the newly created Grid is deleted on a best-effort basis and the original
    exception is re-raised.

    Arguments:
        owner_principal_id: The principal ID (user or team) that will own the
            created grid session. When not provided, the principal ID of the
            caller is used.
        timeout: Seconds to wait for the grid creation job. Defaults to 120.
        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 newly created Grid.

    Raises:
        ValueError: If task_id is unset or task_properties is of an unsupported type.
        SynapseHTTPError: If the status update fails. The orphan Grid is
            deleted on a best-effort basis before the error is re-raised.

    Example: Create a grid session for a curation task
        &nbsp;

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

        syn = Synapse()
        syn.login()

        grid = CurationTask(task_id=123).create_grid_session()
        print(grid.session_id)
        ```
    """
    return Grid()

set_task_state ¶

set_task_state(state: TaskState | str, *, synapse_client: Synapse | None = None) -> CurationTaskStatus

Set the state on this CurationTask's status.

Does not modify execution_details. Fetches the current CurationTaskStatus first so the update carries a fresh etag.

PARAMETER	DESCRIPTION
`state`	The state to set on this task's status. Accepts a TaskState or a string exactly matching one of its members (e.g. NOT_STARTED, IN_PROGRESS, COMPLETED, CANCELED). TYPE: `TaskState \| str`
`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: `Synapse \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`CurationTaskStatus`	The updated CurationTaskStatus object.

RAISES	DESCRIPTION
`ValueError`	If the CurationTask object does not have a task_id, or if state is a string that does not match a TaskState member.

Mark a curation task as completed

from synapseclient import Synapse
from synapseclient.models import CurationTask, TaskState

syn = Synapse()
syn.login()

CurationTask(task_id=123).set_task_state(
    state=TaskState.COMPLETED
)

Mark a curation task as completed using a string

from synapseclient import Synapse
from synapseclient.models import CurationTask

syn = Synapse()
syn.login()

CurationTask(task_id=123).set_task_state(state="COMPLETED")

Source code in synapseclient/models/curation.py

def set_task_state(
    self,
    state: "TaskState | str",
    *,
    synapse_client: Synapse | None = None,
) -> "CurationTaskStatus":
    """
    Set the state on this CurationTask's status.

    Does not modify execution_details. Fetches the current CurationTaskStatus
    first so the update carries a fresh etag.

    Arguments:
        state: The state to set on this task's status. Accepts a
            TaskState or a string exactly matching one of its members
            (e.g. NOT_STARTED, IN_PROGRESS, COMPLETED, CANCELED).
        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 updated CurationTaskStatus object.

    Raises:
        ValueError: If the CurationTask object does not have a task_id, or
            if state is a string that does not match a TaskState member.

    Example: Mark a curation task as completed
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import CurationTask, TaskState

        syn = Synapse()
        syn.login()

        CurationTask(task_id=123).set_task_state(
            state=TaskState.COMPLETED
        )
        ```

    Example: Mark a curation task as completed using a string
        &nbsp;

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

        syn = Synapse()
        syn.login()

        CurationTask(task_id=123).set_task_state(state="COMPLETED")
        ```
    """
    return CurationTaskStatus()

synchronize_active_grid_session ¶

synchronize_active_grid_session(*, sync_type: SyncType | str, synapse_client: Synapse | None = None) -> Optional[Grid]

Synchronize this task's active grid session against its source entity.

If task_properties is not yet populated on this object, it is fetched from Synapse first. If the task has no active grid session, a warning is logged and None is returned; no new grid session is created.

sync_type is always required, for both task types. FileBasedMetadataTaskProperties tasks always perform a SyncType.PULL_PUSH regardless of the value passed in.

PARAMETER DESCRIPTION

sync_type

The type of synchronization to perform. Required.

SyncType.PULL: Update the grid session with the latest data/schema from the source RecordSet, without writing the grid back to it. Use this to preview an incoming schema or data change in the grid before committing it. Only supported for record-based tasks.
SyncType.PULL_PUSH: Update the grid session with the latest data from the source, then write the grid's data back to the source (the source RecordSet for record-based tasks, or the referenced entities for file-based tasks). This commits any in-progress curation in the grid as a new version of the source.

For record-based tasks, this determines whether the call previews (PULL) or commits (PULL_PUSH). For file-based tasks, the value is ignored and the call always behaves as SyncType.PULL_PUSH.

TYPE: SyncType | str

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: Synapse | None DEFAULT: None

RETURNS	DESCRIPTION
`Optional[Grid]`	The synchronized Grid, or None if the task has no active grid session.

RAISES	DESCRIPTION
`ValueError`	If task_id is unset, task_properties is of an unsupported type, or sync_type is not provided for a record-based task.

Synchronize a record-based curation task's grid session

from synapseclient import Synapse
from synapseclient.models import CurationTask
from synapseclient.models.curation import SyncType

syn = Synapse()
syn.login()

grid = CurationTask(task_id=123).synchronize_active_grid_session(
    sync_type=SyncType.PULL_PUSH
)
if grid is not None:
    print(grid.session_id)

Synchronize a file-based curation task's grid session

File-based tasks always synchronize with SyncType.PULL_PUSH, so any value works here -- but sync_type still has to be passed.

from synapseclient import Synapse
from synapseclient.models import CurationTask
from synapseclient.models.curation import SyncType

syn = Synapse()
syn.login()

grid = CurationTask(task_id=456).synchronize_active_grid_session(
    sync_type=SyncType.PULL_PUSH
)
if grid is not None:
    print(grid.session_id)

Source code in synapseclient/models/curation.py

def synchronize_active_grid_session(
    self,
    *,
    sync_type: "SyncType | str",
    synapse_client: Synapse | None = None,
) -> Optional["Grid"]:
    """
    Synchronize this task's active grid session against its source entity.

    If task_properties is not yet populated on this object, it is fetched
    from Synapse first. If the task has no active grid session, a warning
    is logged and None is returned; no new grid session is created.

    `sync_type` is always required, for both task types. FileBasedMetadataTaskProperties
    tasks always perform a SyncType.PULL_PUSH regardless of the value passed in.

    Arguments:
        sync_type: The type of synchronization to perform. Required.

            - SyncType.PULL: Update the grid session with the latest data/schema
              from the source RecordSet, without writing the grid back to it.
              Use this to preview an incoming schema or data change in the grid
              before committing it. Only supported for record-based tasks.
            - SyncType.PULL_PUSH: Update the grid session with the latest data
              from the source, then write the grid's data back to the source
              (the source RecordSet for record-based tasks, or the referenced
              entities for file-based tasks). This commits any in-progress
              curation in the grid as a new version of the source.

            For record-based tasks, this determines whether the call previews
            (PULL) or commits (PULL_PUSH). For file-based tasks, the value is
            ignored and the call always behaves as SyncType.PULL_PUSH.
        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 synchronized Grid, or None if the task has no active grid session.

    Raises:
        ValueError: If task_id is unset, task_properties is of an unsupported
            type, or sync_type is not provided for a record-based task.

    Example: Synchronize a record-based curation task's grid session
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import CurationTask
        from synapseclient.models.curation import SyncType

        syn = Synapse()
        syn.login()

        grid = CurationTask(task_id=123).synchronize_active_grid_session(
            sync_type=SyncType.PULL_PUSH
        )
        if grid is not None:
            print(grid.session_id)
        ```

    Example: Synchronize a file-based curation task's grid session
        &nbsp;

        File-based tasks always synchronize with SyncType.PULL_PUSH, so any
        value works here -- but `sync_type` still has to be passed.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import CurationTask
        from synapseclient.models.curation import SyncType

        syn = Synapse()
        syn.login()

        grid = CurationTask(task_id=456).synchronize_active_grid_session(
            sync_type=SyncType.PULL_PUSH
        )
        if grid is not None:
            print(grid.session_id)
        ```
    """
    return Grid()

synapseclient.models.RecordSet `dataclass` ¶

Bases: RecordSetSynchronousProtocol, AccessControllable, BaseJSONSchema

A RecordSet entity captures record-based metadata as a special type of CSV. The record set content can be curated using the grid services. When a grid is created from a record set, its data can be exported back to a new version of the record set. The export will include the validation summary as well as a validation file handle that contains detailed validation results for each row in the record set.

ATTRIBUTE	DESCRIPTION
`id`	The unique immutable ID for this file. A new ID will be generated for new Files. 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. If not specified, the name will be derived from the file name. TYPE: `Optional[str]`
`path`	The path to the file on disk. Using shorthand `~` will be expanded to the user's home directory. This is used during a `get` operation to specify where to download the file to. It should be pointing to a directory. This is also used during a `store` operation to specify the file to upload. It should be pointing to a file. TYPE: `Optional[str]`
`description`	The description of this file. Must be 1000 characters or less. TYPE: `Optional[str]`
`parent_id`	The ID of the Entity that is the parent of this Entity. Setting this to a new value and storing it will move this File under the new parent. TYPE: `Optional[str]`
`version_label`	The version label for this entity. Updates to the entity will increment the version number. TYPE: `Optional[str]`
`version_comment`	The version comment for this entity. TYPE: `Optional[str]`
`data_file_handle_id`	ID of the file handle associated with this entity. You may define an existing data_file_handle_id to use the existing data_file_handle_id. The creator of the file must also be the owner of the data_file_handle_id to have permission to store the file. TYPE: `Optional[str]`
`activity`	The Activity model represents the main record of Provenance in Synapse. It is analygous to the Activity defined in the W3C Specification on Provenance. Activity cannot be removed during a store operation by setting it to None. You must use: synapseclient.models.Activity.delete_async or synapseclient.models.Activity.disassociate_from_entity_async. TYPE: `Optional[Activity]`
`annotations`	Additional metadata associated with the entity. 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 `{}`. TYPE: `Optional[Dict[str, Union[List[str], List[bool], List[float], List[int], List[date], List[datetime]]]]`
`upsert_keys`	One or more column names that define this upsert key for this set. This key is used to determine if a new record should be treated as an update or an insert. TYPE: `Optional[List[str]]`
`csv_descriptor`	The description of a CSV for upload or download. TYPE: `Optional[CsvTableDescriptor]`
`validation_summary`	Summary statistics for the JSON schema validation results for the children of an Entity container (Project or Folder). TYPE: `Optional[ValidationSummary]`
`file_name_override`	An optional replacement for the name of the uploaded file. This is distinct from the entity name. If omitted the file will retain its original name. TYPE: `Optional[str]`
`validation_file_handle_id`	(Read Only) Pointer to a CSV file that contains the detailed validation results for each row in the record set. The CSV file will contain for each row the following columns: row_index, is_valid, validation_error_message, all_validation_messages. Generated only from a grid session export, cannot be changed by the user. TYPE: `Optional[str]`
`content_type`	(New Upload Only) Used to manually specify Content-type header, for example 'application/png' or 'application/json; charset=UTF-8'. If not specified, the content type will be derived from the file extension. This can be specified only during the initial store of this file. In order to change this after the File has been created use synapseclient.models.File.change_metadata. TYPE: `Optional[str]`
`content_size`	(New Upload Only) The size of the file in bytes. This can be specified only during the initial creation of the File. This is also only applicable to files not uploaded to Synapse. ie: `synapse_store` is False. TYPE: `Optional[int]`
`content_md5`	(Store only) The MD5 of the file is known. If not supplied this will be computed in the client is possible. If supplied for a file entity already stored in Synapse it will be calculated again to check if a new upload needs to occur. This will not be filled in during a read for data. It is only used during a store operation. To retrieve the md5 of the file after read from synapse use the `.file_handle.content_md5` attribute. TYPE: `Optional[str]`
`create_or_update`	(Store only) Indicates whether the method should automatically perform an update if the file conflicts with an existing Synapse object. TYPE: `bool`
`force_version`	(Store only) Indicates whether the method should increment the version of the object if something within the entity has changed. For example updating the description or name. You may set this to False and an update to the entity will not increment the version. Updating the `version_label` attribute will also cause a version update regardless of this flag. An update to the MD5 of the file will force a version update regardless of this flag. TYPE: `bool`
`is_restricted`	(Store only) If set to true, an email will be sent to the Synapse access control team to start the process of adding terms-of-use or review board approval for this entity. You will be contacted with regards to the specific data being restricted and the requirements of access. This may be used only by an administrator of the specified file. TYPE: `bool`
`merge_existing_annotations`	(Store only) Works in conjunction with `create_or_update` in that this is only evaluated if `create_or_update` is True. If this entity exists in Synapse that has annotations that are not present in a store operation, these annotations will be added to the entity. If this is False any annotations that are not present within a store operation will be removed from this entity. This allows one to complete a destructive update of annotations on an entity. TYPE: `bool`
`associate_activity_to_new_version`	(Store only) Works in conjunction with `create_or_update` in that this is only evaluated if `create_or_update` is True. When true an activity already attached to the current version of this entity will be associated the new version during a store operation if the version was updated. This is useful if you are updating the entity and want to ensure that the activity is persisted onto the new version the entity. When this is False the activity will not be associated to the new version of the entity during a store operation. Regardless of this setting, if you have an Activity object on the entity it will be persisted onto the new version. This is only used when you don't have an Activity object on the entity. TYPE: `bool`
`synapse_store`	(Store only) Whether the File should be uploaded or if false: only the path should be stored when synapseclient.models.File.store is called. TYPE: `bool`
`download_file`	(Get only) If True the file will be downloaded. TYPE: `bool`
`if_collision`	(Get only) Determines how to handle file collisions. Defaults to "keep.both". May be: `overwrite.local` `keep.local` `keep.both` TYPE: `str`
`synapse_container_limit`	(Get only) A Synanpse ID used to limit the search in Synapse if file is specified as a local file. That is, if the file is stored in multiple locations in Synapse only the ones in the specified folder/project will be returned. TYPE: `Optional[str]`
`etag`	(Read Only) 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`	(Read Only) The date this entity was created. TYPE: `Optional[str]`
`modified_on`	(Read Only) The date this entity was last modified. TYPE: `Optional[str]`
`created_by`	(Read Only) The ID of the user that created this entity. TYPE: `Optional[str]`
`modified_by`	(Read Only) The ID of the user that last modified this entity. TYPE: `Optional[str]`
`version_number`	(Read Only) The version number issued to this version on the object. TYPE: `Optional[int]`
`is_latest_version`	(Read Only) If this is the latest version of the object. TYPE: `Optional[bool]`
`file_handle`	(Read Only) The file handle associated with this entity. TYPE: `Optional[FileHandle]`

Source code in synapseclient/models/recordset.py

@dataclass()
@async_to_sync
class RecordSet(RecordSetSynchronousProtocol, AccessControllable, BaseJSONSchema):
    """
    A RecordSet entity captures record-based metadata as a special type of CSV.
    The record set content can be curated using the grid services.
    When a grid is created from a record set, its data can be exported back to a new version of the record set.
    The export will include the validation summary as well as a validation file handle that
      contains detailed validation results for each row in the record set.

    Attributes:
        id: The unique immutable ID for this file. A new ID will be generated for new
            Files. 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. If not specified, the name will be
            derived from the file name.
        path: The path to the file on disk. Using shorthand `~` will be expanded to
            the user's home directory.

            This is used during a `get` operation to specify where to download the
            file to. It should be pointing to a directory.

            This is also used during a `store` operation to specify the file to
            upload. It should be pointing to a file.
        description: The description of this file. Must be 1000 characters or less.
        parent_id: The ID of the Entity that is the parent of this Entity. Setting
            this to a new value and storing it will move this File under the new
            parent.
        version_label: The version label for this entity. Updates to the entity will
            increment the version number.
        version_comment: The version comment for this entity.
        data_file_handle_id: ID of the file handle associated with this entity. You
            may define an existing data_file_handle_id to use the existing
            data_file_handle_id. The creator of the file must also be the owner of
            the data_file_handle_id to have permission to store the file.
        activity: The Activity model represents the main record of Provenance in
            Synapse.  It is analygous to the Activity defined in the
            [W3C Specification](https://www.w3.org/TR/prov-n/) on Provenance.
            Activity cannot be removed during a store operation by setting it to None.
            You must use: [synapseclient.models.Activity.delete_async][] or
            [synapseclient.models.Activity.disassociate_from_entity_async][].
        annotations: Additional metadata associated with the entity. 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 `{}`.
        upsert_keys: One or more column names that define this upsert key for this
            set. This key is used to determine if a new record should be treated as
            an update or an insert.
        csv_descriptor: The description of a CSV for upload or download.
        validation_summary: Summary statistics for the JSON schema validation results
            for the children of an Entity container (Project or Folder).
        file_name_override: An optional replacement for the name of the uploaded
            file. This is distinct from the entity name. If omitted the file will
            retain its original name.
        validation_file_handle_id: (Read Only) Pointer to a CSV file that contains the
            detailed validation results for each row in the record set. The CSV file
            will contain for each row the following columns: row_index, is_valid,
            validation_error_message, all_validation_messages. Generated only from a
            grid session export, cannot be changed by the user.
        content_type: (New Upload Only) Used to manually specify Content-type header,
            for example 'application/png' or 'application/json; charset=UTF-8'. If not
            specified, the content type will be derived from the file extension.

            This can be specified only during the initial store of this file. In order
            to change this after the File has been created use
            [synapseclient.models.File.change_metadata][].
        content_size: (New Upload Only) The size of the file in bytes. This can be
            specified only during the initial creation of the File. This is also only
            applicable to files not uploaded to Synapse. ie: `synapse_store` is False.
        content_md5: (Store only) The MD5 of the file is known. If not supplied this
            will be computed in the client is possible. If supplied for a file entity
            already stored in Synapse it will be calculated again to check if a new
            upload needs to occur. This will not be filled in during a read for data.
            It is only used during a store operation. To retrieve the md5 of the file
            after read from synapse use the `.file_handle.content_md5` attribute.
        create_or_update: (Store only) Indicates whether the method should
            automatically perform an update if the file conflicts with an existing
            Synapse object.
        force_version: (Store only) Indicates whether the method should increment the
            version of the object if something within the entity has changed. For
            example updating the description or name. You may set this to False and
            an update to the entity will not increment the version.

            Updating the `version_label` attribute will also cause a version update
            regardless of this flag.

            An update to the MD5 of the file will force a version update regardless
            of this flag.
        is_restricted: (Store only) If set to true, an email will be sent to the
            Synapse access control team to start the process of adding terms-of-use
            or review board approval for this entity. You will be contacted with
            regards to the specific data being restricted and the requirements of
            access.

            This may be used only by an administrator of the specified file.
        merge_existing_annotations: (Store only) Works in conjunction with
            `create_or_update` in that this is only evaluated if `create_or_update`
            is True. If this entity exists in Synapse that has annotations that are
            not present in a store operation, these annotations will be added to the
            entity. If this is False any annotations that are not present within a
            store operation will be removed from this entity. This allows one to
            complete a destructive update of annotations on an entity.
        associate_activity_to_new_version: (Store only) Works in conjunction with
            `create_or_update` in that this is only evaluated if `create_or_update`
            is True. When true an activity already attached to the current version of
            this entity will be associated the new version during a store operation
            if the version was updated. This is useful if you are updating the entity
            and want to ensure that the activity is persisted onto the new version
            the entity.

            When this is False the activity will not be associated to the new version
            of the entity during a store operation.

            Regardless of this setting, if you have an Activity object on the entity
            it will be persisted onto the new version. This is only used when you
            don't have an Activity object on the entity.
        synapse_store: (Store only) Whether the File should be uploaded or if false:
            only the path should be stored when [synapseclient.models.File.store][]
            is called.
        download_file: (Get only) If True the file will be downloaded.
        if_collision: (Get only) Determines how to handle file collisions. Defaults
            to "keep.both". May be:

            - `overwrite.local`
            - `keep.local`
            - `keep.both`
        synapse_container_limit: (Get only) A Synanpse ID used to limit the search in
            Synapse if file is specified as a local file. That is, if the file is
            stored in multiple locations in Synapse only the ones in the specified
            folder/project will be returned.
        etag: (Read Only) 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: (Read Only) The date this entity was created.
        modified_on: (Read Only) The date this entity was last modified.
        created_by: (Read Only) The ID of the user that created this entity.
        modified_by: (Read Only) The ID of the user that last modified this entity.
        version_number: (Read Only) The version number issued to this version on the
            object.
        is_latest_version: (Read Only) If this is the latest version of the object.
        file_handle: (Read Only) The file handle associated with this entity.
    """

    id: Optional[str] = None
    """The unique immutable ID for this file. A new ID will be generated for new Files.
    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. If not specified, the name will be
    derived from the file name.
    """

    path: Optional[str] = field(default=None, compare=False)
    """The path to the file on disk. Using shorthand `~` will be expanded to the user's
    home directory.

    This is used during a `get` operation to specify where to download the file to. It
    should be pointing to a directory.

    This is also used during a `store` operation to specify the file to upload. It
    should be pointing to a file."""

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

    parent_id: Optional[str] = None
    """The ID of the Entity that is the parent of this Entity. Setting this to a new
    value and storing it will move this File under the new parent."""

    version_label: Optional[str] = None
    """The version label for this entity. Updates to the entity will increment the
    version number."""

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

    data_file_handle_id: Optional[str] = None
    """
    ID of the file handle associated with this entity. You may define an existing
    data_file_handle_id to use the existing data_file_handle_id. The creator of the
    file must also be the owner of the data_file_handle_id to have permission to
    store the file.
    """

    activity: Optional[Activity] = field(default=None, compare=False)
    """The Activity model represents the main record of Provenance in Synapse.  It is
    analygous to the Activity defined in the
    [W3C Specification](https://www.w3.org/TR/prov-n/) on Provenance. Activity cannot
    be removed during a store operation by setting it to None. You must use:
    [synapseclient.models.Activity.delete_async][] or
    [synapseclient.models.Activity.disassociate_from_entity_async][].
    """

    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 folder. 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 `{}`."""

    upsert_keys: Optional[List[str]] = field(default_factory=list)
    """One or more column names that define this upsert key for this set. This key is
    used to determine if a new record should be treated as an update or an insert.
    """

    csv_descriptor: Optional["CsvTableDescriptor"] = field(default=None)
    """The description of a CSV for upload or download."""

    validation_summary: Optional[ValidationSummary] = field(default=None, compare=False)
    """Summary statistics for the JSON schema validation results for the children of
    an Entity container (Project or Folder)"""

    file_name_override: Optional[str] = None
    """An optional replacement for the name of the uploaded file. This is distinct from
    the entity name. If omitted the file will retain its original name.
    """

    validation_file_handle_id: Optional[str] = None
    """
    (Read Only) Pointer to a CSV file that contains the detailed validation results for
    each row in the record set. The CSV file will contain for each row the following
    columns: row_index, is_valid, validation_error_message, all_validation_messages.
    Generated only from a grid session export, cannot be changed by the user.
    """

    content_type: Optional[str] = None
    """
    (New Upload Only)
    Used to manually specify Content-type header, for example 'application/png'
    or 'application/json; charset=UTF-8'. If not specified, the content type will be
    derived from the file extension.

    This can be specified only during the initial store of this file. In order to change
    this after the File has been created use
    [synapseclient.models.File.change_metadata][].
    """

    content_size: Optional[int] = None
    """
    (New Upload Only)
    The size of the file in bytes. This can be specified only during the initial
    creation of the File. This is also only applicable to files not uploaded to Synapse.
    ie: `synapse_store` is False.
    """

    content_md5: Optional[str] = field(default=None, compare=False)
    """
    (Store only)
    The MD5 of the file is known. If not supplied this will be computed in the client
    is possible. If supplied for a file entity already stored in Synapse it will be
    calculated again to check if a new upload needs to occur. This will not be filled
    in during a read for data. It is only used during a store operation. To retrieve
    the md5 of the file after read from synapse use the `.file_handle.content_md5`
    attribute.
    """

    create_or_update: bool = field(default=True, repr=False, compare=False)
    """
    (Store only)

    Indicates whether the method should automatically perform an update if the file
    conflicts with an existing Synapse object.
    """

    force_version: bool = field(default=True, repr=False, compare=False)
    """
    (Store only)

    Indicates whether the method should increment the version of the object if something
    within the entity has changed. For example updating the description or name.
    You may set this to False and an update to the entity will not increment the
    version.

    Updating the `version_label` attribute will also cause a version update regardless
    of this flag.

    An update to the MD5 of the file will force a version update regardless of this
    flag.
    """

    is_restricted: bool = field(default=False, repr=False)
    """
    (Store only)

    If set to true, an email will be sent to the Synapse access control team to start
    the process of adding terms-of-use or review board approval for this entity.
    You will be contacted with regards to the specific data being restricted and the
    requirements of access.

    This may be used only by an administrator of the specified file.
    """

    merge_existing_annotations: bool = field(default=True, repr=False, compare=False)
    """
    (Store only)

    Works in conjunction with `create_or_update` in that this is only evaluated if
    `create_or_update` is True. If this entity exists in Synapse that has annotations
    that are not present in a store operation, these annotations will be added to the
    entity. If this is False any annotations that are not present within a store
    operation will be removed from this entity. This allows one to complete a
    destructive update of annotations on an entity.
    """

    associate_activity_to_new_version: bool = field(
        default=False, repr=False, compare=False
    )
    """
    (Store only)

    Works in conjunction with `create_or_update` in that this is only evaluated if
    `create_or_update` is True. When true an activity already attached to the current
    version of this entity will be associated the new version during a store operation
    if the version was updated. This is useful if you are updating the entity and want
    to ensure that the activity is persisted onto the new version the entity.

    When this is False the activity will not be associated to the new version of the
    entity during a store operation.

    Regardless of this setting, if you have an Activity object on the entity it will be
    persisted onto the new version. This is only used when you don't have an Activity
    object on the entity.
    """

    synapse_store: bool = field(default=True, repr=False)
    """
    (Store only)

    Whether the File should be uploaded or if false: only the path should be stored when
    [synapseclient.models.File.store][] is called.
    """

    download_file: bool = field(default=True, repr=False, compare=False)
    """
    (Get only)

    If True the file will be downloaded."""

    if_collision: str = field(default="keep.both", repr=False, compare=False)
    """
    (Get only)

    Determines how to handle file collisions. Defaults to "keep.both".
            May be

            - `overwrite.local`
            - `keep.local`
            - `keep.both`
    """

    synapse_container_limit: Optional[str] = field(
        default=None, repr=False, compare=False
    )
    """A Synanpse ID used to limit the search in Synapse if file is specified as a local
    file. That is, if the file is stored in multiple locations in Synapse only the
    ones in the specified folder/project will be returned."""

    etag: Optional[str] = field(default=None, compare=False)
    """
    (Read Only)
    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)
    """(Read Only) The date this entity was created."""

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

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

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

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

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

    file_handle: Optional["FileHandle"] = field(default=None, compare=False)
    """(Read Only) The file handle associated with this entity."""

    _last_persistent_instance: Optional["RecordSet"] = 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."""

    @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
        )

    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.annotations = (
            deepcopy(self.annotations) if self.annotations else {}
        )

    def _fill_from_file_handle(self) -> None:
        """Fill the file object from the file handle."""
        if self.file_handle:
            self.data_file_handle_id = self.file_handle.id
            self.content_type = self.file_handle.content_type
            self.content_size = self.file_handle.content_size

    def fill_from_dict(
        self,
        entity: Dict[str, Union[bool, str, int]],
        set_annotations: bool = True,
    ) -> "RecordSet":
        """
        Converts a response from the REST API into this dataclass.

        This method populates the RecordSet instance with data from a Synapse REST API
        response or a dictionary containing RecordSet information. It handles the
        conversion from Synapse API field names (camelCase) to Python attribute names
        (snake_case) and processes nested objects appropriately.

        Arguments:
            synapse_file: The response from the REST API or a dictionary containing
                RecordSet data. Can be either a Synapse_File object or a dictionary
                with string keys and various value types.
            set_annotations: Whether to set the annotations from the response.
                If True, annotations will be populated from the API response.

        Returns:
            The RecordSet object with updated attributes from the API response.
        """
        self.id = entity.get("id", None)
        self.name = entity.get("name", None)
        self.description = entity.get("description", None)
        self.etag = entity.get("etag", None)
        self.created_on = entity.get("createdOn", None)
        self.modified_on = entity.get("modifiedOn", None)
        self.created_by = entity.get("createdBy", None)
        self.modified_by = entity.get("modifiedBy", None)
        self.parent_id = entity.get("parentId", 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", False)
        self.data_file_handle_id = entity.get("dataFileHandleId", None)
        self.path = entity.get("path", self.path)
        self.file_name_override = entity.get("fileNameOverride", None)
        self.validation_file_handle_id = entity.get("validationFileHandleId", None)
        csv_descriptor = entity.get("csvDescriptor", None)
        if csv_descriptor:
            from synapseclient.models import CsvTableDescriptor

            self.csv_descriptor = CsvTableDescriptor().fill_from_dict(csv_descriptor)

        validation_summary = entity.get("validationSummary", None)

        if validation_summary:
            self.validation_summary = ValidationSummary(
                container_id=validation_summary.get("containerId", None),
                total_number_of_children=validation_summary.get(
                    "totalNumberOfChildren", None
                ),
                number_of_valid_children=validation_summary.get(
                    "numberOfValidChildren", None
                ),
                number_of_invalid_children=validation_summary.get(
                    "numberOfInvalidChildren", None
                ),
                number_of_unknown_children=validation_summary.get(
                    "numberOfUnknownChildren", None
                ),
                generated_on=validation_summary.get("generatedOn", None),
            )

        self.upsert_keys = entity.get("upsertKey", [])

        synapse_file_handle = entity.get("_file_handle", None)
        if synapse_file_handle:
            from synapseclient.models import FileHandle

            file_handle = self.file_handle or FileHandle()
            self.file_handle = file_handle.fill_from_dict(
                synapse_instance=synapse_file_handle
            )
            self._fill_from_file_handle()

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

    def _cannot_store(self) -> bool:
        """
        Determines based on guard conditions if a store operation can proceed.
        """
        return (
            not (
                self.id is not None
                and (self.path is not None or self.data_file_handle_id is not None)
            )
            and not (self.path is not None and self.parent_id is not None)
            and not (
                self.parent_id is not None and self.data_file_handle_id is not None
            )
        )

    async def _load_local_md5(self) -> None:
        """
        Load the MD5 hash of a local file if it exists and hasn't been loaded yet.

        This method computes and sets the content_md5 attribute for local files
        that exist on disk. It only performs the calculation if the content_md5
        is not already set and the path points to an existing file.
        """
        if not self.content_md5 and self.path and os.path.isfile(self.path):
            self.content_md5 = utils.md5_for_file_hex(filename=self.path)

    async def _find_existing_entity(
        self, *, synapse_client: Optional[Synapse] = None
    ) -> Union["RecordSet", None]:
        """
        Determines if the RecordSet already exists in Synapse.

        This method searches for an existing RecordSet in Synapse that matches the
        current instance. If found, it returns the existing RecordSet object, otherwise
        it returns None. This is used to determine if the RecordSet should be updated
        or created during a store operation.

        Arguments:
            synapse_client: If not passed in and caching was not disabled, this will
                use the last created instance from the Synapse class constructor.

        Returns:
            The existing RecordSet object if it exists in Synapse, None otherwise.
        """

        async def get_entity(existing_id: str) -> "RecordSet":
            """Small wrapper to retrieve a file instance without raising an error if it
            does not exist.

            Arguments:
                existing_id: The ID of the file to retrieve.

            Returns:
                The file object if it exists, otherwise None.
            """
            try:
                entity_copy = RecordSet(
                    id=existing_id,
                    download_file=False,
                    version_number=self.version_number,
                    synapse_container_limit=self.synapse_container_limit,
                    parent_id=self.parent_id,
                )
                return await entity_copy.get_async(
                    synapse_client=synapse_client,
                    include_activity=self.activity is not None
                    or self.associate_activity_to_new_version,
                )
            except SynapseFileNotFoundError:
                return None

        if (
            self.create_or_update
            and not self._last_persistent_instance
            and (
                existing_entity_id := await get_id(
                    entity=self,
                    failure_strategy=None,
                    synapse_client=synapse_client,
                )
            )
            and (existing_file := await get_entity(existing_entity_id))
        ):
            return existing_file
        return None

    def _determine_fields_to_ignore_in_merge(self) -> List[str]:
        """
        Determine which fields should not be merged when merging two entities.

        This method returns a list of field names that should be ignored during
        entity merging operations. This allows for fine-tuned destructive updates
        of an entity based on the current configuration settings.

        The method has special handling for manifest uploads where specific fields
        are provided in the manifest and should take precedence over existing
        entity values.

        Returns:
            A list of field names that should not be merged from the existing entity.
        """
        fields_to_not_merge = []
        if not self.merge_existing_annotations:
            fields_to_not_merge.append("annotations")

        if not self.associate_activity_to_new_version:
            fields_to_not_merge.append("activity")

        return fields_to_not_merge

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        This method transforms the RecordSet object into a dictionary format that
        matches the structure expected by the Synapse REST API. It handles the
        conversion of Python snake_case attribute names to the camelCase format
        used by the API, and ensures that nested objects are properly serialized.

        Returns:
            A dictionary representation of this object formatted for API requests.
            None values are automatically removed from the dictionary.

        Example: Converting a RecordSet for API submission
            This method is used internally when storing or updating RecordSets:

            ```python
            from synapseclient.models import RecordSet

            record_set = RecordSet(
                name="My RecordSet",
                description="A test record set",
                parent_id="syn123456"
            )
            api_dict = record_set.to_synapse_request()
            # api_dict contains properly formatted data for the REST API
            ```
        """

        entity = {
            "concreteType": concrete_types.RECORD_SET_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,
            "versionNumber": self.version_number,
            "versionLabel": self.version_label,
            "versionComment": self.version_comment,
            "isLatestVersion": self.is_latest_version,
            "dataFileHandleId": self.data_file_handle_id,
            "upsertKey": self.upsert_keys,
            "csvDescriptor": (
                self.csv_descriptor.to_synapse_request()
                if self.csv_descriptor
                else None
            ),
            "validationSummary": (
                {
                    "containerId": self.validation_summary.container_id,
                    "totalNumberOfChildren": self.validation_summary.total_number_of_children,
                    "numberOfValidChildren": self.validation_summary.number_of_valid_children,
                    "numberOfInvalidChildren": self.validation_summary.number_of_invalid_children,
                    "numberOfUnknownChildren": self.validation_summary.number_of_unknown_children,
                    "generatedOn": self.validation_summary.generated_on,
                }
                if self.validation_summary
                else None
            ),
            "fileNameOverride": self.file_name_override,
        }
        delete_none_keys(entity)

        return entity

    async def store_async(
        self,
        parent: Optional[Union["Folder", "Project"]] = None,
        *,
        synapse_client: Optional[Synapse] = None,
    ) -> "RecordSet":
        """
        Store the RecordSet in Synapse.

        This method uploads or updates a RecordSet in Synapse. It can handle both
        creating new RecordSets and updating existing ones based on the
        `create_or_update` flag. The method supports file uploads, metadata updates,
        and merging with existing entities when appropriate.

        Arguments:
            parent: The parent Folder or Project for this RecordSet. If provided,
                this will override the `parent_id` attribute.
            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 RecordSet object with updated metadata from Synapse after the
            store operation.

        Raises:
            ValueError: If the RecordSet does not have the required information
                for storing. Must have either: (ID with path or data_file_handle_id),
                or (path with parent_id), or (data_file_handle_id with parent_id).

        Example: Storing a new RecordSet
            Creating and storing a new RecordSet in Synapse:

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

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

                record_set = RecordSet(
                    name="My RecordSet",
                    description="A dataset for analysis",
                    parent_id="syn123456",
                    path="/path/to/data.csv"
                )
                stored_record_set = await record_set.store_async()
                print(f"Stored RecordSet with ID: {stored_record_set.id}")

            asyncio.run(main())
            ```

            Updating an existing RecordSet:
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import RecordSet

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

                record_set = await RecordSet(id="syn789012").get_async()
                record_set.description = "Updated description"
                updated_record_set = await record_set.store_async()

            asyncio.run(main())
            ```
        """
        self.parent_id = parent.id if parent else self.parent_id
        if self._cannot_store():
            raise ValueError(
                "The file must have an (ID with a (path or `data_file_handle_id`)), or a "
                "(path with a (`parent_id` or parent with an id)), or a "
                "(data_file_handle_id with a (`parent_id` or parent with an id)) to store."
            )
        self.name = self.name or (guess_file_name(self.path) if self.path else None)
        client = Synapse.get_client(synapse_client=synapse_client)

        if existing_file := await self._find_existing_entity(synapse_client=client):
            merge_dataclass_entities(
                source=existing_file,
                destination=self,
                fields_to_ignore=self._determine_fields_to_ignore_in_merge(),
            )

        if self.id:
            trace.get_current_span().set_attributes(
                {
                    "synapse.id": self.id,
                }
            )

        if self.path:
            self.path = os.path.expanduser(self.path)
            async with client._get_parallel_file_transfer_semaphore(
                asyncio_event_loop=asyncio.get_running_loop()
            ):
                from synapseclient.models.file import _upload_file

                await _upload_file(entity_to_upload=self, synapse_client=client)
        elif self.data_file_handle_id:
            self.path = client.cache.get(file_handle_id=self.data_file_handle_id)

        if self.has_changed:
            entity = await store_entity(
                resource=self, entity=self.to_synapse_request(), synapse_client=client
            )

            self.fill_from_dict(entity=entity, set_annotations=False)

        re_read_required = await store_entity_components(
            root_resource=self, synapse_client=client
        )
        if re_read_required:
            before_download_file = self.download_file
            self.download_file = False
            await self.get_async(
                synapse_client=client,
            )
            self.download_file = before_download_file

        self._set_last_persistent_instance()

        client.logger.debug(f"Stored File {self.name}, id: {self.id}: {self.path}")
        # Clear the content_md5 so that it is recalculated if the file is updated
        self.content_md5 = None
        return self

    async def get_async(
        self,
        include_activity: bool = False,
        *,
        synapse_client: Optional[Synapse] = None,
    ) -> "RecordSet":
        """
        Get the RecordSet from Synapse.

        This method retrieves a RecordSet entity from Synapse. You may retrieve
        a RecordSet by either its ID or path. If you specify both, the ID will
        take precedence.

        If you specify the path and the RecordSet is stored in multiple locations
        in Synapse, only the first one found will be returned. The other matching
        RecordSets will be printed to the console.

        You may also specify a `version_number` to get a specific version of the
        RecordSet.

        Arguments:
            include_activity: If True, the activity will be included in the RecordSet
                if it exists.
            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 RecordSet object with data populated from Synapse.

        Raises:
            ValueError: If the RecordSet does not have an ID or path to retrieve.

        Example: Retrieving a RecordSet by ID
            Get an existing RecordSet from Synapse:

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

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

                record_set = await RecordSet(id="syn123").get_async()
                print(f"RecordSet name: {record_set.name}")

            asyncio.run(main())
            ```

            Downloading a RecordSet to a specific directory:
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import RecordSet

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

                record_set = await RecordSet(
                    id="syn123",
                    path="/path/to/download/directory"
                ).get_async()

            asyncio.run(main())
            ```

            Including activity information:
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import RecordSet

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

                record_set = await RecordSet(id="syn123").get_async(include_activity=True)
                if record_set.activity:
                    print(f"Activity: {record_set.activity.name}")

            asyncio.run(main())
            ```
        """
        if not self.id and not self.path:
            raise ValueError("The file must have an ID or path to get.")
        syn = Synapse.get_client(synapse_client=synapse_client)

        await self._load_local_md5()

        await get_from_entity_factory(
            entity_to_update=self,
            synapse_id_or_path=self.id or self.path,
            version=self.version_number,
            if_collision=self.if_collision,
            limit_search=self.synapse_container_limit or self.parent_id,
            download_file=self.download_file,
            download_location=(
                os.path.dirname(self.path)
                if self.path and os.path.isfile(self.path)
                else self.path
            ),
            md5=self.content_md5,
            synapse_client=syn,
        )

        if (
            self.data_file_handle_id
            and (not self.path or (self.path and not os.path.isfile(self.path)))
            and (cached_path := syn.cache.get(file_handle_id=self.data_file_handle_id))
        ):
            self.path = cached_path

        if include_activity:
            self.activity = await Activity.from_parent_async(
                parent=self, synapse_client=synapse_client
            )

        self._set_last_persistent_instance()
        Synapse.get_client(synapse_client=synapse_client).logger.debug(
            f"Got file {self.name}, id: {self.id}, path: {self.path}"
        )
        return self

    async def get_detailed_validation_results_async(
        self,
        download_location: Optional[str] = None,
        *,
        synapse_client: Optional[Synapse] = None,
    ) -> DATA_FRAME_TYPE:
        """
        Get detailed validation results for the RecordSet as a pandas DataFrame.

        This method downloads a CSV file containing detailed validation results for each row
        in the RecordSet. The validation results are generated when a RecordSet with a bound
        JSON schema is synchronized (pushed) from a Grid session. The CSV contains columns:
        - row_index: The index of the row in the RecordSet
        - is_valid: Boolean indicating if the row is valid according to the schema
        - validation_error_message: The primary validation error message (if any)
        - all_validation_messages: All validation messages for the row (if any)

        Arguments:
            download_location: Optional directory path where the validation results CSV
                should be downloaded. If not specified, the file will be downloaded to
                the Synapse cache directory. If the file is already cached, it will use
                the cached version unless a different download_location is specified.
            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 pandas DataFrame containing the validation results, or None if no
            validation_file_handle_id is available (with a warning logged).

        Example: Get validation results for a RecordSet
            Get detailed validation results after synchronizing from a Grid session:

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import RecordSet, Grid
            from synapseclient.models.curation import SyncType

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

                # Assuming you have a RecordSet with a bound schema
                record_set = await RecordSet(id="syn123").get_async()

                # Create and push a Grid session to generate validation results
                grid = await Grid(record_set_id=record_set.id).create_async()
                await grid.synchronize_async(sync_type=SyncType.PULL_PUSH)
                await grid.delete_async()

                # Re-fetch the RecordSet to get updated validation_file_handle_id
                record_set = await record_set.get_async()

                # Get the detailed validation results
                results_df = await record_set.get_detailed_validation_results_async()

                # Analyze the results
                print(f"Total rows: {len(results_df)}")
                print(f"Columns: {results_df.columns.tolist()}")

                # Filter for valid and invalid rows
                # Note: is_valid is boolean (True/False) for validated rows
                valid_rows = results_df[results_df['is_valid'] == True]  # noqa: E712
                invalid_rows = results_df[results_df['is_valid'] == False]  # noqa: E712

                print(f"Valid rows: {len(valid_rows)}")
                print(f"Invalid rows: {len(invalid_rows)}")

                # View invalid rows with their error messages
                if len(invalid_rows) > 0:
                    print(invalid_rows[['row_index', 'validation_error_message']])

            asyncio.run(main())
            ```
        """
        test_import_pandas()
        import pandas as pd

        client = Synapse.get_client(synapse_client=synapse_client)

        if not self.validation_file_handle_id:
            client.logger.warning(
                "No validation file handle ID found for this RecordSet. Cannot retrieve detailed validation results."
            )
            return None

        cached_file_path = client.cache.get(
            file_handle_id=self.validation_file_handle_id, path=download_location
        )

        # location in .synapseCache where the file would be corresponding to its FileHandleId
        synapse_cache_location = client.cache.get_cache_dir(
            file_handle_id=self.validation_file_handle_id
        )

        if download_location is not None:
            # Make sure the specified download location is a fully resolved directory
            download_location = ensure_download_location_is_directory(download_location)
        elif cached_file_path is not None:
            # file already cached so use that as the download location
            download_location = os.path.dirname(cached_file_path)
        else:
            # file not cached and no user-specified location so default to .synapseCache
            download_location = synapse_cache_location

        # Generate filename for the validation results CSV
        filename = f"SYNAPSE_RECORDSET_VALIDATION_{self.validation_file_handle_id}.csv"
        destination_path = os.path.join(download_location, filename)

        validation_file_path = await download_by_file_handle(
            file_handle_id=self.validation_file_handle_id,
            synapse_id=self.id,
            entity_type="FileEntity",
            destination=destination_path,
            synapse_client=client,
        )

        return pd.read_csv(validation_file_path)

    async def delete_async(
        self,
        version_only: Optional[bool] = False,
        *,
        synapse_client: Optional[Synapse] = None,
    ) -> None:
        """
        Delete the RecordSet from Synapse using its ID.

        This method removes a RecordSet entity from Synapse. You can choose to
        delete either a specific version or the entire RecordSet including all
        its versions.

        Arguments:
            version_only: If True, only the version specified in the `version_number`
                attribute of the RecordSet will be deleted. If False, the entire
                RecordSet including all versions will be deleted.
            synapse_client: If not passed in and caching was not disabled by
                `Synapse.allow_client_caching(False)`, this will use the last created
                instance from the Synapse class constructor.

        Returns:
            None

        Raises:
            ValueError: If the RecordSet does not have an ID to delete.
            ValueError: If the RecordSet does not have a version number to delete a
                specific version, and `version_only` is True.

        Example: Deleting a RecordSet
            Delete an entire RecordSet and all its versions:

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

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

                await RecordSet(id="syn123").delete_async()

            asyncio.run(main())
            ```

            Delete only a specific version:
            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import RecordSet

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

                record_set = RecordSet(id="syn123", version_number=2)
                await record_set.delete_async(version_only=True)

            asyncio.run(main())
            ```
        """
        if not self.id:
            raise ValueError("The file must have an ID to delete.")
        if version_only and not self.version_number:
            raise ValueError("The file must have a version number to delete a version.")

        loop = asyncio.get_event_loop()
        await loop.run_in_executor(
            None,
            lambda: Synapse.get_client(synapse_client=synapse_client).delete(
                obj=self.id,
                version=self.version_number if version_only else None,
            ),
        )
        Synapse.get_client(synapse_client=synapse_client).logger.debug(
            f"Deleted file {self.id}"
        )

Methods:¶

get ¶

get(include_activity: bool = False, *, synapse_client: Optional[Synapse] = None) -> RecordSet

Get the RecordSet from Synapse.

This method retrieves a RecordSet entity from Synapse. You may retrieve a RecordSet by either its ID or path. If you specify both, the ID will take precedence.

If you specify the path and the RecordSet is stored in multiple locations in Synapse, only the first one found will be returned. The other matching RecordSets will be printed to the console.

You may also specify a version_number to get a specific version of the RecordSet.

PARAMETER	DESCRIPTION
`include_activity`	If True, the activity will be included in the RecordSet if it exists. 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
`RecordSet`	The RecordSet object with data populated from Synapse.

RAISES	DESCRIPTION
`ValueError`	If the RecordSet does not have an ID or path to retrieve.

Retrieving a RecordSet by ID

Get an existing RecordSet from Synapse:

from synapseclient import Synapse
from synapseclient.models import RecordSet

syn = Synapse()
syn.login()

record_set = RecordSet(id="syn123").get()
print(f"RecordSet name: {record_set.name}")

Downloading a RecordSet to a specific directory:

from synapseclient import Synapse
from synapseclient.models import RecordSet

syn = Synapse()
syn.login()

record_set = RecordSet(
    id="syn123",
    path="/path/to/download/directory"
).get()

Including activity information:

from synapseclient import Synapse
from synapseclient.models import RecordSet

syn = Synapse()
syn.login()

record_set = RecordSet(id="syn123").get(include_activity=True)
if record_set.activity:
    print(f"Activity: {record_set.activity.name}")

Source code in synapseclient/models/recordset.py

def get(
    self,
    include_activity: bool = False,
    *,
    synapse_client: Optional[Synapse] = None,
) -> "RecordSet":
    """
    Get the RecordSet from Synapse.

    This method retrieves a RecordSet entity from Synapse. You may retrieve
    a RecordSet by either its ID or path. If you specify both, the ID will
    take precedence.

    If you specify the path and the RecordSet is stored in multiple locations
    in Synapse, only the first one found will be returned. The other matching
    RecordSets will be printed to the console.

    You may also specify a `version_number` to get a specific version of the
    RecordSet.

    Arguments:
        include_activity: If True, the activity will be included in the RecordSet
            if it exists.
        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 RecordSet object with data populated from Synapse.

    Raises:
        ValueError: If the RecordSet does not have an ID or path to retrieve.

    Example: Retrieving a RecordSet by ID
        Get an existing RecordSet from Synapse:

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

        syn = Synapse()
        syn.login()

        record_set = RecordSet(id="syn123").get()
        print(f"RecordSet name: {record_set.name}")
        ```

        Downloading a RecordSet to a specific directory:
        ```python
        from synapseclient import Synapse
        from synapseclient.models import RecordSet

        syn = Synapse()
        syn.login()

        record_set = RecordSet(
            id="syn123",
            path="/path/to/download/directory"
        ).get()
        ```

        Including activity information:
        ```python
        from synapseclient import Synapse
        from synapseclient.models import RecordSet

        syn = Synapse()
        syn.login()

        record_set = RecordSet(id="syn123").get(include_activity=True)
        if record_set.activity:
            print(f"Activity: {record_set.activity.name}")
        ```
    """
    return self

store ¶

store(parent: Optional[Union[Folder, Project]] = None, *, synapse_client: Optional[Synapse] = None) -> RecordSet

Store the RecordSet in Synapse.

This method uploads or updates a RecordSet in Synapse. It can handle both creating new RecordSets and updating existing ones based on the create_or_update flag. The method supports file uploads, metadata updates, and merging with existing entities when appropriate.

PARAMETER	DESCRIPTION
`parent`	The parent Folder or Project for this RecordSet. If provided, this will override the `parent_id` attribute. TYPE: `Optional[Union[Folder, Project]]` DEFAULT: `None`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)`, this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`RecordSet`	The RecordSet object with updated metadata from Synapse after the
`RecordSet`	store operation.

RAISES	DESCRIPTION
`ValueError`	If the RecordSet does not have the required information for storing. Must have either: (ID with path or data_file_handle_id), or (path with parent_id), or (data_file_handle_id with parent_id).

Storing a new RecordSet

Creating and storing a new RecordSet in Synapse:

from synapseclient import Synapse
from synapseclient.models import RecordSet

syn = Synapse()
syn.login()

record_set = RecordSet(
    name="My RecordSet",
    description="A dataset for analysis",
    parent_id="syn123456",
    path="/path/to/data.csv"
)
stored_record_set = record_set.store()
print(f"Stored RecordSet with ID: {stored_record_set.id}")

Updating an existing RecordSet:

from synapseclient import Synapse
from synapseclient.models import RecordSet

syn = Synapse()
syn.login()

record_set = RecordSet(id="syn789012").get()
record_set.description = "Updated description"
updated_record_set = record_set.store()

Source code in synapseclient/models/recordset.py

def store(
    self,
    parent: Optional[Union["Folder", "Project"]] = None,
    *,
    synapse_client: Optional[Synapse] = None,
) -> "RecordSet":
    """
    Store the RecordSet in Synapse.

    This method uploads or updates a RecordSet in Synapse. It can handle both
    creating new RecordSets and updating existing ones based on the
    `create_or_update` flag. The method supports file uploads, metadata updates,
    and merging with existing entities when appropriate.

    Arguments:
        parent: The parent Folder or Project for this RecordSet. If provided,
            this will override the `parent_id` attribute.
        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 RecordSet object with updated metadata from Synapse after the
        store operation.

    Raises:
        ValueError: If the RecordSet does not have the required information
            for storing. Must have either: (ID with path or data_file_handle_id),
            or (path with parent_id), or (data_file_handle_id with parent_id).

    Example: Storing a new RecordSet
        Creating and storing a new RecordSet in Synapse:

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

        syn = Synapse()
        syn.login()

        record_set = RecordSet(
            name="My RecordSet",
            description="A dataset for analysis",
            parent_id="syn123456",
            path="/path/to/data.csv"
        )
        stored_record_set = record_set.store()
        print(f"Stored RecordSet with ID: {stored_record_set.id}")
        ```

        Updating an existing RecordSet:
        ```python
        from synapseclient import Synapse
        from synapseclient.models import RecordSet

        syn = Synapse()
        syn.login()

        record_set = RecordSet(id="syn789012").get()
        record_set.description = "Updated description"
        updated_record_set = record_set.store()

        ```
    """
    return self

delete ¶

delete(version_only: Optional[bool] = False, *, synapse_client: Optional[Synapse] = None) -> None

Delete the RecordSet from Synapse using its ID.

This method removes a RecordSet entity from Synapse. You can choose to delete either a specific version or the entire RecordSet including all its versions.

PARAMETER	DESCRIPTION
`version_only`	If True, only the version specified in the `version_number` attribute of the RecordSet will be deleted. If False, the entire RecordSet including all versions will be deleted. TYPE: `Optional[bool]` DEFAULT: `False`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)`, this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`None`	None

RAISES	DESCRIPTION
`ValueError`	If the RecordSet does not have an ID to delete.
`ValueError`	If the RecordSet does not have a version number to delete a specific version, and `version_only` is True.

Deleting a RecordSet

Delete an entire RecordSet and all its versions:

from synapseclient import Synapse
from synapseclient.models import RecordSet

syn = Synapse()
syn.login()

RecordSet(id="syn123").delete()

Delete only a specific version:

from synapseclient import Synapse
from synapseclient.models import RecordSet

syn = Synapse()
syn.login()

record_set = RecordSet(id="syn123", version_number=2)
record_set.delete(version_only=True)

Source code in synapseclient/models/recordset.py

def delete(
    self,
    version_only: Optional[bool] = False,
    *,
    synapse_client: Optional[Synapse] = None,
) -> None:
    """
    Delete the RecordSet from Synapse using its ID.

    This method removes a RecordSet entity from Synapse. You can choose to
    delete either a specific version or the entire RecordSet including all
    its versions.

    Arguments:
        version_only: If True, only the version specified in the `version_number`
            attribute of the RecordSet will be deleted. If False, the entire
            RecordSet including all versions will be deleted.
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)`, this will use the last created
            instance from the Synapse class constructor.

    Returns:
        None

    Raises:
        ValueError: If the RecordSet does not have an ID to delete.
        ValueError: If the RecordSet does not have a version number to delete a
            specific version, and `version_only` is True.

    Example: Deleting a RecordSet
        Delete an entire RecordSet and all its versions:

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

        syn = Synapse()
        syn.login()

        RecordSet(id="syn123").delete()

        ```

        Delete only a specific version:
        ```python
        from synapseclient import Synapse
        from synapseclient.models import RecordSet

        syn = Synapse()
        syn.login()

        record_set = RecordSet(id="syn123", version_number=2)
        record_set.delete(version_only=True)
        ```
    """
    return None

get_detailed_validation_results ¶

get_detailed_validation_results(download_location: Optional[str] = None, *, synapse_client: Optional[Synapse] = None) -> DataFrame

Get detailed validation results for the RecordSet as a pandas DataFrame.

This method downloads a CSV file containing detailed validation results for each row in the RecordSet. The validation results are generated when a RecordSet with a bound JSON schema is synchronized (pushed) from a Grid session. The CSV contains columns: - row_index: The index of the row in the RecordSet - is_valid: Boolean indicating if the row is valid according to the schema - validation_error_message: The primary validation error message (if any) - all_validation_messages: All validation messages for the row (if any)

PARAMETER	DESCRIPTION
`download_location`	Optional directory path where the validation results CSV should be downloaded. If not specified, the file will be downloaded to the Synapse cache directory. If the file is already cached, it will use the cached version unless a different download_location is specified. TYPE: `Optional[str]` DEFAULT: `None`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)`, this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`DataFrame`	A pandas DataFrame containing the validation results, or None if no
`DataFrame`	validation_file_handle_id is available (with a warning logged).

Get validation results for a RecordSet

Get detailed validation results after synchronizing from a Grid session:

from synapseclient import Synapse
from synapseclient.models import RecordSet, Grid
from synapseclient.models.curation import SyncType

syn = Synapse()
syn.login()

# Assuming you have a RecordSet with a bound schema
record_set = RecordSet(id="syn123").get()

# Create and push a Grid session to generate validation results
grid = Grid(record_set_id=record_set.id).create()
grid.synchronize(sync_type=SyncType.PULL_PUSH)
grid.delete()

# Re-fetch the RecordSet to get updated validation_file_handle_id
record_set = record_set.get()

# Get the detailed validation results
results_df = record_set.get_detailed_validation_results()

# Analyze the results
print(f"Total rows: {len(results_df)}")
print(f"Columns: {results_df.columns.tolist()}")

# Filter for valid and invalid rows
# Note: is_valid is boolean (True/False) for validated rows
valid_rows = results_df[results_df['is_valid'] == True]  # noqa: E712
invalid_rows = results_df[results_df['is_valid'] == False]  # noqa: E712

print(f"Valid rows: {len(valid_rows)}")
print(f"Invalid rows: {len(invalid_rows)}")

# View invalid rows with their error messages
if len(invalid_rows) > 0:
    print(invalid_rows[['row_index', 'validation_error_message']])

Source code in synapseclient/models/recordset.py

def get_detailed_validation_results(
    self,
    download_location: Optional[str] = None,
    *,
    synapse_client: Optional[Synapse] = None,
) -> DATA_FRAME_TYPE:
    """
    Get detailed validation results for the RecordSet as a pandas DataFrame.

    This method downloads a CSV file containing detailed validation results for each row
    in the RecordSet. The validation results are generated when a RecordSet with a bound
    JSON schema is synchronized (pushed) from a Grid session. The CSV contains columns:
    - row_index: The index of the row in the RecordSet
    - is_valid: Boolean indicating if the row is valid according to the schema
    - validation_error_message: The primary validation error message (if any)
    - all_validation_messages: All validation messages for the row (if any)

    Arguments:
        download_location: Optional directory path where the validation results CSV
            should be downloaded. If not specified, the file will be downloaded to
            the Synapse cache directory. If the file is already cached, it will use
            the cached version unless a different download_location is specified.
        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 pandas DataFrame containing the validation results, or None if no
        validation_file_handle_id is available (with a warning logged).

    Example: Get validation results for a RecordSet
        Get detailed validation results after synchronizing from a Grid session:

        ```python
        from synapseclient import Synapse
        from synapseclient.models import RecordSet, Grid
        from synapseclient.models.curation import SyncType

        syn = Synapse()
        syn.login()

        # Assuming you have a RecordSet with a bound schema
        record_set = RecordSet(id="syn123").get()

        # Create and push a Grid session to generate validation results
        grid = Grid(record_set_id=record_set.id).create()
        grid.synchronize(sync_type=SyncType.PULL_PUSH)
        grid.delete()

        # Re-fetch the RecordSet to get updated validation_file_handle_id
        record_set = record_set.get()

        # Get the detailed validation results
        results_df = record_set.get_detailed_validation_results()

        # Analyze the results
        print(f"Total rows: {len(results_df)}")
        print(f"Columns: {results_df.columns.tolist()}")

        # Filter for valid and invalid rows
        # Note: is_valid is boolean (True/False) for validated rows
        valid_rows = results_df[results_df['is_valid'] == True]  # noqa: E712
        invalid_rows = results_df[results_df['is_valid'] == False]  # noqa: E712

        print(f"Valid rows: {len(valid_rows)}")
        print(f"Invalid rows: {len(invalid_rows)}")

        # View invalid rows with their error messages
        if len(invalid_rows) > 0:
            print(invalid_rows[['row_index', 'validation_error_message']])
        ```
    """
    return None

get_acl ¶

get_acl(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/protocols/access_control_protocol.py

def get_acl(
    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 [""]

get_permissions ¶

get_permissions(*, 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

from synapseclient import Synapse
from synapseclient.models import File

syn = Synapse()
syn.login()

permissions = File(id="syn123").get_permissions()

Getting access types list from the Permissions object

permissions.access_types

Source code in synapseclient/models/protocols/access_control_protocol.py

def get_permissions(
    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
        from synapseclient import Synapse
        from synapseclient.models import File

        syn = Synapse()
        syn.login()

        permissions = File(id="syn123").get_permissions()
        ```

        Getting access types list from the Permissions object

        ```
        permissions.access_types
        ```
    """
    return self

set_permissions ¶

set_permissions(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

Setting permissions

Grant all registered users download access

from synapseclient import Synapse
from synapseclient.models import File

syn = Synapse()
syn.login()

File(id="syn123").set_permissions(principal_id=273948, access_type=['READ','DOWNLOAD'])

Grant the public view access

from synapseclient import Synapse
from synapseclient.models import File

syn = Synapse()
syn.login()

File(id="syn123").set_permissions(principal_id=273949, access_type=['READ'])

Source code in synapseclient/models/protocols/access_control_protocol.py

def set_permissions(
    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

    Example: Setting permissions
        Grant all registered users download access

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

        syn = Synapse()
        syn.login()

        File(id="syn123").set_permissions(principal_id=273948, access_type=['READ','DOWNLOAD'])
        ```

        Grant the public view access

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

        syn = Synapse()
        syn.login()

        File(id="syn123").set_permissions(principal_id=273949, access_type=['READ'])
        ```
    """
    return {}

delete_permissions ¶

delete_permissions(include_self: bool = True, include_container_content: bool = False, recursive: bool = False, target_entity_types: Optional[List[str]] = None, dry_run: bool = False, show_acl_details: bool = True, show_files_in_containers: bool = True, *, benefactor_tracker: Optional[BenefactorTracker] = None, synapse_client: Optional[Synapse] = None) -> None

Delete the entire Access Control List (ACL) for a given Entity. This is not scoped to a specific user or group, but rather removes all permissions associated with the Entity. After this operation, the Entity will inherit permissions from its benefactor, which is typically its parent entity or the Project it belongs to.

In order to remove permissions for a specific user or group, you should use the set_permissions method with the access_type set to an empty list.

By default, Entities such as FileEntity and Folder inherit their permission from their containing Project. For such Entities the Project is the Entity's 'benefactor'. This permission inheritance can be overridden by creating an ACL for the Entity. When this occurs the Entity becomes its own benefactor and all permission are determined by its own ACL.

If the ACL of an Entity is deleted, then its benefactor will automatically be set to its parent's benefactor.

Special notice for Projects: The ACL for a Project cannot be deleted, you must individually update or revoke the permissions for each user or group.

PARAMETER	DESCRIPTION
`include_self`	If True (default), delete the ACL of the current entity. If False, skip deleting the ACL of the current entity. TYPE: `bool` DEFAULT: `True`
`include_container_content`	If True, delete ACLs from contents directly within containers (files and folders inside self). This must be set to True for recursive to have any effect. Defaults to False. TYPE: `bool` DEFAULT: `False`
`recursive`	If True and the entity is a container (e.g., Project or Folder), recursively process child containers. Note that this must be used with include_container_content=True to have any effect. Setting recursive=True with include_container_content=False will raise a ValueError. Only works on classes that support the `sync_from_synapse_async` method. TYPE: `bool` DEFAULT: `False`
`target_entity_types`	Specify which entity types to process when deleting ACLs. Allowed values are "folder" and "file" (case-insensitive). If None, defaults to ["folder", "file"]. This does not affect the entity type of the current entity, which is always processed if `include_self=True`. TYPE: `Optional[List[str]]` DEFAULT: `None`
`dry_run`	If True, log the changes that would be made instead of actually performing the deletions. When enabled, all ACL deletion operations are simulated and logged at info level. Defaults to False. TYPE: `bool` DEFAULT: `False`
`show_acl_details`	When dry_run=True, controls whether current ACL details are displayed for entities that will have their permissions changed. If True (default), shows detailed ACL information. If False, hides ACL details for cleaner output. Has no effect when dry_run=False. TYPE: `bool` DEFAULT: `True`
`show_files_in_containers`	When dry_run=True, controls whether files within containers are displayed in the preview. If True (default), shows all files. If False, hides files when their only change is benefactor inheritance (but still shows files with local ACLs being deleted). Has no effect when dry_run=False. TYPE: `bool` DEFAULT: `True`
`benefactor_tracker`	Optional tracker for managing benefactor relationships. Used for recursive functionality to track which entities will be affected TYPE: `Optional[BenefactorTracker]` DEFAULT: `None`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)` this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`None`	None

RAISES	DESCRIPTION
`ValueError`	If the entity does not have an ID or if an invalid entity type is provided.
`SynapseHTTPError`	If there are permission issues or if the entity already inherits permissions.
`Exception`	For any other errors that may occur during the process.

Note: The caller must be granted ACCESS_TYPE.CHANGE_PERMISSIONS on the Entity to call this method.

Delete permissions for a single entity

from synapseclient import Synapse
from synapseclient.models import File

syn = Synapse()
syn.login()

File(id="syn123").delete_permissions()

Delete permissions recursively for a folder and all its children

from synapseclient import Synapse
from synapseclient.models import Folder

syn = Synapse()
syn.login()

# Delete permissions for this folder only (does not affect children)
Folder(id="syn123").delete_permissions()

# Delete permissions for all files and folders directly within this folder,
# but not the folder itself
Folder(id="syn123").delete_permissions(
    include_self=False,
    include_container_content=True
)

# Delete permissions for all items in the entire hierarchy (folders and their files)
# Both recursive and include_container_content must be True
Folder(id="syn123").delete_permissions(
    recursive=True,
    include_container_content=True
)

# Delete permissions only for folder entities within this folder recursively
# and their contents
Folder(id="syn123").delete_permissions(
    recursive=True,
    include_container_content=True,
    target_entity_types=["folder"]
)

# Delete permissions only for files within this folder and all subfolders
Folder(id="syn123").delete_permissions(
    include_self=False,
    recursive=True,
    include_container_content=True,
    target_entity_types=["file"]
)

# Dry run example: Log what would be deleted without making changes
Folder(id="syn123").delete_permissions(
    recursive=True,
    include_container_content=True,
    dry_run=True
)

Source code in synapseclient/models/protocols/access_control_protocol.py

def delete_permissions(
    self,
    include_self: bool = True,
    include_container_content: bool = False,
    recursive: bool = False,
    target_entity_types: Optional[List[str]] = None,
    dry_run: bool = False,
    show_acl_details: bool = True,
    show_files_in_containers: bool = True,
    *,
    benefactor_tracker: Optional["BenefactorTracker"] = None,
    synapse_client: Optional[Synapse] = None,
) -> None:
    """
    Delete the entire Access Control List (ACL) for a given Entity. This is not
    scoped to a specific user or group, but rather removes all permissions
    associated with the Entity. After this operation, the Entity will inherit
    permissions from its benefactor, which is typically its parent entity or
    the Project it belongs to.

    In order to remove permissions for a specific user or group, you
    should use the `set_permissions` method with the `access_type` set to
    an empty list.

    By default, Entities such as FileEntity and Folder inherit their permission from
    their containing Project. For such Entities the Project is the Entity's 'benefactor'.
    This permission inheritance can be overridden by creating an ACL for the Entity.
    When this occurs the Entity becomes its own benefactor and all permission are
    determined by its own ACL.

    If the ACL of an Entity is deleted, then its benefactor will automatically be set
    to its parent's benefactor.

    **Special notice for Projects:** The ACL for a Project cannot be deleted, you
    must individually update or revoke the permissions for each user or group.

    Arguments:
        include_self: If True (default), delete the ACL of the current entity.
            If False, skip deleting the ACL of the current entity.
        include_container_content: If True, delete ACLs from contents directly within
            containers (files and folders inside self). This must be set to
            True for recursive to have any effect. Defaults to False.
        recursive: If True and the entity is a container (e.g., Project or Folder),
            recursively process child containers. Note that this must be used with
            include_container_content=True to have any effect. Setting recursive=True
            with include_container_content=False will raise a ValueError.
            Only works on classes that support the `sync_from_synapse_async` method.
        target_entity_types: Specify which entity types to process when deleting ACLs.
            Allowed values are "folder" and "file" (case-insensitive).
            If None, defaults to ["folder", "file"]. This does not affect the
            entity type of the current entity, which is always processed if
            `include_self=True`.
        dry_run: If True, log the changes that would be made instead of actually
            performing the deletions. When enabled, all ACL deletion operations are
            simulated and logged at info level. Defaults to False.
        show_acl_details: When dry_run=True, controls whether current ACL details are
            displayed for entities that will have their permissions changed. If True (default),
            shows detailed ACL information. If False, hides ACL details for cleaner output.
            Has no effect when dry_run=False.
        show_files_in_containers: When dry_run=True, controls whether files within containers
            are displayed in the preview. If True (default), shows all files. If False, hides
            files when their only change is benefactor inheritance (but still shows files with
            local ACLs being deleted). Has no effect when dry_run=False.
        benefactor_tracker: Optional tracker for managing benefactor relationships.
            Used for recursive functionality to track which entities will be affected
        synapse_client: If not passed in and caching was not disabled by
            `Synapse.allow_client_caching(False)` this will use the last created
            instance from the Synapse class constructor.

    Returns:
        None

    Raises:
        ValueError: If the entity does not have an ID or if an invalid entity type is provided.
        SynapseHTTPError: If there are permission issues or if the entity already inherits permissions.
        Exception: For any other errors that may occur during the process.

    Note: The caller must be granted ACCESS_TYPE.CHANGE_PERMISSIONS on the Entity to
    call this method.

    Example: Delete permissions for a single entity
        ```python
        from synapseclient import Synapse
        from synapseclient.models import File

        syn = Synapse()
        syn.login()

        File(id="syn123").delete_permissions()

        ```

    Example: Delete permissions recursively for a folder and all its children
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Folder

        syn = Synapse()
        syn.login()

        # Delete permissions for this folder only (does not affect children)
        Folder(id="syn123").delete_permissions()

        # Delete permissions for all files and folders directly within this folder,
        # but not the folder itself
        Folder(id="syn123").delete_permissions(
            include_self=False,
            include_container_content=True
        )

        # Delete permissions for all items in the entire hierarchy (folders and their files)
        # Both recursive and include_container_content must be True
        Folder(id="syn123").delete_permissions(
            recursive=True,
            include_container_content=True
        )

        # Delete permissions only for folder entities within this folder recursively
        # and their contents
        Folder(id="syn123").delete_permissions(
            recursive=True,
            include_container_content=True,
            target_entity_types=["folder"]
        )

        # Delete permissions only for files within this folder and all subfolders
        Folder(id="syn123").delete_permissions(
            include_self=False,
            recursive=True,
            include_container_content=True,
            target_entity_types=["file"]
        )

        # Dry run example: Log what would be deleted without making changes
        Folder(id="syn123").delete_permissions(
            recursive=True,
            include_container_content=True,
            dry_run=True
        )
        ```
    """
    return None

list_acl ¶

list_acl(recursive: bool = False, include_container_content: bool = False, target_entity_types: Optional[List[str]] = None, log_tree: bool = False, *, synapse_client: Optional[Synapse] = None, _progress_bar: Optional[tqdm] = None) -> AclListResult

List the Access Control Lists (ACLs) for this entity and optionally its children.

This function returns the local sharing settings for the entity and optionally its children. It provides a mapping of all ACLs for the given container/entity.

Important Note: This function returns the LOCAL sharing settings only, not the effective permissions that each Synapse User ID/Team has on the entities. More permissive permissions could be granted via a Team that the user has access to that has permissions on the entity, or through inheritance from parent entities.

PARAMETER	DESCRIPTION
`recursive`	If True and the entity is a container (e.g., Project or Folder), recursively process child containers. Note that this must be used with include_container_content=True to have any effect. Setting recursive=True with include_container_content=False will raise a ValueError. Only works on classes that support the `sync_from_synapse_async` method. TYPE: `bool` DEFAULT: `False`
`include_container_content`	If True, include ACLs from contents directly within containers (files and folders inside self). This must be set to True for recursive to have any effect. Defaults to False. TYPE: `bool` DEFAULT: `False`
`target_entity_types`	Specify which entity types to process when listing ACLs. Allowed values are "folder" and "file" (case-insensitive). If None, defaults to ["folder", "file"]. TYPE: `Optional[List[str]]` DEFAULT: `None`
`log_tree`	If True, logs the ACL results to console in ASCII tree format showing entity hierarchies and their ACL permissions in a tree-like structure. Defaults to False. 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`
`_progress_bar`	Internal parameter. Progress bar instance to use for updates when called recursively. Should not be used by external callers. TYPE: `Optional[tqdm]` DEFAULT: `None`

RETURNS	DESCRIPTION
`AclListResult`	An AclListResult object containing a structured representation of ACLs where:
`AclListResult`	entity_acls: A list of EntityAcl objects, each representing one entity's ACL
`AclListResult`	Each EntityAcl contains acl_entries (a list of AclEntry objects)
`AclListResult`	Each AclEntry contains the principal_id and their list of permissions

RAISES	DESCRIPTION
`ValueError`	If the entity does not have an ID or if an invalid entity type is provided.
`SynapseHTTPError`	If there are permission issues accessing ACLs.
`Exception`	For any other errors that may occur during the process.

List ACLs for a single entity

from synapseclient import Synapse
from synapseclient.models import File

syn = Synapse()
syn.login()

acl_result = File(id="syn123").list_acl()
print(acl_result)

# Access entity ACLs (entity_acls is a list, not a dict)
for entity_acl in acl_result.all_entity_acls:
    if entity_acl.entity_id == "syn123":
        # Access individual ACL entries
        for acl_entry in entity_acl.acl_entries:
            if acl_entry.principal_id == "273948":
                print(f"Principal 273948 has permissions: {acl_entry.permissions}")

# I can also access the ACL for the file itself
print(acl_result.entity_acl)

print(acl_result)

List ACLs recursively for a folder and all its children

from synapseclient import Synapse
from synapseclient.models import Folder

syn = Synapse()
syn.login()

acl_result = Folder(id="syn123").list_acl(
    recursive=True,
    include_container_content=True
)

# Access each entity's ACL (entity_acls is a list)
for entity_acl in acl_result.all_entity_acls:
    print(f"Entity {entity_acl.entity_id} has ACL with {len(entity_acl.acl_entries)} principals")

# I can also access the ACL for the folder itself
print(acl_result.entity_acl)

# List ACLs for only folder entities
folder_acl_result = Folder(id="syn123").list_acl(
    recursive=True,
    include_container_content=True,
    target_entity_types=["folder"]
)

List ACLs with ASCII tree visualization

When log_tree=True, the ACLs will be logged in a tree format. Additionally, the ascii_tree attribute of the AclListResult will contain the ASCII tree representation of the ACLs.

from synapseclient import Synapse
from synapseclient.models import Folder

syn = Synapse()
syn.login()

acl_result = Folder(id="syn123").list_acl(
    recursive=True,
    include_container_content=True,
    log_tree=True, # Enable ASCII tree logging
)

# The ASCII tree representation of the ACLs will also be available
# in acl_result.ascii_tree
print(acl_result.ascii_tree)

Source code in synapseclient/models/protocols/access_control_protocol.py

def list_acl(
    self,
    recursive: bool = False,
    include_container_content: bool = False,
    target_entity_types: Optional[List[str]] = None,
    log_tree: bool = False,
    *,
    synapse_client: Optional[Synapse] = None,
    _progress_bar: Optional[tqdm] = None,  # Internal parameter for recursive calls
) -> "AclListResult":
    """
    List the Access Control Lists (ACLs) for this entity and optionally its children.

    This function returns the local sharing settings for the entity and optionally
    its children. It provides a mapping of all ACLs for the given container/entity.

    **Important Note:** This function returns the LOCAL sharing settings only, not
    the effective permissions that each Synapse User ID/Team has on the entities.
    More permissive permissions could be granted via a Team that the user has access
    to that has permissions on the entity, or through inheritance from parent entities.

    Arguments:
        recursive: If True and the entity is a container (e.g., Project or Folder),
            recursively process child containers. Note that this must be used with
            include_container_content=True to have any effect. Setting recursive=True
            with include_container_content=False will raise a ValueError.
            Only works on classes that support the `sync_from_synapse_async` method.
        include_container_content: If True, include ACLs from contents directly within
            containers (files and folders inside self). This must be set to
            True for recursive to have any effect. Defaults to False.
        target_entity_types: Specify which entity types to process when listing ACLs.
            Allowed values are "folder" and "file" (case-insensitive).
            If None, defaults to ["folder", "file"].
        log_tree: If True, logs the ACL results to console in ASCII tree format showing
            entity hierarchies and their ACL permissions in a tree-like structure.
            Defaults to 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.
        _progress_bar: Internal parameter. Progress bar instance to use for updates
            when called recursively. Should not be used by external callers.

    Returns:
        An AclListResult object containing a structured representation of ACLs where:
        - entity_acls: A list of EntityAcl objects, each representing one entity's ACL
        - Each EntityAcl contains acl_entries (a list of AclEntry objects)
        - Each AclEntry contains the principal_id and their list of permissions

    Raises:
        ValueError: If the entity does not have an ID or if an invalid entity type is provided.
        SynapseHTTPError: If there are permission issues accessing ACLs.
        Exception: For any other errors that may occur during the process.

    Example: List ACLs for a single entity
        ```python
        from synapseclient import Synapse
        from synapseclient.models import File

        syn = Synapse()
        syn.login()

        acl_result = File(id="syn123").list_acl()
        print(acl_result)

        # Access entity ACLs (entity_acls is a list, not a dict)
        for entity_acl in acl_result.all_entity_acls:
            if entity_acl.entity_id == "syn123":
                # Access individual ACL entries
                for acl_entry in entity_acl.acl_entries:
                    if acl_entry.principal_id == "273948":
                        print(f"Principal 273948 has permissions: {acl_entry.permissions}")

        # I can also access the ACL for the file itself
        print(acl_result.entity_acl)

        print(acl_result)

        ```

    Example: List ACLs recursively for a folder and all its children
        ```python
        from synapseclient import Synapse
        from synapseclient.models import Folder

        syn = Synapse()
        syn.login()

        acl_result = Folder(id="syn123").list_acl(
            recursive=True,
            include_container_content=True
        )

        # Access each entity's ACL (entity_acls is a list)
        for entity_acl in acl_result.all_entity_acls:
            print(f"Entity {entity_acl.entity_id} has ACL with {len(entity_acl.acl_entries)} principals")

        # I can also access the ACL for the folder itself
        print(acl_result.entity_acl)

        # List ACLs for only folder entities
        folder_acl_result = Folder(id="syn123").list_acl(
            recursive=True,
            include_container_content=True,
            target_entity_types=["folder"]
        )
        ```

    Example: List ACLs with ASCII tree visualization
        When `log_tree=True`, the ACLs will be logged in a tree format. Additionally,
        the `ascii_tree` attribute of the AclListResult will contain the ASCII tree
        representation of the ACLs.

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

        syn = Synapse()
        syn.login()

        acl_result = Folder(id="syn123").list_acl(
            recursive=True,
            include_container_content=True,
            log_tree=True, # Enable ASCII tree logging
        )

        # The ASCII tree representation of the ACLs will also be available
        # in acl_result.ascii_tree
        print(acl_result.ascii_tree)
        ```
    """
    return AclListResult()

bind_schema ¶

bind_schema(json_schema_uri: str, *, enable_derived_annotations: Optional[bool] = False, synapse_client: Optional[Synapse] = None) -> JSONSchemaBinding

Bind a JSON schema to the entity.

PARAMETER	DESCRIPTION
`json_schema_uri`	The URI of the JSON schema to bind to the entity. TYPE: `str`
`enable_derived_annotations`	If true, enable derived annotations. Defaults to False. TYPE: `Optional[bool]` DEFAULT: `False`
`synapse_client`	The Synapse client instance. If not provided, the last created instance from the Synapse class constructor will be used. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`JSONSchemaBinding`	An object containing details about the JSON schema binding.

Using this function

Binding JSON schema to a folder or a file. This example expects that you have a Synapse project to use, and a file to upload. Set the PROJECT_NAME and FILE_PATH variables to your project name and file path respectively.

from synapseclient import Synapse
from synapseclient.models import File, Folder

syn = Synapse()
syn.login()

# Define Project and JSON schema info
PROJECT_NAME = "test_json_schema_project"  # replace with your project name
FILE_PATH = "~/Sample.txt"  # replace with your test file path

PROJECT_ID = syn.findEntityId(name=PROJECT_NAME)
ORG_NAME = "UniqueOrg"  # replace with your organization name
SCHEMA_NAME = "myTestSchema"  # replace with your schema name
FOLDER_NAME = "test_script_folder"
VERSION = "0.0.1"
SCHEMA_URI = f"{ORG_NAME}-{SCHEMA_NAME}-{VERSION}"

# Create organization (if not already created)
js = syn.service("json_schema")
all_orgs = js.list_organizations()
for org in all_orgs:
    if org["name"] == ORG_NAME:
        print(f"Organization {ORG_NAME} already exists: {org}")
        break
else:
    print(f"Creating organization {ORG_NAME}.")
    created_organization = js.create_organization(ORG_NAME)
    print(f"Created organization: {created_organization}")


my_test_org = js.JsonSchemaOrganization(ORG_NAME)
test_schema = my_test_org.get_json_schema(SCHEMA_NAME)

if not test_schema:
    # Create the schema (if not already created)
    schema_definition = {
        "$id": "mySchema",
        "type": "object",
        "properties": {
            "foo": {"type": "string"},
            "bar": {"type": "integer"},
        },
        "required": ["foo"]
    }
    test_schema = my_test_org.create_json_schema(schema_definition, SCHEMA_NAME, VERSION)

# Create a test folder
test_folder = Folder(name=FOLDER_NAME, parent_id=PROJECT_ID)
test_folder.store()

# Bind JSON schema to the folder
bound_schema = test_folder.bind_schema(
    json_schema_uri=SCHEMA_URI,
    enable_derived_annotations=True
)
print(f"Result from binding schema to folder: {bound_schema}")

# Bind the same schema to a file
example_file = File(
    path=FILE_PATH,  # Replace with your test file path
    parent_id=test_folder.id,
).store()

bound_schema_file = example_file.bind_schema(
    json_schema_uri=SCHEMA_URI,
    enable_derived_annotations=True
)
print(f"Result from binding schema to file: {bound_schema_file}")

Source code in synapseclient/models/protocols/json_schema_protocol.py

def bind_schema(
    self,
    json_schema_uri: str,
    *,
    enable_derived_annotations: Optional[bool] = False,
    synapse_client: Optional["Synapse"] = None,
) -> "JSONSchemaBinding":
    """
    Bind a JSON schema to the entity.

    Arguments:
        json_schema_uri: The URI of the JSON schema to bind to the entity.
        enable_derived_annotations: If true, enable derived annotations. Defaults to False.
        synapse_client: The Synapse client instance. If not provided,
            the last created instance from the Synapse class constructor will be used.

    Returns:
        An object containing details about the JSON schema binding.

    Example: Using this function
        Binding JSON schema to a folder or a file. This example expects that you
        have a Synapse project to use, and a file to upload. Set the `PROJECT_NAME`
        and `FILE_PATH` variables to your project name and file path respectively.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import File, Folder

        syn = Synapse()
        syn.login()

        # Define Project and JSON schema info
        PROJECT_NAME = "test_json_schema_project"  # replace with your project name
        FILE_PATH = "~/Sample.txt"  # replace with your test file path

        PROJECT_ID = syn.findEntityId(name=PROJECT_NAME)
        ORG_NAME = "UniqueOrg"  # replace with your organization name
        SCHEMA_NAME = "myTestSchema"  # replace with your schema name
        FOLDER_NAME = "test_script_folder"
        VERSION = "0.0.1"
        SCHEMA_URI = f"{ORG_NAME}-{SCHEMA_NAME}-{VERSION}"

        # Create organization (if not already created)
        js = syn.service("json_schema")
        all_orgs = js.list_organizations()
        for org in all_orgs:
            if org["name"] == ORG_NAME:
                print(f"Organization {ORG_NAME} already exists: {org}")
                break
        else:
            print(f"Creating organization {ORG_NAME}.")
            created_organization = js.create_organization(ORG_NAME)
            print(f"Created organization: {created_organization}")


        my_test_org = js.JsonSchemaOrganization(ORG_NAME)
        test_schema = my_test_org.get_json_schema(SCHEMA_NAME)

        if not test_schema:
            # Create the schema (if not already created)
            schema_definition = {
                "$id": "mySchema",
                "type": "object",
                "properties": {
                    "foo": {"type": "string"},
                    "bar": {"type": "integer"},
                },
                "required": ["foo"]
            }
            test_schema = my_test_org.create_json_schema(schema_definition, SCHEMA_NAME, VERSION)

        # Create a test folder
        test_folder = Folder(name=FOLDER_NAME, parent_id=PROJECT_ID)
        test_folder.store()

        # Bind JSON schema to the folder
        bound_schema = test_folder.bind_schema(
            json_schema_uri=SCHEMA_URI,
            enable_derived_annotations=True
        )
        print(f"Result from binding schema to folder: {bound_schema}")

        # Bind the same schema to a file
        example_file = File(
            path=FILE_PATH,  # Replace with your test file path
            parent_id=test_folder.id,
        ).store()

        bound_schema_file = example_file.bind_schema(
            json_schema_uri=SCHEMA_URI,
            enable_derived_annotations=True
        )
        print(f"Result from binding schema to file: {bound_schema_file}")
        ```
    """
    return JSONSchemaBinding()

get_schema ¶

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

Get the JSON schema bound to the entity.

PARAMETER	DESCRIPTION
`synapse_client`	The Synapse client instance. If not provided, the last created instance from the Synapse class constructor will be used. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`JSONSchemaBinding`	An object containing details about the bound JSON schema.

Using this function

Retrieving the bound JSON schema from a folder or file. This example demonstrates how to get existing schema bindings from entities that already have schemas bound. Set the PROJECT_NAME variable to your project name.

from synapseclient import Synapse
from synapseclient.models import File, Folder

syn = Synapse()
syn.login()

# Define Project and JSON schema info
PROJECT_NAME = "test_json_schema_project"  # replace with your project name
FILE_PATH = "~/Sample.txt"  # replace with your test file path

PROJECT_ID = syn.findEntityId(name=PROJECT_NAME)
ORG_NAME = "UniqueOrg"  # replace with your organization name
SCHEMA_NAME = "myTestSchema"  # replace with your schema name
FOLDER_NAME = "test_script_folder"
VERSION = "0.0.1"
SCHEMA_URI = f"{ORG_NAME}-{SCHEMA_NAME}-{VERSION}"

# Create organization (if not already created)
js = syn.service("json_schema")
all_orgs = js.list_organizations()
for org in all_orgs:
    if org["name"] == ORG_NAME:
        print(f"Organization {ORG_NAME} already exists: {org}")
        break
else:
    print(f"Creating organization {ORG_NAME}.")
    created_organization = js.create_organization(ORG_NAME)
    print(f"Created organization: {created_organization}")

my_test_org = js.JsonSchemaOrganization(ORG_NAME)
test_schema = my_test_org.get_json_schema(SCHEMA_NAME)

if not test_schema:
    # Create the schema (if not already created)
    schema_definition = {
        "$id": "mySchema",
        "type": "object",
        "properties": {
            "foo": {"type": "string"},
            "bar": {"type": "integer"},
        },
        "required": ["foo"]
    }
    test_schema = my_test_org.create_json_schema(schema_definition, SCHEMA_NAME, VERSION)
    print(f"Created new schema: {SCHEMA_NAME}")

# Create a test folder
test_folder = Folder(name=FOLDER_NAME, parent_id=PROJECT_ID)
test_folder.store()
print(f"Created test folder: {FOLDER_NAME}")

# Bind JSON schema to the folder first
bound_schema = test_folder.bind_schema(
    json_schema_uri=SCHEMA_URI,
    enable_derived_annotations=True
)
print(f"Bound schema to folder: {bound_schema}")

# Create and bind schema to a file
example_file = File(
    path=FILE_PATH,  # Replace with your test file path
    parent_id=test_folder.id,
).store()

bound_schema_file = example_file.bind_schema(
    json_schema_uri=SCHEMA_URI,
    enable_derived_annotations=True
)
print(f"Bound schema to file: {bound_schema_file}")

# Retrieve the bound schema from the folder
retrieved_folder_schema = test_folder.get_schema()
print(f"Retrieved schema from folder: {retrieved_folder_schema}")

# Retrieve the bound schema from the file
retrieved_file_schema = example_file.get_schema()
print(f"Retrieved schema from file: {retrieved_file_schema}")

Source code in synapseclient/models/protocols/json_schema_protocol.py

def get_schema(
    self, *, synapse_client: Optional["Synapse"] = None
) -> "JSONSchemaBinding":
    """
    Get the JSON schema bound to the entity.

    Arguments:
        synapse_client: The Synapse client instance. If not provided,
            the last created instance from the Synapse class constructor will be used.

    Returns:
        An object containing details about the bound JSON schema.

    Example: Using this function
        Retrieving the bound JSON schema from a folder or file. This example demonstrates
        how to get existing schema bindings from entities that already have schemas bound.
        Set the `PROJECT_NAME` variable to your project name.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import File, Folder

        syn = Synapse()
        syn.login()

        # Define Project and JSON schema info
        PROJECT_NAME = "test_json_schema_project"  # replace with your project name
        FILE_PATH = "~/Sample.txt"  # replace with your test file path

        PROJECT_ID = syn.findEntityId(name=PROJECT_NAME)
        ORG_NAME = "UniqueOrg"  # replace with your organization name
        SCHEMA_NAME = "myTestSchema"  # replace with your schema name
        FOLDER_NAME = "test_script_folder"
        VERSION = "0.0.1"
        SCHEMA_URI = f"{ORG_NAME}-{SCHEMA_NAME}-{VERSION}"

        # Create organization (if not already created)
        js = syn.service("json_schema")
        all_orgs = js.list_organizations()
        for org in all_orgs:
            if org["name"] == ORG_NAME:
                print(f"Organization {ORG_NAME} already exists: {org}")
                break
        else:
            print(f"Creating organization {ORG_NAME}.")
            created_organization = js.create_organization(ORG_NAME)
            print(f"Created organization: {created_organization}")

        my_test_org = js.JsonSchemaOrganization(ORG_NAME)
        test_schema = my_test_org.get_json_schema(SCHEMA_NAME)

        if not test_schema:
            # Create the schema (if not already created)
            schema_definition = {
                "$id": "mySchema",
                "type": "object",
                "properties": {
                    "foo": {"type": "string"},
                    "bar": {"type": "integer"},
                },
                "required": ["foo"]
            }
            test_schema = my_test_org.create_json_schema(schema_definition, SCHEMA_NAME, VERSION)
            print(f"Created new schema: {SCHEMA_NAME}")

        # Create a test folder
        test_folder = Folder(name=FOLDER_NAME, parent_id=PROJECT_ID)
        test_folder.store()
        print(f"Created test folder: {FOLDER_NAME}")

        # Bind JSON schema to the folder first
        bound_schema = test_folder.bind_schema(
            json_schema_uri=SCHEMA_URI,
            enable_derived_annotations=True
        )
        print(f"Bound schema to folder: {bound_schema}")

        # Create and bind schema to a file
        example_file = File(
            path=FILE_PATH,  # Replace with your test file path
            parent_id=test_folder.id,
        ).store()

        bound_schema_file = example_file.bind_schema(
            json_schema_uri=SCHEMA_URI,
            enable_derived_annotations=True
        )
        print(f"Bound schema to file: {bound_schema_file}")

        # Retrieve the bound schema from the folder
        retrieved_folder_schema = test_folder.get_schema()
        print(f"Retrieved schema from folder: {retrieved_folder_schema}")

        # Retrieve the bound schema from the file
        retrieved_file_schema = example_file.get_schema()
        print(f"Retrieved schema from file: {retrieved_file_schema}")
        ```
    """
    return JSONSchemaBinding()

unbind_schema ¶

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

Unbind the JSON schema from the entity.

PARAMETER	DESCRIPTION
`synapse_client`	The Synapse client instance. If not provided, the last created instance from the Synapse class constructor will be used. TYPE: `Optional[Synapse]` DEFAULT: `None`

Using this function

Unbinding a JSON schema from a folder or file. This example demonstrates how to remove schema bindings from entities. Assumes entities already have schemas bound. Set the PROJECT_NAME variable to your project name.

from synapseclient import Synapse
from synapseclient.models import File, Folder

syn = Synapse()
syn.login()

# Define Project and JSON schema info
PROJECT_NAME = "test_json_schema_project"  # replace with your project name
FILE_PATH = "~/Sample.txt"  # replace with your test file path

PROJECT_ID = syn.findEntityId(name=PROJECT_NAME)
ORG_NAME = "UniqueOrg"  # replace with your organization name
SCHEMA_NAME = "myTestSchema"  # replace with your schema name
FOLDER_NAME = "test_script_folder"
VERSION = "0.0.1"
SCHEMA_URI = f"{ORG_NAME}-{SCHEMA_NAME}-{VERSION}"

# Create organization (if not already created)
js = syn.service("json_schema")
all_orgs = js.list_organizations()
for org in all_orgs:
    if org["name"] == ORG_NAME:
        print(f"Organization {ORG_NAME} already exists: {org}")
        break
else:
    print(f"Creating organization {ORG_NAME}.")
    created_organization = js.create_organization(ORG_NAME)
    print(f"Created organization: {created_organization}")

my_test_org = js.JsonSchemaOrganization(ORG_NAME)
test_schema = my_test_org.get_json_schema(SCHEMA_NAME)

if not test_schema:
    # Create the schema (if not already created)
    schema_definition = {
        "$id": "mySchema",
        "type": "object",
        "properties": {
            "foo": {"type": "string"},
            "bar": {"type": "integer"},
        },
        "required": ["foo"]
    }
    test_schema = my_test_org.create_json_schema(schema_definition, SCHEMA_NAME, VERSION)
    print(f"Created new schema: {SCHEMA_NAME}")

# Create a test folder
test_folder = Folder(name=FOLDER_NAME, parent_id=PROJECT_ID)
test_folder.store()
print(f"Created test folder: {FOLDER_NAME}")

# Bind JSON schema to the folder first
bound_schema = test_folder.bind_schema(
    json_schema_uri=SCHEMA_URI,
    enable_derived_annotations=True
)
print(f"Bound schema to folder: {bound_schema}")

# Create and bind schema to a file
example_file = File(
    path=FILE_PATH,  # Replace with your test file path
    parent_id=test_folder.id,
).store()

bound_schema_file = example_file.bind_schema(
    json_schema_uri=SCHEMA_URI,
    enable_derived_annotations=True
)
print(f"Bound schema to file: {bound_schema_file}")

# Unbind the schema from the folder
test_folder.unbind_schema()
print("Successfully unbound schema from folder")

# Unbind the schema from the file
example_file.unbind_schema()
print("Successfully unbound schema from file")

Source code in synapseclient/models/protocols/json_schema_protocol.py

def unbind_schema(self, *, synapse_client: Optional["Synapse"] = None) -> None:
    """
    Unbind the JSON schema from the entity.

    Arguments:
        synapse_client: The Synapse client instance. If not provided,
            the last created instance from the Synapse class constructor will be used.

    Example: Using this function
        Unbinding a JSON schema from a folder or file. This example demonstrates
        how to remove schema bindings from entities. Assumes entities already have
        schemas bound. Set the `PROJECT_NAME` variable to your project name.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import File, Folder

        syn = Synapse()
        syn.login()

        # Define Project and JSON schema info
        PROJECT_NAME = "test_json_schema_project"  # replace with your project name
        FILE_PATH = "~/Sample.txt"  # replace with your test file path

        PROJECT_ID = syn.findEntityId(name=PROJECT_NAME)
        ORG_NAME = "UniqueOrg"  # replace with your organization name
        SCHEMA_NAME = "myTestSchema"  # replace with your schema name
        FOLDER_NAME = "test_script_folder"
        VERSION = "0.0.1"
        SCHEMA_URI = f"{ORG_NAME}-{SCHEMA_NAME}-{VERSION}"

        # Create organization (if not already created)
        js = syn.service("json_schema")
        all_orgs = js.list_organizations()
        for org in all_orgs:
            if org["name"] == ORG_NAME:
                print(f"Organization {ORG_NAME} already exists: {org}")
                break
        else:
            print(f"Creating organization {ORG_NAME}.")
            created_organization = js.create_organization(ORG_NAME)
            print(f"Created organization: {created_organization}")

        my_test_org = js.JsonSchemaOrganization(ORG_NAME)
        test_schema = my_test_org.get_json_schema(SCHEMA_NAME)

        if not test_schema:
            # Create the schema (if not already created)
            schema_definition = {
                "$id": "mySchema",
                "type": "object",
                "properties": {
                    "foo": {"type": "string"},
                    "bar": {"type": "integer"},
                },
                "required": ["foo"]
            }
            test_schema = my_test_org.create_json_schema(schema_definition, SCHEMA_NAME, VERSION)
            print(f"Created new schema: {SCHEMA_NAME}")

        # Create a test folder
        test_folder = Folder(name=FOLDER_NAME, parent_id=PROJECT_ID)
        test_folder.store()
        print(f"Created test folder: {FOLDER_NAME}")

        # Bind JSON schema to the folder first
        bound_schema = test_folder.bind_schema(
            json_schema_uri=SCHEMA_URI,
            enable_derived_annotations=True
        )
        print(f"Bound schema to folder: {bound_schema}")

        # Create and bind schema to a file
        example_file = File(
            path=FILE_PATH,  # Replace with your test file path
            parent_id=test_folder.id,
        ).store()

        bound_schema_file = example_file.bind_schema(
            json_schema_uri=SCHEMA_URI,
            enable_derived_annotations=True
        )
        print(f"Bound schema to file: {bound_schema_file}")

        # Unbind the schema from the folder
        test_folder.unbind_schema()
        print("Successfully unbound schema from folder")

        # Unbind the schema from the file
        example_file.unbind_schema()
        print("Successfully unbound schema from file")
        ```
    """

validate_schema ¶

validate_schema(*, synapse_client: Optional[Synapse] = None) -> Union[JSONSchemaValidation, InvalidJSONSchemaValidation]

Validate the entity against the bound JSON schema.

PARAMETER	DESCRIPTION
`synapse_client`	The Synapse client instance. If not provided, the last created instance from the Synapse class constructor will be used. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Union[JSONSchemaValidation, InvalidJSONSchemaValidation]`	The validation results.

Using this function

Validating a folder or file against the bound JSON schema. This example demonstrates how to validate entities with annotations against their bound schemas. Requires entities to have schemas already bound. Set the PROJECT_NAME variable to your project name.

from synapseclient import Synapse
from synapseclient.models import File, Folder
import time

syn = Synapse()
syn.login()

# Define Project and JSON schema info
PROJECT_NAME = "test_json_schema_project"  # replace with your project name
FILE_PATH = "~/Sample.txt"  # replace with your test file path

PROJECT_ID = syn.findEntityId(name=PROJECT_NAME)
ORG_NAME = "UniqueOrg"  # replace with your organization name
SCHEMA_NAME = "myTestSchema"  # replace with your schema name
FOLDER_NAME = "test_script_folder"
VERSION = "0.0.1"
SCHEMA_URI = f"{ORG_NAME}-{SCHEMA_NAME}-{VERSION}"

# Create organization (if not already created)
js = syn.service("json_schema")
all_orgs = js.list_organizations()
for org in all_orgs:
    if org["name"] == ORG_NAME:
        print(f"Organization {ORG_NAME} already exists: {org}")
        break
else:
    print(f"Creating organization {ORG_NAME}.")
    created_organization = js.create_organization(ORG_NAME)
    print(f"Created organization: {created_organization}")

my_test_org = js.JsonSchemaOrganization(ORG_NAME)
test_schema = my_test_org.get_json_schema(SCHEMA_NAME)

if not test_schema:
    # Create the schema (if not already created)
    schema_definition = {
        "$id": "mySchema",
        "type": "object",
        "properties": {
            "foo": {"type": "string"},
            "bar": {"type": "integer"},
        },
        "required": ["foo"]
    }
    test_schema = my_test_org.create_json_schema(schema_definition, SCHEMA_NAME, VERSION)
    print(f"Created new schema: {SCHEMA_NAME}")

# Create a test folder
test_folder = Folder(name=FOLDER_NAME, parent_id=PROJECT_ID)
test_folder.store()
print(f"Created test folder: {FOLDER_NAME}")

# Bind JSON schema to the folder
bound_schema = test_folder.bind_schema(
    json_schema_uri=SCHEMA_URI,
    enable_derived_annotations=True
)
print(f"Bound schema to folder: {bound_schema}")

# Create and bind schema to a file
example_file = File(
    path=FILE_PATH,  # Replace with your test file path
    parent_id=test_folder.id,
).store()

bound_schema_file = example_file.bind_schema(
    json_schema_uri=SCHEMA_URI,
    enable_derived_annotations=True
)
print(f"Bound schema to file: {bound_schema_file}")

# Validate the folder entity against the bound schema
test_folder.annotations = {"foo": "test_value", "bar": 42}  # Example annotations
test_folder.store()
print("Added annotations to folder and stored")
time.sleep(2)  # Allow time for processing

validation_response = test_folder.validate_schema()
print(f"Folder validation response: {validation_response}")

# Validate the file entity against the bound schema
example_file.annotations = {"foo": "test_value", "bar": 43}  # Example annotations
example_file.store()
print("Added annotations to file and stored")
time.sleep(2)  # Allow time for processing

validation_response_file = example_file.validate_schema()
print(f"File validation response: {validation_response_file}")

Source code in synapseclient/models/protocols/json_schema_protocol.py

def validate_schema(
    self, *, synapse_client: Optional["Synapse"] = None
) -> Union["JSONSchemaValidation", "InvalidJSONSchemaValidation"]:
    """
    Validate the entity against the bound JSON schema.

    Arguments:
        synapse_client: The Synapse client instance. If not provided,
            the last created instance from the Synapse class constructor will be used.

    Returns:
        The validation results.

    Example: Using this function
        Validating a folder or file against the bound JSON schema. This example demonstrates
        how to validate entities with annotations against their bound schemas. Requires entities
        to have schemas already bound. Set the `PROJECT_NAME` variable to your project name.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import File, Folder
        import time

        syn = Synapse()
        syn.login()

        # Define Project and JSON schema info
        PROJECT_NAME = "test_json_schema_project"  # replace with your project name
        FILE_PATH = "~/Sample.txt"  # replace with your test file path

        PROJECT_ID = syn.findEntityId(name=PROJECT_NAME)
        ORG_NAME = "UniqueOrg"  # replace with your organization name
        SCHEMA_NAME = "myTestSchema"  # replace with your schema name
        FOLDER_NAME = "test_script_folder"
        VERSION = "0.0.1"
        SCHEMA_URI = f"{ORG_NAME}-{SCHEMA_NAME}-{VERSION}"

        # Create organization (if not already created)
        js = syn.service("json_schema")
        all_orgs = js.list_organizations()
        for org in all_orgs:
            if org["name"] == ORG_NAME:
                print(f"Organization {ORG_NAME} already exists: {org}")
                break
        else:
            print(f"Creating organization {ORG_NAME}.")
            created_organization = js.create_organization(ORG_NAME)
            print(f"Created organization: {created_organization}")

        my_test_org = js.JsonSchemaOrganization(ORG_NAME)
        test_schema = my_test_org.get_json_schema(SCHEMA_NAME)

        if not test_schema:
            # Create the schema (if not already created)
            schema_definition = {
                "$id": "mySchema",
                "type": "object",
                "properties": {
                    "foo": {"type": "string"},
                    "bar": {"type": "integer"},
                },
                "required": ["foo"]
            }
            test_schema = my_test_org.create_json_schema(schema_definition, SCHEMA_NAME, VERSION)
            print(f"Created new schema: {SCHEMA_NAME}")

        # Create a test folder
        test_folder = Folder(name=FOLDER_NAME, parent_id=PROJECT_ID)
        test_folder.store()
        print(f"Created test folder: {FOLDER_NAME}")

        # Bind JSON schema to the folder
        bound_schema = test_folder.bind_schema(
            json_schema_uri=SCHEMA_URI,
            enable_derived_annotations=True
        )
        print(f"Bound schema to folder: {bound_schema}")

        # Create and bind schema to a file
        example_file = File(
            path=FILE_PATH,  # Replace with your test file path
            parent_id=test_folder.id,
        ).store()

        bound_schema_file = example_file.bind_schema(
            json_schema_uri=SCHEMA_URI,
            enable_derived_annotations=True
        )
        print(f"Bound schema to file: {bound_schema_file}")

        # Validate the folder entity against the bound schema
        test_folder.annotations = {"foo": "test_value", "bar": 42}  # Example annotations
        test_folder.store()
        print("Added annotations to folder and stored")
        time.sleep(2)  # Allow time for processing

        validation_response = test_folder.validate_schema()
        print(f"Folder validation response: {validation_response}")

        # Validate the file entity against the bound schema
        example_file.annotations = {"foo": "test_value", "bar": 43}  # Example annotations
        example_file.store()
        print("Added annotations to file and stored")
        time.sleep(2)  # Allow time for processing

        validation_response_file = example_file.validate_schema()
        print(f"File validation response: {validation_response_file}")
        ```
    """
    return InvalidJSONSchemaValidation() or JSONSchemaValidation()

get_schema_derived_keys ¶

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

Retrieve derived JSON schema keys for the entity.

PARAMETER	DESCRIPTION
`synapse_client`	The Synapse client instance. If not provided, the last created instance from the Synapse class constructor will be used. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`JSONSchemaDerivedKeys`	An object containing the derived keys for the entity.

Using this function

Retrieving derived keys from a folder or file. This example demonstrates how to get derived annotation keys from schemas with constant values. Set the PROJECT_NAME variable to your project name.

from synapseclient import Synapse
from synapseclient.models import File, Folder

syn = Synapse()
syn.login()

# Define Project and JSON schema info
PROJECT_NAME = "test_json_schema_project"  # replace with your project name
FILE_PATH = "~/Sample.txt"  # replace with your test file path

PROJECT_ID = syn.findEntityId(name=PROJECT_NAME)
ORG_NAME = "UniqueOrg"  # replace with your organization name
DERIVED_TEST_SCHEMA_NAME = "myTestDerivedSchema"  # replace with your derived schema name
FOLDER_NAME = "test_script_folder"
VERSION = "0.0.1"
SCHEMA_URI = f"{ORG_NAME}-{DERIVED_TEST_SCHEMA_NAME}-{VERSION}"

# Create organization (if not already created)
js = syn.service("json_schema")
all_orgs = js.list_organizations()
for org in all_orgs:
    if org["name"] == ORG_NAME:
        print(f"Organization {ORG_NAME} already exists: {org}")
        break
else:
    print(f"Creating organization {ORG_NAME}.")
    created_organization = js.create_organization(ORG_NAME)
    print(f"Created organization: {created_organization}")

my_test_org = js.JsonSchemaOrganization(ORG_NAME)
test_schema = my_test_org.get_json_schema(DERIVED_TEST_SCHEMA_NAME)

if not test_schema:
    # Create the schema (if not already created)
    schema_definition = {
        "$id": "mySchema",
        "type": "object",
        "properties": {
            "foo": {"type": "string"},
            "baz": {"type": "string", "const": "example_value"},  # Example constant for derived annotation
            "bar": {"type": "integer"},
        },
        "required": ["foo"]
    }
    test_schema = my_test_org.create_json_schema(schema_definition, DERIVED_TEST_SCHEMA_NAME, VERSION)
    print(f"Created new derived schema: {DERIVED_TEST_SCHEMA_NAME}")

# Create a test folder
test_folder = Folder(name=FOLDER_NAME, parent_id=PROJECT_ID)
test_folder.store()
print(f"Created test folder: {FOLDER_NAME}")

# Bind JSON schema to the folder
bound_schema = test_folder.bind_schema(
    json_schema_uri=SCHEMA_URI,
    enable_derived_annotations=True
)
print(f"Bound schema to folder with derived annotations: {bound_schema}")

# Create and bind schema to a file
example_file = File(
    path=FILE_PATH,  # Replace with your test file path
    parent_id=test_folder.id,
).store()

bound_schema_file = example_file.bind_schema(
    json_schema_uri=SCHEMA_URI,
    enable_derived_annotations=True
)
print(f"Bound schema to file with derived annotations: {bound_schema_file}")

# Get the derived keys from the bound schema of the folder
test_folder.annotations = {"foo": "test_value_new", "bar": 42}  # Example annotations
test_folder.store()
print("Added annotations to folder and stored")

derived_keys = test_folder.get_schema_derived_keys()
print(f"Derived keys from folder: {derived_keys}")

# Get the derived keys from the bound schema of the file
example_file.annotations = {"foo": "test_value_new", "bar": 43}  # Example annotations
example_file.store()
print("Added annotations to file and stored")

derived_keys_file = example_file.get_schema_derived_keys()
print(f"Derived keys from file: {derived_keys_file}")

Source code in synapseclient/models/protocols/json_schema_protocol.py

def get_schema_derived_keys(
    self, *, synapse_client: Optional["Synapse"] = None
) -> "JSONSchemaDerivedKeys":
    """
    Retrieve derived JSON schema keys for the entity.

    Arguments:
        synapse_client: The Synapse client instance. If not provided,
            the last created instance from the Synapse class constructor will be used.

    Returns:
        An object containing the derived keys for the entity.

    Example: Using this function
        Retrieving derived keys from a folder or file. This example demonstrates
        how to get derived annotation keys from schemas with constant values.
        Set the `PROJECT_NAME` variable to your project name.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import File, Folder

        syn = Synapse()
        syn.login()

        # Define Project and JSON schema info
        PROJECT_NAME = "test_json_schema_project"  # replace with your project name
        FILE_PATH = "~/Sample.txt"  # replace with your test file path

        PROJECT_ID = syn.findEntityId(name=PROJECT_NAME)
        ORG_NAME = "UniqueOrg"  # replace with your organization name
        DERIVED_TEST_SCHEMA_NAME = "myTestDerivedSchema"  # replace with your derived schema name
        FOLDER_NAME = "test_script_folder"
        VERSION = "0.0.1"
        SCHEMA_URI = f"{ORG_NAME}-{DERIVED_TEST_SCHEMA_NAME}-{VERSION}"

        # Create organization (if not already created)
        js = syn.service("json_schema")
        all_orgs = js.list_organizations()
        for org in all_orgs:
            if org["name"] == ORG_NAME:
                print(f"Organization {ORG_NAME} already exists: {org}")
                break
        else:
            print(f"Creating organization {ORG_NAME}.")
            created_organization = js.create_organization(ORG_NAME)
            print(f"Created organization: {created_organization}")

        my_test_org = js.JsonSchemaOrganization(ORG_NAME)
        test_schema = my_test_org.get_json_schema(DERIVED_TEST_SCHEMA_NAME)

        if not test_schema:
            # Create the schema (if not already created)
            schema_definition = {
                "$id": "mySchema",
                "type": "object",
                "properties": {
                    "foo": {"type": "string"},
                    "baz": {"type": "string", "const": "example_value"},  # Example constant for derived annotation
                    "bar": {"type": "integer"},
                },
                "required": ["foo"]
            }
            test_schema = my_test_org.create_json_schema(schema_definition, DERIVED_TEST_SCHEMA_NAME, VERSION)
            print(f"Created new derived schema: {DERIVED_TEST_SCHEMA_NAME}")

        # Create a test folder
        test_folder = Folder(name=FOLDER_NAME, parent_id=PROJECT_ID)
        test_folder.store()
        print(f"Created test folder: {FOLDER_NAME}")

        # Bind JSON schema to the folder
        bound_schema = test_folder.bind_schema(
            json_schema_uri=SCHEMA_URI,
            enable_derived_annotations=True
        )
        print(f"Bound schema to folder with derived annotations: {bound_schema}")

        # Create and bind schema to a file
        example_file = File(
            path=FILE_PATH,  # Replace with your test file path
            parent_id=test_folder.id,
        ).store()

        bound_schema_file = example_file.bind_schema(
            json_schema_uri=SCHEMA_URI,
            enable_derived_annotations=True
        )
        print(f"Bound schema to file with derived annotations: {bound_schema_file}")

        # Get the derived keys from the bound schema of the folder
        test_folder.annotations = {"foo": "test_value_new", "bar": 42}  # Example annotations
        test_folder.store()
        print("Added annotations to folder and stored")

        derived_keys = test_folder.get_schema_derived_keys()
        print(f"Derived keys from folder: {derived_keys}")

        # Get the derived keys from the bound schema of the file
        example_file.annotations = {"foo": "test_value_new", "bar": 43}  # Example annotations
        example_file.store()
        print("Added annotations to file and stored")

        derived_keys_file = example_file.get_schema_derived_keys()
        print(f"Derived keys from file: {derived_keys_file}")
        ```
    """
    return JSONSchemaDerivedKeys()

synapseclient.models.RecordBasedMetadataTaskProperties `dataclass` ¶

Bases: EnumCoercionMixin

A CurationTaskProperties for record-based metadata.

Represents a Synapse RecordBasedMetadataTaskProperties.

ATTRIBUTE	DESCRIPTION
`record_set_id`	The synId of the RecordSet that will contain all record-based metadata TYPE: `Optional[str]`
`suggested_authorization_mode`	Recommends who is allowed to access the curation grid session that a client opens for this task. The value is stored on the task as a suggestion; the client applies it when it creates a new session. Choose from SESSION_OWNER (only the person or team who owns the session can access it) or SOURCE_BENEFACTOR (anyone with EDIT permission on the data being curated can access the session). When omitted (None, the default), no recommendation is stored and clients fall back to their usual behavior. TYPE: `Optional[Union[AuthorizationMode, str]]`
`collaborator_principal_ids`	Not actively used at this time. The set of principal IDs that should collaborate on the grid session. Used to set the owner(s) of a linked GridSession when suggested_authorization_mode is SESSION_OWNER. TYPE: `Optional[list[str]]`

Source code in synapseclient/models/curation.py

@dataclass
class RecordBasedMetadataTaskProperties(EnumCoercionMixin):
    """
    A CurationTaskProperties for record-based metadata.

    Represents a [Synapse RecordBasedMetadataTaskProperties](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/curation/metadata/RecordBasedMetadataTaskProperties.html).

    Attributes:
        record_set_id: The synId of the RecordSet that will contain all record-based metadata
        suggested_authorization_mode: Recommends who is allowed to access the curation
            grid session that a client opens for this task. The value is stored on the
            task as a suggestion; the client applies it when it creates a new session.
            Choose from SESSION_OWNER (only the person or team who owns the session can
            access it) or SOURCE_BENEFACTOR (anyone with EDIT permission on the data being
            curated can access the session). When omitted (None, the default), no
            recommendation is stored and clients fall back to their usual behavior.
        collaborator_principal_ids: Not actively used at this time. The set of principal
            IDs that should collaborate on the grid session. Used to set the owner(s) of a
            linked GridSession when suggested_authorization_mode is SESSION_OWNER.
    """

    _ENUM_FIELDS: ClassVar[dict[str, type]] = {
        "suggested_authorization_mode": AuthorizationMode
    }

    record_set_id: Optional[str] = None
    """The synId of the RecordSet that will contain all record-based metadata"""

    suggested_authorization_mode: Optional[Union[AuthorizationMode, str]] = None
    """Recommends who is allowed to access the curation
        grid session that a client opens for this task. The value is stored on the
        task as a suggestion; the client applies it when it creates a new session.
        Choose from:
        - SESSION_OWNER: only the person or team who owns the session can access it.
        - SOURCE_BENEFACTOR: anyone with EDIT permission on the
            data being curated can access the session. This lets editors collaborate
            in the same session without being added to a shared ownership team.
        When omitted (None, the default), no recommendation is stored and clients
        fall back to their usual behavior of finding or creating a private session
        for the current user. Changing this value after the task already exists
        resets the task's active session, so a new grid session must be opened
        before curation can continue."""

    collaborator_principal_ids: Optional[list[str]] = None
    """Not actively used at this time.
    The set of principal IDs that should collaborate on the grid session. Used to set
    the owner(s) of a linked GridSession when suggested_authorization_mode is SESSION_OWNER"""

    def fill_from_dict(
        self, synapse_response: Union[Dict[str, Any], Any]
    ) -> "RecordBasedMetadataTaskProperties":
        """
        Converts a response from the REST API into this dataclass.

        Arguments:
            synapse_response: The response from the REST API.

        Returns:
            The RecordBasedMetadataTaskProperties object.
        """
        self.record_set_id = synapse_response.get("recordSetId", None)
        self.suggested_authorization_mode = synapse_response.get(
            "suggestedAuthorizationMode", None
        )
        self.collaborator_principal_ids = synapse_response.get(
            "collaboratorPrincipalIds", None
        )
        return self

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        request_dict = {
            "concreteType": RECORD_BASED_METADATA_TASK_PROPERTIES,
            "recordSetId": self.record_set_id,
            "suggestedAuthorizationMode": (
                self.suggested_authorization_mode.value
                if self.suggested_authorization_mode is not None
                else None
            ),
            "collaboratorPrincipalIds": self.collaborator_principal_ids,
        }
        delete_none_keys(request_dict)
        return request_dict

Attributes¶

record_set_id `class-attribute` `instance-attribute` ¶

record_set_id: Optional[str] = None

The synId of the RecordSet that will contain all record-based metadata

suggested_authorization_mode `class-attribute` `instance-attribute` ¶

suggested_authorization_mode: Optional[Union[AuthorizationMode, str]] = None

Recommends who is allowed to access the curation grid session that a client opens for this task. The value is stored on the task as a suggestion; the client applies it when it creates a new session. Choose from: - SESSION_OWNER: only the person or team who owns the session can access it. - SOURCE_BENEFACTOR: anyone with EDIT permission on the data being curated can access the session. This lets editors collaborate in the same session without being added to a shared ownership team. When omitted (None, the default), no recommendation is stored and clients fall back to their usual behavior of finding or creating a private session for the current user. Changing this value after the task already exists resets the task's active session, so a new grid session must be opened before curation can continue.

collaborator_principal_ids `class-attribute` `instance-attribute` ¶

collaborator_principal_ids: Optional[list[str]] = None

Not actively used at this time. The set of principal IDs that should collaborate on the grid session. Used to set the owner(s) of a linked GridSession when suggested_authorization_mode is SESSION_OWNER

synapseclient.models.FileBasedMetadataTaskProperties `dataclass` ¶

Bases: EnumCoercionMixin

A CurationTaskProperties for file-based data, describing where data is uploaded and a view which contains the annotations.

Represents a Synapse FileBasedMetadataTaskProperties.

ATTRIBUTE	DESCRIPTION
`upload_folder_id`	The synId of the folder where data files of this type are to be uploaded TYPE: `Optional[str]`
`file_view_id`	The synId of the FileView that shows all data of this type TYPE: `Optional[str]`
`suggested_authorization_mode`	Recommends who is allowed to access the curation grid session that a client opens for this task. The value is stored on the task as a suggestion; the client applies it when it creates a new session. Choose from SESSION_OWNER (only the person or team who owns the session can access it) or SOURCE_BENEFACTOR (anyone with EDIT permission on the data being curated can access the session). When omitted (None, the default), no recommendation is stored and clients fall back to their usual behavior. TYPE: `Optional[Union[AuthorizationMode, str]]`
`collaborator_principal_ids`	Not actively used at this time. The set of principal IDs that should collaborate on the grid session. Used to set the owner(s) of a linked GridSession when suggested_authorization_mode is SESSION_OWNER. TYPE: `Optional[list[str]]`

Source code in synapseclient/models/curation.py

@dataclass
class FileBasedMetadataTaskProperties(EnumCoercionMixin):
    """
    A CurationTaskProperties for file-based data, describing where data is uploaded
    and a view which contains the annotations.

    Represents a [Synapse FileBasedMetadataTaskProperties](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/curation/metadata/FileBasedMetadataTaskProperties.html).

    Attributes:
        upload_folder_id: The synId of the folder where data files of this type are to be uploaded
        file_view_id: The synId of the FileView that shows all data of this type
        suggested_authorization_mode: Recommends who is allowed to access the curation
            grid session that a client opens for this task. The value is stored on the
            task as a suggestion; the client applies it when it creates a new session.
            Choose from SESSION_OWNER (only the person or team who owns the session can
            access it) or SOURCE_BENEFACTOR (anyone with EDIT permission on the data being
            curated can access the session). When omitted (None, the default), no
            recommendation is stored and clients fall back to their usual behavior.
        collaborator_principal_ids: Not actively used at this time. The set of principal
            IDs that should collaborate on the grid session. Used to set the owner(s) of a
            linked GridSession when suggested_authorization_mode is SESSION_OWNER.
    """

    _ENUM_FIELDS: ClassVar[dict[str, type]] = {
        "suggested_authorization_mode": AuthorizationMode
    }

    upload_folder_id: Optional[str] = None
    """The synId of the folder where data files of this type are to be uploaded"""

    file_view_id: Optional[str] = None
    """The synId of the FileView that shows all data of this type"""

    suggested_authorization_mode: Optional[Union[AuthorizationMode, str]] = None
    """Recommends who is allowed to access the curation
        grid session that a client opens for this task. The value is stored on the
        task as a suggestion; the client applies it when it creates a new session.
        Choose from:
        - SESSION_OWNER: only the person or team who owns the session can access it.
        - SOURCE_BENEFACTOR: anyone with EDIT permission on the
            data being curated can access the session. This lets editors collaborate
            in the same session without being added to a shared ownership team.
        When omitted (None, the default), no recommendation is stored and clients
        fall back to their usual behavior of finding or creating a private session
        for the current user. Changing this value after the task already exists
        resets the task's active session, so a new grid session must be opened
        before curation can continue."""

    collaborator_principal_ids: Optional[list[str]] = None
    """Not actively used at this time.
    The set of principal IDs that should collaborate on the grid session. Used to set
    the owner(s) of a linked GridSession when suggested_authorization_mode is SESSION_OWNER"""

    def fill_from_dict(
        self, synapse_response: Union[Dict[str, Any], Any]
    ) -> "FileBasedMetadataTaskProperties":
        """
        Converts a response from the REST API into this dataclass.

        Arguments:
            synapse_response: The response from the REST API.

        Returns:
            The FileBasedMetadataTaskProperties object.
        """
        self.upload_folder_id = synapse_response.get("uploadFolderId", None)
        self.file_view_id = synapse_response.get("fileViewId", None)
        self.suggested_authorization_mode = synapse_response.get(
            "suggestedAuthorizationMode", None
        )
        self.collaborator_principal_ids = synapse_response.get(
            "collaboratorPrincipalIds", None
        )
        return self

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        request_dict = {
            "concreteType": FILE_BASED_METADATA_TASK_PROPERTIES,
            "uploadFolderId": self.upload_folder_id,
            "fileViewId": self.file_view_id,
            "suggestedAuthorizationMode": (
                self.suggested_authorization_mode.value
                if self.suggested_authorization_mode is not None
                else None
            ),
            "collaboratorPrincipalIds": self.collaborator_principal_ids,
        }
        delete_none_keys(request_dict)
        return request_dict

Attributes¶

upload_folder_id `class-attribute` `instance-attribute` ¶

upload_folder_id: Optional[str] = None

The synId of the folder where data files of this type are to be uploaded

file_view_id `class-attribute` `instance-attribute` ¶

file_view_id: Optional[str] = None

The synId of the FileView that shows all data of this type

suggested_authorization_mode `class-attribute` `instance-attribute` ¶

suggested_authorization_mode: Optional[Union[AuthorizationMode, str]] = None

Recommends who is allowed to access the curation grid session that a client opens for this task. The value is stored on the task as a suggestion; the client applies it when it creates a new session. Choose from: - SESSION_OWNER: only the person or team who owns the session can access it. - SOURCE_BENEFACTOR: anyone with EDIT permission on the data being curated can access the session. This lets editors collaborate in the same session without being added to a shared ownership team. When omitted (None, the default), no recommendation is stored and clients fall back to their usual behavior of finding or creating a private session for the current user. Changing this value after the task already exists resets the task's active session, so a new grid session must be opened before curation can continue.

collaborator_principal_ids `class-attribute` `instance-attribute` ¶

collaborator_principal_ids: Optional[list[str]] = None

Not actively used at this time. The set of principal IDs that should collaborate on the grid session. Used to set the owner(s) of a linked GridSession when suggested_authorization_mode is SESSION_OWNER

synapseclient.models.AuthorizationMode ¶

Bases: str, Enum

The authorization mode a client should use when creating a linked grid session for a CurationTask.

See https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/AuthorizationMode.html.

Source code in synapseclient/models/curation.py

class AuthorizationMode(str, Enum):
    """
    The authorization mode a client should use when creating a linked grid session
    for a CurationTask.

    See <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/AuthorizationMode.html>.
    """

    SESSION_OWNER = "SESSION_OWNER"
    """Access is limited to the session owner or members of the owner's team. This is
    the default setting. When a view serves as the source, the owner can access all
    available rows, while other team members see data according to the owner's
    permission scope."""

    SOURCE_BENEFACTOR = "SOURCE_BENEFACTOR"
    """Access is granted to any user who has EDIT (UPDATE) access on all benefactor IDs
    captured when the session was created. This mode allows project administrators to
    enable collaborative grid access for all editors without maintaining a separate
    ownership team. User visibility of rows depends on their individual permissions."""

Attributes¶

SESSION_OWNER `class-attribute` `instance-attribute` ¶

SESSION_OWNER = 'SESSION_OWNER'

Access is limited to the session owner or members of the owner's team. This is the default setting. When a view serves as the source, the owner can access all available rows, while other team members see data according to the owner's permission scope.

SOURCE_BENEFACTOR `class-attribute` `instance-attribute` ¶

SOURCE_BENEFACTOR = 'SOURCE_BENEFACTOR'

Access is granted to any user who has EDIT (UPDATE) access on all benefactor IDs captured when the session was created. This mode allows project administrators to enable collaborative grid access for all editors without maintaining a separate ownership team. User visibility of rows depends on their individual permissions.

synapseclient.models.SyncType ¶

Bases: ForwardCompatibleStrEnum

The type of synchronization to perform on a grid session.

See https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/SyncType.html.

Source code in synapseclient/models/curation.py

class SyncType(ForwardCompatibleStrEnum):
    """
    The type of synchronization to perform on a grid session.

    See <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/SyncType.html>.
    """

    PULL = "PULL"
    """Update the grid with the latest data from the source, without writing the
    grid back to the source. Currently only supported for RecordSet-based grids."""

    PULL_PUSH = "PULL_PUSH"
    """Update the grid with the latest data from the source, then update the source
    (the referenced entities for EntityView-based grids, or the source RecordSet for
    RecordSet-based grids) with the grid data. This is the default when sync_type is
    not specified."""

Attributes¶

PULL `class-attribute` `instance-attribute` ¶

PULL = 'PULL'

Update the grid with the latest data from the source, without writing the grid back to the source. Currently only supported for RecordSet-based grids.

PULL_PUSH `class-attribute` `instance-attribute` ¶

PULL_PUSH = 'PULL_PUSH'

Update the grid with the latest data from the source, then update the source (the referenced entities for EntityView-based grids, or the source RecordSet for RecordSet-based grids) with the grid data. This is the default when sync_type is not specified.

synapseclient.models.Grid `dataclass` ¶

Bases: EnumCoercionMixin, GridSynchronousProtocol

A GridSession provides functionality to create and manage grid sessions in Synapse. Grid sessions are used for curation workflows where data can be edited in a grid format and then exported back to record sets.

ATTRIBUTE	DESCRIPTION
`record_set_id`	The synId of the RecordSet to use for initializing the grid TYPE: `Optional[str]`
`initial_query`	Initialize a grid session from an EntityView. Mutually exclusive with record_set_id. TYPE: `Optional[Query]`
`owner_principal_id`	The principal ID (user or team) that will own the created grid session. When not provided, the principal ID of the caller is used. TYPE: `int \| None`
`authorization_mode`	Controls access permissions and row visibility at session creation time. See AuthorizationMode. When not provided, the service default (SESSION_OWNER) is used. TYPE: `Optional[Union[AuthorizationMode, str]]`
`session_id`	The unique sessionId that identifies the grid session TYPE: `Optional[str]`
`started_by`	The user that started this session TYPE: `Optional[str]`
`started_on`	The date-time when the session was started TYPE: `Optional[str]`
`etag`	Changes when the session changes TYPE: `Optional[str]`
`modified_on`	The date-time when the session was last changed TYPE: `Optional[str]`
`last_replica_id_client`	The last replica ID issued to a client TYPE: `Optional[int]`
`last_replica_id_service`	The last replica ID issued to a service TYPE: `Optional[int]`
`grid_json_schema_id`	The $id of the JSON schema used for model validation TYPE: `Optional[str]`
`source_entity_id`	The synId of the table/view/csv that this grid was cloned from TYPE: `Optional[str]`
`record_set_version_number`	The version number of the exported record set TYPE: `Optional[int]`
`validation_summary_statistics`	Summary statistics for validation results TYPE: `Optional[ValidationSummary]`

Create and manage a grid session workflow

from synapseclient import Synapse
from synapseclient.models import Grid
from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll, SyncType

syn = Synapse()
syn.login()

# Create a new grid session from a record set
grid = Grid(record_set_id="syn1234567")
grid = grid.create()
print(f"Created grid session: {grid.session_id}")

# Validate rows. SelectAll() selects every column, so each row's full
# data is returned alongside its validation results.
with grid.connect() as session:
    query_request = QueryRequest(query=GridQuery(column_selection=[SelectAll()]))
    result = session.validate_rows(query_request=query_request)
    for row in result.rows:
        print(f"Row ID: {row.row_id}, Validation Result: {row.validation_results}")

# Later, push the modified data back to the record set
grid = grid.synchronize(sync_type=SyncType.PULL_PUSH)

# Clean up by deleting the session when done
grid.delete()

Working with grid sessions using queries

from synapseclient import Synapse
from synapseclient.models import Grid
from synapseclient.models.table_components import Query
from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll, SyncType

syn = Synapse()
syn.login()

# Create a grid from an entity view query
query = Query(sql="SELECT * FROM syn1234567")
grid = Grid(initial_query=query)
grid = grid.create()

# Validate rows. SelectAll() selects every column, so each row's full
# data is returned alongside its validation results.
with grid.connect() as session:
    query_request = QueryRequest(query=GridQuery(column_selection=[SelectAll()]))
    result = session.validate_rows(query_request=query_request)
    for row in result.rows:
        print(f"Row ID: {row.row_id}, Validation Result: {row.validation_results}")

# Push when ready
grid = grid.synchronize(sync_type=SyncType.PULL_PUSH)

Source code in synapseclient/models/curation.py

@dataclass
@async_to_sync
class Grid(EnumCoercionMixin, GridSynchronousProtocol):
    """
    A GridSession provides functionality to create and manage grid sessions in Synapse.
    Grid sessions are used for curation workflows where data can be edited in a grid format
    and then exported back to record sets.

    Attributes:
        record_set_id: The synId of the RecordSet to use for initializing the grid
        initial_query: Initialize a grid session from an EntityView.
            Mutually exclusive with record_set_id.
        owner_principal_id: The principal ID (user or team) that will own the
            created grid session. When not provided, the principal ID of the
            caller is used.
        authorization_mode: Controls access permissions and row visibility at
            session creation time. See AuthorizationMode. When not provided, the
            service default (SESSION_OWNER) is used.
        session_id: The unique sessionId that identifies the grid session
        started_by: The user that started this session
        started_on: The date-time when the session was started
        etag: Changes when the session changes
        modified_on: The date-time when the session was last changed
        last_replica_id_client: The last replica ID issued to a client
        last_replica_id_service: The last replica ID issued to a service
        grid_json_schema_id: The $id of the JSON schema used for model validation
        source_entity_id: The synId of the table/view/csv that this grid was cloned from
        record_set_version_number: The version number of the exported record set
        validation_summary_statistics: Summary statistics for validation results

    Example: Create and manage a grid session workflow
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Grid
        from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll, SyncType

        syn = Synapse()
        syn.login()

        # Create a new grid session from a record set
        grid = Grid(record_set_id="syn1234567")
        grid = grid.create()
        print(f"Created grid session: {grid.session_id}")

        # Validate rows. SelectAll() selects every column, so each row's full
        # data is returned alongside its validation results.
        with grid.connect() as session:
            query_request = QueryRequest(query=GridQuery(column_selection=[SelectAll()]))
            result = session.validate_rows(query_request=query_request)
            for row in result.rows:
                print(f"Row ID: {row.row_id}, Validation Result: {row.validation_results}")

        # Later, push the modified data back to the record set
        grid = grid.synchronize(sync_type=SyncType.PULL_PUSH)

        # Clean up by deleting the session when done
        grid.delete()
        ```

    Example: Working with grid sessions using queries
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Grid
        from synapseclient.models.table_components import Query
        from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll, SyncType

        syn = Synapse()
        syn.login()

        # Create a grid from an entity view query
        query = Query(sql="SELECT * FROM syn1234567")
        grid = Grid(initial_query=query)
        grid = grid.create()

        # Validate rows. SelectAll() selects every column, so each row's full
        # data is returned alongside its validation results.
        with grid.connect() as session:
            query_request = QueryRequest(query=GridQuery(column_selection=[SelectAll()]))
            result = session.validate_rows(query_request=query_request)
            for row in result.rows:
                print(f"Row ID: {row.row_id}, Validation Result: {row.validation_results}")

        # Push when ready
        grid = grid.synchronize(sync_type=SyncType.PULL_PUSH)
        ```
    """

    record_set_id: Optional[str] = None
    """The synId of the RecordSet to use for initializing the grid"""

    initial_query: Optional[Query] = None
    """Initialize a grid session from an EntityView.
    Mutually exclusive with record_set_id."""

    owner_principal_id: int | None = None
    """The principal ID (user or team) that will own the created grid session.
    When not provided, the principal ID of the caller is used."""

    authorization_mode: Optional[Union[AuthorizationMode, str]] = None
    """Controls access permissions and row visibility at session creation time.
    See AuthorizationMode. When not provided, the service default (SESSION_OWNER)
    is used."""

    session_id: Optional[str] = None
    """The unique sessionId that identifies the grid session"""

    started_by: Optional[str] = None
    """The user that started this session"""

    started_on: Optional[str] = None
    """The date-time when the session was started"""

    etag: Optional[str] = None
    """Changes when the session changes"""

    modified_on: Optional[str] = None
    """The date-time when the session was last changed"""

    last_replica_id_client: Optional[int] = None
    """The last replica ID issued to a client. Client replica IDs are incremented."""

    last_replica_id_service: Optional[int] = None
    """The last replica ID issued to a service. Service replica IDs are decremented."""

    grid_json_schema_id: Optional[str] = None
    """The $id of the JSON schema that will be used for model validation in this grid session"""

    source_entity_id: Optional[str] = None
    """The synId of the table/view/csv that this grid was cloned from"""

    record_set_version_number: Optional[int] = None
    """The version number of the exported record set"""

    validation_summary_statistics: Optional[ValidationSummary] = None
    """Summary statistics for validation results"""

    _replica_id: Optional[int] = field(default=None, repr=False, compare=False)
    """The replica ID bound to this instance by `connect_async`. Reused by
    `validate_rows_async` so repeated calls do not each create a new replica."""

    _ENUM_FIELDS: ClassVar[dict[str, type]] = {"authorization_mode": AuthorizationMode}

    async def create_async(
        self,
        attach_to_previous_session=False,
        *,
        timeout: int = 120,
        synapse_client: Optional[Synapse] = None,
    ) -> "Grid":
        """
        Creates a new grid session from a `record_set_id` or `initial_query`.

        When using `record_set_id`, first checks for existing active sessions that match
        the record set before creating a new one. When using `initial_query`, always
        creates a new session due to the complexity of matching query parameters.

        Arguments:
            attach_to_previous_session: If True and using `record_set_id`, will attach
                to an existing active session if one exists. Defaults to False.
            timeout: The number of seconds to wait for the job to complete or progress
                before raising a SynapseTimeoutError. Defaults to 120.
            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:
            GridSession: The GridSession object with populated session_id.

        Raises:
            ValueError: If `record_set_id` or `initial_query` is not provided.

        Example: Create a grid session asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                # Create a grid session from a record set
                grid = Grid(record_set_id="syn1234567")
                grid = await grid.create_async()
                print(f"Created grid session: {grid.session_id}")

            asyncio.run(main())
            ```
        """
        if not self.record_set_id and not self.initial_query:
            raise ValueError(
                "record_set_id or initial_query is required to create a GridSession"
            )

        trace.get_current_span().set_attributes(
            {
                "synapse.record_set_id": self.record_set_id or "",
                "synapse.session_id": self.session_id or "",
            }
        )

        # Check for existing active sessions only when using record_set_id
        # For initial_query, always create a new session due to complexity of matching
        if self.record_set_id and attach_to_previous_session:
            # Look for existing active sessions for this record set
            async for existing_session in self.list_async(
                source_id=self.record_set_id, synapse_client=synapse_client
            ):
                # Found an existing session, populate this object with its data and return
                self.session_id = existing_session.session_id
                self.started_by = existing_session.started_by
                self.started_on = existing_session.started_on
                self.etag = existing_session.etag
                self.modified_on = existing_session.modified_on
                self.last_replica_id_client = existing_session.last_replica_id_client
                self.last_replica_id_service = existing_session.last_replica_id_service
                self.grid_json_schema_id = existing_session.grid_json_schema_id
                self.source_entity_id = existing_session.source_entity_id
                return self

        # No existing session found, create a new one
        create_request = CreateGridRequest(
            record_set_id=self.record_set_id,
            initial_query=self.initial_query,
            owner_principal_id=self.owner_principal_id,
            authorization_mode=self.authorization_mode,
        )
        result = await create_request.send_job_and_wait_async(
            timeout=timeout, synapse_client=synapse_client
        )

        # Fill this GridSession with the grid session data from the async job response
        result.fill_grid_session_from_response(self)

        return self

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: f"Grid_Get: ID: {self.session_id}"
    )
    async def get_async(self, *, synapse_client: Optional[Synapse] = None) -> "Grid":
        """
        Get a grid session from Synapse by its session_id.

        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:
            The Grid object populated with the session data from Synapse.

        Raises:
            ValueError: If session_id is not provided.

        Example: Get a grid session by its session id asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                grid = await Grid(session_id="abc-123-def").get_async()
                print(f"Source entity: {grid.source_entity_id}")

            asyncio.run(main())
            ```
        """
        if not self.session_id:
            raise ValueError("session_id is required to get a GridSession")

        response = await get_grid_session(
            session_id=self.session_id, synapse_client=synapse_client
        )
        self.fill_from_dict(response)
        return self

    @deprecated(
        version="4.14.0",
        reason="Use `synchronize_async` with `sync_type=SyncType.PULL_PUSH` instead.",
    )
    async def export_to_record_set_async(
        self, *, timeout: int = 120, synapse_client: Optional[Synapse] = None
    ) -> "Grid":
        """
        Exports the grid session data back to a record set. This will create a new version
        of the original record set with the modified data from the grid session.

        WARNING - This method is deprecated and will be removed in a future release.
        Use `synchronize`/`synchronize_async` with `sync_type=SyncType.PULL_PUSH` instead.

        Arguments:
            timeout: The number of seconds to wait for the job to complete or progress
                before raising a SynapseTimeoutError. Defaults to 120.
            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:
            GridSession: The GridSession object with export information populated.

        Raises:
            ValueError: If session_id is not provided.

        Example: Migration to synchronize_async
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Grid
            from synapseclient.models.curation import SyncType

            syn = Synapse()
            syn.login()

            async def main():
                grid = Grid(session_id="abc-123-def")

                # Old approach (DEPRECATED)
                # grid = await grid.export_to_record_set_async()
                # print(f"Exported to record set: {grid.record_set_id}")
                # print(f"Version number: {grid.record_set_version_number}")
                # if grid.validation_summary_statistics:
                #     print(f"Valid records: {grid.validation_summary_statistics.number_of_valid_children}")

                # New approach (RECOMMENDED)
                # Note: unlike export_to_record_set_async, synchronize_async
                # does not populate record_set_id, record_set_version_number,
                # or validation_summary_statistics on the returned Grid.
                grid = await grid.synchronize_async(sync_type=SyncType.PULL_PUSH)

            asyncio.run(main())
            ```
        """
        if not self.session_id:
            raise ValueError("session_id is required to export a GridSession")

        trace.get_current_span().set_attributes(
            {
                "synapse.session_id": self.session_id or "",
            }
        )

        # Create and send the export request
        export_request = GridRecordSetExportRequest(session_id=self.session_id)
        result = await export_request.send_job_and_wait_async(
            timeout=timeout, synapse_client=synapse_client
        )

        self.record_set_id = result.response_record_set_id
        self.record_set_version_number = result.record_set_version_number
        self.validation_summary_statistics = result.validation_summary_statistics

        return self

    def fill_from_dict(self, synapse_response: Dict[str, Any]) -> "Grid":
        """Converts a response from the REST API into this dataclass."""
        self.session_id = synapse_response.get("sessionId", None)
        self.started_by = synapse_response.get("startedBy", None)
        self.started_on = synapse_response.get("startedOn", None)
        self.etag = synapse_response.get("etag", None)
        self.modified_on = synapse_response.get("modifiedOn", None)
        self.last_replica_id_client = synapse_response.get("lastReplicaIdClient", None)
        self.last_replica_id_service = synapse_response.get(
            "lastReplicaIdService", None
        )
        self.grid_json_schema_id = synapse_response.get("gridJsonSchema$Id", None)
        self.source_entity_id = synapse_response.get("sourceEntityId", None)
        owner_principal_id = synapse_response.get("ownerPrincipalId")
        self.owner_principal_id = (
            int(owner_principal_id) if owner_principal_id is not None else None
        )
        self.authorization_mode = synapse_response.get("authorizationMode", None)
        return self

    @skip_async_to_sync
    @classmethod
    async def list_async(
        cls,
        source_id: Optional[str] = None,
        *,
        synapse_client: Optional[Synapse] = None,
    ) -> AsyncGenerator["Grid", None]:
        """
        Generator to get a list of active grid sessions for the user.

        Arguments:
            source_id: Optional. When provided, only sessions with this synId will be returned.
            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.

        Yields:
            Grid objects representing active grid sessions.

        Example: List all active grid sessions asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                # List all active grid sessions for the user
                async for grid in Grid.list_async():
                    print(f"Session ID: {grid.session_id}")
                    print(f"Source Entity: {grid.source_entity_id}")
                    print(f"Started: {grid.started_on}")
                    print("---")

                # List grid sessions for a specific source
                async for grid in Grid.list_async(source_id="syn1234567"):
                    print(f"Session ID: {grid.session_id}")
                    print(f"Modified: {grid.modified_on}")

            asyncio.run(main())
            ```
        """
        async for session_dict in list_grid_sessions(
            source_id=source_id, synapse_client=synapse_client
        ):
            # Convert the dictionary to a Grid object
            grid = cls()
            grid.fill_from_dict(session_dict)
            yield grid

    @classmethod
    def list(
        cls,
        source_id: Optional[str] = None,
        *,
        synapse_client: Optional[Synapse] = None,
    ) -> Generator["Grid", None, None]:
        """
        Generator to get a list of active grid sessions for the user.

        Arguments:
            source_id: Optional. When provided, only sessions with this synId will be returned.
            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.

        Yields:
            Grid objects representing active grid sessions.
        """
        return wrap_async_generator_to_sync_generator(
            async_gen_func=cls.list_async,
            source_id=source_id,
            synapse_client=synapse_client,
        )

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: f"Grid_Delete: ID: {self.session_id}"
    )
    async def delete_async(self, *, synapse_client: Optional[Synapse] = None) -> None:
        """
        Delete the grid session.

        Note: Only the user that created a grid session may delete it.

        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:
            None

        Raises:
            ValueError: If session_id is not provided.

        Example: Delete a grid session asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                # Delete the grid session
                grid = Grid(session_id="abc-123-def")
                await grid.delete_async()
                print("Grid session deleted successfully")

            asyncio.run(main())
            ```
        """
        if not self.session_id:
            raise ValueError("session_id is required to delete a GridSession")

        trace.get_current_span().set_attributes(
            {
                "synapse.session_id": self.session_id or "",
            }
        )

        await delete_grid_session(
            session_id=self.session_id, synapse_client=synapse_client
        )

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: f"Grid_ImportCsv: ID: {self.session_id}"
    )
    async def import_csv_async(
        self,
        path: str,
        *,
        timeout: int = 120,
        csv_table_descriptor: Optional[CsvTableDescriptor] = None,
        synapse_client: Optional[Synapse] = None,
    ) -> "Grid":
        """
        Import a CSV file into this grid session. Previews the file to determine
        the column schema, then imports the data. Currently supports only grids
        created from a record set.

        Arguments:
            path: Local path to the CSV file to import.
            csv_table_descriptor: The description of the CSV format (delimiter,
                quote character, etc.). If not provided, the default CSV format
                will be used.
            timeout: The number of seconds to wait for each async job to complete
                or progress before raising a SynapseTimeoutError. Defaults to 120.
            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 Grid object.

        Raises:
            ValueError: If session_id is not provided.

        Example: Import a CSV file into a grid session asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                grid = Grid(session_id="abc-123-def")
                grid = await grid.import_csv_async(path="/local/path/to/data.csv")
                print(f"Import complete for session: {grid.session_id}")

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

        if not self.session_id:
            raise ValueError(
                "session_id is required to import a CSV into a GridSession"
            )

        if not os.path.isfile(path):
            raise ValueError(f"Path '{path}' is not a valid file.")

        trace.get_current_span().set_attributes(
            {
                "synapse.session_id": self.session_id,
            }
        )

        client = Synapse.get_client(synapse_client=synapse_client)
        file_handle = await upload_synapse_s3(syn=client, file_path=path)
        file_handle_id = file_handle["id"]

        effective_descriptor = csv_table_descriptor or CsvTableDescriptor()

        upload_to_table_preview = UploadToTablePreviewRequest(
            csv_table_descriptor=effective_descriptor,
            upload_file_handle_id=file_handle_id,
        )

        preview_response = await upload_to_table_preview.send_job_and_wait_async(
            timeout=timeout, synapse_client=synapse_client
        )
        if not preview_response.suggested_columns:
            raise ValueError(
                f"CSV preview for file handle {file_handle_id} returned no suggested "
                f"columns (rows scanned: {preview_response.rows_scanned}). The file may "
                f"be empty, contain only a header row, or use a separator different "
                f"from the configured csv_table_descriptor "
                f"(separator={repr(effective_descriptor.separator)})."
            )

        import_request = GridCsvImportRequest(
            session_id=self.session_id,
            file_handle_id=file_handle_id,
            schema=preview_response.suggested_columns,
            csv_descriptor=effective_descriptor,
        )
        import_response = await import_request.send_job_and_wait_async(
            timeout=timeout, synapse_client=synapse_client
        )
        client.logger.info(
            f"CSV import to grid session {self.session_id} completed successfully, "
            f"total count: {import_response.total_count}, "
            f"total created: {import_response.created_count}, "
            f"total updated: {import_response.updated_count}"
        )

        return self

    @otel_trace_method(
        method_to_trace_name=lambda self, *args, **kwargs: f"Grid_DownloadCsv: ID: {self.session_id}"
    )
    async def download_csv_async(
        self,
        *,
        destination: Optional[str] = None,
        write_header: bool = True,
        include_row_id_and_row_version: bool = False,
        include_etag: bool = False,
        csv_table_descriptor: Optional[CsvTableDescriptor] = None,
        file_name: Optional[str] = None,
        timeout: int = 120,
        synapse_client: Optional[Synapse] = None,
    ) -> str:
        """
        Asynchronously download the current state of this grid session as a CSV file.

        Submits a DownloadFromGridRequest async job, waits for it to complete,
        then downloads the resulting CSV to the local filesystem.

        Arguments:
            destination: Local directory path where the CSV will be saved. The directory must already exist.
                If not provided, defaults to the current working directory.
            write_header: Whether the first line should contain column names
                as a header. Defaults to True.
            include_row_id_and_row_version: Whether the first two columns
                should contain row ID and version. Defaults to False.
            include_etag: Whether a column should contain the row etag.
                Defaults to False.
            csv_table_descriptor: The description of the CSV format (delimiter,
                quote character, etc.). If not provided, the default CSV format
                will be used.
            file_name: The optional name for the downloaded file. If not
                provided, defaults to `grid_{session_id}-{timestamp}.csv`.
            timeout: The number of seconds to wait for the async job to
                complete or progress before raising a SynapseTimeoutError.
                Defaults to 120.
            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 local path to the downloaded CSV file.

        Raises:
            ValueError: If session_id is not provided.

        Example: Download a grid session as a CSV asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                grid = Grid(session_id="abc-123-def")
                path = await grid.download_csv_async(destination="./downloads")
                print(f"Downloaded CSV to: {path}")

            asyncio.run(main())
            ```

        Example: Download a grid session as a CSV with a custom file name asynchronously
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                grid = Grid(session_id="abc-123-def")
                path = await grid.download_csv_async(
                    destination="./downloads", file_name="my_export.csv"
                )
                print(f"Downloaded CSV to: {path}")

            asyncio.run(main())
            ```
        """
        if not self.session_id:
            raise ValueError("session_id is required to download a GridSession as CSV")

        if not destination:
            destination = os.getcwd()

        if not os.path.isdir(destination):
            raise ValueError(f"Destination {destination} is not a valid directory.")

        trace.get_current_span().set_attributes({"synapse.session_id": self.session_id})

        effective_descriptor = csv_table_descriptor or CsvTableDescriptor()
        request = DownloadFromGridRequest(
            session_id=self.session_id,
            write_header=write_header,
            include_row_id_and_row_version=include_row_id_and_row_version,
            include_etag=include_etag,
            csv_table_descriptor=effective_descriptor,
            file_name=file_name,
        )
        download_response = await request.send_job_and_wait_async(
            timeout=timeout, synapse_client=synapse_client
        )
        if not download_response.results_file_handle_id:
            raise ValueError(
                f"Download job for grid session '{self.session_id}' completed but "
                "did not return a file handle ID. The CSV result may be empty or "
                "the job may have failed silently."
            )
        file_handle, presigned_url = await asyncio.gather(
            get_file_handle(
                file_handle_id=download_response.results_file_handle_id,
                synapse_client=synapse_client,
            ),
            get_file_handle_presigned_url(
                file_handle_id=download_response.results_file_handle_id,
                synapse_client=synapse_client,
            ),
        )
        if not file_name:
            timestamp = datetime.now(tz=timezone.utc).strftime("%Y%m%d%H%M%S")
            file_name = f"grid_{self.session_id}-{timestamp}.csv"
        file_path = os.path.join(destination, file_name)
        return await asyncio.to_thread(
            download_from_url,
            url=presigned_url,
            destination=file_path,
            file_handle_id=file_handle["id"],
            expected_md5=file_handle.get("contentMd5"),
            url_is_presigned=True,
            synapse_client=synapse_client,
        )

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: f"Grid_Synchronize: ID: {self.session_id}"
    )
    async def synchronize_async(
        self,
        *,
        sync_type: Optional[Union[SyncType, str]] = None,
        timeout: int = 120,
        synapse_client: Optional[Synapse] = None,
    ) -> "Grid":
        """
        Synchronizes the grid session's schema and row data against its source entity.

        Grid sessions created from a file view via `initial_query` always perform a
        full PULL_PUSH. Grid sessions backed by a RecordSet may instead pass
        `sync_type=SyncType.PULL` to pull the latest RecordSet data/schema into the
        session for review, without immediately writing the merged result back as a
        new RecordSet version. Once satisfied with the result, call this method again
        (with `sync_type` omitted, or explicitly set to `SyncType.PULL_PUSH`) to push
        the merged data back to the RecordSet as a new version.

        Arguments:
            sync_type: The type of synchronization to perform. Optional; the server
                defaults to `SyncType.PULL_PUSH` when omitted. `SyncType.PULL` is
                currently only supported for RecordSet-based grids.
            timeout: The number of seconds to wait for the job to complete or progress
                before raising a SynapseTimeoutError. Defaults to 120.
            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:
            Grid: The Grid object.

        Raises:
            ValueError: If session_id is not provided.

        Example: Synchronize a grid session created from a file view
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Grid
            from synapseclient.models.table_components import Query

            syn = Synapse()
            syn.login()

            async def main():
                # First create a grid session from a file view
                query = Query(sql="SELECT * FROM syn1234567")
                grid = Grid(initial_query=query)
                grid = await grid.create_async()

                # Synchronize the grid with the latest state of the file view
                grid = await grid.synchronize_async()

            asyncio.run(main())
            ```

        Example: Preview a RecordSet-backed grid's merge before pushing it back
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Grid
            from synapseclient.models.curation import SyncType

            syn = Synapse()
            syn.login()

            async def main():
                grid = Grid(record_set_id="syn1234567")
                grid = await grid.create_async()

                # Pull in the latest RecordSet data/schema without pushing back yet
                grid = await grid.synchronize_async(sync_type=SyncType.PULL)

                # ... review the merged result in the grid session ...

                # Push the merged result back as a new RecordSet version
                grid = await grid.synchronize_async(sync_type=SyncType.PULL_PUSH)

            asyncio.run(main())
            ```
        """
        if not self.session_id:
            raise ValueError("session_id is required to synchronize a GridSession")

        request = SynchronizeGridRequest(
            grid_session_id=self.session_id, sync_type=sync_type
        )
        result = await request.send_job_and_wait_async(
            timeout=timeout, synapse_client=synapse_client
        )

        if result.error_messages:
            client = Synapse.get_client(synapse_client=synapse_client)
            client.logger.error(
                f"Grid session '{self.session_id}' synchronization completed with "
                f"error messages: {result.error_messages}"
            )

        return self

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: f"Grid_Create_Replica_Session_ID: {self.session_id}"
    )
    async def _create_replica_async(
        self, *, synapse_client: Optional[Synapse] = None
    ) -> "GridReplica":
        """
        Creates a new replica for this grid session.

        A grid replica is an in-memory document that represents a 'copy' of the
        grid. Each replica is identified by a unique replicaId, issued by the
        'hub'. A user can have more than one replica at a time (i.e. using
        multiple browser tabs/machines). Only the user that started the grid session
        may create a replica.

        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:
            The newly created GridReplica.

        Raises:
            ValueError: If session_id is not provided, or if the Synapse response
                did not contain replica information.

        Example: Create a replica for a grid session
            &nbsp;

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

            syn = Synapse()
            syn.login()

            async def main():
                grid = Grid(record_set_id="syn1234567")
                grid = await grid.create_async()

                replica = await grid._create_replica_async()
                print(f"Replica created with ID: {replica.replica_id}")

            asyncio.run(main())
            ```
        """
        if not self.session_id:
            raise ValueError(
                "session_id is required to create a replica for a GridSession"
            )

        grid_replica = await create_grid_replica(
            session_id=self.session_id,
            create_replica_request=CreateReplicaRequest(
                self.session_id
            ).to_synapse_request(),
            synapse_client=synapse_client,
        )
        replica_data = grid_replica.get("replica")
        if not replica_data:
            raise ValueError(
                f"Replica could not be created for grid session '{self.session_id}': "
                f"no replica was returned in the Synapse response."
            )
        return GridReplica().fill_from_dict(replica_data)

    @skip_async_to_sync
    @asynccontextmanager
    async def connect_async(
        self,
        *,
        attach_to_previous_session: bool = False,
        timeout: int = 120,
        synapse_client: Optional[Synapse] = None,
    ) -> AsyncGenerator["Grid", None]:
        """
        Connects to a grid session and binds a single replica to it for the
        duration of the `async with` block.

        If `session_id` is not already set (e.g. from `create_grid_session`),
        creates a new grid session first via `record_set_id` or
        `initial_query`, same as `create_async`. Either way, one replica is
        then created (see `_create_replica_async`) that is reused by every
        `validate_rows_async` call made within the block.

        Arguments:
            attach_to_previous_session: Only applies when creating a new
                session from `record_set_id`. If True, attaches to an existing
                active session instead of creating a new one. Defaults to False.
            timeout: The number of seconds to wait for the job to complete or progress
                before raising a SynapseTimeoutError. Defaults to 120.
            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.

        Yields:
            The connected Grid, with a replica bound to it.

        Example: Validate rows using a newly created grid session
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Grid
            from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll

            syn = Synapse()
            syn.login()

            async def main():
                async with Grid(record_set_id="syn1234567").connect_async() as session:
                    query_request = QueryRequest(
                        query=GridQuery(column_selection=[SelectAll()])
                    )
                    result = await session.validate_rows_async(query_request=query_request)
                    for row in result.rows:
                        print(f"Row ID: {row.row_id}, Validation Result: {row.validation_results}")

            asyncio.run(main())
            ```

        Example: Validate rows using an existing grid session
            &nbsp;

            If a session_id is already set, connect_async will not create a new
            grid session

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import CurationTask, Grid
            from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll

            syn = Synapse()
            syn.login()

            task = CurationTask(task_id="1234")
            grid = task.create_grid_session()

            async def main():
                async with grid.connect_async() as session:
                    query_request = QueryRequest(
                        query=GridQuery(column_selection=[SelectAll()])
                    )
                    result = await session.validate_rows_async(query_request=query_request)
                    for row in result.rows:
                        print(f"Row ID: {row.row_id}, Validation Result: {row.validation_results}")

            asyncio.run(main())
            ```
        """
        trace.get_current_span().set_attributes(
            {
                "synapse.record_set_id": self.record_set_id or "",
                "synapse.session_id": self.session_id or "",
            }
        )

        if not self.session_id:
            await self.create_async(
                attach_to_previous_session=attach_to_previous_session,
                timeout=timeout,
                synapse_client=synapse_client,
            )

        replica = await self._create_replica_async(synapse_client=synapse_client)
        self._replica_id = replica.replica_id
        try:
            yield self
        finally:
            self._replica_id = None

    @contextmanager
    def connect(
        self,
        *,
        attach_to_previous_session: bool = False,
        timeout: int = 120,
        synapse_client: Optional[Synapse] = None,
    ) -> Generator["Grid", None, None]:
        """
        Synchronous equivalent of `connect_async`.

        Connects to a grid session and binds a single replica to it for the
        duration of the `with` block.

        If `session_id` is not already set (e.g. from `create_grid_session`),
        creates a new grid session first via `record_set_id` or
        `initial_query`, same as `create`. Either way, one replica is then
        created (see `_create_replica`) that is reused by every
        `validate_rows` call made within the block.

        Arguments:
            attach_to_previous_session: Only applies when creating a new
                session from `record_set_id`. If True, attaches to an existing
                active session instead of creating a new one. Defaults to False.
            timeout: The number of seconds to wait for the job to complete or progress
                before raising a SynapseTimeoutError. Defaults to 120.
            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.

        Yields:
            The connected Grid, with a replica bound to it.

        Example: Validate rows using a newly created grid session
            &nbsp;

            ```python
            from synapseclient import Synapse
            from synapseclient.models import Grid
            from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll

            syn = Synapse()
            syn.login()

            with Grid(record_set_id="syn1234567").connect() as session:
                query_request = QueryRequest(
                    query=GridQuery(column_selection=[SelectAll()])
                )
                result = session.validate_rows(query_request=query_request)
                for row in result.rows:
                    print(f"Row ID: {row.row_id}, Validation Result: {row.validation_results}")
            ```

        Example: Validate rows using an existing grid session
            &nbsp;

            If a session_id is already set, connect will not create a new grid
            session.

            ```python
            from synapseclient import Synapse
            from synapseclient.models import CurationTask, Grid
            from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll

            syn = Synapse()
            syn.login()

            task = CurationTask(task_id="1234")
            grid = task.create_grid_session()

            with grid.connect() as session:
                query_request = QueryRequest(
                    query=GridQuery(column_selection=[SelectAll()])
                )
                result = session.validate_rows(query_request=query_request)
                for row in result.rows:
                    print(f"Row ID: {row.row_id}, Validation Result: {row.validation_results}")
            ```
        """
        trace.get_current_span().set_attributes(
            {
                "synapse.record_set_id": self.record_set_id or "",
                "synapse.session_id": self.session_id or "",
            }
        )

        if not self.session_id:
            self.create(
                attach_to_previous_session=attach_to_previous_session,
                timeout=timeout,
                synapse_client=synapse_client,
            )

        replica = self._create_replica(synapse_client=synapse_client)
        self._replica_id = replica.replica_id
        try:
            yield self
        finally:
            self._replica_id = None

    @otel_trace_method(
        method_to_trace_name=lambda self, **kwargs: f"Grid_Validate_Rows_Session_ID: {self.session_id}"
    )
    async def validate_rows_async(
        self,
        *,
        timeout: int = 120,
        query_request: QueryRequest,
        synapse_client: Optional[Synapse] = None,
    ) -> Optional["GridQueryResult"]:
        """
        Queries this grid session's rows and returns their per-row validation
        results against the grid's bound JSON schema.

        This Grid must have been obtained from `connect_async` (or `connect`),
        which binds a replica to it. The given query_request is then submitted
        to the grid session using that replica, and this waits for the job to
        complete.

        Arguments:
            timeout: The number of seconds to wait for the job to complete or progress
                before raising a SynapseTimeoutError. Defaults to 120.
            query_request: The structured query to run against the grid, wrapping a
                GridQuery that defines the column selection, filters, and whether to
                include the detailed `all_validation_messages` list on each row.
            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 GridQueryResult containing the selected columns and rows, each with its own validation_results, or None if the completed job did not return a query_result. Logs a warning if the job completed but no rows matched the query.

        Raises:
            ValueError: If session_id is not provided, or if no replica is bound
                to this Grid (see `connect_async`/`connect`).

        Example: Validate every row of a grid session
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Grid
            from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll

            syn = Synapse()
            syn.login()

            async def main():
                async with Grid(record_set_id="syn1234567").connect_async() as grid:
                    # SelectAll() selects every column in the grid, so each row's
                    # full data is returned alongside its validation results.
                    query_request = QueryRequest(
                        query=GridQuery(column_selection=[SelectAll()])
                    )
                    query_result = await grid.validate_rows_async(query_request=query_request)

                    for row in query_result.rows:
                        validation = row.validation_results
                        print(f"Row ID: {row.row_id}, Validation Result: {validation}")

            asyncio.run(main())
            ```

        Example: Validate only the currently invalid rows of a grid session
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.models import Grid
            from synapseclient.models.curation import (
                GridQuery,
                QueryRequest,
                RowIsValidFilter,
                SelectAll,
            )

            syn = Synapse()
            syn.login()

            async def main():
                async with Grid(record_set_id="syn1234567").connect_async() as grid:
                    # Filter to only the rows that are currently invalid, and request
                    # the detailed allValidationMessages list on each one.
                    query_request = QueryRequest(
                        query=GridQuery(
                            column_selection=[SelectAll()],
                            filters=[RowIsValidFilter(value=False)],
                            include_validation_messages=True,
                        )
                    )
                    query_result = await grid.validate_rows_async(query_request=query_request)

                    for row in query_result.rows:
                        print(f"Invalid row {row.row_id}: {row.validation_results}")

            asyncio.run(main())
            ```
        """
        if not self.session_id:
            raise ValueError("session_id is required to validate rows")

        if self._replica_id is None:
            raise ValueError(
                "No replica is bound to this Grid. Use `connect_async` (or "
                "`connect`) to connect to a grid session before calling "
                "validate_rows_async."
            )

        request = GridQueryJobRequest(
            session_id=self.session_id,
            replica_id=self._replica_id,
            query_request=query_request,
        )
        request = await request.send_job_and_wait_async(
            timeout=timeout, synapse_client=synapse_client
        )

        if not request.query_result or not request.query_result.rows:
            client = Synapse.get_client(synapse_client=synapse_client)
            client.logger.warning(
                f"Validation job for grid session '{self.session_id}' completed but "
                "did not return any row validation results. This grid may not have "
                "any rows matching the query."
            )
        return request.query_result

Methods:¶

create ¶

create(attach_to_previous_session=False, *, timeout: int = 120, synapse_client: Optional[Synapse] = None) -> Grid

Creates a new grid session from a record_set_id or initial_query.

PARAMETER	DESCRIPTION
`attach_to_previous_session`	If True and using `record_set_id`, will attach to an existing active session if one exists. Defaults to False. DEFAULT: `False`
`timeout`	The number of seconds to wait for the job to complete or progress before raising a SynapseTimeoutError. Defaults to 120. TYPE: `int` DEFAULT: `120`
`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
`GridSession`	The GridSession object with populated session_id. TYPE: `Grid`

RAISES	DESCRIPTION
`ValueError`	If `record_set_id` or `initial_query` is not provided.

Create a grid session from a record set

from synapseclient import Synapse
from synapseclient.models import Grid

syn = Synapse()
syn.login()

# Create a grid session from a record set
grid = Grid(record_set_id="syn1234567")
grid = grid.create()
print(f"Created grid session: {grid.session_id}")

Create a grid session from a query

from synapseclient import Synapse
from synapseclient.models import Grid
from synapseclient.models.table_components import Query

syn = Synapse()
syn.login()

# Create a grid session from an entity view query
query = Query(sql="SELECT * FROM syn1234567")
grid = Grid(initial_query=query)
grid = grid.create()
print(f"Created grid session: {grid.session_id}")

Source code in synapseclient/models/curation.py

def create(
    self,
    attach_to_previous_session=False,
    *,
    timeout: int = 120,
    synapse_client: Optional[Synapse] = None,
) -> "Grid":
    """
    Creates a new grid session from a `record_set_id` or `initial_query`.

    Arguments:
        attach_to_previous_session: If True and using `record_set_id`, will attach
            to an existing active session if one exists. Defaults to False.
        timeout: The number of seconds to wait for the job to complete or progress
            before raising a SynapseTimeoutError. Defaults to 120.
        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:
        GridSession: The GridSession object with populated session_id.

    Raises:
        ValueError: If `record_set_id` or `initial_query` is not provided.

    Example: Create a grid session from a record set
        &nbsp;

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

        syn = Synapse()
        syn.login()

        # Create a grid session from a record set
        grid = Grid(record_set_id="syn1234567")
        grid = grid.create()
        print(f"Created grid session: {grid.session_id}")
        ```

    Example: Create a grid session from a query
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Grid
        from synapseclient.models.table_components import Query

        syn = Synapse()
        syn.login()

        # Create a grid session from an entity view query
        query = Query(sql="SELECT * FROM syn1234567")
        grid = Grid(initial_query=query)
        grid = grid.create()
        print(f"Created grid session: {grid.session_id}")
        ```
    """
    return self

get ¶

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

Get a grid session from Synapse by its session_id.

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
`Grid`	The Grid object populated with the session data from Synapse.

RAISES	DESCRIPTION
`ValueError`	If session_id is not provided.

Get a grid session by its session id

from synapseclient import Synapse
from synapseclient.models import Grid

syn = Synapse()
syn.login()

grid = Grid(session_id="abc-123-def").get()
print(f"Source entity: {grid.source_entity_id}")

Source code in synapseclient/models/curation.py

def get(self, *, synapse_client: Optional[Synapse] = None) -> "Grid":
    """
    Get a grid session from Synapse by its session_id.

    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:
        The Grid object populated with the session data from Synapse.

    Raises:
        ValueError: If session_id is not provided.

    Example: Get a grid session by its session id
        &nbsp;

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

        syn = Synapse()
        syn.login()

        grid = Grid(session_id="abc-123-def").get()
        print(f"Source entity: {grid.source_entity_id}")
        ```
    """
    return self

export_to_record_set ¶

export_to_record_set(*, timeout: int = 120, synapse_client: Optional[Synapse] = None) -> Grid

Exports the grid session data back to a record set. This will create a new version of the original record set with the modified data from the grid session.

WARNING - This method is deprecated and will be removed in a future release. Use synchronize/synchronize_async with sync_type=SyncType.PULL_PUSH instead.

PARAMETER	DESCRIPTION
`timeout`	The number of seconds to wait for the job to complete or progress before raising a SynapseTimeoutError. Defaults to 120. TYPE: `int` DEFAULT: `120`
`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
`GridSession`	The GridSession object with export information populated. TYPE: `Grid`

RAISES	DESCRIPTION
`ValueError`	If session_id is not provided.

Migration to synchronize

from synapseclient import Synapse
from synapseclient.models import Grid
from synapseclient.models.curation import SyncType

syn = Synapse()
syn.login()

grid = Grid(session_id="abc-123-def")

# Old approach (DEPRECATED)
# grid = grid.export_to_record_set()
# print(f"Exported to record set: {grid.record_set_id}")
# print(f"Version number: {grid.record_set_version_number}")
# if grid.validation_summary_statistics:
#     print(f"Valid records: {grid.validation_summary_statistics.number_of_valid_children}")

# New approach (RECOMMENDED)
# Note: unlike export_to_record_set, synchronize does not populate
# record_set_id, record_set_version_number, or
# validation_summary_statistics on the returned Grid.
grid = grid.synchronize(sync_type=SyncType.PULL_PUSH)

Source code in synapseclient/models/curation.py

def export_to_record_set(
    self, *, timeout: int = 120, synapse_client: Optional[Synapse] = None
) -> "Grid":
    """
    Exports the grid session data back to a record set. This will create a new version
    of the original record set with the modified data from the grid session.

    WARNING - This method is deprecated and will be removed in a future release.
    Use `synchronize`/`synchronize_async` with `sync_type=SyncType.PULL_PUSH` instead.

    Arguments:
        timeout: The number of seconds to wait for the job to complete or progress
            before raising a SynapseTimeoutError. Defaults to 120.
        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:
        GridSession: The GridSession object with export information populated.

    Raises:
        ValueError: If session_id is not provided.

    Example: Migration to synchronize
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Grid
        from synapseclient.models.curation import SyncType

        syn = Synapse()
        syn.login()

        grid = Grid(session_id="abc-123-def")

        # Old approach (DEPRECATED)
        # grid = grid.export_to_record_set()
        # print(f"Exported to record set: {grid.record_set_id}")
        # print(f"Version number: {grid.record_set_version_number}")
        # if grid.validation_summary_statistics:
        #     print(f"Valid records: {grid.validation_summary_statistics.number_of_valid_children}")

        # New approach (RECOMMENDED)
        # Note: unlike export_to_record_set, synchronize does not populate
        # record_set_id, record_set_version_number, or
        # validation_summary_statistics on the returned Grid.
        grid = grid.synchronize(sync_type=SyncType.PULL_PUSH)
        ```
    """
    return self

synchronize ¶

synchronize(*, sync_type: Optional[Union[SyncType, str]] = None, timeout: int = 120, synapse_client: Optional[Synapse] = None) -> Grid

Synchronizes the grid session's schema and row data against its source entity.

Grid sessions created from a file view via initial_query always perform a full PULL_PUSH. Grid sessions backed by a RecordSet may instead pass sync_type=SyncType.PULL to pull the latest RecordSet data/schema into the session for review, without immediately writing the merged result back as a new RecordSet version. Once satisfied with the result, call this method again (with sync_type omitted, or explicitly set to SyncType.PULL_PUSH) to push the merged data back to the RecordSet as a new version.

PARAMETER	DESCRIPTION
`sync_type`	The type of synchronization to perform. Optional; the server defaults to `SyncType.PULL_PUSH` when omitted. `SyncType.PULL` is currently only supported for RecordSet-based grids. TYPE: `Optional[Union[SyncType, str]]` DEFAULT: `None`
`timeout`	The number of seconds to wait for the job to complete or progress before raising a SynapseTimeoutError. Defaults to 120. TYPE: `int` DEFAULT: `120`
`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
`Grid`	The Grid object. TYPE: `Grid`

RAISES	DESCRIPTION
`ValueError`	If session_id is not provided.

Synchronize a grid session created from a file view

from synapseclient import Synapse
from synapseclient.models import Grid
from synapseclient.models.table_components import Query

syn = Synapse()
syn.login()

# First create a grid session from a file view
query = Query(sql="SELECT * FROM syn1234567")
grid = Grid(initial_query=query)
grid = grid.create()

# Synchronize the grid with the latest state of the file view
grid = grid.synchronize()

Preview a RecordSet-backed grid's merge before pushing it back

from synapseclient import Synapse
from synapseclient.models import Grid
from synapseclient.models.curation import SyncType

syn = Synapse()
syn.login()

grid = Grid(record_set_id="syn1234567")
grid = grid.create()

# Pull in the latest RecordSet data/schema without pushing back yet
grid = grid.synchronize(sync_type=SyncType.PULL)

# ... review the merged result in the grid session ...

# Push the merged result back as a new RecordSet version
grid = grid.synchronize(sync_type=SyncType.PULL_PUSH)

Source code in synapseclient/models/curation.py

def synchronize(
    self,
    *,
    sync_type: Optional[Union[SyncType, str]] = None,
    timeout: int = 120,
    synapse_client: Optional[Synapse] = None,
) -> "Grid":
    """
    Synchronizes the grid session's schema and row data against its source entity.

    Grid sessions created from a file view via `initial_query` always perform a
    full PULL_PUSH. Grid sessions backed by a RecordSet may instead pass
    `sync_type=SyncType.PULL` to pull the latest RecordSet data/schema into the
    session for review, without immediately writing the merged result back as a
    new RecordSet version. Once satisfied with the result, call this method again
    (with `sync_type` omitted, or explicitly set to `SyncType.PULL_PUSH`) to push
    the merged data back to the RecordSet as a new version.

    Arguments:
        sync_type: The type of synchronization to perform. Optional; the server
            defaults to `SyncType.PULL_PUSH` when omitted. `SyncType.PULL` is
            currently only supported for RecordSet-based grids.
        timeout: The number of seconds to wait for the job to complete or progress
            before raising a SynapseTimeoutError. Defaults to 120.
        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:
        Grid: The Grid object.

    Raises:
        ValueError: If session_id is not provided.

    Example: Synchronize a grid session created from a file view
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Grid
        from synapseclient.models.table_components import Query

        syn = Synapse()
        syn.login()

        # First create a grid session from a file view
        query = Query(sql="SELECT * FROM syn1234567")
        grid = Grid(initial_query=query)
        grid = grid.create()

        # Synchronize the grid with the latest state of the file view
        grid = grid.synchronize()
        ```

    Example: Preview a RecordSet-backed grid's merge before pushing it back
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Grid
        from synapseclient.models.curation import SyncType

        syn = Synapse()
        syn.login()

        grid = Grid(record_set_id="syn1234567")
        grid = grid.create()

        # Pull in the latest RecordSet data/schema without pushing back yet
        grid = grid.synchronize(sync_type=SyncType.PULL)

        # ... review the merged result in the grid session ...

        # Push the merged result back as a new RecordSet version
        grid = grid.synchronize(sync_type=SyncType.PULL_PUSH)
        ```
    """
    return self

download_csv ¶

download_csv(*, destination: Optional[str] = None, write_header: bool = True, include_row_id_and_row_version: bool = False, include_etag: bool = False, csv_table_descriptor: Optional[CsvTableDescriptor] = None, file_name: Optional[str] = None, timeout: int = 120, synapse_client: Optional[Synapse] = None) -> str

Download the current state of this grid session as a CSV file.

Submits a DownloadFromGridRequest async job, waits for it to complete, then downloads the resulting CSV to the local filesystem.

PARAMETER	DESCRIPTION
`destination`	Local directory path where the CSV will be saved. If not provided, defaults to the current working directory. The directory must already exist. TYPE: `Optional[str]` DEFAULT: `None`
`write_header`	Whether the first line should contain column names as a header. Defaults to True. TYPE: `bool` DEFAULT: `True`
`include_row_id_and_row_version`	Whether the first two columns should contain row ID and version. Defaults to False. TYPE: `bool` DEFAULT: `False`
`include_etag`	Whether a column should contain the row etag. Defaults to False. TYPE: `bool` DEFAULT: `False`
`csv_table_descriptor`	The description of the CSV format (delimiter, quote character, etc.). If not provided, the default CSV format will be used. TYPE: `Optional[CsvTableDescriptor]` DEFAULT: `None`
`file_name`	The optional name for the downloaded file. If not provided, defaults to `grid_{session_id}-{timestamp}.csv`. TYPE: `Optional[str]` DEFAULT: `None`
`timeout`	The number of seconds to wait for the async job to complete or progress before raising a SynapseTimeoutError. Defaults to 120. TYPE: `int` DEFAULT: `120`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)` this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

RETURNS	DESCRIPTION
`str`	The local path to the downloaded CSV file.

RAISES	DESCRIPTION
`ValueError`	If session_id is not provided.

Download a grid session as a CSV

from synapseclient import Synapse
from synapseclient.models import Grid

syn = Synapse()
syn.login()

grid = Grid(session_id="abc-123-def")
path = grid.download_csv(destination="./downloads")
print(f"Downloaded CSV to: {path}")

Download a grid session as a CSV with a custom file name

from synapseclient import Synapse
from synapseclient.models import Grid

syn = Synapse()
syn.login()

grid = Grid(session_id="abc-123-def")
path = grid.download_csv(destination="./downloads", file_name="my_export.csv")
print(f"Downloaded CSV to: {path}")

Source code in synapseclient/models/curation.py

def download_csv(
    self,
    *,
    destination: Optional[str] = None,
    write_header: bool = True,
    include_row_id_and_row_version: bool = False,
    include_etag: bool = False,
    csv_table_descriptor: Optional[CsvTableDescriptor] = None,
    file_name: Optional[str] = None,
    timeout: int = 120,
    synapse_client: Optional[Synapse] = None,
) -> str:
    """
    Download the current state of this grid session as a CSV file.

    Submits a DownloadFromGridRequest async job, waits for it to complete,
    then downloads the resulting CSV to the local filesystem.

    Arguments:
        destination: Local directory path where the CSV will be saved.
            If not provided, defaults to the current working directory. The directory must already exist.
        write_header: Whether the first line should contain column names
            as a header. Defaults to True.
        include_row_id_and_row_version: Whether the first two columns
            should contain row ID and version. Defaults to False.
        include_etag: Whether a column should contain the row etag.
            Defaults to False.
        csv_table_descriptor: The description of the CSV format (delimiter,
            quote character, etc.). If not provided, the default CSV format
            will be used.
        file_name: The optional name for the downloaded file. If not
            provided, defaults to `grid_{session_id}-{timestamp}.csv`.
        timeout: The number of seconds to wait for the async job to
            complete or progress before raising a SynapseTimeoutError.
            Defaults to 120.
        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 local path to the downloaded CSV file.

    Raises:
        ValueError: If session_id is not provided.

    Example: Download a grid session as a CSV
        &nbsp;

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

        syn = Synapse()
        syn.login()

        grid = Grid(session_id="abc-123-def")
        path = grid.download_csv(destination="./downloads")
        print(f"Downloaded CSV to: {path}")
        ```

    Example: Download a grid session as a CSV with a custom file name
        &nbsp;

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

        syn = Synapse()
        syn.login()

        grid = Grid(session_id="abc-123-def")
        path = grid.download_csv(destination="./downloads", file_name="my_export.csv")
        print(f"Downloaded CSV to: {path}")
        ```
    """
    return ""

import_csv ¶

import_csv(path: str, *, timeout: int = 120, csv_table_descriptor: Optional[CsvTableDescriptor] = None, synapse_client: Optional[Synapse] = None) -> Grid

Import a CSV file into this grid session. Previews the file to determine the column schema, then imports the data. Currently supports only grids created from a record set.

PARAMETER	DESCRIPTION
`path`	Local path to the CSV file to import. TYPE: `str`
`csv_table_descriptor`	The description of the CSV format (delimiter, quote character, etc.). If not provided, the default CSV format will be used. TYPE: `Optional[CsvTableDescriptor]` DEFAULT: `None`
`timeout`	The number of seconds to wait for each async job to complete or progress before raising a SynapseTimeoutError. Defaults to 120. TYPE: `int` DEFAULT: `120`
`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
`Grid`	The Grid object.

RAISES	DESCRIPTION
`ValueError`	If session_id is not provided.

Import a CSV file into a grid session

from synapseclient import Synapse
from synapseclient.models import Grid

syn = Synapse()
syn.login()

grid = Grid(session_id="abc-123-def")
grid = grid.import_csv(path="/local/path/to/data.csv")
print(f"Import complete for session: {grid.session_id}")

Source code in synapseclient/models/curation.py

def import_csv(
    self,
    path: str,
    *,
    timeout: int = 120,
    csv_table_descriptor: Optional[CsvTableDescriptor] = None,
    synapse_client: Optional[Synapse] = None,
) -> "Grid":
    """
    Import a CSV file into this grid session. Previews the file to determine
    the column schema, then imports the data. Currently supports only grids
    created from a record set.

    Arguments:
        path: Local path to the CSV file to import.
        csv_table_descriptor: The description of the CSV format (delimiter,
            quote character, etc.). If not provided, the default CSV format
            will be used.
        timeout: The number of seconds to wait for each async job to complete
            or progress before raising a SynapseTimeoutError. Defaults to 120.
        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 Grid object.

    Raises:
        ValueError: If session_id is not provided.

    Example: Import a CSV file into a grid session
        &nbsp;

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

        syn = Synapse()
        syn.login()

        grid = Grid(session_id="abc-123-def")
        grid = grid.import_csv(path="/local/path/to/data.csv")
        print(f"Import complete for session: {grid.session_id}")
        ```
    """
    return self

delete ¶

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

Delete the grid session.

Note: Only the user that created a grid session may delete it.

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
`None`	None

RAISES	DESCRIPTION
`ValueError`	If session_id is not provided.

Delete a grid session

from synapseclient import Synapse
from synapseclient.models import Grid

syn = Synapse()
syn.login()

# Delete the grid session
grid = Grid(session_id="abc-123-def")
grid.delete()

Source code in synapseclient/models/curation.py

def delete(self, *, synapse_client: Optional[Synapse] = None) -> None:
    """
    Delete the grid session.

    Note: Only the user that created a grid session may delete it.

    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:
        None

    Raises:
        ValueError: If session_id is not provided.

    Example: Delete a grid session
        &nbsp;

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

        syn = Synapse()
        syn.login()

        # Delete the grid session
        grid = Grid(session_id="abc-123-def")
        grid.delete()
        ```
    """
    return None

list `classmethod` ¶

list(source_id: Optional[str] = None, *, synapse_client: Optional[Synapse] = None) -> Generator[Grid, None, None]

Generator to get a list of active grid sessions for the user.

PARAMETER	DESCRIPTION
`source_id`	Optional. When provided, only sessions with this synId will be returned. TYPE: `Optional[str]` DEFAULT: `None`
`synapse_client`	If not passed in and caching was not disabled by `Synapse.allow_client_caching(False)` this will use the last created instance from the Synapse class constructor. TYPE: `Optional[Synapse]` DEFAULT: `None`

YIELDS	DESCRIPTION
`Grid`	Grid objects representing active grid sessions.

Source code in synapseclient/models/curation.py

@classmethod
def list(
    cls,
    source_id: Optional[str] = None,
    *,
    synapse_client: Optional[Synapse] = None,
) -> Generator["Grid", None, None]:
    """
    Generator to get a list of active grid sessions for the user.

    Arguments:
        source_id: Optional. When provided, only sessions with this synId will be returned.
        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.

    Yields:
        Grid objects representing active grid sessions.
    """
    return wrap_async_generator_to_sync_generator(
        async_gen_func=cls.list_async,
        source_id=source_id,
        synapse_client=synapse_client,
    )

connect ¶

connect(*, attach_to_previous_session: bool = False, timeout: int = 120, synapse_client: Optional[Synapse] = None) -> Generator[Grid, None, None]

Synchronous equivalent of connect_async.

Connects to a grid session and binds a single replica to it for the duration of the with block.

If session_id is not already set (e.g. from create_grid_session), creates a new grid session first via record_set_id or initial_query, same as create. Either way, one replica is then created (see _create_replica) that is reused by every validate_rows call made within the block.

PARAMETER	DESCRIPTION
`attach_to_previous_session`	Only applies when creating a new session from `record_set_id`. If True, attaches to an existing active session instead of creating a new one. Defaults to False. TYPE: `bool` DEFAULT: `False`
`timeout`	The number of seconds to wait for the job to complete or progress before raising a SynapseTimeoutError. Defaults to 120. TYPE: `int` DEFAULT: `120`
`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`

YIELDS	DESCRIPTION
`Grid`	The connected Grid, with a replica bound to it.

Validate rows using a newly created grid session

from synapseclient import Synapse
from synapseclient.models import Grid
from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll

syn = Synapse()
syn.login()

with Grid(record_set_id="syn1234567").connect() as session:
    query_request = QueryRequest(
        query=GridQuery(column_selection=[SelectAll()])
    )
    result = session.validate_rows(query_request=query_request)
    for row in result.rows:
        print(f"Row ID: {row.row_id}, Validation Result: {row.validation_results}")

Validate rows using an existing grid session

If a session_id is already set, connect will not create a new grid session.

from synapseclient import Synapse
from synapseclient.models import CurationTask, Grid
from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll

syn = Synapse()
syn.login()

task = CurationTask(task_id="1234")
grid = task.create_grid_session()

with grid.connect() as session:
    query_request = QueryRequest(
        query=GridQuery(column_selection=[SelectAll()])
    )
    result = session.validate_rows(query_request=query_request)
    for row in result.rows:
        print(f"Row ID: {row.row_id}, Validation Result: {row.validation_results}")

Source code in synapseclient/models/curation.py

@contextmanager
def connect(
    self,
    *,
    attach_to_previous_session: bool = False,
    timeout: int = 120,
    synapse_client: Optional[Synapse] = None,
) -> Generator["Grid", None, None]:
    """
    Synchronous equivalent of `connect_async`.

    Connects to a grid session and binds a single replica to it for the
    duration of the `with` block.

    If `session_id` is not already set (e.g. from `create_grid_session`),
    creates a new grid session first via `record_set_id` or
    `initial_query`, same as `create`. Either way, one replica is then
    created (see `_create_replica`) that is reused by every
    `validate_rows` call made within the block.

    Arguments:
        attach_to_previous_session: Only applies when creating a new
            session from `record_set_id`. If True, attaches to an existing
            active session instead of creating a new one. Defaults to False.
        timeout: The number of seconds to wait for the job to complete or progress
            before raising a SynapseTimeoutError. Defaults to 120.
        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.

    Yields:
        The connected Grid, with a replica bound to it.

    Example: Validate rows using a newly created grid session
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Grid
        from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll

        syn = Synapse()
        syn.login()

        with Grid(record_set_id="syn1234567").connect() as session:
            query_request = QueryRequest(
                query=GridQuery(column_selection=[SelectAll()])
            )
            result = session.validate_rows(query_request=query_request)
            for row in result.rows:
                print(f"Row ID: {row.row_id}, Validation Result: {row.validation_results}")
        ```

    Example: Validate rows using an existing grid session
        &nbsp;

        If a session_id is already set, connect will not create a new grid
        session.

        ```python
        from synapseclient import Synapse
        from synapseclient.models import CurationTask, Grid
        from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll

        syn = Synapse()
        syn.login()

        task = CurationTask(task_id="1234")
        grid = task.create_grid_session()

        with grid.connect() as session:
            query_request = QueryRequest(
                query=GridQuery(column_selection=[SelectAll()])
            )
            result = session.validate_rows(query_request=query_request)
            for row in result.rows:
                print(f"Row ID: {row.row_id}, Validation Result: {row.validation_results}")
        ```
    """
    trace.get_current_span().set_attributes(
        {
            "synapse.record_set_id": self.record_set_id or "",
            "synapse.session_id": self.session_id or "",
        }
    )

    if not self.session_id:
        self.create(
            attach_to_previous_session=attach_to_previous_session,
            timeout=timeout,
            synapse_client=synapse_client,
        )

    replica = self._create_replica(synapse_client=synapse_client)
    self._replica_id = replica.replica_id
    try:
        yield self
    finally:
        self._replica_id = None

validate_rows ¶

validate_rows(*, timeout: int = 120, query_request: QueryRequest, synapse_client: Optional[Synapse] = None) -> Optional[GridQueryResult]

Queries this grid session's rows and returns their per-row validation results against the grid's bound JSON schema.

This Grid must have been obtained from connect_async (or connect), which binds a replica to it. The given query_request is then submitted to the grid session using that replica, and this waits for the job to complete.

PARAMETER	DESCRIPTION
`timeout`	The number of seconds to wait for the job to complete or progress before raising a SynapseTimeoutError. Defaults to 120. TYPE: `int` DEFAULT: `120`
`query_request`	The structured query to run against the grid, wrapping a GridQuery that defines the column selection, filters, and whether to include the detailed `all_validation_messages` list on each row. TYPE: `QueryRequest`
`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
`Optional[GridQueryResult]`	The GridQueryResult containing the selected columns and rows, each with its own validation_results, or None if the completed job did not return a query_result. Logs a warning if the job completed but no rows matched the query.

RAISES	DESCRIPTION
`ValueError`	If session_id is not provided, or if no replica is bound to this Grid (see `connect_async`/`connect`).

Validate every row of a grid session

from synapseclient import Synapse
from synapseclient.models import Grid
from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll

syn = Synapse()
syn.login()

with Grid(record_set_id="syn1234567").connect() as grid:
    # SelectAll() selects every column in the grid, so each row's full
    # data is returned alongside its validation results.
    query_request = QueryRequest(query=GridQuery(column_selection=[SelectAll()]))
    query_result = grid.validate_rows(query_request=query_request)

    for row in query_result.rows:
        validation = row.validation_results
        print(f"Row ID: {row.row_id}, Validation Result: {validation}")

Validate only the currently invalid rows of a grid session

from synapseclient import Synapse
from synapseclient.models import Grid
from synapseclient.models.curation import (
    GridQuery,
    QueryRequest,
    RowIsValidFilter,
    SelectAll,
)

syn = Synapse()
syn.login()

with Grid(record_set_id="syn1234567").connect() as grid:
    # Filter to only the rows that are currently invalid, and request the
    # detailed allValidationMessages list on each one.
    query_request = QueryRequest(
        query=GridQuery(
            column_selection=[SelectAll()],
            filters=[RowIsValidFilter(value=False)],
            include_validation_messages=True,
        )
    )
    query_result = grid.validate_rows(query_request=query_request)

    for row in query_result.rows:
        print(f"Invalid row {row.row_id}: {row.validation_results}")

Source code in synapseclient/models/curation.py

def validate_rows(
    self,
    *,
    timeout: int = 120,
    query_request: "QueryRequest",
    synapse_client: Optional[Synapse] = None,
) -> Optional["GridQueryResult"]:
    """
    Queries this grid session's rows and returns their per-row validation
    results against the grid's bound JSON schema.

    This Grid must have been obtained from `connect_async` (or `connect`),
    which binds a replica to it. The given query_request is then submitted
    to the grid session using that replica, and this waits for the job to
    complete.

    Arguments:
        timeout: The number of seconds to wait for the job to complete or progress
            before raising a SynapseTimeoutError. Defaults to 120.
        query_request: The structured query to run against the grid, wrapping a
            GridQuery that defines the column selection, filters, and whether to
            include the detailed `all_validation_messages` list on each row.
        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 GridQueryResult containing the selected columns and rows, each with its own validation_results, or None if the completed job did not return a query_result. Logs a warning if the job completed but no rows matched the query.

    Raises:
        ValueError: If session_id is not provided, or if no replica is bound
            to this Grid (see `connect_async`/`connect`).

    Example: Validate every row of a grid session
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Grid
        from synapseclient.models.curation import GridQuery, QueryRequest, SelectAll

        syn = Synapse()
        syn.login()

        with Grid(record_set_id="syn1234567").connect() as grid:
            # SelectAll() selects every column in the grid, so each row's full
            # data is returned alongside its validation results.
            query_request = QueryRequest(query=GridQuery(column_selection=[SelectAll()]))
            query_result = grid.validate_rows(query_request=query_request)

            for row in query_result.rows:
                validation = row.validation_results
                print(f"Row ID: {row.row_id}, Validation Result: {validation}")
        ```

    Example: Validate only the currently invalid rows of a grid session
        &nbsp;

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Grid
        from synapseclient.models.curation import (
            GridQuery,
            QueryRequest,
            RowIsValidFilter,
            SelectAll,
        )

        syn = Synapse()
        syn.login()

        with Grid(record_set_id="syn1234567").connect() as grid:
            # Filter to only the rows that are currently invalid, and request the
            # detailed allValidationMessages list on each one.
            query_request = QueryRequest(
                query=GridQuery(
                    column_selection=[SelectAll()],
                    filters=[RowIsValidFilter(value=False)],
                    include_validation_messages=True,
                )
            )
            query_result = grid.validate_rows(query_request=query_request)

            for row in query_result.rows:
                print(f"Invalid row {row.row_id}: {row.validation_results}")
        ```
    """
    return None

synapseclient.models.Query `dataclass` ¶

Represents a SQL query with optional parameters.

This result is modeled from: https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/Query.html

Source code in synapseclient/models/table_components.py

@dataclass
class Query:
    """
    Represents a SQL query with optional parameters.

    This result is modeled from: <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/Query.html>
    """

    sql: str
    """The SQL query string"""

    additional_filters: Optional[List[Dict[str, Any]]] = None
    """Appends additional filters to the SQL query. These are applied before facets.
    Filters within the list have an AND relationship. If a WHERE clause already exists
    on the SQL query or facets are selected, it will also be ANDed with the query
    generated by these additional filters."""
    """TODO: create QueryFilter dataclass: https://sagebionetworks.jira.com/browse/SYNPY-1651"""

    selected_facets: Optional[List[Dict[str, Any]]] = None
    """The selected facet filters"""
    """TODO: create FacetColumnRequest dataclass: https://sagebionetworks.jira.com/browse/SYNPY-1651"""

    include_entity_etag: Optional[bool] = False
    """Optional, default false. When true, a query results against views will include
    the Etag of each entity in the results. Note: The etag is necessary to update
    Entities in the view."""

    select_file_column: Optional[int] = None
    """The id of the column used to select file entities (e.g. to fetch the action
    required for download). The column needs to be an ENTITYID type column and be
    part of the schema of the underlying table/view."""

    select_file_version_column: Optional[int] = None
    """The id of the column used as the version for selecting file entities when required
    (e.g. to add a materialized view query to the download cart with version enabled).
    The column needs to be an INTEGER type column and be part of the schema of the
    underlying table/view."""

    offset: Optional[int] = None
    """The optional offset into the results"""

    limit: Optional[int] = None
    """The optional limit to the results"""

    sort: Optional[List[Dict[str, Any]]] = None
    """The sort order for the query results (ARRAY<SortItem>)"""
    """TODO: Add SortItem dataclass: https://sagebionetworks.jira.com/browse/SYNPY-1651 """

    def to_synapse_request(self) -> Dict[str, Any]:
        """Converts the Query object into a dictionary that can be passed into the REST API."""
        result = {
            "sql": self.sql,
            "additionalFilters": self.additional_filters,
            "selectedFacets": self.selected_facets,
            "includeEntityEtag": self.include_entity_etag,
            "selectFileColumn": self.select_file_column,
            "selectFileVersionColumn": self.select_file_version_column,
            "offset": self.offset,
            "limit": self.limit,
            "sort": self.sort,
        }
        delete_none_keys(result)
        return result

Attributes¶

sql `instance-attribute` ¶

sql: str

The SQL query string

additional_filters `class-attribute` `instance-attribute` ¶

additional_filters: Optional[List[Dict[str, Any]]] = None

Appends additional filters to the SQL query. These are applied before facets. Filters within the list have an AND relationship. If a WHERE clause already exists on the SQL query or facets are selected, it will also be ANDed with the query generated by these additional filters.

selected_facets `class-attribute` `instance-attribute` ¶

selected_facets: Optional[List[Dict[str, Any]]] = None

The selected facet filters

include_entity_etag `class-attribute` `instance-attribute` ¶

include_entity_etag: Optional[bool] = False

Optional, default false. When true, a query results against views will include the Etag of each entity in the results. Note: The etag is necessary to update Entities in the view.

select_file_column `class-attribute` `instance-attribute` ¶

select_file_column: Optional[int] = None

The id of the column used to select file entities (e.g. to fetch the action required for download). The column needs to be an ENTITYID type column and be part of the schema of the underlying table/view.

select_file_version_column `class-attribute` `instance-attribute` ¶

select_file_version_column: Optional[int] = None

The id of the column used as the version for selecting file entities when required (e.g. to add a materialized view query to the download cart with version enabled). The column needs to be an INTEGER type column and be part of the schema of the underlying table/view.

offset `class-attribute` `instance-attribute` ¶

offset: Optional[int] = None

The optional offset into the results

limit `class-attribute` `instance-attribute` ¶

limit: Optional[int] = None

The optional limit to the results

sort `class-attribute` `instance-attribute` ¶

sort: Optional[List[Dict[str, Any]]] = None

The sort order for the query results (ARRAY)

synapseclient.models.curation.GridQuery `dataclass` ¶

A structured grid query, expressed with JSON SelectItem and Filter objects rather than SQL syntax.

Represents a Synapse Query.

Note: This is distinct from the SQL-based table Query (org.sagebionetworks.repo.model.table.Query, imported here as Query), which takes a SQL string rather than structured select items and filters.

ATTRIBUTE	DESCRIPTION
`column_selection`	One or more SelectItem is required to define the columns that will be returned by this query (e.g. SelectAll, CountStar). TYPE: `list[SelectItem]`
`filters`	Each filter must be a complete JSON object with the required 'concreteType' property. Multiple filters are combined with AND logic. TYPE: `Optional[list[Filter]]`
`limit`	Limit of the number of rows returned to avoid loading more data than needed into your context window. TYPE: `Optional[int]`
`offset`	Specifies where the first returned row begins in the result set. TYPE: `Optional[int]`
`include_validation_messages`	Controls whether the 'allValidationMessages' array appears in the response. Defaults to false to conserve token usage. TYPE: `Optional[bool]`

Source code in synapseclient/models/curation.py

@dataclass
class GridQuery:
    """
    A structured grid query, expressed with JSON SelectItem and Filter objects
    rather than SQL syntax.

    Represents a [Synapse Query](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/Query.html).

    Note: This is distinct from the SQL-based table
    [Query](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/Query.html)
    (`org.sagebionetworks.repo.model.table.Query`, imported here as `Query`), which
    takes a SQL string rather than structured select items and filters.

    Attributes:
        column_selection: One or more SelectItem is required to define the
            columns that will be returned by this query (e.g. SelectAll,
            CountStar).
        filters: Each filter must be a complete JSON object with the required
            'concreteType' property. Multiple filters are combined with AND logic.
        limit: Limit of the number of rows returned to avoid loading more data
            than needed into your context window.
        offset: Specifies where the first returned row begins in the result set.
        include_validation_messages: Controls whether the
            'allValidationMessages' array appears in the response. Defaults to
            false to conserve token usage.
    """

    column_selection: list[SelectItem] = field(default_factory=list)
    """One or more SelectItem is required to define the columns that will be
    returned by this query."""

    limit: Optional[int] = None
    """Limit of the number of rows returned to avoid loading more data than
    needed into your context window."""

    filters: Optional[list[Filter]] = None
    """Each filter must be a complete JSON object with the required
    'concreteType' property. Multiple filters are combined with AND logic."""

    offset: Optional[int] = None
    """Specifies where the first returned row begins in the result set."""

    include_validation_messages: Optional[bool] = None
    """Controls whether the 'allValidationMessages' array appears in the response."""

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.

        Raises:
            ValueError: If column_selection is empty.
        """
        if not self.column_selection:
            raise ValueError(
                "column_selection is required and must contain at least one "
                "SelectItem."
            )

        request_dict = {
            "columnSelection": [
                item.to_synapse_request() for item in self.column_selection
            ],
            "filters": (
                [item.to_synapse_request() for item in self.filters]
                if self.filters is not None
                else None
            ),
            "limit": self.limit,
            "offset": self.offset,
            "includeValidationMessages": self.include_validation_messages,
        }
        delete_none_keys(request_dict)
        return request_dict

Attributes¶

column_selection `class-attribute` `instance-attribute` ¶

column_selection: list[SelectItem] = field(default_factory=list)

One or more SelectItem is required to define the columns that will be returned by this query.

limit `class-attribute` `instance-attribute` ¶

limit: Optional[int] = None

Limit of the number of rows returned to avoid loading more data than needed into your context window.

filters `class-attribute` `instance-attribute` ¶

filters: Optional[list[Filter]] = None

Each filter must be a complete JSON object with the required 'concreteType' property. Multiple filters are combined with AND logic.

offset `class-attribute` `instance-attribute` ¶

offset: Optional[int] = None

Specifies where the first returned row begins in the result set.

include_validation_messages `class-attribute` `instance-attribute` ¶

include_validation_messages: Optional[bool] = None

Controls whether the 'allValidationMessages' array appears in the response.

synapseclient.models.curation.QueryRequest `dataclass` ¶

Request to run a query.

Represents a Synapse QueryRequest.

ATTRIBUTE	DESCRIPTION
`query`	Defines a structured query using JSON SelectItems and Filters objects - NOT SQL syntax. TYPE: `Optional[GridQuery]`

Source code in synapseclient/models/curation.py

@dataclass
class QueryRequest:
    """
    Request to run a query.

    Represents a [Synapse QueryRequest](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/QueryRequest.html).

    Attributes:
        query: Defines a structured query using JSON SelectItems and Filters objects - NOT SQL syntax.
    """

    query: Optional[GridQuery] = None
    """Defines a structured query using JSON SelectItems and Filters objects (not SQL syntax)."""

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        request_dict = {
            "query": self.query.to_synapse_request() if self.query else None,
        }
        delete_none_keys(request_dict)
        return request_dict

Attributes¶

query `class-attribute` `instance-attribute` ¶

query: Optional[GridQuery] = None

Defines a structured query using JSON SelectItems and Filters objects (not SQL syntax).

synapseclient.models.curation.SelectItem `dataclass` ¶

Bases: ABC

A generic select item.

https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/SelectItem.html

Known implementations: SelectByName, SelectAll, CountStar, SelectSelection.

The concrete subclass is determined by the concreteType field in the REST response.

Source code in synapseclient/models/curation.py

@dataclass
class SelectItem(ABC):
    """
    A generic select item.

    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/SelectItem.html>

    Known implementations: SelectByName, SelectAll, CountStar, SelectSelection.

    The concrete subclass is determined by the concreteType field in the REST response.
    """

    @abstractmethod
    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        ...

synapseclient.models.curation.SelectByName `dataclass` ¶

Bases: SelectItem

A SelectItem that will result in the selection of a single column by its name.

https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/SelectByName.html

ATTRIBUTE	DESCRIPTION
`column_name`	The name of the column to include in the select. TYPE: `Optional[str]`

Source code in synapseclient/models/curation.py

@dataclass
class SelectByName(SelectItem):
    """
    A SelectItem that will result in the selection of a single column by its name.

    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/SelectByName.html>

    Attributes:
        column_name: The name of the column to include in the select.
    """

    column_name: Optional[str] = None
    """The name of the column to include in the select."""

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        request_dict = {"concreteType": SELECT_BY_NAME, "columnName": self.column_name}
        delete_none_keys(request_dict)
        return request_dict

Attributes¶

column_name `class-attribute` `instance-attribute` ¶

column_name: Optional[str] = None

The name of the column to include in the select.

synapseclient.models.curation.SelectAll `dataclass` ¶

Bases: SelectItem

A SelectItem that will result in the selection of all columns.

https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/SelectAll.html

Source code in synapseclient/models/curation.py

@dataclass
class SelectAll(SelectItem):
    """
    A SelectItem that will result in the selection of all columns.

    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/SelectAll.html>
    """

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        return {"concreteType": SELECT_ALL}

synapseclient.models.curation.CountStar `dataclass` ¶

Bases: SelectItem

Use this to count the total number of rows that match the query. For example, for a user request like 'how many rows are there in total?', select this item. The alias property can be used to name the resulting count column.

https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/function/CountStar.html

ATTRIBUTE	DESCRIPTION
`alias`	Used to name the resulting count column. TYPE: `Optional[str]`

Source code in synapseclient/models/curation.py

@dataclass
class CountStar(SelectItem):
    """
    Use this to count the total number of rows that match the query. For example,
    for a user request like 'how many rows are there in total?', select this item.
    The alias property can be used to name the resulting count column.

    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/function/CountStar.html>

    Attributes:
        alias: Used to name the resulting count column.
    """

    alias: Optional[str] = None
    """Used to name the resulting count column."""

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        request_dict = {"concreteType": COUNT_STAR, "alias": self.alias}
        delete_none_keys(request_dict)
        return request_dict

Attributes¶

alias `class-attribute` `instance-attribute` ¶

alias: Optional[str] = None

Used to name the resulting count column.

synapseclient.models.curation.SelectSelection `dataclass` ¶

Bases: SelectItem

A SelectItem that will result in the selection of the columns the user has actively selected in the interface.

https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/SelectSelection.html

Source code in synapseclient/models/curation.py

@dataclass
class SelectSelection(SelectItem):
    """
    A SelectItem that will result in the selection of the columns the user has
    actively selected in the interface.

    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/SelectSelection.html>
    """

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        return {"concreteType": SELECT_SELECTION}

synapseclient.models.curation.Filter `dataclass` ¶

Bases: ABC

There are five different types of filters that can be applied to a grid query.

https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/Filter.html

Known implementations: RowValidationResultFilter, CellValueFilter, RowSelectionFilter, RowIsValidFilter, RowIdFilter.

The concrete subclass is determined by the concreteType field in the REST response.

Source code in synapseclient/models/curation.py

@dataclass
class Filter(ABC):
    """
    There are five different types of filters that can be applied to a grid query.

    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/Filter.html>

    Known implementations: RowValidationResultFilter, CellValueFilter,
    RowSelectionFilter, RowIsValidFilter, RowIdFilter.

    The concrete subclass is determined by the concreteType field in the REST response.
    """

    @abstractmethod
    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        ...

synapseclient.models.curation.RowValidationResultFilter `dataclass` ¶

Bases: Filter, EnumCoercionMixin

Use this filter to find rows that have data quality issues or schema validation errors.

https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/RowValidationResultFilter.html

To find type errors, use the LIKE operator with '%expected type:%' as the validation result value.

ATTRIBUTE	DESCRIPTION
`operator`	The comparison operator. TYPE: `Optional[Union[ValidationOperator, str]]`
`validation_result_value`	A validation result value. For wildcards use '%' to represents zero or more characters, and '_' to represents a single character. TYPE: `Optional[str]`

Source code in synapseclient/models/curation.py

@dataclass
class RowValidationResultFilter(Filter, EnumCoercionMixin):
    """
    Use this filter to find rows that have data quality issues or schema
    validation errors.

    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/RowValidationResultFilter.html>

    To find type errors, use the LIKE operator with '%expected type:%' as the
    validation result value.

    Attributes:
        operator: The comparison operator.
        validation_result_value: A validation result value. For wildcards use
            '%' to represents zero or more characters, and '_' to represents a
            single character.
    """

    _ENUM_FIELDS: ClassVar[dict[str, type]] = {"operator": ValidationOperator}

    operator: Optional[Union[ValidationOperator, str]] = None
    """The comparison operator."""

    validation_result_value: Optional[str] = None
    """A validation result value. For wildcards use '%' to represents zero or
    more characters, and '_' to represents a single character."""

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        request_dict = {
            "concreteType": ROW_VALIDATION_RESULT_FILTER,
            "operator": self.operator.value if self.operator is not None else None,
            "validationResultValue": self.validation_result_value,
        }
        delete_none_keys(request_dict)
        return request_dict

Attributes¶

operator `class-attribute` `instance-attribute` ¶

operator: Optional[Union[ValidationOperator, str]] = None

The comparison operator.

validation_result_value `class-attribute` `instance-attribute` ¶

validation_result_value: Optional[str] = None

A validation result value. For wildcards use '%' to represents zero or more characters, and '_' to represents a single character.

synapseclient.models.curation.CellValueFilter `dataclass` ¶

Bases: Filter, EnumCoercionMixin

A filter used to select rows based on cell values. For example, to handle a user request like 'find all rows where the Project column is Alpha', you would set 'columnName' to 'Project', 'operator' to 'EQUALS', and 'value' to ['Alpha'].

https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/CellValueFilter.html

ATTRIBUTE	DESCRIPTION
`column_name`	The name of the column to filter by. TYPE: `Optional[str]`
`operator`	The comparison operator. TYPE: `Optional[Union[CellValueOperator, str]]`
`value`	Use operators like 'EQUALS' or 'LIKE' with the 'value' property for standard comparisons. The 'IS_NULL' operator can be used to find null values. The 'IS_UNDEFINED' operator can be used to find undefined values. When using IN or NOT_IN operators, value should be an array of values to compare against. When using either 'LIKE' or 'NOT_LIKE', the wildcard character '%' is used to represents zero or more characters, and '_' is used to represent a single character. TYPE: `Optional[Any]`

Source code in synapseclient/models/curation.py

@dataclass
class CellValueFilter(Filter, EnumCoercionMixin):
    """
    A filter used to select rows based on cell values. For example, to handle a
    user request like 'find all rows where the Project column is Alpha', you
    would set 'columnName' to 'Project', 'operator' to 'EQUALS', and 'value' to
    ['Alpha'].

    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/CellValueFilter.html>

    Attributes:
        column_name: The name of the column to filter by.
        operator: The comparison operator.
        value: Use operators like 'EQUALS' or 'LIKE' with the 'value' property
            for standard comparisons. The 'IS_NULL' operator can be used to
            find null values. The 'IS_UNDEFINED' operator can be used to find
            undefined values. When using IN or NOT_IN operators, value should
            be an array of values to compare against. When using either 'LIKE'
            or 'NOT_LIKE', the wildcard character '%' is used to represents
            zero or more characters, and '_' is used to represent a single
            character.
    """

    _ENUM_FIELDS: ClassVar[dict[str, type]] = {"operator": CellValueOperator}

    column_name: Optional[str] = None
    """The name of the column to filter by."""

    operator: Optional[Union[CellValueOperator, str]] = None
    """The comparison operator."""

    value: Optional[Any] = None
    """Use operators like 'EQUALS' or 'LIKE' with the 'value' property for
    standard comparisons. The 'IS_NULL' operator can be used to find null
    values. The 'IS_UNDEFINED' operator can be used to find undefined values.
    When using IN or NOT_IN operators, value should be an array of values to
    compare against. When using either 'LIKE' or 'NOT_LIKE', the wildcard
    character '%' is used to represents zero or more characters, and '_' is
    used to represent a single character."""

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        request_dict = {
            "concreteType": CELL_VALUE_FILTER,
            "columnName": self.column_name,
            "operator": self.operator.value if self.operator is not None else None,
            "value": self.value,
        }
        delete_none_keys(request_dict)
        return request_dict

Attributes¶

column_name `class-attribute` `instance-attribute` ¶

column_name: Optional[str] = None

The name of the column to filter by.

operator `class-attribute` `instance-attribute` ¶

operator: Optional[Union[CellValueOperator, str]] = None

The comparison operator.

value `class-attribute` `instance-attribute` ¶

value: Optional[Any] = None

Use operators like 'EQUALS' or 'LIKE' with the 'value' property for standard comparisons. The 'IS_NULL' operator can be used to find null values. The 'IS_UNDEFINED' operator can be used to find undefined values. When using IN or NOT_IN operators, value should be an array of values to compare against. When using either 'LIKE' or 'NOT_LIKE', the wildcard character '%' is used to represents zero or more characters, and '_' is used to represent a single character.

synapseclient.models.curation.RowSelectionFilter `dataclass` ¶

Bases: Filter

Use this filter to narrow down results based on rows the user has actively selected in the interface. For user requests like 'show me only my selected items' or 'run this analysis on the rows I've checked', set the 'isSelected' property to true.

https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/RowSelectionFilter.html

ATTRIBUTE	DESCRIPTION
`is_selected`	When true, only rows that the user has selected will be returned. When false, rows that the user has selected will be excluded. TYPE: `Optional[bool]`

Source code in synapseclient/models/curation.py

@dataclass
class RowSelectionFilter(Filter):
    """
    Use this filter to narrow down results based on rows the user has actively
    selected in the interface. For user requests like 'show me only my selected
    items' or 'run this analysis on the rows I've checked', set the
    'isSelected' property to true.

    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/RowSelectionFilter.html>

    Attributes:
        is_selected: When true, only rows that the user has selected will be
            returned. When false, rows that the user has selected will be
            excluded.
    """

    is_selected: Optional[bool] = None
    """When true, only rows that the user has selected will be returned. When
    false, rows that the user has selected will be excluded."""

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        request_dict = {
            "concreteType": ROW_SELECTION_FILTER,
            "isSelected": self.is_selected,
        }
        delete_none_keys(request_dict)
        return request_dict

Attributes¶

is_selected `class-attribute` `instance-attribute` ¶

is_selected: Optional[bool] = None

When true, only rows that the user has selected will be returned. When false, rows that the user has selected will be excluded.

synapseclient.models.curation.RowIsValidFilter `dataclass` ¶

Bases: Filter

Use this filter for simple requests to find all 'valid' or 'invalid' rows based on their overall validation status.

https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/RowIsValidFilter.html

ATTRIBUTE	DESCRIPTION
`value`	Set to true to find rows that are valid according to the schema. Set to false to find rows that are invalid and have validation errors. TYPE: `Optional[bool]`

Source code in synapseclient/models/curation.py

@dataclass
class RowIsValidFilter(Filter):
    """
    Use this filter for simple requests to find all 'valid' or 'invalid' rows
    based on their overall validation status.

    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/RowIsValidFilter.html>

    Attributes:
        value: Set to true to find rows that are valid according to the
            schema. Set to false to find rows that are invalid and have
            validation errors.
    """

    value: Optional[bool] = None
    """Set to true to find rows that are valid according to the schema. Set to
    false to find rows that are invalid and have validation errors."""

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        request_dict = {"concreteType": ROW_IS_VALID_FILTER, "value": self.value}
        delete_none_keys(request_dict)
        return request_dict

Attributes¶

value `class-attribute` `instance-attribute` ¶

value: Optional[bool] = None

Set to true to find rows that are valid according to the schema. Set to false to find rows that are invalid and have validation errors.

synapseclient.models.curation.RowIdFilter `dataclass` ¶

Bases: Filter

Row ID inclusion filter. Use when you need to operate on specific existing rows by their explicit row IDs obtained from a prior grid query (e.g., an update). The filter matches any row whose ID is in the provided list (logical OR semantics). Do not use for pattern matching or broad selection; supply only the exact row IDs you intend to modify or retrieve.

https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/RowIdFilter.html

ATTRIBUTE	DESCRIPTION
`row_ids_in`	Array of explicit row IDs. The result will include any row whose ID appears in this list (logical OR). Provide only IDs previously obtained from a grid query. Omit this filter if you do not know the IDs. Do not include duplicates or IDs not present in the current grid. TYPE: `Optional[list[str]]`

Source code in synapseclient/models/curation.py

@dataclass
class RowIdFilter(Filter):
    """
    Row ID inclusion filter. Use when you need to operate on specific existing
    rows by their explicit row IDs obtained from a prior grid query (e.g., an
    update). The filter matches any row whose ID is in the provided list
    (logical OR semantics). Do not use for pattern matching or broad selection;
    supply only the exact row IDs you intend to modify or retrieve.

    <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/RowIdFilter.html>

    Attributes:
        row_ids_in: Array of explicit row IDs. The result will include any row
            whose ID appears in this list (logical OR). Provide only IDs
            previously obtained from a grid query. Omit this filter if you do
            not know the IDs. Do not include duplicates or IDs not present in
            the current grid.
    """

    row_ids_in: Optional[list[str]] = None
    """Array of explicit row IDs. The result will include any row whose ID
    appears in this list (logical OR). Provide only IDs previously obtained
    from a grid query. Omit this filter if you do not know the IDs. Do not
    include duplicates or IDs not present in the current grid."""

    def to_synapse_request(self) -> Dict[str, Any]:
        """
        Converts this dataclass to a dictionary suitable for a Synapse REST API request.

        Returns:
            A dictionary representation of this object for API requests.
        """
        request_dict = {"concreteType": ROW_ID_FILTER, "rowIdsIn": self.row_ids_in}
        delete_none_keys(request_dict)
        return request_dict

Attributes¶

row_ids_in `class-attribute` `instance-attribute` ¶

row_ids_in: Optional[list[str]] = None

Array of explicit row IDs. The result will include any row whose ID appears in this list (logical OR). Provide only IDs previously obtained from a grid query. Omit this filter if you do not know the IDs. Do not include duplicates or IDs not present in the current grid.

synapseclient.models.curation.ValidationOperator ¶

Bases: str, Enum

The comparison operator.

See https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/ValidationOperator.html.

Source code in synapseclient/models/curation.py

class ValidationOperator(str, Enum):
    """
    The comparison operator.

    See <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/ValidationOperator.html>.
    """

    LIKE = "LIKE"
    NOT_LIKE = "NOT_LIKE"

synapseclient.models.curation.CellValueOperator ¶

Bases: str, Enum

The comparison operator.

See https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/CellValueOperator.html.

Source code in synapseclient/models/curation.py

class CellValueOperator(str, Enum):
    """
    The comparison operator.

    See <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/CellValueOperator.html>.
    """

    EQUALS = "EQUALS"
    NOT_EQUALS = "NOT_EQUALS"
    GREATER_THAN = "GREATER_THAN"
    LESS_THAN = "LESS_THAN"
    GREATER_THAN_OR_EQUALS = "GREATER_THAN_OR_EQUALS"
    LESS_THAN_OR_EQUALS = "LESS_THAN_OR_EQUALS"
    IN = "IN"
    NOT_IN = "NOT_IN"
    LIKE = "LIKE"
    NOT_LIKE = "NOT_LIKE"
    IS_NULL = "IS_NULL"
    IS_NOT_NULL = "IS_NOT_NULL"
    IS_UNDEFINED = "IS_UNDEFINED"
    IS_DEFINED = "IS_DEFINED"

synapseclient.models.curation.GridQueryResult `dataclass` ¶

A single page of rows returned from a grid query.

Represents a Synapse QueryResult.

Note: This is distinct from the SQL-based table QueryResult (org.sagebionetworks.repo.model.table.QueryResult), which wraps SQL query results rather than a grid query's SelectColumn/Row objects.

ATTRIBUTE	DESCRIPTION
`select_columns`	Information about the selected columns. TYPE: `Optional[list[SelectColumn]]`
`rows`	A single page of rows. TYPE: `Optional[list[GridRow]]`

Source code in synapseclient/models/curation.py

@dataclass
class GridQueryResult:
    """
    A single page of rows returned from a grid query.

    Represents a [Synapse QueryResult](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/result/QueryResult.html).

    Note: This is distinct from the SQL-based table
    [QueryResult](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/QueryResult.html)
    (`org.sagebionetworks.repo.model.table.QueryResult`), which wraps SQL query
    results rather than a grid query's SelectColumn/Row objects.

    Attributes:
        select_columns: Information about the selected columns.
        rows: A single page of rows.
    """

    select_columns: Optional[list[SelectColumn]] = None
    """Information about the selected columns."""

    rows: Optional[list[GridRow]] = None
    """A single page of rows."""

    def fill_from_dict(self, synapse_response: Dict[str, Any]) -> "GridQueryResult":
        """
        Converts a response from the REST API into this dataclass.

        Arguments:
            synapse_response: The response from the REST API.

        Returns:
            The GridQueryResult object.
        """
        select_columns_data = synapse_response.get("selectColumns", None)
        self.select_columns = (
            [SelectColumn().fill_from_dict(col) for col in select_columns_data]
            if select_columns_data is not None
            else None
        )

        rows_data = synapse_response.get("rows", None)
        self.rows = (
            [GridRow().fill_from_dict(row) for row in rows_data]
            if rows_data is not None
            else None
        )
        return self

Attributes¶

select_columns `class-attribute` `instance-attribute` ¶

select_columns: Optional[list[SelectColumn]] = None

Information about the selected columns.

rows `class-attribute` `instance-attribute` ¶

rows: Optional[list[GridRow]] = None

A single page of rows.

synapseclient.models.curation.GridRow `dataclass` ¶

A single row of a grid query result.

Represents a Synapse Row.

Note: This is distinct from the SQL-based table Row (org.sagebionetworks.repo.model.table.Row), which represents a row of a table/view query result rather than a grid query result.

ATTRIBUTE	DESCRIPTION
`row_id`	Logical timestamp identifying the row in compact form `replicaId.sequenceNumber` (e.g. `123.456`). Used in filtering operations and update/patch procedures. TYPE: `Optional[str]`
`data`	The JSON object representing a single row. TYPE: `Optional[Dict[str, Any]]`
`validation_results`	Results of validating this row against a JSON schema, if a schema is bound. TYPE: `Optional[GridQueryValidationResult]`

Source code in synapseclient/models/curation.py

@dataclass
class GridRow:
    """
    A single row of a grid query result.

    Represents a [Synapse Row](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/result/Row.html).

    Note: This is distinct from the SQL-based table
    [Row](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/Row.html)
    (`org.sagebionetworks.repo.model.table.Row`), which represents a row of a
    table/view query result rather than a grid query result.

    Attributes:
        row_id: Logical timestamp identifying the row in compact form
            `replicaId.sequenceNumber` (e.g. `123.456`). Used in filtering
            operations and update/patch procedures.
        data: The JSON object representing a single row.
        validation_results: Results of validating this row against a JSON
            schema, if a schema is bound.
    """

    row_id: Optional[str] = None
    """Logical timestamp identifying the row in compact form `replicaId.sequenceNumber`."""

    data: Optional[Dict[str, Any]] = None
    """The JSON object representing a single row."""

    validation_results: Optional[GridQueryValidationResult] = None
    """Results of validating this row against a JSON schema, if a schema is bound."""

    def fill_from_dict(self, synapse_response: Dict[str, Any]) -> "GridRow":
        """
        Converts a response from the REST API into this dataclass.

        Arguments:
            synapse_response: The response from the REST API.

        Returns:
            The GridRow object.
        """
        self.row_id = synapse_response.get("rowId", None)
        self.data = synapse_response.get("data", None)
        validation_results_data = synapse_response.get("validationResults", None)
        self.validation_results = (
            GridQueryValidationResult().fill_from_dict(validation_results_data)
            if validation_results_data is not None
            else None
        )
        return self

Attributes¶

row_id `class-attribute` `instance-attribute` ¶

row_id: Optional[str] = None

Logical timestamp identifying the row in compact form replicaId.sequenceNumber.

data `class-attribute` `instance-attribute` ¶

data: Optional[Dict[str, Any]] = None

The JSON object representing a single row.

validation_results `class-attribute` `instance-attribute` ¶

validation_results: Optional[GridQueryValidationResult] = None

Results of validating this row against a JSON schema, if a schema is bound.

synapseclient.models.curation.SelectColumn `dataclass` ¶

Information about a selected column in a grid query result.

Represents a Synapse SelectColumn.

Note: This is distinct from the table SelectColumn (org.sagebionetworks.repo.model.table.SelectColumn), which additionally carries id and columnType. This grid-query SelectColumn only has column_name.

ATTRIBUTE	DESCRIPTION
`column_name`	The name of the column. Will be the alias if one is provided in the select item. TYPE: `Optional[str]`

Source code in synapseclient/models/curation.py

@dataclass
class SelectColumn:
    """
    Information about a selected column in a grid query result.

    Represents a [Synapse SelectColumn](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/result/SelectColumn.html).

    Note: This is distinct from the table
    [SelectColumn](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/SelectColumn.html)
    (`org.sagebionetworks.repo.model.table.SelectColumn`), which additionally carries
    `id` and `columnType`. This grid-query `SelectColumn` only has `column_name`.

    Attributes:
        column_name: The name of the column. Will be the alias if one is
            provided in the select item.
    """

    column_name: Optional[str] = None
    """The name of the column. Will be the alias if one is provided in the select item."""

    def fill_from_dict(self, synapse_response: Dict[str, Any]) -> "SelectColumn":
        """
        Converts a response from the REST API into this dataclass.

        Arguments:
            synapse_response: The response from the REST API.

        Returns:
            The SelectColumn object.
        """
        self.column_name = synapse_response.get("columnName", None)
        return self

Attributes¶

column_name `class-attribute` `instance-attribute` ¶

column_name: Optional[str] = None

The name of the column. Will be the alias if one is provided in the select item.

synapseclient.models.curation.GridQueryValidationResult `dataclass` ¶

Results of a grid row against a JSON schema

Represents a Synapse ValidationResults.

Note: This is distinct from the general-purpose ValidationResults (org.sagebionetworks.repo.model.schema.ValidationResults), which is used for validating entities/containers against a schema and carries additional fields (objectId, objectType, objectEtag, schema$id, validatedOn, validationException) that this grid-row-specific type does not have.

ATTRIBUTE	DESCRIPTION
`is_valid`	Will be 'true' if the row is valid according to the JSON schema. Will be 'false' when the row is invalid. TYPE: `Optional[bool]`
`validation_error_message`	If the object is not valid according to the schema, a simple one line error message will be provided. TYPE: `Optional[str]`
`all_validation_messages`	If the object is not valid according to the schema, a the flat list of error messages will be provided with one error message per sub-schema. Included only if includeValidationMessages was set to true in the query. Otherwise, this array is omitted to optimize performance. TYPE: `Optional[list[str]]`

Source code in synapseclient/models/curation.py

@dataclass
class GridQueryValidationResult:
    """
    Results of a grid row against a JSON schema

    Represents a [Synapse ValidationResults](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/grid/query/result/ValidationResults.html).

    Note: This is distinct from the general-purpose
    [ValidationResults](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/schema/ValidationResults.html)
    (`org.sagebionetworks.repo.model.schema.ValidationResults`), which is used
    for validating entities/containers against a schema and carries additional
    fields (`objectId`, `objectType`, `objectEtag`, `schema$id`, `validatedOn`,
    `validationException`) that this grid-row-specific type does not have.

    Attributes:
        is_valid: Will be 'true' if the row is valid according to the JSON
            schema. Will be 'false' when the row is invalid.
        validation_error_message: If the object is not valid according to the
            schema, a simple one line error message will be provided.
        all_validation_messages: If the object is not valid according to the
            schema, a the flat list of error messages will be provided with one
            error message per sub-schema. Included only if
            includeValidationMessages was set to true in the query. Otherwise,
            this array is omitted to optimize performance.
    """

    is_valid: Optional[bool] = None
    """Will be 'true' if the row is valid according to the JSON schema. Will be
    'false' when the row is invalid."""

    validation_error_message: Optional[str] = None
    """If the object is not valid according to the schema, a simple one line
    error message will be provided."""

    all_validation_messages: Optional[list[str]] = None
    """If the object is not valid according to the schema, a the flat list of
    error messages will be provided with one error message per sub-schema.
    Included only if includeValidationMessages was set to true in the query.
    Otherwise, this array is omitted to optimize performance."""

    def fill_from_dict(
        self, synapse_response: Dict[str, Any]
    ) -> "GridQueryValidationResult":
        """
        Converts a response from the REST API into this dataclass.

        Arguments:
            synapse_response: The response from the REST API.

        Returns:
            The GridQueryValidationResult object.
        """
        self.is_valid = synapse_response.get("isValid", None)
        self.validation_error_message = synapse_response.get(
            "validationErrorMessage", None
        )
        self.all_validation_messages = synapse_response.get(
            "allValidationMessages", None
        )
        return self

Attributes¶

is_valid `class-attribute` `instance-attribute` ¶

is_valid: Optional[bool] = None

Will be 'true' if the row is valid according to the JSON schema. Will be 'false' when the row is invalid.

validation_error_message `class-attribute` `instance-attribute` ¶

validation_error_message: Optional[str] = None

If the object is not valid according to the schema, a simple one line error message will be provided.

all_validation_messages `class-attribute` `instance-attribute` ¶

all_validation_messages: Optional[list[str]] = None

If the object is not valid according to the schema, a the flat list of error messages will be provided with one error message per sub-schema. Included only if includeValidationMessages was set to true in the query. Otherwise, this array is omitted to optimize performance.

Curator¶

API reference¶

synapseclient.models.CurationTask dataclass ¶

Methods:¶

get ¶

get_status ¶

update_status ¶

set_active_grid_session ¶

delete ¶

store ¶

list classmethod ¶

create_grid_session ¶

set_task_state ¶

synchronize_active_grid_session ¶

synapseclient.models.RecordSet dataclass ¶

Methods:¶

get ¶

store ¶

delete ¶

get_detailed_validation_results ¶

get_acl ¶

get_permissions ¶

set_permissions ¶

delete_permissions ¶

list_acl ¶

bind_schema ¶

get_schema ¶

unbind_schema ¶

validate_schema ¶

get_schema_derived_keys ¶

synapseclient.models.RecordBasedMetadataTaskProperties dataclass ¶

Attributes¶

record_set_id class-attribute instance-attribute ¶

suggested_authorization_mode class-attribute instance-attribute ¶

collaborator_principal_ids class-attribute instance-attribute ¶

synapseclient.models.FileBasedMetadataTaskProperties dataclass ¶

Attributes¶

upload_folder_id class-attribute instance-attribute ¶

file_view_id class-attribute instance-attribute ¶

suggested_authorization_mode class-attribute instance-attribute ¶

collaborator_principal_ids class-attribute instance-attribute ¶

synapseclient.models.AuthorizationMode ¶

Attributes¶

SESSION_OWNER class-attribute instance-attribute ¶

SOURCE_BENEFACTOR class-attribute instance-attribute ¶

synapseclient.models.SyncType ¶

Attributes¶

PULL class-attribute instance-attribute ¶

PULL_PUSH class-attribute instance-attribute ¶

synapseclient.models.Grid dataclass ¶

Methods:¶

create ¶

get ¶

export_to_record_set ¶

synchronize ¶

download_csv ¶

import_csv ¶

delete ¶

list classmethod ¶

connect ¶

validate_rows ¶

synapseclient.models.Query dataclass ¶

Attributes¶

sql instance-attribute ¶

additional_filters class-attribute instance-attribute ¶

selected_facets class-attribute instance-attribute ¶

include_entity_etag class-attribute instance-attribute ¶

select_file_column class-attribute instance-attribute ¶

select_file_version_column class-attribute instance-attribute ¶

offset class-attribute instance-attribute ¶

limit class-attribute instance-attribute ¶

sort class-attribute instance-attribute ¶

synapseclient.models.curation.GridQuery dataclass ¶

Attributes¶

column_selection class-attribute instance-attribute ¶

limit class-attribute instance-attribute ¶

filters class-attribute instance-attribute ¶

offset class-attribute instance-attribute ¶

include_validation_messages class-attribute instance-attribute ¶

synapseclient.models.curation.QueryRequest dataclass ¶

synapseclient.models.CurationTask `dataclass` ¶

list `classmethod` ¶

synapseclient.models.RecordSet `dataclass` ¶

synapseclient.models.RecordBasedMetadataTaskProperties `dataclass` ¶

record_set_id `class-attribute` `instance-attribute` ¶

suggested_authorization_mode `class-attribute` `instance-attribute` ¶

collaborator_principal_ids `class-attribute` `instance-attribute` ¶

synapseclient.models.FileBasedMetadataTaskProperties `dataclass` ¶

upload_folder_id `class-attribute` `instance-attribute` ¶

file_view_id `class-attribute` `instance-attribute` ¶

suggested_authorization_mode `class-attribute` `instance-attribute` ¶

collaborator_principal_ids `class-attribute` `instance-attribute` ¶

SESSION_OWNER `class-attribute` `instance-attribute` ¶

SOURCE_BENEFACTOR `class-attribute` `instance-attribute` ¶

PULL `class-attribute` `instance-attribute` ¶

PULL_PUSH `class-attribute` `instance-attribute` ¶

synapseclient.models.Grid `dataclass` ¶

list `classmethod` ¶

synapseclient.models.Query `dataclass` ¶

sql `instance-attribute` ¶

additional_filters `class-attribute` `instance-attribute` ¶

selected_facets `class-attribute` `instance-attribute` ¶

include_entity_etag `class-attribute` `instance-attribute` ¶

select_file_column `class-attribute` `instance-attribute` ¶

select_file_version_column `class-attribute` `instance-attribute` ¶

offset `class-attribute` `instance-attribute` ¶

limit `class-attribute` `instance-attribute` ¶

sort `class-attribute` `instance-attribute` ¶

synapseclient.models.curation.GridQuery `dataclass` ¶

column_selection `class-attribute` `instance-attribute` ¶

limit `class-attribute` `instance-attribute` ¶

filters `class-attribute` `instance-attribute` ¶

offset `class-attribute` `instance-attribute` ¶

include_validation_messages `class-attribute` `instance-attribute` ¶

synapseclient.models.curation.QueryRequest `dataclass` ¶

query `class-attribute` `instance-attribute` ¶

synapseclient.models.curation.SelectItem `dataclass` ¶

synapseclient.models.curation.SelectByName `dataclass` ¶

column_name `class-attribute` `instance-attribute` ¶

synapseclient.models.curation.SelectAll `dataclass` ¶

synapseclient.models.curation.CountStar `dataclass` ¶

alias `class-attribute` `instance-attribute` ¶

synapseclient.models.curation.SelectSelection `dataclass` ¶

synapseclient.models.curation.Filter `dataclass` ¶

synapseclient.models.curation.RowValidationResultFilter `dataclass` ¶

operator `class-attribute` `instance-attribute` ¶

validation_result_value `class-attribute` `instance-attribute` ¶

synapseclient.models.curation.CellValueFilter `dataclass` ¶

column_name `class-attribute` `instance-attribute` ¶

operator `class-attribute` `instance-attribute` ¶

value `class-attribute` `instance-attribute` ¶

synapseclient.models.curation.RowSelectionFilter `dataclass` ¶

is_selected `class-attribute` `instance-attribute` ¶

synapseclient.models.curation.RowIsValidFilter `dataclass` ¶

value `class-attribute` `instance-attribute` ¶

synapseclient.models.curation.RowIdFilter `dataclass` ¶

row_ids_in `class-attribute` `instance-attribute` ¶

synapseclient.models.curation.GridQueryResult `dataclass` ¶

select_columns `class-attribute` `instance-attribute` ¶

rows `class-attribute` `instance-attribute` ¶

synapseclient.models.curation.GridRow `dataclass` ¶

row_id `class-attribute` `instance-attribute` ¶

data `class-attribute` `instance-attribute` ¶

validation_results `class-attribute` `instance-attribute` ¶

synapseclient.models.curation.SelectColumn `dataclass` ¶

column_name `class-attribute` `instance-attribute` ¶

synapseclient.models.curation.GridQueryValidationResult `dataclass` ¶

is_valid `class-attribute` `instance-attribute` ¶

validation_error_message `class-attribute` `instance-attribute` ¶

all_validation_messages `class-attribute` `instance-attribute` ¶