Client

v5.0.0 is object-oriented

Many Synapse client methods documented below are deprecated in favor of the object-oriented models (see the Object-Oriented Models section of the API reference) and the synapseclient.operations functions. The Synapse object is still required for authentication via syn.login. New code should prefer the object-oriented models — start with the Python client tutorial.

synapseclient.Synapse

Bases: object

Constructs a Python client object for the Synapse repository service

ATTRIBUTE	DESCRIPTION
repoEndpoint	Location of Synapse repository
authEndpoint	Location of authentication service
fileHandleEndpoint	Location of file service
portalEndpoint	Location of the website
debug	Print debugging messages if True
skip_checks	Skip version and endpoint checks
configPath	Path to config File with setting for Synapse. Defaults to ~/.synapseConfig
requests_session	A custom requests.Session object that this Synapse instance will use when making http requests.
cache_root_dir	Root directory for storing cache data
silent	Defaults to False.
requests_session_async_synapse	A custom httpx.AsyncClient that this synapse instance will use when making HTTP requests. requests_session is being deprecated in favor of this.
requests_session_storage	A custom httpx.Client that this synapse instance will use when making HTTP requests to storage providers like AWS S3 and Google Cloud Storage.
asyncio_event_loop	The event loop that is going to be used while executing this code. This is optional and only used when you are manually specifying an async HTTPX client. This is important to pass when you are using the requests_session_async_synapse kwarg because the connection pooling is tied to the event loop.
cache_client	Whether to cache the Synapse client object in the Synapse module. Defaults to True. When set to True anywhere a Synapse object is optional you do not need to pass an instance of Synapse to that function, method, or class. When working in a multi-user environment it is recommended to set this to False, or use Synapse.allow_client_caching(False).
user_agent	Additional values to add to the User-Agent header on HTTP requests. This should be in the format of "my-project-identifier/1.0.0". This may be a single string or a list of strings to add onto the header. If the format is incorrect a ValueError exception will be raised. These will be appended to the default User-Agent header that already includes the version of this client that you are using, and the HTTP library used to make the request.
timeout	The timeout in seconds for HTTP requests. The default is 70 seconds. You may increase this if you are experiencing timeouts when interacting with slow services.

Getting started

Logging in to Synapse using an authToken

import synapseclient
syn = synapseclient.login(authToken="authtoken")

Using environment variable or .synapseConfig

import synapseclient
syn = synapseclient.login()

Adding an additional user_agent value

This example shows how to add an additional user_agent to the HTTP headers on the request. This is useful for tracking the requests that are being made from your application.

from synapseclient import Synapse

my_agent = "my-project-identifier/1.0.0"
# You may also provide a list of strings to add to the User-Agent header.
# my_agent = ["my-sub-library/1.0.0", "my-parent-project/2.0.0"]

syn = Synapse(user_agent=my_agent)

Source code in synapseclient/client.py

class Synapse(object):
    """
    Constructs a Python client object for the Synapse repository service

    Attributes:
        repoEndpoint:          Location of Synapse repository
        authEndpoint:          Location of authentication service
        fileHandleEndpoint:    Location of file service
        portalEndpoint:        Location of the website
        debug:                 Print debugging messages if True
        skip_checks:           Skip version and endpoint checks
        configPath:            Path to config File with setting for Synapse. Defaults to ~/.synapseConfig
        requests_session:      A custom [requests.Session object](https://requests.readthedocs.io/en/latest/user/advanced/) that this Synapse instance will use
                               when making http requests.
        cache_root_dir:        Root directory for storing cache data
        silent:                Defaults to False.
        requests_session_async_synapse: A custom
            [httpx.AsyncClient](https://www.python-httpx.org/async/) that this synapse
            instance will use when making HTTP requests. `requests_session` is being
            deprecated in favor of this.
        requests_session_storage: A custom
            [httpx.Client](https://www.python-httpx.org/advanced/clients/) that this synapse
            instance will use when making HTTP requests to storage providers like AWS S3
            and Google Cloud Storage.
        asyncio_event_loop: The event loop that is going to be used while executing
            this code. This is optional and only used when you are manually specifying
            an async HTTPX client. This is important to pass when you are using the
            `requests_session_async_synapse` kwarg because the connection pooling is
            tied to the event loop.
        cache_client: Whether to cache the Synapse client object in the Synapse module.
            Defaults to True. When set to True anywhere a `Synapse` object is optional
            you do not need to pass an instance of `Synapse` to that function, method,
            or class. When working in a multi-user environment it is recommended to set
            this to False, or use `Synapse.allow_client_caching(False)`.
        user_agent: Additional values to add to the `User-Agent` header on HTTP
            requests. This should be in the format of `"my-project-identifier/1.0.0"`.
            This may be a single string or a list of strings to add onto the
            header. If the format is incorrect a `ValueError` exception will be
            raised. These will be appended to the default `User-Agent` header that
            already includes the version of this client that you are using, and the
            HTTP library used to make the request.
        timeout: The timeout in seconds for HTTP requests. The default is 70 seconds.
            You may increase this if you are experiencing timeouts when interacting
            with slow services.

    Example: Getting started
        Logging in to Synapse using an authToken

        ```python
        import synapseclient
        syn = synapseclient.login(authToken="authtoken")
        ```

        Using environment variable or `.synapseConfig`

        ```python
        import synapseclient
        syn = synapseclient.login()
        ```

    Example: Adding an additional `user_agent` value
        This example shows how to add an additional `user_agent` to the HTTP headers
        on the request. This is useful for tracking the requests that are being made
        from your application.

        ```python
        from synapseclient import Synapse

        my_agent = "my-project-identifier/1.0.0"
        # You may also provide a list of strings to add to the User-Agent header.
        # my_agent = ["my-sub-library/1.0.0", "my-parent-project/2.0.0"]

        syn = Synapse(user_agent=my_agent)
        ```

    """

    _synapse_client = None
    _allow_client_caching = True

    # TODO: add additional boolean for write to disk?
    def __init__(
        self,
        repoEndpoint: str = None,
        authEndpoint: str = None,
        fileHandleEndpoint: str = None,
        portalEndpoint: str = None,
        debug: bool = None,
        skip_checks: bool = False,
        configPath: str = CONFIG_FILE,
        requests_session: requests.Session = None,
        cache_root_dir: str = None,
        silent: bool = None,
        requests_session_async_synapse: httpx.AsyncClient = None,
        requests_session_storage: httpx.Client = None,
        asyncio_event_loop: asyncio.AbstractEventLoop = None,
        cache_client: bool = True,
        user_agent: Union[str, List[str]] = None,
        http_timeout_seconds: int = 70,
    ) -> "Synapse":
        """
        Initialize Synapse object

        Arguments:
            repoEndpoint:       Location of Synapse repository.
            authEndpoint:       Location of authentication service.
            fileHandleEndpoint: Location of file service.
            portalEndpoint:     Location of the website.
            debug:              Print debugging messages if True.
            skip_checks:        Skip version and endpoint checks.
            configPath:         Path to config File with setting for Synapse.
            requests_session:   A custom [requests.Session object](https://requests.readthedocs.io/en/latest/user/advanced/) that this Synapse instance will use
                                when making http requests.
            cache_root_dir:     Root directory for storing cache data.
            silent:             Suppresses message.
            requests_session_async_synapse: The HTTPX Async client for interacting with
                Synapse services.
            requests_session_storage: The HTTPX client for interacting with
                storage providers like AWS S3 and Google Cloud.
            asyncio_event_loop: The event loop that is going to be used while executing
                this code. This is optional and only used when you are manually
                specifying an async HTTPX client.
            cache_client: Whether to cache the Synapse client object in the Synapse module. Defaults to True.
                             When set to True anywhere a `Synapse` object is optional you do not need to pass an
                             instance of `Synapse` to that function, method, or class.
                             When working in a multi-user environment it is
                             recommended to set this to False, or use
                             `Synapse.allow_client_caching(False)`.
            user_agent: Additional values to add to the `User-Agent` header on HTTP
                requests. This should be in the format of
                `"my-project-identifier/1.0.0"`. Only
                [Semantic Versioning](https://semver.org/) is expected.
                This may be a single string or a list of strings to add onto the
                header. If the format is incorrect a `ValueError` exception will be
                raised. These will be appended to the default `User-Agent` header that
                already includes the version of this client that you are using, and the
                HTTP library used to make the request.
            http_timeout_seconds: The timeout in seconds for HTTP requests.
                The default is 70 seconds. You may increase this if you are
                experiencing timeouts when interacting with slow services.

        Raises:
            ValueError: Warn for non-boolean debug value.
        """
        self._requests_session = requests_session or requests.Session()

        # `requests_session_async_synapse` and the thread pools are being stored in
        # a dict based on the current running event loop. This is to ensure that the
        # connection pooling is maintained within the same event loop. This is to
        # prevent the connection pooling from being shared across different event loops.
        if requests_session_async_synapse and asyncio_event_loop:
            self._requests_session_async_synapse = {
                asyncio_event_loop: requests_session_async_synapse
            }
        else:
            self._requests_session_async_synapse = {}

        self._http_timeout_seconds = http_timeout_seconds
        httpx_timeout = httpx.Timeout(http_timeout_seconds, pool=None)
        self._requests_session_storage = requests_session_storage or httpx.Client(
            timeout=httpx_timeout
        )

        cache_root_dir = (
            cache.CACHE_ROOT_DIR if cache_root_dir is None else cache_root_dir
        )

        config_debug = None
        # Check for a config file
        self.configPath = configPath
        if os.path.isfile(configPath):
            config = get_config_file(configPath)
            if config.has_option("cache", "location"):
                cache_root_dir = config.get("cache", "location")
            if config.has_section("debug"):
                config_debug = True

        if debug is None:
            debug = config_debug if config_debug is not None else DEBUG_DEFAULT

        if not isinstance(debug, bool):
            raise ValueError("debug must be set to a bool (either True or False)")
        self.debug = debug

        self.cache = cache.Cache(cache_root_dir)
        self._sts_token_store = sts_transfer.StsTokenStore()

        self.setEndpoints(
            repoEndpoint, authEndpoint, fileHandleEndpoint, portalEndpoint, skip_checks
        )

        self.default_headers = {
            "content-type": "application/json; charset=UTF-8",
            "Accept": "application/json; charset=UTF-8",
        }
        self.credentials = None

        self._validate_user_agent_format(user_agent)
        if isinstance(user_agent, str):
            self.user_agent = [user_agent]
        else:
            self.user_agent = user_agent

        self.silent = silent
        self._init_logger()  # initializes self.logger

        self.skip_checks = skip_checks

        self.table_query_sleep = 0.2  # Sleep for 200ms between table query retries
        self.table_query_backoff = 1.1
        self.table_query_max_sleep = 20
        self.table_query_timeout = 600  # in seconds
        self.multi_threaded = True  # if set to True, multi threaded download will be used for http and https URLs

        transfer_config = get_transfer_config(config_path=self.configPath)
        self.max_threads = transfer_config["max_threads"]
        self._thread_executor = {}
        self._process_executor = {}
        self._parallel_file_transfer_semaphore = {}
        self.use_boto_sts_transfers = transfer_config["use_boto_sts"]
        self._parts_transfered_counter = 0
        if cache_client and Synapse._allow_client_caching:
            Synapse.set_client(synapse_client=self)

    def _validate_user_agent_format(self, agent: Union[str, List[str]]) -> None:
        if not agent:
            return

        if not isinstance(agent, str) and not isinstance(agent, list):
            raise ValueError(
                f"user_agent must be a string or a list of strings to add to the User-Agent header. Current value: {agent}"
            )

        if isinstance(agent, str):
            if not re.match(USER_AGENT_REGEX_PATTERN, agent):
                raise ValueError(
                    f"user_agent must be in the format of 'my-project-identifier/1.0.0'. Current value: {agent}"
                )
        else:
            for value in agent:
                self._validate_user_agent_format(agent=value)

    def _get_requests_session_async_synapse(
        self, asyncio_event_loop: asyncio.AbstractEventLoop
    ) -> httpx.AsyncClient:
        """
        httpx.AsyncClient can only use connection pooling within the same event loop.
        As a result an `atexit` handler is used to close the connection when the event
        loop is closed. It will also delete the attribute from the object to prevent
        it from being reused in the future.

        Further documentation can be found here:
        <https://github.com/encode/httpx/discussions/2959>


        As a result of this issue: It is recommended to use the same event loop for all
        requests. This means to enter into an event loop before making any requests.

        This is expected to be called from within an AsyncIO loop.
        """
        if (
            hasattr(self, "_requests_session_async_synapse")
            and asyncio_event_loop in self._requests_session_async_synapse
            and self._requests_session_async_synapse[asyncio_event_loop] is not None
        ):
            return self._requests_session_async_synapse[asyncio_event_loop]

        async def close_connection() -> None:
            """Close connection when event loop exits"""
            await self._requests_session_async_synapse[asyncio_event_loop].aclose()
            del self._requests_session_async_synapse[asyncio_event_loop]

        httpx_timeout = httpx.Timeout(self._http_timeout_seconds, pool=None)
        self._requests_session_async_synapse.update(
            {
                asyncio_event_loop: httpx.AsyncClient(
                    limits=httpx.Limits(max_connections=5),
                    timeout=httpx_timeout,
                )
            }
        )

        asyncio_atexit.register(close_connection)
        return self._requests_session_async_synapse[asyncio_event_loop]

    def _get_thread_pool_executor(
        self, asyncio_event_loop: asyncio.AbstractEventLoop
    ) -> ThreadPoolExecutor:
        """
        Retrieve the thread pool executor for the Synapse client. Or create a new one if
        it does not exist. This executor is used for concurrent uploads of data to
        storage providers like AWS S3 and Google Cloud Storage.

        This is expected to be called from within an AsyncIO loop.
        """
        if (
            hasattr(self, "_thread_executor")
            and asyncio_event_loop in self._thread_executor
            and self._thread_executor[asyncio_event_loop] is not None
        ):
            return self._thread_executor[asyncio_event_loop]

        def close_pool() -> None:
            """Close pool when event loop exits"""
            self._thread_executor[asyncio_event_loop].shutdown(wait=True)
            del self._thread_executor[asyncio_event_loop]

        self._thread_executor.update(
            {asyncio_event_loop: get_executor(thread_count=self.max_threads)}
        )

        asyncio_atexit.register(close_pool)
        return self._thread_executor[asyncio_event_loop]

    def _get_parallel_file_transfer_semaphore(
        self, asyncio_event_loop: asyncio.AbstractEventLoop
    ) -> asyncio.Semaphore:
        """
        Retrieve the semaphore for the Synapse client. Or create a new one if it does
        not exist. This semaphore is used to limit the number of files that can actively
        enter the uploading/downloading process.

        This is expected to be called from within an AsyncIO loop.

        By default the number of files that can enter the "uploading" state will be
        limited to 2 * max_threads. This is to ensure that the files that are entering
        into the "uploading" state will have priority to finish. Additionally, it means
        that there should be a good spread of files getting up to the "uploading"
        state, entering the "uploading" state, and finishing the "uploading" state.

        If we break these states down into large components they would look like:
        - Before "uploading" state: HTTP rest calls to retrieve what data Synapse has
        - Entering "uploading" state: MD5 calculation and HTTP rest calls to determine
          how/where to upload a file to.
        - During "uploading" state: Uploading the file to a storage provider.
        - After "uploading" state: HTTP rest calls to finalize the upload.

        This has not yet been applied to parallel file downloads. That will take place
        later on.
        """
        if (
            hasattr(self, "_parallel_file_transfer_semaphore")
            and asyncio_event_loop in self._parallel_file_transfer_semaphore
            and self._parallel_file_transfer_semaphore[asyncio_event_loop] is not None
        ):
            return self._parallel_file_transfer_semaphore[asyncio_event_loop]

        self._parallel_file_transfer_semaphore.update(
            {asyncio_event_loop: asyncio.Semaphore(max(self.max_threads * 2, 1))}
        )

        return self._parallel_file_transfer_semaphore[asyncio_event_loop]

    # initialize logging
    def _init_logger(self):
        """
        Initialize logging
        """
        logger_name = (
            SILENT_LOGGER_NAME
            if self.silent
            else DEBUG_LOGGER_NAME if self.debug else DEFAULT_LOGGER_NAME
        )
        self.logger = logging.getLogger(logger_name)
        logging.getLogger("py.warnings").handlers = self.logger.handlers

    @classmethod
    def get_client(cls, synapse_client: typing.Union[None, "Synapse"]) -> "Synapse":
        """
        Convience function to get an instance of 'Synapse'. The latest instance created
        by 'login()' or set via `set_client` will be returned.

        When 'logout()' is called it will delete the instance.

        Arguments:
            synapse_client: An instance of 'Synapse' or None. This is used to simplify logical checks
                    in cases where synapse is passed into them.

        Returns:
            An instance of 'Synapse'.

        Raises:
            SynapseError: No Synapse client instance was provided, and no cached
                instance is available. Ensure that either an instance is passed as the
                `synapse_client` kwarg, or a cached instance is available.
        """
        if synapse_client:
            return synapse_client

        if not cls._synapse_client:
            raise SynapseError(
                "No Synapse client instance was provided, and no cached instance is available. Ensure that either an instance is passed as the `synapse_client` kwarg, or a cached instance is available."
            )
        return cls._synapse_client

    @staticmethod
    def allow_client_caching(allow_client_caching: bool) -> None:
        """Allows for a global setting to enable or disable caching of the Synapse
        client object. **If you are working in a multi-user environment you should set
        this to False to prevent any possibility of picking up another user session.**


        As a consequence of setting this to false you must pass a Synapse class instance
        to any function, method, or class that requires it - If if it is marked as
        `Optional`.
        """
        Synapse._allow_client_caching = allow_client_caching

    @staticmethod
    def enable_open_telemetry(
        enable_open_telemetry_tracing: bool = True,
        enable_open_telemetry_metrics: bool = False,
        *,
        resource_attributes: Optional[Dict[str, Any]] = None,
        include_context: bool = True,
    ) -> None:
        """Enables OpenTelemetry instrumentation for the Synapse client to collect telemetry data
        about your application's performance and behavior. This data can provide insights into
        latency, errors, and other performance metrics.

        Note: This is a one-way operation - once enabled, OpenTelemetry cannot be disabled within
        the same process. To disable it, you must restart your Python interpreter or application.

        When enabled, this method automatically:
        1. Sets up instrumentation for dependent libraries:
            - **Threading** (via `ThreadingInstrumentor`): Ensures proper context propagation
              across threads for maintaining trace continuity in multi-threaded applications
            - **HTTP libraries**:
                - `requests` (via `RequestsInstrumentor`): Captures all HTTP requests, including
                  methods, URLs, status codes, and timing information
                - `httpx` (via `HTTPXClientInstrumentor`): Tracks both synchronous and
                  asynchronous HTTP requests
                - `urllib` (via `URLLibInstrumentor`): Monitors lower-level HTTP operations
            - Each instrumented HTTP library includes custom hooks that extract Synapse entity
              IDs from URLs and add them as span attributes
        2. Configures traces to collect spans across your application:
            - Spans automatically capture operation duration, status, and errors
            - Attributes like `synapse.transfer.direction` and `synapse.operation.category`
              are properly propagated to child spans
            - Trace data is exported via OTLP (OpenTelemetry Protocol)
        3. Adds resource information to your traces, including:
            - Python version
            - OS type
            - Synapse client version
            - Service name and instance ID

        Environment Variable Configuration:
            - `OTEL_SERVICE_NAME`: Defines a unique identifier for your application or service
              (defaults to 'synapseclient'). Set this to a descriptive name that represents your
              specific implementation for easier filtering and analysis.
            - `OTEL_EXPORTER_OTLP_ENDPOINT`: Specifies the destination URL for sending telemetry
              data (defaults to 'http://localhost:4318/v1/traces'). Configure this to direct
              traces to your preferred collector or monitoring service.
            - `OTEL_DEBUG_CONSOLE`: Controls local visibility of telemetry data. Set to 'true' to
              output trace information to the console for development and troubleshooting.
            - `OTEL_SERVICE_INSTANCE_ID`: Distinguishes between multiple instances of the same
              service (e.g., 'prod', 'development', 'local') to identify which specific
              deployment generated particular traces.
            - `OTEL_EXPORTER_OTLP_HEADERS`: Configures authentication and metadata for telemetry
              exports. Use this to add API keys, tokens, or custom metadata when sending traces
              to secured collectors.

        Args:
            enable_open_telemetry_tracing: Whether to enable tracing (defaults to True).
            enable_open_telemetry_metrics: Whether to enable metrics collection (defaults to False).
            resource_attributes: Additional attributes to include with telemetry data, which can
                override environment variables like service name and instance ID.
            include_context: Whether to include runtime environment context (defaults to True).

        Example: Basic usage
            ```python
            import synapseclient

            # Enable OpenTelemetry with default settings
            synapseclient.Synapse.enable_open_telemetry()

            # Get a tracer and create custom spans for your code
            tracer = synapseclient.Synapse.get_tracer()

            # Use the tracer to create spans around your operations
            with tracer.start_as_current_span("my_operation"):
                syn = synapseclient.Synapse()
                syn.login()

                # Create nested spans for more detailed tracing
                with tracer.start_as_current_span("data_processing"):
                    # Your code here
                    pass
            ```

        Example: Custom configuration with resource attributes
            ```python
            import synapseclient
            import os

            # Set environment variables for telemetry configuration
            os.environ["OTEL_SERVICE_NAME"] = "my-synapse-app"
            os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://collector.example.com:4318"

            # Enable with custom resource attributes that override some environment variables
            synapseclient.Synapse.enable_open_telemetry(
                resource_attributes={
                    "deployment.environment": "production",
                    "service.version": "1.2.3",
                    "service.instance.id": "instance-1", # Overrides OTEL_SERVICE_INSTANCE_ID
                    "custom.attribute": "value"
                }
            )

            syn = synapseclient.Synapse()
            syn.login()
            ```
        """
        set_up_telemetry(
            enable_open_telemetry_tracing=enable_open_telemetry_tracing,
            enable_open_telemetry_metrics=enable_open_telemetry_metrics,
            resource_attributes=resource_attributes,
            include_context=include_context,
        )

    @classmethod
    def get_tracer(cls, name: Optional[str] = None) -> trace.Tracer:
        """Returns an OpenTelemetry tracer that can be used to create spans and collect telemetry data.

        The tracer allows you to create custom spans to track specific operations in your code,
        making it easier to analyze performance and troubleshoot issues. You can create spans,
        add attributes, events, and links to provide rich context about your application's behavior.

        Note: OpenTelemetry must be enabled via `Synapse.enable_open_telemetry()` before using this method.

        Args:
            name: Optional name for the tracer. If not provided, the default Synapse tracer is used.
                 Use this to create separate tracers for different components of your application.

        Returns:
            An OpenTelemetry Tracer instance that can be used to create spans.

        Example: Creating spans with the tracer
            ```python
            import synapseclient
            from opentelemetry.trace.status import Status, StatusCode

            # Enable OpenTelemetry first
            synapseclient.Synapse.enable_open_telemetry()
            syn = synapseclient.login()

            # Get a tracer
            tracer = synapseclient.Synapse.get_tracer()

            # Create a parent span
            with tracer.start_as_current_span("my_operation") as span:
                # Add attributes to provide context
                span.set_attribute("library.operation.type", "data_processing")
                span.set_attribute("library.entity.id", "syn123456")

                # Your code here

                # Create a child span for a sub-operation
                with tracer.start_as_current_span("data_validation") as child_span:
                    child_span.set_attribute("library.validation.type", "schema")
                    # More code here

                    # Add an event to mark a significant occurrence
                    child_span.add_event("validation_complete",
                                        {"records_processed": 100})
            ```

        Example: Using multiple named tracers
            ```python
            import synapseclient

            # Enable OpenTelemetry
            synapseclient.Synapse.enable_open_telemetry()

            data_tracer = synapseclient.Synapse.get_tracer("data_operations")
            syn = synapseclient.login()

            with data_tracer.start_as_current_span("data_download"):
                # Data download code
                pass
            ```
        """
        return otel_config_get_tracer(name=name)

    @classmethod
    def set_client(cls, synapse_client) -> None:
        cls._synapse_client = synapse_client

    @property
    def max_threads(self) -> int:
        return self._max_threads

    @max_threads.setter
    def max_threads(self, value: int):
        self._max_threads = min(max(value, 1), MAX_THREADS_CAP)

    @property
    def username(self) -> Union[str, None]:
        # for backwards compatability when username was a part of the Synapse object and not in credentials
        return self.credentials.username if self.credentials is not None else None

    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/api/configuration_services.py::get_config_file",
    )
    @functools.lru_cache()
    def getConfigFile(self, configPath: str) -> configparser.RawConfigParser:
        """
        Retrieves the client configuration information.

        Arguments:
            configPath:  Path to configuration file on local file system

        Returns:
            A RawConfigParser populated with properties from the user's configuration file.
        """

        try:
            config = configparser.RawConfigParser()
            config.read(configPath)  # Does not fail if the file does not exist
            return config
        except configparser.Error as ex:
            raise ValueError(
                "Error parsing Synapse config file: {}".format(configPath)
            ) from ex

    def setEndpoints(
        self,
        repoEndpoint: str = None,
        authEndpoint: str = None,
        fileHandleEndpoint: str = None,
        portalEndpoint: str = None,
        skip_checks: bool = False,
    ) -> None:
        """
        Sets the locations for each of the Synapse services (mostly useful for testing).

        Arguments:
            repoEndpoint:          Location of synapse repository
            authEndpoint:          Location of authentication service
            fileHandleEndpoint:    Location of file service
            portalEndpoint:        Location of the website
            skip_checks:           Skip version and endpoint checks

        Example: Switching endpoints
            To switch between staging and production endpoints

                syn.setEndpoints(**synapseclient.client.STAGING_ENDPOINTS)
                syn.setEndpoints(**synapseclient.client.PRODUCTION_ENDPOINTS)

        """

        endpoints = {
            "repoEndpoint": repoEndpoint,
            "authEndpoint": authEndpoint,
            "fileHandleEndpoint": fileHandleEndpoint,
            "portalEndpoint": portalEndpoint,
        }

        # For unspecified endpoints, first look in the config file
        config = get_config_file(self.configPath)
        for point in endpoints.keys():
            if endpoints[point] is None and config.has_option("endpoints", point):
                endpoints[point] = config.get("endpoints", point)

        # Endpoints default to production
        for point in endpoints.keys():
            if endpoints[point] is None:
                endpoints[point] = PRODUCTION_ENDPOINTS[point]

            # Update endpoints if we get redirected
            if not skip_checks:
                response = with_retry(
                    lambda point=point: self._requests_session.get(
                        endpoints[point],
                        allow_redirects=False,
                        headers=synapseclient.USER_AGENT,
                        timeout=self._http_timeout_seconds,
                    ),
                    verbose=self.debug,
                    **{**STANDARD_RETRY_PARAMS, "retries": 2},
                )
                if response.status_code == 301:
                    endpoints[point] = response.headers["location"]

        self.repoEndpoint = endpoints["repoEndpoint"]
        self.authEndpoint = endpoints["authEndpoint"]
        self.fileHandleEndpoint = endpoints["fileHandleEndpoint"]
        self.portalEndpoint = endpoints["portalEndpoint"]

    def login(
        self,
        email: str = None,
        silent: bool = False,
        authToken: str = None,
        profile: str = "default",
    ) -> None:
        """
        Valid combinations of login() arguments:

        - authToken
        - Profile-based authentication (from .synapseConfig)

        If no login arguments are provided or only username is provided, login() will attempt to log in using
         information from these sources (in order of preference):

        1. .synapseConfig file (supports multiple profiles)(in user home folder unless configured otherwise)
        2. User defined arguments during a CLI session
        3. User's Personal Access Token (aka: Synapse Auth Token)
            from the environment variable: SYNAPSE_AUTH_TOKEN
        4. Retrieves user's authentication token from AWS SSM Parameter store (if configured)

        Arguments:
            email (str): Synapse user name (or an email address associated with a Synapse account)
            authToken (str): A bearer authorization token, e.g. a
                [personal access token](https://python-docs.synapse.org/tutorials/authentication/).
            silent (bool): Defaults to False.  Suppresses the "Welcome ...!" message.
            profile (str): Profile to use from .synapseConfig (default: "default").

        Example: Logging in
        - Logging in using a specific profile:
                import synapseclient
                syn = synapseclient.login(profile="user1)
                > Welcome, username! You are using the user1 profile

        - Logging in with an authentication token:
            import synapseclient
            syn = synapseclient.login(authToken = "your_auth_token"))
            > Welcome, username!
        """
        # Note: the order of the logic below reflects the ordering in the docstring above.

        # Check version before logging in
        if not self.skip_checks:
            version_check(logger=self.logger)

        # Make sure to invalidate the existing session
        self.logout()

        user_login_args = UserLoginArgs(
            profile=profile, username=email, auth_token=authToken
        )
        credential_provider_chain = get_default_credential_chain()
        self.credentials = credential_provider_chain.get_credentials(
            syn=self, user_login_args=user_login_args
        )

        # Final check on login success
        if not self.credentials:
            raise SynapseNoCredentialsError(
                f"No valid authentication credentials provided.\n"
                f"Tried profile: '{profile}', email: '{email or 'N/A'}'.\n"
                "Check your `.synapseConfig` or ensure the provided auth token is valid."
            )

        if not silent:
            display_name = self.credentials.displayname or self.credentials.username
            if (
                not self.credentials.profile_name
                or self.credentials.profile_name.lower()
                == config_file_constants.AUTHENTICATION_SECTION_NAME
            ):
                self.logger.info(f"Welcome, {display_name}!\n")
            else:
                self.logger.info(
                    f"Welcome, {display_name}! You are using the '{self.credentials.profile_name}' profile."
                )

    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/api/configuration_services.py::get_config_section_dict",
    )
    def _get_config_section_dict(self, section_name: str) -> Dict[str, str]:
        """
        Get a profile section in the configuration file with the section name.

        Arguments:
            section_name: The name of the profile section in the configuration file

        Returns:
            A dictionary containing the configuration profile section content
        """
        config = get_config_file(self.configPath)
        try:
            return dict(config.items(section_name))
        except configparser.NoSectionError:
            # section not present
            return {}

    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/api/configuration_services.py::get_config_authentication",
    )
    def _get_config_authentication(self) -> Dict[str, str]:
        """
        Get the authentication section of the configuration file.

        Returns:
            The authentication section of the configuration file
        """
        return get_config_section_dict(
            section_name=config_file_constants.AUTHENTICATION_SECTION_NAME,
            config_path=self.configPath,
        )

    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/api/configuration_services.py::get_client_authenticated_s3_profile",
    )
    def _get_client_authenticated_s3_profile(
        self, endpoint: str, bucket: str
    ) -> Dict[str, str]:
        """
        Get the authenticated S3 profile from the configuration file.

        Arguments:
            endpoint: The location of the target service
            bucket:   AWS S3 bucket name

        Returns:
            The authenticated S3 profile
        """
        config_section = endpoint + "/" + bucket
        return get_config_section_dict(
            section_name=config_section, config_path=self.configPath
        ).get("profile_name", "default")

    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/api/configuration_services.py::get_transfer_config",
    )
    def _get_transfer_config(self) -> Dict[str, str]:
        """
        Get the transfer profile from the configuration file.

        Raises:
            ValueError: Invalid max_threads value. Should be equal or less than 16.
            ValueError: Invalid use_boto_sts value. Should be true or false.

        Returns:
            The transfer profile
        """
        # defaults
        transfer_config = {"max_threads": DEFAULT_NUM_THREADS, "use_boto_sts": False}

        for k, v in get_config_section_dict(
            section_name="transfer", config_path=self.configPath
        ).items():
            if v:
                if k == "max_threads" and v:
                    try:
                        transfer_config["max_threads"] = int(v)
                    except ValueError as cause:
                        raise ValueError(
                            f"Invalid transfer.max_threads config setting {v}"
                        ) from cause

                elif k == "use_boto_sts":
                    lower_v = v.lower()
                    if lower_v not in ("true", "false"):
                        raise ValueError(
                            f"Invalid transfer.use_boto_sts config setting {v}"
                        )

                    transfer_config["use_boto_sts"] = "true" == lower_v

        return transfer_config

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _is_logged_in(self) -> bool:
        """
        Test whether the user is logged in to Synapse.

        Returns:
            Boolean value indicating current user's login status
        """
        # This is a quick sanity check to see if credentials have been
        # configured on the client
        if self.credentials is None:
            return False
        # The public can query this command so there is no need to try catch.
        user = self.restGET("/userProfile")
        if user.get("userName") == "anonymous":
            return False
        return True

    def logout(self) -> None:
        """
        Removes authentication information from the Synapse client.

        Returns:
            None
        """
        self.credentials = None

    @deprecated(
        version="4.0.0",
        reason="deprecated with no replacement. The client does not support API keys for "
        "authentication. Please use a personal access token instead. This method will "
        "be removed in a future release.",
    )
    def invalidateAPIKey(self):
        """
        **Deprecated with no replacement.** The client does not support API keys for
        authentication. Please use a
        [personal access token](https://python-docs.synapse.org/tutorials/authentication/)
        instead. This method will be removed in a future release.


        Invalidates authentication across all clients.

        Returns:
            None
        """

        # Logout globally
        if self._is_logged_in():
            self.restDELETE("/secretKey", endpoint=self.authEndpoint)

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `from_username` method on the `from synapseclient.models import UserProfile` class. "
        "Check the docstring for the replacement function example.",
    )
    @functools.lru_cache()
    def get_user_profile_by_username(
        self,
        username: str = None,
        sessionToken: str = None,
    ) -> UserProfile:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the [from_username][synapseclient.models.UserProfile.from_username] method on the `from synapseclient.models import UserProfile` class.

        Get the details about a Synapse user.
        Retrieves information on the current user if 'id' is omitted or is empty string.

        Arguments:
            username:     The userName of a user
            sessionToken: The session token to use to find the user profile

        Returns:
            The user profile for the user of interest.

        Example: Using this function (DEPRECATED)
            Getting your own profile

                my_profile = syn.get_user_profile_by_username()

            Getting another user's profile

                users_profile = syn.get_user_profile_by_username('synapse-service-dpe-team')

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Get your own profile
            my_profile = UserProfile().get()
            print(f"My profile: {my_profile.username}")

            # Get another user's profile by username
            profile_by_username = UserProfile.from_username(username='synapse-service-dpe-team')
            print(f"Profile by username: {profile_by_username.username}")
            ```
        """
        is_none = username is None
        is_str = isinstance(username, str)
        if not is_str and not is_none:
            raise TypeError("username must be string or None")
        if is_str:
            principals = self._findPrincipals(username)
            for principal in principals:
                if principal.get("userName", None).lower() == username.lower():
                    id = principal["ownerId"]
                    break
            else:
                raise ValueError(f"Can't find user '{username}'")
        else:
            id = ""
        uri = f"/userProfile/{id}"
        return UserProfile(
            **self.restGET(
                uri, headers={"sessionToken": sessionToken} if sessionToken else None
            )
        )

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `from_id` method on the `from synapseclient.models import UserProfile` class. "
        "Check the docstring for the replacement function example.",
    )
    @functools.lru_cache()
    def get_user_profile_by_id(
        self,
        id: int = None,
        sessionToken: str = None,
    ) -> UserProfile:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.models.UserProfile.from_id][] instead.

        Get the details about a Synapse user.
        Retrieves information on the current user if 'id' is omitted.

        Arguments:
            id:           The ownerId of a user
            sessionToken: The session token to use to find the user profile

        Returns:
            The user profile for the user of interest.

        Example: Using this function (DEPRECATED)
            Getting your own profile

                my_profile = syn.get_user_profile_by_id()

            Getting another user's profile

                users_profile = syn.get_user_profile_by_id(3485485)

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Get your own profile
            my_profile = UserProfile().get()
            print(f"My profile: {my_profile.username}")

            # Get another user's profile by ID
            profile_by_id = UserProfile.from_id(user_id=3485485)
            print(f"Profile by id: {profile_by_id.username}")
            ```
        """
        if id:
            if not isinstance(id, int):
                raise TypeError("id must be an 'ownerId' integer")
        else:
            id = ""
        uri = f"/userProfile/{id}"
        return UserProfile(
            **self.restGET(
                uri, headers={"sessionToken": sessionToken} if sessionToken else None
            )
        )

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `from_id` and `from_username` methods on the `from synapseclient.models import UserProfile` class. "
        "Check the docstring for the replacement function example.",
    )
    @functools.lru_cache()
    def getUserProfile(
        self,
        id: Union[str, int, UserProfile, TeamMember] = None,
        sessionToken: str = None,
    ) -> UserProfile:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.models.protocols.user_protocol.from_id][] instead.

        Get the details about a Synapse user.
        Retrieves information on the current user if 'id' is omitted.

        Arguments:
            id:           The 'userId' (aka 'ownerId') of a user or the userName
            sessionToken: The session token to use to find the user profile

        Returns:
            The user profile for the user of interest.

        Example: Using this function (DEPRECATED)
            Getting your own profile

                my_profile = syn.getUserProfile()

            Getting another user's profile

                users_profile = syn.getUserProfile('synapse-service-dpe-team')

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Get your own profile
            my_profile = UserProfile().get()
            print(f"My profile: {my_profile.username}")

            # Get another user's profile by username
            profile_by_username = UserProfile.from_username(username='synapse-service-dpe-team')
            print(f"Profile by username: {profile_by_username.username}")

            # Get another user's profile by ID
            profile_by_id = UserProfile.from_id(user_id=3485485)
            print(f"Profile by id: {profile_by_id.username}")
            ```
        """
        try:
            # if id is unset or a userID, this will succeed
            id = "" if id is None else int(id)
        except (TypeError, ValueError):
            if isinstance(id, collections.abc.Mapping) and "ownerId" in id:
                id = id.ownerId
            elif isinstance(id, TeamMember):
                id = id.member.ownerId
            else:
                principals = self._findPrincipals(id)
                if len(principals) == 1:
                    id = principals[0]["ownerId"]
                else:
                    for principal in principals:
                        if principal.get("userName", None).lower() == id.lower():
                            id = principal["ownerId"]
                            break
                    else:  # no break
                        raise ValueError('Can\'t find user "%s": ' % id)
        uri = "/userProfile/%s" % id
        return UserProfile(
            **self.restGET(
                uri, headers={"sessionToken": sessionToken} if sessionToken else None
            )
        )

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _findPrincipals(self, query_string: str) -> List[UserGroupHeader]:
        """
        Find users or groups by name or email.

        Returns:
            A list of userGroupHeader objects with fields displayName, email, firstName, lastName, isIndividual, ownerId


        Example: Using this function
            Find userGroupHeader objects for test user

                syn._findPrincipals('test')

                [{u'displayName': u'Synapse Test',
                u'email': u'syn...t@sagebase.org',
                u'firstName': u'Synapse',
                u'isIndividual': True,
                u'lastName': u'Test',
                u'ownerId': u'1560002'},
                {u'displayName': ... }]
        """
        uri = "/userGroupHeaders?prefix=%s" % urllib_urlparse.quote(query_string)
        return [UserGroupHeader(**result) for result in self._GET_paginated(uri)]

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _get_certified_passing_record(
        self, userid: int
    ) -> Dict[str, Union[str, int, bool, list]]:
        """
        Retrieve the Passing Record on the User Certification test for the given user.

        Arguments:
            userid: Synapse user Id

        Returns:
            Synapse Passing Record. A record of whether a given user passed a given test.
            <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/quiz/PassingRecord.html>
        """
        response = self.restGET(f"/user/{userid}/certifiedUserPassingRecord")
        return response

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _get_user_bundle(self, userid: int, mask: int) -> Dict[str, Union[str, dict]]:
        """
        Retrieve the user bundle for the given user.

        Arguments:
            userid: Synapse user Id
            mask:   Bit field indicating which components to include in the bundle.

        Returns:
            [Synapse User Bundle](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/UserBundle.html)
        """
        try:
            response = self.restGET(f"/user/{userid}/bundle?mask={mask}")
        except SynapseHTTPError as ex:
            if ex.response.status_code == 404:
                return None
        return response

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `is_certified` method on the `from synapseclient.models import UserProfile` class. "
        "Check the docstring for the replacement function example.",
    )
    def is_certified(self, user: typing.Union[str, int]) -> bool:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.models.UserProfile.is_certified][] instead.

        Determines whether a Synapse user is a certified user.

        Arguments:
            user: Synapse username or Id

        Returns:
            True if the Synapse user is certified

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Check if user is certified by username
            profile_by_username = UserProfile.from_username(username='synapse-service-dpe-team')
            user_certified = profile_by_username.is_certified()
            print(f"User {profile_by_username.username} is certified: {user_certified}")

            # Check if user is certified by ID
            profile_by_id = UserProfile.from_id(user_id=3485485)
            user_certified = profile_by_id.is_certified()
            print(f"User {profile_by_id.username} is certified: {user_certified}")
            ```
        """
        # Check if userid or username exists
        syn_user = self.getUserProfile(user)
        # Get passing record

        try:
            certification_status = self._get_certified_passing_record(
                syn_user["ownerId"]
            )
            return certification_status["passed"]
        except SynapseHTTPError as ex:
            if ex.response.status_code == 404:
                # user hasn't taken the quiz
                return False
            raise

    @deprecated(
        version="4.11.0",
        reason="To be removed in 5.0.0. "
        "Use `from synapseclient.operations import is_synapse_id` instead.",
    )
    def is_synapse_id(self, syn_id: str) -> bool:
        """Checks if given synID is valid (attached to actual entity?)

        Arguments:
            syn_id: A Synapse ID

        Returns:
            True if the Synapse ID is valid
        """
        if isinstance(syn_id, str):
            try:
                self.get(syn_id, downloadFile=False)
            except SynapseFileNotFoundError:
                return False
            except (
                SynapseHTTPError,
                SynapseAuthenticationError,
            ) as err:
                status = (
                    err.__context__.response.status_code or err.response.status_code
                )
                if status in (400, 404):
                    return False
                # Valid ID but user lacks permission or is not logged in
                elif status == 403:
                    return True
            return True
        self.logger.warning("synID must be a string")
        return False

    @deprecated(
        version="4.11.0",
        reason="To be removed in 5.0.0. "
        "Use `from synapseclient.operations import onweb` instead.",
    )
    def onweb(self, entity, subpageId=None):
        """Opens up a browser window to the entity page or wiki-subpage.

        Arguments:
            entity:    Either an Entity or a Synapse ID
            subpageId: (Optional) ID of one of the wiki's sub-pages

        Returns:
            None
        """
        if isinstance(entity, str) and os.path.isfile(entity):
            entity = self.get(entity, downloadFile=False)
        synId = id_of(entity)
        if subpageId is None:
            webbrowser.open("%s/Synapse:%s" % (self.portalEndpoint, synId))
        else:
            webbrowser.open(
                "%s/Wiki:%s/ENTITY/%s" % (self.portalEndpoint, synId, subpageId)
            )

    @deprecated(
        version="4.11.0",
        reason="To be removed in 5.0.0. "
        "Use `from synapseclient.operations import print_entity` instead.",
    )
    def printEntity(self, entity, ensure_ascii=True) -> None:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.operations.print_entity][] instead.

        Pretty prints an Entity.

        Arguments:
            entity: The entity to be printed.
            ensure_ascii: If True, escapes all non-ASCII characters

        Example: Migration to new function
            &nbsp;

            ```python
            from synapseclient import Synapse
            from synapseclient.operations import print_entity

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Print an entity by Synapse ID
            print_entity("syn123456")

            # Print an entity object
            from synapseclient.operations import get
            entity = get(synapse_id="syn123456")
            print_entity(entity)

            # Print with unicode characters preserved
            print_entity("syn123456", ensure_ascii=False)
            ```

        Returns:
            None
        """

        if utils.is_synapse_id_str(entity):
            synid, version = utils.get_synid_and_version(entity)
            entity = self._getEntity(synid, version)
        try:
            self.logger.info(
                json.dumps(entity, sort_keys=True, indent=2, ensure_ascii=ensure_ascii)
            )
        except TypeError:
            self.logger.info(str(entity))

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _print_transfer_progress(self, *args, **kwargs) -> None:
        """
        Checking synapse if the mode is silent mode.
        If self.silent is True, no need to print out transfer progress.
        """
        if self.silent is not True:
            logger = kwargs.pop("logger", self.logger)
            cumulative_transfer_progress.printTransferProgress(
                *args, logger=logger, **kwargs
            )

    ############################################################
    #                      Service methods                     #
    ############################################################

    _services = {
        "json_schema": "JsonSchemaService",
    }

    @deprecated(
        version="4.11.0",
        reason="To be removed in 5.0.0. This is a beta feature with no replacement.",
    )
    def get_available_services(self) -> typing.List[str]:
        """Get available Synapse services
        This is a beta feature and is subject to change

        Returns:
            List of available services
        """
        services = self._services.keys()
        return list(services)

    @deprecated(
        version="4.11.0",
        reason="To be removed in 5.0.0. This is a beta feature with no replacement.",
    )
    def service(self, service_name: str):
        """Get available Synapse services
        This is a beta feature and is subject to change

        Arguments:
            service_name: name of the service
        """
        # This is to avoid circular imports
        # TODO: revisit the import order and method https://stackoverflow.com/a/37126790
        # To move this to the top
        import synapseclient.services

        assert isinstance(service_name, str)
        service_name = service_name.lower().replace(" ", "_")
        assert service_name in self._services, (
            f"Unrecognized service ({service_name}). Run the 'get_available_"
            "services()' method to get a list of available services."
        )
        service_attr = self._services[service_name]
        service_cls = getattr(synapseclient.services, service_attr)
        service = service_cls(self)
        return service

    ############################################################
    #                   Get / Store methods                    #
    ############################################################

    @deprecated(
        version="4.11.0",
        reason="To be removed in 5.0.0. "
        "Use `from synapseclient.operations import get` instead.",
    )
    def get(self, entity, **kwargs):
        """
        Gets a Synapse entity from the repository service.

        Arguments:
            entity:           A Synapse ID (e.g. syn123 or syn123.1, with .1 denoting version), a Synapse Entity object,
                              a plain dictionary in which 'id' maps to a Synapse ID or a local file that is stored in
                              Synapse (found by the file MD5)
            version:          The specific version to get.
                                Defaults to the most recent version. If not denoted in the entity input.
            downloadFile:     Whether associated files(s) should be downloaded.
                                Defaults to True.
            downloadLocation: Directory where to download the Synapse File Entity.
                                Defaults to the local cache.
            followLink:       Whether the link returns the target Entity.
                                Defaults to False.
            ifcollision:      Determines how to handle file collisions.
                                May be "overwrite.local", "keep.local", or "keep.both".
                                Defaults to "keep.both".
            limitSearch:      A Synanpse ID used to limit the search in Synapse if entity 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.
            md5: The MD5 checksum for the file, if known. Otherwise if the file is a
                local file, it will be calculated automatically.

        Returns:
            A new Synapse Entity object of the appropriate type.

        Example: Using this function
            Download file into cache

                entity = syn.get('syn1906479')
                print(entity.name)
                print(entity.path)

            Download file into current working directory

                entity = syn.get('syn1906479', downloadLocation='.')
                print(entity.name)
                print(entity.path)

            Determine the provenance of a locally stored file as indicated in Synapse

                entity = syn.get('/path/to/file.txt', limitSearch='syn12312')
                print(syn.getProvenance(entity))
        """
        return wrap_async_to_sync(self.get_async(entity, **kwargs))

    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1623
    async def get_async(self, entity, **kwargs):
        """
        Gets a Synapse entity from the repository service.

        Arguments:
            entity:           A Synapse ID (e.g. syn123 or syn123.1, with .1 denoting version), a Synapse Entity object,
                              a plain dictionary in which 'id' maps to a Synapse ID or a local file that is stored in
                              Synapse (found by the file MD5)
            version:          The specific version to get.
                                Defaults to the most recent version. If not denoted in the entity input.
            downloadFile:     Whether associated files(s) should be downloaded.
                                Defaults to True.
            downloadLocation: Directory where to download the Synapse File Entity.
                                Defaults to the local cache.
            followLink:       Whether the link returns the target Entity.
                                Defaults to False.
            ifcollision:      Determines how to handle file collisions.
                                May be "overwrite.local", "keep.local", or "keep.both".
                                Defaults to "keep.both".
            limitSearch:      A Synanpse ID used to limit the search in Synapse if entity 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.
            md5: The MD5 checksum for the file, if known. Otherwise if the file is a
                local file, it will be calculated automatically.

        Returns:
            A new Synapse Entity object of the appropriate type.

        Example: Using this function
            Download file into cache

                entity = syn.get('syn1906479')
                print(entity.name)
                print(entity.path)

            Download file into current working directory

                entity = syn.get('syn1906479', downloadLocation='.')
                print(entity.name)
                print(entity.path)

            Determine the provenance of a locally stored file as indicated in Synapse

                entity = syn.get('/path/to/file.txt', limitSearch='syn12312')
                print(syn.getProvenance(entity))
        """
        # If entity is a local file determine the corresponding synapse entity
        if isinstance(entity, str) and os.path.isfile(entity):
            bundle = self._getFromFile(
                entity, kwargs.pop("limitSearch", None), md5=kwargs.get("md5", None)
            )
            kwargs["downloadFile"] = False
            kwargs["path"] = entity

        elif isinstance(entity, str) and not utils.is_synapse_id_str(entity):
            raise SynapseFileNotFoundError(
                (
                    "The parameter %s is neither a local file path "
                    " or a valid entity id" % entity
                )
            )
        # have not been saved entities
        elif isinstance(entity, Entity) and not entity.get("id"):
            raise ValueError(
                "Cannot retrieve entity that has not been saved."
                " Please use syn.store() to save your entity and try again."
            )
        else:
            input_version = kwargs.get("version", None)
            synid_and_version = utils.get_synid_and_version(entity)
            version = (
                input_version if input_version is not None else synid_and_version[1]
            )
            # If ``version`` is None, the arg will be ignored
            bundle = self._getEntityBundle(synid_and_version[0], version)

        # Check and warn for unmet access requirements
        self._check_entity_restrictions(
            bundle, entity, kwargs.get("downloadFile", True)
        )

        return_data = await self._getWithEntityBundle_async(
            entityBundle=bundle, entity=entity, **kwargs
        )
        trace.get_current_span().set_attributes(
            {
                "synapse.id": return_data.get("id", ""),
                "synapse.concrete_type": return_data.get("concreteType", ""),
            }
        )
        return return_data

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _check_entity_restrictions(
        self, bundle: dict, entity: Union[str, Entity, dict], downloadFile: bool
    ) -> None:
        """
        Check and warn for unmet access requirements.

        Arguments:
            bundle: A Synapse entityBundle
            entity: A Synapse ID, a Synapse Entity object, a plain dictionary in which 'id' maps to a
                    Synapse ID or a local file that is stored in Synapse (found by the file MD5)
            downloadFile: Whether associated files(s) should be downloaded.

        Raises:
            SynapseUnmetAccessRestrictions: Warning for unmet access requirements.
        """
        restriction_information = bundle.get("restrictionInformation", None)
        if restriction_information and restriction_information.get(
            "hasUnmetAccessRequirement", None
        ):
            if not self.credentials or not self.credentials._token:
                warning_message = (
                    "You have not provided valid credentials for authentication with Synapse."
                    " Please provide an authentication token and use `synapseclient.login()` before your next attempt."
                    " See https://python-docs.synapse.org/tutorials/authentication/ for more information."
                )
            else:
                warning_message = (
                    "\nThis entity has access restrictions. Please visit the web page for this entity "
                    f'(syn.onweb("{id_of(entity)}")). Look for the "Access" label and the lock icon underneath '
                    'the file name. Click "Request Access", and then review and fulfill the file '
                    "download requirement(s).\n"
                )
            if downloadFile and bundle.get("entityType") not in ("project", "folder"):
                raise SynapseUnmetAccessRestrictions(warning_message)
            self.logger.warning(warning_message)

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _getFromFile(
        self, filepath: str, limitSearch: str = None, md5: str = None
    ) -> Dict[str, dict]:
        """
        Gets a Synapse entityBundle based on the md5 of a local file.
        See [get][synapseclient.Synapse.get].

        Arguments:
            filepath:    The path to local file
            limitSearch: Limits the places in Synapse where the file is searched for.
            md5: The MD5 checksum for the file, if known. Otherwise if the file is a
                local file, it will be calculated automatically.


        Raises:
            SynapseFileNotFoundError: If the file is not in Synapse.

        Returns:
            A Synapse entityBundle
        """
        results = self.restGET(
            "/entity/md5/%s" % (md5 or utils.md5_for_file(filepath).hexdigest())
        )["results"]
        if limitSearch is not None:
            # Go through and find the path of every entity found
            paths = [self.restGET("/entity/%s/path" % ent["id"]) for ent in results]
            # Filter out all entities whose path does not contain limitSearch
            results = [
                ent
                for ent, path in zip(results, paths)
                if utils.is_in_path(limitSearch, path)
            ]
        if len(results) == 0:  # None found
            raise SynapseFileNotFoundError("File %s not found in Synapse" % (filepath,))
        elif len(results) > 1:
            id_txts = "\n".join(
                ["%s.%i" % (r["id"], r["versionNumber"]) for r in results]
            )
            self.logger.warning(
                "\nThe file %s is associated with many files in Synapse:\n%s\n"
                "You can limit to files in specific project or folder by setting the limitSearch to the"
                " synapse Id of the project or folder.\n"
                "Will use the first one returned: \n"
                "%s version %i\n"
                % (filepath, id_txts, results[0]["id"], results[0]["versionNumber"])
            )
        entity = results[0]

        bundle = self._getEntityBundle(entity, version=entity["versionNumber"])
        self.cache.add(bundle["entity"]["dataFileHandleId"], filepath)

        return bundle

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "This method uses legacy Entity objects. "
        "Use the new dataclass models (File, Folder, Table, etc.) with their `parent_id` attribute and `.store()` method instead. ",
    )
    def move(self, entity, new_parent):
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the new dataclass models (File, Folder, Table, etc.) with their `parent_id`
        attribute and `.store()` method instead.

        Move a Synapse entity to a new container.

        Arguments:
            entity:     A Synapse ID, a Synapse Entity object, or a local file that is stored in Synapse
            new_parent: The new parent container (Folder or Project) to which the entity should be moved.

        Returns:
            The Synapse Entity object that has been moved.

        Example: Using this function (DEPRECATED)
            Move a Synapse Entity object to a new parent container

                entity = syn.move('syn456', 'syn123')

        Example: Migration to new method
            &nbsp;

            ```python
            from synapseclient import Synapse
            from synapseclient.models import (
                File, Folder, Table, Dataset, DatasetCollection,
                EntityView, SubmissionView, MaterializedView, VirtualTable
            )

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Moving a File
            file = File(id="syn456", download_file=False).get()
            file.parent_id = "syn123"
            file = file.store()
            print(f"Moved file to: {file.parent_id}")

            # Moving a Folder
            folder = Folder(id="syn789").get()
            folder.parent_id = "syn123"
            folder = folder.store()
            print(f"Moved folder to: {folder.parent_id}")

            # Moving a Table
            table = Table(id="syn101112").get()
            table.parent_id = "syn123"
            table = table.store()
            print(f"Moved table to: {table.parent_id}")

            # Moving a Dataset
            dataset = Dataset(id="syn131415").get()
            dataset.parent_id = "syn123"
            dataset = dataset.store()
            print(f"Moved dataset to: {dataset.parent_id}")

            # Moving a DatasetCollection
            dataset_collection = DatasetCollection(id="syn161718").get()
            dataset_collection.parent_id = "syn123"
            dataset_collection = dataset_collection.store()
            print(f"Moved dataset collection to: {dataset_collection.parent_id}")

            # Moving an EntityView
            entity_view = EntityView(id="syn192021").get()
            entity_view.parent_id = "syn123"
            entity_view = entity_view.store()
            print(f"Moved entity view to: {entity_view.parent_id}")

            # Moving a SubmissionView
            submission_view = SubmissionView(id="syn222324").get()
            submission_view.parent_id = "syn123"
            submission_view = submission_view.store()
            print(f"Moved submission view to: {submission_view.parent_id}")

            # Moving a MaterializedView
            materialized_view = MaterializedView(id="syn252627").get()
            materialized_view.parent_id = "syn123"
            materialized_view = materialized_view.store()
            print(f"Moved materialized view to: {materialized_view.parent_id}")

            # Moving a VirtualTable
            virtual_table = VirtualTable(id="syn282930").get()
            virtual_table.parent_id = "syn123"
            virtual_table = virtual_table.store()
            print(f"Moved virtual table to: {virtual_table.parent_id}")
            ```
        """

        entity = self.get(entity, downloadFile=False)
        entity.parentId = id_of(new_parent)
        entity = self.store(entity, forceVersion=False)
        trace.get_current_span().set_attributes(
            {
                "synapse.id": entity.get("id", ""),
                "synapse.parent_id": entity.get("parentId", ""),
            }
        )

        return entity

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _getWithEntityBundle(
        self, entityBundle: dict, entity: Entity = None, **kwargs
    ) -> Entity:
        """
        Creates a [Entity][synapseclient.Entity] from an entity bundle returned by Synapse.
        An existing Entity can be supplied in case we want to refresh a stale Entity.

        Arguments:
            entityBundle: Uses the given dictionary as the meta information of the Entity to get
            entity:       Optional, entity whose local state will be copied into the returned entity
            submission:   Optional, access associated files through a submission rather than through an entity.

        Returns:
            A new Synapse Entity

        Also see:
        - See [get][synapseclient.Synapse.get].
        - See [_getEntityBundle][synapseclient.Synapse._getEntityBundle].
        - See [Entity][synapseclient.Entity].
        """
        return wrap_async_to_sync(
            self._getWithEntityBundle_async(entityBundle, entity, **kwargs)
        )

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    async def _getWithEntityBundle_async(
        self, entityBundle: dict, entity: Entity = None, **kwargs
    ) -> Entity:
        """
        Creates a [Entity][synapseclient.Entity] from an entity bundle returned by Synapse.
        An existing Entity can be supplied in case we want to refresh a stale Entity.

        Arguments:
            entityBundle: Uses the given dictionary as the meta information of the Entity to get
            entity:       Optional, entity whose local state will be copied into the returned entity
            submission:   Optional, access associated files through a submission rather than through an entity.

        Returns:
            A new Synapse Entity

        Also see:
        - See [get][synapseclient.Synapse.get].
        - See [_getEntityBundle][synapseclient.Synapse._getEntityBundle].
        - See [Entity][synapseclient.Entity].
        """
        # Note: This version overrides the version of 'entity' (if the object is Mappable)
        kwargs.pop("version", None)
        downloadFile = kwargs.pop("downloadFile", True)
        downloadLocation = kwargs.pop("downloadLocation", None)
        ifcollision = kwargs.pop("ifcollision", None)
        submission = kwargs.pop("submission", None)
        followLink = kwargs.pop("followLink", False)
        path = kwargs.pop("path", None)

        # If Link, get target ID entity bundle
        if (
            entityBundle["entity"]["concreteType"]
            == "org.sagebionetworks.repo.model.Link"
            and followLink
        ):
            targetId = entityBundle["entity"]["linksTo"]["targetId"]
            targetVersion = entityBundle["entity"]["linksTo"].get("targetVersionNumber")
            entityBundle = self._getEntityBundle(targetId, targetVersion)

        # TODO is it an error to specify both downloadFile=False and downloadLocation?
        # TODO this matters if we want to return already cached files when downloadFile=False

        # Make a fresh copy of the Entity
        local_state = (
            entity.local_state() if entity and isinstance(entity, Entity) else {}
        )
        if path is not None:
            local_state["path"] = path
        properties = entityBundle["entity"]
        annotations = from_synapse_annotations(entityBundle["annotations"])
        entity = Entity.create(properties, annotations, local_state)

        # Handle download of fileEntities
        if isinstance(entity, File):
            # update the entity with FileHandle metadata
            file_handle = next(
                (
                    handle
                    for handle in entityBundle["fileHandles"]
                    if handle["id"] == entity.dataFileHandleId
                ),
                None,
            )
            entity._update_file_handle(file_handle)

            if downloadFile:
                if file_handle:
                    await download_file_entity(
                        download_location=downloadLocation,
                        entity=entity,
                        if_collision=ifcollision,
                        submission=submission,
                        synapse_client=self,
                    )
                else:  # no filehandle means that we do not have DOWNLOAD permission
                    warning_message = (
                        "WARNING: You have READ permission on this file entity but not DOWNLOAD "
                        "permission. The file has NOT been downloaded."
                    )
                    self.logger.warning(
                        "\n"
                        + "!" * len(warning_message)
                        + "\n"
                        + warning_message
                        + "\n"
                        + "!" * len(warning_message)
                        + "\n"
                    )
        return entity

    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/core/download/download_functions.py::ensure_download_location_is_directory",
    )
    def _ensure_download_location_is_directory(self, downloadLocation: str) -> str:
        """
        Check if the download location is a directory

        Arguments:
            downloadLocation: The download location

        Raises:
            ValueError: If the downloadLocation is not a directory

        Returns:
            The download location
        """
        download_dir = os.path.expandvars(os.path.expanduser(downloadLocation))
        if os.path.isfile(download_dir):
            raise ValueError(
                "Parameter 'downloadLocation' should be a directory, not a file."
            )
        return download_dir

    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/core/download/download_functions.py::download_file_entity",
    )
    def _download_file_entity(
        self,
        downloadLocation: str,
        entity: Entity,
        ifcollision: str,
        submission: str,
    ) -> None:
        """
        Download file entity

        Arguments:
            downloadLocation: The download location
            entity:           The Synapse Entity object
            ifcollision:      Determines how to handle file collisions.
                              May be

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

            submission:       Access associated files through a submission rather than through an entity.
        """
        # set the initial local state
        entity.path = None
        entity.files = []
        entity.cacheDir = None

        # check to see if an UNMODIFIED version of the file (since it was last downloaded) already exists
        # this location could be either in .synapseCache or a user specified location to which the user previously
        # downloaded the file
        cached_file_path = self.cache.get(entity.dataFileHandleId, downloadLocation)

        # location in .synapseCache where the file would be corresponding to its FileHandleId
        synapseCache_location = self.cache.get_cache_dir(entity.dataFileHandleId)

        file_name = (
            entity._file_handle.fileName
            if cached_file_path is None
            else os.path.basename(cached_file_path)
        )

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

        # resolve file path collisions by either overwriting, renaming, or not downloading, depending on the
        # ifcollision value
        downloadPath = self._resolve_download_path_collisions(
            downloadLocation,
            file_name,
            ifcollision,
            synapseCache_location,
            cached_file_path,
        )
        if downloadPath is None:
            return

        if cached_file_path is not None:  # copy from cache
            if downloadPath != cached_file_path:
                # create the foider if it does not exist already
                if not os.path.exists(downloadLocation):
                    os.makedirs(downloadLocation)
                shutil.copy(cached_file_path, downloadPath)

        else:  # download the file from URL (could be a local file)
            objectType = "FileEntity" if submission is None else "SubmissionAttachment"
            objectId = entity["id"] if submission is None else submission

            # reassign downloadPath because if url points to local file (e.g. file://~/someLocalFile.txt)
            # it won't be "downloaded" and, instead, downloadPath will just point to '~/someLocalFile.txt'
            # _downloadFileHandle may also return None to indicate that the download failed
            downloadPath = self._downloadFileHandle(
                entity.dataFileHandleId, objectId, objectType, downloadPath
            )

            if downloadPath is None or not os.path.exists(downloadPath):
                return

        # converts the path format from forward slashes back to backward slashes on Windows
        entity.path = os.path.normpath(downloadPath)
        entity.files = [os.path.basename(downloadPath)]
        entity.cacheDir = os.path.dirname(downloadPath)

    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/core/download/download_functions.py::resolve_download_path_collisions",
    )
    def _resolve_download_path_collisions(
        self,
        downloadLocation: str,
        file_name: str,
        ifcollision: str,
        synapseCache_location: str,
        cached_file_path: str,
    ) -> str:
        """
        Resolve file path collisions

        Arguments:
            downloadLocation:      The download location
            file_name:             The file name
            ifcollision:           Determines how to handle file collisions.
                                   May be "overwrite.local", "keep.local", or "keep.both".
            synapseCache_location: The location in .synapseCache where the file would be
                                   corresponding to its FileHandleId.
            cached_file_path:      The file path of the cached copy

        Raises:
            ValueError: Invalid ifcollision. Should be "overwrite.local", "keep.local", or "keep.both".

        Returns:
            The download file path with collisions resolved
        """
        # always overwrite if we are downloading to .synapseCache
        if utils.normalize_path(downloadLocation) == synapseCache_location:
            if ifcollision is not None and ifcollision != "overwrite.local":
                self.logger.warning(
                    "\n"
                    + "!" * 50
                    + f"\nifcollision={ifcollision} "
                    + "is being IGNORED because the download destination is synapse's cache."
                    ' Instead, the behavior is "overwrite.local". \n' + "!" * 50 + "\n"
                )
            ifcollision = "overwrite.local"
        # if ifcollision not specified, keep.local
        ifcollision = ifcollision or "keep.both"

        downloadPath = utils.normalize_path(os.path.join(downloadLocation, file_name))
        # resolve collison
        if os.path.exists(downloadPath):
            if ifcollision == "overwrite.local":
                pass
            elif ifcollision == "keep.local":
                # Don't want to overwrite the local file.
                return None
            elif ifcollision == "keep.both":
                if downloadPath != cached_file_path:
                    return utils.unique_filename(downloadPath)
            else:
                raise ValueError(
                    'Invalid parameter: "%s" is not a valid value '
                    'for "ifcollision"' % ifcollision
                )
        return downloadPath

    @deprecated(
        version="4.11.0",
        reason="To be removed in 5.0.0. "
        "Use `from synapseclient.operations import store` instead.",
    )
    def store(
        self,
        obj,
        *,
        createOrUpdate=True,
        forceVersion=True,
        versionLabel=None,
        isRestricted=False,
        activity=None,
        used=None,
        executed=None,
        activityName=None,
        activityDescription=None,
        set_annotations=True,
    ):
        """
        Creates a new Entity or updates an existing Entity, uploading any files in the process.

        Arguments:
            obj: A Synapse Entity, Evaluation, or Wiki
            used: The Entity, Synapse ID, or URL used to create the object (can also be a list of these)
            executed: The Entity, Synapse ID, or URL representing code executed to create the object
                        (can also be a list of these)
            activity: Activity object specifying the user's provenance.
            activityName: Activity name to be used in conjunction with *used* and *executed*.
            activityDescription: Activity description to be used in conjunction with *used* and *executed*.
            createOrUpdate: Indicates whether the method should automatically perform an update if the 'obj'
                            conflicts with an existing Synapse object.
            forceVersion: Indicates whether the method should increment the version of the object even if nothing
                            has changed.
            versionLabel: Arbitrary string used to label the version.
            isRestricted: 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.
            set_annotations: If True, set the annotations on the entity. If False, do not set the annotations.

        Returns:
            A Synapse Entity, Evaluation, or Wiki

        Example: Using this function
            Creating a new Project:

                from synapseclient import Project

                project = Project('My uniquely named project')
                project = syn.store(project)

            Adding files with [provenance (aka: Activity)][synapseclient.Activity]:

                from synapseclient import File, Activity

            A synapse entity *syn1906480* contains data and an entity *syn1917825* contains code

                activity = Activity(
                    'Fancy Processing',
                    description='No seriously, really fancy processing',
                    used=['syn1906480', 'http://data_r_us.com/fancy/data.txt'],
                    executed='syn1917825')

                test_entity = File('/path/to/data/file.xyz', description='Fancy new data', parent=project)
                test_entity = syn.store(test_entity, activity=activity)

        """
        return wrap_async_to_sync(
            coroutine=self.store_async(
                obj,
                createOrUpdate=createOrUpdate,
                forceVersion=forceVersion,
                versionLabel=versionLabel,
                isRestricted=isRestricted,
                activity=activity,
                used=used,
                executed=executed,
                activityName=activityName,
                activityDescription=activityDescription,
                set_annotations=set_annotations,
            )
        )

    async def store_async(
        self,
        obj,
        *,
        createOrUpdate=True,
        forceVersion=True,
        versionLabel=None,
        isRestricted=False,
        activity=None,
        used=None,
        executed=None,
        activityName=None,
        activityDescription=None,
        set_annotations=True,
    ):
        """
        Creates a new Entity or updates an existing Entity, uploading any files in the process.

        Arguments:
            obj: A Synapse Entity, Evaluation, or Wiki
            used: The Entity, Synapse ID, or URL used to create the object (can also be a list of these)
            executed: The Entity, Synapse ID, or URL representing code executed to create the object
                        (can also be a list of these)
            activity: Activity object specifying the user's provenance.
            activityName: Activity name to be used in conjunction with *used* and *executed*.
            activityDescription: Activity description to be used in conjunction with *used* and *executed*.
            createOrUpdate: Indicates whether the method should automatically perform an update if the 'obj'
                            conflicts with an existing Synapse object.
            forceVersion: Indicates whether the method should increment the version of the object even if nothing
                            has changed.
            versionLabel: Arbitrary string used to label the version.
            isRestricted: 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.
            set_annotations: If True, set the annotations on the entity. If False, do not set the annotations.

        Returns:
            A Synapse Entity, Evaluation, or Wiki

        Example: Using this function
            Creating a new Project:

            ```python
            import asyncio
            from synapseclient import Project, Synapse

            syn = Synapse()
            syn.login()

            async def main():
                project = Project('My uniquely named project')
                project = await syn.store_async(project)

            asyncio.run(main())
            ```

            Adding files with [provenance (aka: Activity)][synapseclient.Activity]:

            A synapse entity *syn1906480* contains data and an entity *syn1917825* contains code

            ```python
            import asyncio
            from synapseclient import File, Activity, Synapse

            syn = Synapse()
            syn.login()


            activity = Activity(
                'Fancy Processing',
                description='No seriously, really fancy processing',
                used=['syn1906480', 'http://data_r_us.com/fancy/data.txt'],
                executed='syn1917825')

            test_entity = File('/path/to/data/file.xyz', description='Fancy new data', parent=project)

            async def main():
                test_entity = await syn.store_async(test_entity, activity=activity)

            asyncio.run(main())
            ```

        """
        trace.get_current_span().set_attributes({"thread.id": threading.get_ident()})
        # SYNPY-1031: activity must be Activity object or code will fail later
        if activity:
            if not isinstance(activity, synapseclient.Activity):
                raise ValueError("activity should be synapseclient.Activity object")
        # _before_store hook
        # give objects a chance to do something before being stored
        if hasattr(obj, "_before_synapse_store"):
            obj._before_synapse_store(self)

        # _synapse_store hook
        # for objects that know how to store themselves
        if hasattr(obj, "_synapse_store_async"):
            return await obj._synapse_store_async(self)
        elif hasattr(obj, "_synapse_store"):
            return obj._synapse_store(self)

        # Handle all non-Entity objects
        if not (isinstance(obj, Entity) or type(obj) == dict):
            if isinstance(obj, Wiki):
                return await self._storeWiki_async(obj, createOrUpdate)

            if "id" in obj:  # If ID is present, update
                trace.get_current_span().set_attributes({"synapse.id": obj["id"]})
                return type(obj)(**self.restPUT(obj.putURI(), obj.json()))

            try:  # If no ID is present, attempt to POST the object
                return type(obj)(**self.restPOST(obj.postURI(), obj.json()))

            except SynapseHTTPError as err:
                # If already present and we want to update attempt to get the object content
                if createOrUpdate and err.response.status_code == 409:
                    newObj = self.restGET(obj.getByNameURI(obj.name))
                    newObj.update(obj)
                    obj = type(obj)(**newObj)
                    trace.get_current_span().set_attributes({"synapse.id": obj["id"]})
                    obj.update(self.restPUT(obj.putURI(), obj.json()))
                    return obj
                raise

        # If the input object is an Entity or a dictionary
        entity = obj
        properties, annotations, local_state = split_entity_namespaces(entity)
        bundle = None
        # Explicitly set an empty versionComment property if none is supplied,
        # otherwise an existing entity bundle's versionComment will be copied to the update.
        properties["versionComment"] = (
            properties["versionComment"] if "versionComment" in properties else None
        )

        # Anything with a path is treated as a cache-able item
        # Only Files are expected in the following logic
        if entity.get("path", False) and not isinstance(obj, Folder):
            local_file_md5_hex = None
            if "concreteType" not in properties:
                properties["concreteType"] = File._synapse_entity_type
            # Make sure the path is fully resolved
            entity["path"] = os.path.expanduser(entity["path"])

            # Check if the File already exists in Synapse by fetching metadata on it
            bundle = self._getEntityBundle(entity)

            if bundle:
                if createOrUpdate:
                    # update our properties from the existing bundle so that we have
                    # enough to process this as an entity update.
                    properties = {**bundle["entity"], **properties}

                # Check if the file should be uploaded
                fileHandle = find_data_file_handle(bundle)
                if (
                    fileHandle
                    and fileHandle["concreteType"]
                    == "org.sagebionetworks.repo.model.file.ExternalFileHandle"
                ):
                    # switching away from ExternalFileHandle or the url was updated
                    needs_upload = entity["synapseStore"] or (
                        fileHandle["externalURL"] != entity["externalURL"]
                    )
                else:
                    synapse_store_flag = entity["synapseStore"] or local_state.get(
                        "synapseStore"
                    )
                    # Check if we need to upload a new version of an existing
                    # file. If the file referred to by entity['path'] has been
                    # modified, we want to upload the new version.
                    # If synapeStore is false then we must upload a ExternalFileHandle
                    needs_upload = not synapse_store_flag or not self.cache.contains(
                        bundle["entity"]["dataFileHandleId"], entity["path"]
                    )

                    md5_stored_in_synapse = local_state.get("_file_handle", {}).get(
                        "contentMd5", None
                    ) or (fileHandle or {}).get("contentMd5", None)

                    # Check if we got an MD5 checksum from Synapse and compare it to the local file
                    if (
                        synapse_store_flag
                        and needs_upload
                        and os.path.isfile(entity["path"])
                        and md5_stored_in_synapse
                        and md5_stored_in_synapse
                        == (
                            local_file_md5_hex := utils.md5_for_file(
                                entity["path"]
                            ).hexdigest()
                        )
                    ):
                        needs_upload = False
            elif entity.get("dataFileHandleId", None) is not None:
                needs_upload = False
            else:
                needs_upload = True

            if needs_upload:
                local_state_fh = local_state.get("_file_handle", {})
                synapseStore = local_state.get("synapseStore", True)

                # parent_id_for_upload is allowing `store` to be called on files that have
                # already been stored to Synapse, but did not specify a parentId in the
                # FileEntity. This is useful as it prevents the need to specify the
                # parentId every time a file is stored to Synapse when the ID is
                # already known.
                parent_id_for_upload = entity.get("parentId", None)
                if not parent_id_for_upload and bundle and bundle.get("entity", None):
                    parent_id_for_upload = bundle["entity"]["parentId"]

                if not parent_id_for_upload:
                    raise SynapseMalformedEntityError(
                        "Entities of type File must have a parentId."
                    )

                fileHandle = await upload_file_handle_async(
                    self,
                    parent_id_for_upload,
                    (
                        local_state["path"]
                        if (synapseStore or local_state_fh.get("externalURL") is None)
                        else local_state_fh.get("externalURL")
                    ),
                    synapse_store=synapseStore,
                    md5=local_file_md5_hex or local_state_fh.get("contentMd5"),
                    file_size=local_state_fh.get("contentSize"),
                    mimetype=local_state_fh.get("contentType"),
                )
                properties["dataFileHandleId"] = fileHandle["id"]
                local_state["_file_handle"] = fileHandle

            elif "dataFileHandleId" not in properties:
                # Handle the case where the Entity lacks an ID
                # But becomes an update() due to conflict
                properties["dataFileHandleId"] = bundle["entity"]["dataFileHandleId"]

            # update the file_handle metadata if the FileEntity's FileHandle id has changed
            local_state_fh_id = local_state.get("_file_handle", {}).get("id")
            if (
                local_state_fh_id
                and properties["dataFileHandleId"] != local_state_fh_id
            ):
                local_state["_file_handle"] = find_data_file_handle(
                    self._getEntityBundle(
                        properties["id"],
                        requestedObjects={
                            "includeEntity": True,
                            "includeFileHandles": True,
                        },
                    )
                )

                # check if we already have the filehandleid cached somewhere
                cached_path = self.cache.get(properties["dataFileHandleId"])
                if cached_path is None:
                    local_state["path"] = None
                    local_state["cacheDir"] = None
                    local_state["files"] = []
                else:
                    local_state["path"] = cached_path
                    local_state["cacheDir"] = os.path.dirname(cached_path)
                    local_state["files"] = [os.path.basename(cached_path)]

        # Create or update Entity in Synapse
        if "id" in properties:
            trace.get_current_span().set_attributes({"synapse.id": properties["id"]})
            properties = self._updateEntity(properties, forceVersion, versionLabel)
        else:
            # If Link, get the target name, version number and concrete type and store in link properties
            if properties["concreteType"] == "org.sagebionetworks.repo.model.Link":
                target_properties = self._getEntity(
                    properties["linksTo"]["targetId"],
                    version=properties["linksTo"].get("targetVersionNumber"),
                )
                if target_properties["parentId"] == properties["parentId"]:
                    raise ValueError(
                        "Cannot create a Link to an entity under the same parent."
                    )
                properties["linksToClassName"] = target_properties["concreteType"]
                if (
                    target_properties.get("versionNumber") is not None
                    and properties["linksTo"].get("targetVersionNumber") is not None
                ):
                    properties["linksTo"]["targetVersionNumber"] = target_properties[
                        "versionNumber"
                    ]
                properties["name"] = target_properties["name"]
            try:
                properties = self._createEntity(properties)
            except SynapseHTTPError as ex:
                if createOrUpdate and ex.response.status_code == 409:
                    # Get the existing Entity's ID via the name and parent
                    existing_entity_id = self.findEntityId(
                        properties["name"], properties.get("parentId", None)
                    )
                    if existing_entity_id is None:
                        raise

                    # get existing properties and annotations
                    if not bundle:
                        bundle = self._getEntityBundle(
                            existing_entity_id,
                            requestedObjects={
                                "includeEntity": True,
                                "includeAnnotations": True,
                            },
                        )

                    properties = {**bundle["entity"], **properties}

                    # we additionally merge the annotations under the assumption that a missing annotation
                    # from a resolved conflict represents an newer annotation that should be preserved
                    # rather than an intentionally deleted annotation.
                    annotations = {
                        **from_synapse_annotations(bundle["annotations"]),
                        **annotations,
                    }

                    properties = self._updateEntity(
                        properties, forceVersion, versionLabel
                    )

                else:
                    raise

        # Deal with access restrictions
        if isRestricted:
            self._createAccessRequirementIfNone(properties)

        # Update annotations
        if set_annotations and (
            (not bundle and annotations)
            or (
                bundle and check_annotations_changed(bundle["annotations"], annotations)
            )
        ):
            annotations = self.set_annotations(
                Annotations(properties["id"], properties["etag"], annotations)
            )
            properties["etag"] = annotations.etag

        # If the parameters 'used' or 'executed' are given, create an Activity object
        if used or executed:
            if activity is not None:
                raise SynapseProvenanceError(
                    "Provenance can be specified as an Activity object or as used/executed"
                    " item(s), but not both."
                )
            activity = Activity(
                name=activityName,
                description=activityDescription,
                used=used,
                executed=executed,
            )

        # If we have an Activity, set it as the Entity's provenance record
        if activity:
            self.setProvenance(properties, activity)

            # 'etag' has changed, so get the new Entity
            properties = self._getEntity(properties)

        # Return the updated Entity object
        entity = Entity.create(properties, annotations, local_state)
        return_data = await self.get_async(entity, downloadFile=False)

        trace.get_current_span().set_attributes(
            {
                "synapse.id": return_data.get("id", ""),
                "synapse.concrete_type": entity.get("concreteType", ""),
            }
        )
        return return_data

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _createAccessRequirementIfNone(self, entity: Union[Entity, str]) -> None:
        """
        Checks to see if the given entity has access requirements. If not, then one is added

        Arguments:
            entity: A Synapse ID or a Synapse Entity object
        """
        existingRestrictions = self.restGET(
            "/entity/%s/accessRequirement?offset=0&limit=1" % id_of(entity)
        )
        if len(existingRestrictions["results"]) <= 0:
            self.restPOST("/entity/%s/lockAccessRequirement" % id_of(entity), body="")

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _getEntityBundle(
        self,
        entity: Union[Entity, str],
        version: int = None,
        requestedObjects: Dict[str, bool] = None,
    ) -> Dict[str, Union[dict, str, int, bool]]:
        """
        Gets some information about the Entity.

        Arguments:
            entity:           A Synapse Entity or Synapse ID
            version:          The entity's version. Defaults to None meaning most recent version.
            requestedObjects: A dictionary indicating settings for what to include.

        Default value for requestedObjects is:

            requestedObjects = {'includeEntity': True,
                                'includeAnnotations': True,
                                'includeFileHandles': True,
                                'includeRestrictionInformation': True}

        Keys available for requestedObjects:

            includeEntity
            includeAnnotations
            includePermissions
            includeEntityPath
            includeHasChildren
            includeAccessControlList
            includeFileHandles
            includeTableBundle
            includeRootWikiId
            includeBenefactorACL
            includeDOIAssociation
            includeFileName
            includeThreadCount
            includeRestrictionInformation


        Keys with values set to False may simply be omitted.
        For example, we might ask for an entity bundle containing file handles, annotations, and properties:
            requested_objects = {'includeEntity':True
                                 'includeAnnotations':True,
                                 'includeFileHandles':True}
            bundle = syn._getEntityBundle('syn111111', )

        Returns:
            An EntityBundle with the requested fields or by default Entity header, annotations, unmet access
            requirements, and file handles
        """
        # If 'entity' is given without an ID, try to find it by 'parentId' and 'name'.
        # Use case:
        #     If the user forgets to catch the return value of a syn.store(e)
        #     this allows them to recover by doing: e = syn.get(e)
        if requestedObjects is None:
            requestedObjects = {
                "includeEntity": True,
                "includeAnnotations": True,
                "includeFileHandles": True,
                "includeRestrictionInformation": True,
            }
        if (
            isinstance(entity, collections.abc.Mapping)
            and "id" not in entity
            and "name" in entity
        ):
            entity = self.findEntityId(entity["name"], entity.get("parentId", None))

        # Avoid an exception from finding an ID from a NoneType
        try:
            id_of(entity)
        except ValueError:
            return None

        if version is not None:
            uri = f"/entity/{id_of(entity)}/version/{int(version):d}/bundle2"
        else:
            uri = f"/entity/{id_of(entity)}/bundle2"
        bundle = self.restPOST(uri, body=json.dumps(requestedObjects))

        return bundle

    @deprecated(
        version="4.11.0",
        reason="To be removed in 5.0.0. "
        "Use `from synapseclient.operations import delete` instead.",
    )
    def delete(
        self,
        obj,
        version=None,
    ):
        """
        Removes an object from Synapse.

        Arguments:
            obj: An existing object stored on Synapse such as Evaluation, File, Project, or Wiki
            version: For entities, specify a particular version to delete.
        """
        # Handle all strings as the Entity ID for backward compatibility
        if isinstance(obj, str):
            entity_id = id_of(obj)
            trace.get_current_span().set_attributes({"synapse.id": entity_id})
            if version:
                self.restDELETE(uri=f"/entity/{entity_id}/version/{version}")
            else:
                self.restDELETE(uri=f"/entity/{entity_id}")
        elif hasattr(obj, "_synapse_delete"):
            return obj._synapse_delete(self)
        else:
            try:
                if isinstance(obj, Versionable):
                    self.restDELETE(obj.deleteURI(versionNumber=version))
                else:
                    self.restDELETE(obj.deleteURI())
            except AttributeError:
                raise SynapseError(
                    f"Can't delete a {type(obj)}. Please specify a Synapse object or id"
                )

    _user_name_cache = {}

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _get_user_name(self, user_id: str) -> str:
        """
        Get username with ownerId

        Arguments:
            user_id: The ownerId of a user

        Returns:
            A username
        """
        if user_id not in self._user_name_cache:
            self._user_name_cache[user_id] = utils.extract_user_name(
                self.getUserProfile(user_id)
            )
        return self._user_name_cache[user_id]

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _list(
        self,
        parent: str,
        recursive: bool = False,
        long_format: bool = False,
        show_modified: bool = False,
        indent: float = 0,
        out=sys.stdout,
    ) -> None:
        """
        List child objects of the given parent, recursively if requested.

        Arguments:
            parent:        A Synapse ID for folder or project that you want to list child objects for
            recursive:     Whether to show subfolder
            long_format:   Whether to show createdOn, createdBy and version
            show_modified: Whether to show modifiedOn and modifiedBy
            indent:        The left padding of the file tree structure
            out:           The location to write the output.
        """
        fields = ["id", "name", "nodeType"]
        if long_format:
            fields.extend(["createdByPrincipalId", "createdOn", "versionNumber"])
        if show_modified:
            fields.extend(["modifiedByPrincipalId", "modifiedOn"])
        results = self.getChildren(parent)

        results_found = False
        for result in results:
            results_found = True

            fmt_fields = {
                "name": result["name"],
                "id": result["id"],
                "padding": " " * indent,
                "slash_or_not": "/" if is_container(result) else "",
            }
            fmt_string = "{id}"

            if long_format:
                fmt_fields["createdOn"] = utils.iso_to_datetime(
                    result["createdOn"]
                ).strftime("%Y-%m-%d %H:%M")
                fmt_fields["createdBy"] = self._get_user_name(result["createdBy"])[:18]
                fmt_fields["version"] = result["versionNumber"]
                fmt_string += " {version:3}  {createdBy:>18} {createdOn}"
            if show_modified:
                fmt_fields["modifiedOn"] = utils.iso_to_datetime(
                    result["modifiedOn"]
                ).strftime("%Y-%m-%d %H:%M")
                fmt_fields["modifiedBy"] = self._get_user_name(result["modifiedBy"])[
                    :18
                ]
                fmt_string += "  {modifiedBy:>18} {modifiedOn}"

            fmt_string += "  {padding}{name}{slash_or_not}\n"
            out.write(fmt_string.format(**fmt_fields))

            if (indent == 0 or recursive) and is_container(result):
                self._list(
                    result["id"],
                    recursive=recursive,
                    long_format=long_format,
                    show_modified=show_modified,
                    indent=indent + 2,
                    out=out,
                )

        if indent == 0 and not results_found:
            out.write(
                "No results visible to {username} found for id {id}\n".format(
                    username=self.credentials.username, id=id_of(parent)
                )
            )

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/core/upload/upload_functions.py::upload_file_handle_async. "
        "Use `upload_file_handle_async` directly instead.",
    )
    def uploadFileHandle(
        self, path, parent, synapseStore=True, mimetype=None, md5=None, file_size=None
    ):
        """Uploads the file in the provided path (if necessary) to a storage location based on project settings.
        Returns a new FileHandle as a dict to represent the stored file.

        Arguments:
            parent: Parent of the entity to which we upload.
            path:   File path to the file being uploaded
            synapseStore: If False, will not upload the file, but instead create an ExternalFileHandle that references
                            the file on the local machine.
                            If True, will upload the file based on StorageLocation determined by the entity_parent_id
            mimetype: The MIME type metadata for the uploaded file
            md5: The MD5 checksum for the file, if known. Otherwise if the file is a local file, it will be calculated
                    automatically.
            file_size: The size the file, if known. Otherwise if the file is a local file, it will be calculated
                        automatically.
            file_type: The MIME type the file, if known. Otherwise if the file is a local file, it will be calculated
                        automatically.

        Returns:
            A dict of a new FileHandle as a dict that represents the uploaded file

        Example: Migrating from this method to upload_file_handle_async
            **Legacy approach (deprecated):**
            ```python
            # Using the deprecated uploadFileHandle method
            file_handle = syn.uploadFileHandle(
                path="/path/to/file.txt",
                parent="syn12345",
                synapseStore=True,
                mimetype="text/plain"
            )
            ```

            **New approach using upload_file_handle:**
            ```python
            import asyncio
            import synapseclient
            from synapseclient.core.upload.upload_functions_async import upload_file_handle

            # Create client and login
            syn = synapseclient.Synapse()
            syn.login()

            # Using the new async function directly
            async def upload_file():
                file_handle = await upload_file_handle(
                    syn=syn,
                    parent_entity_id="syn12345",
                    path="/path/to/file.txt",
                    synapse_store=True,
                    md5=None,
                    file_size=None,
                    mimetype="text/plain"
                )
                return file_handle

            # Run the async function
            file_handle = asyncio.run(upload_file())
            print(f"File handle uploaded: {file_handle}")
            ```
        """
        return wrap_async_to_sync(
            upload_file_handle_async(
                self, parent, path, synapseStore, md5, file_size, mimetype
            )
        )

    ############################################################
    #                  Download List                           #
    ############################################################
    @deprecated(
        version="4.13.0",
        reason=(
            "Use `synapseclient.operations.download_list_clear()` instead. "
            "See synapseclient.operations.download_list_operations for the new interface."
        ),
    )
    def clear_download_list(self):
        """Clear all files from download list

        Example: Migration to new method
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # syn.clear_download_list()

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.operations import download_list_clear

            syn = Synapse()
            syn.login()

            # Clear all files from the download list
            download_list_clear()
            ```
        """
        self.restDELETE("/download/list")

    @deprecated(
        version="4.13.0",
        reason=(
            "Use `synapseclient.operations.download_list_remove(files)` instead. "
            "See synapseclient.operations.download_list_operations for the new interface."
        ),
    )
    def remove_from_download_list(self, list_of_files: typing.List[typing.Dict]) -> int:
        """Remove a batch of files from download list

        Example: Migration to new method
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # syn.remove_from_download_list([
            #     {"fileEntityId": "syn123", "versionNumber": 1},
            # ])

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.operations import download_list_remove, DownloadListItem

            syn = Synapse()
            syn.login()

            # Remove specific file versions from the download list
            download_list_remove([
                DownloadListItem(file_entity_id="syn123", version_number=1),
            ])
            ```

        Arguments:
            list_of_files: Array of files in the format of a mapping {fileEntityId: synid, versionNumber: version}

        Returns:
            Number of files removed from download list
        """
        request_body = {"batchToRemove": list_of_files}
        num_files_removed = self.restPOST(
            "/download/list/remove", body=json.dumps(request_body)
        )
        return num_files_removed

    @deprecated(
        version="4.13.0",
        reason=(
            "Use `synapseclient.operations.download_list_manifest()` instead. "
            "See synapseclient.operations.download_list_operations for the new interface."
        ),
    )
    def _generate_manifest_from_download_list(
        self,
        quoteCharacter: str = '"',
        escapeCharacter: str = "\\",
        lineEnd: str = os.linesep,
        separator: str = ",",
        header: bool = True,
    ):
        """Creates a download list manifest generation request

        Example: Migration to new method
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # manifest_handle = syn._generate_manifest_from_download_list()

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.operations import download_list_manifest

            syn = Synapse()
            syn.login()

            # Generate and download the manifest CSV
            manifest_path = download_list_manifest()
            ```

        Arguments:
            quoteCharacter:  The character to be used for quoted elements in the resulting file.
            escapeCharacter: The escape character to be used for escaping a separator or quote in the resulting file.
            lineEnd:         The line feed terminator to be used for the resulting file.
            separator:       The delimiter to be used for separating entries in the resulting file.
            header:          Is the first line a header?

        Returns:
            Filehandle of download list manifest
        """
        request_body = {
            "concreteType": "org.sagebionetworks.repo.model.download.DownloadListManifestRequest",
            "csvTableDescriptor": {
                "separator": separator,
                "quoteCharacter": quoteCharacter,
                "escapeCharacter": escapeCharacter,
                "lineEnd": lineEnd,
                "isFirstLineHeader": header,
            },
        }
        return self._waitForAsync(
            uri="/download/list/manifest/async", request=request_body
        )

    @deprecated(
        version="4.13.0",
        reason=(
            "Use `synapseclient.operations.download_list_manifest()` instead. "
            "See synapseclient.operations.download_list_operations for the new interface."
        ),
    )
    def get_download_list_manifest(self):
        """Get the path of the download list manifest file

        Example: Migration to new method
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # manifest_path = syn.get_download_list_manifest()

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.operations import download_list_manifest

            syn = Synapse()
            syn.login()

            # Generate and download the manifest CSV
            manifest_path = download_list_manifest()
            ```

        Returns:
            Path of download list manifest file
        """
        manifest = self._generate_manifest_from_download_list()
        # Get file handle download link
        file_result = get_file_handle_for_download(
            file_handle_id=manifest["resultFileHandleId"],
            synapse_id=manifest["resultFileHandleId"],
            entity_type="FileEntity",
            synapse_client=self,
        )
        # Download the manifest
        downloaded_path = self._download_from_URL(
            url=file_result["preSignedURL"],
            destination="./",
            fileHandleId=file_result["fileHandleId"],
            expected_md5=file_result["fileHandle"].get("contentMd5"),
        )
        trace.get_current_span().set_attributes(
            {"synapse.file_handle_id": file_result["fileHandleId"]}
        )
        return downloaded_path

    @deprecated(
        version="4.13.0",
        reason=(
            "Use `synapseclient.operations.download_list_files(download_location=...)` instead. "
            "See synapseclient.operations.download_list_operations for the new interface."
        ),
    )
    def get_download_list(self, downloadLocation: str = None) -> str:
        """Download all files from your Synapse download list

        Example: Migration to new method
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # manifest_path = syn.get_download_list(downloadLocation="./downloads")

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.operations import download_list_files

            syn = Synapse()
            syn.login()

            # Download all files in the cart and get the result manifest path
            manifest_path = download_list_files(download_location="./downloads")
            ```

        Arguments:
            downloadLocation: Directory to download files to.

        Returns:
            Manifest file with file paths
        """
        dl_list_path = self.get_download_list_manifest()
        downloaded_files = []
        new_manifest_path = f"manifest_{time.time_ns()}.csv"
        with (
            open(dl_list_path) as manifest_f,
            open(new_manifest_path, "w") as write_obj,
        ):
            reader = csv.DictReader(manifest_f)
            columns = reader.fieldnames
            columns.extend(["path", "error"])
            # Write the downloaded paths to a new manifest file
            writer = csv.DictWriter(write_obj, fieldnames=columns)
            writer.writeheader()

            for row in reader:
                # You can add things to the download list that you don't have access to
                # So there must be a try catch here
                try:
                    entity = self.get(row["ID"], downloadLocation=downloadLocation)
                    # Must include version number because you can have multiple versions of a
                    # file in the download list
                    downloaded_files.append(
                        {
                            "fileEntityId": row["ID"],
                            "versionNumber": row["versionNumber"],
                        }
                    )
                    row["path"] = entity.path
                    row["error"] = ""
                except Exception:
                    row["path"] = ""
                    row["error"] = "DOWNLOAD FAILED"
                    self.logger.exception("Unable to download file")
                writer.writerow(row)

        # Don't want to clear all the download list because you can add things
        # to the download list after initiating this command.
        # Files that failed to download should not be removed from download list
        # Remove all files from download list after the entire download is complete.
        # This is because if download fails midway, we want to return the full manifest
        if downloaded_files:
            # Only want to invoke this if there is a list of files to remove
            # or the API call will error
            self.remove_from_download_list(list_of_files=downloaded_files)
        else:
            self.logger.warning("A manifest was created, but no files were downloaded")

        # Always remove original manifest file
        os.remove(dl_list_path)

        return new_manifest_path

    ############################################################
    #                  Get / Set Annotations                   #
    ############################################################

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _getRawAnnotations(
        self, entity: Union[Entity, str], version: int = None
    ) -> Dict[str, Union[str, dict]]:
        """
        Retrieve annotations for an Entity returning them in the native Synapse format.

        Arguments:
            entity:  A Synapse Entity or Synapse ID
            version: The entity's version. Defaults to None meaning most recent version.

        Returns:
            An annotation dictionary
        """
        # Note: Specifying the version results in a zero-ed out etag,
        # even if the version is the most recent.
        # See [PLFM-1874](https://sagebionetworks.jira.com/browse/PLFM-1874) for more details.
        if version:
            uri = f"/entity/{id_of(entity)}/version/{str(version)}/annotations2"
        else:
            uri = f"/entity/{id_of(entity)}/annotations2"
        return self.restGET(uri)

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. Use the dataclass model attributes instead. "
        "All dataclass models support annotations: File, Folder, Project, Table, EntityView, Dataset, "
        "DatasetCollection, MaterializedView, SubmissionView, VirtualTable. "
        "Access annotations directly via `instance.annotations` attribute.",
    )
    def get_annotations(
        self, entity: typing.Union[str, Entity], version: typing.Union[str, int] = None
    ) -> Annotations:
        """
        Retrieve annotations for an Entity from the Synapse Repository as a Python dict.

        Note that collapsing annotations from the native Synapse format to a Python dict may involve some loss of
        information. See `_getRawAnnotations` to get annotations in the native format.

        Arguments:
            entity: An Entity or Synapse ID to lookup
            version: The version of the Entity to retrieve.

        Returns:
            A [synapseclient.annotations.Annotations][] object, a dict that also has id and etag attributes

        Example: Migrating from this method to dataclass models
            **Legacy approach (deprecated):**
            ```python
            # Get the File entity first
            file_entity = syn.get("syn123")

            # Get annotations separately
            annotations = syn.get_annotations(file_entity)
            print(annotations)
            ```

            **New approach using dataclass models:**
            ```python
            import synapseclient
            from synapseclient.models import (
                File, Folder, Project, Table, EntityView, Dataset,
                DatasetCollection, MaterializedView, SubmissionView, VirtualTable
            )

            # Create client and login
            syn = synapseclient.Synapse()
            syn.login()

            # File - don't download the file content, just get metadata
            file_instance = File(id="syn12345", download_file=False)
            file_instance = file_instance.get()
            print(f"File annotations: {file_instance.annotations}")

            # Folder
            folder_instance = Folder(id="syn11111")
            folder_instance = folder_instance.get()
            print(f"Folder annotations: {folder_instance.annotations}")

            # Project
            project_instance = Project(id="syn22222")
            project_instance = project_instance.get()
            print(f"Project annotations: {project_instance.annotations}")

            # Table
            table_instance = Table(id="syn33333")
            table_instance = table_instance.get()
            print(f"Table annotations: {table_instance.annotations}")

            # EntityView
            view_instance = EntityView(id="syn44444")
            view_instance = view_instance.get()
            print(f"EntityView annotations: {view_instance.annotations}")

            # Dataset
            dataset_instance = Dataset(id="syn55555")
            dataset_instance = dataset_instance.get()
            print(f"Dataset annotations: {dataset_instance.annotations}")

            # DatasetCollection
            collection_instance = DatasetCollection(id="syn66666")
            collection_instance = collection_instance.get()
            print(f"DatasetCollection annotations: {collection_instance.annotations}")

            # MaterializedView
            mat_view_instance = MaterializedView(id="syn77777")
            mat_view_instance = mat_view_instance.get()
            print(f"MaterializedView annotations: {mat_view_instance.annotations}")

            # SubmissionView
            sub_view_instance = SubmissionView(id="syn88888")
            sub_view_instance = sub_view_instance.get()
            print(f"SubmissionView annotations: {sub_view_instance.annotations}")

            # VirtualTable
            virtual_table_instance = VirtualTable(id="syn99999")
            virtual_table_instance = virtual_table_instance.get()
            print(f"VirtualTable annotations: {virtual_table_instance.annotations}")

            # Access specific annotation values
            # annotations is always a dict by default (empty {} if no annotations exist)
            species = file_instance.annotations.get("species", [])
            data_type = file_instance.annotations.get("dataType", [])
            print(f"Species: {species}, Data type: {data_type}")

            # Check if a specific annotation exists
            if species:
                print(f"Species annotation exists: {species}")
            else:
                print("Species annotation not found")

            # Get all annotation keys
            annotation_keys = list(file_instance.annotations.keys())
            print(f"Available annotation keys: {annotation_keys}")
            ```
        """
        return from_synapse_annotations(self._getRawAnnotations(entity, version))

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. Use the dataclass model attributes instead. "
        "All dataclass models support annotations: File, Folder, Project, Table, EntityView, Dataset, "
        "DatasetCollection, MaterializedView, SubmissionView, VirtualTable. "
        "Set annotations via `instance.annotations = {...}` then call `instance.store()`.",
    )
    def set_annotations(self, annotations: Annotations):
        """
        Store annotations for an Entity in the Synapse Repository.

        Arguments:
            annotations: A [synapseclient.annotations.Annotations][] of annotation names and values,
                            with the id and etag attribute set

        Returns:
            The updated [synapseclient.annotations.Annotations][] for the entity

        Example: Migrating from this method to dataclass models
            **Legacy approach (deprecated):**
            ```python
            # Get annotations, modify, and set back
            annos = syn.get_annotations('syn12345')
            annos['foo'] = ['bar', 'baz']
            annos['qwerty'] = 'asdf'
            annos = syn.set_annotations(annos)
            print(annos)
            ```

            **New approach using dataclass models:**

            In this example all of these updates are destructive, meaning they will
            overwrite any existing annotations. If you want to merge annotations
            instead, see the merging example below.
            ```python
            import synapseclient
            from synapseclient.models import (
                File, Folder, Project, Table, EntityView, Dataset,
                DatasetCollection, MaterializedView, SubmissionView, VirtualTable
            )

            # Create client and login
            syn = synapseclient.Synapse()
            syn.login()

            # File - don't download the file content, just get metadata
            file_instance = File(id="syn12345", download_file=False)
            file_instance = file_instance.get()
            file_instance.annotations = {
                "foo": ["bar", "baz"],
                "qwerty": ["asdf"],
                "species": ["Homo sapiens"]
            }
            file_instance = file_instance.store()
            print(f"File annotations: {file_instance.annotations}")

            # Folder
            folder_instance = Folder(id="syn11111")
            folder_instance = folder_instance.get()
            folder_instance.annotations = {
                "category": ["research"],
                "department": ["biology"]
            }
            folder_instance = folder_instance.store()
            print(f"Folder annotations: {folder_instance.annotations}")

            # Project
            project_instance = Project(id="syn22222")
            project_instance = project_instance.get()
            project_instance.annotations = {
                "funding": ["NIH"],
                "grant_number": ["R01-12345"]
            }
            project_instance = project_instance.store()
            print(f"Project annotations: {project_instance.annotations}")

            # Table
            table_instance = Table(id="syn33333")
            table_instance = table_instance.get()
            table_instance.annotations = {
                "version": ["1.0"],
                "data_type": ["clinical"]
            }
            table_instance = table_instance.store()
            print(f"Table annotations: {table_instance.annotations}")

            # EntityView
            view_instance = EntityView(id="syn44444")
            view_instance = view_instance.get()
            view_instance.annotations = {
                "scope": ["project_wide"],
                "view_type": ["file_view"]
            }
            view_instance = view_instance.store()
            print(f"EntityView annotations: {view_instance.annotations}")

            # Dataset
            dataset_instance = Dataset(id="syn55555")
            dataset_instance = dataset_instance.get()
            dataset_instance.annotations = {
                "dataset_type": ["genomic"],
                "size": ["large"]
            }
            dataset_instance = dataset_instance.store()
            print(f"Dataset annotations: {dataset_instance.annotations}")

            # DatasetCollection
            collection_instance = DatasetCollection(id="syn66666")
            collection_instance = collection_instance.get()
            collection_instance.annotations = {
                "collection_type": ["multi_omics"],
                "studies": ["3"]
            }
            collection_instance = collection_instance.store()
            print(f"DatasetCollection annotations: {collection_instance.annotations}")

            # MaterializedView
            mat_view_instance = MaterializedView(id="syn77777")
            mat_view_instance = mat_view_instance.get()
            mat_view_instance.annotations = {
                "refresh_frequency": ["daily"],
                "data_source": ["clinical_db"]
            }
            mat_view_instance = mat_view_instance.store()
            print(f"MaterializedView annotations: {mat_view_instance.annotations}")

            # SubmissionView
            sub_view_instance = SubmissionView(id="syn88888")
            sub_view_instance = sub_view_instance.get()
            sub_view_instance.annotations = {
                "evaluation_queue": ["challenge_2024"],
                "status": ["active"]
            }
            sub_view_instance = sub_view_instance.store()
            print(f"SubmissionView annotations: {sub_view_instance.annotations}")

            # VirtualTable
            virtual_table_instance = VirtualTable(id="syn99999")
            virtual_table_instance = virtual_table_instance.get()
            virtual_table_instance.annotations = {
                "virtual_type": ["federated"],
                "source_count": ["5"]
            }
            virtual_table_instance = virtual_table_instance.store()
            print(f"VirtualTable annotations: {virtual_table_instance.annotations}")
            ```

            **For merging with existing annotations:**
            ```python
            import synapseclient
            from synapseclient.models import File, Folder

            # Create client and login
            syn = synapseclient.Synapse()
            syn.login()

            # Get existing annotations and merge for File
            file_instance = File(id="syn12345", download_file=False)
            file_instance = file_instance.get()

            # Merge with existing annotations (annotations is always a dict by default)
            file_instance.annotations.update({
                "foo": ["bar", "baz"],
                "qwerty": ["asdf"]
            })

            # Store the updated File
            file_instance = file_instance.store()
            print(f"Updated file annotations: {file_instance.annotations}")

            # Same pattern works for all other dataclass models
            folder_instance = Folder(id="syn11111")
            folder_instance = folder_instance.get()
            folder_instance.annotations.update({"new_key": ["new_value"]})
            folder_instance = folder_instance.store()
            print(f"Updated folder annotations: {folder_instance.annotations}")
            ```

            **For updating single annotation values:**
            ```python
            import synapseclient
            from synapseclient.models import File

            # Create client and login
            syn = synapseclient.Synapse()
            syn.login()

            # Update a single annotation value while preserving existing annotations
            file_instance = File(id="syn12345", download_file=False)
            file_instance = file_instance.get()

            # annotations is always a dict by default (empty {} if no annotations exist)
            # You can directly access and modify annotation values
            file_instance.annotations["species"] = ["Mus musculus"]
            file_instance.annotations["data_type"] = ["RNA-seq"]

            # Store the updated File
            file_instance = file_instance.store()
            print(f"Updated file annotations: {file_instance.annotations}")
            ```

            **IMPORTANT - Destructive vs Non-destructive updates:**
            ```python
            import synapseclient
            from synapseclient.models import File

            # Create client and login
            syn = synapseclient.Synapse()
            syn.login()

            # When you call .get(), existing annotations are loaded into the instance
            file_instance = File(id="syn12345", download_file=False)
            file_instance = file_instance.get()
            # Now file_instance.annotations contains existing annotations from Synapse

            # DESTRUCTIVE UPDATE - This replaces ALL existing annotations
            file_instance.annotations = {
                "new_key": ["new_value"]
            }
            # All previous annotations are lost!

            # NON-DESTRUCTIVE UPDATE - This preserves existing annotations
            # annotations is always a dict by default (empty {} if no annotations exist)
            file_instance.annotations.update({
                "new_key": ["new_value"]
            })
            # OR modify individual keys:
            file_instance.annotations["another_key"] = ["another_value"]
            # Previous annotations are preserved

            # To remove ALL annotations, set to None or empty dict
            file_instance.annotations = None  # Clears all annotations
            # OR
            file_instance.annotations = {}    # Also clears all annotations

            file_instance = file_instance.store()
            ```

        Example: Using this function (DEPRECATED)
            Getting annotations, adding a new annotation, and updating the annotations:

                annos = syn.get_annotations('syn123')

            `annos` will contain the id and etag associated with the entity upon retrieval

                print(annos.id)
                > syn123
                print(annos.etag)
                > 7bdb83e9-a50a-46e4-987a-4962559f090f   (Usually some UUID in the form of a string)

            Returned `annos` object from `get_annotations()` can be used as if it were a dict.
            Set key 'foo' to have value of 'bar' and 'baz'

                annos['foo'] = ['bar', 'baz']

            Single values will automatically be wrapped in a list once stored

                annos['qwerty'] = 'asdf'

            Store the annotations

                annos = syn.set_annotations(annos)

                print(annos)
                > {'foo':['bar','baz], 'qwerty':['asdf']}
        """

        if not isinstance(annotations, Annotations):
            raise TypeError("Expected a synapseclient.Annotations object")

        synapseAnnos = to_synapse_annotations(annotations)

        entity_id = id_of(annotations)
        trace.get_current_span().set_attributes({"synapse.id": entity_id})

        return from_synapse_annotations(
            self.restPUT(
                f"/entity/{entity_id}/annotations2",
                body=json.dumps(synapseAnnos),
            )
        )

    ############################################################
    #                         Querying                         #
    ############################################################

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Use the new dataclass models `from synapseclient.models import Project, Folder` "
        "with their `sync_from_synapse` method for most use cases, "
        "or the `synapseclient.api.get_children` function for direct API access with sorting and filtering.",
    )
    def getChildren(
        self,
        parent,
        includeTypes=[
            "folder",
            "file",
            "table",
            "link",
            "entityview",
            "dockerrepo",
            "submissionview",
            "dataset",
            "materializedview",
        ],
        sortBy="NAME",
        sortDirection="ASC",
    ):
        """
        Retrieves all of the entities stored within a parent such as folder or project.

        Arguments:
            parent: An id or an object of a Synapse container or None to retrieve all projects
            includeTypes: Must be a list of entity types (ie. ["folder","file"]) which can be found [here](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/EntityType.html)
            sortBy: How results should be sorted. Can be NAME, or CREATED_ON
            sortDirection: The direction of the result sort. Can be ASC, or DESC

        Yields:
            An iterator that shows all the children of the container.

        Also see:

        - [synapseutils.walk][]

        Example: Migrating from this method to new approaches
            &nbsp;

            **Legacy approach (deprecated):**
            ```python
            # Using the deprecated getChildren method
            for child in syn.getChildren("syn12345", includeTypes=["file", "folder"]):
                print(f"Child: {child['name']} (ID: {child['id']})")
            ```

            **New approach using dataclass models with sync_from_synapse:**
            ```python
            import synapseclient
            from synapseclient.models import Project, Folder

            # Create client and login
            syn = synapseclient.Synapse()
            syn.login()

            # For projects - get all children automatically (recursive by default)
            project = Project(id="syn12345")
            project = project.sync_from_synapse(download_file=False)

            # Access different types of children
            print(f"Files: {len(project.files)}")
            for file in project.files:
                print(f"  File: {file.name} (ID: {file.id})")

            print(f"Folders: {len(project.folders)}")
            for folder in project.folders:
                print(f"  Folder: {folder.name} (ID: {folder.id})")

            print(f"Tables: {len(project.tables)}")
            for table in project.tables:
                print(f"  Table: {table.name} (ID: {table.id})")

            # For folders - get all children automatically (recursive by default)
            folder = Folder(id="syn67890")
            folder = folder.sync_from_synapse(download_file=False)

            # Access children in the same way
            for file in folder.files:
                print(f"  File: {file.name} (ID: {file.id})")

            # For non-recursive behavior (equivalent to single getChildren call)
            folder = Folder(id="syn67890")
            folder = folder.sync_from_synapse(download_file=False, recursive=False)

            # This will only get immediate children, not subfolders' contents
            for file in folder.files:
                print(f"  File: {file.name} (ID: {file.id})")
            for subfolder in folder.folders:
                print(f"  Subfolder: {subfolder.name} (ID: {subfolder.id})")
                # Note: subfolder.files and subfolder.folders will be empty
                # because recursive=False
            ```

            **New approach using the API directly (for advanced sorting/filtering):**
            ```python
            import asyncio
            import synapseclient
            from synapseclient.api import get_children

            # Create client and login
            syn = synapseclient.Synapse()
            syn.login()

            # Using the new async API function directly
            async def get_sorted_children():
                async for child in get_children(
                    parent="syn12345",
                    include_types=["file", "folder"],
                    sort_by="NAME",
                    sort_direction="ASC"
                ):
                    print(f"Child: {child['name']} (ID: {child['id']}, Type: {child['type']})")

            # Run the async function
            asyncio.run(get_sorted_children())
            ```
        """
        parentId = id_of(parent) if parent is not None else None

        trace.get_current_span().set_attributes({"synapse.parent_id": parentId})
        entityChildrenRequest = {
            "parentId": parentId,
            "includeTypes": includeTypes,
            "sortBy": sortBy,
            "sortDirection": sortDirection,
            "nextPageToken": None,
        }
        entityChildrenResponse = {"nextPageToken": "first"}
        while entityChildrenResponse.get("nextPageToken") is not None:
            entityChildrenResponse = self.restPOST(
                "/entity/children", body=json.dumps(entityChildrenRequest)
            )
            for child in entityChildrenResponse["page"]:
                yield child
            if entityChildrenResponse.get("nextPageToken") is not None:
                entityChildrenRequest["nextPageToken"] = entityChildrenResponse[
                    "nextPageToken"
                ]

    @deprecated(
        version="4.11.0",
        reason="To be removed in 5.0.0. "
        "Use `from synapseclient.operations import md5_query` instead.",
    )
    def md5Query(self, md5):
        """
        Find the Entities which have attached file(s) which have the given MD5 hash.

        Arguments:
            md5: The MD5 to query for (hexadecimal string)

        Returns:
            A list of Entity headers
        """

        return self.restGET("/entity/md5/%s" % md5)["results"]

    ############################################################
    #                     ACL manipulation                     #
    ############################################################

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _getBenefactor(
        self, entity: Union[Entity, str]
    ) -> Dict[str, Union[str, int, bool]]:
        """
        Get an Entity's benefactor.
        An Entity gets its ACL from its benefactor.

        Arguments:
            entity: A Synapse Entity or Synapse ID

        Returns:
            A dictionary of the Entity's benefactor

        """
        if utils.is_synapse_id_str(entity) or is_synapse_entity(entity):
            synid, _ = utils.get_synid_and_version(entity)
            return self.restGET("/entity/%s/benefactor" % synid)

        return entity

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _getACL(
        self, entity: Union[Entity, str], check_benefactor: bool = True
    ) -> Dict[str, Union[str, list]]:
        """
        Get the effective Access Control Lists (ACL) for a Synapse Entity.

        Arguments:
            entity: A Synapse Entity or Synapse ID
            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.

        Returns:
            A dictionary of the Entity's ACL
        """
        if hasattr(entity, "getACLURI"):
            uri = entity.getACLURI()
            return self.restGET(uri)
        else:
            if check_benefactor:
                # Get the ACL from the benefactor (which may be the entity itself)
                benefactor = self._getBenefactor(entity)
                trace.get_current_span().set_attributes(
                    {"synapse.id": benefactor["id"]}
                )
                uri = "/entity/%s/acl" % (benefactor["id"])
                return self.restGET(uri)
            else:
                synid, _ = utils.get_synid_and_version(entity)
                trace.get_current_span().set_attributes({"synapse.id": synid})
                uri = "/entity/%s/acl" % (synid)
                try:
                    return self.restGET(uri)
                except SynapseHTTPError as e:
                    if (
                        "The requested ACL does not exist. This entity inherits its permissions from:"
                        in str(e)
                    ):
                        # If the entity does not have an ACL, return an empty ACL
                        return {"resourceAccess": []}
                    raise e

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _storeACL(
        self, entity: Union[Entity, str], acl: Dict[str, Union[str, list]]
    ) -> Dict[str, Union[str, list]]:
        """
        Create or update the ACL for a Synapse Entity.

        Arguments:
            entity:  A Synapse Entity or Synapse ID
            acl:     An ACl as a dictionary

        The format of acl:

            {'resourceAccess': [
                {'accessType': ['READ'],
                 'principalId': 222222}
            ]}

        Returns:
            The new or updated ACL
        """
        if hasattr(entity, "putACLURI"):
            return self.restPUT(entity.putACLURI(), json.dumps(acl))
        else:
            # Get benefactor. (An entity gets its ACL from its benefactor.)
            entity_id = id_of(entity)
            uri = "/entity/%s/benefactor" % entity_id
            benefactor = self.restGET(uri)

            # Update or create new ACL
            uri = "/entity/%s/acl" % entity_id
            if benefactor["id"] == entity_id:
                return self.restPUT(uri, json.dumps(acl))
            else:
                return self.restPOST(uri, json.dumps(acl))

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _getUserbyPrincipalIdOrName(self, principalId: str = None) -> int:
        """
        Given either a string, int or None finds the corresponding user where None implies PUBLIC

        Arguments:
            principalId: Identifier of a user or group

        Raises:
            SynapseError: Warn for unknown user principalId

        Returns:
            The integer ID of the user
        """
        if principalId is None or principalId == "PUBLIC":
            return PUBLIC
        try:
            return int(principalId)

        # If principalId is not a number assume it is a name or email
        except ValueError:
            userProfiles = self.restGET("/userGroupHeaders?prefix=%s" % principalId)
            totalResults = len(userProfiles["children"])
            if totalResults == 1:
                return int(userProfiles["children"][0]["ownerId"])
            elif totalResults > 1:
                for profile in userProfiles["children"]:
                    if profile["userName"] == principalId:
                        return int(profile["ownerId"])

            supplementalMessage = (
                "Please be more specific" if totalResults > 1 else "No matches"
            )
            raise SynapseError(
                "Unknown Synapse user (%s).  %s." % (principalId, supplementalMessage)
            )

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `get_acl` method on the dataclass models that inherit from `AccessControllable` mixin. "
        "Example: `from synapseclient.models import File; File(id='syn123').get_acl()`",
    )
    def get_acl(
        self,
        entity: Union[Entity, Evaluation, str, collections.abc.Mapping],
        principal_id: str = None,
        check_benefactor: bool = True,
    ) -> typing.List[str]:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `get_acl` method on the dataclass models that inherit from `AccessControllable` mixin instead.

        Get the [ACL](https://rest-docs.synapse.org/rest/org/
        sagebionetworks/repo/model/ACCESS_TYPE.html)
        that a user or group has on an Entity.

        Arguments:
            entity:      An Entity or Synapse ID to lookup
            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.

        Returns:
            An array containing some combination of
                ['READ', 'UPDATE', 'CREATE', 'DELETE', 'DOWNLOAD', 'MODERATE',
                'CHANGE_PERMISSIONS', 'CHANGE_SETTINGS']
                or an empty array

        Example: Using this function (DEPRECATED)
            Getting ACL permissions for a user on an entity

                permissions = syn.get_acl("syn123", principal_id="12345")

            Getting ACL permissions for the public on an entity

                permissions = syn.get_acl("syn123")

        Example: Migration to new method
            &nbsp;

            ```python
            from synapseclient import Synapse
            from synapseclient.models import (
                File, Folder, Project, Table, EntityView, Dataset,
                DatasetCollection, MaterializedView, SubmissionView, VirtualTable
            )

            # Create client and login
            syn = Synapse()
            syn.login()

            # Get ACL permissions for a specific user on a File
            file_instance = File(id="syn123")
            permissions = file_instance.get_acl(principal_id=12345)
            print(f"User 12345 permissions on File syn123: {permissions}")

            # Get ACL permissions for the public on a File
            file_instance = File(id="syn123")
            permissions = file_instance.get_acl()  # defaults to PUBLIC users
            print(f"Public permissions on File syn123: {permissions}")

            # Get ACL permissions with benefactor check disabled
            file_instance = File(id="syn123")
            permissions = file_instance.get_acl(
                principal_id=12345,
                check_benefactor=False
            )
            print(f"Entity-specific permissions for user 12345 on File syn123: {permissions}")

            # Works with all AccessControllable models:

            # Project
            project = Project(id="syn123")
            permissions = project.get_acl(principal_id=12345)
            print(f"User 12345 permissions on Project syn123: {permissions}")

            # Folder
            folder = Folder(id="syn123")
            permissions = folder.get_acl(principal_id=12345)
            print(f"User 12345 permissions on Folder syn123: {permissions}")

            # Table
            table = Table(id="syn123")
            permissions = table.get_acl(principal_id=12345)
            print(f"User 12345 permissions on Table syn123: {permissions}")

            # EntityView
            entity_view = EntityView(id="syn123")
            permissions = entity_view.get_acl(principal_id=12345)
            print(f"User 12345 permissions on EntityView syn123: {permissions}")

            # Dataset
            dataset = Dataset(id="syn123")
            permissions = dataset.get_acl(principal_id=12345)
            print(f"User 12345 permissions on Dataset syn123: {permissions}")

            # DatasetCollection
            dataset_collection = DatasetCollection(id="syn123")
            permissions = dataset_collection.get_acl(principal_id=12345)
            print(f"User 12345 permissions on DatasetCollection syn123: {permissions}")

            # MaterializedView
            materialized_view = MaterializedView(id="syn123")
            permissions = materialized_view.get_acl(principal_id=12345)
            print(f"User 12345 permissions on MaterializedView syn123: {permissions}")

            # SubmissionView
            submission_view = SubmissionView(id="syn123")
            permissions = submission_view.get_acl(principal_id=12345)
            print(f"User 12345 permissions on SubmissionView syn123: {permissions}")

            # VirtualTable
            virtual_table = VirtualTable(id="syn123")
            permissions = virtual_table.get_acl(principal_id=12345)
            print(f"User 12345 permissions on VirtualTable syn123: {permissions}")

            # Additional functionality available on AccessControllable models:

            # List all ACL entries for an entity
            file_instance = File(id="syn123")
            acl_list = file_instance.list_acl()
            print(f"All ACL entries for File syn123: {acl_list}")

            # Delete the entire ACL for an entity (makes it inherit from benefactor)
            file_instance = File(id="syn123")
            file_instance.delete_permissions()
            print("Successfully deleted entire ACL for File syn123 - now inherits permissions")

            # To remove permissions for a specific user/group, use set_permissions with empty access_type
            file_instance = File(id="syn123")
            file_instance.set_permissions(principal_id=12345, access_type=[])
            print("Successfully removed all permissions for user 12345 on File syn123")

            # Use dry_run to preview what would be deleted without actually deleting
            file_instance = File(id="syn123")
            file_instance.delete_permissions(dry_run=True)
            print("Dry run completed - showed what would be deleted")
            ```
        """

        principal_id = self._getUserbyPrincipalIdOrName(principal_id)

        trace.get_current_span().set_attributes(
            {"synapse.id": id_of(entity), "synapse.principal_id": principal_id}
        )

        acl = self._getACL(entity=entity, check_benefactor=check_benefactor)

        team_list = self._find_teams_for_principal(principal_id)
        team_ids = [int(team.id) for team in team_list]
        effective_permission_set = set()

        # This user_profile_bundle is being used to verify that the principal_id
        #  is a registered user of the system
        user_profile_bundle = self._get_user_bundle(principal_id, 1)

        # Loop over all permissions in the returned ACL and add it to the effective_permission_set
        # if the principalId in the ACL matches
        # 1) the one we are looking for,
        # 2) a team the entity is a member of,
        # 3) PUBLIC
        # 4) A user_profile_bundle exists for the principal_id
        for permissions in acl["resourceAccess"]:
            if "principalId" in permissions and (
                permissions["principalId"] == principal_id
                or permissions["principalId"] in team_ids
                or permissions["principalId"] == PUBLIC
                or (
                    permissions["principalId"] == AUTHENTICATED_USERS
                    and user_profile_bundle is not None
                )
            ):
                effective_permission_set = effective_permission_set.union(
                    permissions["accessType"]
                )
        return list(effective_permission_set)

    @deprecated(
        version="4.0.0",
        reason="deprecated and replaced with synapseclient.Synapse.get_acl",
    )
    def getPermissions(
        self,
        entity: Union[Entity, Evaluation, str, collections.abc.Mapping],
        principal_id: str = None,
    ) -> typing.List[str]:
        """
        **Deprecated** and replaced with [get_acl][synapseclient.Synapse.get_acl].


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

        Arguments:
            entity:      An Entity or Synapse ID to lookup
            principal_id: Identifier of a user or group (defaults to PUBLIC users)

        Returns:
            An array containing some combination of
                ['READ', 'UPDATE', 'CREATE', 'DELETE', 'DOWNLOAD', 'MODERATE',
                'CHANGE_PERMISSIONS', 'CHANGE_SETTINGS']
                or an empty array
        """

        return self.get_acl(entity=entity, principal_id=principal_id)

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `get_permissions` method on the dataclass models that inherit from `AccessControllable` mixin. "
        "Note: The new `get_permissions` method only returns permissions for the current user. "
        "To get permissions for a specific principal, use the `get_acl` method instead. "
        "Example: `from synapseclient.models import File; File(id='syn123').get_permissions(); File(id='syn123').get_acl(principal_id=12345)`",
    )
    def get_permissions(
        self, entity: Union[Entity, Evaluation, str, collections.abc.Mapping]
    ) -> Permissions:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `get_permissions` method on the dataclass models that inherit from `AccessControllable` mixin instead.

        Get the [permissions](https://rest-docs.synapse.org/rest/org/
        sagebionetworks/repo/model/auth/UserEntityPermissions.html)
        that the caller has on an Entity.

        Arguments:
            entity: An Entity or Synapse ID to lookup

        Returns:
            An Permissions object

        Example: Using this function (DEPRECATED)
            Getting permissions for a Synapse Entity

                permissions = syn.get_permissions(Entity)

            Getting permissions for a Synapse ID

                permissions = syn.get_permissions("syn12345")

            Getting access types list from the Permissions object

                permissions.access_types

        Example: Migration to new method
            &nbsp;

            ```python
            from synapseclient import Synapse
            from synapseclient.models import (
                File, Folder, Project, Table, EntityView, Dataset,
                DatasetCollection, MaterializedView, SubmissionView, VirtualTable
            )

            # Create client and login
            syn = Synapse()
            syn.login()

            # Get permissions for the current user on a File
            file_instance = File(id="syn12345")
            permissions = file_instance.get_permissions()
            print(f"Current user permissions on File syn12345: {permissions}")
            print(f"Current user access types: {permissions.access_types}")

            # Get permissions for the current user on other entity types:

            # Project
            project = Project(id="syn12345")
            permissions = project.get_permissions()
            print(f"Current user permissions on Project {project.id}: {permissions}")
            print(f"Current user access types: {permissions.access_types}")

            # Folder
            folder = Folder(id="syn12345")
            permissions = folder.get_permissions()
            print(f"Current user permissions on Folder {folder.id}: {permissions}")
            print(f"Current user access types: {permissions.access_types}")

            # Table
            table = Table(id="syn12345")
            permissions = table.get_permissions()
            print(f"Current user permissions on Table {table.id}: {permissions}")
            print(f"Current user access types: {permissions.access_types}")

            # EntityView
            entity_view = EntityView(id="syn12345")
            permissions = entity_view.get_permissions()
            print(f"Current user permissions on EntityView {entity_view.id}: {permissions}")
            print(f"Current user access types: {permissions.access_types}")

            # Dataset
            dataset = Dataset(id="syn12345")
            permissions = dataset.get_permissions()
            print(f"Current user permissions on Dataset {dataset.id}: {permissions}")
            print(f"Current user access types: {permissions.access_types}")

            # DatasetCollection
            dataset_collection = DatasetCollection(id="syn12345")
            permissions = dataset_collection.get_permissions()
            print(f"Current user permissions on DatasetCollection {dataset_collection.id}: {permissions}")
            print(f"Current user access types: {permissions.access_types}")

            # MaterializedView
            materialized_view = MaterializedView(id="syn12345")
            permissions = materialized_view.get_permissions()
            print(f"Current user permissions on MaterializedView {materialized_view.id}: {permissions}")
            print(f"Current user access types: {permissions.access_types}")

            # SubmissionView
            submission_view = SubmissionView(id="syn12345")
            permissions = submission_view.get_permissions()
            print(f"Current user permissions on SubmissionView {submission_view.id}: {permissions}")
            print(f"Current user access types: {permissions.access_types}")

            # VirtualTable
            virtual_table = VirtualTable(id="syn12345")
            permissions = virtual_table.get_permissions()
            print(f"Current user permissions on VirtualTable {virtual_table.id}: {permissions}")
            print(f"Current user access types: {permissions.access_types}")

            # To get permissions for a specific user/group, use get_acl instead:
            file_instance = File(id="syn12345")

            # Get ACL permissions for a specific user
            user_permissions = file_instance.get_acl(principal_id=12345)
            print(f"User 12345 permissions on File {file_instance.id}: {user_permissions}")

            # Get ACL permissions for the public
            public_permissions = file_instance.get_acl()  # defaults to PUBLIC users
            print(f"Public permissions on File {file_instance.id}: {public_permissions}")

            # List all ACL entries for an entity
            acl_list = file_instance.list_acl()
            print(f"All ACL entries for File {file_instance.id}: {acl_list}")
            ```
        """

        entity_id = id_of(entity)

        trace.get_current_span().set_attributes({"synapse.id": entity_id})

        url = f"/entity/{entity_id}/permissions"
        data = self.restGET(url)
        return Permissions.from_dict(data)

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `set_permissions` method on the dataclass models that inherit from `AccessControllable` mixin. "
        "Example: `from synapseclient.models import File; File(id='syn123').set_permissions(principal_id=12345, access_type=['READ'])`. "
        "To remove permissions for a specific user, use `access_type=[]` or `access_type=None`.",
    )
    def setPermissions(
        self,
        entity,
        principalId=None,
        accessType=["READ", "DOWNLOAD"],
        modify_benefactor=False,
        warn_if_inherits=True,
        overwrite=True,
    ):
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `set_permissions` method on the dataclass models that inherit from `AccessControllable` mixin instead.

        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:
            entity: An Entity or Synapse ID to modify
            principalId: Identifier of a user or group. '273948' is for all registered Synapse users
                            and '273949' is for public access. None implies public access.
            accessType: Type of permission to be granted. One or more of CREATE, READ, DOWNLOAD, UPDATE,
                            DELETE, CHANGE_PERMISSIONS
            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.

        Returns:
            An Access Control List object

        Example: Using this function (DEPRECATED)
            Grant all registered users download access

                syn.setPermissions('syn1234','273948',['READ','DOWNLOAD'])

            Grant the public view access

                syn.setPermissions('syn1234','273949',['READ'])

        Example: Migration to new method
            &nbsp;

            ```python
            from synapseclient import Synapse, AUTHENTICATED_USERS, PUBLIC
            from synapseclient.models import (
                File, Folder, Project, Table, EntityView, Dataset,
                DatasetCollection, MaterializedView, SubmissionView, VirtualTable
            )

            # Create client and login
            syn = Synapse()
            syn.login()

            # Set permissions for a File
            file_instance = File(id="syn1234")

            # Grant all registered users download access
            file_instance.set_permissions(
                principal_id=AUTHENTICATED_USERS,
                access_type=["READ", "DOWNLOAD"]
            )
            print(f"Successfully granted READ and DOWNLOAD access to all registered users on File {file_instance.id}")

            # Grant the public view access
            file_instance.set_permissions(
                principal_id=PUBLIC,
                access_type=["READ"]
            )
            print(f"Successfully granted READ access to public users on File {file_instance.id}")

            # Set permissions with additional options
            file_instance.set_permissions(
                principal_id=12345,
                access_type=["READ", "DOWNLOAD", "UPDATE"],
                modify_benefactor=True,
                warn_if_inherits=False,
                overwrite=False  # Add to existing permissions instead of overwriting
            )
            print(f"Successfully added READ, DOWNLOAD, and UPDATE access for user 12345 on File {file_instance.id}")

            # Remove permissions for a specific user/group by setting access_type to empty list
            file_instance.set_permissions(
                principal_id=12345,
                access_type=[]  # Empty list removes all permissions for this principal
            )
            print(f"Successfully removed all permissions for user 12345 on File {file_instance.id}")

            # Alternative: Remove permissions by setting access_type to None
            file_instance.set_permissions(
                principal_id=12345,
                access_type=None  # None also removes all permissions for this principal
            )
            print(f"Successfully removed all permissions for user 12345 on File {file_instance.id}")

            # Set permissions for other entity types:

            # Project
            project = Project(id="syn1234")
            project.set_permissions(
                principal_id=12345,
                access_type=["READ", "DOWNLOAD"]
            )
            print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on Project {project.id}")

            # Folder
            folder = Folder(id="syn1234")
            folder.set_permissions(
                principal_id=12345,
                access_type=["READ", "DOWNLOAD"]
            )
            print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on Folder {folder.id}")

            # Table
            table = Table(id="syn1234")
            table.set_permissions(
                principal_id=12345,
                access_type=["READ", "DOWNLOAD"]
            )
            print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on Table {table.id}")

            # EntityView
            entity_view = EntityView(id="syn1234")
            entity_view.set_permissions(
                principal_id=12345,
                access_type=["READ", "DOWNLOAD"]
            )
            print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on EntityView {entity_view.id}")

            # Dataset
            dataset = Dataset(id="syn1234")
            dataset.set_permissions(
                principal_id=12345,
                access_type=["READ", "DOWNLOAD"]
            )
            print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on Dataset {dataset.id}")

            # DatasetCollection
            dataset_collection = DatasetCollection(id="syn1234")
            dataset_collection.set_permissions(
                principal_id=12345,
                access_type=["READ", "DOWNLOAD"]
            )
            print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on DatasetCollection {dataset_collection.id}")

            # MaterializedView
            materialized_view = MaterializedView(id="syn1234")
            materialized_view.set_permissions(
                principal_id=12345,
                access_type=["READ", "DOWNLOAD"]
            )
            print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on MaterializedView {materialized_view.id}")

            # SubmissionView
            submission_view = SubmissionView(id="syn1234")
            submission_view.set_permissions(
                principal_id=12345,
                access_type=["READ", "DOWNLOAD"]
            )
            print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on SubmissionView {submission_view.id}")

            # VirtualTable
            virtual_table = VirtualTable(id="syn1234")
            virtual_table.set_permissions(
                principal_id=12345,
                access_type=["READ", "DOWNLOAD"]
            )
            print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on VirtualTable {virtual_table.id}")

            # Additional functionality available on AccessControllable models:

            # List all ACL entries for an entity
            file_instance = File(id="syn1234")
            acl_list = file_instance.list_acl()
            print(f"All ACL entries for File syn1234: {acl_list}")

            # Delete the entire ACL for an entity (makes it inherit from benefactor)
            file_instance = File(id="syn1234")
            file_instance.delete_permissions()
            print(f"Successfully deleted entire ACL for File {file_instance.id} - now inherits permissions")

            # To remove permissions for a specific user/group, use set_permissions with empty access_type
            file_instance = File(id="syn1234")
            file_instance.set_permissions(principal_id=12345, access_type=[])
            print(f"Successfully removed all permissions for user 12345 on File {file_instance.id}")

            # Use dry_run to preview what would be deleted without actually deleting
            file_instance = File(id="syn1234")
            file_instance.delete_permissions(dry_run=True)
            print("Dry run completed - showed what would be deleted")
            ```
        """
        entity_id = id_of(entity)
        trace.get_current_span().set_attributes({"synapse.id": entity_id})

        benefactor = self._getBenefactor(entity)
        if benefactor["id"] != entity_id:
            if modify_benefactor:
                entity = benefactor
            elif warn_if_inherits:
                self.logger.warning(
                    "Creating an ACL for entity %s, which formerly inherited access control from a"
                    ' benefactor entity, "%s" (%s).\n'
                    % (entity_id, benefactor["name"], benefactor["id"])
                )

        acl = self._getACL(entity)

        principalId = self._getUserbyPrincipalIdOrName(principalId)

        # Find existing permissions
        permissions_to_update = None
        for permissions in acl["resourceAccess"]:
            if (
                "principalId" in permissions
                and permissions["principalId"] == principalId
            ):
                permissions_to_update = permissions
                break

        if accessType is None or accessType == []:
            # remove permissions
            if permissions_to_update and overwrite:
                acl["resourceAccess"].remove(permissions_to_update)
        else:
            # add a 'resourceAccess' entry, if necessary
            if not permissions_to_update:
                permissions_to_update = {"accessType": [], "principalId": principalId}
                acl["resourceAccess"].append(permissions_to_update)
            if overwrite:
                permissions_to_update["accessType"] = accessType
            else:
                permissions_to_update["accessType"] = list(
                    set(permissions_to_update["accessType"]) | set(accessType)
                )
        return self._storeACL(entity, acl)

    ############################################################
    #                        Provenance                        #
    ############################################################

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `get` method on the `from synapseclient.models import Activity` class. "
        "Check the docstring for the replacement function example.",
    )
    def getProvenance(
        self,
        entity: typing.Union[str, collections.abc.Mapping, numbers.Number],
        version: int = None,
    ) -> Activity:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.models.Activity.get][] instead.

        Retrieve provenance information for a Synapse Entity.

        Arguments:
            entity:  An Entity or Synapse ID to lookup
            version: The version of the Entity to retrieve. Gets the most recent version if omitted

        Returns:
            An Activity object or raises exception if no provenance record exists

        Raises:
            SynapseHTTPError: if no provenance record exists

        Example: Using this function (DEPRECATED)
            Getting provenance for an entity

                activity = syn.getProvenance("syn123")

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Get the activity associated with the entity
            activity = Activity.get(parent_id="syn123")
            if activity:
                print(f"Activity: {activity.name}")
            else:
                print("No activity found")

            # Get the activity for a specific version
            activity = Activity.get(parent_id="syn123", parent_version_number=2)
            if activity:
                print(f"Activity: {activity.name}")
            else:
                print("No activity found")
            ```
        """
        # Get versionNumber from Entity
        if version is None and "versionNumber" in entity:
            version = entity["versionNumber"]
        entity_id = id_of(entity)
        if version:
            uri = "/entity/%s/version/%d/generatedBy" % (entity_id, version)
        else:
            uri = "/entity/%s/generatedBy" % entity_id

        trace.get_current_span().set_attributes({"synapse.id": entity_id})
        return Activity(data=self.restGET(uri))

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `store` method on the `from synapseclient.models import Activity` class. "
        "Check the docstring for the replacement function example.",
    )
    def setProvenance(
        self,
        entity: typing.Union[str, collections.abc.Mapping, numbers.Number],
        activity: Activity,
    ) -> Activity:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.models.Activity.store][] instead.

        Stores a record of the code and data used to derive a Synapse entity.

        Arguments:
            entity:   An Entity or Synapse ID to modify
            activity: A [synapseclient.activity.Activity][]

        Returns:
            An updated [synapseclient.activity.Activity][] object

        Example: Using this function (DEPRECATED)
            Setting provenance for an entity

                activity = Activity(name="Analysis", description="Data processing")
                updated_activity = syn.setProvenance("syn123", activity)

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Create an activity
            activity = Activity(
                name="Analysis",
                description="Data processing"
            )

            # Store the activity and associate it with the entity
            stored_activity = activity.store(parent="syn123")
            print(f"Stored activity: {stored_activity.name}")
            ```
        """
        # Assert that the entity was generated by a given Activity.
        activity = self._saveActivity(activity)

        entity_id = id_of(entity)
        # assert that an entity is generated by an activity
        uri = "/entity/%s/generatedBy?generatedBy=%s" % (entity_id, activity["id"])
        activity = Activity(data=self.restPUT(uri))

        trace.get_current_span().set_attributes({"synapse.id": entity_id})
        return activity

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `delete` method on the `from synapseclient.models import Activity` class. "
        "Check the docstring for the replacement function example.",
    )
    def deleteProvenance(
        self,
        entity: typing.Union[str, collections.abc.Mapping, numbers.Number],
    ) -> None:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.models.Activity.delete][] instead.

        Removes provenance information from an Entity and deletes the associated Activity.

        Arguments:
            entity: An Entity or Synapse ID to modify

        Example: Using this function (DEPRECATED)
            Deleting provenance for an entity

                syn.deleteProvenance("syn123")

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Delete the activity associated with the entity
            Activity.delete(parent="syn123")
            print("Activity deleted")
            ```
        """
        activity = self.getProvenance(entity)
        if not activity:
            return
        entity_id = id_of(entity)
        trace.get_current_span().set_attributes({"synapse.id": entity_id})

        uri = "/entity/%s/generatedBy" % entity_id
        self.restDELETE(uri)

        # If the activity is shared by more than one entity you recieve an HTTP 400 error:
        # "If you wish to delete this activity, please first delete all Entities generated by this Activity.""
        uri = "/activity/%s" % activity["id"]
        self.restDELETE(uri)

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _saveActivity(self, activity: Activity) -> Activity:
        """
        Save the Activity

        Arguments:
            activity: The Activity to be saved

        Returns:
            An Activity object
        """
        if "id" in activity:
            # We're updating provenance
            uri = "/activity/%s" % activity["id"]
            activity = Activity(data=self.restPUT(uri, json.dumps(activity)))
        else:
            activity = self.restPOST("/activity", body=json.dumps(activity))
        return activity

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `store` method on the `from synapseclient.models import Activity` class. "
        "Check the docstring for the replacement function example.",
    )
    def updateActivity(self, activity) -> Activity:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.models.Activity.store][] instead.

        Modifies an existing Activity.

        Arguments:
            activity: The Activity to be updated.

        Returns:
            An updated Activity object

        Example: Using this function (DEPRECATED)
            Updating an existing activity

                activity = syn.getProvenance("syn123")
                activity['name'] = "Updated Analysis"
                updated_activity = syn.updateActivity(activity)

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Get the existing activity by parent entity
            activity = Activity.get(parent_id="syn123")

            if activity:
                # Update the activity
                activity.name = "Updated Analysis"
                activity.description = "Updated data processing"

                # Store the updated activity
                updated_activity = activity.store()
                print(f"Updated activity: {updated_activity.name}")
            ```
        """
        if "id" not in activity:
            raise ValueError("The activity you want to update must exist on Synapse")
        trace.get_current_span().set_attributes({"synapse.id": activity["id"]})
        return self._saveActivity(activity)

    # TODO: Deprecate this method and point to new functionality - This is used from the CLI only
    def _convertProvenanceList(self, usedList: list, limitSearch: str = None) -> list:
        """
        Convert a list of Synapse IDs, URLs and local files by replacing local files with Synapse IDs

        Arguments:
            usedList:    A list of Synapse IDs, URLs and local files
            limitSearch: Limits the places in Synapse where the file is searched for.

        Returns:
            A converted list with local files being replaced with Synapse IDs
        """
        if usedList is None:
            return None
        usedList = [
            (
                self.get(target, limitSearch=limitSearch)
                if (os.path.isfile(target) if isinstance(target, str) else False)
                else target
            )
            for target in usedList
        ]
        return usedList

    ############################################################
    #                File handle service calls                 #
    ############################################################

    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/api/file_services.py::get_file_handle_for_download",
    )
    def _getFileHandleDownload(
        self, fileHandleId: str, objectId: str, objectType: str = None
    ) -> Dict[str, str]:
        """
        Gets the URL and the metadata as filehandle object for a filehandle or fileHandleId

        Arguments:
            fileHandleId:   ID of fileHandle to download
            objectId:       The ID of the object associated with the file e.g. syn234
            objectType:     Type of object associated with a file e.g. FileEntity, TableEntity

        Raises:
            SynapseFileNotFoundError: If the fileHandleId is not found in Synapse.
            SynapseError:             If the user does not have the permission to access the fileHandleId.

        Returns:
            A dictionary with keys: fileHandle, fileHandleId and preSignedURL
        """
        body = {
            "includeFileHandles": True,
            "includePreSignedURLs": True,
            "requestedFiles": [
                {
                    "fileHandleId": fileHandleId,
                    "associateObjectId": objectId,
                    "associateObjectType": objectType or "FileEntity",
                }
            ],
        }
        response = self.restPOST(
            "/fileHandle/batch", body=json.dumps(body), endpoint=self.fileHandleEndpoint
        )
        result = response["requestedFiles"][0]
        failure = result.get("failureCode")
        if failure == "NOT_FOUND":
            raise SynapseFileNotFoundError(
                "The fileHandleId %s could not be found" % fileHandleId
            )
        elif failure == "UNAUTHORIZED":
            raise SynapseError(
                "You are not authorized to access fileHandleId %s associated with the Synapse"
                " %s: %s" % (fileHandleId, objectType, objectId)
            )
        return result

    @staticmethod
    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/core/download/download_functions.py::is_retryable_download_error",
    )
    def _is_retryable_download_error(ex: Exception) -> bool:
        """
        Check if the download error is retryable

        Arguments:
            ex: An exception

        Returns:
            Boolean value indicating whether the download error is retryable
        """
        # some exceptions caught during download indicate non-recoverable situations that
        # will not be remedied by a repeated download attempt.
        return not (
            (isinstance(ex, OSError) and ex.errno == errno.ENOSPC)
            or isinstance(ex, SynapseMd5MismatchError)  # out of disk space
        )

    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/core/download/download_functions.py::download_by_file_handle",
    )
    def _downloadFileHandle(
        self,
        fileHandleId: str,
        objectId: str,
        objectType: str,
        destination: str,
        retries: int = 5,
    ) -> str:
        """
        Download a file from the given URL to the local file system.

        Arguments:
            fileHandleId: The id of the FileHandle to download
            objectId:     The id of the Synapse object that uses the FileHandle e.g. "syn123"
            objectType:   The type of the Synapse object that uses the FileHandle e.g. "FileEntity"
            destination:  The destination on local file system
            retries:      The Number of download retries attempted before throwing an exception.

        Returns:
            The path to downloaded file
        """
        os.makedirs(os.path.dirname(destination), exist_ok=True)

        while retries > 0:
            try:
                fileResult = self._getFileHandleDownload(
                    fileHandleId, objectId, objectType
                )
                fileHandle = fileResult["fileHandle"]
                concreteType = fileHandle["concreteType"]
                storageLocationId = fileHandle.get("storageLocationId")

                if concreteType == concrete_types.EXTERNAL_OBJECT_STORE_FILE_HANDLE:
                    profile = get_client_authenticated_s3_profile(
                        endpoint=fileHandle["endpointUrl"],
                        bucket=fileHandle["bucket"],
                        config_path=self.configPath,
                    )
                    downloaded_path = S3ClientWrapper.download_file(
                        fileHandle["bucket"],
                        fileHandle["endpointUrl"],
                        fileHandle["fileKey"],
                        destination,
                        profile_name=profile,
                        show_progress=not self.silent,
                    )

                elif (
                    sts_transfer.is_boto_sts_transfer_enabled(self)
                    and sts_transfer.is_storage_location_sts_enabled(
                        self, objectId, storageLocationId
                    )
                    and concreteType == concrete_types.S3_FILE_HANDLE
                ):

                    def download_fn(credentials):
                        return S3ClientWrapper.download_file(
                            fileHandle["bucketName"],
                            None,
                            fileHandle["key"],
                            destination,
                            credentials=credentials,
                            show_progress=not self.silent,
                            # pass through our synapse threading config to boto s3
                            transfer_config_kwargs={
                                "max_concurrency": self.max_threads
                            },
                        )

                    downloaded_path = sts_transfer.with_boto_sts_credentials(
                        download_fn,
                        self,
                        objectId,
                        "read_only",
                    )

                elif (
                    self.multi_threaded
                    and concreteType == concrete_types.S3_FILE_HANDLE
                    and fileHandle.get("contentSize", 0)
                    > multithread_download.SYNAPSE_DEFAULT_DOWNLOAD_PART_SIZE
                ):
                    # run the download multi threaded if the file supports it, we're configured to do so,
                    # and the file is large enough that it would be broken into parts to take advantage of
                    # multiple downloading threads. otherwise it's more efficient to run the download as a simple
                    # single threaded URL download.
                    downloaded_path = self._download_from_url_multi_threaded(
                        fileHandleId,
                        objectId,
                        objectType,
                        destination,
                        expected_md5=fileHandle.get("contentMd5"),
                    )

                else:
                    downloaded_path = self._download_from_URL(
                        fileResult["preSignedURL"],
                        destination,
                        fileHandle["id"],
                        expected_md5=fileHandle.get("contentMd5"),
                    )
                self.cache.add(fileHandle["id"], downloaded_path)
                return downloaded_path

            except Exception as ex:
                if not self._is_retryable_download_error(ex):
                    raise

                exc_info = sys.exc_info()
                ex.progress = 0 if not hasattr(ex, "progress") else ex.progress
                self.logger.debug(
                    "\nRetrying download on error: [%s] after progressing %i bytes"
                    % (exc_info[0], ex.progress),
                    exc_info=True,
                )  # this will include stack trace
                if ex.progress == 0:  # No progress was made reduce remaining retries.
                    retries -= 1
                if retries <= 0:
                    # Re-raise exception
                    raise

        raise Exception("should not reach this line")

    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/core/download/download_functions.py::download_from_url_multi_threaded",
    )
    def _download_from_url_multi_threaded(
        self,
        file_handle_id: str,
        object_id: str,
        object_type: str,
        destination: str,
        *,
        expected_md5: str = None,
    ) -> str:
        """
        Download a file from the given URL using multiple threads.

        Arguments:
            file_handle_id: The id of the FileHandle to download
            object_id:      The id of the Synapse object that uses the FileHandle e.g. "syn123"
            object_type:    The type of the Synapse object that uses the FileHandle e.g. "FileEntity"
            destination:    The destination on local file system
            expected_md5:   The expected MD5
        Raises:
            SynapseMd5MismatchError: If the actual MD5 does not match expected MD5.

        Returns:
            The path to downloaded file
        """
        destination = os.path.abspath(destination)
        temp_destination = utils.temp_download_filename(destination, file_handle_id)

        request = multithread_download.DownloadRequest(
            file_handle_id=int(file_handle_id),
            object_id=object_id,
            object_type=object_type,
            path=temp_destination,
            debug=self.debug,
        )

        multithread_download.download_file(self, request)

        if (
            expected_md5
        ):  # if md5 not set (should be the case for all except http download)
            actual_md5 = utils.md5_for_file(temp_destination).hexdigest()
            # check md5 if given
            if actual_md5 != expected_md5:
                try:
                    os.remove(temp_destination)
                except FileNotFoundError:
                    # file already does not exist. nothing to do
                    pass
                raise SynapseMd5MismatchError(
                    "Downloaded file {filename}'s md5 {md5} does not match expected MD5 of"
                    " {expected_md5}".format(
                        filename=temp_destination,
                        md5=actual_md5,
                        expected_md5=expected_md5,
                    )
                )
        # once download completed, rename to desired destination
        shutil.move(temp_destination, destination)

        return destination

    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/core/download/download_functions.py::is_synapse_uri",
    )
    def _is_synapse_uri(self, uri: str) -> bool:
        """
        Check whether the given uri is hosted at the configured Synapse repo endpoint

        Arguments:
            uri: A given uri

        Returns:
            A boolean value indicating whether the given uri is hosted at the configured Synapse repo endpoint
        """
        uri_domain = urllib_urlparse.urlparse(uri).netloc
        synapse_repo_domain = urllib_urlparse.urlparse(self.repoEndpoint).netloc
        return uri_domain.lower() == synapse_repo_domain.lower()

    @deprecated(
        version="4.4.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient/core/download/download_functions.py::download_from_url",
    )
    def _download_from_URL(
        self,
        url: str,
        destination: str,
        fileHandleId: Optional[str] = None,
        expected_md5: Optional[str] = None,
    ) -> str:
        """
        Download a file from the given URL to the local file system.

        Arguments:
            url:           The source of download
            destination:   The destination on local file system
            fileHandleId:  Optional. If given, the file will be given a temporary name that includes the file
                                    handle id which allows resuming partial downloads of the same file from previous
                                    sessions
            expected_md5:  Optional. If given, check that the MD5 of the downloaded file matches the expected MD5

        Raises:
            IOError:                 If the local file does not exist.
            SynapseError:            If fail to download the file.
            SynapseHTTPError:        If there are too many redirects.
            SynapseMd5MismatchError: If the actual MD5 does not match expected MD5.

        Returns:
            The path to downloaded file
        """
        destination = os.path.abspath(destination)
        actual_md5 = None
        redirect_count = 0
        delete_on_md5_mismatch = True
        self.logger.debug(f"Downloading from {url} to {destination}")
        while redirect_count < REDIRECT_LIMIT:
            redirect_count += 1
            scheme = urllib_urlparse.urlparse(url).scheme
            if scheme == "file":
                delete_on_md5_mismatch = False
                destination = utils.file_url_to_path(url, verify_exists=True)
                if destination is None:
                    raise IOError("Local file (%s) does not exist." % url)
                break
            elif scheme == "sftp":
                username, password = self._getUserCredentials(url)
                destination = SFTPWrapper.download_file(
                    url, destination, username, password, show_progress=not self.silent
                )
                break
            elif scheme == "ftp":
                transfer_start_time = time.time()

                def _ftp_report_hook(
                    block_number: int, read_size: int, total_size: int
                ) -> None:
                    show_progress = not self.silent
                    if show_progress:
                        self._print_transfer_progress(
                            transferred=block_number * read_size,
                            toBeTransferred=total_size,
                            prefix="Downloading ",
                            postfix=os.path.basename(destination),
                            dt=time.time() - transfer_start_time,
                        )

                urllib_request.urlretrieve(
                    url=url, filename=destination, reporthook=_ftp_report_hook
                )
                break
            elif scheme == "http" or scheme == "https":
                # if a partial download exists with the temporary name,
                temp_destination = utils.temp_download_filename(
                    destination, fileHandleId
                )
                range_header = (
                    {
                        "Range": "bytes={start}-".format(
                            start=os.path.getsize(temp_destination)
                        )
                    }
                    if os.path.exists(temp_destination)
                    else {}
                )

                # pass along synapse auth credentials only if downloading directly from synapse
                auth = self.credentials if self._is_synapse_uri(url) else None
                response = with_retry(
                    lambda: self._requests_session.get(
                        url,
                        headers=self._generate_headers(range_header),
                        stream=True,
                        allow_redirects=False,
                        auth=auth,
                    ),
                    verbose=self.debug,
                    **STANDARD_RETRY_PARAMS,
                )
                try:
                    exceptions._raise_for_status(response, verbose=self.debug)
                except SynapseHTTPError as err:
                    if err.response.status_code == 404:
                        raise SynapseError("Could not download the file at %s" % url)
                    elif (
                        err.response.status_code == 416
                    ):  # Requested Range Not Statisfiable
                        # this is a weird error when the client already finished downloading but the loop continues
                        # When this exception occurs, the range we request is guaranteed to be >= file size so we
                        # assume that the file has been fully downloaded, rename it to destination file
                        # and break out of the loop to perform the MD5 check.
                        # If it fails the user can retry with another download.
                        shutil.move(temp_destination, destination)
                        break
                    raise

                # handle redirects
                if response.status_code in [301, 302, 303, 307, 308]:
                    url = response.headers["location"]
                    # don't break, loop again
                else:
                    # get filename from content-disposition, if we don't have it already
                    if os.path.isdir(destination):
                        filename = utils.extract_filename(
                            content_disposition_header=response.headers.get(
                                "content-disposition", None
                            ),
                            default_filename=utils.guess_file_name(url),
                        )
                        destination = os.path.join(destination, filename)
                    # Stream the file to disk
                    if "content-length" in response.headers:
                        toBeTransferred = float(response.headers["content-length"])
                    else:
                        toBeTransferred = -1
                    transferred = 0

                    # Servers that respect the Range header return 206 Partial Content
                    if response.status_code == 206:
                        mode = "ab"
                        previouslyTransferred = os.path.getsize(temp_destination)
                        toBeTransferred += previouslyTransferred
                        transferred += previouslyTransferred
                        sig = utils.md5_for_file(temp_destination)
                    else:
                        mode = "wb"
                        previouslyTransferred = 0
                        sig = hashlib.new("md5", usedforsecurity=False)  # nosec

                    try:
                        with open(temp_destination, mode) as fd:
                            t0 = time.time()
                            for nChunks, chunk in enumerate(
                                response.iter_content(FILE_BUFFER_SIZE)
                            ):
                                fd.write(chunk)
                                sig.update(chunk)

                                # the 'content-length' header gives the total number of bytes that will be transferred
                                # to us len(chunk) cannot be used to track progress because iter_content automatically
                                # decodes the chunks if the response body is encoded so the len(chunk) could be
                                # different from the total number of bytes we've read read from the response body
                                # response.raw.tell() is the total number of response body bytes transferred over the
                                # wire so far
                                transferred = (
                                    response.raw.tell() + previouslyTransferred
                                )
                                self._print_transfer_progress(
                                    transferred,
                                    toBeTransferred,
                                    "Downloading ",
                                    os.path.basename(destination),
                                    dt=time.time() - t0,
                                )
                    except (
                        Exception
                    ) as ex:  # We will add a progress parameter then push it back to retry.
                        ex.progress = transferred - previouslyTransferred
                        raise

                    # verify that the file was completely downloaded and retry if it is not complete
                    if toBeTransferred > 0 and transferred < toBeTransferred:
                        self.logger.warning(
                            "\nRetrying download because the connection ended early.\n"
                        )
                        continue

                    actual_md5 = sig.hexdigest()
                    # rename to final destination
                    shutil.move(temp_destination, destination)
                    break
            else:
                self.logger.error("Unable to download URLs of type %s" % scheme)
                return None

        else:  # didn't break out of loop
            raise SynapseHTTPError("Too many redirects")

        if (
            actual_md5 is None
        ):  # if md5 not set (should be the case for all except http download)
            actual_md5 = utils.md5_for_file(destination).hexdigest()

        # check md5 if given
        if expected_md5 and actual_md5 != expected_md5:
            if delete_on_md5_mismatch and os.path.exists(destination):
                os.remove(destination)
            raise SynapseMd5MismatchError(
                "Downloaded file {filename}'s md5 {md5} does not match expected MD5 of"
                " {expected_md5}".format(
                    filename=destination, md5=actual_md5, expected_md5=expected_md5
                )
            )

        return destination

    def _createExternalFileHandle(
        self,
        externalURL: str,
        mimetype: str = None,
        md5: str = None,
        fileSize: int = None,
    ) -> Dict[str, Union[str, int]]:
        """
        Create a new FileHandle representing an external URL.

        Arguments:
            externalURL: An external URL
            mimetype:    The Mimetype of the file, if known.
            md5:         The file's content MD5.
            fileSize:    The size of the file in bytes.

        Returns:
            A FileHandle for files that are stored externally.
        """
        fileName = externalURL.split("/")[-1]
        externalURL = utils.as_url(externalURL)
        fileHandle = {
            "concreteType": concrete_types.EXTERNAL_FILE_HANDLE,
            "fileName": fileName,
            "externalURL": externalURL,
            "contentMd5": md5,
            "contentSize": fileSize,
        }
        if mimetype is None:
            mimetype, enc = mimetypes.guess_type(externalURL, strict=False)
        if mimetype is not None:
            fileHandle["contentType"] = mimetype
        return self.restPOST(
            "/externalFileHandle", json.dumps(fileHandle), self.fileHandleEndpoint
        )

    def _createExternalObjectStoreFileHandle(
        self,
        s3_file_key,
        file_path: str,
        storage_location_id: int,
        mimetype: str = None,
        md5: str = None,
    ) -> Dict[str, Union[str, int]]:
        """
        Create a new FileHandle representing an external object.

        Arguments:
            s3_file_key:         S3 key of the uploaded object
            file_path:           The local path of the uploaded file
            storage_location_id: The optional storage location descriptor
            mimetype:            The Mimetype of the file, if known.
            md5:                 The file's content MD5, if known.

        Returns:
            A FileHandle for objects that are stored externally.
        """
        if mimetype is None:
            mimetype, _ = mimetypes.guess_type(file_path, strict=False)
        file_handle = {
            "concreteType": concrete_types.EXTERNAL_OBJECT_STORE_FILE_HANDLE,
            "fileKey": s3_file_key,
            "fileName": os.path.basename(file_path),
            "contentMd5": md5 or utils.md5_for_file(file_path).hexdigest(),
            "contentSize": os.stat(file_path).st_size,
            "storageLocationId": storage_location_id,
            "contentType": mimetype,
        }

        return self.restPOST(
            "/externalFileHandle", json.dumps(file_handle), self.fileHandleEndpoint
        )

    @deprecated(
        version="4.12.0",
        reason="To be removed in 5.0.0. "
        "Use `synapseclient.api.post_external_s3_file_handle()` instead.",
    )
    def create_external_s3_file_handle(
        self,
        bucket_name,
        s3_file_key,
        file_path,
        *,
        parent=None,
        storage_location_id=None,
        mimetype=None,
        md5: str = None,
    ):
        """
        Create an external S3 file handle for e.g. a file that has been uploaded directly to
        an external S3 storage location.

        Arguments:
            bucket_name: Name of the S3 bucket
            s3_file_key: S3 key of the uploaded object
            file_path: Local path of the uploaded file
            parent: Parent entity to create the file handle in, the file handle will be created
                    in the default storage location of the parent. Mutually exclusive with
                    storage_location_id
            storage_location_id: Explicit storage location id to create the file handle in, mutually exclusive
                    with parent
            mimetype: Mimetype of the file, if known
            md5: MD5 of the file, if known

        Raises:
            ValueError: If neither parent nor storage_location_id is specified, or if both are specified.
        """

        if storage_location_id:
            if parent:
                raise ValueError("Pass parent or storage_location_id, not both")
        elif not parent:
            raise ValueError("One of parent or storage_location_id is required")
        else:
            upload_destination = self._getDefaultUploadDestination(parent)
            storage_location_id = upload_destination["storageLocationId"]

        if mimetype is None:
            mimetype, _ = mimetypes.guess_type(file_path, strict=False)

        file_handle = {
            "concreteType": concrete_types.S3_FILE_HANDLE,
            "key": s3_file_key,
            "bucketName": bucket_name,
            "fileName": os.path.basename(file_path),
            "contentMd5": md5 or utils.md5_for_file(file_path).hexdigest(),
            "contentSize": os.stat(file_path).st_size,
            "storageLocationId": storage_location_id,
            "contentType": mimetype,
        }

        return self.restPOST(
            "/externalFileHandle/s3",
            json.dumps(file_handle),
            endpoint=self.fileHandleEndpoint,
        )

    def _get_file_handle_as_creator(
        self, fileHandle: Dict[str, Union[str, int]]
    ) -> Dict[str, Union[str, int]]:
        """
        Retrieve a fileHandle from the fileHandle service.
        Note: You must be the creator of the filehandle to use this method. Otherwise, an 403-Forbidden error will be raised.

        Arguments:
            fileHandle: A fileHandle

        Returns:
            A fileHandle retrieved from the fileHandle service.
        """
        uri = "/fileHandle/%s" % (id_of(fileHandle),)
        return self.restGET(uri, endpoint=self.fileHandleEndpoint)

    def _deleteFileHandle(self, fileHandle: Dict[str, Union[str, int]]) -> None:
        """
        Delete the given file handle.

        Note: Only the user that created the FileHandle can delete it. Also, a FileHandle cannot be deleted if it is
        associated with a FileEntity or WikiPage.

        Arguments:
            fileHandle: A fileHandle
        """
        uri = "/fileHandle/%s" % (id_of(fileHandle),)
        self.restDELETE(uri, endpoint=self.fileHandleEndpoint)
        return fileHandle

    ############################################################
    #                    SFTP                                  #
    ############################################################

    def _getDefaultUploadDestination(self, parent_entity):
        return self.restGET(
            "/entity/%s/uploadDestination" % id_of(parent_entity),
            endpoint=self.fileHandleEndpoint,
        )

    def _getUserCredentials(
        self, url: str, username: str = None, password: str = None
    ) -> Tuple[str, str]:
        """
        Get user credentials for a specified URL by either looking in the configFile or querying the user.

        Arguments:
            username: The username on server (optionally specified).
            password: The password for authentication on the server (optionally specified).

        Returns:
            A tuple of username, password.
        """
        # Get authentication information from configFile
        parsedURL = urllib_urlparse.urlparse(url)
        baseURL = parsedURL.scheme + "://" + parsedURL.hostname

        config = get_config_file(self.configPath)
        if username is None and config.has_option(baseURL, "username"):
            username = config.get(baseURL, "username")
        if password is None and config.has_option(baseURL, "password"):
            password = config.get(baseURL, "password")
        # If I still don't have a username and password prompt for it
        if username is None:
            username = getpass.getuser()  # Default to login name
            # Note that if we hit the following line from within nosetests in
            # Python 3, we get "TypeError: bad argument type for built-in operation".
            # Luckily, this case isn't covered in our test suite!
            user = input("Username for %s (%s):" % (baseURL, username))
            username = username if user == "" else user
        if password is None:
            password = getpass.getpass("Password for %s:" % baseURL)
        return username, password

    ############################################
    # Project/Folder storage location settings #
    ############################################

    @deprecated(
        version="4.12.0",
        reason="To be removed in 5.0.0. "
        "Use `StorageLocation(...).store()` from synapseclient.models instead.",
    )
    def createStorageLocationSetting(self, storage_type, **kwargs):
        """
        Creates an IMMUTABLE storage location based on the specified type.

        For each storage_type, the following kwargs should be specified:

        **ExternalObjectStorage**: (S3-like (e.g. AWS S3 or Openstack) bucket not accessed by Synapse)

        - `endpointUrl`: endpoint URL of the S3 service (for example: 'https://s3.amazonaws.com')
        - `bucket`: the name of the bucket to use

        **ExternalS3Storage**: (Amazon S3 bucket accessed by Synapse)

        - `bucket`: the name of the bucket to use

        **ExternalStorage**: (SFTP or FTP storage location not accessed by Synapse)

        - `url`: the base URL for uploading to the external destination
        - `supportsSubfolders(optional)`: does the destination support creating subfolders under the base url
            (default: false)

        **ProxyStorage**: (a proxy server that controls access to a storage)

        - `secretKey`: The encryption key used to sign all pre-signed URLs used to communicate with the proxy.
        - `proxyUrl`: The HTTPS URL of the proxy used for upload and download.

        Arguments:
            storage_type: The type of the StorageLocationSetting to create
            banner: (Optional) The optional banner to show every time a file is uploaded
            description: (Optional) The description to show the user when the user has to choose which upload destination to use
            kwargs: fields necessary for creation of the specified storage_type

        Returns:
            A dict of the created StorageLocationSetting
        """
        upload_type_dict = {
            "ExternalObjectStorage": "S3",
            "ExternalS3Storage": "S3",
            "ExternalStorage": "SFTP",
            "ProxyStorage": "PROXYLOCAL",
        }

        if storage_type not in upload_type_dict:
            raise ValueError("Unknown storage_type: %s", storage_type)

        # ProxyStorageLocationSettings has an extra 's' at the end >:(
        kwargs["concreteType"] = (
            "org.sagebionetworks.repo.model.project."
            + storage_type
            + "LocationSetting"
            + ("s" if storage_type == "ProxyStorage" else "")
        )
        kwargs["uploadType"] = upload_type_dict[storage_type]

        return self.restPOST("/storageLocation", body=json.dumps(kwargs))

    @deprecated(
        version="4.12.0",
        reason="To be removed in 5.0.0. "
        "Use `StorageLocation(storage_location_id=id).get()` from "
        "synapseclient.models instead.",
    )
    def getMyStorageLocationSetting(self, storage_location_id):
        """
        Get a StorageLocationSetting by its id.

        Arguments:
            storage_location_id: id of the StorageLocationSetting to retrieve.
                                    The corresponding StorageLocationSetting must have been created by this user.

        Returns:
            A dict describing the StorageLocationSetting retrieved by its id
        """
        return self.restGET("/storageLocation/%s" % storage_location_id)

    @deprecated(
        version="4.12.0",
        reason="To be removed in 5.0.0. "
        "Use `Folder(id=...).set_storage_location(...)` or "
        "`Project(id=...).set_storage_location(...)` from synapseclient.models instead.",
    )
    def setStorageLocation(self, entity, storage_location_id):
        """
        Sets the storage location for a Project or Folder

        Arguments:
            entity: A Project or Folder to which the StorageLocationSetting is set
            storage_location_id: A StorageLocation id or a list of StorageLocation ids. Pass in None for the default
                                    Synapse storage.

        Returns:
            The created or updated settings as a dict.
        """
        if storage_location_id is None:
            storage_location_id = DEFAULT_STORAGE_LOCATION_ID
        locations = (
            storage_location_id
            if isinstance(storage_location_id, list)
            else [storage_location_id]
        )

        existing_setting = self.getProjectSetting(entity, "upload")
        if existing_setting is not None:
            existing_setting["locations"] = locations
            self.restPUT("/projectSettings", body=json.dumps(existing_setting))
            return self.getProjectSetting(entity, "upload")
        else:
            project_destination = {
                "concreteType": "org.sagebionetworks.repo.model.project.UploadDestinationListSetting",
                "settingsType": "upload",
                "locations": locations,
                "projectId": id_of(entity),
            }

            return self.restPOST(
                "/projectSettings", body=json.dumps(project_destination)
            )

    @deprecated(
        version="4.12.0",
        reason="To be removed in 5.0.0. "
        "Use `Folder(id=...).get_project_setting(...)` or "
        "`Project(id=...).get_project_setting(...)` from synapseclient.models instead.",
    )
    def getProjectSetting(self, project, setting_type):
        """
        Gets the ProjectSetting for a project.

        Arguments:
            project: Project entity or its id as a string
            setting_type: Type of setting. Choose from:

                - `upload`
                - `external_sync`
                - `requester_pays`

        Returns:
            The ProjectSetting as a dict or None if no settings of the specified type exist.
        """
        if setting_type not in {"upload", "external_sync", "requester_pays"}:
            raise ValueError("Invalid project_type: %s" % setting_type)

        response = self.restGET(
            "/projectSettings/{projectId}/type/{type}".format(
                projectId=id_of(project), type=setting_type
            )
        )
        return (
            response if response else None
        )  # if no project setting, a empty string is returned as the response

    @deprecated(
        version="4.12.0",
        reason="To be removed in 5.0.0. "
        "Use `Folder(id=...).get_sts_storage_token(...)` or "
        "`Project(id=...).get_sts_storage_token(...)` from synapseclient.models instead.",
    )
    def get_sts_storage_token(
        self, entity, permission, *, output_format="json", min_remaining_life=None
    ):
        """Get STS credentials for the given entity_id and permission, outputting it in the given format

        Arguments:
            entity: The entity or entity id whose credentials are being returned
            permission: One of:

                - `read_only`
                - `read_write`

            output_format: One of:

                - `json`: the dictionary returned from the Synapse STS API including expiration
                - `boto`: a dictionary compatible with a boto session (aws_access_key_id, etc)
                - `shell`: output commands for exporting credentials appropriate for the detected shell
                - `bash`: output commands for exporting credentials into a bash shell
                - `cmd`: output commands for exporting credentials into a windows cmd shell
                - `powershell`: output commands for exporting credentials into a windows powershell

            min_remaining_life: The minimum allowable remaining life on a cached token to return. If a cached token
                                has left than this amount of time left a fresh token will be fetched
        """
        return sts_transfer.get_sts_credentials(
            self,
            id_of(entity),
            permission,
            output_format=output_format,
            min_remaining_life=min_remaining_life,
        )

    @deprecated(
        version="4.12.0",
        reason="To be removed in 5.0.0. "
        "Use the `synapseclient.models.StorageLocation` model and its `store()` "
        "method instead. To also create a folder and apply the storage location "
        "as a project setting, use `Folder` together with "
        "`set_storage_location()` on the project/folder.",
    )
    def create_s3_storage_location(
        self,
        *,
        parent=None,
        folder_name=None,
        folder=None,
        bucket_name=None,
        base_key=None,
        sts_enabled=False,
    ) -> Tuple[Folder, Dict[str, str], Dict[str, str]]:
        """
        Create a storage location in the given parent, either in the given folder or by creating a new
        folder in that parent with the given name. This will both create a StorageLocationSetting,
        and a ProjectSetting together, optionally creating a new folder in which to locate it,
        and optionally enabling this storage location for access via STS. If enabling an existing folder for STS,
        it must be empty.

        Deprecated: To be removed in 5.0.0. Use the synapseclient.models.StorageLocation
        model and its store() method to create the storage location, and
        set_storage_location() on a Project or Folder to apply it as a project setting.

        Arguments:
            parent: The parent in which to locate the storage location (mutually exclusive with folder)
            folder_name: The name of a new folder to create (mutually exclusive with folder)
            folder: The existing folder in which to create the storage location (mutually exclusive with folder_name)
            bucket_name: The name of an S3 bucket, if this is an external storage location,
                            if None will use Synapse S3 storage
            base_key: The base key of within the bucket, None to use the bucket root,
                            only applicable if bucket_name is passed
            sts_enabled: Whether this storage location should be STS enabled

        Returns:
            A 3-tuple of the synapse Folder, a the storage location setting, and the project setting dictionaries.

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # folder, storage_setting, project_setting = syn.create_s3_storage_location(
            #     parent="syn123",
            #     folder_name="my-external-storage",
            #     bucket_name="my-bucket",
            # )

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import Folder, StorageLocation, StorageLocationType

            syn = Synapse()
            syn.login()

            # Create the storage location backed by your own S3 bucket
            storage = StorageLocation(
                storage_type=StorageLocationType.EXTERNAL_S3,
                bucket="my-bucket",
            ).store()

            # Create a folder to hold the externally stored files
            folder = Folder(name="my-external-storage", parent_id="syn123").store()

            # Apply the storage location as the folder's upload destination
            folder.set_storage_location(storage_location_id=storage.storage_location_id)
            ```
        """
        return wrap_async_to_sync(
            self.create_s3_storage_location_async(
                parent=parent,
                folder_name=folder_name,
                folder=folder,
                bucket_name=bucket_name,
                base_key=base_key,
                sts_enabled=sts_enabled,
            )
        )

    @deprecated(
        version="4.12.0",
        reason="To be removed in 5.0.0. "
        "Use the `synapseclient.models.StorageLocation` model and its "
        "`store_async()` method instead. To also create a folder and apply the "
        "storage location as a project setting, use `Folder` together with "
        "`set_storage_location_async()` on the project/folder.",
    )
    async def create_s3_storage_location_async(
        self,
        *,
        parent=None,
        folder_name=None,
        folder=None,
        bucket_name=None,
        base_key=None,
        sts_enabled=False,
    ) -> Tuple[Folder, Dict[str, str], Dict[str, str]]:
        """
        async version of create_s3_storage_location

        Deprecated: To be removed in 5.0.0. Use the synapseclient.models.StorageLocation
        model and its store_async() method to create the storage location, and
        set_storage_location_async() on a Project or Folder to apply it as a project
        setting.
        """
        if folder_name and parent:
            if folder:
                raise ValueError(
                    "folder and  folder_name are mutually exclusive, only one should be passed"
                )

            folder = await self.store_async(Folder(name=folder_name, parent=parent))

        elif not folder:
            raise ValueError("either folder or folder_name should be required")

        storage_location_kwargs = {
            "uploadType": "S3",
            "stsEnabled": sts_enabled,
        }

        if bucket_name:
            storage_location_kwargs["concreteType"] = (
                concrete_types.EXTERNAL_S3_STORAGE_LOCATION_SETTING
            )
            storage_location_kwargs["bucket"] = bucket_name
            if base_key:
                storage_location_kwargs["baseKey"] = base_key
        else:
            storage_location_kwargs["concreteType"] = (
                concrete_types.SYNAPSE_S3_STORAGE_LOCATION_SETTING
            )

        storage_location_setting = self.restPOST(
            "/storageLocation", json.dumps(storage_location_kwargs)
        )

        storage_location_id = storage_location_setting["storageLocationId"]
        project_setting = self.setStorageLocation(
            folder,
            storage_location_id,
        )

        return folder, storage_location_setting, project_setting

    ############################################################
    #                   CRUD for Evaluations                   #
    ############################################################

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use the `synapseclient.models.Evaluation` model instead, e.g. "
        "`Evaluation(id=...).get()`.",
    )
    def getEvaluation(self, id):
        """
        Gets an Evaluation object from Synapse.

        Arguments:
            id: The ID of the [synapseclient.evaluation.Evaluation][] to return.

        Returns:
            An [synapseclient.evaluation.Evaluation][] object

        Example: Using this function
            Creating an Evaluation instance

                evaluation = syn.getEvaluation(2005090)

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # evaluation = syn.getEvaluation(2005090)

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import Evaluation

            syn = Synapse()
            syn.login()

            evaluation = Evaluation(id="2005090").get()
            ```
        """

        evaluation_id = id_of(id)
        uri = Evaluation.getURI(evaluation_id)
        return Evaluation(**self.restGET(uri))

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use the `synapseclient.models.Evaluation` model instead, e.g. "
        "`Evaluation(name=...).get()`.",
    )
    def getEvaluationByName(self, name):
        """
        Gets an Evaluation object from Synapse.

        Arguments:
            Name: The name of the [synapseclient.evaluation.Evaluation][] to return.

        Returns:
            An [synapseclient.evaluation.Evaluation][] object

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # evaluation = syn.getEvaluationByName("My Evaluation")

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import Evaluation

            syn = Synapse()
            syn.login()

            evaluation = Evaluation(name="My Evaluation").get()
            ```
        """
        uri = Evaluation.getByNameURI(name)
        return Evaluation(**self.restGET(uri))

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use `synapseclient.models.Evaluation.get_evaluations_by_project()` instead.",
    )
    def getEvaluationByContentSource(self, entity):
        """
        Returns a generator over evaluations that derive their content from the given entity

        Arguments:
            entity: The [synapseclient.entity.Project][] whose Evaluations are to be fetched.

        Yields:
            A generator over [synapseclient.evaluation.Evaluation][] objects for the given [synapseclient.entity.Project][].

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # evaluations = syn.getEvaluationByContentSource("syn123")

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import Evaluation

            syn = Synapse()
            syn.login()

            evaluations = Evaluation.get_evaluations_by_project(project_id="syn123")
            ```
        """

        entityId = id_of(entity)
        url = "/entity/%s/evaluation" % entityId

        for result in self._GET_paginated(url):
            yield Evaluation(**result)

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _findTeam(self, name: str) -> typing.Iterator[Team]:
        """
        Retrieve a Teams matching the supplied name fragment

        Arguments:
            name: A team name

        Yields:
            A generator that yields objects of type [Team][synapseclient.team.Team]
        """
        for result in self._GET_paginated("/teams?fragment=%s" % name):
            yield Team(**result)

    def _find_teams_for_principal(self, principal_id: str) -> typing.Iterator[Team]:
        """
        Retrieve a list of teams for the matching principal ID. If the principalId that is passed in is a team itself,
        or not found, this will return a generator that yields no results.

        Arguments:
            principal_id: Identifier of a user or group.

        Yields:
            A generator that yields objects of type [Team][synapseclient.team.Team]
        """
        for result in self._GET_paginated(f"/user/{principal_id}/team"):
            yield Team(**result)

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `create` method on the `from synapseclient.models import Team` class. "
        "Check the docstring for the replacement function example.",
    )
    def create_team(
        self,
        name: str,
        description: str = None,
        icon: str = None,
        can_public_join: bool = False,
        can_request_membership: bool = True,
    ) -> Team:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.models.Team.create][] instead.

        Creates a new team.

        Arguments:
            name: The name of the team to create.
            description: A description of the team.
            icon: The FileHandleID of the icon to be used for the team.
            canPublicJoin: Whether the team can be joined by anyone. Defaults to False.
            canRequestMembership: Whether the team can request membership. Defaults to True.

        Returns:
            An object of type [synapseclient.team.Team][]

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Create a new team
            new_team = Team(
                name="My Team",
                description="A sample team",
                can_public_join=False,
                can_request_membership=True
            )
            created_team = new_team.create()
            print(f"Created team: {created_team.name}")
            ```
        """
        request_body = {
            "name": name,
            "description": description,
            "icon": icon,
            "canPublicJoin": can_public_join,
            "canRequestMembership": can_request_membership,
        }
        return Team(
            **self.restPOST(
                "/team",
                json.dumps(request_body),
            )
        )

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `delete` method on the `from synapseclient.models import Team` class. "
        "Check the docstring for the replacement function example.",
    )
    def delete_team(self, id: int) -> None:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.models.Team.delete][] instead.

        Deletes a team.

        Arguments:
            id: The ID of the team to delete.

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Delete a team
            team = Team(id=12345)
            team.delete()
            ```

        """
        return self.restDELETE(f"/team/{id}")

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `get`, `from_id`, and `from_name` methods on the `from synapseclient.models import Team` class. "
        "Check the docstring for the replacement function example.",
    )
    def getTeam(self, id: Union[int, str]) -> Team:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.models.Team.from_id][] or [synapseclient.models.Team.from_name][] instead.

        Finds a team with a given ID or name.

        Arguments:
            id: The ID or name of the team or a Team object to retrieve.

        Returns:
            An object of type [synapseclient.team.Team][]

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Get a team by ID
            team_by_id = Team.from_id(id=12345)
            print(f"Team by ID: {team_by_id.name}")

            # Get a team by name
            team_by_name = Team.from_name(name="My Team")
            print(f"Team by name: {team_by_name.name}")
            ```
        """
        # Retrieves team id
        teamid = id_of(id)
        try:
            int(teamid)
        except (TypeError, ValueError):
            if isinstance(id, str):
                for team in self._findTeam(id):
                    if team.name == id:
                        teamid = team.id
                        break
                else:
                    raise ValueError('Can\'t find team "{}"'.format(teamid))
            else:
                raise ValueError('Can\'t find team "{}"'.format(teamid))
        return Team(**self.restGET("/team/%s" % teamid))

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `members` method on the `from synapseclient.models import Team` class. "
        "Check the docstring for the replacement function example.",
    )
    def getTeamMembers(
        self, team: Union[Team, int, str]
    ) -> typing.Generator[TeamMember, None, None]:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.models.Team.members][] instead.

        Lists the members of the given team.

        Arguments:
            team: A [synapseclient.team.Team][] object or a team's ID.

        Yields:
            A generator over [synapseclient.team.TeamMember][] objects.

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Get team members
            team = Team.from_id(id=12345)
            members = team.members()
            for member in members:
                print(f"Member: {member.member.user_name}")
            ```

        """
        for result in self._GET_paginated("/teamMembers/{id}".format(id=id_of(team))):
            yield TeamMember(**result)

    def _get_docker_digest(
        self, entity: Union[Entity, str], docker_tag: str = "latest"
    ) -> str:
        """
        Get matching Docker sha-digest of a DockerRepository given a Docker tag

        Arguments:
            entity:      Synapse ID or Entity of Docker repository
            docker_tag:  Docker tag

        Returns:
            Docker digest matching Docker tag
        """
        entityid = id_of(entity)
        uri = "/entity/{entityId}/dockerTag".format(entityId=entityid)

        docker_commits = self._GET_paginated(uri)
        docker_digest = None
        for commit in docker_commits:
            if docker_tag == commit["tag"]:
                docker_digest = commit["digest"]
        if docker_digest is None:
            raise ValueError(
                "Docker tag {docker_tag} not found.  Please specify a "
                "docker tag that exists. 'latest' is used as "
                "default.".format(docker_tag=docker_tag)
            )
        return docker_digest

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `open_invitations` method on the `from synapseclient.models import Team` class. "
        "Check the docstring for the replacement function example.",
    )
    def get_team_open_invitations(
        self, team: Union[Team, int, str]
    ) -> typing.Generator[dict, None, None]:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.models.Team.open_invitations][] instead.

        Retrieve the open requests submitted to a Team
        <https://rest-docs.synapse.org/rest/GET/team/id/openInvitation.html>

        Arguments:
            team: A [synapseclient.team.Team][] object or a team's ID.

        Yields:
            Generator of MembershipRequest dictionaries

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Get open invitations for a team
            team = Team.from_id(id=12345)
            invitations = team.open_invitations()
            for invitation in invitations:
                print(f"Invitation: {invitation}")
            ```
        """
        teamid = id_of(team)
        request = "/team/{team}/openInvitation".format(team=teamid)
        open_requests = self._GET_paginated(request)
        return open_requests

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Use the `get_user_membership_status` method on the `Team` class from `synapseclient.models` instead. "
        "Check the docstring for the replacement function example.",
    )
    def get_membership_status(self, userid, team):
        """Retrieve a user's Team Membership Status bundle.
        <https://rest-docs.synapse.org/rest/GET/team/id/member/principalId/membershipStatus.html>

        Arguments:
            user: Synapse user ID
            team: A [synapseclient.team.Team][] object or a team's ID.

        Returns:
            dict of TeamMembershipStatus

        Example: Using this function (DEPRECATED)
            &nbsp;
            Getting a user's membership status for a team

            ```python
            from synapseclient import Synapse

            # Login to Synapse
            syn = Synapse()
            syn.login()

            status = syn.get_membership_status(userid="12345", team="67890")
            print(status)
            ```


        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Use synchronous version (recommended for most use cases)
            team = Team.from_id(id="67890")
            status = team.get_user_membership_status(
                user_id="12345",
            )
            print(status)
            ```
        """
        teamid = id_of(team)
        request = "/team/{team}/member/{user}/membershipStatus".format(
            team=teamid, user=userid
        )
        membership_status = self.restGET(request)
        return membership_status

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _delete_membership_invitation(self, invitationid: str) -> None:
        """
        Delete an invitation Note: The client must be an administrator of the
        Team referenced by the invitation or the invitee to make this request.

        Arguments:
            invitationid: Open invitation id
        """
        self.restDELETE("/membershipInvitation/{id}".format(id=invitationid))

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to synapseclient.api.team_services.send_membership_invitation. "
        "Check the docstring for the replacement function example.",
    )
    def send_membership_invitation(
        self, teamId, inviteeId=None, inviteeEmail=None, message=None
    ):
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.api.team_services.send_membership_invitation][] instead.

        Create a membership invitation and send an email notification
        to the invitee.

        Arguments:
            teamId: Synapse teamId
            inviteeId: Synapse username or profile id of user
            inviteeEmail: Email of user
            message: Additional message for the user getting invited to the
                     team.

        Returns:
            MembershipInvitation

        Example: Migration to new method
            &nbsp;

            ```python
            import asyncio
            from synapseclient import Synapse
            from synapseclient.api.team_services import send_membership_invitation

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Send invitation by user ID
            invitation = asyncio.run(send_membership_invitation(
                team_id=12345,
                invitee_id="username_or_user_id",
                message="Welcome to our team!"
            ))
            print(f"Invitation sent: {invitation}")

            # Send invitation by email
            invitation = asyncio.run(send_membership_invitation(
                team_id=12345,
                invitee_email="user@example.com",
                message="Join our team!"
            ))
            print(f"Invitation sent: {invitation}")
            ```
        """

        invite_request = {"teamId": str(teamId), "message": message}
        if inviteeEmail is not None:
            invite_request["inviteeEmail"] = str(inviteeEmail)
        if inviteeId is not None:
            invite_request["inviteeId"] = str(inviteeId)

        response = self.restPOST(
            "/membershipInvitation", body=json.dumps(invite_request)
        )
        return response

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `invite` method on the `from synapseclient.models import Team` class. "
        "Check the docstring for the replacement function example.",
    )
    def invite_to_team(
        self,
        team: Union[Team, int, str],
        user: str = None,
        inviteeEmail: str = None,
        message: str = None,
        force: bool = False,
    ):
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use [synapseclient.models.Team.invite][] instead.

        Invite user to a Synapse team via Synapse username or email
        (choose one or the other)

        Arguments:
            syn: Synapse object
            team: A [synapseclient.team.Team][] object or a team's ID.
            user: Synapse username or profile id of user
            inviteeEmail: Email of user
            message: Additional message for the user getting invited to the team.
            force: If an open invitation exists for the invitee, the old invite will be cancelled.

        Returns:
            MembershipInvitation or None if user is already a member

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Invite a user to a team
            team = Team.from_id(id=12345)
            invitation = team.invite(
                user="username",
                message="Welcome to the team!",
                force=True
            )
            print(f"Invitation sent: {invitation}")
            ```
        """
        # Throw error if both user and email is specified and if both not
        # specified
        id_email_specified = inviteeEmail is not None and user is not None
        id_email_notspecified = inviteeEmail is None and user is None
        if id_email_specified or id_email_notspecified:
            raise ValueError("Must specify either 'user' or 'inviteeEmail'")

        teamid = id_of(team)
        is_member = False
        open_invitations = self.get_team_open_invitations(teamid)

        if user is not None:
            inviteeId = self.getUserProfile(user)["ownerId"]
            membership_status = self.get_membership_status(inviteeId, teamid)
            is_member = membership_status["isMember"]
            open_invites_to_user = [
                invitation
                for invitation in open_invitations
                if invitation.get("inviteeId") == inviteeId
            ]
        else:
            inviteeId = None
            open_invites_to_user = [
                invitation
                for invitation in open_invitations
                if invitation.get("inviteeEmail") == inviteeEmail
            ]
        # Only invite if the invitee is not a member and
        # if invitee doesn't have an open invitation unless force=True
        if not is_member and (not open_invites_to_user or force):
            # Delete all old invitations
            for invite in open_invites_to_user:
                self._delete_membership_invitation(invite["id"])
            return self.send_membership_invitation(
                teamid,
                inviteeId=inviteeId,
                inviteeEmail=inviteeEmail,
                message=message,
            )
        if is_member:
            not_sent_reason = "invitee is already a member"
        else:
            not_sent_reason = (
                "invitee already has an open invitation "
                "Set force=True to send new invite."
            )

        self.logger.warning("No invitation sent: {}".format(not_sent_reason))
        # Return None if no invite is sent.
        return None

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use the `synapseclient.models.Submission` model instead, e.g. "
        "`Submission(...).store()`.",
    )
    def submit(
        self,
        evaluation,
        entity,
        name=None,
        team=None,
        silent=False,
        submitterAlias=None,
        teamName=None,
        dockerTag="latest",
    ):
        """
        Submit an Entity for [evaluation][synapseclient.evaluation.Evaluation].

        Arguments:
            evalation: Evaluation queue to submit to
            entity: The Entity containing the Submissions
            name: A name for this submission. In the absent of this parameter, the entity name will be used.
                    (Optional) A [synapseclient.team.Team][] object, ID or name of a Team that is registered for the challenge
            team: (optional) A [synapseclient.team.Team][] object, ID or name of a Team that is registered for the challenge
            silent: Set to True to suppress output.
            submitterAlias: (optional) A nickname, possibly for display in leaderboards in place of the submitter's name
            teamName: (deprecated) A synonym for submitterAlias
            dockerTag: (optional) The Docker tag must be specified if the entity is a DockerRepository.

        Returns:
            A [synapseclient.evaluation.Submission][] object


        In the case of challenges, a team can optionally be provided to give credit to members of the team that
        contributed to the submission. The team must be registered for the challenge with which the given evaluation is
        associated. The caller must be a member of the submitting team.

        Example: Using this function
            Getting and submitting an evaluation

                evaluation = syn.getEvaluation(123)
                entity = syn.get('syn456')
                submission = syn.submit(evaluation, entity, name='Our Final Answer', team='Blue Team')

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # submission = syn.submit(9614543, "syn456", name="Our Final Answer")

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import Submission

            syn = Synapse()
            syn.login()

            submission = Submission(
                evaluation_id="9614543",
                entity_id="syn456",
                name="Our Final Answer",
            ).store()
            ```
        """
        return wrap_async_to_sync(
            self.submit_async(
                evaluation,
                entity,
                name=name,
                team=team,
                silent=silent,
                submitterAlias=submitterAlias,
                teamName=teamName,
                dockerTag=dockerTag,
            )
        )

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use the `synapseclient.models.Submission` model instead, e.g. "
        "`await Submission(...).store_async()`.",
    )
    async def submit_async(
        self,
        evaluation,
        entity,
        name=None,
        team=None,
        silent=False,
        submitterAlias=None,
        teamName=None,
        dockerTag="latest",
    ):
        """
        Submit an Entity for [evaluation][synapseclient.evaluation.Evaluation].

        Arguments:
            evalation: Evaluation queue to submit to
            entity: The Entity containing the Submissions
            name: A name for this submission. In the absent of this parameter, the entity name will be used.
                    (Optional) A [synapseclient.team.Team][] object, ID or name of a Team that is registered for the challenge
            team: (optional) A [synapseclient.team.Team][] object, ID or name of a Team that is registered for the challenge
            silent: Set to True to suppress output.
            submitterAlias: (optional) A nickname, possibly for display in leaderboards in place of the submitter's name
            teamName: (deprecated) A synonym for submitterAlias
            dockerTag: (optional) The Docker tag must be specified if the entity is a DockerRepository.

        Returns:
            A [synapseclient.evaluation.Submission][] object


        In the case of challenges, a team can optionally be provided to give credit to members of the team that
        contributed to the submission. The team must be registered for the challenge with which the given evaluation is
        associated. The caller must be a member of the submitting team.

        Example: Using this function
            Getting and submitting an evaluation

                evaluation = syn.getEvaluation(123)
                entity = syn.get('syn456')
                submission = syn.submit(evaluation, entity, name='Our Final Answer', team='Blue Team')

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # submission = await syn.submit_async(9614543, "syn456", name="Our Final Answer")

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import Submission

            syn = Synapse()
            syn.login()

            submission = await Submission(
                evaluation_id="9614543",
                entity_id="syn456",
                name="Our Final Answer",
            ).store_async()
            ```
        """

        require_param(evaluation, "evaluation")
        require_param(entity, "entity")

        evaluation_id = id_of(evaluation)

        entity_id = id_of(entity)
        if isinstance(entity, synapseclient.DockerRepository):
            # Edge case if dockerTag is specified as None
            if dockerTag is None:
                raise ValueError(
                    "A dockerTag is required to submit a DockerEntity. Cannot be None"
                )
            docker_repository = entity["repositoryName"]
        else:
            docker_repository = None

        # Some hacks to make sure that new OOP models will also work with this interface
        entity_is_dataclass = is_dataclass(entity)
        if entity_is_dataclass:
            if not entity.version_number:
                if hasattr(entity, "download_file"):
                    entity.download_file = False
                entity.get(synapse_client=self)
            entity_version = entity.version_number
        else:
            if "versionNumber" not in entity:
                entity = await self.get_async(entity, downloadFile=False)
            # version defaults to 1 to hack around required version field and allow submission of files/folders
            entity_version = entity.get("versionNumber", 1)

        # default name of submission to name of entity
        if name is None:
            if entity_is_dataclass:
                name = entity.name
            elif "name" in entity:
                name = entity["name"]

        team_id = None
        if team:
            team = self.getTeam(team)
            team_id = id_of(team)

        contributors, eligibility_hash = self._get_contributors(evaluation_id, team)

        # for backward compatible until we remove supports for teamName
        if not submitterAlias:
            if teamName:
                submitterAlias = teamName
            elif team and "name" in team:
                submitterAlias = team["name"]

        if isinstance(entity, synapseclient.DockerRepository):
            docker_digest = self._get_docker_digest(entity, dockerTag)
        else:
            docker_digest = None

        submission = {
            "evaluationId": evaluation_id,
            "name": name,
            "entityId": entity_id,
            "versionNumber": entity_version,
            "dockerDigest": docker_digest,
            "dockerRepositoryName": docker_repository,
            "teamId": team_id,
            "contributors": contributors,
            "submitterAlias": submitterAlias,
        }

        if entity_is_dataclass:
            entity_etag = entity.etag
        else:
            entity_etag = entity["etag"]
        submitted = self._submit(submission, entity_etag, eligibility_hash)

        # if we want to display the receipt message, we need the full object
        if not silent:
            if not (isinstance(evaluation, Evaluation)):
                evaluation = self.getEvaluation(evaluation_id)
            if "submissionReceiptMessage" in evaluation:
                self.logger.info(evaluation["submissionReceiptMessage"])

        return Submission(**submitted)

    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1590
    def _submit(self, submission, entity_etag, eligibility_hash):
        require_param(submission, "submission")
        require_param(entity_etag, "entity_etag")
        # URI requires the etag of the entity and, in the case of a team submission, requires an eligibilityStateHash
        uri = "/evaluation/submission?etag=%s" % entity_etag
        if eligibility_hash:
            uri += "&submissionEligibilityHash={0}".format(eligibility_hash)
        submitted = self.restPOST(uri, json.dumps(submission))
        return submitted

    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1590
    def _get_contributors(self, evaluation_id, team):
        if not evaluation_id or not team:
            return None, None

        team_id = id_of(team)
        # see <https://rest-docs.synapse.org/rest/GET/evaluation/evalId/team/id/submissionEligibility.html>
        eligibility = self.restGET(
            "/evaluation/{evalId}/team/{id}/submissionEligibility".format(
                evalId=evaluation_id, id=team_id
            )
        )

        if not eligibility["teamEligibility"]["isEligible"]:
            # Check team eligibility and raise an exception if not eligible
            if not eligibility["teamEligibility"]["isRegistered"]:
                raise SynapseError(
                    'Team "{team}" is not registered.'.format(team=team.name)
                )
            if eligibility["teamEligibility"]["isQuotaFilled"]:
                raise SynapseError(
                    'Team "{team}" has already submitted the full quota of submissions.'.format(
                        team=team.name
                    )
                )
            raise SynapseError('Team "{team}" is not eligible.'.format(team=team.name))

        # Include all team members who are eligible.
        contributors = [
            {"principalId": member["principalId"]}
            for member in eligibility["membersEligibility"]
            if member["isEligible"] and not member["hasConflictingSubmission"]
        ]
        return contributors, eligibility["eligibilityStateHash"]

    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1590
    def _allowParticipation(
        self,
        evaluation: Union[Evaluation, str],
        user: str,
        rights: list = ["READ", "PARTICIPATE", "SUBMIT", "UPDATE_SUBMISSION"],
    ) -> Dict[str, Union[str, list]]:
        """
        Grants the given user the minimal access rights to join and submit to an Evaluation.
        Note: The specification of this method has not been decided yet, so the method is likely to change in future.

        Arguments:
            evaluation: An Evaluation object or Evaluation ID
            user:       Either a user group or the principal ID of a user to grant rights to.

                - To allow all users, use "PUBLIC".
                - To allow authenticated users, use "AUTHENTICATED_USERS".

            rights:     The access rights to give to the users.

                - `READ`
                - `PARTICIPATE`
                - `SUBMIT`
                - `UPDATE_SUBMISSION`

        Raises:
            SynapseError: If the user does not exist

        Returns:
            The new or updated ACL
        """
        # Check to see if the user is an ID or group
        userId = -1
        try:
            # TODO: is there a better way to differentiate between a userID and a group name?
            # What if a group is named with just numbers?
            userId = int(user)

            # Verify that the user exists
            try:
                self.getUserProfile(userId)
            except SynapseHTTPError as err:
                if err.response.status_code == 404:
                    raise SynapseError("The user (%s) does not exist" % str(userId))
                raise

        except ValueError:
            # Fetch the ID of the user group
            userId = self._getUserbyPrincipalIdOrName(user)

        if not isinstance(evaluation, Evaluation):
            evaluation = self.getEvaluation(id_of(evaluation))

        self.setPermissions(evaluation, userId, accessType=rights, overwrite=False)

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use `synapseclient.models.Submission.get_evaluation_submissions()` (or "
        "`get_user_submissions()` for your own submissions) instead.",
    )
    def getSubmissions(self, evaluation, status=None, myOwn=False, limit=20, offset=0):
        """
        Arguments:
            evaluation: Evaluation to get submissions from.
            status: Optionally filter submissions for a specific status.
                    One of:

                - `OPEN`
                - `CLOSED`
                - `SCORED`
                - `INVALID`
                - `VALIDATED`
                - `EVALUATION_IN_PROGRESS`
                - `RECEIVED`
                - `REJECTED`
                - `ACCEPTED`

            myOwn: Determines if only your Submissions should be fetched.
                     Defaults to False (all Submissions)
            limit: Limits the number of submissions in a single response.
                        Because this method returns a generator and repeatedly
                        fetches submissions, this argument is limiting the
                        size of a single request and NOT the number of sub-
                        missions returned in total.
            offset: Start iterating at a submission offset from the first submission.

        Yields:
            A generator over [synapseclient.evaluation.Submission][] objects for an Evaluation

        Example: Using this function
            Print submissions

                for submission in syn.getSubmissions(1234567):
                    print(submission['entityId'])

        See:

        - [synapseclient.evaluation][]

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # for submission in syn.getSubmissions(1234567):
            #     print(submission)

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import Submission

            syn = Synapse()
            syn.login()

            # All submissions for an evaluation
            for submission in Submission.get_evaluation_submissions(evaluation_id="1234567"):
                print(submission)

            # Only your own submissions (equivalent to myOwn=True)
            for submission in Submission.get_user_submissions(evaluation_id="1234567"):
                print(submission)
            ```
        """

        evaluation_id = id_of(evaluation)
        uri = "/evaluation/%s/submission%s" % (evaluation_id, "" if myOwn else "/all")

        if status is not None:
            uri += "?status=%s" % status

        for result in self._GET_paginated(uri, limit=limit, offset=offset):
            yield Submission(**result)

    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1590
    def _getSubmissionBundles(
        self,
        evaluation: Union[Evaluation, str],
        status: str = None,
        myOwn: bool = False,
        limit: int = 20,
        offset: int = 0,
    ) -> typing.Iterator[Dict[str, Union[Submission, dict]]]:
        """
        Gets the requesting user's bundled Submissions and SubmissionStatuses to a specified Evaluation.

        Arguments:
            evaluation: Evaluation to get submissions from.
            status:     Optionally filter submissions for a specific status.
                        One of {OPEN, CLOSED, SCORED, INVALID}
            myOwn:      Determines if only your Submissions should be fetched.
                        Defaults to False (all Submissions)
            limit:      Limits the number of submissions coming back from the
                        service in a single response.
            offset:     Start iterating at a submission offset from the first
                        submission.

        Returns:
            A generator over dictionaries with keys 'submission' and 'submissionStatus'.

        Example:

            for sb in syn._getSubmissionBundles(1234567):
                print(sb['submission']['name'],
                      sb['submission']['submitterAlias'],
                      sb['submissionStatus']['status'],
                      sb['submissionStatus']['score'])

        This may later be changed to return objects, pending some thought on how submissions along with related status
        and annotations should be represented in the clients.

        See: [synapseclient.evaluation][]
        """

        evaluation_id = id_of(evaluation)
        url = "/evaluation/%s/submission/bundle%s" % (
            evaluation_id,
            "" if myOwn else "/all",
        )
        if status is not None:
            url += "?status=%s" % status

        return self._GET_paginated(url, limit=limit, offset=offset)

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use `synapseclient.models.SubmissionBundle.get_evaluation_submission_bundles()` "
        "(or `get_user_submission_bundles()` for your own) instead.",
    )
    def getSubmissionBundles(
        self, evaluation, status=None, myOwn=False, limit=20, offset=0
    ):
        """
        Retrieve submission bundles (submission and submissions status) for an evaluation queue, optionally filtered by
        submission status and/or owner.

        Arguments:
            evaluation: Evaluation to get submissions from.
            status:     Optionally filter submissions for a specific status.
                        One of:

                - `OPEN`
                - `CLOSED`
                - `SCORED`
                - `INVALID`

            myOwn:      Determines if only your Submissions should be fetched.
                        Defaults to False (all Submissions)
            limit:      Limits the number of submissions coming back from the
                        service in a single response.
            offset:     Start iterating at a submission offset from the first submission.

        Yields:
            A generator over tuples containing a [synapseclient.evaluation.Submission][] and a [synapseclient.evaluation.SubmissionStatus][].

        Example: Using this function
            Loop over submissions

                for submission, status in syn.getSubmissionBundles(evaluation):
                    print(submission.name,
                          submission.submitterAlias,
                          status.status,
                          status.score)

        This may later be changed to return objects, pending some thought on how submissions along with related status
        and annotations should be represented in the clients.

        See:
        - [synapseclient.evaluation][]

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # for submission, status in syn.getSubmissionBundles(1234567):
            #     print(submission, status)

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import SubmissionBundle

            syn = Synapse()
            syn.login()

            # All submission bundles for an evaluation
            for bundle in SubmissionBundle.get_evaluation_submission_bundles(evaluation_id="1234567"):
                print(bundle.submission, bundle.submission_status)

            # Only your own submission bundles (equivalent to myOwn=True)
            for bundle in SubmissionBundle.get_user_submission_bundles(evaluation_id="1234567"):
                print(bundle.submission, bundle.submission_status)
            ```
        """
        for bundle in self._getSubmissionBundles(
            evaluation, status=status, myOwn=myOwn, limit=limit, offset=offset
        ):
            yield (
                Submission(**bundle["submission"]),
                SubmissionStatus(**bundle["submissionStatus"]),
            )

    def _GET_paginated(self, uri: str, limit: int = 20, offset: int = 0):
        """
        Get paginated results

        Arguments:
            uri:     A URI that returns paginated results
            limit:   How many records should be returned per request
            offset:  At what record offset from the first should iteration start

        Returns:
            A generator over some paginated results

        The limit parameter is set at 20 by default. Using a larger limit results in fewer calls to the service, but if
        responses are large enough to be a burden on the service they may be truncated.
        """
        prev_num_results = sys.maxsize
        while prev_num_results > 0:
            uri = utils._limit_and_offset(uri, limit=limit, offset=offset)
            page = self.restGET(uri)
            results = page["results"] if "results" in page else page["children"]
            prev_num_results = len(results)

            for result in results:
                offset += 1
                yield result

    def _POST_paginated(self, uri: str, body, **kwargs):
        """
        Get paginated results

        Arguments:
            uri:     A URI that returns paginated results
            body:    POST request payload

        Returns:
            A generator over some paginated results
        """

        next_page_token = None
        while True:
            body["nextPageToken"] = next_page_token
            response = self.restPOST(uri, body=json.dumps(body), **kwargs)
            next_page_token = response.get("nextPageToken")
            for item in response["page"]:
                yield item
            if next_page_token is None:
                break

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use the `synapseclient.models.Submission` model instead, e.g. "
        "`Submission(id=...).get()`.",
    )
    def getSubmission(
        self, id: typing.Union[str, int, collections.abc.Mapping], **kwargs
    ) -> Submission:
        """
        Gets a [synapseclient.evaluation.Submission][] object based on a given ID
        or previous [synapseclient.evaluation.Submission][] object.

        Arguments:
            id: The ID of the submission to retrieve or a [synapseclient.evaluation.Submission][] object

        Returns:
            A [synapseclient.evaluation.Submission][] object

        See:

        - [synapseclient.Synapse.get][] for information
             on the *downloadFile*, *downloadLocation*, and *ifcollision* parameters

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # submission = syn.getSubmission(9700123)

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import Submission

            syn = Synapse()
            syn.login()

            submission = Submission(id="9700123").get()
            ```
        """
        return wrap_async_to_sync(self.getSubmission_async(id=id, **kwargs))

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use the `synapseclient.models.Submission` model instead, e.g. "
        "`await Submission(id=...).get_async()`.",
    )
    async def getSubmission_async(
        self, id: typing.Union[str, int, collections.abc.Mapping], **kwargs
    ) -> Submission:
        """
        Gets a [synapseclient.evaluation.Submission][] object based on a given ID
        or previous [synapseclient.evaluation.Submission][] object.

        Arguments:
            id: The ID of the submission to retrieve or a [synapseclient.evaluation.Submission][] object

        Returns:
            A [synapseclient.evaluation.Submission][] object

        See:

        - [synapseclient.Synapse.get][] for information
             on the *downloadFile*, *downloadLocation*, and *ifcollision* parameters

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # submission = await syn.getSubmission_async(9700123)

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import Submission

            syn = Synapse()
            syn.login()

            submission = await Submission(id="9700123").get_async()
            ```
        """

        submission_id = validate_submission_id(id)
        uri = Submission.getURI(submission_id)
        submission = Submission(**self.restGET(uri))

        # Pre-fetch the Entity tied to the Submission, if there is one
        if "entityId" in submission and submission["entityId"] is not None:
            entityBundleJSON = json.loads(submission["entityBundleJSON"])

            # getWithEntityBundle expects a bundle services v2 style
            # annotations dict, but the evaluations API may return
            # an older format annotations object in the encoded JSON
            # depending on when the original submission was made.
            annotations = entityBundleJSON.get("annotations")
            if annotations:
                entityBundleJSON["annotations"] = convert_old_annotation_json(
                    annotations
                )

            related = await self._getWithEntityBundle_async(
                entityBundle=entityBundleJSON,
                entity=submission["entityId"],
                submission=submission_id,
                **kwargs,
            )
            submission.entity = related
            submission.filePath = related.get("path", None)

        return submission

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use the `synapseclient.models.SubmissionStatus` model instead, e.g. "
        "`SubmissionStatus(id=...).get()`.",
    )
    def getSubmissionStatus(
        self, submission: typing.Union[str, int, collections.abc.Mapping]
    ) -> SubmissionStatus:
        """
        Downloads the status of a Submission given its ID or previous [synapseclient.evaluation.Submission][] object.

        Arguments:
            submission: The submission to lookup (ID or [synapseclient.evaluation.Submission][] object)

        Returns:
            A [synapseclient.evaluation.SubmissionStatus][] object

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # status = syn.getSubmissionStatus(9700123)

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import SubmissionStatus

            syn = Synapse()
            syn.login()

            status = SubmissionStatus(id="9700123").get()
            ```
        """

        submission_id = validate_submission_id(submission)
        uri = SubmissionStatus.getURI(submission_id)
        val = self.restGET(uri)
        return SubmissionStatus(**val)

    ############################################################
    #                      CRUD for Wikis                      #
    ############################################################

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use the `synapseclient.models.WikiPage` model instead, e.g. "
        "`WikiPage(owner_id=..., id=...).get()`.",
    )
    def getWiki(self, owner, subpageId=None, version=None):
        """
        Get a [synapseclient.wiki.Wiki][] object from Synapse. Uses wiki2 API which supports versioning.

        Arguments:
            owner: The entity to which the Wiki is attached
            subpageId: The id of the specific sub-page or None to get the root Wiki page
            version: The version of the page to retrieve or None to retrieve the latest

        Returns:
            A [synapseclient.wiki.Wiki][] object

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # wiki = syn.getWiki("syn123", subpageId="456")

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import WikiPage

            syn = Synapse()
            syn.login()

            wiki = WikiPage(owner_id="syn123", id="456").get()
            ```
        """
        return wrap_async_to_sync(
            self.getWiki_async(owner, subpageId=subpageId, version=version)
        )

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use the `synapseclient.models.WikiPage` model instead, e.g. "
        "`await WikiPage(owner_id=..., id=...).get_async()`.",
    )
    async def getWiki_async(self, owner, subpageId=None, version=None):
        """
        Get a [synapseclient.wiki.Wiki][] object from Synapse. Uses wiki2 API which supports versioning.

        Arguments:
            owner: The entity to which the Wiki is attached
            subpageId: The id of the specific sub-page or None to get the root Wiki page
            version: The version of the page to retrieve or None to retrieve the latest

        Returns:
            A [synapseclient.wiki.Wiki][] object

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # wiki = await syn.getWiki_async("syn123", subpageId="456")

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import WikiPage

            syn = Synapse()
            syn.login()

            wiki = await WikiPage(owner_id="syn123", id="456").get_async()
            ```
        """
        uri = "/entity/{ownerId}/wiki2".format(ownerId=id_of(owner))
        if subpageId is not None:
            uri += "/{wikiId}".format(wikiId=subpageId)
        if version is not None:
            uri += "?wikiVersion={version}".format(version=version)

        wiki = self.restGET(uri)
        wiki["owner"] = owner
        wiki = Wiki(**wiki)

        path = self.cache.get(wiki.markdownFileHandleId)
        if not path:
            cache_dir = self.cache.get_cache_dir(wiki.markdownFileHandleId)
            if not os.path.exists(cache_dir):
                os.makedirs(cache_dir)
            path = await download_by_file_handle(
                file_handle_id=wiki["markdownFileHandleId"],
                synapse_id=wiki["id"],
                entity_type="WikiMarkdown",
                destination=os.path.join(
                    cache_dir, str(wiki.markdownFileHandleId) + ".md"
                ),
                synapse_client=self,
            )
        try:
            import gzip

            with gzip.open(path) as f:
                markdown = f.read().decode("utf-8")
        except IOError:
            with open(path) as f:
                markdown = f.read().decode("utf-8")

        wiki.markdown = markdown
        wiki.markdown_path = path

        return wiki

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use `synapseclient.models.WikiHeader.get(owner_id=...)` instead.",
    )
    def getWikiHeaders(self, owner):
        """
        Retrieves the headers of all Wikis belonging to the owner (the entity to which the Wiki is attached).

        Arguments:
            owner: An Entity

        Returns:
            A list of Objects with three fields: id, title and parentId.

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # headers = syn.getWikiHeaders("syn123")

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import WikiHeader

            syn = Synapse()
            syn.login()

            for header in WikiHeader.get(owner_id="syn123"):
                print(header)
            ```
        """

        uri = "/entity/%s/wikiheadertree" % id_of(owner)
        return [DictObject(**header) for header in self._GET_paginated(uri)]

    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1351
    def _storeWiki(self, wiki: Wiki, createOrUpdate: bool) -> Wiki:
        """
        Stores or updates the given Wiki.

        Arguments:
            wiki:           A Wiki object
            createOrUpdate: Indicates whether the method should automatically perform an update if the 'obj'
                            conflicts with an existing Synapse object.

        Returns:
            An updated Wiki object
        """
        return wrap_async_to_sync(self._storeWiki_async(wiki, createOrUpdate))

    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1351
    async def _storeWiki_async(self, wiki: Wiki, createOrUpdate: bool) -> Wiki:
        """
        Stores or updates the given Wiki.

        Arguments:
            wiki:           A Wiki object
            createOrUpdate: Indicates whether the method should automatically perform an update if the 'obj'
                            conflicts with an existing Synapse object.

        Returns:
            An updated Wiki object
        """
        # Make sure the file handle field is a list
        if "attachmentFileHandleIds" not in wiki:
            wiki["attachmentFileHandleIds"] = []

        # Convert all attachments into file handles
        if wiki.get("attachments") is not None:
            for attachment in wiki["attachments"]:
                fileHandle = await upload_synapse_s3(self, attachment)
                wiki["attachmentFileHandleIds"].append(fileHandle["id"])
            del wiki["attachments"]

        # Perform an update if the Wiki has an ID
        if "id" in wiki:
            updated_wiki = Wiki(
                owner=wiki.ownerId, **self.restPUT(wiki.putURI(), wiki.json())
            )

        # Perform a create if the Wiki has no ID
        else:
            try:
                updated_wiki = Wiki(
                    owner=wiki.ownerId, **self.restPOST(wiki.postURI(), wiki.json())
                )
            except SynapseHTTPError as err:
                # If already present we get an unhelpful SQL error
                if createOrUpdate and (
                    (
                        err.response.status_code == 400
                        and "DuplicateKeyException" in err.response.text
                    )
                    or err.response.status_code == 409
                ):
                    existing_wiki = await self.getWiki_async(wiki.ownerId)

                    # overwrite everything except for the etag (this will keep unmodified fields in the existing wiki)
                    etag = existing_wiki["etag"]
                    existing_wiki.update(wiki)
                    existing_wiki.etag = etag

                    updated_wiki = Wiki(
                        owner=wiki.ownerId,
                        **self.restPUT(existing_wiki.putURI(), existing_wiki.json()),
                    )
                else:
                    raise
        return updated_wiki

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. "
        "Use `synapseclient.models.WikiPage.get_attachment_handles()` on the WikiPage "
        "instead.",
    )
    def getWikiAttachments(self, wiki):
        """
        Retrieve the attachments to a wiki page.

        Arguments:
            wiki: The Wiki object for which the attachments are to be returned.

        Returns:
            A list of file handles for the files attached to the Wiki.

        Example: Migration to the object-oriented model
            &nbsp;

            ```python
            # Old approach (DEPRECATED)
            # attachments = syn.getWikiAttachments(wiki)

            # New approach (RECOMMENDED)
            from synapseclient import Synapse
            from synapseclient.models import WikiPage

            syn = Synapse()
            syn.login()

            attachments = WikiPage(owner_id="syn123", id="456").get_attachment_handles()
            ```
        """
        uri = "/entity/%s/wiki/%s/attachmenthandles" % (wiki.ownerId, wiki.id)
        results = self.restGET(uri)
        file_handles = list(WikiAttachment(**fh) for fh in results["list"])
        return file_handles

    ############################################################
    #                      Tables                              #
    ############################################################

    @tracer.start_as_current_span("Synapse::_waitForAsync")
    def _waitForAsync(self, uri, request, endpoint=None):
        if endpoint is None:
            endpoint = self.repoEndpoint
        async_job_id = self.restPOST(
            uri + "/start", body=json.dumps(request), endpoint=endpoint
        )

        # https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/asynch/AsynchronousJobStatus.html
        sleep = self.table_query_sleep
        start_time = time.time()
        lastMessage, lastProgress, lastTotal = "", 0, 1
        progress_bar = create_progress_bar(total=None, desc=uri, synapse_client=self)
        while time.time() - start_time < self.table_query_timeout:
            result = self.restGET(
                uri + "/get/%s" % async_job_id["token"], endpoint=endpoint
            )
            if result.get("jobState", None) == "PROCESSING":
                message = result.get("progressMessage", lastMessage)
                progress = result.get("progressCurrent", lastProgress)
                total = result.get("progressTotal", lastTotal)
                if total and progress_bar.total != total:
                    progress_bar.total = total
                    progress_bar.refresh()

                if message != "":
                    progress_bar.desc = message
                    progress_bar.refresh()

                # Reset the time if we made progress (fix SYNPY-214)
                if message != lastMessage or lastProgress != progress:
                    progress_bar.update(progress)
                    start_time = time.time()
                    lastMessage, lastProgress, lastTotal = message, progress, total
                sleep = min(
                    self.table_query_max_sleep, sleep * self.table_query_backoff
                )
                doze(sleep, trace_span_name="Synapse::doze_for_async")
            else:
                break
        else:
            raise SynapseTimeoutError(
                "Timeout waiting for query results: %0.1f seconds "
                % (time.time() - start_time)
            )
        if result.get("jobState", None) == "FAILED":
            raise SynapseError(
                result.get("errorMessage", None)
                + "\n"
                + result.get("errorDetails", None),
                asynchronousJobStatus=result,
            )
        if progress_bar.total and progress_bar.n:
            progress_bar.update(progress_bar.total - progress_bar.n)
        progress_bar.refresh()
        progress_bar.close()
        return result

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Use the `Column.get()` method instead. "
        "Check the docstring for the replacement function example.",
    )
    def getColumn(self, id):
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `Column.get()` method instead.

        Gets a Column object from Synapse by ID.

        See: [synapseclient.table.Column][]

        Arguments:
            id: The ID of the column to retrieve

        Returns:
            An object of type [synapseclient.table.Column][]

        Example: Using this function (DEPRECATED)
            Getting a column

                column = syn.getColumn(123)

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Get a column by ID
            column = Column(id="123").get()
            print(f"Column name: {column.name}")
            print(f"Column type: {column.column_type}")
            print(f"Column ID: {column.id}")
            ```
        """
        return Column(**self.restGET(Column.getURI(id)))

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "For table columns, use the `.columns` attribute on Table, EntityView, SubmissionView, or Dataset classes after calling `.get(include_columns=True)`. "
        "For column listing and prefix filtering, use the `Column.list()` method. "
        "Check the docstring for the replacement function example.",
    )
    def getColumns(self, x, limit=100, offset=0):
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `.columns` attribute on table classes or `Column.list()` method instead.

        Get the columns defined in Synapse either (1) corresponding to a set of column headers, (2) those for a given
        schema, or (3) those whose names start with a given prefix.

        Arguments:
            x: A list of column headers, a Table Entity object (Schema/EntityViewSchema), a Table's Synapse ID, or a
                string prefix
            limit: Number of columns to retrieve per request to Synapse (pagination parameter).
                The function will continue retrieving results until all matching columns are returned.
            offset: the index of the first column to return (pagination parameter)

        Yields:
            A generator over [synapseclient.table.Column][] objects

        Example: Using this function (DEPRECATED)
            Getting columns for a table

                for column in syn.getColumns("syn12345"):
                    print(column.name)

            Getting columns with a prefix

                for column in syn.getColumns("my_prefix"):
                    print(column.name)

        Example: Migration to new method
            &nbsp;

            ```python
            from synapseclient import Synapse
            from synapseclient.models import Column, Table, EntityView, SubmissionView, Dataset, DatasetCollection

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # For getting columns of a specific table/view/dataset
            table = Table(id="syn12345")
            table = table.get(include_columns=True)
            for column_name, column in table.columns.items():
                print(f"Table column: {column_name}, Type: {column.column_type}")

            # For EntityView
            view = EntityView(id="syn67890")
            view = view.get(include_columns=True)
            for column_name, column in view.columns.items():
                print(f"EntityView column: {column_name}, Type: {column.column_type}")

            # For SubmissionView
            submission_view = SubmissionView(id="syn11111")
            submission_view = submission_view.get(include_columns=True)
            for column_name, column in submission_view.columns.items():
                print(f"SubmissionView column: {column_name}, Type: {column.column_type}")

            # For Dataset
            dataset = Dataset(id="syn22222")
            dataset = dataset.get(include_columns=True)
            for column_name, column in dataset.columns.items():
                print(f"Dataset column: {column_name}, Type: {column.column_type}")

            # For DatasetCollection
            dataset_collection = DatasetCollection(id="syn33333")
            dataset_collection = dataset_collection.get(include_columns=True)
            for column_name, column in dataset_collection.columns.items():
                print(f"DatasetCollection column: {column_name}, Type: {column.column_type}")

            # For listing all columns with a prefix
            for column in Column.list(prefix="my_prefix"):
                print(f"Prefixed column: {column.name}, Type: {column.column_type}")

            # For listing all columns
            for column in Column.list():
                print(f"All columns: {column.name}, Type: {column.column_type}")

            ```
        """
        if x is None:
            uri = "/column"
            for result in self._GET_paginated(uri, limit=limit, offset=offset):
                yield Column(**result)
        elif isinstance(x, (list, tuple)):
            for header in x:
                try:
                    # if header is an integer, it's a columnID, otherwise it's an aggregate column, like "AVG(Foo)"
                    int(header)
                    yield self.getColumn(header)
                except ValueError:
                    # ignore aggregate column
                    pass
        elif isinstance(x, SchemaBase) or utils.is_synapse_id_str(x):
            for col in self.getTableColumns(x):
                yield col
        elif isinstance(x, str):
            uri = "/column?prefix=" + x
            for result in self._GET_paginated(uri, limit=limit, offset=offset):
                yield Column(**result)
        else:
            ValueError("Can't get columns for a %s" % type(x))

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Use the `.snapshot()` method on the `Table`, `EntityView`, `SubmissionView`, or `Dataset` classes instead. "
        "Check the docstring for the replacement function example.",
    )
    def create_snapshot_version(
        self,
        table: typing.Union[
            EntityViewSchema, Schema, str, SubmissionViewSchema, Dataset
        ],
        comment: str = None,
        label: str = None,
        activity: typing.Union[Activity, str] = None,
        wait: bool = True,
    ) -> int:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `.snapshot()` method on the `Table`, `EntityView`, `SubmissionView`, or `Dataset` classes instead.

        Create a new Table Version, new View version, or new Dataset version.

        Arguments:
            table: The schema of the Table/View, or its ID.
            comment: Optional snapshot comment.
            label: Optional snapshot label.
            activity: Optional activity ID applied to snapshot version.
            wait: True if this method should return the snapshot version after waiting for any necessary
                    asynchronous table updates to complete. If False this method will return
                    as soon as any updates are initiated.

        Returns:
            The snapshot version number if wait=True, None if wait=False

        Example: Using this function (DEPRECATED)
            Creating a snapshot of a table

                table_id = "syn1234"
                snapshot_version = syn.create_snapshot_version(
                    table_id,
                    comment="This is a snapshot",
                    label="v1.0",
                    activity=my_activity
                )

        Example: Migration to new method
            &nbsp;

            ```python
            from synapseclient import Synapse
            from synapseclient.models import Table, EntityView, SubmissionView, Dataset

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # For Tables
            table = Table(id="syn1234")
            snapshot_response = table.snapshot(
                comment="This is a snapshot",
                label="v1.0",
                include_activity=True,
                associate_activity_to_new_version=True
            )
            print(f"Snapshot version: {snapshot_response['snapshotVersionNumber']}")

            # For Entity Views
            view = EntityView(id="syn5678")
            snapshot_transaction = view.snapshot(
                comment="This is a snapshot",
                label="v1.0",
                include_activity=True,
                associate_activity_to_new_version=True
            )
            print(f"Snapshot version: {snapshot_transaction.snapshot_version_number}")

            # For Submission Views
            submission_view = SubmissionView(id="syn9012")
            snapshot_transaction = submission_view.snapshot(
                comment="This is a snapshot",
                label="v1.0",
                include_activity=True,
                associate_activity_to_new_version=True
            )
            print(f"Snapshot version: {snapshot_transaction.snapshot_version_number}")

            # For Datasets
            dataset = Dataset(id="syn3456")
            snapshot_transaction = dataset.snapshot(
                comment="This is a snapshot",
                label="v1.0",
                include_activity=True,
                associate_activity_to_new_version=True
            )
            print(f"Snapshot version: {snapshot_transaction.snapshot_version_number}")
            ```
        """
        ent = self.get(id_of(table), downloadFile=False)
        if isinstance(ent, (EntityViewSchema, SubmissionViewSchema, Dataset)):
            result = self._async_table_update(
                table,
                create_snapshot=True,
                comment=comment,
                label=label,
                activity=activity,
                wait=wait,
            )
        elif isinstance(ent, Schema):
            result = self._create_table_snapshot(
                table,
                comment=comment,
                label=label,
                activity=activity,
            )
        else:
            raise ValueError(
                "This function only accepts Synapse ids of Tables or Views"
            )

        # for consistency we return nothing if wait=False since we can't
        # supply the snapshot version on an async table update without waiting
        return result["snapshotVersionNumber"] if wait else None

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _create_table_snapshot(
        self,
        table: typing.Union[Schema, str],
        comment: str = None,
        label: str = None,
        activity: typing.Union[Activity, str] = None,
    ) -> dict:
        """
        Creates Table snapshot

        Arguments:
            table:  The schema of the Table
            comment:  Optional snapshot comment.
            label:  Optional snapshot label.
            activity:  Optional activity ID or activity instance applied to snapshot version.

        Returns:
            Snapshot Response
        """

        # check the activity id or object is provided
        activity_id = None
        if isinstance(activity, collections.abc.Mapping):
            if "id" not in activity:
                activity = self._saveActivity(activity)
            activity_id = activity["id"]
        elif activity is not None:
            activity_id = str(activity)

        snapshot_body = {
            "snapshotComment": comment,
            "snapshotLabel": label,
            "snapshotActivityId": activity_id,
        }
        new_body = {
            key: value for key, value in snapshot_body.items() if value is not None
        }
        snapshot = self.restPOST(
            "/entity/{}/table/snapshot".format(id_of(table)), body=json.dumps(new_body)
        )
        return snapshot

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _async_table_update(
        self,
        table: typing.Union[EntityViewSchema, Schema, str, SubmissionViewSchema],
        changes: typing.List[dict] = [],
        create_snapshot: bool = False,
        comment: str = None,
        label: str = None,
        activity: str = None,
        wait: bool = True,
    ) -> dict:
        """
        Creates view updates and snapshots

        Arguments:
            table:           The schema of the EntityView or its ID.
            changes:         Array of Table changes
            create_snapshot: Create snapshot
            comment:         Optional snapshot comment.
            label:           Optional snapshot label.
            activity:        Optional activity ID applied to snapshot version.
            wait:            True to wait for async table update to complete

        Returns:
            A Snapshot Response
        """
        snapshot_options = {
            "snapshotComment": comment,
            "snapshotLabel": label,
            "snapshotActivityId": activity,
        }
        new_snapshot = {
            key: value for key, value in snapshot_options.items() if value is not None
        }
        table_update_body = {
            "changes": changes,
            "createSnapshot": create_snapshot,
            "snapshotOptions": new_snapshot,
        }

        uri = "/entity/{}/table/transaction/async".format(id_of(table))

        if wait:
            result = self._waitForAsync(uri, table_update_body)

        else:
            result = self.restPOST(
                "{}/start".format(uri), body=json.dumps(table_update_body)
            )

        return result

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Moved to the `columns` attribute on the `from synapseclient.models import Table` class. "
        "Check the docstring for the replacement function example.",
    )
    def getTableColumns(self, table):
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `columns` attribute on [synapseclient.models.Table][] instead.

        Retrieve the column models used in the given table schema.

        Arguments:
            table: The schema of the Table whose columns are to be retrieved

        Yields:
            A Generator over the Table's [columns][synapseclient.table.Column]

        Example: Using this function (DEPRECATED)
            Getting columns from a table schema:

                columns = list(syn.getTableColumns("syn123"))

        Example: Migration to new method
            &nbsp;

            ```python
            from synapseclient import Synapse
            from synapseclient.models import Table, Dataset, DatasetCollection, EntityView, SubmissionView

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # For Tables
            table = Table(id="syn123").get()
            columns = list(table.columns.values())
            print("Columns in table:", columns)
            # Access individual columns by name
            my_table_column = table.columns["my_column_name"]

            # For Datasets
            dataset = Dataset(id="syn456").get()
            columns = list(dataset.columns.values())
            print("Columns in dataset:", columns)
            # Access individual columns by name
            my_dataset_column = dataset.columns["my_column_name"]

            # For Dataset Collections
            dataset_collection = DatasetCollection(id="syn789").get()
            columns = list(dataset_collection.columns.values())
            print("Columns in dataset collection:", columns)
            # Access individual columns by name
            my_collection_column = dataset_collection.columns["my_column_name"]

            # For Entity Views
            entity_view = EntityView(id="syn012").get()
            columns = list(entity_view.columns.values())
            print("Columns in entity view:", columns)
            # Access individual columns by name
            my_view_column = entity_view.columns["my_column_name"]

            # For Submission Views
            submission_view = SubmissionView(id="syn345").get()
            columns = list(submission_view.columns.values())
            print("Columns in submission view:", columns)
            # Access individual columns by name
            my_submission_column = submission_view.columns["my_column_name"]
            ```
        """
        uri = "/entity/{id}/column".format(id=id_of(table))
        # The returned object type for this service, PaginatedColumnModels, is a misnomer.
        # This service always returns the full list of results so the pagination does not not actually matter.
        for result in self.restGET(uri)["results"]:
            yield Column(**result)

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Use the `query` functions from `synapseclient.models.Table` instead. "
        "Check the docstring for the replacement function example.",
    )
    def tableQuery(self, query: str, resultsAs: str = "csv", **kwargs):
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `query` or `query_async` functions from [synapseclient.models.Table][] instead.

        Query a Synapse Table.

        You can receive query results either as a generator over rows or as a CSV file. For smallish tables, either
        method will work equally well. Use of a "rowset" generator allows rows to be processed one at a time and
        processing may be stopped before downloading the entire table.

        Optional keyword arguments differ for the two return types of `rowset` or `csv`

        Arguments:
            query: Query string in a [SQL-like syntax](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/web/controller/TableExamples.html), for example: `"SELECT * from syn12345"`
            resultsAs: select whether results are returned as a CSV file ("csv") or incrementally downloaded as sets of rows ("rowset")
            limit: (rowset only) Specify the maximum number of rows to be returned, defaults to None
            offset: (rowset only) Don't return the first n rows, defaults to None
            quoteCharacter: (csv only) default double quote
            escapeCharacter: (csv only) default backslash
            lineEnd: (csv only) defaults to os.linesep
            separator: (csv only) defaults to comma
            header: (csv only) True by default
            includeRowIdAndRowVersion: (csv only) True by default
            downloadLocation: (csv only) directory path to download the CSV file to

        Returns:
            A [TableQueryResult][synapseclient.table.TableQueryResult] or [CsvFileTable][synapseclient.table.CsvFileTable] object

        NOTE:
            When performing queries on frequently updated tables, the table can be inaccessible for a period leading
              to a timeout of the query.  Since the results are guaranteed to eventually be returned you can change the
              max timeout by setting the table_query_timeout variable of the Synapse object:

                  # Sets the max timeout to 5 minutes.
                  syn.table_query_timeout = 300

        Example: Using this function (DEPRECATED)
            Getting query results as a DataFrame:

                results = syn.tableQuery("SELECT * FROM syn12345")
                df = results.asDataFrame()

            Getting query results as a CSV file:

                results = syn.tableQuery("SELECT * FROM syn12345", resultsAs="csv", downloadLocation="./my_data/")

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Synchronous query (recommended for most use cases)
            results = query(query="SELECT * FROM syn12345")
            print(results)

            # Query with specific options
            results = query(
                query="SELECT * FROM syn12345",
                include_row_id_and_row_version=True,
                convert_to_datetime=True
            )
            print(results)

            # Download query results to a CSV file
            file_path = query(
                query="SELECT * FROM syn12345",
                download_location="./my_data/",
                separator=",",
                quote_character='"',
                header=True
            )
            print(f"Results downloaded to: {file_path}")

            # Asynchronous query (for advanced use cases)
            async def async_query_example():
                results = await query_async(query="SELECT * FROM syn12345")
                print(results)

                # Download query results to a CSV file asynchronously
                file_path = await query_async(
                    query="SELECT * FROM syn12345",
                    download_location="./my_data/",
                    separator=",",
                    quote_character='"',
                    header=True
                )
                print(f"Results downloaded to: {file_path}")

            # Run the async example
            asyncio.run(async_query_example())
            ```

        """
        if resultsAs.lower() == "rowset":
            return TableQueryResult(self, query, **kwargs)
        elif resultsAs.lower() == "csv":
            # TODO: remove isConsistent because it has now been deprecated
            # from the backend
            if kwargs.get("isConsistent") is not None:
                kwargs.pop("isConsistent")
            return CsvFileTable.from_table_query(self, query, **kwargs)
        else:
            raise ValueError(
                "Unknown return type requested from tableQuery: " + str(resultsAs)
            )

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Use the `query_part_mask` methods on the `Table`, `EntityView`, `SubmissionView`, `MaterializedView`, or `Dataset` classes instead.",
    )
    def _queryTable(
        self,
        query: str,
        limit: int = None,
        offset: int = None,
        isConsistent: bool = True,
        partMask=None,
    ) -> TableQueryResult:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `query_part_mask` or `query_part_mask_async` methods on the `Table`, `EntityView`, `SubmissionView`, `MaterializedView`, or `Dataset` classes instead.

        Query a table and return the first page of results as a [QueryResultBundle](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/QueryResultBundle.html).
        If the result contains a *nextPageToken*, following pages a retrieved by calling [_queryTableNext][].

        Arguments:
            query:        A sql query
            limit:        The optional limit to the results
            offset:       The optional offset into the results
            isConsistent: Whether the index is inconsistent with the true state of the table
            partMask:     Optional, default all. The 'partsMask' is a bit field for requesting
                          different elements in the resulting JSON bundle.
                          Query Results (queryResults) = 0x1
                          Query Count (queryCount) = 0x2
                          Select Columns (selectColumns) = 0x4
                          Max Rows Per Page (maxRowsPerPage) = 0x8

        Returns:
            The first page of results as a QueryResultBundle

        Example: Using this function (DEPRECATED)
            Query a table with part mask:

                result = syn._queryTable(
                    query="SELECT * FROM syn123",
                    partMask=0x1
                )

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            table = Table(id="syn123")
            result = table.query_part_mask(
                query="SELECT * FROM syn123",
                part_mask=0x1  # QUERY_RESULTS
            )

            # Or using the async version
            async def async_query_example():
                table = Table(id="syn123")
                result = await table.query_part_mask_async(
                    query="SELECT * FROM syn123",
                    part_mask=0x1  # QUERY_RESULTS
                )
                print(result)

            # Run the async example
            asyncio.run(async_query_example())
            ```

        """
        # See: <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/QueryBundleRequest.html>
        query_bundle_request = {
            "concreteType": "org.sagebionetworks.repo.model.table.QueryBundleRequest",
            "query": {
                "sql": query,
                "isConsistent": isConsistent,
                "includeEntityEtag": True,
            },
        }

        if partMask:
            query_bundle_request["partMask"] = partMask
        if limit is not None:
            query_bundle_request["query"]["limit"] = limit
        if offset is not None:
            query_bundle_request["query"]["offset"] = offset
        query_bundle_request["query"]["isConsistent"] = isConsistent

        uri = "/entity/{id}/table/query/async".format(
            id=extract_synapse_id_from_query(query)
        )

        return self._waitForAsync(uri=uri, request=query_bundle_request)

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Use the `query_part_mask` method on the `Table`, `EntityView`, `SubmissionView`, `MaterializedView`, or `Dataset` classes instead.",
    )
    def _queryTableNext(self, nextPageToken: str, tableId: str) -> TableQueryResult:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `query_part_mask` or `query_part_mask_async` methods on the `Table`, `EntityView`, `SubmissionView`, `MaterializedView`, or `Dataset` classes instead.

        Retrieve following pages if the result contains a *nextPageToken*

        Arguments:
            nextPageToken: Forward this token to get the next page of results.
            tableId:       The Synapse ID of the table

        Returns:
            The following page of results as a QueryResultBundle

        Example: Using this function (DEPRECATED)
            Get the next page of results:

                result = syn._queryTableNext(
                    nextPageToken="some_token",
                    tableId="syn123"
                )

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            table = Table(id="syn123")

            # For pagination, use LIMIT and OFFSET directly in the SQL query instead of nextPageToken.
            # LIMIT controls the number of rows returned per page, OFFSET skips the specified number of rows.
            # For example: LIMIT 100 OFFSET 100 returns rows 101-200, LIMIT 100 OFFSET 200 returns rows 201-300, etc.
            result = table.query_part_mask(
                query="SELECT * FROM syn123 LIMIT 100 OFFSET 100",
                part_mask=0x1  # QUERY_RESULTS
            )

            # Or using the async version
            async def async_query_example():
                table = Table(id="syn123")
                result = await table.query_part_mask_async(
                    query="SELECT * FROM syn123 LIMIT 100 OFFSET 100",
                    part_mask=0x1  # QUERY_RESULTS
                )
                print(result)

            # Run the async example
            asyncio.run(async_query_example())
            ```
        """
        uri = "/entity/{id}/table/query/nextPage/async".format(id=tableId)
        return self._waitForAsync(uri=uri, request=nextPageToken)

    def _uploadCsv(
        self,
        filepath: str,
        schema: Union[Entity, str],
        updateEtag: str = None,
        quoteCharacter: str = '"',
        escapeCharacter: str = "\\",
        lineEnd: str = os.linesep,
        separator: str = ",",
        header: bool = True,
        linesToSkip: int = 0,
    ) -> dict:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `_chunk_and_upload_csv` method on [synapseclient.models.Table][] instead for efficient CSV processing.

        Send an [UploadToTableRequest](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/UploadToTableRequest.html) to Synapse.

        Arguments:
            filepath:        Path of a [CSV](https://en.wikipedia.org/wiki/Comma-separated_values) file.
            schema:          A table entity or its Synapse ID.
            updateEtag:      Any RowSet returned from Synapse will contain the current etag of the change set.
                             To update any rows from a RowSet the etag must be provided with the POST.
            quoteCharacter:  Quotation character
            escapeCharacter: Escape character
            lineEnd:         The string used to separate lines
            separator:       Separator character
            header:          Whether to set the first line as header.
            linesToSkip:     The number of lines to skip from the start of the file.
                             The default value of 0 will be used if this is not provided by the caller.

        Returns:
            [UploadToTableResult](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/UploadToTableResult.html)

        Example: Using this function (DEPRECATED)
            Uploading a CSV file to an existing table:

                response = syn._uploadCsv(
                    filepath='/path/to/table.csv',
                    schema='syn123'
                )

        Example: Migration to new method
            &nbsp;

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

            TABLE_ID ="syn123"  # Replace with your table ID
            PATH = "/path/to/table.csv"

            # Login to Synapse
            # syn = Synapse()
            # syn.login()

            # Create CSV table descriptor with your settings
            csv_descriptor = CsvTableDescriptor(
                is_first_line_header=True,
                separator=",",  # or your custom separator
                quote_character='"',  # or your custom quote character
                escape_character="\\",  # or your custom escape character
            )

            # Define an async function to upload CSV with chunk method
            async def upload_csv_with_chunk_method(table_id, path):
                table = await Table(id=table_id).get_async(include_columns=True)
                await table._chunk_and_upload_csv(
                    path_to_csv=path,
                    insert_size_bytes=900 * 1024 * 1024,  # 900MB chunks
                    csv_table_descriptor=csv_descriptor,
                    schema_change_request=None,  # Add schema changes if needed
                    client=syn,
                    job_timeout=600,
                    additional_changes=None  # Add additional changes if needed
                )

            # Run the async function
            asyncio.run(upload_csv_with_chunk_method(table_id=TABLE_ID, path=PATH))
            ```
        """
        return wrap_async_to_sync(
            self._uploadCsv_async(
                filepath,
                schema,
                updateEtag,
                quoteCharacter,
                escapeCharacter,
                lineEnd,
                separator,
                header,
                linesToSkip,
            )
        )

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Use the `_chunk_and_upload_csv` method on the `from synapseclient.models import Table` class instead. "
        "Check the docstring for the replacement function example.",
    )
    async def _uploadCsv_async(
        self,
        filepath: str,
        schema: Union[Entity, str],
        updateEtag: str = None,
        quoteCharacter: str = '"',
        escapeCharacter: str = "\\",
        lineEnd: str = os.linesep,
        separator: str = ",",
        header: bool = True,
        linesToSkip: int = 0,
    ) -> dict:
        """
        Async version of [_uploadCsv][]
        """

        fileHandleId = await multipart_upload_file_async(
            self, filepath, content_type="text/csv"
        )

        uploadRequest = {
            "concreteType": "org.sagebionetworks.repo.model.table.UploadToTableRequest",
            "csvTableDescriptor": {
                "isFirstLineHeader": header,
                "quoteCharacter": quoteCharacter,
                "escapeCharacter": escapeCharacter,
                "lineEnd": lineEnd,
                "separator": separator,
            },
            "linesToSkip": linesToSkip,
            "tableId": id_of(schema),
            "uploadFileHandleId": fileHandleId,
        }

        if updateEtag:
            uploadRequest["updateEtag"] = updateEtag

        response = self._async_table_update(schema, changes=[uploadRequest], wait=True)
        self._check_table_transaction_response(response)

        return response

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _check_table_transaction_response(self, response):
        for result in response["results"]:
            result_type = result["concreteType"]

            if result_type in {
                concrete_types.ROW_REFERENCE_SET_RESULTS,
                concrete_types.TABLE_SCHEMA_CHANGE_RESPONSE,
                concrete_types.UPLOAD_TO_TABLE_RESULT,
            }:
                # if these fail, it we would have gotten an HttpError before the results came back
                pass
            elif result_type == concrete_types.ENTITY_UPDATE_RESULTS:
                # TODO: output full response to error file when the logging JIRA issue gets pulled in
                successful_updates = []
                failed_updates = []
                for update_result in result["updateResults"]:
                    failure_code = update_result.get("failureCode")
                    failure_message = update_result.get("failureMessage")
                    entity_id = update_result.get("entityId")
                    if failure_code or failure_message:
                        failed_updates.append(update_result)
                    else:
                        successful_updates.append(entity_id)

                if failed_updates:
                    raise SynapseError(
                        "Not all of the entities were updated."
                        " Successful updates: %s.  Failed updates: %s"
                        % (successful_updates, failed_updates)
                    )

            else:
                warnings.warn(
                    "Unexpected result from a table transaction of type [%s]."
                    " Please check the result to make sure it is correct. %s"
                    % (result_type, result)
                )

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Use the `query` or `query_async` functions from `synapseclient.models.Table` with `download_location` parameter instead. "
        "Check the docstring for the replacement function example.",
    )
    def _queryTableCsv(
        self,
        query: str,
        quoteCharacter: str = '"',
        escapeCharacter: str = "\\",
        lineEnd: str = os.linesep,
        separator: str = ",",
        header: bool = True,
        includeRowIdAndRowVersion: bool = True,
        downloadLocation: str = None,
    ) -> Tuple:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `query` or `query_async` functions from [synapseclient.models.Table][] with `download_location` parameter instead.

        Query a Synapse Table and download a CSV file containing the results.

        Sends a [DownloadFromTableRequest](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/DownloadFromTableRequest.html) to Synapse.

        Arguments:
            query:                     A sql query
            quoteCharacter:            Quotation character
            escapeCharacter:           Escape character
            lineEnd:                   The string used to separate lines
            separator:                 Separator character
            header:                    Whether to set the first line as header.
            includeRowIdAndRowVersion: Whether to set the first two columns contains the row ID and row version.
            downloadLocation:          The download location

        Returns:
            A tuple containing a [DownloadFromTableResult](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/DownloadFromTableResult.html)

        Example: Using this function (DEPRECATED)
            Query a table and download CSV:

                result, csv_path = syn._queryTableCsv(
                    query="SELECT * FROM syn123",
                    downloadLocation="/path/to/download",
                    quoteCharacter='"',
                    separator=","
                )

        Example: Migration to new method
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Synchronous query with CSV download
            csv_path = query(
                query="SELECT * FROM syn123",
                download_location="/path/to/download",
                quote_character='"',
                separator=",",
                header=True,
                include_row_id_and_row_version=True
            )
            print(f"CSV downloaded to: {csv_path}")

            # Asynchronous query with CSV download
            async def async_csv_download():
                csv_path = await query_async(
                    query="SELECT * FROM syn123",
                    download_location="/path/to/download",
                    quote_character='"',
                    separator=",",
                    header=True,
                    include_row_id_and_row_version=True
                )
                print(f"CSV downloaded to: {csv_path}")

            # Run the async example
            asyncio.run(async_csv_download())
            ```

        The DownloadFromTableResult object contains these fields:
         * headers:             ARRAY<STRING>, The list of ColumnModel IDs that describes the rows of this set.
         * resultsFileHandleId: STRING, The resulting file handle ID can be used to download the CSV file created by
                                this query.
         * concreteType:        STRING
         * etag:                STRING, Any RowSet returned from Synapse will contain the current etag of the change
                                set.
                                To update any rows from a RowSet the etag must be provided with the POST.
         * tableId:             STRING, The ID of the table identified in the from clause of the table query.
        """
        download_from_table_request = {
            "concreteType": "org.sagebionetworks.repo.model.table.DownloadFromTableRequest",
            "csvTableDescriptor": {
                "isFirstLineHeader": header,
                "quoteCharacter": quoteCharacter,
                "escapeCharacter": escapeCharacter,
                "lineEnd": lineEnd,
                "separator": separator,
            },
            "sql": query,
            "writeHeader": header,
            "includeRowIdAndRowVersion": includeRowIdAndRowVersion,
            "includeEntityEtag": True,
        }

        uri = "/entity/{id}/table/download/csv/async".format(
            id=extract_synapse_id_from_query(query)
        )
        download_from_table_result = self._waitForAsync(
            uri=uri, request=download_from_table_request
        )
        file_handle_id = download_from_table_result["resultsFileHandleId"]
        cached_file_path = self.cache.get(
            file_handle_id=file_handle_id, path=downloadLocation
        )
        if cached_file_path is not None:
            return download_from_table_result, cached_file_path

        if downloadLocation:
            download_dir = ensure_download_location_is_directory(
                download_location=downloadLocation
            )
        else:
            download_dir = self.cache.get_cache_dir(file_handle_id=file_handle_id)

        os.makedirs(download_dir, exist_ok=True)
        filename = f"SYNAPSE_TABLE_QUERY_{file_handle_id}.csv"
        path = wrap_async_to_sync(
            coroutine=download_by_file_handle(
                file_handle_id=file_handle_id,
                synapse_id=extract_synapse_id_from_query(query),
                entity_type="TableEntity",
                destination=os.path.join(download_dir, filename),
                synapse_client=self,
            )
        )

        return download_from_table_result, path

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Use the `.columns` attribute on table-like classes or the `add_column` method to store columns during the storage of these table-like classes. "
        "For individual column operations, use the synapseclient.api.table_services.post_columns function. "
        "Check the docstring for the replacement function example.",
    )
    def createColumn(
        self,
        name,
        columnType,
        maximumSize=None,
        defaultValue=None,
        enumValues=None,
    ):
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `.columns` attribute on table-like classes or `add_column` method to store columns during the storage of these table-like classes.

        Creates a new [synapseclient.table.Column][] in Synapse.

        Arguments:
            name: The name of the column
            columnType: The column type
            maximumSize: The maximum size of the column
            defaultValue: The default value of the column
            enumValues: The enum values of the column

        Returns:
            A [synapseclient.table.Column][] object

        Example: Using this function (DEPRECATED)
            Creating a column

                column = syn.createColumn(
                    name="my_column",
                    columnType="STRING",
                    maximumSize=100
                )

        Example: Migration to new methods
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Method 1: Create column and add to table using ColumnMixin
            column = Column(
                name="my_column",
                column_type=ColumnType.STRING,
                maximum_size=100
            )

            # Get an existing table and add the column
            table = Table(id="syn1234").get(include_columns=True)
            table.add_column(column)
            table.store()

            # Method 2: Create a new table with columns
            table = Table(
                name="My Table",
                parent_id="syn5678",
                columns=[
                    Column(name="column1", column_type=ColumnType.STRING),
                    Column(name="column2", column_type=ColumnType.INTEGER),
                ]
            )
            table.store()

            # Method 3: Use the async post_columns function directly
            async def create_columns():
                columns = [
                    Column(name="my_column", column_type=ColumnType.STRING, maximum_size=100)
                ]
                created_columns = await post_columns(columns)
                return created_columns

            # Run the async function
            created_columns = asyncio.run(create_columns())
            ```
        """
        columnModel = Column(
            name=name,
            columnType=columnType,
            maximumSize=maximumSize,
            defaultValue=defaultValue,
            enumValue=enumValues,
        )
        return Column(**self.restPOST("/column", json.dumps(columnModel)))

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. "
        "Use the `.columns` attribute on table-like classes or the `add_column` method to store columns during the storage of these table-like classes. "
        "For batch column operations, use the synapseclient.api.table_services.post_columns function. "
        "Check the docstring for the replacement function example.",
    )
    def createColumns(self, columns: typing.List[Column]) -> typing.List[Column]:
        """
        **Deprecated with replacement.** This method will be removed in 5.0.0.
        Use the `.columns` attribute on table-like classes or the `add_column` method to store columns during the storage of these table-like classes.

        Creates a batch of [synapseclient.table.Column][]'s within a single request.

        Arguments:
            columns: A list of [synapseclient.table.Column][]'s

        Returns:
            A list of [synapseclient.table.Column][]'s that have been created in Synapse

        Example: Using this function (DEPRECATED)
            Creating multiple columns

                columns = [
                    Column(name="col1", columnType="STRING"),
                    Column(name="col2", columnType="INTEGER")
                ]
                created_columns = syn.createColumns(columns)

        Example: Migration to new methods
            &nbsp;

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

            # Login to Synapse
            syn = Synapse()
            syn.login()

            # Method 1: Create columns and add to table using ColumnMixin
            columns = [
                Column(name="col1", column_type=ColumnType.STRING),
                Column(name="col2", column_type=ColumnType.INTEGER)
            ]

            # Get an existing table and add the columns
            table = Table(id="syn1234").get(include_columns=True)
            table.add_column(columns)
            table.store()

            # Method 2: Create a new table with columns
            table = Table(
                name="My Table",
                parent_id="syn5678",
                columns=[
                    Column(name="col1", column_type=ColumnType.STRING),
                    Column(name="col2", column_type=ColumnType.INTEGER),
                ]
            )
            table.store()

            # Method 3: Use the async post_columns function directly
            async def create_columns():
                columns = [
                    Column(name="col1", column_type=ColumnType.STRING),
                    Column(name="col2", column_type=ColumnType.INTEGER)
                ]
                created_columns = await post_columns(columns)
                return created_columns

            # Run the async function
            created_columns = asyncio.run(create_columns())
            ```
        """
        request_body = {
            "concreteType": "org.sagebionetworks.repo.model.ListWrapper",
            "list": list(columns),
        }
        response = self.restPOST("/column/batch", json.dumps(request_body))
        return [Column(**col) for col in response["list"]]

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _getColumnByName(self, schema: Schema, column_name: str) -> Column:
        """
        Given a schema and a column name, get the corresponding [Column][synapseclient.table.Column] object.

        Arguments:
            schema: The Schema is an [Entity][synapseclient.entity.Entity] that defines a set of columns in a table.
            column_name: The column name

        Returns:
            A Column object
        """
        for column in self.getColumns(schema):
            if column.name == column_name:
                return column
        return None

    @deprecated(
        version="4.14.0",
        reason="To be removed in 5.0.0. This function has no replacement.",
    )
    def downloadTableColumns(self, table, columns, downloadLocation=None, **kwargs):
        """
        Bulk download of table-associated files.

        Arguments:
            table: Table query result
            columns: A list of column names as strings
            downloadLocation: Directory into which to download the files

        Returns:
            A dictionary from file handle ID to path in the local file system.

        For example, consider a Synapse table whose ID is "syn12345" with two columns of type FILEHANDLEID named 'foo'
        and 'bar'. The associated files are JSON encoded, so we might retrieve the files from Synapse and load for the
        second 100 of those rows as shown here:

            import json

            results = syn.tableQuery('SELECT * FROM syn12345 LIMIT 100 OFFSET 100')
            file_map = syn.downloadTableColumns(results, ['foo', 'bar'])

            for file_handle_id, path in file_map.items():
                with open(path) as f:
                    data[file_handle_id] = f.read()

        """
        return wrap_async_to_sync(
            self.downloadTableColumns_async(table, columns, downloadLocation, **kwargs)
        )

    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1632
    async def downloadTableColumns_async(
        self, table, columns, downloadLocation=None, **kwargs
    ):
        """Async version of downloadTableColumns."""
        RETRIABLE_FAILURE_CODES = ["EXCEEDS_SIZE_LIMIT"]
        MAX_DOWNLOAD_TRIES = 100
        max_files_per_request = kwargs.get("max_files_per_request", 2500)
        # Rowset tableQuery result not allowed
        if isinstance(table, TableQueryResult):
            raise ValueError(
                "downloadTableColumn doesn't work with rowsets. Please use default tableQuery settings."
            )
        if isinstance(columns, str):
            columns = [columns]
        if not isinstance(columns, collections.abc.Iterable):
            raise TypeError("Columns parameter requires a list of column names")

        (
            file_handle_associations,
            file_handle_to_path_map,
        ) = self._build_table_download_file_handle_list(
            table,
            columns,
            downloadLocation,
        )

        self.logger.info(
            "Downloading %d files, %d cached locally"
            % (len(file_handle_associations), len(file_handle_to_path_map))
        )

        permanent_failures = collections.OrderedDict()

        attempts = 0
        while len(file_handle_associations) > 0 and attempts < MAX_DOWNLOAD_TRIES:
            attempts += 1

            file_handle_associations_batch = file_handle_associations[
                :max_files_per_request
            ]

            # ------------------------------------------------------------
            # call async service to build zip file
            # ------------------------------------------------------------

            # returns a BulkFileDownloadResponse:
            #   <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/file/BulkFileDownloadResponse.html>
            request = dict(
                concreteType="org.sagebionetworks.repo.model.file.BulkFileDownloadRequest",
                requestedFiles=file_handle_associations_batch,
            )
            response = self._waitForAsync(
                uri="/file/bulk/async",
                request=request,
                endpoint=self.fileHandleEndpoint,
            )

            # ------------------------------------------------------------
            # download zip file
            # ------------------------------------------------------------

            temp_dir = tempfile.mkdtemp()
            zipfilepath = os.path.join(temp_dir, "table_file_download.zip")
            try:
                zipfilepath = await download_by_file_handle(
                    file_handle_id=response["resultZipFileHandleId"],
                    synapse_id=table.tableId,
                    entity_type="TableEntity",
                    destination=zipfilepath,
                )
                # TODO handle case when no zip file is returned
                # TODO test case when we give it partial or all bad file handles
                # TODO test case with deleted fileHandleID
                # TODO return null for permanent failures

                # ------------------------------------------------------------
                # unzip into cache
                # ------------------------------------------------------------

                if downloadLocation:
                    download_dir = ensure_download_location_is_directory(
                        downloadLocation
                    )

                with zipfile.ZipFile(zipfilepath) as zf:
                    # the directory structure within the zip follows that of the cache:
                    # {fileHandleId modulo 1000}/{fileHandleId}/{fileName}
                    for summary in response["fileSummary"]:
                        if summary["status"] == "SUCCESS":
                            if not downloadLocation:
                                download_dir = self.cache.get_cache_dir(
                                    summary["fileHandleId"]
                                )

                            filepath = extract_zip_file_to_directory(
                                zf, summary["zipEntryName"], download_dir
                            )
                            self.cache.add(summary["fileHandleId"], filepath)
                            file_handle_to_path_map[summary["fileHandleId"]] = filepath
                        elif summary["failureCode"] not in RETRIABLE_FAILURE_CODES:
                            permanent_failures[summary["fileHandleId"]] = summary
            finally:
                if os.path.exists(zipfilepath):
                    os.remove(zipfilepath)

            # Do we have remaining files to download?
            file_handle_associations = [
                fha
                for fha in file_handle_associations
                if fha["fileHandleId"] not in file_handle_to_path_map
                and fha["fileHandleId"] not in permanent_failures.keys()
            ]

        # TODO if there are files we still haven't downloaded

        return file_handle_to_path_map

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _build_table_download_file_handle_list(self, table, columns, downloadLocation):
        # ------------------------------------------------------------
        # build list of file handles to download
        # ------------------------------------------------------------
        cols_not_found = [
            c for c in columns if c not in [h.name for h in table.headers]
        ]
        if len(cols_not_found) > 0:
            raise ValueError(
                "Columns not found: "
                + ", ".join('"' + col + '"' for col in cols_not_found)
            )
        col_indices = [i for i, h in enumerate(table.headers) if h.name in columns]
        # see: <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/file/BulkFileDownloadRequest.html>
        file_handle_associations = []
        file_handle_to_path_map = collections.OrderedDict()
        seen_file_handle_ids = (
            set()
        )  # ensure not sending duplicate requests for the same FileHandle IDs
        for row in table:
            for col_index in col_indices:
                file_handle_id = row[col_index]
                if is_integer(file_handle_id):
                    path_to_cached_file = self.cache.get(
                        file_handle_id, path=downloadLocation
                    )
                    if path_to_cached_file:
                        file_handle_to_path_map[file_handle_id] = path_to_cached_file
                    elif file_handle_id not in seen_file_handle_ids:
                        file_handle_associations.append(
                            dict(
                                associateObjectType="TableEntity",
                                fileHandleId=file_handle_id,
                                associateObjectId=table.tableId,
                            )
                        )
                    seen_file_handle_ids.add(file_handle_id)
                else:
                    warnings.warn("Weird file handle: %s" % file_handle_id)
        return file_handle_associations, file_handle_to_path_map

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _get_default_view_columns(self, view_type, view_type_mask=None):
        """Get default view columns"""
        uri = f"/column/tableview/defaults?viewEntityType={view_type}"
        if view_type_mask:
            uri += f"&viewTypeMask={view_type_mask}"
        return [Column(**col) for col in self.restGET(uri)["list"]]

    @deprecated(
        version="4.9.0",
        reason="To be removed in 5.0.0. This is a private function and has no direct replacement.",
    )
    def _get_annotation_view_columns(
        self, scope_ids: list, view_type: str, view_type_mask: str = None
    ) -> list:
        """
        Get all the columns of a submission of entity view based on existing annotations

        Arguments:
            scope_ids:      List of Evaluation Queue or Project/Folder Ids
            view_type:      The submissionview or entityview
            view_type_mask: Bit mask representing the types to include in the view.

        Returns:
            The list of columns
        """
        columns = []
        next_page_token = None
        while True:
            view_scope = {
                "concreteType": "org.sagebionetworks.repo.model.table.ViewColumnModelRequest",
                "viewScope": {
                    "scope": scope_ids,
                    "viewEntityType": view_type,
                    "viewTypeMask": view_type_mask,
                },
            }
            if next_page_token:
                view_scope["nextPageToken"] = next_page_token
            response = self._waitForAsync(
                uri="/column/view/scope/async", request=view_scope
            )
            columns.extend(Column(**column) for column in response["results"])
            next_page_token = response.get("nextPageToken")
            if next_page_token is None:
                break
        return columns

    ############################################################
    #              CRUD for Entities (properties)              #
    ############################################################

    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1623
    def _getEntity(
        self, entity: Union[str, dict, Entity], version: int = None
    ) -> Dict[str, Union[str, bool]]:
        """
        Get an entity from Synapse.

        Arguments:
            entity:  A Synapse ID, a dictionary representing an Entity, or a Synapse Entity object
            version: The version number to fetch

        Returns:
            A dictionary containing an Entity's properties
        """

        uri = "/entity/" + id_of(entity)
        if version:
            uri += "/version/%d" % version
        return self.restGET(uri)

    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1623
    def _createEntity(self, entity: Union[dict, Entity]) -> Dict[str, Union[str, bool]]:
        """
        Create a new entity in Synapse.

        Arguments:
            entity: A dictionary representing an Entity or a Synapse Entity object

        Returns:
            A dictionary containing an Entity's properties
        """

        return self.restPOST(uri="/entity", body=json.dumps(get_properties(entity)))

    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1623
    def _updateEntity(
        self,
        entity: Union[dict, Entity],
        incrementVersion: bool = True,
        versionLabel: str = None,
    ) -> Dict[str, Union[str, bool]]:
        """
        Update an existing entity in Synapse.

        Arguments:
            entity:           A dictionary representing an Entity or a Synapse Entity object
            incrementVersion: Whether to increment the entity version (if Versionable)
            versionLabel:     A label for the entity version (if Versionable)

        Returns:
            A dictionary containing an Entity's properties
        """

        uri = "/entity/%s" % id_of(entity)

        params = {}
        if is_versionable(entity):
            if versionLabel:
                # a versionLabel implicitly implies incrementing
                incrementVersion = True
            elif incrementVersion and "versionNumber" in entity:
                versionLabel = str(entity["versionNumber"] + 1)

            if incrementVersion:
                entity["versionLabel"] = versionLabel
                params["newVersion"] = "true"

        return self.restPUT(uri, body=json.dumps(get_properties(entity)), params=params)

    @deprecated(
        version="4.11.0",
        reason="To be removed in 5.0.0. "
        "Use `from synapseclient.operations import find_entity_id` instead.",
    )
    def findEntityId(self, name, parent=None):
        """
        Find an Entity given its name and parent.

        Arguments:
            name: Name of the entity to find
            parent: An Entity object or the Id of an entity as a string. Omit if searching for a Project by name

        Returns:
            The Entity ID or None if not found
        """
        # when we want to search for a project by name. set parentId as None instead of ROOT_ENTITY
        entity_lookup_request = {
            "parentId": id_of(parent) if parent else None,
            "entityName": name,
        }
        try:
            return self.restPOST(
                "/entity/child", body=json.dumps(entity_lookup_request)
            ).get("id")
        except SynapseHTTPError as e:
            if (
                e.response.status_code == 404
            ):  # a 404 error is raised if the entity does not exist
                return None
            raise

    ############################################################
    #                       Send Message                       #
    ############################################################
    def sendMessage(
        self, userIds, messageSubject, messageBody, contentType="text/plain"
    ):
        """
        send a message via Synapse.

        Arguments:
            userIds: A list of user IDs to which the message is to be sent
            messageSubject: The subject for the message
            messageBody: The body of the message
            contentType: optional contentType of message body (default="text/plain")
                            Should be one of "text/plain" or "text/html"

        Returns:
            The metadata of the created message
        """
        return wrap_async_to_sync(
            self.sendMessage_async(
                userIds=userIds,
                messageSubject=messageSubject,
                messageBody=messageBody,
                contentType=contentType,
            )
        )

    async def sendMessage_async(
        self, userIds, messageSubject, messageBody, contentType="text/plain"
    ):
        """Async version of sendMessage."""

        fileHandleId = await multipart_upload_string_async(
            self, messageBody, content_type=contentType
        )
        message = dict(
            recipients=userIds, subject=messageSubject, fileHandleId=fileHandleId
        )
        return self.restPOST(uri="/message", body=json.dumps(message))

    ############################################################
    #                   Low level Rest calls                   #
    ############################################################

    def _generate_headers(
        self, headers: Dict[str, str] = None, is_httpx: bool = False
    ) -> Dict[str, str]:
        """
        Generate headers (auth headers produced separately by credentials object)

        """
        if headers is None:
            headers = dict(self.default_headers)

        # Replace the `requests` package's default user-agent with the httpx user agent
        if is_httpx:
            httpx_agent = f"{httpx.__title__}/{httpx.__version__}"
            requests_agent = requests.utils.default_user_agent()
            agent = deepcopy(synapseclient.USER_AGENT)
            agent["User-Agent"] = agent["User-Agent"].replace(
                requests_agent, httpx_agent
            )
            headers.update(agent)
        else:
            headers.update(synapseclient.USER_AGENT)

        if self.user_agent:
            headers["User-Agent"] = (
                headers["User-Agent"] + " " + " ".join(self.user_agent)
            )

        return headers

    def _handle_synapse_http_error(self, response):
        """Raise errors as appropriate for returned Synapse http status codes"""

        try:
            exceptions._raise_for_status(response, verbose=self.debug)
        except exceptions.SynapseHTTPError as ex:
            # if we get a unauthenticated or forbidden error and the user is not logged in
            # then we raise it as an authentication error.
            # we can't know for certain that logging in to their particular account will grant them
            # access to this resource but more than likely it's the cause of this error.
            if response.status_code in (401, 403) and not self.credentials:
                raise SynapseAuthenticationError(
                    "You are not logged in and do not have access to a requested resource."
                ) from ex

            raise

    def _handle_httpx_synapse_http_error(self, response: httpx.Response) -> None:
        """Raise errors as appropriate for the HTTPX library returned Synapse http
        status codes

        Arguments:
            response: The HTTPX response object
        """

        try:
            exceptions._raise_for_status_httpx(
                response=response, verbose=self.debug, logger=self.logger
            )
        except exceptions.SynapseHTTPError as ex:
            # if we get a unauthenticated or forbidden error and the user is not logged in
            # then we raise it as an authentication error.
            # we can't know for certain that logging in to their particular account will grant them
            # access to this resource but more than likely it's the cause of this error.
            if response.status_code in (401, 403) and not self.credentials:
                raise SynapseAuthenticationError(
                    "You are not logged in and do not have access to a requested resource."
                ) from ex

            raise

    def _rest_call(
        self,
        method,
        uri,
        data,
        endpoint,
        headers,
        retryPolicy,
        requests_session,
        **kwargs,
    ):
        """
        Sends an HTTP request to the Synapse server.

        Arguments:
            method:           The method to implement Create, Read, Update, Delete operations.
                              Should be post, get, put, delete.
            uri:              URI on which the method is performed
            endpoint:         Server endpoint, defaults to self.repoEndpoint
            headers:          Dictionary of headers to use rather than the API-key-signed default set of headers
            retryPolicy:      A retry policy
            requests_session: An external [requests.Session object](https://requests.readthedocs.io/en/latest/user/advanced/) to use when making this specific call
            kwargs:           Any other arguments taken by a
                              [request](http://docs.python-requests.org/en/latest/) method

        Returns:
            JSON encoding of response
        """
        self.logger.debug(f"Sending {method} request to {uri}")
        uri, headers = self._build_uri_and_headers(
            uri, endpoint=endpoint, headers=headers
        )

        retryPolicy = self._build_retry_policy(retryPolicy)
        requests_session = requests_session or self._requests_session

        auth = kwargs.pop("auth", self.credentials)
        requests_method_fn = getattr(requests_session, method)
        timeout = kwargs.pop("timeout", self._http_timeout_seconds)
        response = with_retry(
            lambda: requests_method_fn(
                uri,
                data=data,
                headers=headers,
                auth=auth,
                timeout=timeout,
                **kwargs,
            ),
            verbose=self.debug,
            **retryPolicy,
        )
        self._handle_synapse_http_error(response)
        return response

    def restGET(
        self,
        uri,
        endpoint=None,
        headers=None,
        retryPolicy={},
        requests_session=None,
        **kwargs,
    ):
        """
        Sends an HTTP GET request to the Synapse server.

        Arguments:
            uri: URI on which get is performed
            endpoint: Server endpoint, defaults to self.repoEndpoint
            headers: Dictionary of headers to use rather than the API-key-signed default set of headers
            requests_session: An external [requests.Session object](https://requests.readthedocs.io/en/latest/user/advanced/) to use when making this specific call
            kwargs: Any other arguments taken by a [request](http://docs.python-requests.org/en/latest/) method

        Returns:
            JSON encoding of response
        """
        response = self._rest_call(
            "get", uri, None, endpoint, headers, retryPolicy, requests_session, **kwargs
        )
        return self._return_rest_body(response)

    def restPOST(
        self,
        uri,
        body,
        endpoint=None,
        headers=None,
        retryPolicy={},
        requests_session=None,
        **kwargs,
    ):
        """
        Sends an HTTP POST request to the Synapse server.

        Arguments:
            uri: URI on which get is performed
            endpoint: Server endpoint, defaults to self.repoEndpoint
            body: The payload to be delivered
            headers: Dictionary of headers to use rather than the API-key-signed default set of headers
            requests_session: An external [requests.Session object](https://requests.readthedocs.io/en/latest/user/advanced/) to use when making this specific call
            kwargs: Any other arguments taken by a [request](http://docs.python-requests.org/en/latest/) method

        Returns:
            JSON encoding of response
        """
        response = self._rest_call(
            "post",
            uri,
            body,
            endpoint,
            headers,
            retryPolicy,
            requests_session,
            **kwargs,
        )
        return self._return_rest_body(response)

    def restPUT(
        self,
        uri,
        body=None,
        endpoint=None,
        headers=None,
        retryPolicy={},
        requests_session=None,
        **kwargs,
    ):
        """
        Sends an HTTP PUT request to the Synapse server.

        Arguments:
            uri: URI on which get is performed
            endpoint: Server endpoint, defaults to self.repoEndpoint
            body: The payload to be delivered
            headers: Dictionary of headers to use rather than the API-key-signed default set of headers
            requests_session: An external [requests.Session object](https://requests.readthedocs.io/en/latest/user/advanced/) to use when making this specific call
            kwargs: Any other arguments taken by a [request](http://docs.python-requests.org/en/latest/) method

        Returns
            JSON encoding of response
        """
        response = self._rest_call(
            "put",
            uri,
            body,
            endpoint,
            headers,
            retryPolicy,
            requests_session,
            **kwargs,
        )
        return self._return_rest_body(response)

    def restDELETE(
        self,
        uri,
        endpoint=None,
        headers=None,
        retryPolicy={},
        requests_session=None,
        **kwargs,
    ):
        """
        Sends an HTTP DELETE request to the Synapse server.

        Arguments:
            uri: URI of resource to be deleted
            endpoint: Server endpoint, defaults to self.repoEndpoint
            headers: Dictionary of headers to use rather than the API-key-signed default set of headers
            requests_session: An external [requests.Session object](https://requests.readthedocs.io/en/latest/user/advanced/) to use when making this specific call
            kwargs: Any other arguments taken by a [request](http://docs.python-requests.org/en/latest/) method

        """
        self._rest_call(
            "delete",
            uri,
            None,
            endpoint,
            headers,
            retryPolicy,
            requests_session,
            **kwargs,
        )

    def _build_uri_and_headers(
        self,
        uri: str,
        endpoint: str = None,
        headers: Dict[str, str] = None,
        is_httpx: bool = False,
    ) -> Tuple[str, Dict[str, str]]:
        """Returns a tuple of the URI and headers to request with."""

        if endpoint is None:
            endpoint = self.repoEndpoint

        trace.get_current_span().set_attributes({"server.address": endpoint})

        # Check to see if the URI is incomplete (i.e. a Synapse URL)
        # In that case, append a Synapse endpoint to the URI
        parsedURL = urllib_urlparse.urlparse(uri)
        if parsedURL.netloc == "":
            uri = endpoint + uri

        if headers is None:
            headers = self._generate_headers(is_httpx=is_httpx)
        return uri, headers

    def _build_retry_policy(self, retryPolicy={}):
        """Returns a retry policy to be passed onto _with_retry."""

        defaults = dict(STANDARD_RETRY_PARAMS)
        defaults.update(retryPolicy)
        return defaults

    def _build_retry_policy_async(
        self, retry_policy: Dict[str, Any] = {}
    ) -> Dict[str, Any]:
        """Returns a retry policy to be passed onto with_retry_time_based_async."""

        defaults = dict(STANDARD_RETRY_ASYNC_PARAMS)
        defaults.update(retry_policy)
        return defaults

    def _return_rest_body(self, response) -> Union[Dict[str, Any], str]:
        """Returns either a dictionary or a string depending on the 'content-type' of the response."""
        if is_json(response.headers.get("content-type", None)):
            return response.json()
        return response.text

    async def _rest_call_async(
        self,
        method: str,
        uri: str,
        data: Any,
        endpoint: str,
        headers: Dict[str, str],
        retry_policy: Dict[str, Any],
        requests_session_async_synapse: httpx.AsyncClient,
        **kwargs,
    ) -> Union[httpx.Response, None]:
        """
        Sends an HTTP request to the Synapse server.

        Arguments:
            method: The method to implement Create, Read, Update, Delete operations.
                Should be post, get, put, delete.
            uri: URI on which the method is performed.
            data: The payload to be delivered.
            endpoint: Server endpoint, defaults to self.repoEndpoint
            headers: Dictionary of headers to use.
            retry_policy: A retry policy that matches the arguments of
                [synapseclient.core.retry.with_retry_time_based_async][].
            requests_session_async_synapse: The async client to use when making this
                specific call.
            kwargs: Any other arguments taken by a
                [request](https://www.python-httpx.org/api/) method

        Returns:
            JSON encoding of response
        """
        self.logger.debug(f"Sending {method} request to {uri}")
        uri, headers = self._build_uri_and_headers(
            uri, endpoint=endpoint, headers=headers, is_httpx=True
        )

        retry_policy = self._build_retry_policy_async(retry_policy)
        requests_session = (
            requests_session_async_synapse
            or self._get_requests_session_async_synapse(
                asyncio_event_loop=asyncio.get_running_loop()
            )
        )

        auth = kwargs.pop("auth", self.credentials)
        requests_method_fn = getattr(requests_session, method)
        if data:
            response = await with_retry_time_based_async(
                lambda: requests_method_fn(
                    uri,
                    content=data,
                    headers=headers,
                    auth=auth,
                    **kwargs,
                ),
                verbose=self.debug,
                **retry_policy,
            )
        else:
            response = await with_retry_time_based_async(
                lambda: requests_method_fn(
                    uri,
                    headers=headers,
                    auth=auth,
                    **kwargs,
                ),
                verbose=self.debug,
                **retry_policy,
            )

        self._handle_httpx_synapse_http_error(response)

        return response

    async def rest_get_async(
        self,
        uri: str,
        endpoint: str = None,
        headers: httpx.Headers = None,
        retry_policy: Dict[str, Any] = {},
        requests_session_async_synapse: httpx.AsyncClient = None,
        **kwargs,
    ) -> Union[Dict[str, Any], str, None]:
        """
        Sends an HTTP GET request to the Synapse server.

        Arguments:
            uri: URI on which get is performed
            endpoint: Server endpoint, defaults to self.repoEndpoint
            headers: Dictionary of headers to use.
            retry_policy: A retry policy that matches the arguments of
                [synapseclient.core.retry.with_retry_time_based_async][].
            requests_session_async_synapse: The async client to use when making this
                specific call.
            kwargs: Any other arguments taken by a
                [request](https://www.python-httpx.org/api/) method

        Returns:
            JSON encoding of response
        """
        response = await self._rest_call_async(
            "get",
            uri,
            None,
            endpoint,
            headers,
            retry_policy,
            requests_session_async_synapse,
            **kwargs,
        )
        return self._return_rest_body(response)

    async def rest_post_async(
        self,
        uri: str,
        body: Any = None,
        endpoint: str = None,
        headers: httpx.Headers = None,
        retry_policy: Dict[str, Any] = {},
        requests_session_async_synapse: httpx.AsyncClient = None,
        **kwargs,
    ) -> Union[Dict[str, Any], str]:
        """
        Sends an HTTP POST request to the Synapse server.

        Arguments:
            uri: URI on which get is performed
            body: The payload to be delivered
            endpoint: Server endpoint, defaults to self.repoEndpoint
            headers: Dictionary of headers to use.
            retry_policy: A retry policy that matches the arguments of
                [synapseclient.core.retry.with_retry_time_based_async][].
            requests_session_async_synapse: The async client to use when making this
                specific call.
            kwargs: Any other arguments taken by a
                [request](https://www.python-httpx.org/api/) method

        Returns:
            JSON encoding of response
        """
        response = await self._rest_call_async(
            "post",
            uri,
            body,
            endpoint,
            headers,
            retry_policy,
            requests_session_async_synapse,
            **kwargs,
        )
        return self._return_rest_body(response)

    async def rest_put_async(
        self,
        uri: str,
        body: Any = None,
        endpoint: str = None,
        headers: httpx.Headers = None,
        retry_policy: Dict[str, Any] = {},
        requests_session_async_synapse: httpx.AsyncClient = None,
        **kwargs,
    ) -> Union[Dict[str, Any], str]:
        """
        Sends an HTTP PUT request to the Synapse server.

        Arguments:
            uri: URI on which get is performed
            body: The payload to be delivered.
            endpoint: Server endpoint, defaults to self.repoEndpoint
            headers: Dictionary of headers to use.
            retry_policy: A retry policy that matches the arguments of
                [synapseclient.core.retry.with_retry_time_based_async][].
            requests_session_async_synapse: The async client to use when making this
                specific call.
            kwargs: Any other arguments taken by a
                [request](https://www.python-httpx.org/api/) method

        Returns
            JSON encoding of response
        """
        response = await self._rest_call_async(
            "put",
            uri,
            body,
            endpoint,
            headers,
            retry_policy,
            requests_session_async_synapse,
            **kwargs,
        )
        return self._return_rest_body(response)

    async def rest_delete_async(
        self,
        uri: str,
        endpoint: str = None,
        headers: httpx.Headers = None,
        retry_policy: Dict[str, Any] = {},
        requests_session_async_synapse: httpx.AsyncClient = None,
        **kwargs,
    ) -> None:
        """
        Sends an HTTP DELETE request to the Synapse server.

        Arguments:
            uri: URI of resource to be deleted
            endpoint: Server endpoint, defaults to self.repoEndpoint
            headers: Dictionary of headers to use.
            retry_policy: A retry policy that matches the arguments of
                [synapseclient.core.retry.with_retry_time_based_async][].
            requests_session_async_synapse: The async client to use when making this
                specific call
            kwargs: Any other arguments taken by a [request](https://www.python-httpx.org/api/) method

        """
        await self._rest_call_async(
            "delete",
            uri,
            None,
            endpoint,
            headers,
            retry_policy,
            requests_session_async_synapse,
            **kwargs,
        )

Methods:

login

login(email: str = None, silent: bool = False, authToken: str = None, profile: str = 'default') -> None

Valid combinations of login() arguments:

• authToken
• Profile-based authentication (from .synapseConfig)

If no login arguments are provided or only username is provided, login() will attempt to log in using information from these sources (in order of preference):

1. .synapseConfig file (supports multiple profiles)(in user home folder unless configured otherwise)
2. User defined arguments during a CLI session
3. User's Personal Access Token (aka: Synapse Auth Token) from the environment variable: SYNAPSE_AUTH_TOKEN
4. Retrieves user's authentication token from AWS SSM Parameter store (if configured)

PARAMETER	DESCRIPTION
email	Synapse user name (or an email address associated with a Synapse account) TYPE: str DEFAULT: None
authToken	A bearer authorization token, e.g. a personal access token. TYPE: str DEFAULT: None
silent	Defaults to False. Suppresses the "Welcome ...!" message. TYPE: bool DEFAULT: False
profile	Profile to use from .synapseConfig (default: "default"). TYPE: str DEFAULT: 'default'

Example: Logging in - Logging in using a specific profile: import synapseclient syn = synapseclient.login(profile="user1) > Welcome, username! You are using the user1 profile

• Logging in with an authentication token: import synapseclient syn = synapseclient.login(authToken = "your_auth_token")) > Welcome, username!

Source code in synapseclient/client.py

def login(
    self,
    email: str = None,
    silent: bool = False,
    authToken: str = None,
    profile: str = "default",
) -> None:
    """
    Valid combinations of login() arguments:

    - authToken
    - Profile-based authentication (from .synapseConfig)

    If no login arguments are provided or only username is provided, login() will attempt to log in using
     information from these sources (in order of preference):

    1. .synapseConfig file (supports multiple profiles)(in user home folder unless configured otherwise)
    2. User defined arguments during a CLI session
    3. User's Personal Access Token (aka: Synapse Auth Token)
        from the environment variable: SYNAPSE_AUTH_TOKEN
    4. Retrieves user's authentication token from AWS SSM Parameter store (if configured)

    Arguments:
        email (str): Synapse user name (or an email address associated with a Synapse account)
        authToken (str): A bearer authorization token, e.g. a
            [personal access token](https://python-docs.synapse.org/tutorials/authentication/).
        silent (bool): Defaults to False.  Suppresses the "Welcome ...!" message.
        profile (str): Profile to use from .synapseConfig (default: "default").

    Example: Logging in
    - Logging in using a specific profile:
            import synapseclient
            syn = synapseclient.login(profile="user1)
            > Welcome, username! You are using the user1 profile

    - Logging in with an authentication token:
        import synapseclient
        syn = synapseclient.login(authToken = "your_auth_token"))
        > Welcome, username!
    """
    # Note: the order of the logic below reflects the ordering in the docstring above.

    # Check version before logging in
    if not self.skip_checks:
        version_check(logger=self.logger)

    # Make sure to invalidate the existing session
    self.logout()

    user_login_args = UserLoginArgs(
        profile=profile, username=email, auth_token=authToken
    )
    credential_provider_chain = get_default_credential_chain()
    self.credentials = credential_provider_chain.get_credentials(
        syn=self, user_login_args=user_login_args
    )

    # Final check on login success
    if not self.credentials:
        raise SynapseNoCredentialsError(
            f"No valid authentication credentials provided.\n"
            f"Tried profile: '{profile}', email: '{email or 'N/A'}'.\n"
            "Check your `.synapseConfig` or ensure the provided auth token is valid."
        )

    if not silent:
        display_name = self.credentials.displayname or self.credentials.username
        if (
            not self.credentials.profile_name
            or self.credentials.profile_name.lower()
            == config_file_constants.AUTHENTICATION_SECTION_NAME
        ):
            self.logger.info(f"Welcome, {display_name}!\n")
        else:
            self.logger.info(
                f"Welcome, {display_name}! You are using the '{self.credentials.profile_name}' profile."
            )

logout

logout() -> None

Removes authentication information from the Synapse client.

RETURNS	DESCRIPTION
None	None

Source code in synapseclient/client.py

def logout(self) -> None:
    """
    Removes authentication information from the Synapse client.

    Returns:
        None
    """
    self.credentials = None

get

get(entity, **kwargs)

Gets a Synapse entity from the repository service.

PARAMETER	DESCRIPTION
entity	A Synapse ID (e.g. syn123 or syn123.1, with .1 denoting version), a Synapse Entity object, a plain dictionary in which 'id' maps to a Synapse ID or a local file that is stored in Synapse (found by the file MD5)
version	The specific version to get. Defaults to the most recent version. If not denoted in the entity input.
downloadFile	Whether associated files(s) should be downloaded. Defaults to True.
downloadLocation	Directory where to download the Synapse File Entity. Defaults to the local cache.
followLink	Whether the link returns the target Entity. Defaults to False.
ifcollision	Determines how to handle file collisions. May be "overwrite.local", "keep.local", or "keep.both". Defaults to "keep.both".
limitSearch	A Synanpse ID used to limit the search in Synapse if entity 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.
md5	The MD5 checksum for the file, if known. Otherwise if the file is a local file, it will be calculated automatically.

RETURNS	DESCRIPTION
	A new Synapse Entity object of the appropriate type.

Using this function

Download file into cache

entity = syn.get('syn1906479')
print(entity.name)
print(entity.path)

Download file into current working directory

entity = syn.get('syn1906479', downloadLocation='.')
print(entity.name)
print(entity.path)

Determine the provenance of a locally stored file as indicated in Synapse

entity = syn.get('/path/to/file.txt', limitSearch='syn12312')
print(syn.getProvenance(entity))

Source code in synapseclient/client.py

@deprecated(
    version="4.11.0",
    reason="To be removed in 5.0.0. "
    "Use `from synapseclient.operations import get` instead.",
)
def get(self, entity, **kwargs):
    """
    Gets a Synapse entity from the repository service.

    Arguments:
        entity:           A Synapse ID (e.g. syn123 or syn123.1, with .1 denoting version), a Synapse Entity object,
                          a plain dictionary in which 'id' maps to a Synapse ID or a local file that is stored in
                          Synapse (found by the file MD5)
        version:          The specific version to get.
                            Defaults to the most recent version. If not denoted in the entity input.
        downloadFile:     Whether associated files(s) should be downloaded.
                            Defaults to True.
        downloadLocation: Directory where to download the Synapse File Entity.
                            Defaults to the local cache.
        followLink:       Whether the link returns the target Entity.
                            Defaults to False.
        ifcollision:      Determines how to handle file collisions.
                            May be "overwrite.local", "keep.local", or "keep.both".
                            Defaults to "keep.both".
        limitSearch:      A Synanpse ID used to limit the search in Synapse if entity 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.
        md5: The MD5 checksum for the file, if known. Otherwise if the file is a
            local file, it will be calculated automatically.

    Returns:
        A new Synapse Entity object of the appropriate type.

    Example: Using this function
        Download file into cache

            entity = syn.get('syn1906479')
            print(entity.name)
            print(entity.path)

        Download file into current working directory

            entity = syn.get('syn1906479', downloadLocation='.')
            print(entity.name)
            print(entity.path)

        Determine the provenance of a locally stored file as indicated in Synapse

            entity = syn.get('/path/to/file.txt', limitSearch='syn12312')
            print(syn.getProvenance(entity))
    """
    return wrap_async_to_sync(self.get_async(entity, **kwargs))

store

store(obj, *, createOrUpdate=True, forceVersion=True, versionLabel=None, isRestricted=False, activity=None, used=None, executed=None, activityName=None, activityDescription=None, set_annotations=True)

Creates a new Entity or updates an existing Entity, uploading any files in the process.

PARAMETER	DESCRIPTION
obj	A Synapse Entity, Evaluation, or Wiki
used	The Entity, Synapse ID, or URL used to create the object (can also be a list of these) DEFAULT: None
executed	The Entity, Synapse ID, or URL representing code executed to create the object (can also be a list of these) DEFAULT: None
activity	Activity object specifying the user's provenance. DEFAULT: None
activityName	Activity name to be used in conjunction with used and executed. DEFAULT: None
activityDescription	Activity description to be used in conjunction with used and executed. DEFAULT: None
createOrUpdate	Indicates whether the method should automatically perform an update if the 'obj' conflicts with an existing Synapse object. DEFAULT: True
forceVersion	Indicates whether the method should increment the version of the object even if nothing has changed. DEFAULT: True
versionLabel	Arbitrary string used to label the version. DEFAULT: None
isRestricted	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. DEFAULT: False
set_annotations	If True, set the annotations on the entity. If False, do not set the annotations. DEFAULT: True

RETURNS	DESCRIPTION
	A Synapse Entity, Evaluation, or Wiki

Using this function

Creating a new Project:

from synapseclient import Project

project = Project('My uniquely named project')
project = syn.store(project)

Adding files with provenance (aka: Activity):

from synapseclient import File, Activity

A synapse entity syn1906480 contains data and an entity syn1917825 contains code

activity = Activity(
    'Fancy Processing',
    description='No seriously, really fancy processing',
    used=['syn1906480', 'http://data_r_us.com/fancy/data.txt'],
    executed='syn1917825')

test_entity = File('/path/to/data/file.xyz', description='Fancy new data', parent=project)
test_entity = syn.store(test_entity, activity=activity)

Source code in synapseclient/client.py

@deprecated(
    version="4.11.0",
    reason="To be removed in 5.0.0. "
    "Use `from synapseclient.operations import store` instead.",
)
def store(
    self,
    obj,
    *,
    createOrUpdate=True,
    forceVersion=True,
    versionLabel=None,
    isRestricted=False,
    activity=None,
    used=None,
    executed=None,
    activityName=None,
    activityDescription=None,
    set_annotations=True,
):
    """
    Creates a new Entity or updates an existing Entity, uploading any files in the process.

    Arguments:
        obj: A Synapse Entity, Evaluation, or Wiki
        used: The Entity, Synapse ID, or URL used to create the object (can also be a list of these)
        executed: The Entity, Synapse ID, or URL representing code executed to create the object
                    (can also be a list of these)
        activity: Activity object specifying the user's provenance.
        activityName: Activity name to be used in conjunction with *used* and *executed*.
        activityDescription: Activity description to be used in conjunction with *used* and *executed*.
        createOrUpdate: Indicates whether the method should automatically perform an update if the 'obj'
                        conflicts with an existing Synapse object.
        forceVersion: Indicates whether the method should increment the version of the object even if nothing
                        has changed.
        versionLabel: Arbitrary string used to label the version.
        isRestricted: 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.
        set_annotations: If True, set the annotations on the entity. If False, do not set the annotations.

    Returns:
        A Synapse Entity, Evaluation, or Wiki

    Example: Using this function
        Creating a new Project:

            from synapseclient import Project

            project = Project('My uniquely named project')
            project = syn.store(project)

        Adding files with [provenance (aka: Activity)][synapseclient.Activity]:

            from synapseclient import File, Activity

        A synapse entity *syn1906480* contains data and an entity *syn1917825* contains code

            activity = Activity(
                'Fancy Processing',
                description='No seriously, really fancy processing',
                used=['syn1906480', 'http://data_r_us.com/fancy/data.txt'],
                executed='syn1917825')

            test_entity = File('/path/to/data/file.xyz', description='Fancy new data', parent=project)
            test_entity = syn.store(test_entity, activity=activity)

    """
    return wrap_async_to_sync(
        coroutine=self.store_async(
            obj,
            createOrUpdate=createOrUpdate,
            forceVersion=forceVersion,
            versionLabel=versionLabel,
            isRestricted=isRestricted,
            activity=activity,
            used=used,
            executed=executed,
            activityName=activityName,
            activityDescription=activityDescription,
            set_annotations=set_annotations,
        )
    )

move

move(entity, new_parent)

Deprecated with replacement. This method will be removed in 5.0.0. Use the new dataclass models (File, Folder, Table, etc.) with their parent_id attribute and .store() method instead.

Move a Synapse entity to a new container.

PARAMETER	DESCRIPTION
entity	A Synapse ID, a Synapse Entity object, or a local file that is stored in Synapse
new_parent	The new parent container (Folder or Project) to which the entity should be moved.

RETURNS	DESCRIPTION
	The Synapse Entity object that has been moved.

Using this function (DEPRECATED)

Move a Synapse Entity object to a new parent container

entity = syn.move('syn456', 'syn123')

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import (
    File, Folder, Table, Dataset, DatasetCollection,
    EntityView, SubmissionView, MaterializedView, VirtualTable
)

# Login to Synapse
syn = Synapse()
syn.login()

# Moving a File
file = File(id="syn456", download_file=False).get()
file.parent_id = "syn123"
file = file.store()
print(f"Moved file to: {file.parent_id}")

# Moving a Folder
folder = Folder(id="syn789").get()
folder.parent_id = "syn123"
folder = folder.store()
print(f"Moved folder to: {folder.parent_id}")

# Moving a Table
table = Table(id="syn101112").get()
table.parent_id = "syn123"
table = table.store()
print(f"Moved table to: {table.parent_id}")

# Moving a Dataset
dataset = Dataset(id="syn131415").get()
dataset.parent_id = "syn123"
dataset = dataset.store()
print(f"Moved dataset to: {dataset.parent_id}")

# Moving a DatasetCollection
dataset_collection = DatasetCollection(id="syn161718").get()
dataset_collection.parent_id = "syn123"
dataset_collection = dataset_collection.store()
print(f"Moved dataset collection to: {dataset_collection.parent_id}")

# Moving an EntityView
entity_view = EntityView(id="syn192021").get()
entity_view.parent_id = "syn123"
entity_view = entity_view.store()
print(f"Moved entity view to: {entity_view.parent_id}")

# Moving a SubmissionView
submission_view = SubmissionView(id="syn222324").get()
submission_view.parent_id = "syn123"
submission_view = submission_view.store()
print(f"Moved submission view to: {submission_view.parent_id}")

# Moving a MaterializedView
materialized_view = MaterializedView(id="syn252627").get()
materialized_view.parent_id = "syn123"
materialized_view = materialized_view.store()
print(f"Moved materialized view to: {materialized_view.parent_id}")

# Moving a VirtualTable
virtual_table = VirtualTable(id="syn282930").get()
virtual_table.parent_id = "syn123"
virtual_table = virtual_table.store()
print(f"Moved virtual table to: {virtual_table.parent_id}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "This method uses legacy Entity objects. "
    "Use the new dataclass models (File, Folder, Table, etc.) with their `parent_id` attribute and `.store()` method instead. ",
)
def move(self, entity, new_parent):
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use the new dataclass models (File, Folder, Table, etc.) with their `parent_id`
    attribute and `.store()` method instead.

    Move a Synapse entity to a new container.

    Arguments:
        entity:     A Synapse ID, a Synapse Entity object, or a local file that is stored in Synapse
        new_parent: The new parent container (Folder or Project) to which the entity should be moved.

    Returns:
        The Synapse Entity object that has been moved.

    Example: Using this function (DEPRECATED)
        Move a Synapse Entity object to a new parent container

            entity = syn.move('syn456', 'syn123')

    Example: Migration to new method
         

        ```python
        from synapseclient import Synapse
        from synapseclient.models import (
            File, Folder, Table, Dataset, DatasetCollection,
            EntityView, SubmissionView, MaterializedView, VirtualTable
        )

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Moving a File
        file = File(id="syn456", download_file=False).get()
        file.parent_id = "syn123"
        file = file.store()
        print(f"Moved file to: {file.parent_id}")

        # Moving a Folder
        folder = Folder(id="syn789").get()
        folder.parent_id = "syn123"
        folder = folder.store()
        print(f"Moved folder to: {folder.parent_id}")

        # Moving a Table
        table = Table(id="syn101112").get()
        table.parent_id = "syn123"
        table = table.store()
        print(f"Moved table to: {table.parent_id}")

        # Moving a Dataset
        dataset = Dataset(id="syn131415").get()
        dataset.parent_id = "syn123"
        dataset = dataset.store()
        print(f"Moved dataset to: {dataset.parent_id}")

        # Moving a DatasetCollection
        dataset_collection = DatasetCollection(id="syn161718").get()
        dataset_collection.parent_id = "syn123"
        dataset_collection = dataset_collection.store()
        print(f"Moved dataset collection to: {dataset_collection.parent_id}")

        # Moving an EntityView
        entity_view = EntityView(id="syn192021").get()
        entity_view.parent_id = "syn123"
        entity_view = entity_view.store()
        print(f"Moved entity view to: {entity_view.parent_id}")

        # Moving a SubmissionView
        submission_view = SubmissionView(id="syn222324").get()
        submission_view.parent_id = "syn123"
        submission_view = submission_view.store()
        print(f"Moved submission view to: {submission_view.parent_id}")

        # Moving a MaterializedView
        materialized_view = MaterializedView(id="syn252627").get()
        materialized_view.parent_id = "syn123"
        materialized_view = materialized_view.store()
        print(f"Moved materialized view to: {materialized_view.parent_id}")

        # Moving a VirtualTable
        virtual_table = VirtualTable(id="syn282930").get()
        virtual_table.parent_id = "syn123"
        virtual_table = virtual_table.store()
        print(f"Moved virtual table to: {virtual_table.parent_id}")
        ```
    """

    entity = self.get(entity, downloadFile=False)
    entity.parentId = id_of(new_parent)
    entity = self.store(entity, forceVersion=False)
    trace.get_current_span().set_attributes(
        {
            "synapse.id": entity.get("id", ""),
            "synapse.parent_id": entity.get("parentId", ""),
        }
    )

    return entity

delete

delete(obj, version=None)

Removes an object from Synapse.

PARAMETER	DESCRIPTION
obj	An existing object stored on Synapse such as Evaluation, File, Project, or Wiki
version	For entities, specify a particular version to delete. DEFAULT: None

Source code in synapseclient/client.py

@deprecated(
    version="4.11.0",
    reason="To be removed in 5.0.0. "
    "Use `from synapseclient.operations import delete` instead.",
)
def delete(
    self,
    obj,
    version=None,
):
    """
    Removes an object from Synapse.

    Arguments:
        obj: An existing object stored on Synapse such as Evaluation, File, Project, or Wiki
        version: For entities, specify a particular version to delete.
    """
    # Handle all strings as the Entity ID for backward compatibility
    if isinstance(obj, str):
        entity_id = id_of(obj)
        trace.get_current_span().set_attributes({"synapse.id": entity_id})
        if version:
            self.restDELETE(uri=f"/entity/{entity_id}/version/{version}")
        else:
            self.restDELETE(uri=f"/entity/{entity_id}")
    elif hasattr(obj, "_synapse_delete"):
        return obj._synapse_delete(self)
    else:
        try:
            if isinstance(obj, Versionable):
                self.restDELETE(obj.deleteURI(versionNumber=version))
            else:
                self.restDELETE(obj.deleteURI())
        except AttributeError:
            raise SynapseError(
                f"Can't delete a {type(obj)}. Please specify a Synapse object or id"
            )

get_annotations

get_annotations(entity: Union[str, Entity], version: Union[str, int] = None) -> Annotations

Retrieve annotations for an Entity from the Synapse Repository as a Python dict.

Note that collapsing annotations from the native Synapse format to a Python dict may involve some loss of information. See _getRawAnnotations to get annotations in the native format.

PARAMETER	DESCRIPTION
entity	An Entity or Synapse ID to lookup TYPE: Union[str, Entity]
version	The version of the Entity to retrieve. TYPE: Union[str, int] DEFAULT: None

RETURNS	DESCRIPTION
Annotations	A synapseclient.annotations.Annotations object, a dict that also has id and etag attributes

Migrating from this method to dataclass models

Legacy approach (deprecated):

# Get the File entity first
file_entity = syn.get("syn123")

# Get annotations separately
annotations = syn.get_annotations(file_entity)
print(annotations)

New approach using dataclass models:

import synapseclient
from synapseclient.models import (
    File, Folder, Project, Table, EntityView, Dataset,
    DatasetCollection, MaterializedView, SubmissionView, VirtualTable
)

# Create client and login
syn = synapseclient.Synapse()
syn.login()

# File - don't download the file content, just get metadata
file_instance = File(id="syn12345", download_file=False)
file_instance = file_instance.get()
print(f"File annotations: {file_instance.annotations}")

# Folder
folder_instance = Folder(id="syn11111")
folder_instance = folder_instance.get()
print(f"Folder annotations: {folder_instance.annotations}")

# Project
project_instance = Project(id="syn22222")
project_instance = project_instance.get()
print(f"Project annotations: {project_instance.annotations}")

# Table
table_instance = Table(id="syn33333")
table_instance = table_instance.get()
print(f"Table annotations: {table_instance.annotations}")

# EntityView
view_instance = EntityView(id="syn44444")
view_instance = view_instance.get()
print(f"EntityView annotations: {view_instance.annotations}")

# Dataset
dataset_instance = Dataset(id="syn55555")
dataset_instance = dataset_instance.get()
print(f"Dataset annotations: {dataset_instance.annotations}")

# DatasetCollection
collection_instance = DatasetCollection(id="syn66666")
collection_instance = collection_instance.get()
print(f"DatasetCollection annotations: {collection_instance.annotations}")

# MaterializedView
mat_view_instance = MaterializedView(id="syn77777")
mat_view_instance = mat_view_instance.get()
print(f"MaterializedView annotations: {mat_view_instance.annotations}")

# SubmissionView
sub_view_instance = SubmissionView(id="syn88888")
sub_view_instance = sub_view_instance.get()
print(f"SubmissionView annotations: {sub_view_instance.annotations}")

# VirtualTable
virtual_table_instance = VirtualTable(id="syn99999")
virtual_table_instance = virtual_table_instance.get()
print(f"VirtualTable annotations: {virtual_table_instance.annotations}")

# Access specific annotation values
# annotations is always a dict by default (empty {} if no annotations exist)
species = file_instance.annotations.get("species", [])
data_type = file_instance.annotations.get("dataType", [])
print(f"Species: {species}, Data type: {data_type}")

# Check if a specific annotation exists
if species:
    print(f"Species annotation exists: {species}")
else:
    print("Species annotation not found")

# Get all annotation keys
annotation_keys = list(file_instance.annotations.keys())
print(f"Available annotation keys: {annotation_keys}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. Use the dataclass model attributes instead. "
    "All dataclass models support annotations: File, Folder, Project, Table, EntityView, Dataset, "
    "DatasetCollection, MaterializedView, SubmissionView, VirtualTable. "
    "Access annotations directly via `instance.annotations` attribute.",
)
def get_annotations(
    self, entity: typing.Union[str, Entity], version: typing.Union[str, int] = None
) -> Annotations:
    """
    Retrieve annotations for an Entity from the Synapse Repository as a Python dict.

    Note that collapsing annotations from the native Synapse format to a Python dict may involve some loss of
    information. See `_getRawAnnotations` to get annotations in the native format.

    Arguments:
        entity: An Entity or Synapse ID to lookup
        version: The version of the Entity to retrieve.

    Returns:
        A [synapseclient.annotations.Annotations][] object, a dict that also has id and etag attributes

    Example: Migrating from this method to dataclass models
        **Legacy approach (deprecated):**
        ```python
        # Get the File entity first
        file_entity = syn.get("syn123")

        # Get annotations separately
        annotations = syn.get_annotations(file_entity)
        print(annotations)
        ```

        **New approach using dataclass models:**
        ```python
        import synapseclient
        from synapseclient.models import (
            File, Folder, Project, Table, EntityView, Dataset,
            DatasetCollection, MaterializedView, SubmissionView, VirtualTable
        )

        # Create client and login
        syn = synapseclient.Synapse()
        syn.login()

        # File - don't download the file content, just get metadata
        file_instance = File(id="syn12345", download_file=False)
        file_instance = file_instance.get()
        print(f"File annotations: {file_instance.annotations}")

        # Folder
        folder_instance = Folder(id="syn11111")
        folder_instance = folder_instance.get()
        print(f"Folder annotations: {folder_instance.annotations}")

        # Project
        project_instance = Project(id="syn22222")
        project_instance = project_instance.get()
        print(f"Project annotations: {project_instance.annotations}")

        # Table
        table_instance = Table(id="syn33333")
        table_instance = table_instance.get()
        print(f"Table annotations: {table_instance.annotations}")

        # EntityView
        view_instance = EntityView(id="syn44444")
        view_instance = view_instance.get()
        print(f"EntityView annotations: {view_instance.annotations}")

        # Dataset
        dataset_instance = Dataset(id="syn55555")
        dataset_instance = dataset_instance.get()
        print(f"Dataset annotations: {dataset_instance.annotations}")

        # DatasetCollection
        collection_instance = DatasetCollection(id="syn66666")
        collection_instance = collection_instance.get()
        print(f"DatasetCollection annotations: {collection_instance.annotations}")

        # MaterializedView
        mat_view_instance = MaterializedView(id="syn77777")
        mat_view_instance = mat_view_instance.get()
        print(f"MaterializedView annotations: {mat_view_instance.annotations}")

        # SubmissionView
        sub_view_instance = SubmissionView(id="syn88888")
        sub_view_instance = sub_view_instance.get()
        print(f"SubmissionView annotations: {sub_view_instance.annotations}")

        # VirtualTable
        virtual_table_instance = VirtualTable(id="syn99999")
        virtual_table_instance = virtual_table_instance.get()
        print(f"VirtualTable annotations: {virtual_table_instance.annotations}")

        # Access specific annotation values
        # annotations is always a dict by default (empty {} if no annotations exist)
        species = file_instance.annotations.get("species", [])
        data_type = file_instance.annotations.get("dataType", [])
        print(f"Species: {species}, Data type: {data_type}")

        # Check if a specific annotation exists
        if species:
            print(f"Species annotation exists: {species}")
        else:
            print("Species annotation not found")

        # Get all annotation keys
        annotation_keys = list(file_instance.annotations.keys())
        print(f"Available annotation keys: {annotation_keys}")
        ```
    """
    return from_synapse_annotations(self._getRawAnnotations(entity, version))

set_annotations

set_annotations(annotations: Annotations)

Store annotations for an Entity in the Synapse Repository.

PARAMETER	DESCRIPTION
annotations	A synapseclient.annotations.Annotations of annotation names and values, with the id and etag attribute set TYPE: Annotations

RETURNS	DESCRIPTION
	The updated synapseclient.annotations.Annotations for the entity

Migrating from this method to dataclass models

Legacy approach (deprecated):

# Get annotations, modify, and set back
annos = syn.get_annotations('syn12345')
annos['foo'] = ['bar', 'baz']
annos['qwerty'] = 'asdf'
annos = syn.set_annotations(annos)
print(annos)

New approach using dataclass models:

In this example all of these updates are destructive, meaning they will overwrite any existing annotations. If you want to merge annotations instead, see the merging example below.

import synapseclient
from synapseclient.models import (
    File, Folder, Project, Table, EntityView, Dataset,
    DatasetCollection, MaterializedView, SubmissionView, VirtualTable
)

# Create client and login
syn = synapseclient.Synapse()
syn.login()

# File - don't download the file content, just get metadata
file_instance = File(id="syn12345", download_file=False)
file_instance = file_instance.get()
file_instance.annotations = {
    "foo": ["bar", "baz"],
    "qwerty": ["asdf"],
    "species": ["Homo sapiens"]
}
file_instance = file_instance.store()
print(f"File annotations: {file_instance.annotations}")

# Folder
folder_instance = Folder(id="syn11111")
folder_instance = folder_instance.get()
folder_instance.annotations = {
    "category": ["research"],
    "department": ["biology"]
}
folder_instance = folder_instance.store()
print(f"Folder annotations: {folder_instance.annotations}")

# Project
project_instance = Project(id="syn22222")
project_instance = project_instance.get()
project_instance.annotations = {
    "funding": ["NIH"],
    "grant_number": ["R01-12345"]
}
project_instance = project_instance.store()
print(f"Project annotations: {project_instance.annotations}")

# Table
table_instance = Table(id="syn33333")
table_instance = table_instance.get()
table_instance.annotations = {
    "version": ["1.0"],
    "data_type": ["clinical"]
}
table_instance = table_instance.store()
print(f"Table annotations: {table_instance.annotations}")

# EntityView
view_instance = EntityView(id="syn44444")
view_instance = view_instance.get()
view_instance.annotations = {
    "scope": ["project_wide"],
    "view_type": ["file_view"]
}
view_instance = view_instance.store()
print(f"EntityView annotations: {view_instance.annotations}")

# Dataset
dataset_instance = Dataset(id="syn55555")
dataset_instance = dataset_instance.get()
dataset_instance.annotations = {
    "dataset_type": ["genomic"],
    "size": ["large"]
}
dataset_instance = dataset_instance.store()
print(f"Dataset annotations: {dataset_instance.annotations}")

# DatasetCollection
collection_instance = DatasetCollection(id="syn66666")
collection_instance = collection_instance.get()
collection_instance.annotations = {
    "collection_type": ["multi_omics"],
    "studies": ["3"]
}
collection_instance = collection_instance.store()
print(f"DatasetCollection annotations: {collection_instance.annotations}")

# MaterializedView
mat_view_instance = MaterializedView(id="syn77777")
mat_view_instance = mat_view_instance.get()
mat_view_instance.annotations = {
    "refresh_frequency": ["daily"],
    "data_source": ["clinical_db"]
}
mat_view_instance = mat_view_instance.store()
print(f"MaterializedView annotations: {mat_view_instance.annotations}")

# SubmissionView
sub_view_instance = SubmissionView(id="syn88888")
sub_view_instance = sub_view_instance.get()
sub_view_instance.annotations = {
    "evaluation_queue": ["challenge_2024"],
    "status": ["active"]
}
sub_view_instance = sub_view_instance.store()
print(f"SubmissionView annotations: {sub_view_instance.annotations}")

# VirtualTable
virtual_table_instance = VirtualTable(id="syn99999")
virtual_table_instance = virtual_table_instance.get()
virtual_table_instance.annotations = {
    "virtual_type": ["federated"],
    "source_count": ["5"]
}
virtual_table_instance = virtual_table_instance.store()
print(f"VirtualTable annotations: {virtual_table_instance.annotations}")

For merging with existing annotations:

import synapseclient
from synapseclient.models import File, Folder

# Create client and login
syn = synapseclient.Synapse()
syn.login()

# Get existing annotations and merge for File
file_instance = File(id="syn12345", download_file=False)
file_instance = file_instance.get()

# Merge with existing annotations (annotations is always a dict by default)
file_instance.annotations.update({
    "foo": ["bar", "baz"],
    "qwerty": ["asdf"]
})

# Store the updated File
file_instance = file_instance.store()
print(f"Updated file annotations: {file_instance.annotations}")

# Same pattern works for all other dataclass models
folder_instance = Folder(id="syn11111")
folder_instance = folder_instance.get()
folder_instance.annotations.update({"new_key": ["new_value"]})
folder_instance = folder_instance.store()
print(f"Updated folder annotations: {folder_instance.annotations}")

For updating single annotation values:

import synapseclient
from synapseclient.models import File

# Create client and login
syn = synapseclient.Synapse()
syn.login()

# Update a single annotation value while preserving existing annotations
file_instance = File(id="syn12345", download_file=False)
file_instance = file_instance.get()

# annotations is always a dict by default (empty {} if no annotations exist)
# You can directly access and modify annotation values
file_instance.annotations["species"] = ["Mus musculus"]
file_instance.annotations["data_type"] = ["RNA-seq"]

# Store the updated File
file_instance = file_instance.store()
print(f"Updated file annotations: {file_instance.annotations}")

IMPORTANT - Destructive vs Non-destructive updates:

import synapseclient
from synapseclient.models import File

# Create client and login
syn = synapseclient.Synapse()
syn.login()

# When you call .get(), existing annotations are loaded into the instance
file_instance = File(id="syn12345", download_file=False)
file_instance = file_instance.get()
# Now file_instance.annotations contains existing annotations from Synapse

# DESTRUCTIVE UPDATE - This replaces ALL existing annotations
file_instance.annotations = {
    "new_key": ["new_value"]
}
# All previous annotations are lost!

# NON-DESTRUCTIVE UPDATE - This preserves existing annotations
# annotations is always a dict by default (empty {} if no annotations exist)
file_instance.annotations.update({
    "new_key": ["new_value"]
})
# OR modify individual keys:
file_instance.annotations["another_key"] = ["another_value"]
# Previous annotations are preserved

# To remove ALL annotations, set to None or empty dict
file_instance.annotations = None  # Clears all annotations
# OR
file_instance.annotations = {}    # Also clears all annotations

file_instance = file_instance.store()

Using this function (DEPRECATED)

Getting annotations, adding a new annotation, and updating the annotations:

annos = syn.get_annotations('syn123')

annos will contain the id and etag associated with the entity upon retrieval

print(annos.id)
> syn123
print(annos.etag)
> 7bdb83e9-a50a-46e4-987a-4962559f090f   (Usually some UUID in the form of a string)

Returned annos object from get_annotations() can be used as if it were a dict. Set key 'foo' to have value of 'bar' and 'baz'

annos['foo'] = ['bar', 'baz']

Single values will automatically be wrapped in a list once stored

annos['qwerty'] = 'asdf'

Store the annotations

annos = syn.set_annotations(annos)

print(annos)
> {'foo':['bar','baz], 'qwerty':['asdf']}

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. Use the dataclass model attributes instead. "
    "All dataclass models support annotations: File, Folder, Project, Table, EntityView, Dataset, "
    "DatasetCollection, MaterializedView, SubmissionView, VirtualTable. "
    "Set annotations via `instance.annotations = {...}` then call `instance.store()`.",
)
def set_annotations(self, annotations: Annotations):
    """
    Store annotations for an Entity in the Synapse Repository.

    Arguments:
        annotations: A [synapseclient.annotations.Annotations][] of annotation names and values,
                        with the id and etag attribute set

    Returns:
        The updated [synapseclient.annotations.Annotations][] for the entity

    Example: Migrating from this method to dataclass models
        **Legacy approach (deprecated):**
        ```python
        # Get annotations, modify, and set back
        annos = syn.get_annotations('syn12345')
        annos['foo'] = ['bar', 'baz']
        annos['qwerty'] = 'asdf'
        annos = syn.set_annotations(annos)
        print(annos)
        ```

        **New approach using dataclass models:**

        In this example all of these updates are destructive, meaning they will
        overwrite any existing annotations. If you want to merge annotations
        instead, see the merging example below.
        ```python
        import synapseclient
        from synapseclient.models import (
            File, Folder, Project, Table, EntityView, Dataset,
            DatasetCollection, MaterializedView, SubmissionView, VirtualTable
        )

        # Create client and login
        syn = synapseclient.Synapse()
        syn.login()

        # File - don't download the file content, just get metadata
        file_instance = File(id="syn12345", download_file=False)
        file_instance = file_instance.get()
        file_instance.annotations = {
            "foo": ["bar", "baz"],
            "qwerty": ["asdf"],
            "species": ["Homo sapiens"]
        }
        file_instance = file_instance.store()
        print(f"File annotations: {file_instance.annotations}")

        # Folder
        folder_instance = Folder(id="syn11111")
        folder_instance = folder_instance.get()
        folder_instance.annotations = {
            "category": ["research"],
            "department": ["biology"]
        }
        folder_instance = folder_instance.store()
        print(f"Folder annotations: {folder_instance.annotations}")

        # Project
        project_instance = Project(id="syn22222")
        project_instance = project_instance.get()
        project_instance.annotations = {
            "funding": ["NIH"],
            "grant_number": ["R01-12345"]
        }
        project_instance = project_instance.store()
        print(f"Project annotations: {project_instance.annotations}")

        # Table
        table_instance = Table(id="syn33333")
        table_instance = table_instance.get()
        table_instance.annotations = {
            "version": ["1.0"],
            "data_type": ["clinical"]
        }
        table_instance = table_instance.store()
        print(f"Table annotations: {table_instance.annotations}")

        # EntityView
        view_instance = EntityView(id="syn44444")
        view_instance = view_instance.get()
        view_instance.annotations = {
            "scope": ["project_wide"],
            "view_type": ["file_view"]
        }
        view_instance = view_instance.store()
        print(f"EntityView annotations: {view_instance.annotations}")

        # Dataset
        dataset_instance = Dataset(id="syn55555")
        dataset_instance = dataset_instance.get()
        dataset_instance.annotations = {
            "dataset_type": ["genomic"],
            "size": ["large"]
        }
        dataset_instance = dataset_instance.store()
        print(f"Dataset annotations: {dataset_instance.annotations}")

        # DatasetCollection
        collection_instance = DatasetCollection(id="syn66666")
        collection_instance = collection_instance.get()
        collection_instance.annotations = {
            "collection_type": ["multi_omics"],
            "studies": ["3"]
        }
        collection_instance = collection_instance.store()
        print(f"DatasetCollection annotations: {collection_instance.annotations}")

        # MaterializedView
        mat_view_instance = MaterializedView(id="syn77777")
        mat_view_instance = mat_view_instance.get()
        mat_view_instance.annotations = {
            "refresh_frequency": ["daily"],
            "data_source": ["clinical_db"]
        }
        mat_view_instance = mat_view_instance.store()
        print(f"MaterializedView annotations: {mat_view_instance.annotations}")

        # SubmissionView
        sub_view_instance = SubmissionView(id="syn88888")
        sub_view_instance = sub_view_instance.get()
        sub_view_instance.annotations = {
            "evaluation_queue": ["challenge_2024"],
            "status": ["active"]
        }
        sub_view_instance = sub_view_instance.store()
        print(f"SubmissionView annotations: {sub_view_instance.annotations}")

        # VirtualTable
        virtual_table_instance = VirtualTable(id="syn99999")
        virtual_table_instance = virtual_table_instance.get()
        virtual_table_instance.annotations = {
            "virtual_type": ["federated"],
            "source_count": ["5"]
        }
        virtual_table_instance = virtual_table_instance.store()
        print(f"VirtualTable annotations: {virtual_table_instance.annotations}")
        ```

        **For merging with existing annotations:**
        ```python
        import synapseclient
        from synapseclient.models import File, Folder

        # Create client and login
        syn = synapseclient.Synapse()
        syn.login()

        # Get existing annotations and merge for File
        file_instance = File(id="syn12345", download_file=False)
        file_instance = file_instance.get()

        # Merge with existing annotations (annotations is always a dict by default)
        file_instance.annotations.update({
            "foo": ["bar", "baz"],
            "qwerty": ["asdf"]
        })

        # Store the updated File
        file_instance = file_instance.store()
        print(f"Updated file annotations: {file_instance.annotations}")

        # Same pattern works for all other dataclass models
        folder_instance = Folder(id="syn11111")
        folder_instance = folder_instance.get()
        folder_instance.annotations.update({"new_key": ["new_value"]})
        folder_instance = folder_instance.store()
        print(f"Updated folder annotations: {folder_instance.annotations}")
        ```

        **For updating single annotation values:**
        ```python
        import synapseclient
        from synapseclient.models import File

        # Create client and login
        syn = synapseclient.Synapse()
        syn.login()

        # Update a single annotation value while preserving existing annotations
        file_instance = File(id="syn12345", download_file=False)
        file_instance = file_instance.get()

        # annotations is always a dict by default (empty {} if no annotations exist)
        # You can directly access and modify annotation values
        file_instance.annotations["species"] = ["Mus musculus"]
        file_instance.annotations["data_type"] = ["RNA-seq"]

        # Store the updated File
        file_instance = file_instance.store()
        print(f"Updated file annotations: {file_instance.annotations}")
        ```

        **IMPORTANT - Destructive vs Non-destructive updates:**
        ```python
        import synapseclient
        from synapseclient.models import File

        # Create client and login
        syn = synapseclient.Synapse()
        syn.login()

        # When you call .get(), existing annotations are loaded into the instance
        file_instance = File(id="syn12345", download_file=False)
        file_instance = file_instance.get()
        # Now file_instance.annotations contains existing annotations from Synapse

        # DESTRUCTIVE UPDATE - This replaces ALL existing annotations
        file_instance.annotations = {
            "new_key": ["new_value"]
        }
        # All previous annotations are lost!

        # NON-DESTRUCTIVE UPDATE - This preserves existing annotations
        # annotations is always a dict by default (empty {} if no annotations exist)
        file_instance.annotations.update({
            "new_key": ["new_value"]
        })
        # OR modify individual keys:
        file_instance.annotations["another_key"] = ["another_value"]
        # Previous annotations are preserved

        # To remove ALL annotations, set to None or empty dict
        file_instance.annotations = None  # Clears all annotations
        # OR
        file_instance.annotations = {}    # Also clears all annotations

        file_instance = file_instance.store()
        ```

    Example: Using this function (DEPRECATED)
        Getting annotations, adding a new annotation, and updating the annotations:

            annos = syn.get_annotations('syn123')

        `annos` will contain the id and etag associated with the entity upon retrieval

            print(annos.id)
            > syn123
            print(annos.etag)
            > 7bdb83e9-a50a-46e4-987a-4962559f090f   (Usually some UUID in the form of a string)

        Returned `annos` object from `get_annotations()` can be used as if it were a dict.
        Set key 'foo' to have value of 'bar' and 'baz'

            annos['foo'] = ['bar', 'baz']

        Single values will automatically be wrapped in a list once stored

            annos['qwerty'] = 'asdf'

        Store the annotations

            annos = syn.set_annotations(annos)

            print(annos)
            > {'foo':['bar','baz], 'qwerty':['asdf']}
    """

    if not isinstance(annotations, Annotations):
        raise TypeError("Expected a synapseclient.Annotations object")

    synapseAnnos = to_synapse_annotations(annotations)

    entity_id = id_of(annotations)
    trace.get_current_span().set_attributes({"synapse.id": entity_id})

    return from_synapse_annotations(
        self.restPUT(
            f"/entity/{entity_id}/annotations2",
            body=json.dumps(synapseAnnos),
        )
    )

tableQuery

tableQuery(query: str, resultsAs: str = 'csv', **kwargs)

Deprecated with replacement. This method will be removed in 5.0.0. Use the query or query_async functions from synapseclient.models.Table instead.

Query a Synapse Table.

You can receive query results either as a generator over rows or as a CSV file. For smallish tables, either method will work equally well. Use of a "rowset" generator allows rows to be processed one at a time and processing may be stopped before downloading the entire table.

Optional keyword arguments differ for the two return types of rowset or csv

PARAMETER	DESCRIPTION
query	Query string in a SQL-like syntax, for example: "SELECT * from syn12345" TYPE: str
resultsAs	select whether results are returned as a CSV file ("csv") or incrementally downloaded as sets of rows ("rowset") TYPE: str DEFAULT: 'csv'
limit	(rowset only) Specify the maximum number of rows to be returned, defaults to None
offset	(rowset only) Don't return the first n rows, defaults to None
quoteCharacter	(csv only) default double quote
escapeCharacter	(csv only) default backslash
lineEnd	(csv only) defaults to os.linesep
separator	(csv only) defaults to comma
header	(csv only) True by default
includeRowIdAndRowVersion	(csv only) True by default
downloadLocation	(csv only) directory path to download the CSV file to

RETURNS	DESCRIPTION
	A TableQueryResult or CsvFileTable object

NOTE

When performing queries on frequently updated tables, the table can be inaccessible for a period leading to a timeout of the query. Since the results are guaranteed to eventually be returned you can change the max timeout by setting the table_query_timeout variable of the Synapse object:

  # Sets the max timeout to 5 minutes.
  syn.table_query_timeout = 300

Using this function (DEPRECATED)

Getting query results as a DataFrame:

results = syn.tableQuery("SELECT * FROM syn12345")
df = results.asDataFrame()

Getting query results as a CSV file:

results = syn.tableQuery("SELECT * FROM syn12345", resultsAs="csv", downloadLocation="./my_data/")

Migration to new method

 

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

# Login to Synapse
syn = Synapse()
syn.login()

# Synchronous query (recommended for most use cases)
results = query(query="SELECT * FROM syn12345")
print(results)

# Query with specific options
results = query(
    query="SELECT * FROM syn12345",
    include_row_id_and_row_version=True,
    convert_to_datetime=True
)
print(results)

# Download query results to a CSV file
file_path = query(
    query="SELECT * FROM syn12345",
    download_location="./my_data/",
    separator=",",
    quote_character='"',
    header=True
)
print(f"Results downloaded to: {file_path}")

# Asynchronous query (for advanced use cases)
async def async_query_example():
    results = await query_async(query="SELECT * FROM syn12345")
    print(results)

    # Download query results to a CSV file asynchronously
    file_path = await query_async(
        query="SELECT * FROM syn12345",
        download_location="./my_data/",
        separator=",",
        quote_character='"',
        header=True
    )
    print(f"Results downloaded to: {file_path}")

# Run the async example
asyncio.run(async_query_example())

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Use the `query` functions from `synapseclient.models.Table` instead. "
    "Check the docstring for the replacement function example.",
)
def tableQuery(self, query: str, resultsAs: str = "csv", **kwargs):
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use the `query` or `query_async` functions from [synapseclient.models.Table][] instead.

    Query a Synapse Table.

    You can receive query results either as a generator over rows or as a CSV file. For smallish tables, either
    method will work equally well. Use of a "rowset" generator allows rows to be processed one at a time and
    processing may be stopped before downloading the entire table.

    Optional keyword arguments differ for the two return types of `rowset` or `csv`

    Arguments:
        query: Query string in a [SQL-like syntax](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/web/controller/TableExamples.html), for example: `"SELECT * from syn12345"`
        resultsAs: select whether results are returned as a CSV file ("csv") or incrementally downloaded as sets of rows ("rowset")
        limit: (rowset only) Specify the maximum number of rows to be returned, defaults to None
        offset: (rowset only) Don't return the first n rows, defaults to None
        quoteCharacter: (csv only) default double quote
        escapeCharacter: (csv only) default backslash
        lineEnd: (csv only) defaults to os.linesep
        separator: (csv only) defaults to comma
        header: (csv only) True by default
        includeRowIdAndRowVersion: (csv only) True by default
        downloadLocation: (csv only) directory path to download the CSV file to

    Returns:
        A [TableQueryResult][synapseclient.table.TableQueryResult] or [CsvFileTable][synapseclient.table.CsvFileTable] object

    NOTE:
        When performing queries on frequently updated tables, the table can be inaccessible for a period leading
          to a timeout of the query.  Since the results are guaranteed to eventually be returned you can change the
          max timeout by setting the table_query_timeout variable of the Synapse object:

              # Sets the max timeout to 5 minutes.
              syn.table_query_timeout = 300

    Example: Using this function (DEPRECATED)
        Getting query results as a DataFrame:

            results = syn.tableQuery("SELECT * FROM syn12345")
            df = results.asDataFrame()

        Getting query results as a CSV file:

            results = syn.tableQuery("SELECT * FROM syn12345", resultsAs="csv", downloadLocation="./my_data/")

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Synchronous query (recommended for most use cases)
        results = query(query="SELECT * FROM syn12345")
        print(results)

        # Query with specific options
        results = query(
            query="SELECT * FROM syn12345",
            include_row_id_and_row_version=True,
            convert_to_datetime=True
        )
        print(results)

        # Download query results to a CSV file
        file_path = query(
            query="SELECT * FROM syn12345",
            download_location="./my_data/",
            separator=",",
            quote_character='"',
            header=True
        )
        print(f"Results downloaded to: {file_path}")

        # Asynchronous query (for advanced use cases)
        async def async_query_example():
            results = await query_async(query="SELECT * FROM syn12345")
            print(results)

            # Download query results to a CSV file asynchronously
            file_path = await query_async(
                query="SELECT * FROM syn12345",
                download_location="./my_data/",
                separator=",",
                quote_character='"',
                header=True
            )
            print(f"Results downloaded to: {file_path}")

        # Run the async example
        asyncio.run(async_query_example())
        ```

    """
    if resultsAs.lower() == "rowset":
        return TableQueryResult(self, query, **kwargs)
    elif resultsAs.lower() == "csv":
        # TODO: remove isConsistent because it has now been deprecated
        # from the backend
        if kwargs.get("isConsistent") is not None:
            kwargs.pop("isConsistent")
        return CsvFileTable.from_table_query(self, query, **kwargs)
    else:
        raise ValueError(
            "Unknown return type requested from tableQuery: " + str(resultsAs)
        )

createColumns

createColumns(columns: List[Column]) -> List[Column]

Deprecated with replacement. This method will be removed in 5.0.0. Use the .columns attribute on table-like classes or the add_column method to store columns during the storage of these table-like classes.

Creates a batch of synapseclient.table.Column's within a single request.

PARAMETER	DESCRIPTION
columns	A list of synapseclient.table.Column's TYPE: List[Column]

RETURNS	DESCRIPTION
List[Column]	A list of synapseclient.table.Column's that have been created in Synapse

Using this function (DEPRECATED)

Creating multiple columns

columns = [
    Column(name="col1", columnType="STRING"),
    Column(name="col2", columnType="INTEGER")
]
created_columns = syn.createColumns(columns)

Migration to new methods

 

from synapseclient import Synapse
from synapseclient.models import Column, ColumnType, Table
from synapseclient.api.table_services import post_columns
import asyncio

# Login to Synapse
syn = Synapse()
syn.login()

# Method 1: Create columns and add to table using ColumnMixin
columns = [
    Column(name="col1", column_type=ColumnType.STRING),
    Column(name="col2", column_type=ColumnType.INTEGER)
]

# Get an existing table and add the columns
table = Table(id="syn1234").get(include_columns=True)
table.add_column(columns)
table.store()

# Method 2: Create a new table with columns
table = Table(
    name="My Table",
    parent_id="syn5678",
    columns=[
        Column(name="col1", column_type=ColumnType.STRING),
        Column(name="col2", column_type=ColumnType.INTEGER),
    ]
)
table.store()

# Method 3: Use the async post_columns function directly
async def create_columns():
    columns = [
        Column(name="col1", column_type=ColumnType.STRING),
        Column(name="col2", column_type=ColumnType.INTEGER)
    ]
    created_columns = await post_columns(columns)
    return created_columns

# Run the async function
created_columns = asyncio.run(create_columns())

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Use the `.columns` attribute on table-like classes or the `add_column` method to store columns during the storage of these table-like classes. "
    "For batch column operations, use the synapseclient.api.table_services.post_columns function. "
    "Check the docstring for the replacement function example.",
)
def createColumns(self, columns: typing.List[Column]) -> typing.List[Column]:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use the `.columns` attribute on table-like classes or the `add_column` method to store columns during the storage of these table-like classes.

    Creates a batch of [synapseclient.table.Column][]'s within a single request.

    Arguments:
        columns: A list of [synapseclient.table.Column][]'s

    Returns:
        A list of [synapseclient.table.Column][]'s that have been created in Synapse

    Example: Using this function (DEPRECATED)
        Creating multiple columns

            columns = [
                Column(name="col1", columnType="STRING"),
                Column(name="col2", columnType="INTEGER")
            ]
            created_columns = syn.createColumns(columns)

    Example: Migration to new methods
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Method 1: Create columns and add to table using ColumnMixin
        columns = [
            Column(name="col1", column_type=ColumnType.STRING),
            Column(name="col2", column_type=ColumnType.INTEGER)
        ]

        # Get an existing table and add the columns
        table = Table(id="syn1234").get(include_columns=True)
        table.add_column(columns)
        table.store()

        # Method 2: Create a new table with columns
        table = Table(
            name="My Table",
            parent_id="syn5678",
            columns=[
                Column(name="col1", column_type=ColumnType.STRING),
                Column(name="col2", column_type=ColumnType.INTEGER),
            ]
        )
        table.store()

        # Method 3: Use the async post_columns function directly
        async def create_columns():
            columns = [
                Column(name="col1", column_type=ColumnType.STRING),
                Column(name="col2", column_type=ColumnType.INTEGER)
            ]
            created_columns = await post_columns(columns)
            return created_columns

        # Run the async function
        created_columns = asyncio.run(create_columns())
        ```
    """
    request_body = {
        "concreteType": "org.sagebionetworks.repo.model.ListWrapper",
        "list": list(columns),
    }
    response = self.restPOST("/column/batch", json.dumps(request_body))
    return [Column(**col) for col in response["list"]]

getColumn

getColumn(id)

Deprecated with replacement. This method will be removed in 5.0.0. Use the Column.get() method instead.

Gets a Column object from Synapse by ID.

See: synapseclient.table.Column

PARAMETER	DESCRIPTION
id	The ID of the column to retrieve

RETURNS	DESCRIPTION
	An object of type synapseclient.table.Column

Using this function (DEPRECATED)

Getting a column

column = syn.getColumn(123)

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Column

# Login to Synapse
syn = Synapse()
syn.login()

# Get a column by ID
column = Column(id="123").get()
print(f"Column name: {column.name}")
print(f"Column type: {column.column_type}")
print(f"Column ID: {column.id}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Use the `Column.get()` method instead. "
    "Check the docstring for the replacement function example.",
)
def getColumn(self, id):
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use the `Column.get()` method instead.

    Gets a Column object from Synapse by ID.

    See: [synapseclient.table.Column][]

    Arguments:
        id: The ID of the column to retrieve

    Returns:
        An object of type [synapseclient.table.Column][]

    Example: Using this function (DEPRECATED)
        Getting a column

            column = syn.getColumn(123)

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Get a column by ID
        column = Column(id="123").get()
        print(f"Column name: {column.name}")
        print(f"Column type: {column.column_type}")
        print(f"Column ID: {column.id}")
        ```
    """
    return Column(**self.restGET(Column.getURI(id)))

getColumns

getColumns(x, limit=100, offset=0)

Deprecated with replacement. This method will be removed in 5.0.0. Use the .columns attribute on table classes or Column.list() method instead.

Get the columns defined in Synapse either (1) corresponding to a set of column headers, (2) those for a given schema, or (3) those whose names start with a given prefix.

PARAMETER	DESCRIPTION
x	A list of column headers, a Table Entity object (Schema/EntityViewSchema), a Table's Synapse ID, or a string prefix
limit	Number of columns to retrieve per request to Synapse (pagination parameter). The function will continue retrieving results until all matching columns are returned. DEFAULT: 100
offset	the index of the first column to return (pagination parameter) DEFAULT: 0

YIELDS	DESCRIPTION
	A generator over synapseclient.table.Column objects

Using this function (DEPRECATED)

Getting columns for a table

for column in syn.getColumns("syn12345"):
    print(column.name)

Getting columns with a prefix

for column in syn.getColumns("my_prefix"):
    print(column.name)

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Column, Table, EntityView, SubmissionView, Dataset, DatasetCollection

# Login to Synapse
syn = Synapse()
syn.login()

# For getting columns of a specific table/view/dataset
table = Table(id="syn12345")
table = table.get(include_columns=True)
for column_name, column in table.columns.items():
    print(f"Table column: {column_name}, Type: {column.column_type}")

# For EntityView
view = EntityView(id="syn67890")
view = view.get(include_columns=True)
for column_name, column in view.columns.items():
    print(f"EntityView column: {column_name}, Type: {column.column_type}")

# For SubmissionView
submission_view = SubmissionView(id="syn11111")
submission_view = submission_view.get(include_columns=True)
for column_name, column in submission_view.columns.items():
    print(f"SubmissionView column: {column_name}, Type: {column.column_type}")

# For Dataset
dataset = Dataset(id="syn22222")
dataset = dataset.get(include_columns=True)
for column_name, column in dataset.columns.items():
    print(f"Dataset column: {column_name}, Type: {column.column_type}")

# For DatasetCollection
dataset_collection = DatasetCollection(id="syn33333")
dataset_collection = dataset_collection.get(include_columns=True)
for column_name, column in dataset_collection.columns.items():
    print(f"DatasetCollection column: {column_name}, Type: {column.column_type}")

# For listing all columns with a prefix
for column in Column.list(prefix="my_prefix"):
    print(f"Prefixed column: {column.name}, Type: {column.column_type}")

# For listing all columns
for column in Column.list():
    print(f"All columns: {column.name}, Type: {column.column_type}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "For table columns, use the `.columns` attribute on Table, EntityView, SubmissionView, or Dataset classes after calling `.get(include_columns=True)`. "
    "For column listing and prefix filtering, use the `Column.list()` method. "
    "Check the docstring for the replacement function example.",
)
def getColumns(self, x, limit=100, offset=0):
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use the `.columns` attribute on table classes or `Column.list()` method instead.

    Get the columns defined in Synapse either (1) corresponding to a set of column headers, (2) those for a given
    schema, or (3) those whose names start with a given prefix.

    Arguments:
        x: A list of column headers, a Table Entity object (Schema/EntityViewSchema), a Table's Synapse ID, or a
            string prefix
        limit: Number of columns to retrieve per request to Synapse (pagination parameter).
            The function will continue retrieving results until all matching columns are returned.
        offset: the index of the first column to return (pagination parameter)

    Yields:
        A generator over [synapseclient.table.Column][] objects

    Example: Using this function (DEPRECATED)
        Getting columns for a table

            for column in syn.getColumns("syn12345"):
                print(column.name)

        Getting columns with a prefix

            for column in syn.getColumns("my_prefix"):
                print(column.name)

    Example: Migration to new method
         

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Column, Table, EntityView, SubmissionView, Dataset, DatasetCollection

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # For getting columns of a specific table/view/dataset
        table = Table(id="syn12345")
        table = table.get(include_columns=True)
        for column_name, column in table.columns.items():
            print(f"Table column: {column_name}, Type: {column.column_type}")

        # For EntityView
        view = EntityView(id="syn67890")
        view = view.get(include_columns=True)
        for column_name, column in view.columns.items():
            print(f"EntityView column: {column_name}, Type: {column.column_type}")

        # For SubmissionView
        submission_view = SubmissionView(id="syn11111")
        submission_view = submission_view.get(include_columns=True)
        for column_name, column in submission_view.columns.items():
            print(f"SubmissionView column: {column_name}, Type: {column.column_type}")

        # For Dataset
        dataset = Dataset(id="syn22222")
        dataset = dataset.get(include_columns=True)
        for column_name, column in dataset.columns.items():
            print(f"Dataset column: {column_name}, Type: {column.column_type}")

        # For DatasetCollection
        dataset_collection = DatasetCollection(id="syn33333")
        dataset_collection = dataset_collection.get(include_columns=True)
        for column_name, column in dataset_collection.columns.items():
            print(f"DatasetCollection column: {column_name}, Type: {column.column_type}")

        # For listing all columns with a prefix
        for column in Column.list(prefix="my_prefix"):
            print(f"Prefixed column: {column.name}, Type: {column.column_type}")

        # For listing all columns
        for column in Column.list():
            print(f"All columns: {column.name}, Type: {column.column_type}")

        ```
    """
    if x is None:
        uri = "/column"
        for result in self._GET_paginated(uri, limit=limit, offset=offset):
            yield Column(**result)
    elif isinstance(x, (list, tuple)):
        for header in x:
            try:
                # if header is an integer, it's a columnID, otherwise it's an aggregate column, like "AVG(Foo)"
                int(header)
                yield self.getColumn(header)
            except ValueError:
                # ignore aggregate column
                pass
    elif isinstance(x, SchemaBase) or utils.is_synapse_id_str(x):
        for col in self.getTableColumns(x):
            yield col
    elif isinstance(x, str):
        uri = "/column?prefix=" + x
        for result in self._GET_paginated(uri, limit=limit, offset=offset):
            yield Column(**result)
    else:
        ValueError("Can't get columns for a %s" % type(x))

getTableColumns

getTableColumns(table)

Deprecated with replacement. This method will be removed in 5.0.0. Use the columns attribute on synapseclient.models.Table instead.

Retrieve the column models used in the given table schema.

PARAMETER	DESCRIPTION
table	The schema of the Table whose columns are to be retrieved

YIELDS	DESCRIPTION
	A Generator over the Table's columns

Using this function (DEPRECATED)

Getting columns from a table schema:

columns = list(syn.getTableColumns("syn123"))

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Table, Dataset, DatasetCollection, EntityView, SubmissionView

# Login to Synapse
syn = Synapse()
syn.login()

# For Tables
table = Table(id="syn123").get()
columns = list(table.columns.values())
print("Columns in table:", columns)
# Access individual columns by name
my_table_column = table.columns["my_column_name"]

# For Datasets
dataset = Dataset(id="syn456").get()
columns = list(dataset.columns.values())
print("Columns in dataset:", columns)
# Access individual columns by name
my_dataset_column = dataset.columns["my_column_name"]

# For Dataset Collections
dataset_collection = DatasetCollection(id="syn789").get()
columns = list(dataset_collection.columns.values())
print("Columns in dataset collection:", columns)
# Access individual columns by name
my_collection_column = dataset_collection.columns["my_column_name"]

# For Entity Views
entity_view = EntityView(id="syn012").get()
columns = list(entity_view.columns.values())
print("Columns in entity view:", columns)
# Access individual columns by name
my_view_column = entity_view.columns["my_column_name"]

# For Submission Views
submission_view = SubmissionView(id="syn345").get()
columns = list(submission_view.columns.values())
print("Columns in submission view:", columns)
# Access individual columns by name
my_submission_column = submission_view.columns["my_column_name"]

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `columns` attribute on the `from synapseclient.models import Table` class. "
    "Check the docstring for the replacement function example.",
)
def getTableColumns(self, table):
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use the `columns` attribute on [synapseclient.models.Table][] instead.

    Retrieve the column models used in the given table schema.

    Arguments:
        table: The schema of the Table whose columns are to be retrieved

    Yields:
        A Generator over the Table's [columns][synapseclient.table.Column]

    Example: Using this function (DEPRECATED)
        Getting columns from a table schema:

            columns = list(syn.getTableColumns("syn123"))

    Example: Migration to new method
         

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Table, Dataset, DatasetCollection, EntityView, SubmissionView

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # For Tables
        table = Table(id="syn123").get()
        columns = list(table.columns.values())
        print("Columns in table:", columns)
        # Access individual columns by name
        my_table_column = table.columns["my_column_name"]

        # For Datasets
        dataset = Dataset(id="syn456").get()
        columns = list(dataset.columns.values())
        print("Columns in dataset:", columns)
        # Access individual columns by name
        my_dataset_column = dataset.columns["my_column_name"]

        # For Dataset Collections
        dataset_collection = DatasetCollection(id="syn789").get()
        columns = list(dataset_collection.columns.values())
        print("Columns in dataset collection:", columns)
        # Access individual columns by name
        my_collection_column = dataset_collection.columns["my_column_name"]

        # For Entity Views
        entity_view = EntityView(id="syn012").get()
        columns = list(entity_view.columns.values())
        print("Columns in entity view:", columns)
        # Access individual columns by name
        my_view_column = entity_view.columns["my_column_name"]

        # For Submission Views
        submission_view = SubmissionView(id="syn345").get()
        columns = list(submission_view.columns.values())
        print("Columns in submission view:", columns)
        # Access individual columns by name
        my_submission_column = submission_view.columns["my_column_name"]
        ```
    """
    uri = "/entity/{id}/column".format(id=id_of(table))
    # The returned object type for this service, PaginatedColumnModels, is a misnomer.
    # This service always returns the full list of results so the pagination does not not actually matter.
    for result in self.restGET(uri)["results"]:
        yield Column(**result)

downloadTableColumns

downloadTableColumns(table, columns, downloadLocation=None, **kwargs)

Bulk download of table-associated files.

PARAMETER	DESCRIPTION
table	Table query result
columns	A list of column names as strings
downloadLocation	Directory into which to download the files DEFAULT: None

RETURNS	DESCRIPTION
	A dictionary from file handle ID to path in the local file system.

For example, consider a Synapse table whose ID is "syn12345" with two columns of type FILEHANDLEID named 'foo' and 'bar'. The associated files are JSON encoded, so we might retrieve the files from Synapse and load for the second 100 of those rows as shown here:

import json

results = syn.tableQuery('SELECT * FROM syn12345 LIMIT 100 OFFSET 100')
file_map = syn.downloadTableColumns(results, ['foo', 'bar'])

for file_handle_id, path in file_map.items():
    with open(path) as f:
        data[file_handle_id] = f.read()

Source code in synapseclient/client.py

@deprecated(
    version="4.14.0",
    reason="To be removed in 5.0.0. This function has no replacement.",
)
def downloadTableColumns(self, table, columns, downloadLocation=None, **kwargs):
    """
    Bulk download of table-associated files.

    Arguments:
        table: Table query result
        columns: A list of column names as strings
        downloadLocation: Directory into which to download the files

    Returns:
        A dictionary from file handle ID to path in the local file system.

    For example, consider a Synapse table whose ID is "syn12345" with two columns of type FILEHANDLEID named 'foo'
    and 'bar'. The associated files are JSON encoded, so we might retrieve the files from Synapse and load for the
    second 100 of those rows as shown here:

        import json

        results = syn.tableQuery('SELECT * FROM syn12345 LIMIT 100 OFFSET 100')
        file_map = syn.downloadTableColumns(results, ['foo', 'bar'])

        for file_handle_id, path in file_map.items():
            with open(path) as f:
                data[file_handle_id] = f.read()

    """
    return wrap_async_to_sync(
        self.downloadTableColumns_async(table, columns, downloadLocation, **kwargs)
    )

get_acl

get_acl(entity: Union[Entity, Evaluation, str, Mapping], principal_id: str = None, check_benefactor: bool = True) -> List[str]

Deprecated with replacement. This method will be removed in 5.0.0. Use the get_acl method on the dataclass models that inherit from AccessControllable mixin instead.

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

PARAMETER	DESCRIPTION
entity	An Entity or Synapse ID to lookup TYPE: Union[Entity, Evaluation, str, Mapping]
principal_id	Identifier of a user or group (defaults to PUBLIC users) TYPE: str 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

RETURNS	DESCRIPTION
List[str]	An array containing some combination of ['READ', 'UPDATE', 'CREATE', 'DELETE', 'DOWNLOAD', 'MODERATE', 'CHANGE_PERMISSIONS', 'CHANGE_SETTINGS'] or an empty array

Using this function (DEPRECATED)

Getting ACL permissions for a user on an entity

permissions = syn.get_acl("syn123", principal_id="12345")

Getting ACL permissions for the public on an entity

permissions = syn.get_acl("syn123")

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import (
    File, Folder, Project, Table, EntityView, Dataset,
    DatasetCollection, MaterializedView, SubmissionView, VirtualTable
)

# Create client and login
syn = Synapse()
syn.login()

# Get ACL permissions for a specific user on a File
file_instance = File(id="syn123")
permissions = file_instance.get_acl(principal_id=12345)
print(f"User 12345 permissions on File syn123: {permissions}")

# Get ACL permissions for the public on a File
file_instance = File(id="syn123")
permissions = file_instance.get_acl()  # defaults to PUBLIC users
print(f"Public permissions on File syn123: {permissions}")

# Get ACL permissions with benefactor check disabled
file_instance = File(id="syn123")
permissions = file_instance.get_acl(
    principal_id=12345,
    check_benefactor=False
)
print(f"Entity-specific permissions for user 12345 on File syn123: {permissions}")

# Works with all AccessControllable models:

# Project
project = Project(id="syn123")
permissions = project.get_acl(principal_id=12345)
print(f"User 12345 permissions on Project syn123: {permissions}")

# Folder
folder = Folder(id="syn123")
permissions = folder.get_acl(principal_id=12345)
print(f"User 12345 permissions on Folder syn123: {permissions}")

# Table
table = Table(id="syn123")
permissions = table.get_acl(principal_id=12345)
print(f"User 12345 permissions on Table syn123: {permissions}")

# EntityView
entity_view = EntityView(id="syn123")
permissions = entity_view.get_acl(principal_id=12345)
print(f"User 12345 permissions on EntityView syn123: {permissions}")

# Dataset
dataset = Dataset(id="syn123")
permissions = dataset.get_acl(principal_id=12345)
print(f"User 12345 permissions on Dataset syn123: {permissions}")

# DatasetCollection
dataset_collection = DatasetCollection(id="syn123")
permissions = dataset_collection.get_acl(principal_id=12345)
print(f"User 12345 permissions on DatasetCollection syn123: {permissions}")

# MaterializedView
materialized_view = MaterializedView(id="syn123")
permissions = materialized_view.get_acl(principal_id=12345)
print(f"User 12345 permissions on MaterializedView syn123: {permissions}")

# SubmissionView
submission_view = SubmissionView(id="syn123")
permissions = submission_view.get_acl(principal_id=12345)
print(f"User 12345 permissions on SubmissionView syn123: {permissions}")

# VirtualTable
virtual_table = VirtualTable(id="syn123")
permissions = virtual_table.get_acl(principal_id=12345)
print(f"User 12345 permissions on VirtualTable syn123: {permissions}")

# Additional functionality available on AccessControllable models:

# List all ACL entries for an entity
file_instance = File(id="syn123")
acl_list = file_instance.list_acl()
print(f"All ACL entries for File syn123: {acl_list}")

# Delete the entire ACL for an entity (makes it inherit from benefactor)
file_instance = File(id="syn123")
file_instance.delete_permissions()
print("Successfully deleted entire ACL for File syn123 - now inherits permissions")

# To remove permissions for a specific user/group, use set_permissions with empty access_type
file_instance = File(id="syn123")
file_instance.set_permissions(principal_id=12345, access_type=[])
print("Successfully removed all permissions for user 12345 on File syn123")

# Use dry_run to preview what would be deleted without actually deleting
file_instance = File(id="syn123")
file_instance.delete_permissions(dry_run=True)
print("Dry run completed - showed what would be deleted")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `get_acl` method on the dataclass models that inherit from `AccessControllable` mixin. "
    "Example: `from synapseclient.models import File; File(id='syn123').get_acl()`",
)
def get_acl(
    self,
    entity: Union[Entity, Evaluation, str, collections.abc.Mapping],
    principal_id: str = None,
    check_benefactor: bool = True,
) -> typing.List[str]:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use the `get_acl` method on the dataclass models that inherit from `AccessControllable` mixin instead.

    Get the [ACL](https://rest-docs.synapse.org/rest/org/
    sagebionetworks/repo/model/ACCESS_TYPE.html)
    that a user or group has on an Entity.

    Arguments:
        entity:      An Entity or Synapse ID to lookup
        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.

    Returns:
        An array containing some combination of
            ['READ', 'UPDATE', 'CREATE', 'DELETE', 'DOWNLOAD', 'MODERATE',
            'CHANGE_PERMISSIONS', 'CHANGE_SETTINGS']
            or an empty array

    Example: Using this function (DEPRECATED)
        Getting ACL permissions for a user on an entity

            permissions = syn.get_acl("syn123", principal_id="12345")

        Getting ACL permissions for the public on an entity

            permissions = syn.get_acl("syn123")

    Example: Migration to new method
         

        ```python
        from synapseclient import Synapse
        from synapseclient.models import (
            File, Folder, Project, Table, EntityView, Dataset,
            DatasetCollection, MaterializedView, SubmissionView, VirtualTable
        )

        # Create client and login
        syn = Synapse()
        syn.login()

        # Get ACL permissions for a specific user on a File
        file_instance = File(id="syn123")
        permissions = file_instance.get_acl(principal_id=12345)
        print(f"User 12345 permissions on File syn123: {permissions}")

        # Get ACL permissions for the public on a File
        file_instance = File(id="syn123")
        permissions = file_instance.get_acl()  # defaults to PUBLIC users
        print(f"Public permissions on File syn123: {permissions}")

        # Get ACL permissions with benefactor check disabled
        file_instance = File(id="syn123")
        permissions = file_instance.get_acl(
            principal_id=12345,
            check_benefactor=False
        )
        print(f"Entity-specific permissions for user 12345 on File syn123: {permissions}")

        # Works with all AccessControllable models:

        # Project
        project = Project(id="syn123")
        permissions = project.get_acl(principal_id=12345)
        print(f"User 12345 permissions on Project syn123: {permissions}")

        # Folder
        folder = Folder(id="syn123")
        permissions = folder.get_acl(principal_id=12345)
        print(f"User 12345 permissions on Folder syn123: {permissions}")

        # Table
        table = Table(id="syn123")
        permissions = table.get_acl(principal_id=12345)
        print(f"User 12345 permissions on Table syn123: {permissions}")

        # EntityView
        entity_view = EntityView(id="syn123")
        permissions = entity_view.get_acl(principal_id=12345)
        print(f"User 12345 permissions on EntityView syn123: {permissions}")

        # Dataset
        dataset = Dataset(id="syn123")
        permissions = dataset.get_acl(principal_id=12345)
        print(f"User 12345 permissions on Dataset syn123: {permissions}")

        # DatasetCollection
        dataset_collection = DatasetCollection(id="syn123")
        permissions = dataset_collection.get_acl(principal_id=12345)
        print(f"User 12345 permissions on DatasetCollection syn123: {permissions}")

        # MaterializedView
        materialized_view = MaterializedView(id="syn123")
        permissions = materialized_view.get_acl(principal_id=12345)
        print(f"User 12345 permissions on MaterializedView syn123: {permissions}")

        # SubmissionView
        submission_view = SubmissionView(id="syn123")
        permissions = submission_view.get_acl(principal_id=12345)
        print(f"User 12345 permissions on SubmissionView syn123: {permissions}")

        # VirtualTable
        virtual_table = VirtualTable(id="syn123")
        permissions = virtual_table.get_acl(principal_id=12345)
        print(f"User 12345 permissions on VirtualTable syn123: {permissions}")

        # Additional functionality available on AccessControllable models:

        # List all ACL entries for an entity
        file_instance = File(id="syn123")
        acl_list = file_instance.list_acl()
        print(f"All ACL entries for File syn123: {acl_list}")

        # Delete the entire ACL for an entity (makes it inherit from benefactor)
        file_instance = File(id="syn123")
        file_instance.delete_permissions()
        print("Successfully deleted entire ACL for File syn123 - now inherits permissions")

        # To remove permissions for a specific user/group, use set_permissions with empty access_type
        file_instance = File(id="syn123")
        file_instance.set_permissions(principal_id=12345, access_type=[])
        print("Successfully removed all permissions for user 12345 on File syn123")

        # Use dry_run to preview what would be deleted without actually deleting
        file_instance = File(id="syn123")
        file_instance.delete_permissions(dry_run=True)
        print("Dry run completed - showed what would be deleted")
        ```
    """

    principal_id = self._getUserbyPrincipalIdOrName(principal_id)

    trace.get_current_span().set_attributes(
        {"synapse.id": id_of(entity), "synapse.principal_id": principal_id}
    )

    acl = self._getACL(entity=entity, check_benefactor=check_benefactor)

    team_list = self._find_teams_for_principal(principal_id)
    team_ids = [int(team.id) for team in team_list]
    effective_permission_set = set()

    # This user_profile_bundle is being used to verify that the principal_id
    #  is a registered user of the system
    user_profile_bundle = self._get_user_bundle(principal_id, 1)

    # Loop over all permissions in the returned ACL and add it to the effective_permission_set
    # if the principalId in the ACL matches
    # 1) the one we are looking for,
    # 2) a team the entity is a member of,
    # 3) PUBLIC
    # 4) A user_profile_bundle exists for the principal_id
    for permissions in acl["resourceAccess"]:
        if "principalId" in permissions and (
            permissions["principalId"] == principal_id
            or permissions["principalId"] in team_ids
            or permissions["principalId"] == PUBLIC
            or (
                permissions["principalId"] == AUTHENTICATED_USERS
                and user_profile_bundle is not None
            )
        ):
            effective_permission_set = effective_permission_set.union(
                permissions["accessType"]
            )
    return list(effective_permission_set)

get_permissions

get_permissions(entity: Union[Entity, Evaluation, str, Mapping]) -> Permissions

Deprecated with replacement. This method will be removed in 5.0.0. Use the get_permissions method on the dataclass models that inherit from AccessControllable mixin instead.

Get the permissions that the caller has on an Entity.

PARAMETER	DESCRIPTION
entity	An Entity or Synapse ID to lookup TYPE: Union[Entity, Evaluation, str, Mapping]

RETURNS	DESCRIPTION
Permissions	An Permissions object

Using this function (DEPRECATED)

Getting permissions for a Synapse Entity

permissions = syn.get_permissions(Entity)

Getting permissions for a Synapse ID

permissions = syn.get_permissions("syn12345")

Getting access types list from the Permissions object

permissions.access_types

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import (
    File, Folder, Project, Table, EntityView, Dataset,
    DatasetCollection, MaterializedView, SubmissionView, VirtualTable
)

# Create client and login
syn = Synapse()
syn.login()

# Get permissions for the current user on a File
file_instance = File(id="syn12345")
permissions = file_instance.get_permissions()
print(f"Current user permissions on File syn12345: {permissions}")
print(f"Current user access types: {permissions.access_types}")

# Get permissions for the current user on other entity types:

# Project
project = Project(id="syn12345")
permissions = project.get_permissions()
print(f"Current user permissions on Project {project.id}: {permissions}")
print(f"Current user access types: {permissions.access_types}")

# Folder
folder = Folder(id="syn12345")
permissions = folder.get_permissions()
print(f"Current user permissions on Folder {folder.id}: {permissions}")
print(f"Current user access types: {permissions.access_types}")

# Table
table = Table(id="syn12345")
permissions = table.get_permissions()
print(f"Current user permissions on Table {table.id}: {permissions}")
print(f"Current user access types: {permissions.access_types}")

# EntityView
entity_view = EntityView(id="syn12345")
permissions = entity_view.get_permissions()
print(f"Current user permissions on EntityView {entity_view.id}: {permissions}")
print(f"Current user access types: {permissions.access_types}")

# Dataset
dataset = Dataset(id="syn12345")
permissions = dataset.get_permissions()
print(f"Current user permissions on Dataset {dataset.id}: {permissions}")
print(f"Current user access types: {permissions.access_types}")

# DatasetCollection
dataset_collection = DatasetCollection(id="syn12345")
permissions = dataset_collection.get_permissions()
print(f"Current user permissions on DatasetCollection {dataset_collection.id}: {permissions}")
print(f"Current user access types: {permissions.access_types}")

# MaterializedView
materialized_view = MaterializedView(id="syn12345")
permissions = materialized_view.get_permissions()
print(f"Current user permissions on MaterializedView {materialized_view.id}: {permissions}")
print(f"Current user access types: {permissions.access_types}")

# SubmissionView
submission_view = SubmissionView(id="syn12345")
permissions = submission_view.get_permissions()
print(f"Current user permissions on SubmissionView {submission_view.id}: {permissions}")
print(f"Current user access types: {permissions.access_types}")

# VirtualTable
virtual_table = VirtualTable(id="syn12345")
permissions = virtual_table.get_permissions()
print(f"Current user permissions on VirtualTable {virtual_table.id}: {permissions}")
print(f"Current user access types: {permissions.access_types}")

# To get permissions for a specific user/group, use get_acl instead:
file_instance = File(id="syn12345")

# Get ACL permissions for a specific user
user_permissions = file_instance.get_acl(principal_id=12345)
print(f"User 12345 permissions on File {file_instance.id}: {user_permissions}")

# Get ACL permissions for the public
public_permissions = file_instance.get_acl()  # defaults to PUBLIC users
print(f"Public permissions on File {file_instance.id}: {public_permissions}")

# List all ACL entries for an entity
acl_list = file_instance.list_acl()
print(f"All ACL entries for File {file_instance.id}: {acl_list}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `get_permissions` method on the dataclass models that inherit from `AccessControllable` mixin. "
    "Note: The new `get_permissions` method only returns permissions for the current user. "
    "To get permissions for a specific principal, use the `get_acl` method instead. "
    "Example: `from synapseclient.models import File; File(id='syn123').get_permissions(); File(id='syn123').get_acl(principal_id=12345)`",
)
def get_permissions(
    self, entity: Union[Entity, Evaluation, str, collections.abc.Mapping]
) -> Permissions:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use the `get_permissions` method on the dataclass models that inherit from `AccessControllable` mixin instead.

    Get the [permissions](https://rest-docs.synapse.org/rest/org/
    sagebionetworks/repo/model/auth/UserEntityPermissions.html)
    that the caller has on an Entity.

    Arguments:
        entity: An Entity or Synapse ID to lookup

    Returns:
        An Permissions object

    Example: Using this function (DEPRECATED)
        Getting permissions for a Synapse Entity

            permissions = syn.get_permissions(Entity)

        Getting permissions for a Synapse ID

            permissions = syn.get_permissions("syn12345")

        Getting access types list from the Permissions object

            permissions.access_types

    Example: Migration to new method
         

        ```python
        from synapseclient import Synapse
        from synapseclient.models import (
            File, Folder, Project, Table, EntityView, Dataset,
            DatasetCollection, MaterializedView, SubmissionView, VirtualTable
        )

        # Create client and login
        syn = Synapse()
        syn.login()

        # Get permissions for the current user on a File
        file_instance = File(id="syn12345")
        permissions = file_instance.get_permissions()
        print(f"Current user permissions on File syn12345: {permissions}")
        print(f"Current user access types: {permissions.access_types}")

        # Get permissions for the current user on other entity types:

        # Project
        project = Project(id="syn12345")
        permissions = project.get_permissions()
        print(f"Current user permissions on Project {project.id}: {permissions}")
        print(f"Current user access types: {permissions.access_types}")

        # Folder
        folder = Folder(id="syn12345")
        permissions = folder.get_permissions()
        print(f"Current user permissions on Folder {folder.id}: {permissions}")
        print(f"Current user access types: {permissions.access_types}")

        # Table
        table = Table(id="syn12345")
        permissions = table.get_permissions()
        print(f"Current user permissions on Table {table.id}: {permissions}")
        print(f"Current user access types: {permissions.access_types}")

        # EntityView
        entity_view = EntityView(id="syn12345")
        permissions = entity_view.get_permissions()
        print(f"Current user permissions on EntityView {entity_view.id}: {permissions}")
        print(f"Current user access types: {permissions.access_types}")

        # Dataset
        dataset = Dataset(id="syn12345")
        permissions = dataset.get_permissions()
        print(f"Current user permissions on Dataset {dataset.id}: {permissions}")
        print(f"Current user access types: {permissions.access_types}")

        # DatasetCollection
        dataset_collection = DatasetCollection(id="syn12345")
        permissions = dataset_collection.get_permissions()
        print(f"Current user permissions on DatasetCollection {dataset_collection.id}: {permissions}")
        print(f"Current user access types: {permissions.access_types}")

        # MaterializedView
        materialized_view = MaterializedView(id="syn12345")
        permissions = materialized_view.get_permissions()
        print(f"Current user permissions on MaterializedView {materialized_view.id}: {permissions}")
        print(f"Current user access types: {permissions.access_types}")

        # SubmissionView
        submission_view = SubmissionView(id="syn12345")
        permissions = submission_view.get_permissions()
        print(f"Current user permissions on SubmissionView {submission_view.id}: {permissions}")
        print(f"Current user access types: {permissions.access_types}")

        # VirtualTable
        virtual_table = VirtualTable(id="syn12345")
        permissions = virtual_table.get_permissions()
        print(f"Current user permissions on VirtualTable {virtual_table.id}: {permissions}")
        print(f"Current user access types: {permissions.access_types}")

        # To get permissions for a specific user/group, use get_acl instead:
        file_instance = File(id="syn12345")

        # Get ACL permissions for a specific user
        user_permissions = file_instance.get_acl(principal_id=12345)
        print(f"User 12345 permissions on File {file_instance.id}: {user_permissions}")

        # Get ACL permissions for the public
        public_permissions = file_instance.get_acl()  # defaults to PUBLIC users
        print(f"Public permissions on File {file_instance.id}: {public_permissions}")

        # List all ACL entries for an entity
        acl_list = file_instance.list_acl()
        print(f"All ACL entries for File {file_instance.id}: {acl_list}")
        ```
    """

    entity_id = id_of(entity)

    trace.get_current_span().set_attributes({"synapse.id": entity_id})

    url = f"/entity/{entity_id}/permissions"
    data = self.restGET(url)
    return Permissions.from_dict(data)

getPermissions

getPermissions(entity: Union[Entity, Evaluation, str, Mapping], principal_id: str = None) -> List[str]

Deprecated and replaced with get_acl.

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

PARAMETER	DESCRIPTION
entity	An Entity or Synapse ID to lookup TYPE: Union[Entity, Evaluation, str, Mapping]
principal_id	Identifier of a user or group (defaults to PUBLIC users) TYPE: str 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/client.py

@deprecated(
    version="4.0.0",
    reason="deprecated and replaced with synapseclient.Synapse.get_acl",
)
def getPermissions(
    self,
    entity: Union[Entity, Evaluation, str, collections.abc.Mapping],
    principal_id: str = None,
) -> typing.List[str]:
    """
    **Deprecated** and replaced with [get_acl][synapseclient.Synapse.get_acl].


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

    Arguments:
        entity:      An Entity or Synapse ID to lookup
        principal_id: Identifier of a user or group (defaults to PUBLIC users)

    Returns:
        An array containing some combination of
            ['READ', 'UPDATE', 'CREATE', 'DELETE', 'DOWNLOAD', 'MODERATE',
            'CHANGE_PERMISSIONS', 'CHANGE_SETTINGS']
            or an empty array
    """

    return self.get_acl(entity=entity, principal_id=principal_id)

setPermissions

setPermissions(entity, principalId=None, accessType=['READ', 'DOWNLOAD'], modify_benefactor=False, warn_if_inherits=True, overwrite=True)

Deprecated with replacement. This method will be removed in 5.0.0. Use the set_permissions method on the dataclass models that inherit from AccessControllable mixin instead.

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
entity	An Entity or Synapse ID to modify
principalId	Identifier of a user or group. '273948' is for all registered Synapse users and '273949' is for public access. None implies public access. DEFAULT: None
accessType	Type of permission to be granted. One or more of CREATE, READ, DOWNLOAD, UPDATE, DELETE, CHANGE_PERMISSIONS DEFAULT: ['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. 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. 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. DEFAULT: True

RETURNS	DESCRIPTION
	An Access Control List object

Using this function (DEPRECATED)

Grant all registered users download access

syn.setPermissions('syn1234','273948',['READ','DOWNLOAD'])

Grant the public view access

syn.setPermissions('syn1234','273949',['READ'])

Migration to new method

 

from synapseclient import Synapse, AUTHENTICATED_USERS, PUBLIC
from synapseclient.models import (
    File, Folder, Project, Table, EntityView, Dataset,
    DatasetCollection, MaterializedView, SubmissionView, VirtualTable
)

# Create client and login
syn = Synapse()
syn.login()

# Set permissions for a File
file_instance = File(id="syn1234")

# Grant all registered users download access
file_instance.set_permissions(
    principal_id=AUTHENTICATED_USERS,
    access_type=["READ", "DOWNLOAD"]
)
print(f"Successfully granted READ and DOWNLOAD access to all registered users on File {file_instance.id}")

# Grant the public view access
file_instance.set_permissions(
    principal_id=PUBLIC,
    access_type=["READ"]
)
print(f"Successfully granted READ access to public users on File {file_instance.id}")

# Set permissions with additional options
file_instance.set_permissions(
    principal_id=12345,
    access_type=["READ", "DOWNLOAD", "UPDATE"],
    modify_benefactor=True,
    warn_if_inherits=False,
    overwrite=False  # Add to existing permissions instead of overwriting
)
print(f"Successfully added READ, DOWNLOAD, and UPDATE access for user 12345 on File {file_instance.id}")

# Remove permissions for a specific user/group by setting access_type to empty list
file_instance.set_permissions(
    principal_id=12345,
    access_type=[]  # Empty list removes all permissions for this principal
)
print(f"Successfully removed all permissions for user 12345 on File {file_instance.id}")

# Alternative: Remove permissions by setting access_type to None
file_instance.set_permissions(
    principal_id=12345,
    access_type=None  # None also removes all permissions for this principal
)
print(f"Successfully removed all permissions for user 12345 on File {file_instance.id}")

# Set permissions for other entity types:

# Project
project = Project(id="syn1234")
project.set_permissions(
    principal_id=12345,
    access_type=["READ", "DOWNLOAD"]
)
print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on Project {project.id}")

# Folder
folder = Folder(id="syn1234")
folder.set_permissions(
    principal_id=12345,
    access_type=["READ", "DOWNLOAD"]
)
print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on Folder {folder.id}")

# Table
table = Table(id="syn1234")
table.set_permissions(
    principal_id=12345,
    access_type=["READ", "DOWNLOAD"]
)
print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on Table {table.id}")

# EntityView
entity_view = EntityView(id="syn1234")
entity_view.set_permissions(
    principal_id=12345,
    access_type=["READ", "DOWNLOAD"]
)
print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on EntityView {entity_view.id}")

# Dataset
dataset = Dataset(id="syn1234")
dataset.set_permissions(
    principal_id=12345,
    access_type=["READ", "DOWNLOAD"]
)
print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on Dataset {dataset.id}")

# DatasetCollection
dataset_collection = DatasetCollection(id="syn1234")
dataset_collection.set_permissions(
    principal_id=12345,
    access_type=["READ", "DOWNLOAD"]
)
print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on DatasetCollection {dataset_collection.id}")

# MaterializedView
materialized_view = MaterializedView(id="syn1234")
materialized_view.set_permissions(
    principal_id=12345,
    access_type=["READ", "DOWNLOAD"]
)
print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on MaterializedView {materialized_view.id}")

# SubmissionView
submission_view = SubmissionView(id="syn1234")
submission_view.set_permissions(
    principal_id=12345,
    access_type=["READ", "DOWNLOAD"]
)
print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on SubmissionView {submission_view.id}")

# VirtualTable
virtual_table = VirtualTable(id="syn1234")
virtual_table.set_permissions(
    principal_id=12345,
    access_type=["READ", "DOWNLOAD"]
)
print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on VirtualTable {virtual_table.id}")

# Additional functionality available on AccessControllable models:

# List all ACL entries for an entity
file_instance = File(id="syn1234")
acl_list = file_instance.list_acl()
print(f"All ACL entries for File syn1234: {acl_list}")

# Delete the entire ACL for an entity (makes it inherit from benefactor)
file_instance = File(id="syn1234")
file_instance.delete_permissions()
print(f"Successfully deleted entire ACL for File {file_instance.id} - now inherits permissions")

# To remove permissions for a specific user/group, use set_permissions with empty access_type
file_instance = File(id="syn1234")
file_instance.set_permissions(principal_id=12345, access_type=[])
print(f"Successfully removed all permissions for user 12345 on File {file_instance.id}")

# Use dry_run to preview what would be deleted without actually deleting
file_instance = File(id="syn1234")
file_instance.delete_permissions(dry_run=True)
print("Dry run completed - showed what would be deleted")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `set_permissions` method on the dataclass models that inherit from `AccessControllable` mixin. "
    "Example: `from synapseclient.models import File; File(id='syn123').set_permissions(principal_id=12345, access_type=['READ'])`. "
    "To remove permissions for a specific user, use `access_type=[]` or `access_type=None`.",
)
def setPermissions(
    self,
    entity,
    principalId=None,
    accessType=["READ", "DOWNLOAD"],
    modify_benefactor=False,
    warn_if_inherits=True,
    overwrite=True,
):
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use the `set_permissions` method on the dataclass models that inherit from `AccessControllable` mixin instead.

    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:
        entity: An Entity or Synapse ID to modify
        principalId: Identifier of a user or group. '273948' is for all registered Synapse users
                        and '273949' is for public access. None implies public access.
        accessType: Type of permission to be granted. One or more of CREATE, READ, DOWNLOAD, UPDATE,
                        DELETE, CHANGE_PERMISSIONS
        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.

    Returns:
        An Access Control List object

    Example: Using this function (DEPRECATED)
        Grant all registered users download access

            syn.setPermissions('syn1234','273948',['READ','DOWNLOAD'])

        Grant the public view access

            syn.setPermissions('syn1234','273949',['READ'])

    Example: Migration to new method
         

        ```python
        from synapseclient import Synapse, AUTHENTICATED_USERS, PUBLIC
        from synapseclient.models import (
            File, Folder, Project, Table, EntityView, Dataset,
            DatasetCollection, MaterializedView, SubmissionView, VirtualTable
        )

        # Create client and login
        syn = Synapse()
        syn.login()

        # Set permissions for a File
        file_instance = File(id="syn1234")

        # Grant all registered users download access
        file_instance.set_permissions(
            principal_id=AUTHENTICATED_USERS,
            access_type=["READ", "DOWNLOAD"]
        )
        print(f"Successfully granted READ and DOWNLOAD access to all registered users on File {file_instance.id}")

        # Grant the public view access
        file_instance.set_permissions(
            principal_id=PUBLIC,
            access_type=["READ"]
        )
        print(f"Successfully granted READ access to public users on File {file_instance.id}")

        # Set permissions with additional options
        file_instance.set_permissions(
            principal_id=12345,
            access_type=["READ", "DOWNLOAD", "UPDATE"],
            modify_benefactor=True,
            warn_if_inherits=False,
            overwrite=False  # Add to existing permissions instead of overwriting
        )
        print(f"Successfully added READ, DOWNLOAD, and UPDATE access for user 12345 on File {file_instance.id}")

        # Remove permissions for a specific user/group by setting access_type to empty list
        file_instance.set_permissions(
            principal_id=12345,
            access_type=[]  # Empty list removes all permissions for this principal
        )
        print(f"Successfully removed all permissions for user 12345 on File {file_instance.id}")

        # Alternative: Remove permissions by setting access_type to None
        file_instance.set_permissions(
            principal_id=12345,
            access_type=None  # None also removes all permissions for this principal
        )
        print(f"Successfully removed all permissions for user 12345 on File {file_instance.id}")

        # Set permissions for other entity types:

        # Project
        project = Project(id="syn1234")
        project.set_permissions(
            principal_id=12345,
            access_type=["READ", "DOWNLOAD"]
        )
        print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on Project {project.id}")

        # Folder
        folder = Folder(id="syn1234")
        folder.set_permissions(
            principal_id=12345,
            access_type=["READ", "DOWNLOAD"]
        )
        print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on Folder {folder.id}")

        # Table
        table = Table(id="syn1234")
        table.set_permissions(
            principal_id=12345,
            access_type=["READ", "DOWNLOAD"]
        )
        print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on Table {table.id}")

        # EntityView
        entity_view = EntityView(id="syn1234")
        entity_view.set_permissions(
            principal_id=12345,
            access_type=["READ", "DOWNLOAD"]
        )
        print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on EntityView {entity_view.id}")

        # Dataset
        dataset = Dataset(id="syn1234")
        dataset.set_permissions(
            principal_id=12345,
            access_type=["READ", "DOWNLOAD"]
        )
        print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on Dataset {dataset.id}")

        # DatasetCollection
        dataset_collection = DatasetCollection(id="syn1234")
        dataset_collection.set_permissions(
            principal_id=12345,
            access_type=["READ", "DOWNLOAD"]
        )
        print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on DatasetCollection {dataset_collection.id}")

        # MaterializedView
        materialized_view = MaterializedView(id="syn1234")
        materialized_view.set_permissions(
            principal_id=12345,
            access_type=["READ", "DOWNLOAD"]
        )
        print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on MaterializedView {materialized_view.id}")

        # SubmissionView
        submission_view = SubmissionView(id="syn1234")
        submission_view.set_permissions(
            principal_id=12345,
            access_type=["READ", "DOWNLOAD"]
        )
        print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on SubmissionView {submission_view.id}")

        # VirtualTable
        virtual_table = VirtualTable(id="syn1234")
        virtual_table.set_permissions(
            principal_id=12345,
            access_type=["READ", "DOWNLOAD"]
        )
        print(f"Successfully set READ and DOWNLOAD permissions for user 12345 on VirtualTable {virtual_table.id}")

        # Additional functionality available on AccessControllable models:

        # List all ACL entries for an entity
        file_instance = File(id="syn1234")
        acl_list = file_instance.list_acl()
        print(f"All ACL entries for File syn1234: {acl_list}")

        # Delete the entire ACL for an entity (makes it inherit from benefactor)
        file_instance = File(id="syn1234")
        file_instance.delete_permissions()
        print(f"Successfully deleted entire ACL for File {file_instance.id} - now inherits permissions")

        # To remove permissions for a specific user/group, use set_permissions with empty access_type
        file_instance = File(id="syn1234")
        file_instance.set_permissions(principal_id=12345, access_type=[])
        print(f"Successfully removed all permissions for user 12345 on File {file_instance.id}")

        # Use dry_run to preview what would be deleted without actually deleting
        file_instance = File(id="syn1234")
        file_instance.delete_permissions(dry_run=True)
        print("Dry run completed - showed what would be deleted")
        ```
    """
    entity_id = id_of(entity)
    trace.get_current_span().set_attributes({"synapse.id": entity_id})

    benefactor = self._getBenefactor(entity)
    if benefactor["id"] != entity_id:
        if modify_benefactor:
            entity = benefactor
        elif warn_if_inherits:
            self.logger.warning(
                "Creating an ACL for entity %s, which formerly inherited access control from a"
                ' benefactor entity, "%s" (%s).\n'
                % (entity_id, benefactor["name"], benefactor["id"])
            )

    acl = self._getACL(entity)

    principalId = self._getUserbyPrincipalIdOrName(principalId)

    # Find existing permissions
    permissions_to_update = None
    for permissions in acl["resourceAccess"]:
        if (
            "principalId" in permissions
            and permissions["principalId"] == principalId
        ):
            permissions_to_update = permissions
            break

    if accessType is None or accessType == []:
        # remove permissions
        if permissions_to_update and overwrite:
            acl["resourceAccess"].remove(permissions_to_update)
    else:
        # add a 'resourceAccess' entry, if necessary
        if not permissions_to_update:
            permissions_to_update = {"accessType": [], "principalId": principalId}
            acl["resourceAccess"].append(permissions_to_update)
        if overwrite:
            permissions_to_update["accessType"] = accessType
        else:
            permissions_to_update["accessType"] = list(
                set(permissions_to_update["accessType"]) | set(accessType)
            )
    return self._storeACL(entity, acl)

getProvenance

getProvenance(entity: Union[str, Mapping, Number], version: int = None) -> Activity

Deprecated with replacement. This method will be removed in 5.0.0. Use [synapseclient.models.Activity.get][] instead.

Retrieve provenance information for a Synapse Entity.

PARAMETER	DESCRIPTION
entity	An Entity or Synapse ID to lookup TYPE: Union[str, Mapping, Number]
version	The version of the Entity to retrieve. Gets the most recent version if omitted TYPE: int DEFAULT: None

RETURNS	DESCRIPTION
Activity	An Activity object or raises exception if no provenance record exists

RAISES	DESCRIPTION
SynapseHTTPError	if no provenance record exists

Using this function (DEPRECATED)

Getting provenance for an entity

activity = syn.getProvenance("syn123")

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Activity

# Login to Synapse
syn = Synapse()
syn.login()

# Get the activity associated with the entity
activity = Activity.get(parent_id="syn123")
if activity:
    print(f"Activity: {activity.name}")
else:
    print("No activity found")

# Get the activity for a specific version
activity = Activity.get(parent_id="syn123", parent_version_number=2)
if activity:
    print(f"Activity: {activity.name}")
else:
    print("No activity found")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `get` method on the `from synapseclient.models import Activity` class. "
    "Check the docstring for the replacement function example.",
)
def getProvenance(
    self,
    entity: typing.Union[str, collections.abc.Mapping, numbers.Number],
    version: int = None,
) -> Activity:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.models.Activity.get][] instead.

    Retrieve provenance information for a Synapse Entity.

    Arguments:
        entity:  An Entity or Synapse ID to lookup
        version: The version of the Entity to retrieve. Gets the most recent version if omitted

    Returns:
        An Activity object or raises exception if no provenance record exists

    Raises:
        SynapseHTTPError: if no provenance record exists

    Example: Using this function (DEPRECATED)
        Getting provenance for an entity

            activity = syn.getProvenance("syn123")

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Get the activity associated with the entity
        activity = Activity.get(parent_id="syn123")
        if activity:
            print(f"Activity: {activity.name}")
        else:
            print("No activity found")

        # Get the activity for a specific version
        activity = Activity.get(parent_id="syn123", parent_version_number=2)
        if activity:
            print(f"Activity: {activity.name}")
        else:
            print("No activity found")
        ```
    """
    # Get versionNumber from Entity
    if version is None and "versionNumber" in entity:
        version = entity["versionNumber"]
    entity_id = id_of(entity)
    if version:
        uri = "/entity/%s/version/%d/generatedBy" % (entity_id, version)
    else:
        uri = "/entity/%s/generatedBy" % entity_id

    trace.get_current_span().set_attributes({"synapse.id": entity_id})
    return Activity(data=self.restGET(uri))

setProvenance

setProvenance(entity: Union[str, Mapping, Number], activity: Activity) -> Activity

Deprecated with replacement. This method will be removed in 5.0.0. Use synapseclient.models.Activity.store instead.

Stores a record of the code and data used to derive a Synapse entity.

PARAMETER	DESCRIPTION
entity	An Entity or Synapse ID to modify TYPE: Union[str, Mapping, Number]
activity	A synapseclient.activity.Activity TYPE: Activity

RETURNS	DESCRIPTION
Activity	An updated synapseclient.activity.Activity object

Using this function (DEPRECATED)

Setting provenance for an entity

activity = Activity(name="Analysis", description="Data processing")
updated_activity = syn.setProvenance("syn123", activity)

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Activity

# Login to Synapse
syn = Synapse()
syn.login()

# Create an activity
activity = Activity(
    name="Analysis",
    description="Data processing"
)

# Store the activity and associate it with the entity
stored_activity = activity.store(parent="syn123")
print(f"Stored activity: {stored_activity.name}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `store` method on the `from synapseclient.models import Activity` class. "
    "Check the docstring for the replacement function example.",
)
def setProvenance(
    self,
    entity: typing.Union[str, collections.abc.Mapping, numbers.Number],
    activity: Activity,
) -> Activity:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.models.Activity.store][] instead.

    Stores a record of the code and data used to derive a Synapse entity.

    Arguments:
        entity:   An Entity or Synapse ID to modify
        activity: A [synapseclient.activity.Activity][]

    Returns:
        An updated [synapseclient.activity.Activity][] object

    Example: Using this function (DEPRECATED)
        Setting provenance for an entity

            activity = Activity(name="Analysis", description="Data processing")
            updated_activity = syn.setProvenance("syn123", activity)

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Create an activity
        activity = Activity(
            name="Analysis",
            description="Data processing"
        )

        # Store the activity and associate it with the entity
        stored_activity = activity.store(parent="syn123")
        print(f"Stored activity: {stored_activity.name}")
        ```
    """
    # Assert that the entity was generated by a given Activity.
    activity = self._saveActivity(activity)

    entity_id = id_of(entity)
    # assert that an entity is generated by an activity
    uri = "/entity/%s/generatedBy?generatedBy=%s" % (entity_id, activity["id"])
    activity = Activity(data=self.restPUT(uri))

    trace.get_current_span().set_attributes({"synapse.id": entity_id})
    return activity

deleteProvenance

deleteProvenance(entity: Union[str, Mapping, Number]) -> None

Deprecated with replacement. This method will be removed in 5.0.0. Use synapseclient.models.Activity.delete instead.

Removes provenance information from an Entity and deletes the associated Activity.

PARAMETER	DESCRIPTION
entity	An Entity or Synapse ID to modify TYPE: Union[str, Mapping, Number]

Using this function (DEPRECATED)

Deleting provenance for an entity

syn.deleteProvenance("syn123")

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Activity

# Login to Synapse
syn = Synapse()
syn.login()

# Delete the activity associated with the entity
Activity.delete(parent="syn123")
print("Activity deleted")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `delete` method on the `from synapseclient.models import Activity` class. "
    "Check the docstring for the replacement function example.",
)
def deleteProvenance(
    self,
    entity: typing.Union[str, collections.abc.Mapping, numbers.Number],
) -> None:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.models.Activity.delete][] instead.

    Removes provenance information from an Entity and deletes the associated Activity.

    Arguments:
        entity: An Entity or Synapse ID to modify

    Example: Using this function (DEPRECATED)
        Deleting provenance for an entity

            syn.deleteProvenance("syn123")

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Delete the activity associated with the entity
        Activity.delete(parent="syn123")
        print("Activity deleted")
        ```
    """
    activity = self.getProvenance(entity)
    if not activity:
        return
    entity_id = id_of(entity)
    trace.get_current_span().set_attributes({"synapse.id": entity_id})

    uri = "/entity/%s/generatedBy" % entity_id
    self.restDELETE(uri)

    # If the activity is shared by more than one entity you recieve an HTTP 400 error:
    # "If you wish to delete this activity, please first delete all Entities generated by this Activity.""
    uri = "/activity/%s" % activity["id"]
    self.restDELETE(uri)

updateActivity

updateActivity(activity) -> Activity

Deprecated with replacement. This method will be removed in 5.0.0. Use synapseclient.models.Activity.store instead.

Modifies an existing Activity.

PARAMETER	DESCRIPTION
activity	The Activity to be updated.

RETURNS	DESCRIPTION
Activity	An updated Activity object

Using this function (DEPRECATED)

Updating an existing activity

activity = syn.getProvenance("syn123")
activity['name'] = "Updated Analysis"
updated_activity = syn.updateActivity(activity)

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Activity

# Login to Synapse
syn = Synapse()
syn.login()

# Get the existing activity by parent entity
activity = Activity.get(parent_id="syn123")

if activity:
    # Update the activity
    activity.name = "Updated Analysis"
    activity.description = "Updated data processing"

    # Store the updated activity
    updated_activity = activity.store()
    print(f"Updated activity: {updated_activity.name}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `store` method on the `from synapseclient.models import Activity` class. "
    "Check the docstring for the replacement function example.",
)
def updateActivity(self, activity) -> Activity:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.models.Activity.store][] instead.

    Modifies an existing Activity.

    Arguments:
        activity: The Activity to be updated.

    Returns:
        An updated Activity object

    Example: Using this function (DEPRECATED)
        Updating an existing activity

            activity = syn.getProvenance("syn123")
            activity['name'] = "Updated Analysis"
            updated_activity = syn.updateActivity(activity)

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Get the existing activity by parent entity
        activity = Activity.get(parent_id="syn123")

        if activity:
            # Update the activity
            activity.name = "Updated Analysis"
            activity.description = "Updated data processing"

            # Store the updated activity
            updated_activity = activity.store()
            print(f"Updated activity: {updated_activity.name}")
        ```
    """
    if "id" not in activity:
        raise ValueError("The activity you want to update must exist on Synapse")
    trace.get_current_span().set_attributes({"synapse.id": activity["id"]})
    return self._saveActivity(activity)

findEntityId

findEntityId(name, parent=None)

Find an Entity given its name and parent.

PARAMETER	DESCRIPTION
name	Name of the entity to find
parent	An Entity object or the Id of an entity as a string. Omit if searching for a Project by name DEFAULT: None

RETURNS	DESCRIPTION
	The Entity ID or None if not found

Source code in synapseclient/client.py

@deprecated(
    version="4.11.0",
    reason="To be removed in 5.0.0. "
    "Use `from synapseclient.operations import find_entity_id` instead.",
)
def findEntityId(self, name, parent=None):
    """
    Find an Entity given its name and parent.

    Arguments:
        name: Name of the entity to find
        parent: An Entity object or the Id of an entity as a string. Omit if searching for a Project by name

    Returns:
        The Entity ID or None if not found
    """
    # when we want to search for a project by name. set parentId as None instead of ROOT_ENTITY
    entity_lookup_request = {
        "parentId": id_of(parent) if parent else None,
        "entityName": name,
    }
    try:
        return self.restPOST(
            "/entity/child", body=json.dumps(entity_lookup_request)
        ).get("id")
    except SynapseHTTPError as e:
        if (
            e.response.status_code == 404
        ):  # a 404 error is raised if the entity does not exist
            return None
        raise

getChildren

getChildren(parent, includeTypes=['folder', 'file', 'table', 'link', 'entityview', 'dockerrepo', 'submissionview', 'dataset', 'materializedview'], sortBy='NAME', sortDirection='ASC')

Retrieves all of the entities stored within a parent such as folder or project.

PARAMETER	DESCRIPTION
parent	An id or an object of a Synapse container or None to retrieve all projects
includeTypes	Must be a list of entity types (ie. ["folder","file"]) which can be found here DEFAULT: ['folder', 'file', 'table', 'link', 'entityview', 'dockerrepo', 'submissionview', 'dataset', 'materializedview']
sortBy	How results should be sorted. Can be NAME, or CREATED_ON DEFAULT: 'NAME'
sortDirection	The direction of the result sort. Can be ASC, or DESC DEFAULT: 'ASC'

YIELDS	DESCRIPTION
	An iterator that shows all the children of the container.

Also see:

• synapseutils.walk

Migrating from this method to new approaches

 

Legacy approach (deprecated):

# Using the deprecated getChildren method
for child in syn.getChildren("syn12345", includeTypes=["file", "folder"]):
    print(f"Child: {child['name']} (ID: {child['id']})")

New approach using dataclass models with sync_from_synapse:

import synapseclient
from synapseclient.models import Project, Folder

# Create client and login
syn = synapseclient.Synapse()
syn.login()

# For projects - get all children automatically (recursive by default)
project = Project(id="syn12345")
project = project.sync_from_synapse(download_file=False)

# Access different types of children
print(f"Files: {len(project.files)}")
for file in project.files:
    print(f"  File: {file.name} (ID: {file.id})")

print(f"Folders: {len(project.folders)}")
for folder in project.folders:
    print(f"  Folder: {folder.name} (ID: {folder.id})")

print(f"Tables: {len(project.tables)}")
for table in project.tables:
    print(f"  Table: {table.name} (ID: {table.id})")

# For folders - get all children automatically (recursive by default)
folder = Folder(id="syn67890")
folder = folder.sync_from_synapse(download_file=False)

# Access children in the same way
for file in folder.files:
    print(f"  File: {file.name} (ID: {file.id})")

# For non-recursive behavior (equivalent to single getChildren call)
folder = Folder(id="syn67890")
folder = folder.sync_from_synapse(download_file=False, recursive=False)

# This will only get immediate children, not subfolders' contents
for file in folder.files:
    print(f"  File: {file.name} (ID: {file.id})")
for subfolder in folder.folders:
    print(f"  Subfolder: {subfolder.name} (ID: {subfolder.id})")
    # Note: subfolder.files and subfolder.folders will be empty
    # because recursive=False

New approach using the API directly (for advanced sorting/filtering):

import asyncio
import synapseclient
from synapseclient.api import get_children

# Create client and login
syn = synapseclient.Synapse()
syn.login()

# Using the new async API function directly
async def get_sorted_children():
    async for child in get_children(
        parent="syn12345",
        include_types=["file", "folder"],
        sort_by="NAME",
        sort_direction="ASC"
    ):
        print(f"Child: {child['name']} (ID: {child['id']}, Type: {child['type']})")

# Run the async function
asyncio.run(get_sorted_children())

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Use the new dataclass models `from synapseclient.models import Project, Folder` "
    "with their `sync_from_synapse` method for most use cases, "
    "or the `synapseclient.api.get_children` function for direct API access with sorting and filtering.",
)
def getChildren(
    self,
    parent,
    includeTypes=[
        "folder",
        "file",
        "table",
        "link",
        "entityview",
        "dockerrepo",
        "submissionview",
        "dataset",
        "materializedview",
    ],
    sortBy="NAME",
    sortDirection="ASC",
):
    """
    Retrieves all of the entities stored within a parent such as folder or project.

    Arguments:
        parent: An id or an object of a Synapse container or None to retrieve all projects
        includeTypes: Must be a list of entity types (ie. ["folder","file"]) which can be found [here](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/EntityType.html)
        sortBy: How results should be sorted. Can be NAME, or CREATED_ON
        sortDirection: The direction of the result sort. Can be ASC, or DESC

    Yields:
        An iterator that shows all the children of the container.

    Also see:

    - [synapseutils.walk][]

    Example: Migrating from this method to new approaches
         

        **Legacy approach (deprecated):**
        ```python
        # Using the deprecated getChildren method
        for child in syn.getChildren("syn12345", includeTypes=["file", "folder"]):
            print(f"Child: {child['name']} (ID: {child['id']})")
        ```

        **New approach using dataclass models with sync_from_synapse:**
        ```python
        import synapseclient
        from synapseclient.models import Project, Folder

        # Create client and login
        syn = synapseclient.Synapse()
        syn.login()

        # For projects - get all children automatically (recursive by default)
        project = Project(id="syn12345")
        project = project.sync_from_synapse(download_file=False)

        # Access different types of children
        print(f"Files: {len(project.files)}")
        for file in project.files:
            print(f"  File: {file.name} (ID: {file.id})")

        print(f"Folders: {len(project.folders)}")
        for folder in project.folders:
            print(f"  Folder: {folder.name} (ID: {folder.id})")

        print(f"Tables: {len(project.tables)}")
        for table in project.tables:
            print(f"  Table: {table.name} (ID: {table.id})")

        # For folders - get all children automatically (recursive by default)
        folder = Folder(id="syn67890")
        folder = folder.sync_from_synapse(download_file=False)

        # Access children in the same way
        for file in folder.files:
            print(f"  File: {file.name} (ID: {file.id})")

        # For non-recursive behavior (equivalent to single getChildren call)
        folder = Folder(id="syn67890")
        folder = folder.sync_from_synapse(download_file=False, recursive=False)

        # This will only get immediate children, not subfolders' contents
        for file in folder.files:
            print(f"  File: {file.name} (ID: {file.id})")
        for subfolder in folder.folders:
            print(f"  Subfolder: {subfolder.name} (ID: {subfolder.id})")
            # Note: subfolder.files and subfolder.folders will be empty
            # because recursive=False
        ```

        **New approach using the API directly (for advanced sorting/filtering):**
        ```python
        import asyncio
        import synapseclient
        from synapseclient.api import get_children

        # Create client and login
        syn = synapseclient.Synapse()
        syn.login()

        # Using the new async API function directly
        async def get_sorted_children():
            async for child in get_children(
                parent="syn12345",
                include_types=["file", "folder"],
                sort_by="NAME",
                sort_direction="ASC"
            ):
                print(f"Child: {child['name']} (ID: {child['id']}, Type: {child['type']})")

        # Run the async function
        asyncio.run(get_sorted_children())
        ```
    """
    parentId = id_of(parent) if parent is not None else None

    trace.get_current_span().set_attributes({"synapse.parent_id": parentId})
    entityChildrenRequest = {
        "parentId": parentId,
        "includeTypes": includeTypes,
        "sortBy": sortBy,
        "sortDirection": sortDirection,
        "nextPageToken": None,
    }
    entityChildrenResponse = {"nextPageToken": "first"}
    while entityChildrenResponse.get("nextPageToken") is not None:
        entityChildrenResponse = self.restPOST(
            "/entity/children", body=json.dumps(entityChildrenRequest)
        )
        for child in entityChildrenResponse["page"]:
            yield child
        if entityChildrenResponse.get("nextPageToken") is not None:
            entityChildrenRequest["nextPageToken"] = entityChildrenResponse[
                "nextPageToken"
            ]

getTeam

getTeam(id: Union[int, str]) -> Team

Deprecated with replacement. This method will be removed in 5.0.0. Use synapseclient.models.Team.from_id or synapseclient.models.Team.from_name instead.

Finds a team with a given ID or name.

PARAMETER	DESCRIPTION
id	The ID or name of the team or a Team object to retrieve. TYPE: Union[int, str]

RETURNS	DESCRIPTION
Team	An object of type synapseclient.team.Team

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Team

# Login to Synapse
syn = Synapse()
syn.login()

# Get a team by ID
team_by_id = Team.from_id(id=12345)
print(f"Team by ID: {team_by_id.name}")

# Get a team by name
team_by_name = Team.from_name(name="My Team")
print(f"Team by name: {team_by_name.name}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `get`, `from_id`, and `from_name` methods on the `from synapseclient.models import Team` class. "
    "Check the docstring for the replacement function example.",
)
def getTeam(self, id: Union[int, str]) -> Team:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.models.Team.from_id][] or [synapseclient.models.Team.from_name][] instead.

    Finds a team with a given ID or name.

    Arguments:
        id: The ID or name of the team or a Team object to retrieve.

    Returns:
        An object of type [synapseclient.team.Team][]

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Get a team by ID
        team_by_id = Team.from_id(id=12345)
        print(f"Team by ID: {team_by_id.name}")

        # Get a team by name
        team_by_name = Team.from_name(name="My Team")
        print(f"Team by name: {team_by_name.name}")
        ```
    """
    # Retrieves team id
    teamid = id_of(id)
    try:
        int(teamid)
    except (TypeError, ValueError):
        if isinstance(id, str):
            for team in self._findTeam(id):
                if team.name == id:
                    teamid = team.id
                    break
            else:
                raise ValueError('Can\'t find team "{}"'.format(teamid))
        else:
            raise ValueError('Can\'t find team "{}"'.format(teamid))
    return Team(**self.restGET("/team/%s" % teamid))

getTeamMembers

getTeamMembers(team: Union[Team, int, str]) -> Generator[TeamMember, None, None]

Deprecated with replacement. This method will be removed in 5.0.0. Use synapseclient.models.Team.members instead.

Lists the members of the given team.

PARAMETER	DESCRIPTION
team	A synapseclient.team.Team object or a team's ID. TYPE: Union[Team, int, str]

YIELDS	DESCRIPTION
TeamMember	A generator over synapseclient.team.TeamMember objects.

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Team

# Login to Synapse
syn = Synapse()
syn.login()

# Get team members
team = Team.from_id(id=12345)
members = team.members()
for member in members:
    print(f"Member: {member.member.user_name}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `members` method on the `from synapseclient.models import Team` class. "
    "Check the docstring for the replacement function example.",
)
def getTeamMembers(
    self, team: Union[Team, int, str]
) -> typing.Generator[TeamMember, None, None]:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.models.Team.members][] instead.

    Lists the members of the given team.

    Arguments:
        team: A [synapseclient.team.Team][] object or a team's ID.

    Yields:
        A generator over [synapseclient.team.TeamMember][] objects.

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Get team members
        team = Team.from_id(id=12345)
        members = team.members()
        for member in members:
            print(f"Member: {member.member.user_name}")
        ```

    """
    for result in self._GET_paginated("/teamMembers/{id}".format(id=id_of(team))):
        yield TeamMember(**result)

invite_to_team

invite_to_team(team: Union[Team, int, str], user: str = None, inviteeEmail: str = None, message: str = None, force: bool = False)

Deprecated with replacement. This method will be removed in 5.0.0. Use synapseclient.models.Team.invite instead.

Invite user to a Synapse team via Synapse username or email (choose one or the other)

PARAMETER	DESCRIPTION
syn	Synapse object
team	A synapseclient.team.Team object or a team's ID. TYPE: Union[Team, int, str]
user	Synapse username or profile id of user TYPE: str DEFAULT: None
inviteeEmail	Email of user TYPE: str DEFAULT: None
message	Additional message for the user getting invited to the team. TYPE: str DEFAULT: None
force	If an open invitation exists for the invitee, the old invite will be cancelled. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
	MembershipInvitation or None if user is already a member

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Team

# Login to Synapse
syn = Synapse()
syn.login()

# Invite a user to a team
team = Team.from_id(id=12345)
invitation = team.invite(
    user="username",
    message="Welcome to the team!",
    force=True
)
print(f"Invitation sent: {invitation}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `invite` method on the `from synapseclient.models import Team` class. "
    "Check the docstring for the replacement function example.",
)
def invite_to_team(
    self,
    team: Union[Team, int, str],
    user: str = None,
    inviteeEmail: str = None,
    message: str = None,
    force: bool = False,
):
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.models.Team.invite][] instead.

    Invite user to a Synapse team via Synapse username or email
    (choose one or the other)

    Arguments:
        syn: Synapse object
        team: A [synapseclient.team.Team][] object or a team's ID.
        user: Synapse username or profile id of user
        inviteeEmail: Email of user
        message: Additional message for the user getting invited to the team.
        force: If an open invitation exists for the invitee, the old invite will be cancelled.

    Returns:
        MembershipInvitation or None if user is already a member

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Invite a user to a team
        team = Team.from_id(id=12345)
        invitation = team.invite(
            user="username",
            message="Welcome to the team!",
            force=True
        )
        print(f"Invitation sent: {invitation}")
        ```
    """
    # Throw error if both user and email is specified and if both not
    # specified
    id_email_specified = inviteeEmail is not None and user is not None
    id_email_notspecified = inviteeEmail is None and user is None
    if id_email_specified or id_email_notspecified:
        raise ValueError("Must specify either 'user' or 'inviteeEmail'")

    teamid = id_of(team)
    is_member = False
    open_invitations = self.get_team_open_invitations(teamid)

    if user is not None:
        inviteeId = self.getUserProfile(user)["ownerId"]
        membership_status = self.get_membership_status(inviteeId, teamid)
        is_member = membership_status["isMember"]
        open_invites_to_user = [
            invitation
            for invitation in open_invitations
            if invitation.get("inviteeId") == inviteeId
        ]
    else:
        inviteeId = None
        open_invites_to_user = [
            invitation
            for invitation in open_invitations
            if invitation.get("inviteeEmail") == inviteeEmail
        ]
    # Only invite if the invitee is not a member and
    # if invitee doesn't have an open invitation unless force=True
    if not is_member and (not open_invites_to_user or force):
        # Delete all old invitations
        for invite in open_invites_to_user:
            self._delete_membership_invitation(invite["id"])
        return self.send_membership_invitation(
            teamid,
            inviteeId=inviteeId,
            inviteeEmail=inviteeEmail,
            message=message,
        )
    if is_member:
        not_sent_reason = "invitee is already a member"
    else:
        not_sent_reason = (
            "invitee already has an open invitation "
            "Set force=True to send new invite."
        )

    self.logger.warning("No invitation sent: {}".format(not_sent_reason))
    # Return None if no invite is sent.
    return None

get_membership_status

get_membership_status(userid, team)

Retrieve a user's Team Membership Status bundle. https://rest-docs.synapse.org/rest/GET/team/id/member/principalId/membershipStatus.html

PARAMETER	DESCRIPTION
user	Synapse user ID
team	A synapseclient.team.Team object or a team's ID.

RETURNS	DESCRIPTION
	dict of TeamMembershipStatus

Using this function (DEPRECATED)

  Getting a user's membership status for a team

from synapseclient import Synapse

# Login to Synapse
syn = Synapse()
syn.login()

status = syn.get_membership_status(userid="12345", team="67890")
print(status)

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Team

# Login to Synapse
syn = Synapse()
syn.login()

# Use synchronous version (recommended for most use cases)
team = Team.from_id(id="67890")
status = team.get_user_membership_status(
    user_id="12345",
)
print(status)

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Use the `get_user_membership_status` method on the `Team` class from `synapseclient.models` instead. "
    "Check the docstring for the replacement function example.",
)
def get_membership_status(self, userid, team):
    """Retrieve a user's Team Membership Status bundle.
    <https://rest-docs.synapse.org/rest/GET/team/id/member/principalId/membershipStatus.html>

    Arguments:
        user: Synapse user ID
        team: A [synapseclient.team.Team][] object or a team's ID.

    Returns:
        dict of TeamMembershipStatus

    Example: Using this function (DEPRECATED)
        &nbsp;
        Getting a user's membership status for a team

        ```python
        from synapseclient import Synapse

        # Login to Synapse
        syn = Synapse()
        syn.login()

        status = syn.get_membership_status(userid="12345", team="67890")
        print(status)
        ```


    Example: Migration to new method
        &nbsp;

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Use synchronous version (recommended for most use cases)
        team = Team.from_id(id="67890")
        status = team.get_user_membership_status(
            user_id="12345",
        )
        print(status)
        ```
    """
    teamid = id_of(team)
    request = "/team/{team}/member/{user}/membershipStatus".format(
        team=teamid, user=userid
    )
    membership_status = self.restGET(request)
    return membership_status

get_team_open_invitations

get_team_open_invitations(team: Union[Team, int, str]) -> Generator[dict, None, None]

Deprecated with replacement. This method will be removed in 5.0.0. Use synapseclient.models.Team.open_invitations instead.

Retrieve the open requests submitted to a Team https://rest-docs.synapse.org/rest/GET/team/id/openInvitation.html

PARAMETER	DESCRIPTION
team	A synapseclient.team.Team object or a team's ID. TYPE: Union[Team, int, str]

YIELDS	DESCRIPTION
dict	Generator of MembershipRequest dictionaries

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Team

# Login to Synapse
syn = Synapse()
syn.login()

# Get open invitations for a team
team = Team.from_id(id=12345)
invitations = team.open_invitations()
for invitation in invitations:
    print(f"Invitation: {invitation}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `open_invitations` method on the `from synapseclient.models import Team` class. "
    "Check the docstring for the replacement function example.",
)
def get_team_open_invitations(
    self, team: Union[Team, int, str]
) -> typing.Generator[dict, None, None]:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.models.Team.open_invitations][] instead.

    Retrieve the open requests submitted to a Team
    <https://rest-docs.synapse.org/rest/GET/team/id/openInvitation.html>

    Arguments:
        team: A [synapseclient.team.Team][] object or a team's ID.

    Yields:
        Generator of MembershipRequest dictionaries

    Example: Migration to new method
        &nbsp;

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Get open invitations for a team
        team = Team.from_id(id=12345)
        invitations = team.open_invitations()
        for invitation in invitations:
            print(f"Invitation: {invitation}")
        ```
    """
    teamid = id_of(team)
    request = "/team/{team}/openInvitation".format(team=teamid)
    open_requests = self._GET_paginated(request)
    return open_requests

send_membership_invitation

send_membership_invitation(teamId, inviteeId=None, inviteeEmail=None, message=None)

Deprecated with replacement. This method will be removed in 5.0.0. Use synapseclient.api.team_services.send_membership_invitation instead.

Create a membership invitation and send an email notification to the invitee.

PARAMETER	DESCRIPTION
teamId	Synapse teamId
inviteeId	Synapse username or profile id of user DEFAULT: None
inviteeEmail	Email of user DEFAULT: None
message	Additional message for the user getting invited to the team. DEFAULT: None

RETURNS	DESCRIPTION
	MembershipInvitation

Migration to new method

 

import asyncio
from synapseclient import Synapse
from synapseclient.api.team_services import send_membership_invitation

# Login to Synapse
syn = Synapse()
syn.login()

# Send invitation by user ID
invitation = asyncio.run(send_membership_invitation(
    team_id=12345,
    invitee_id="username_or_user_id",
    message="Welcome to our team!"
))
print(f"Invitation sent: {invitation}")

# Send invitation by email
invitation = asyncio.run(send_membership_invitation(
    team_id=12345,
    invitee_email="user@example.com",
    message="Join our team!"
))
print(f"Invitation sent: {invitation}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to synapseclient.api.team_services.send_membership_invitation. "
    "Check the docstring for the replacement function example.",
)
def send_membership_invitation(
    self, teamId, inviteeId=None, inviteeEmail=None, message=None
):
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.api.team_services.send_membership_invitation][] instead.

    Create a membership invitation and send an email notification
    to the invitee.

    Arguments:
        teamId: Synapse teamId
        inviteeId: Synapse username or profile id of user
        inviteeEmail: Email of user
        message: Additional message for the user getting invited to the
                 team.

    Returns:
        MembershipInvitation

    Example: Migration to new method
         

        ```python
        import asyncio
        from synapseclient import Synapse
        from synapseclient.api.team_services import send_membership_invitation

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Send invitation by user ID
        invitation = asyncio.run(send_membership_invitation(
            team_id=12345,
            invitee_id="username_or_user_id",
            message="Welcome to our team!"
        ))
        print(f"Invitation sent: {invitation}")

        # Send invitation by email
        invitation = asyncio.run(send_membership_invitation(
            team_id=12345,
            invitee_email="user@example.com",
            message="Join our team!"
        ))
        print(f"Invitation sent: {invitation}")
        ```
    """

    invite_request = {"teamId": str(teamId), "message": message}
    if inviteeEmail is not None:
        invite_request["inviteeEmail"] = str(inviteeEmail)
    if inviteeId is not None:
        invite_request["inviteeId"] = str(inviteeId)

    response = self.restPOST(
        "/membershipInvitation", body=json.dumps(invite_request)
    )
    return response

submit

submit(evaluation, entity, name=None, team=None, silent=False, submitterAlias=None, teamName=None, dockerTag='latest')

Submit an Entity for evaluation.

PARAMETER	DESCRIPTION
evalation	Evaluation queue to submit to
entity	The Entity containing the Submissions
name	A name for this submission. In the absent of this parameter, the entity name will be used. (Optional) A synapseclient.team.Team object, ID or name of a Team that is registered for the challenge DEFAULT: None
team	(optional) A synapseclient.team.Team object, ID or name of a Team that is registered for the challenge DEFAULT: None
silent	Set to True to suppress output. DEFAULT: False
submitterAlias	(optional) A nickname, possibly for display in leaderboards in place of the submitter's name DEFAULT: None
teamName	(deprecated) A synonym for submitterAlias DEFAULT: None
dockerTag	(optional) The Docker tag must be specified if the entity is a DockerRepository. DEFAULT: 'latest'

RETURNS	DESCRIPTION
	A synapseclient.evaluation.Submission object

In the case of challenges, a team can optionally be provided to give credit to members of the team that contributed to the submission. The team must be registered for the challenge with which the given evaluation is associated. The caller must be a member of the submitting team.

Using this function

Getting and submitting an evaluation

evaluation = syn.getEvaluation(123)
entity = syn.get('syn456')
submission = syn.submit(evaluation, entity, name='Our Final Answer', team='Blue Team')

Migration to the object-oriented model

 

# Old approach (DEPRECATED)
# submission = syn.submit(9614543, "syn456", name="Our Final Answer")

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.models import Submission

syn = Synapse()
syn.login()

submission = Submission(
    evaluation_id="9614543",
    entity_id="syn456",
    name="Our Final Answer",
).store()

Source code in synapseclient/client.py

@deprecated(
    version="4.14.0",
    reason="To be removed in 5.0.0. "
    "Use the `synapseclient.models.Submission` model instead, e.g. "
    "`Submission(...).store()`.",
)
def submit(
    self,
    evaluation,
    entity,
    name=None,
    team=None,
    silent=False,
    submitterAlias=None,
    teamName=None,
    dockerTag="latest",
):
    """
    Submit an Entity for [evaluation][synapseclient.evaluation.Evaluation].

    Arguments:
        evalation: Evaluation queue to submit to
        entity: The Entity containing the Submissions
        name: A name for this submission. In the absent of this parameter, the entity name will be used.
                (Optional) A [synapseclient.team.Team][] object, ID or name of a Team that is registered for the challenge
        team: (optional) A [synapseclient.team.Team][] object, ID or name of a Team that is registered for the challenge
        silent: Set to True to suppress output.
        submitterAlias: (optional) A nickname, possibly for display in leaderboards in place of the submitter's name
        teamName: (deprecated) A synonym for submitterAlias
        dockerTag: (optional) The Docker tag must be specified if the entity is a DockerRepository.

    Returns:
        A [synapseclient.evaluation.Submission][] object


    In the case of challenges, a team can optionally be provided to give credit to members of the team that
    contributed to the submission. The team must be registered for the challenge with which the given evaluation is
    associated. The caller must be a member of the submitting team.

    Example: Using this function
        Getting and submitting an evaluation

            evaluation = syn.getEvaluation(123)
            entity = syn.get('syn456')
            submission = syn.submit(evaluation, entity, name='Our Final Answer', team='Blue Team')

    Example: Migration to the object-oriented model
         

        ```python
        # Old approach (DEPRECATED)
        # submission = syn.submit(9614543, "syn456", name="Our Final Answer")

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.models import Submission

        syn = Synapse()
        syn.login()

        submission = Submission(
            evaluation_id="9614543",
            entity_id="syn456",
            name="Our Final Answer",
        ).store()
        ```
    """
    return wrap_async_to_sync(
        self.submit_async(
            evaluation,
            entity,
            name=name,
            team=team,
            silent=silent,
            submitterAlias=submitterAlias,
            teamName=teamName,
            dockerTag=dockerTag,
        )
    )

getConfigFile cached

getConfigFile(configPath: str) -> RawConfigParser

Retrieves the client configuration information.

PARAMETER	DESCRIPTION
configPath	Path to configuration file on local file system TYPE: str

RETURNS	DESCRIPTION
RawConfigParser	A RawConfigParser populated with properties from the user's configuration file.

Source code in synapseclient/client.py

@deprecated(
    version="4.4.0",
    reason="To be removed in 5.0.0. "
    "Moved to synapseclient/api/configuration_services.py::get_config_file",
)
@functools.lru_cache()
def getConfigFile(self, configPath: str) -> configparser.RawConfigParser:
    """
    Retrieves the client configuration information.

    Arguments:
        configPath:  Path to configuration file on local file system

    Returns:
        A RawConfigParser populated with properties from the user's configuration file.
    """

    try:
        config = configparser.RawConfigParser()
        config.read(configPath)  # Does not fail if the file does not exist
        return config
    except configparser.Error as ex:
        raise ValueError(
            "Error parsing Synapse config file: {}".format(configPath)
        ) from ex

setEndpoints

setEndpoints(repoEndpoint: str = None, authEndpoint: str = None, fileHandleEndpoint: str = None, portalEndpoint: str = None, skip_checks: bool = False) -> None

Sets the locations for each of the Synapse services (mostly useful for testing).

PARAMETER	DESCRIPTION
repoEndpoint	Location of synapse repository TYPE: str DEFAULT: None
authEndpoint	Location of authentication service TYPE: str DEFAULT: None
fileHandleEndpoint	Location of file service TYPE: str DEFAULT: None
portalEndpoint	Location of the website TYPE: str DEFAULT: None
skip_checks	Skip version and endpoint checks TYPE: bool DEFAULT: False

Switching endpoints

To switch between staging and production endpoints

syn.setEndpoints(**synapseclient.client.STAGING_ENDPOINTS)
syn.setEndpoints(**synapseclient.client.PRODUCTION_ENDPOINTS)

Source code in synapseclient/client.py

def setEndpoints(
    self,
    repoEndpoint: str = None,
    authEndpoint: str = None,
    fileHandleEndpoint: str = None,
    portalEndpoint: str = None,
    skip_checks: bool = False,
) -> None:
    """
    Sets the locations for each of the Synapse services (mostly useful for testing).

    Arguments:
        repoEndpoint:          Location of synapse repository
        authEndpoint:          Location of authentication service
        fileHandleEndpoint:    Location of file service
        portalEndpoint:        Location of the website
        skip_checks:           Skip version and endpoint checks

    Example: Switching endpoints
        To switch between staging and production endpoints

            syn.setEndpoints(**synapseclient.client.STAGING_ENDPOINTS)
            syn.setEndpoints(**synapseclient.client.PRODUCTION_ENDPOINTS)

    """

    endpoints = {
        "repoEndpoint": repoEndpoint,
        "authEndpoint": authEndpoint,
        "fileHandleEndpoint": fileHandleEndpoint,
        "portalEndpoint": portalEndpoint,
    }

    # For unspecified endpoints, first look in the config file
    config = get_config_file(self.configPath)
    for point in endpoints.keys():
        if endpoints[point] is None and config.has_option("endpoints", point):
            endpoints[point] = config.get("endpoints", point)

    # Endpoints default to production
    for point in endpoints.keys():
        if endpoints[point] is None:
            endpoints[point] = PRODUCTION_ENDPOINTS[point]

        # Update endpoints if we get redirected
        if not skip_checks:
            response = with_retry(
                lambda point=point: self._requests_session.get(
                    endpoints[point],
                    allow_redirects=False,
                    headers=synapseclient.USER_AGENT,
                    timeout=self._http_timeout_seconds,
                ),
                verbose=self.debug,
                **{**STANDARD_RETRY_PARAMS, "retries": 2},
            )
            if response.status_code == 301:
                endpoints[point] = response.headers["location"]

    self.repoEndpoint = endpoints["repoEndpoint"]
    self.authEndpoint = endpoints["authEndpoint"]
    self.fileHandleEndpoint = endpoints["fileHandleEndpoint"]
    self.portalEndpoint = endpoints["portalEndpoint"]

invalidateAPIKey

invalidateAPIKey()

Deprecated with no replacement. The client does not support API keys for authentication. Please use a personal access token instead. This method will be removed in a future release.

Invalidates authentication across all clients.

RETURNS	DESCRIPTION
	None

Source code in synapseclient/client.py

@deprecated(
    version="4.0.0",
    reason="deprecated with no replacement. The client does not support API keys for "
    "authentication. Please use a personal access token instead. This method will "
    "be removed in a future release.",
)
def invalidateAPIKey(self):
    """
    **Deprecated with no replacement.** The client does not support API keys for
    authentication. Please use a
    [personal access token](https://python-docs.synapse.org/tutorials/authentication/)
    instead. This method will be removed in a future release.


    Invalidates authentication across all clients.

    Returns:
        None
    """

    # Logout globally
    if self._is_logged_in():
        self.restDELETE("/secretKey", endpoint=self.authEndpoint)

get_user_profile_by_username cached

get_user_profile_by_username(username: str = None, sessionToken: str = None) -> UserProfile

Deprecated with replacement. This method will be removed in 5.0.0. Use the from_username method on the from synapseclient.models import UserProfile class.

Get the details about a Synapse user. Retrieves information on the current user if 'id' is omitted or is empty string.

PARAMETER	DESCRIPTION
username	The userName of a user TYPE: str DEFAULT: None
sessionToken	The session token to use to find the user profile TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
UserProfile	The user profile for the user of interest.

Using this function (DEPRECATED)

Getting your own profile

my_profile = syn.get_user_profile_by_username()

Getting another user's profile

users_profile = syn.get_user_profile_by_username('synapse-service-dpe-team')

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import UserProfile

# Login to Synapse
syn = Synapse()
syn.login()

# Get your own profile
my_profile = UserProfile().get()
print(f"My profile: {my_profile.username}")

# Get another user's profile by username
profile_by_username = UserProfile.from_username(username='synapse-service-dpe-team')
print(f"Profile by username: {profile_by_username.username}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `from_username` method on the `from synapseclient.models import UserProfile` class. "
    "Check the docstring for the replacement function example.",
)
@functools.lru_cache()
def get_user_profile_by_username(
    self,
    username: str = None,
    sessionToken: str = None,
) -> UserProfile:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use the [from_username][synapseclient.models.UserProfile.from_username] method on the `from synapseclient.models import UserProfile` class.

    Get the details about a Synapse user.
    Retrieves information on the current user if 'id' is omitted or is empty string.

    Arguments:
        username:     The userName of a user
        sessionToken: The session token to use to find the user profile

    Returns:
        The user profile for the user of interest.

    Example: Using this function (DEPRECATED)
        Getting your own profile

            my_profile = syn.get_user_profile_by_username()

        Getting another user's profile

            users_profile = syn.get_user_profile_by_username('synapse-service-dpe-team')

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Get your own profile
        my_profile = UserProfile().get()
        print(f"My profile: {my_profile.username}")

        # Get another user's profile by username
        profile_by_username = UserProfile.from_username(username='synapse-service-dpe-team')
        print(f"Profile by username: {profile_by_username.username}")
        ```
    """
    is_none = username is None
    is_str = isinstance(username, str)
    if not is_str and not is_none:
        raise TypeError("username must be string or None")
    if is_str:
        principals = self._findPrincipals(username)
        for principal in principals:
            if principal.get("userName", None).lower() == username.lower():
                id = principal["ownerId"]
                break
        else:
            raise ValueError(f"Can't find user '{username}'")
    else:
        id = ""
    uri = f"/userProfile/{id}"
    return UserProfile(
        **self.restGET(
            uri, headers={"sessionToken": sessionToken} if sessionToken else None
        )
    )

get_user_profile_by_id cached

get_user_profile_by_id(id: int = None, sessionToken: str = None) -> UserProfile

Deprecated with replacement. This method will be removed in 5.0.0. Use synapseclient.models.UserProfile.from_id instead.

Get the details about a Synapse user. Retrieves information on the current user if 'id' is omitted.

PARAMETER	DESCRIPTION
id	The ownerId of a user TYPE: int DEFAULT: None
sessionToken	The session token to use to find the user profile TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
UserProfile	The user profile for the user of interest.

Using this function (DEPRECATED)

Getting your own profile

my_profile = syn.get_user_profile_by_id()

Getting another user's profile

users_profile = syn.get_user_profile_by_id(3485485)

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import UserProfile

# Login to Synapse
syn = Synapse()
syn.login()

# Get your own profile
my_profile = UserProfile().get()
print(f"My profile: {my_profile.username}")

# Get another user's profile by ID
profile_by_id = UserProfile.from_id(user_id=3485485)
print(f"Profile by id: {profile_by_id.username}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `from_id` method on the `from synapseclient.models import UserProfile` class. "
    "Check the docstring for the replacement function example.",
)
@functools.lru_cache()
def get_user_profile_by_id(
    self,
    id: int = None,
    sessionToken: str = None,
) -> UserProfile:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.models.UserProfile.from_id][] instead.

    Get the details about a Synapse user.
    Retrieves information on the current user if 'id' is omitted.

    Arguments:
        id:           The ownerId of a user
        sessionToken: The session token to use to find the user profile

    Returns:
        The user profile for the user of interest.

    Example: Using this function (DEPRECATED)
        Getting your own profile

            my_profile = syn.get_user_profile_by_id()

        Getting another user's profile

            users_profile = syn.get_user_profile_by_id(3485485)

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Get your own profile
        my_profile = UserProfile().get()
        print(f"My profile: {my_profile.username}")

        # Get another user's profile by ID
        profile_by_id = UserProfile.from_id(user_id=3485485)
        print(f"Profile by id: {profile_by_id.username}")
        ```
    """
    if id:
        if not isinstance(id, int):
            raise TypeError("id must be an 'ownerId' integer")
    else:
        id = ""
    uri = f"/userProfile/{id}"
    return UserProfile(
        **self.restGET(
            uri, headers={"sessionToken": sessionToken} if sessionToken else None
        )
    )

getUserProfile cached

getUserProfile(id: Union[str, int, UserProfile, TeamMember] = None, sessionToken: str = None) -> UserProfile

Deprecated with replacement. This method will be removed in 5.0.0. Use [synapseclient.models.protocols.user_protocol.from_id][] instead.

Get the details about a Synapse user. Retrieves information on the current user if 'id' is omitted.

PARAMETER	DESCRIPTION
id	The 'userId' (aka 'ownerId') of a user or the userName TYPE: Union[str, int, UserProfile, TeamMember] DEFAULT: None
sessionToken	The session token to use to find the user profile TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
UserProfile	The user profile for the user of interest.

Using this function (DEPRECATED)

Getting your own profile

my_profile = syn.getUserProfile()

Getting another user's profile

users_profile = syn.getUserProfile('synapse-service-dpe-team')

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import UserProfile

# Login to Synapse
syn = Synapse()
syn.login()

# Get your own profile
my_profile = UserProfile().get()
print(f"My profile: {my_profile.username}")

# Get another user's profile by username
profile_by_username = UserProfile.from_username(username='synapse-service-dpe-team')
print(f"Profile by username: {profile_by_username.username}")

# Get another user's profile by ID
profile_by_id = UserProfile.from_id(user_id=3485485)
print(f"Profile by id: {profile_by_id.username}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `from_id` and `from_username` methods on the `from synapseclient.models import UserProfile` class. "
    "Check the docstring for the replacement function example.",
)
@functools.lru_cache()
def getUserProfile(
    self,
    id: Union[str, int, UserProfile, TeamMember] = None,
    sessionToken: str = None,
) -> UserProfile:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.models.protocols.user_protocol.from_id][] instead.

    Get the details about a Synapse user.
    Retrieves information on the current user if 'id' is omitted.

    Arguments:
        id:           The 'userId' (aka 'ownerId') of a user or the userName
        sessionToken: The session token to use to find the user profile

    Returns:
        The user profile for the user of interest.

    Example: Using this function (DEPRECATED)
        Getting your own profile

            my_profile = syn.getUserProfile()

        Getting another user's profile

            users_profile = syn.getUserProfile('synapse-service-dpe-team')

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Get your own profile
        my_profile = UserProfile().get()
        print(f"My profile: {my_profile.username}")

        # Get another user's profile by username
        profile_by_username = UserProfile.from_username(username='synapse-service-dpe-team')
        print(f"Profile by username: {profile_by_username.username}")

        # Get another user's profile by ID
        profile_by_id = UserProfile.from_id(user_id=3485485)
        print(f"Profile by id: {profile_by_id.username}")
        ```
    """
    try:
        # if id is unset or a userID, this will succeed
        id = "" if id is None else int(id)
    except (TypeError, ValueError):
        if isinstance(id, collections.abc.Mapping) and "ownerId" in id:
            id = id.ownerId
        elif isinstance(id, TeamMember):
            id = id.member.ownerId
        else:
            principals = self._findPrincipals(id)
            if len(principals) == 1:
                id = principals[0]["ownerId"]
            else:
                for principal in principals:
                    if principal.get("userName", None).lower() == id.lower():
                        id = principal["ownerId"]
                        break
                else:  # no break
                    raise ValueError('Can\'t find user "%s": ' % id)
    uri = "/userProfile/%s" % id
    return UserProfile(
        **self.restGET(
            uri, headers={"sessionToken": sessionToken} if sessionToken else None
        )
    )

is_certified

is_certified(user: Union[str, int]) -> bool

Deprecated with replacement. This method will be removed in 5.0.0. Use synapseclient.models.UserProfile.is_certified instead.

Determines whether a Synapse user is a certified user.

PARAMETER	DESCRIPTION
user	Synapse username or Id TYPE: Union[str, int]

RETURNS	DESCRIPTION
bool	True if the Synapse user is certified

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import UserProfile

# Login to Synapse
syn = Synapse()
syn.login()

# Check if user is certified by username
profile_by_username = UserProfile.from_username(username='synapse-service-dpe-team')
user_certified = profile_by_username.is_certified()
print(f"User {profile_by_username.username} is certified: {user_certified}")

# Check if user is certified by ID
profile_by_id = UserProfile.from_id(user_id=3485485)
user_certified = profile_by_id.is_certified()
print(f"User {profile_by_id.username} is certified: {user_certified}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `is_certified` method on the `from synapseclient.models import UserProfile` class. "
    "Check the docstring for the replacement function example.",
)
def is_certified(self, user: typing.Union[str, int]) -> bool:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.models.UserProfile.is_certified][] instead.

    Determines whether a Synapse user is a certified user.

    Arguments:
        user: Synapse username or Id

    Returns:
        True if the Synapse user is certified

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Check if user is certified by username
        profile_by_username = UserProfile.from_username(username='synapse-service-dpe-team')
        user_certified = profile_by_username.is_certified()
        print(f"User {profile_by_username.username} is certified: {user_certified}")

        # Check if user is certified by ID
        profile_by_id = UserProfile.from_id(user_id=3485485)
        user_certified = profile_by_id.is_certified()
        print(f"User {profile_by_id.username} is certified: {user_certified}")
        ```
    """
    # Check if userid or username exists
    syn_user = self.getUserProfile(user)
    # Get passing record

    try:
        certification_status = self._get_certified_passing_record(
            syn_user["ownerId"]
        )
        return certification_status["passed"]
    except SynapseHTTPError as ex:
        if ex.response.status_code == 404:
            # user hasn't taken the quiz
            return False
        raise

is_synapse_id

is_synapse_id(syn_id: str) -> bool

Checks if given synID is valid (attached to actual entity?)

PARAMETER	DESCRIPTION
syn_id	A Synapse ID TYPE: str

RETURNS	DESCRIPTION
bool	True if the Synapse ID is valid

Source code in synapseclient/client.py

@deprecated(
    version="4.11.0",
    reason="To be removed in 5.0.0. "
    "Use `from synapseclient.operations import is_synapse_id` instead.",
)
def is_synapse_id(self, syn_id: str) -> bool:
    """Checks if given synID is valid (attached to actual entity?)

    Arguments:
        syn_id: A Synapse ID

    Returns:
        True if the Synapse ID is valid
    """
    if isinstance(syn_id, str):
        try:
            self.get(syn_id, downloadFile=False)
        except SynapseFileNotFoundError:
            return False
        except (
            SynapseHTTPError,
            SynapseAuthenticationError,
        ) as err:
            status = (
                err.__context__.response.status_code or err.response.status_code
            )
            if status in (400, 404):
                return False
            # Valid ID but user lacks permission or is not logged in
            elif status == 403:
                return True
        return True
    self.logger.warning("synID must be a string")
    return False

onweb

onweb(entity, subpageId=None)

Opens up a browser window to the entity page or wiki-subpage.

PARAMETER	DESCRIPTION
entity	Either an Entity or a Synapse ID
subpageId	(Optional) ID of one of the wiki's sub-pages DEFAULT: None

RETURNS	DESCRIPTION
	None

Source code in synapseclient/client.py

@deprecated(
    version="4.11.0",
    reason="To be removed in 5.0.0. "
    "Use `from synapseclient.operations import onweb` instead.",
)
def onweb(self, entity, subpageId=None):
    """Opens up a browser window to the entity page or wiki-subpage.

    Arguments:
        entity:    Either an Entity or a Synapse ID
        subpageId: (Optional) ID of one of the wiki's sub-pages

    Returns:
        None
    """
    if isinstance(entity, str) and os.path.isfile(entity):
        entity = self.get(entity, downloadFile=False)
    synId = id_of(entity)
    if subpageId is None:
        webbrowser.open("%s/Synapse:%s" % (self.portalEndpoint, synId))
    else:
        webbrowser.open(
            "%s/Wiki:%s/ENTITY/%s" % (self.portalEndpoint, synId, subpageId)
        )

printEntity

printEntity(entity, ensure_ascii=True) -> None

Deprecated with replacement. This method will be removed in 5.0.0. Use synapseclient.operations.print_entity instead.

Pretty prints an Entity.

PARAMETER	DESCRIPTION
entity	The entity to be printed.
ensure_ascii	If True, escapes all non-ASCII characters DEFAULT: True

Migration to new function

 

from synapseclient import Synapse
from synapseclient.operations import print_entity

# Login to Synapse
syn = Synapse()
syn.login()

# Print an entity by Synapse ID
print_entity("syn123456")

# Print an entity object
from synapseclient.operations import get
entity = get(synapse_id="syn123456")
print_entity(entity)

# Print with unicode characters preserved
print_entity("syn123456", ensure_ascii=False)

RETURNS	DESCRIPTION
None	None

Source code in synapseclient/client.py

@deprecated(
    version="4.11.0",
    reason="To be removed in 5.0.0. "
    "Use `from synapseclient.operations import print_entity` instead.",
)
def printEntity(self, entity, ensure_ascii=True) -> None:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.operations.print_entity][] instead.

    Pretty prints an Entity.

    Arguments:
        entity: The entity to be printed.
        ensure_ascii: If True, escapes all non-ASCII characters

    Example: Migration to new function
         

        ```python
        from synapseclient import Synapse
        from synapseclient.operations import print_entity

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Print an entity by Synapse ID
        print_entity("syn123456")

        # Print an entity object
        from synapseclient.operations import get
        entity = get(synapse_id="syn123456")
        print_entity(entity)

        # Print with unicode characters preserved
        print_entity("syn123456", ensure_ascii=False)
        ```

    Returns:
        None
    """

    if utils.is_synapse_id_str(entity):
        synid, version = utils.get_synid_and_version(entity)
        entity = self._getEntity(synid, version)
    try:
        self.logger.info(
            json.dumps(entity, sort_keys=True, indent=2, ensure_ascii=ensure_ascii)
        )
    except TypeError:
        self.logger.info(str(entity))

get_available_services

get_available_services() -> List[str]

Get available Synapse services This is a beta feature and is subject to change

RETURNS	DESCRIPTION
List[str]	List of available services

Source code in synapseclient/client.py

@deprecated(
    version="4.11.0",
    reason="To be removed in 5.0.0. This is a beta feature with no replacement.",
)
def get_available_services(self) -> typing.List[str]:
    """Get available Synapse services
    This is a beta feature and is subject to change

    Returns:
        List of available services
    """
    services = self._services.keys()
    return list(services)

service

service(service_name: str)

Get available Synapse services This is a beta feature and is subject to change

PARAMETER	DESCRIPTION
service_name	name of the service TYPE: str

Source code in synapseclient/client.py

@deprecated(
    version="4.11.0",
    reason="To be removed in 5.0.0. This is a beta feature with no replacement.",
)
def service(self, service_name: str):
    """Get available Synapse services
    This is a beta feature and is subject to change

    Arguments:
        service_name: name of the service
    """
    # This is to avoid circular imports
    # TODO: revisit the import order and method https://stackoverflow.com/a/37126790
    # To move this to the top
    import synapseclient.services

    assert isinstance(service_name, str)
    service_name = service_name.lower().replace(" ", "_")
    assert service_name in self._services, (
        f"Unrecognized service ({service_name}). Run the 'get_available_"
        "services()' method to get a list of available services."
    )
    service_attr = self._services[service_name]
    service_cls = getattr(synapseclient.services, service_attr)
    service = service_cls(self)
    return service

clear_download_list

clear_download_list()

Clear all files from download list

Migration to new method

 

# Old approach (DEPRECATED)
# syn.clear_download_list()

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.operations import download_list_clear

syn = Synapse()
syn.login()

# Clear all files from the download list
download_list_clear()

Source code in synapseclient/client.py

@deprecated(
    version="4.13.0",
    reason=(
        "Use `synapseclient.operations.download_list_clear()` instead. "
        "See synapseclient.operations.download_list_operations for the new interface."
    ),
)
def clear_download_list(self):
    """Clear all files from download list

    Example: Migration to new method
         

        ```python
        # Old approach (DEPRECATED)
        # syn.clear_download_list()

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.operations import download_list_clear

        syn = Synapse()
        syn.login()

        # Clear all files from the download list
        download_list_clear()
        ```
    """
    self.restDELETE("/download/list")

create_external_s3_file_handle

create_external_s3_file_handle(bucket_name, s3_file_key, file_path, *, parent=None, storage_location_id=None, mimetype=None, md5: str = None)

Create an external S3 file handle for e.g. a file that has been uploaded directly to an external S3 storage location.

PARAMETER	DESCRIPTION
bucket_name	Name of the S3 bucket
s3_file_key	S3 key of the uploaded object
file_path	Local path of the uploaded file
parent	Parent entity to create the file handle in, the file handle will be created in the default storage location of the parent. Mutually exclusive with storage_location_id DEFAULT: None
storage_location_id	Explicit storage location id to create the file handle in, mutually exclusive with parent DEFAULT: None
mimetype	Mimetype of the file, if known DEFAULT: None
md5	MD5 of the file, if known TYPE: str DEFAULT: None

RAISES	DESCRIPTION
ValueError	If neither parent nor storage_location_id is specified, or if both are specified.

Source code in synapseclient/client.py

@deprecated(
    version="4.12.0",
    reason="To be removed in 5.0.0. "
    "Use `synapseclient.api.post_external_s3_file_handle()` instead.",
)
def create_external_s3_file_handle(
    self,
    bucket_name,
    s3_file_key,
    file_path,
    *,
    parent=None,
    storage_location_id=None,
    mimetype=None,
    md5: str = None,
):
    """
    Create an external S3 file handle for e.g. a file that has been uploaded directly to
    an external S3 storage location.

    Arguments:
        bucket_name: Name of the S3 bucket
        s3_file_key: S3 key of the uploaded object
        file_path: Local path of the uploaded file
        parent: Parent entity to create the file handle in, the file handle will be created
                in the default storage location of the parent. Mutually exclusive with
                storage_location_id
        storage_location_id: Explicit storage location id to create the file handle in, mutually exclusive
                with parent
        mimetype: Mimetype of the file, if known
        md5: MD5 of the file, if known

    Raises:
        ValueError: If neither parent nor storage_location_id is specified, or if both are specified.
    """

    if storage_location_id:
        if parent:
            raise ValueError("Pass parent or storage_location_id, not both")
    elif not parent:
        raise ValueError("One of parent or storage_location_id is required")
    else:
        upload_destination = self._getDefaultUploadDestination(parent)
        storage_location_id = upload_destination["storageLocationId"]

    if mimetype is None:
        mimetype, _ = mimetypes.guess_type(file_path, strict=False)

    file_handle = {
        "concreteType": concrete_types.S3_FILE_HANDLE,
        "key": s3_file_key,
        "bucketName": bucket_name,
        "fileName": os.path.basename(file_path),
        "contentMd5": md5 or utils.md5_for_file(file_path).hexdigest(),
        "contentSize": os.stat(file_path).st_size,
        "storageLocationId": storage_location_id,
        "contentType": mimetype,
    }

    return self.restPOST(
        "/externalFileHandle/s3",
        json.dumps(file_handle),
        endpoint=self.fileHandleEndpoint,
    )

getMyStorageLocationSetting

getMyStorageLocationSetting(storage_location_id)

Get a StorageLocationSetting by its id.

PARAMETER	DESCRIPTION
storage_location_id	id of the StorageLocationSetting to retrieve. The corresponding StorageLocationSetting must have been created by this user.

RETURNS	DESCRIPTION
	A dict describing the StorageLocationSetting retrieved by its id

Source code in synapseclient/client.py

@deprecated(
    version="4.12.0",
    reason="To be removed in 5.0.0. "
    "Use `StorageLocation(storage_location_id=id).get()` from "
    "synapseclient.models instead.",
)
def getMyStorageLocationSetting(self, storage_location_id):
    """
    Get a StorageLocationSetting by its id.

    Arguments:
        storage_location_id: id of the StorageLocationSetting to retrieve.
                                The corresponding StorageLocationSetting must have been created by this user.

    Returns:
        A dict describing the StorageLocationSetting retrieved by its id
    """
    return self.restGET("/storageLocation/%s" % storage_location_id)

createStorageLocationSetting

createStorageLocationSetting(storage_type, **kwargs)

Creates an IMMUTABLE storage location based on the specified type.

For each storage_type, the following kwargs should be specified:

ExternalObjectStorage: (S3-like (e.g. AWS S3 or Openstack) bucket not accessed by Synapse)

• endpointUrl: endpoint URL of the S3 service (for example: 'https://s3.amazonaws.com')
• bucket: the name of the bucket to use

ExternalS3Storage: (Amazon S3 bucket accessed by Synapse)

• bucket: the name of the bucket to use

ExternalStorage: (SFTP or FTP storage location not accessed by Synapse)

• url: the base URL for uploading to the external destination
• supportsSubfolders(optional): does the destination support creating subfolders under the base url (default: false)

ProxyStorage: (a proxy server that controls access to a storage)

• secretKey: The encryption key used to sign all pre-signed URLs used to communicate with the proxy.
• proxyUrl: The HTTPS URL of the proxy used for upload and download.

PARAMETER	DESCRIPTION
storage_type	The type of the StorageLocationSetting to create
banner	(Optional) The optional banner to show every time a file is uploaded
description	(Optional) The description to show the user when the user has to choose which upload destination to use
kwargs	fields necessary for creation of the specified storage_type DEFAULT: {}

RETURNS	DESCRIPTION
	A dict of the created StorageLocationSetting

Source code in synapseclient/client.py

@deprecated(
    version="4.12.0",
    reason="To be removed in 5.0.0. "
    "Use `StorageLocation(...).store()` from synapseclient.models instead.",
)
def createStorageLocationSetting(self, storage_type, **kwargs):
    """
    Creates an IMMUTABLE storage location based on the specified type.

    For each storage_type, the following kwargs should be specified:

    **ExternalObjectStorage**: (S3-like (e.g. AWS S3 or Openstack) bucket not accessed by Synapse)

    - `endpointUrl`: endpoint URL of the S3 service (for example: 'https://s3.amazonaws.com')
    - `bucket`: the name of the bucket to use

    **ExternalS3Storage**: (Amazon S3 bucket accessed by Synapse)

    - `bucket`: the name of the bucket to use

    **ExternalStorage**: (SFTP or FTP storage location not accessed by Synapse)

    - `url`: the base URL for uploading to the external destination
    - `supportsSubfolders(optional)`: does the destination support creating subfolders under the base url
        (default: false)

    **ProxyStorage**: (a proxy server that controls access to a storage)

    - `secretKey`: The encryption key used to sign all pre-signed URLs used to communicate with the proxy.
    - `proxyUrl`: The HTTPS URL of the proxy used for upload and download.

    Arguments:
        storage_type: The type of the StorageLocationSetting to create
        banner: (Optional) The optional banner to show every time a file is uploaded
        description: (Optional) The description to show the user when the user has to choose which upload destination to use
        kwargs: fields necessary for creation of the specified storage_type

    Returns:
        A dict of the created StorageLocationSetting
    """
    upload_type_dict = {
        "ExternalObjectStorage": "S3",
        "ExternalS3Storage": "S3",
        "ExternalStorage": "SFTP",
        "ProxyStorage": "PROXYLOCAL",
    }

    if storage_type not in upload_type_dict:
        raise ValueError("Unknown storage_type: %s", storage_type)

    # ProxyStorageLocationSettings has an extra 's' at the end >:(
    kwargs["concreteType"] = (
        "org.sagebionetworks.repo.model.project."
        + storage_type
        + "LocationSetting"
        + ("s" if storage_type == "ProxyStorage" else "")
    )
    kwargs["uploadType"] = upload_type_dict[storage_type]

    return self.restPOST("/storageLocation", body=json.dumps(kwargs))

create_s3_storage_location

create_s3_storage_location(*, parent=None, folder_name=None, folder=None, bucket_name=None, base_key=None, sts_enabled=False) -> Tuple[Folder, Dict[str, str], Dict[str, str]]

Create a storage location in the given parent, either in the given folder or by creating a new folder in that parent with the given name. This will both create a StorageLocationSetting, and a ProjectSetting together, optionally creating a new folder in which to locate it, and optionally enabling this storage location for access via STS. If enabling an existing folder for STS, it must be empty.

Deprecated: To be removed in 5.0.0. Use the synapseclient.models.StorageLocation model and its store() method to create the storage location, and set_storage_location() on a Project or Folder to apply it as a project setting.

PARAMETER	DESCRIPTION
parent	The parent in which to locate the storage location (mutually exclusive with folder) DEFAULT: None
folder_name	The name of a new folder to create (mutually exclusive with folder) DEFAULT: None
folder	The existing folder in which to create the storage location (mutually exclusive with folder_name) DEFAULT: None
bucket_name	The name of an S3 bucket, if this is an external storage location, if None will use Synapse S3 storage DEFAULT: None
base_key	The base key of within the bucket, None to use the bucket root, only applicable if bucket_name is passed DEFAULT: None
sts_enabled	Whether this storage location should be STS enabled DEFAULT: False

RETURNS	DESCRIPTION
Tuple[Folder, Dict[str, str], Dict[str, str]]	A 3-tuple of the synapse Folder, a the storage location setting, and the project setting dictionaries.

Migration to the object-oriented model

 

# Old approach (DEPRECATED)
# folder, storage_setting, project_setting = syn.create_s3_storage_location(
#     parent="syn123",
#     folder_name="my-external-storage",
#     bucket_name="my-bucket",
# )

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.models import Folder, StorageLocation, StorageLocationType

syn = Synapse()
syn.login()

# Create the storage location backed by your own S3 bucket
storage = StorageLocation(
    storage_type=StorageLocationType.EXTERNAL_S3,
    bucket="my-bucket",
).store()

# Create a folder to hold the externally stored files
folder = Folder(name="my-external-storage", parent_id="syn123").store()

# Apply the storage location as the folder's upload destination
folder.set_storage_location(storage_location_id=storage.storage_location_id)

Source code in synapseclient/client.py

@deprecated(
    version="4.12.0",
    reason="To be removed in 5.0.0. "
    "Use the `synapseclient.models.StorageLocation` model and its `store()` "
    "method instead. To also create a folder and apply the storage location "
    "as a project setting, use `Folder` together with "
    "`set_storage_location()` on the project/folder.",
)
def create_s3_storage_location(
    self,
    *,
    parent=None,
    folder_name=None,
    folder=None,
    bucket_name=None,
    base_key=None,
    sts_enabled=False,
) -> Tuple[Folder, Dict[str, str], Dict[str, str]]:
    """
    Create a storage location in the given parent, either in the given folder or by creating a new
    folder in that parent with the given name. This will both create a StorageLocationSetting,
    and a ProjectSetting together, optionally creating a new folder in which to locate it,
    and optionally enabling this storage location for access via STS. If enabling an existing folder for STS,
    it must be empty.

    Deprecated: To be removed in 5.0.0. Use the synapseclient.models.StorageLocation
    model and its store() method to create the storage location, and
    set_storage_location() on a Project or Folder to apply it as a project setting.

    Arguments:
        parent: The parent in which to locate the storage location (mutually exclusive with folder)
        folder_name: The name of a new folder to create (mutually exclusive with folder)
        folder: The existing folder in which to create the storage location (mutually exclusive with folder_name)
        bucket_name: The name of an S3 bucket, if this is an external storage location,
                        if None will use Synapse S3 storage
        base_key: The base key of within the bucket, None to use the bucket root,
                        only applicable if bucket_name is passed
        sts_enabled: Whether this storage location should be STS enabled

    Returns:
        A 3-tuple of the synapse Folder, a the storage location setting, and the project setting dictionaries.

    Example: Migration to the object-oriented model
         

        ```python
        # Old approach (DEPRECATED)
        # folder, storage_setting, project_setting = syn.create_s3_storage_location(
        #     parent="syn123",
        #     folder_name="my-external-storage",
        #     bucket_name="my-bucket",
        # )

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.models import Folder, StorageLocation, StorageLocationType

        syn = Synapse()
        syn.login()

        # Create the storage location backed by your own S3 bucket
        storage = StorageLocation(
            storage_type=StorageLocationType.EXTERNAL_S3,
            bucket="my-bucket",
        ).store()

        # Create a folder to hold the externally stored files
        folder = Folder(name="my-external-storage", parent_id="syn123").store()

        # Apply the storage location as the folder's upload destination
        folder.set_storage_location(storage_location_id=storage.storage_location_id)
        ```
    """
    return wrap_async_to_sync(
        self.create_s3_storage_location_async(
            parent=parent,
            folder_name=folder_name,
            folder=folder,
            bucket_name=bucket_name,
            base_key=base_key,
            sts_enabled=sts_enabled,
        )
    )

setStorageLocation

setStorageLocation(entity, storage_location_id)

Sets the storage location for a Project or Folder

PARAMETER	DESCRIPTION
entity	A Project or Folder to which the StorageLocationSetting is set
storage_location_id	A StorageLocation id or a list of StorageLocation ids. Pass in None for the default Synapse storage.

RETURNS	DESCRIPTION
	The created or updated settings as a dict.

Source code in synapseclient/client.py

@deprecated(
    version="4.12.0",
    reason="To be removed in 5.0.0. "
    "Use `Folder(id=...).set_storage_location(...)` or "
    "`Project(id=...).set_storage_location(...)` from synapseclient.models instead.",
)
def setStorageLocation(self, entity, storage_location_id):
    """
    Sets the storage location for a Project or Folder

    Arguments:
        entity: A Project or Folder to which the StorageLocationSetting is set
        storage_location_id: A StorageLocation id or a list of StorageLocation ids. Pass in None for the default
                                Synapse storage.

    Returns:
        The created or updated settings as a dict.
    """
    if storage_location_id is None:
        storage_location_id = DEFAULT_STORAGE_LOCATION_ID
    locations = (
        storage_location_id
        if isinstance(storage_location_id, list)
        else [storage_location_id]
    )

    existing_setting = self.getProjectSetting(entity, "upload")
    if existing_setting is not None:
        existing_setting["locations"] = locations
        self.restPUT("/projectSettings", body=json.dumps(existing_setting))
        return self.getProjectSetting(entity, "upload")
    else:
        project_destination = {
            "concreteType": "org.sagebionetworks.repo.model.project.UploadDestinationListSetting",
            "settingsType": "upload",
            "locations": locations,
            "projectId": id_of(entity),
        }

        return self.restPOST(
            "/projectSettings", body=json.dumps(project_destination)
        )

get_sts_storage_token

get_sts_storage_token(entity, permission, *, output_format='json', min_remaining_life=None)

Get STS credentials for the given entity_id and permission, outputting it in the given format

PARAMETER	DESCRIPTION
entity	The entity or entity id whose credentials are being returned
permission	One of: read_only read_write
output_format	One of: json: the dictionary returned from the Synapse STS API including expiration boto: a dictionary compatible with a boto session (aws_access_key_id, etc) shell: output commands for exporting credentials appropriate for the detected shell bash: output commands for exporting credentials into a bash shell cmd: output commands for exporting credentials into a windows cmd shell powershell: output commands for exporting credentials into a windows powershell DEFAULT: 'json'
min_remaining_life	The minimum allowable remaining life on a cached token to return. If a cached token has left than this amount of time left a fresh token will be fetched DEFAULT: None

Source code in synapseclient/client.py

@deprecated(
    version="4.12.0",
    reason="To be removed in 5.0.0. "
    "Use `Folder(id=...).get_sts_storage_token(...)` or "
    "`Project(id=...).get_sts_storage_token(...)` from synapseclient.models instead.",
)
def get_sts_storage_token(
    self, entity, permission, *, output_format="json", min_remaining_life=None
):
    """Get STS credentials for the given entity_id and permission, outputting it in the given format

    Arguments:
        entity: The entity or entity id whose credentials are being returned
        permission: One of:

            - `read_only`
            - `read_write`

        output_format: One of:

            - `json`: the dictionary returned from the Synapse STS API including expiration
            - `boto`: a dictionary compatible with a boto session (aws_access_key_id, etc)
            - `shell`: output commands for exporting credentials appropriate for the detected shell
            - `bash`: output commands for exporting credentials into a bash shell
            - `cmd`: output commands for exporting credentials into a windows cmd shell
            - `powershell`: output commands for exporting credentials into a windows powershell

        min_remaining_life: The minimum allowable remaining life on a cached token to return. If a cached token
                            has left than this amount of time left a fresh token will be fetched
    """
    return sts_transfer.get_sts_credentials(
        self,
        id_of(entity),
        permission,
        output_format=output_format,
        min_remaining_life=min_remaining_life,
    )

create_snapshot_version

create_snapshot_version(table: Union[EntityViewSchema, Schema, str, SubmissionViewSchema, Dataset], comment: str = None, label: str = None, activity: Union[Activity, str] = None, wait: bool = True) -> int

Deprecated with replacement. This method will be removed in 5.0.0. Use the .snapshot() method on the Table, EntityView, SubmissionView, or Dataset classes instead.

Create a new Table Version, new View version, or new Dataset version.

PARAMETER	DESCRIPTION
table	The schema of the Table/View, or its ID. TYPE: Union[EntityViewSchema, Schema, str, SubmissionViewSchema, Dataset]
comment	Optional snapshot comment. TYPE: str DEFAULT: None
label	Optional snapshot label. TYPE: str DEFAULT: None
activity	Optional activity ID applied to snapshot version. TYPE: Union[Activity, str] DEFAULT: None
wait	True if this method should return the snapshot version after waiting for any necessary asynchronous table updates to complete. If False this method will return as soon as any updates are initiated. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
int	The snapshot version number if wait=True, None if wait=False

Using this function (DEPRECATED)

Creating a snapshot of a table

table_id = "syn1234"
snapshot_version = syn.create_snapshot_version(
    table_id,
    comment="This is a snapshot",
    label="v1.0",
    activity=my_activity
)

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Table, EntityView, SubmissionView, Dataset

# Login to Synapse
syn = Synapse()
syn.login()

# For Tables
table = Table(id="syn1234")
snapshot_response = table.snapshot(
    comment="This is a snapshot",
    label="v1.0",
    include_activity=True,
    associate_activity_to_new_version=True
)
print(f"Snapshot version: {snapshot_response['snapshotVersionNumber']}")

# For Entity Views
view = EntityView(id="syn5678")
snapshot_transaction = view.snapshot(
    comment="This is a snapshot",
    label="v1.0",
    include_activity=True,
    associate_activity_to_new_version=True
)
print(f"Snapshot version: {snapshot_transaction.snapshot_version_number}")

# For Submission Views
submission_view = SubmissionView(id="syn9012")
snapshot_transaction = submission_view.snapshot(
    comment="This is a snapshot",
    label="v1.0",
    include_activity=True,
    associate_activity_to_new_version=True
)
print(f"Snapshot version: {snapshot_transaction.snapshot_version_number}")

# For Datasets
dataset = Dataset(id="syn3456")
snapshot_transaction = dataset.snapshot(
    comment="This is a snapshot",
    label="v1.0",
    include_activity=True,
    associate_activity_to_new_version=True
)
print(f"Snapshot version: {snapshot_transaction.snapshot_version_number}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Use the `.snapshot()` method on the `Table`, `EntityView`, `SubmissionView`, or `Dataset` classes instead. "
    "Check the docstring for the replacement function example.",
)
def create_snapshot_version(
    self,
    table: typing.Union[
        EntityViewSchema, Schema, str, SubmissionViewSchema, Dataset
    ],
    comment: str = None,
    label: str = None,
    activity: typing.Union[Activity, str] = None,
    wait: bool = True,
) -> int:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use the `.snapshot()` method on the `Table`, `EntityView`, `SubmissionView`, or `Dataset` classes instead.

    Create a new Table Version, new View version, or new Dataset version.

    Arguments:
        table: The schema of the Table/View, or its ID.
        comment: Optional snapshot comment.
        label: Optional snapshot label.
        activity: Optional activity ID applied to snapshot version.
        wait: True if this method should return the snapshot version after waiting for any necessary
                asynchronous table updates to complete. If False this method will return
                as soon as any updates are initiated.

    Returns:
        The snapshot version number if wait=True, None if wait=False

    Example: Using this function (DEPRECATED)
        Creating a snapshot of a table

            table_id = "syn1234"
            snapshot_version = syn.create_snapshot_version(
                table_id,
                comment="This is a snapshot",
                label="v1.0",
                activity=my_activity
            )

    Example: Migration to new method
         

        ```python
        from synapseclient import Synapse
        from synapseclient.models import Table, EntityView, SubmissionView, Dataset

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # For Tables
        table = Table(id="syn1234")
        snapshot_response = table.snapshot(
            comment="This is a snapshot",
            label="v1.0",
            include_activity=True,
            associate_activity_to_new_version=True
        )
        print(f"Snapshot version: {snapshot_response['snapshotVersionNumber']}")

        # For Entity Views
        view = EntityView(id="syn5678")
        snapshot_transaction = view.snapshot(
            comment="This is a snapshot",
            label="v1.0",
            include_activity=True,
            associate_activity_to_new_version=True
        )
        print(f"Snapshot version: {snapshot_transaction.snapshot_version_number}")

        # For Submission Views
        submission_view = SubmissionView(id="syn9012")
        snapshot_transaction = submission_view.snapshot(
            comment="This is a snapshot",
            label="v1.0",
            include_activity=True,
            associate_activity_to_new_version=True
        )
        print(f"Snapshot version: {snapshot_transaction.snapshot_version_number}")

        # For Datasets
        dataset = Dataset(id="syn3456")
        snapshot_transaction = dataset.snapshot(
            comment="This is a snapshot",
            label="v1.0",
            include_activity=True,
            associate_activity_to_new_version=True
        )
        print(f"Snapshot version: {snapshot_transaction.snapshot_version_number}")
        ```
    """
    ent = self.get(id_of(table), downloadFile=False)
    if isinstance(ent, (EntityViewSchema, SubmissionViewSchema, Dataset)):
        result = self._async_table_update(
            table,
            create_snapshot=True,
            comment=comment,
            label=label,
            activity=activity,
            wait=wait,
        )
    elif isinstance(ent, Schema):
        result = self._create_table_snapshot(
            table,
            comment=comment,
            label=label,
            activity=activity,
        )
    else:
        raise ValueError(
            "This function only accepts Synapse ids of Tables or Views"
        )

    # for consistency we return nothing if wait=False since we can't
    # supply the snapshot version on an async table update without waiting
    return result["snapshotVersionNumber"] if wait else None

getConfigFile cached

getConfigFile(configPath: str) -> RawConfigParser

Retrieves the client configuration information.

PARAMETER	DESCRIPTION
configPath	Path to configuration file on local file system TYPE: str

RETURNS	DESCRIPTION
RawConfigParser	A RawConfigParser populated with properties from the user's configuration file.

Source code in synapseclient/client.py

@deprecated(
    version="4.4.0",
    reason="To be removed in 5.0.0. "
    "Moved to synapseclient/api/configuration_services.py::get_config_file",
)
@functools.lru_cache()
def getConfigFile(self, configPath: str) -> configparser.RawConfigParser:
    """
    Retrieves the client configuration information.

    Arguments:
        configPath:  Path to configuration file on local file system

    Returns:
        A RawConfigParser populated with properties from the user's configuration file.
    """

    try:
        config = configparser.RawConfigParser()
        config.read(configPath)  # Does not fail if the file does not exist
        return config
    except configparser.Error as ex:
        raise ValueError(
            "Error parsing Synapse config file: {}".format(configPath)
        ) from ex

getEvaluation

getEvaluation(id)

Gets an Evaluation object from Synapse.

PARAMETER	DESCRIPTION
id	The ID of the synapseclient.evaluation.Evaluation to return.

RETURNS	DESCRIPTION
	An synapseclient.evaluation.Evaluation object

Using this function

Creating an Evaluation instance

evaluation = syn.getEvaluation(2005090)

Migration to the object-oriented model

 

# Old approach (DEPRECATED)
# evaluation = syn.getEvaluation(2005090)

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.models import Evaluation

syn = Synapse()
syn.login()

evaluation = Evaluation(id="2005090").get()

Source code in synapseclient/client.py

@deprecated(
    version="4.14.0",
    reason="To be removed in 5.0.0. "
    "Use the `synapseclient.models.Evaluation` model instead, e.g. "
    "`Evaluation(id=...).get()`.",
)
def getEvaluation(self, id):
    """
    Gets an Evaluation object from Synapse.

    Arguments:
        id: The ID of the [synapseclient.evaluation.Evaluation][] to return.

    Returns:
        An [synapseclient.evaluation.Evaluation][] object

    Example: Using this function
        Creating an Evaluation instance

            evaluation = syn.getEvaluation(2005090)

    Example: Migration to the object-oriented model
         

        ```python
        # Old approach (DEPRECATED)
        # evaluation = syn.getEvaluation(2005090)

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.models import Evaluation

        syn = Synapse()
        syn.login()

        evaluation = Evaluation(id="2005090").get()
        ```
    """

    evaluation_id = id_of(id)
    uri = Evaluation.getURI(evaluation_id)
    return Evaluation(**self.restGET(uri))

getEvaluationByContentSource

getEvaluationByContentSource(entity)

Returns a generator over evaluations that derive their content from the given entity

PARAMETER	DESCRIPTION
entity	The synapseclient.entity.Project whose Evaluations are to be fetched.

YIELDS	DESCRIPTION
	A generator over synapseclient.evaluation.Evaluation objects for the given synapseclient.entity.Project.

Migration to the object-oriented model

 

# Old approach (DEPRECATED)
# evaluations = syn.getEvaluationByContentSource("syn123")

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.models import Evaluation

syn = Synapse()
syn.login()

evaluations = Evaluation.get_evaluations_by_project(project_id="syn123")

Source code in synapseclient/client.py

@deprecated(
    version="4.14.0",
    reason="To be removed in 5.0.0. "
    "Use `synapseclient.models.Evaluation.get_evaluations_by_project()` instead.",
)
def getEvaluationByContentSource(self, entity):
    """
    Returns a generator over evaluations that derive their content from the given entity

    Arguments:
        entity: The [synapseclient.entity.Project][] whose Evaluations are to be fetched.

    Yields:
        A generator over [synapseclient.evaluation.Evaluation][] objects for the given [synapseclient.entity.Project][].

    Example: Migration to the object-oriented model
         

        ```python
        # Old approach (DEPRECATED)
        # evaluations = syn.getEvaluationByContentSource("syn123")

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.models import Evaluation

        syn = Synapse()
        syn.login()

        evaluations = Evaluation.get_evaluations_by_project(project_id="syn123")
        ```
    """

    entityId = id_of(entity)
    url = "/entity/%s/evaluation" % entityId

    for result in self._GET_paginated(url):
        yield Evaluation(**result)

getEvaluationByName

getEvaluationByName(name)

Gets an Evaluation object from Synapse.

PARAMETER	DESCRIPTION
Name	The name of the synapseclient.evaluation.Evaluation to return.

RETURNS	DESCRIPTION
	An synapseclient.evaluation.Evaluation object

Migration to the object-oriented model

 

# Old approach (DEPRECATED)
# evaluation = syn.getEvaluationByName("My Evaluation")

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.models import Evaluation

syn = Synapse()
syn.login()

evaluation = Evaluation(name="My Evaluation").get()

Source code in synapseclient/client.py

@deprecated(
    version="4.14.0",
    reason="To be removed in 5.0.0. "
    "Use the `synapseclient.models.Evaluation` model instead, e.g. "
    "`Evaluation(name=...).get()`.",
)
def getEvaluationByName(self, name):
    """
    Gets an Evaluation object from Synapse.

    Arguments:
        Name: The name of the [synapseclient.evaluation.Evaluation][] to return.

    Returns:
        An [synapseclient.evaluation.Evaluation][] object

    Example: Migration to the object-oriented model
         

        ```python
        # Old approach (DEPRECATED)
        # evaluation = syn.getEvaluationByName("My Evaluation")

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.models import Evaluation

        syn = Synapse()
        syn.login()

        evaluation = Evaluation(name="My Evaluation").get()
        ```
    """
    uri = Evaluation.getByNameURI(name)
    return Evaluation(**self.restGET(uri))

create_team

create_team(name: str, description: str = None, icon: str = None, can_public_join: bool = False, can_request_membership: bool = True) -> Team

Deprecated with replacement. This method will be removed in 5.0.0. Use synapseclient.models.Team.create instead.

Creates a new team.

PARAMETER	DESCRIPTION
name	The name of the team to create. TYPE: str
description	A description of the team. TYPE: str DEFAULT: None
icon	The FileHandleID of the icon to be used for the team. TYPE: str DEFAULT: None
canPublicJoin	Whether the team can be joined by anyone. Defaults to False.
canRequestMembership	Whether the team can request membership. Defaults to True.

RETURNS	DESCRIPTION
Team	An object of type synapseclient.team.Team

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Team

# Login to Synapse
syn = Synapse()
syn.login()

# Create a new team
new_team = Team(
    name="My Team",
    description="A sample team",
    can_public_join=False,
    can_request_membership=True
)
created_team = new_team.create()
print(f"Created team: {created_team.name}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `create` method on the `from synapseclient.models import Team` class. "
    "Check the docstring for the replacement function example.",
)
def create_team(
    self,
    name: str,
    description: str = None,
    icon: str = None,
    can_public_join: bool = False,
    can_request_membership: bool = True,
) -> Team:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.models.Team.create][] instead.

    Creates a new team.

    Arguments:
        name: The name of the team to create.
        description: A description of the team.
        icon: The FileHandleID of the icon to be used for the team.
        canPublicJoin: Whether the team can be joined by anyone. Defaults to False.
        canRequestMembership: Whether the team can request membership. Defaults to True.

    Returns:
        An object of type [synapseclient.team.Team][]

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Create a new team
        new_team = Team(
            name="My Team",
            description="A sample team",
            can_public_join=False,
            can_request_membership=True
        )
        created_team = new_team.create()
        print(f"Created team: {created_team.name}")
        ```
    """
    request_body = {
        "name": name,
        "description": description,
        "icon": icon,
        "canPublicJoin": can_public_join,
        "canRequestMembership": can_request_membership,
    }
    return Team(
        **self.restPOST(
            "/team",
            json.dumps(request_body),
        )
    )

delete_team

delete_team(id: int) -> None

Deprecated with replacement. This method will be removed in 5.0.0. Use synapseclient.models.Team.delete instead.

Deletes a team.

PARAMETER	DESCRIPTION
id	The ID of the team to delete. TYPE: int

Migration to new method

 

from synapseclient import Synapse
from synapseclient.models import Team

# Login to Synapse
syn = Synapse()
syn.login()

# Delete a team
team = Team(id=12345)
team.delete()

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to the `delete` method on the `from synapseclient.models import Team` class. "
    "Check the docstring for the replacement function example.",
)
def delete_team(self, id: int) -> None:
    """
    **Deprecated with replacement.** This method will be removed in 5.0.0.
    Use [synapseclient.models.Team.delete][] instead.

    Deletes a team.

    Arguments:
        id: The ID of the team to delete.

    Example: Migration to new method
         

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

        # Login to Synapse
        syn = Synapse()
        syn.login()

        # Delete a team
        team = Team(id=12345)
        team.delete()
        ```

    """
    return self.restDELETE(f"/team/{id}")

getProjectSetting

getProjectSetting(project, setting_type)

Gets the ProjectSetting for a project.

PARAMETER	DESCRIPTION
project	Project entity or its id as a string
setting_type	Type of setting. Choose from: upload external_sync requester_pays

RETURNS	DESCRIPTION
	The ProjectSetting as a dict or None if no settings of the specified type exist.

Source code in synapseclient/client.py

@deprecated(
    version="4.12.0",
    reason="To be removed in 5.0.0. "
    "Use `Folder(id=...).get_project_setting(...)` or "
    "`Project(id=...).get_project_setting(...)` from synapseclient.models instead.",
)
def getProjectSetting(self, project, setting_type):
    """
    Gets the ProjectSetting for a project.

    Arguments:
        project: Project entity or its id as a string
        setting_type: Type of setting. Choose from:

            - `upload`
            - `external_sync`
            - `requester_pays`

    Returns:
        The ProjectSetting as a dict or None if no settings of the specified type exist.
    """
    if setting_type not in {"upload", "external_sync", "requester_pays"}:
        raise ValueError("Invalid project_type: %s" % setting_type)

    response = self.restGET(
        "/projectSettings/{projectId}/type/{type}".format(
            projectId=id_of(project), type=setting_type
        )
    )
    return (
        response if response else None
    )  # if no project setting, a empty string is returned as the response

getSubmission

getSubmission(id: Union[str, int, Mapping], **kwargs) -> Submission

Gets a synapseclient.evaluation.Submission object based on a given ID or previous synapseclient.evaluation.Submission object.

PARAMETER	DESCRIPTION
id	The ID of the submission to retrieve or a synapseclient.evaluation.Submission object TYPE: Union[str, int, Mapping]

RETURNS	DESCRIPTION
Submission	A synapseclient.evaluation.Submission object

See:

• synapseclient.Synapse.get for information on the downloadFile, downloadLocation, and ifcollision parameters

Migration to the object-oriented model

 

# Old approach (DEPRECATED)
# submission = syn.getSubmission(9700123)

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.models import Submission

syn = Synapse()
syn.login()

submission = Submission(id="9700123").get()

Source code in synapseclient/client.py

@deprecated(
    version="4.14.0",
    reason="To be removed in 5.0.0. "
    "Use the `synapseclient.models.Submission` model instead, e.g. "
    "`Submission(id=...).get()`.",
)
def getSubmission(
    self, id: typing.Union[str, int, collections.abc.Mapping], **kwargs
) -> Submission:
    """
    Gets a [synapseclient.evaluation.Submission][] object based on a given ID
    or previous [synapseclient.evaluation.Submission][] object.

    Arguments:
        id: The ID of the submission to retrieve or a [synapseclient.evaluation.Submission][] object

    Returns:
        A [synapseclient.evaluation.Submission][] object

    See:

    - [synapseclient.Synapse.get][] for information
         on the *downloadFile*, *downloadLocation*, and *ifcollision* parameters

    Example: Migration to the object-oriented model
         

        ```python
        # Old approach (DEPRECATED)
        # submission = syn.getSubmission(9700123)

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.models import Submission

        syn = Synapse()
        syn.login()

        submission = Submission(id="9700123").get()
        ```
    """
    return wrap_async_to_sync(self.getSubmission_async(id=id, **kwargs))

getSubmissions

getSubmissions(evaluation, status=None, myOwn=False, limit=20, offset=0)

PARAMETER	DESCRIPTION
evaluation	Evaluation to get submissions from.
status	Optionally filter submissions for a specific status. One of: OPEN CLOSED SCORED INVALID VALIDATED EVALUATION_IN_PROGRESS RECEIVED REJECTED ACCEPTED DEFAULT: None
myOwn	Determines if only your Submissions should be fetched. Defaults to False (all Submissions) DEFAULT: False
limit	Limits the number of submissions in a single response. Because this method returns a generator and repeatedly fetches submissions, this argument is limiting the size of a single request and NOT the number of sub- missions returned in total. DEFAULT: 20
offset	Start iterating at a submission offset from the first submission. DEFAULT: 0

YIELDS	DESCRIPTION
	A generator over synapseclient.evaluation.Submission objects for an Evaluation

Using this function

Print submissions

for submission in syn.getSubmissions(1234567):
    print(submission['entityId'])

See:

• synapseclient.evaluation

Migration to the object-oriented model

 

# Old approach (DEPRECATED)
# for submission in syn.getSubmissions(1234567):
#     print(submission)

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.models import Submission

syn = Synapse()
syn.login()

# All submissions for an evaluation
for submission in Submission.get_evaluation_submissions(evaluation_id="1234567"):
    print(submission)

# Only your own submissions (equivalent to myOwn=True)
for submission in Submission.get_user_submissions(evaluation_id="1234567"):
    print(submission)

Source code in synapseclient/client.py

@deprecated(
    version="4.14.0",
    reason="To be removed in 5.0.0. "
    "Use `synapseclient.models.Submission.get_evaluation_submissions()` (or "
    "`get_user_submissions()` for your own submissions) instead.",
)
def getSubmissions(self, evaluation, status=None, myOwn=False, limit=20, offset=0):
    """
    Arguments:
        evaluation: Evaluation to get submissions from.
        status: Optionally filter submissions for a specific status.
                One of:

            - `OPEN`
            - `CLOSED`
            - `SCORED`
            - `INVALID`
            - `VALIDATED`
            - `EVALUATION_IN_PROGRESS`
            - `RECEIVED`
            - `REJECTED`
            - `ACCEPTED`

        myOwn: Determines if only your Submissions should be fetched.
                 Defaults to False (all Submissions)
        limit: Limits the number of submissions in a single response.
                    Because this method returns a generator and repeatedly
                    fetches submissions, this argument is limiting the
                    size of a single request and NOT the number of sub-
                    missions returned in total.
        offset: Start iterating at a submission offset from the first submission.

    Yields:
        A generator over [synapseclient.evaluation.Submission][] objects for an Evaluation

    Example: Using this function
        Print submissions

            for submission in syn.getSubmissions(1234567):
                print(submission['entityId'])

    See:

    - [synapseclient.evaluation][]

    Example: Migration to the object-oriented model
         

        ```python
        # Old approach (DEPRECATED)
        # for submission in syn.getSubmissions(1234567):
        #     print(submission)

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.models import Submission

        syn = Synapse()
        syn.login()

        # All submissions for an evaluation
        for submission in Submission.get_evaluation_submissions(evaluation_id="1234567"):
            print(submission)

        # Only your own submissions (equivalent to myOwn=True)
        for submission in Submission.get_user_submissions(evaluation_id="1234567"):
            print(submission)
        ```
    """

    evaluation_id = id_of(evaluation)
    uri = "/evaluation/%s/submission%s" % (evaluation_id, "" if myOwn else "/all")

    if status is not None:
        uri += "?status=%s" % status

    for result in self._GET_paginated(uri, limit=limit, offset=offset):
        yield Submission(**result)

getSubmissionBundles

getSubmissionBundles(evaluation, status=None, myOwn=False, limit=20, offset=0)

Retrieve submission bundles (submission and submissions status) for an evaluation queue, optionally filtered by submission status and/or owner.

PARAMETER	DESCRIPTION
evaluation	Evaluation to get submissions from.
status	Optionally filter submissions for a specific status. One of: OPEN CLOSED SCORED INVALID DEFAULT: None
myOwn	Determines if only your Submissions should be fetched. Defaults to False (all Submissions) DEFAULT: False
limit	Limits the number of submissions coming back from the service in a single response. DEFAULT: 20
offset	Start iterating at a submission offset from the first submission. DEFAULT: 0

YIELDS	DESCRIPTION
	A generator over tuples containing a synapseclient.evaluation.Submission and a synapseclient.evaluation.SubmissionStatus.

Using this function

Loop over submissions

for submission, status in syn.getSubmissionBundles(evaluation):
    print(submission.name,
          submission.submitterAlias,
          status.status,
          status.score)

This may later be changed to return objects, pending some thought on how submissions along with related status and annotations should be represented in the clients.

See: - synapseclient.evaluation

Migration to the object-oriented model

 

# Old approach (DEPRECATED)
# for submission, status in syn.getSubmissionBundles(1234567):
#     print(submission, status)

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.models import SubmissionBundle

syn = Synapse()
syn.login()

# All submission bundles for an evaluation
for bundle in SubmissionBundle.get_evaluation_submission_bundles(evaluation_id="1234567"):
    print(bundle.submission, bundle.submission_status)

# Only your own submission bundles (equivalent to myOwn=True)
for bundle in SubmissionBundle.get_user_submission_bundles(evaluation_id="1234567"):
    print(bundle.submission, bundle.submission_status)

Source code in synapseclient/client.py

@deprecated(
    version="4.14.0",
    reason="To be removed in 5.0.0. "
    "Use `synapseclient.models.SubmissionBundle.get_evaluation_submission_bundles()` "
    "(or `get_user_submission_bundles()` for your own) instead.",
)
def getSubmissionBundles(
    self, evaluation, status=None, myOwn=False, limit=20, offset=0
):
    """
    Retrieve submission bundles (submission and submissions status) for an evaluation queue, optionally filtered by
    submission status and/or owner.

    Arguments:
        evaluation: Evaluation to get submissions from.
        status:     Optionally filter submissions for a specific status.
                    One of:

            - `OPEN`
            - `CLOSED`
            - `SCORED`
            - `INVALID`

        myOwn:      Determines if only your Submissions should be fetched.
                    Defaults to False (all Submissions)
        limit:      Limits the number of submissions coming back from the
                    service in a single response.
        offset:     Start iterating at a submission offset from the first submission.

    Yields:
        A generator over tuples containing a [synapseclient.evaluation.Submission][] and a [synapseclient.evaluation.SubmissionStatus][].

    Example: Using this function
        Loop over submissions

            for submission, status in syn.getSubmissionBundles(evaluation):
                print(submission.name,
                      submission.submitterAlias,
                      status.status,
                      status.score)

    This may later be changed to return objects, pending some thought on how submissions along with related status
    and annotations should be represented in the clients.

    See:
    - [synapseclient.evaluation][]

    Example: Migration to the object-oriented model
         

        ```python
        # Old approach (DEPRECATED)
        # for submission, status in syn.getSubmissionBundles(1234567):
        #     print(submission, status)

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.models import SubmissionBundle

        syn = Synapse()
        syn.login()

        # All submission bundles for an evaluation
        for bundle in SubmissionBundle.get_evaluation_submission_bundles(evaluation_id="1234567"):
            print(bundle.submission, bundle.submission_status)

        # Only your own submission bundles (equivalent to myOwn=True)
        for bundle in SubmissionBundle.get_user_submission_bundles(evaluation_id="1234567"):
            print(bundle.submission, bundle.submission_status)
        ```
    """
    for bundle in self._getSubmissionBundles(
        evaluation, status=status, myOwn=myOwn, limit=limit, offset=offset
    ):
        yield (
            Submission(**bundle["submission"]),
            SubmissionStatus(**bundle["submissionStatus"]),
        )

getSubmissionStatus

getSubmissionStatus(submission: Union[str, int, Mapping]) -> SubmissionStatus

Downloads the status of a Submission given its ID or previous synapseclient.evaluation.Submission object.

PARAMETER	DESCRIPTION
submission	The submission to lookup (ID or synapseclient.evaluation.Submission object) TYPE: Union[str, int, Mapping]

RETURNS	DESCRIPTION
SubmissionStatus	A synapseclient.evaluation.SubmissionStatus object

Migration to the object-oriented model

 

# Old approach (DEPRECATED)
# status = syn.getSubmissionStatus(9700123)

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.models import SubmissionStatus

syn = Synapse()
syn.login()

status = SubmissionStatus(id="9700123").get()

Source code in synapseclient/client.py

@deprecated(
    version="4.14.0",
    reason="To be removed in 5.0.0. "
    "Use the `synapseclient.models.SubmissionStatus` model instead, e.g. "
    "`SubmissionStatus(id=...).get()`.",
)
def getSubmissionStatus(
    self, submission: typing.Union[str, int, collections.abc.Mapping]
) -> SubmissionStatus:
    """
    Downloads the status of a Submission given its ID or previous [synapseclient.evaluation.Submission][] object.

    Arguments:
        submission: The submission to lookup (ID or [synapseclient.evaluation.Submission][] object)

    Returns:
        A [synapseclient.evaluation.SubmissionStatus][] object

    Example: Migration to the object-oriented model
         

        ```python
        # Old approach (DEPRECATED)
        # status = syn.getSubmissionStatus(9700123)

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.models import SubmissionStatus

        syn = Synapse()
        syn.login()

        status = SubmissionStatus(id="9700123").get()
        ```
    """

    submission_id = validate_submission_id(submission)
    uri = SubmissionStatus.getURI(submission_id)
    val = self.restGET(uri)
    return SubmissionStatus(**val)

getWiki

getWiki(owner, subpageId=None, version=None)

Get a synapseclient.wiki.Wiki object from Synapse. Uses wiki2 API which supports versioning.

PARAMETER	DESCRIPTION
owner	The entity to which the Wiki is attached
subpageId	The id of the specific sub-page or None to get the root Wiki page DEFAULT: None
version	The version of the page to retrieve or None to retrieve the latest DEFAULT: None

RETURNS	DESCRIPTION
	A synapseclient.wiki.Wiki object

Migration to the object-oriented model

 

# Old approach (DEPRECATED)
# wiki = syn.getWiki("syn123", subpageId="456")

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.models import WikiPage

syn = Synapse()
syn.login()

wiki = WikiPage(owner_id="syn123", id="456").get()

Source code in synapseclient/client.py

@deprecated(
    version="4.14.0",
    reason="To be removed in 5.0.0. "
    "Use the `synapseclient.models.WikiPage` model instead, e.g. "
    "`WikiPage(owner_id=..., id=...).get()`.",
)
def getWiki(self, owner, subpageId=None, version=None):
    """
    Get a [synapseclient.wiki.Wiki][] object from Synapse. Uses wiki2 API which supports versioning.

    Arguments:
        owner: The entity to which the Wiki is attached
        subpageId: The id of the specific sub-page or None to get the root Wiki page
        version: The version of the page to retrieve or None to retrieve the latest

    Returns:
        A [synapseclient.wiki.Wiki][] object

    Example: Migration to the object-oriented model
         

        ```python
        # Old approach (DEPRECATED)
        # wiki = syn.getWiki("syn123", subpageId="456")

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.models import WikiPage

        syn = Synapse()
        syn.login()

        wiki = WikiPage(owner_id="syn123", id="456").get()
        ```
    """
    return wrap_async_to_sync(
        self.getWiki_async(owner, subpageId=subpageId, version=version)
    )

getWikiAttachments

getWikiAttachments(wiki)

Retrieve the attachments to a wiki page.

PARAMETER	DESCRIPTION
wiki	The Wiki object for which the attachments are to be returned.

RETURNS	DESCRIPTION
	A list of file handles for the files attached to the Wiki.

Migration to the object-oriented model

 

# Old approach (DEPRECATED)
# attachments = syn.getWikiAttachments(wiki)

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.models import WikiPage

syn = Synapse()
syn.login()

attachments = WikiPage(owner_id="syn123", id="456").get_attachment_handles()

Source code in synapseclient/client.py

@deprecated(
    version="4.14.0",
    reason="To be removed in 5.0.0. "
    "Use `synapseclient.models.WikiPage.get_attachment_handles()` on the WikiPage "
    "instead.",
)
def getWikiAttachments(self, wiki):
    """
    Retrieve the attachments to a wiki page.

    Arguments:
        wiki: The Wiki object for which the attachments are to be returned.

    Returns:
        A list of file handles for the files attached to the Wiki.

    Example: Migration to the object-oriented model
         

        ```python
        # Old approach (DEPRECATED)
        # attachments = syn.getWikiAttachments(wiki)

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.models import WikiPage

        syn = Synapse()
        syn.login()

        attachments = WikiPage(owner_id="syn123", id="456").get_attachment_handles()
        ```
    """
    uri = "/entity/%s/wiki/%s/attachmenthandles" % (wiki.ownerId, wiki.id)
    results = self.restGET(uri)
    file_handles = list(WikiAttachment(**fh) for fh in results["list"])
    return file_handles

getWikiHeaders

getWikiHeaders(owner)

Retrieves the headers of all Wikis belonging to the owner (the entity to which the Wiki is attached).

PARAMETER	DESCRIPTION
owner	An Entity

RETURNS	DESCRIPTION
	A list of Objects with three fields: id, title and parentId.

Migration to the object-oriented model

 

# Old approach (DEPRECATED)
# headers = syn.getWikiHeaders("syn123")

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.models import WikiHeader

syn = Synapse()
syn.login()

for header in WikiHeader.get(owner_id="syn123"):
    print(header)

Source code in synapseclient/client.py

@deprecated(
    version="4.14.0",
    reason="To be removed in 5.0.0. "
    "Use `synapseclient.models.WikiHeader.get(owner_id=...)` instead.",
)
def getWikiHeaders(self, owner):
    """
    Retrieves the headers of all Wikis belonging to the owner (the entity to which the Wiki is attached).

    Arguments:
        owner: An Entity

    Returns:
        A list of Objects with three fields: id, title and parentId.

    Example: Migration to the object-oriented model
         

        ```python
        # Old approach (DEPRECATED)
        # headers = syn.getWikiHeaders("syn123")

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.models import WikiHeader

        syn = Synapse()
        syn.login()

        for header in WikiHeader.get(owner_id="syn123"):
            print(header)
        ```
    """

    uri = "/entity/%s/wikiheadertree" % id_of(owner)
    return [DictObject(**header) for header in self._GET_paginated(uri)]

get_download_list

get_download_list(downloadLocation: str = None) -> str

Download all files from your Synapse download list

Migration to new method

 

# Old approach (DEPRECATED)
# manifest_path = syn.get_download_list(downloadLocation="./downloads")

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.operations import download_list_files

syn = Synapse()
syn.login()

# Download all files in the cart and get the result manifest path
manifest_path = download_list_files(download_location="./downloads")

PARAMETER	DESCRIPTION
downloadLocation	Directory to download files to. TYPE: str DEFAULT: None

RETURNS	DESCRIPTION
str	Manifest file with file paths

Source code in synapseclient/client.py

@deprecated(
    version="4.13.0",
    reason=(
        "Use `synapseclient.operations.download_list_files(download_location=...)` instead. "
        "See synapseclient.operations.download_list_operations for the new interface."
    ),
)
def get_download_list(self, downloadLocation: str = None) -> str:
    """Download all files from your Synapse download list

    Example: Migration to new method
         

        ```python
        # Old approach (DEPRECATED)
        # manifest_path = syn.get_download_list(downloadLocation="./downloads")

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.operations import download_list_files

        syn = Synapse()
        syn.login()

        # Download all files in the cart and get the result manifest path
        manifest_path = download_list_files(download_location="./downloads")
        ```

    Arguments:
        downloadLocation: Directory to download files to.

    Returns:
        Manifest file with file paths
    """
    dl_list_path = self.get_download_list_manifest()
    downloaded_files = []
    new_manifest_path = f"manifest_{time.time_ns()}.csv"
    with (
        open(dl_list_path) as manifest_f,
        open(new_manifest_path, "w") as write_obj,
    ):
        reader = csv.DictReader(manifest_f)
        columns = reader.fieldnames
        columns.extend(["path", "error"])
        # Write the downloaded paths to a new manifest file
        writer = csv.DictWriter(write_obj, fieldnames=columns)
        writer.writeheader()

        for row in reader:
            # You can add things to the download list that you don't have access to
            # So there must be a try catch here
            try:
                entity = self.get(row["ID"], downloadLocation=downloadLocation)
                # Must include version number because you can have multiple versions of a
                # file in the download list
                downloaded_files.append(
                    {
                        "fileEntityId": row["ID"],
                        "versionNumber": row["versionNumber"],
                    }
                )
                row["path"] = entity.path
                row["error"] = ""
            except Exception:
                row["path"] = ""
                row["error"] = "DOWNLOAD FAILED"
                self.logger.exception("Unable to download file")
            writer.writerow(row)

    # Don't want to clear all the download list because you can add things
    # to the download list after initiating this command.
    # Files that failed to download should not be removed from download list
    # Remove all files from download list after the entire download is complete.
    # This is because if download fails midway, we want to return the full manifest
    if downloaded_files:
        # Only want to invoke this if there is a list of files to remove
        # or the API call will error
        self.remove_from_download_list(list_of_files=downloaded_files)
    else:
        self.logger.warning("A manifest was created, but no files were downloaded")

    # Always remove original manifest file
    os.remove(dl_list_path)

    return new_manifest_path

get_download_list_manifest

get_download_list_manifest()

Get the path of the download list manifest file

Migration to new method

 

# Old approach (DEPRECATED)
# manifest_path = syn.get_download_list_manifest()

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.operations import download_list_manifest

syn = Synapse()
syn.login()

# Generate and download the manifest CSV
manifest_path = download_list_manifest()

RETURNS	DESCRIPTION
	Path of download list manifest file

Source code in synapseclient/client.py

@deprecated(
    version="4.13.0",
    reason=(
        "Use `synapseclient.operations.download_list_manifest()` instead. "
        "See synapseclient.operations.download_list_operations for the new interface."
    ),
)
def get_download_list_manifest(self):
    """Get the path of the download list manifest file

    Example: Migration to new method
         

        ```python
        # Old approach (DEPRECATED)
        # manifest_path = syn.get_download_list_manifest()

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.operations import download_list_manifest

        syn = Synapse()
        syn.login()

        # Generate and download the manifest CSV
        manifest_path = download_list_manifest()
        ```

    Returns:
        Path of download list manifest file
    """
    manifest = self._generate_manifest_from_download_list()
    # Get file handle download link
    file_result = get_file_handle_for_download(
        file_handle_id=manifest["resultFileHandleId"],
        synapse_id=manifest["resultFileHandleId"],
        entity_type="FileEntity",
        synapse_client=self,
    )
    # Download the manifest
    downloaded_path = self._download_from_URL(
        url=file_result["preSignedURL"],
        destination="./",
        fileHandleId=file_result["fileHandleId"],
        expected_md5=file_result["fileHandle"].get("contentMd5"),
    )
    trace.get_current_span().set_attributes(
        {"synapse.file_handle_id": file_result["fileHandleId"]}
    )
    return downloaded_path

remove_from_download_list

remove_from_download_list(list_of_files: List[Dict]) -> int

Remove a batch of files from download list

Migration to new method

 

# Old approach (DEPRECATED)
# syn.remove_from_download_list([
#     {"fileEntityId": "syn123", "versionNumber": 1},
# ])

# New approach (RECOMMENDED)
from synapseclient import Synapse
from synapseclient.operations import download_list_remove, DownloadListItem

syn = Synapse()
syn.login()

# Remove specific file versions from the download list
download_list_remove([
    DownloadListItem(file_entity_id="syn123", version_number=1),
])

PARAMETER	DESCRIPTION
list_of_files	Array of files in the format of a mapping {fileEntityId: synid, versionNumber: version} TYPE: List[Dict]

RETURNS	DESCRIPTION
int	Number of files removed from download list

Source code in synapseclient/client.py

@deprecated(
    version="4.13.0",
    reason=(
        "Use `synapseclient.operations.download_list_remove(files)` instead. "
        "See synapseclient.operations.download_list_operations for the new interface."
    ),
)
def remove_from_download_list(self, list_of_files: typing.List[typing.Dict]) -> int:
    """Remove a batch of files from download list

    Example: Migration to new method
         

        ```python
        # Old approach (DEPRECATED)
        # syn.remove_from_download_list([
        #     {"fileEntityId": "syn123", "versionNumber": 1},
        # ])

        # New approach (RECOMMENDED)
        from synapseclient import Synapse
        from synapseclient.operations import download_list_remove, DownloadListItem

        syn = Synapse()
        syn.login()

        # Remove specific file versions from the download list
        download_list_remove([
            DownloadListItem(file_entity_id="syn123", version_number=1),
        ])
        ```

    Arguments:
        list_of_files: Array of files in the format of a mapping {fileEntityId: synid, versionNumber: version}

    Returns:
        Number of files removed from download list
    """
    request_body = {"batchToRemove": list_of_files}
    num_files_removed = self.restPOST(
        "/download/list/remove", body=json.dumps(request_body)
    )
    return num_files_removed

md5Query

md5Query(md5)

Find the Entities which have attached file(s) which have the given MD5 hash.

PARAMETER	DESCRIPTION
md5	The MD5 to query for (hexadecimal string)

RETURNS	DESCRIPTION
	A list of Entity headers

Source code in synapseclient/client.py

@deprecated(
    version="4.11.0",
    reason="To be removed in 5.0.0. "
    "Use `from synapseclient.operations import md5_query` instead.",
)
def md5Query(self, md5):
    """
    Find the Entities which have attached file(s) which have the given MD5 hash.

    Arguments:
        md5: The MD5 to query for (hexadecimal string)

    Returns:
        A list of Entity headers
    """

    return self.restGET("/entity/md5/%s" % md5)["results"]

sendMessage

sendMessage(userIds, messageSubject, messageBody, contentType='text/plain')

send a message via Synapse.

PARAMETER	DESCRIPTION
userIds	A list of user IDs to which the message is to be sent
messageSubject	The subject for the message
messageBody	The body of the message
contentType	optional contentType of message body (default="text/plain") Should be one of "text/plain" or "text/html" DEFAULT: 'text/plain'

RETURNS	DESCRIPTION
	The metadata of the created message

Source code in synapseclient/client.py

def sendMessage(
    self, userIds, messageSubject, messageBody, contentType="text/plain"
):
    """
    send a message via Synapse.

    Arguments:
        userIds: A list of user IDs to which the message is to be sent
        messageSubject: The subject for the message
        messageBody: The body of the message
        contentType: optional contentType of message body (default="text/plain")
                        Should be one of "text/plain" or "text/html"

    Returns:
        The metadata of the created message
    """
    return wrap_async_to_sync(
        self.sendMessage_async(
            userIds=userIds,
            messageSubject=messageSubject,
            messageBody=messageBody,
            contentType=contentType,
        )
    )

uploadFileHandle

uploadFileHandle(path, parent, synapseStore=True, mimetype=None, md5=None, file_size=None)

Uploads the file in the provided path (if necessary) to a storage location based on project settings. Returns a new FileHandle as a dict to represent the stored file.

PARAMETER	DESCRIPTION
parent	Parent of the entity to which we upload.
path	File path to the file being uploaded
synapseStore	If False, will not upload the file, but instead create an ExternalFileHandle that references the file on the local machine. If True, will upload the file based on StorageLocation determined by the entity_parent_id DEFAULT: True
mimetype	The MIME type metadata for the uploaded file DEFAULT: None
md5	The MD5 checksum for the file, if known. Otherwise if the file is a local file, it will be calculated automatically. DEFAULT: None
file_size	The size the file, if known. Otherwise if the file is a local file, it will be calculated automatically. DEFAULT: None
file_type	The MIME type the file, if known. Otherwise if the file is a local file, it will be calculated automatically.

RETURNS	DESCRIPTION
	A dict of a new FileHandle as a dict that represents the uploaded file

Migrating from this method to upload_file_handle_async

Legacy approach (deprecated):

# Using the deprecated uploadFileHandle method
file_handle = syn.uploadFileHandle(
    path="/path/to/file.txt",
    parent="syn12345",
    synapseStore=True,
    mimetype="text/plain"
)

New approach using upload_file_handle:

import asyncio
import synapseclient
from synapseclient.core.upload.upload_functions_async import upload_file_handle

# Create client and login
syn = synapseclient.Synapse()
syn.login()

# Using the new async function directly
async def upload_file():
    file_handle = await upload_file_handle(
        syn=syn,
        parent_entity_id="syn12345",
        path="/path/to/file.txt",
        synapse_store=True,
        md5=None,
        file_size=None,
        mimetype="text/plain"
    )
    return file_handle

# Run the async function
file_handle = asyncio.run(upload_file())
print(f"File handle uploaded: {file_handle}")

Source code in synapseclient/client.py

@deprecated(
    version="4.9.0",
    reason="To be removed in 5.0.0. "
    "Moved to synapseclient/core/upload/upload_functions.py::upload_file_handle_async. "
    "Use `upload_file_handle_async` directly instead.",
)
def uploadFileHandle(
    self, path, parent, synapseStore=True, mimetype=None, md5=None, file_size=None
):
    """Uploads the file in the provided path (if necessary) to a storage location based on project settings.
    Returns a new FileHandle as a dict to represent the stored file.

    Arguments:
        parent: Parent of the entity to which we upload.
        path:   File path to the file being uploaded
        synapseStore: If False, will not upload the file, but instead create an ExternalFileHandle that references
                        the file on the local machine.
                        If True, will upload the file based on StorageLocation determined by the entity_parent_id
        mimetype: The MIME type metadata for the uploaded file
        md5: The MD5 checksum for the file, if known. Otherwise if the file is a local file, it will be calculated
                automatically.
        file_size: The size the file, if known. Otherwise if the file is a local file, it will be calculated
                    automatically.
        file_type: The MIME type the file, if known. Otherwise if the file is a local file, it will be calculated
                    automatically.

    Returns:
        A dict of a new FileHandle as a dict that represents the uploaded file

    Example: Migrating from this method to upload_file_handle_async
        **Legacy approach (deprecated):**
        ```python
        # Using the deprecated uploadFileHandle method
        file_handle = syn.uploadFileHandle(
            path="/path/to/file.txt",
            parent="syn12345",
            synapseStore=True,
            mimetype="text/plain"
        )
        ```

        **New approach using upload_file_handle:**
        ```python
        import asyncio
        import synapseclient
        from synapseclient.core.upload.upload_functions_async import upload_file_handle

        # Create client and login
        syn = synapseclient.Synapse()
        syn.login()

        # Using the new async function directly
        async def upload_file():
            file_handle = await upload_file_handle(
                syn=syn,
                parent_entity_id="syn12345",
                path="/path/to/file.txt",
                synapse_store=True,
                md5=None,
                file_size=None,
                mimetype="text/plain"
            )
            return file_handle

        # Run the async function
        file_handle = asyncio.run(upload_file())
        print(f"File handle uploaded: {file_handle}")
        ```
    """
    return wrap_async_to_sync(
        upload_file_handle_async(
            self, parent, path, synapseStore, md5, file_size, mimetype
        )
    )

restGET

restGET(uri, endpoint=None, headers=None, retryPolicy={}, requests_session=None, **kwargs)

Sends an HTTP GET request to the Synapse server.

PARAMETER	DESCRIPTION
uri	URI on which get is performed
endpoint	Server endpoint, defaults to self.repoEndpoint DEFAULT: None
headers	Dictionary of headers to use rather than the API-key-signed default set of headers DEFAULT: None
requests_session	An external requests.Session object to use when making this specific call DEFAULT: None
kwargs	Any other arguments taken by a request method DEFAULT: {}

RETURNS	DESCRIPTION
	JSON encoding of response

Source code in synapseclient/client.py

def restGET(
    self,
    uri,
    endpoint=None,
    headers=None,
    retryPolicy={},
    requests_session=None,
    **kwargs,
):
    """
    Sends an HTTP GET request to the Synapse server.

    Arguments:
        uri: URI on which get is performed
        endpoint: Server endpoint, defaults to self.repoEndpoint
        headers: Dictionary of headers to use rather than the API-key-signed default set of headers
        requests_session: An external [requests.Session object](https://requests.readthedocs.io/en/latest/user/advanced/) to use when making this specific call
        kwargs: Any other arguments taken by a [request](http://docs.python-requests.org/en/latest/) method

    Returns:
        JSON encoding of response
    """
    response = self._rest_call(
        "get", uri, None, endpoint, headers, retryPolicy, requests_session, **kwargs
    )
    return self._return_rest_body(response)

restPOST

restPOST(uri, body, endpoint=None, headers=None, retryPolicy={}, requests_session=None, **kwargs)

Sends an HTTP POST request to the Synapse server.

PARAMETER	DESCRIPTION
uri	URI on which get is performed
endpoint	Server endpoint, defaults to self.repoEndpoint DEFAULT: None
body	The payload to be delivered
headers	Dictionary of headers to use rather than the API-key-signed default set of headers DEFAULT: None
requests_session	An external requests.Session object to use when making this specific call DEFAULT: None
kwargs	Any other arguments taken by a request method DEFAULT: {}

RETURNS	DESCRIPTION
	JSON encoding of response

Source code in synapseclient/client.py

def restPOST(
    self,
    uri,
    body,
    endpoint=None,
    headers=None,
    retryPolicy={},
    requests_session=None,
    **kwargs,
):
    """
    Sends an HTTP POST request to the Synapse server.

    Arguments:
        uri: URI on which get is performed
        endpoint: Server endpoint, defaults to self.repoEndpoint
        body: The payload to be delivered
        headers: Dictionary of headers to use rather than the API-key-signed default set of headers
        requests_session: An external [requests.Session object](https://requests.readthedocs.io/en/latest/user/advanced/) to use when making this specific call
        kwargs: Any other arguments taken by a [request](http://docs.python-requests.org/en/latest/) method

    Returns:
        JSON encoding of response
    """
    response = self._rest_call(
        "post",
        uri,
        body,
        endpoint,
        headers,
        retryPolicy,
        requests_session,
        **kwargs,
    )
    return self._return_rest_body(response)

restPUT

restPUT(uri, body=None, endpoint=None, headers=None, retryPolicy={}, requests_session=None, **kwargs)

Sends an HTTP PUT request to the Synapse server.

PARAMETER	DESCRIPTION
uri	URI on which get is performed
endpoint	Server endpoint, defaults to self.repoEndpoint DEFAULT: None
body	The payload to be delivered DEFAULT: None
headers	Dictionary of headers to use rather than the API-key-signed default set of headers DEFAULT: None
requests_session	An external requests.Session object to use when making this specific call DEFAULT: None
kwargs	Any other arguments taken by a request method DEFAULT: {}

Returns JSON encoding of response

Source code in synapseclient/client.py

def restPUT(
    self,
    uri,
    body=None,
    endpoint=None,
    headers=None,
    retryPolicy={},
    requests_session=None,
    **kwargs,
):
    """
    Sends an HTTP PUT request to the Synapse server.

    Arguments:
        uri: URI on which get is performed
        endpoint: Server endpoint, defaults to self.repoEndpoint
        body: The payload to be delivered
        headers: Dictionary of headers to use rather than the API-key-signed default set of headers
        requests_session: An external [requests.Session object](https://requests.readthedocs.io/en/latest/user/advanced/) to use when making this specific call
        kwargs: Any other arguments taken by a [request](http://docs.python-requests.org/en/latest/) method

    Returns
        JSON encoding of response
    """
    response = self._rest_call(
        "put",
        uri,
        body,
        endpoint,
        headers,
        retryPolicy,
        requests_session,
        **kwargs,
    )
    return self._return_rest_body(response)

restDELETE

restDELETE(uri, endpoint=None, headers=None, retryPolicy={}, requests_session=None, **kwargs)

Sends an HTTP DELETE request to the Synapse server.

PARAMETER	DESCRIPTION
uri	URI of resource to be deleted
endpoint	Server endpoint, defaults to self.repoEndpoint DEFAULT: None
headers	Dictionary of headers to use rather than the API-key-signed default set of headers DEFAULT: None
requests_session	An external requests.Session object to use when making this specific call DEFAULT: None
kwargs	Any other arguments taken by a request method DEFAULT: {}

Source code in synapseclient/client.py

def restDELETE(
    self,
    uri,
    endpoint=None,
    headers=None,
    retryPolicy={},
    requests_session=None,
    **kwargs,
):
    """
    Sends an HTTP DELETE request to the Synapse server.

    Arguments:
        uri: URI of resource to be deleted
        endpoint: Server endpoint, defaults to self.repoEndpoint
        headers: Dictionary of headers to use rather than the API-key-signed default set of headers
        requests_session: An external [requests.Session object](https://requests.readthedocs.io/en/latest/user/advanced/) to use when making this specific call
        kwargs: Any other arguments taken by a [request](http://docs.python-requests.org/en/latest/) method

    """
    self._rest_call(
        "delete",
        uri,
        None,
        endpoint,
        headers,
        retryPolicy,
        requests_session,
        **kwargs,
    )

rest_get_async async

rest_get_async(uri: str, endpoint: str = None, headers: Headers = None, retry_policy: Dict[str, Any] = {}, requests_session_async_synapse: AsyncClient = None, **kwargs) -> Union[Dict[str, Any], str, None]

Sends an HTTP GET request to the Synapse server.

PARAMETER	DESCRIPTION
uri	URI on which get is performed TYPE: str
endpoint	Server endpoint, defaults to self.repoEndpoint TYPE: str DEFAULT: None
headers	Dictionary of headers to use. TYPE: Headers DEFAULT: None
retry_policy	A retry policy that matches the arguments of synapseclient.core.retry.with_retry_time_based_async. TYPE: Dict[str, Any] DEFAULT: {}
requests_session_async_synapse	The async client to use when making this specific call. TYPE: AsyncClient DEFAULT: None
kwargs	Any other arguments taken by a request method DEFAULT: {}

RETURNS	DESCRIPTION
Union[Dict[str, Any], str, None]	JSON encoding of response

Source code in synapseclient/client.py

async def rest_get_async(
    self,
    uri: str,
    endpoint: str = None,
    headers: httpx.Headers = None,
    retry_policy: Dict[str, Any] = {},
    requests_session_async_synapse: httpx.AsyncClient = None,
    **kwargs,
) -> Union[Dict[str, Any], str, None]:
    """
    Sends an HTTP GET request to the Synapse server.

    Arguments:
        uri: URI on which get is performed
        endpoint: Server endpoint, defaults to self.repoEndpoint
        headers: Dictionary of headers to use.
        retry_policy: A retry policy that matches the arguments of
            [synapseclient.core.retry.with_retry_time_based_async][].
        requests_session_async_synapse: The async client to use when making this
            specific call.
        kwargs: Any other arguments taken by a
            [request](https://www.python-httpx.org/api/) method

    Returns:
        JSON encoding of response
    """
    response = await self._rest_call_async(
        "get",
        uri,
        None,
        endpoint,
        headers,
        retry_policy,
        requests_session_async_synapse,
        **kwargs,
    )
    return self._return_rest_body(response)

rest_post_async async

rest_post_async(uri: str, body: Any = None, endpoint: str = None, headers: Headers = None, retry_policy: Dict[str, Any] = {}, requests_session_async_synapse: AsyncClient = None, **kwargs) -> Union[Dict[str, Any], str]

Sends an HTTP POST request to the Synapse server.

PARAMETER	DESCRIPTION
uri	URI on which get is performed TYPE: str
body	The payload to be delivered TYPE: Any DEFAULT: None
endpoint	Server endpoint, defaults to self.repoEndpoint TYPE: str DEFAULT: None
headers	Dictionary of headers to use. TYPE: Headers DEFAULT: None
retry_policy	A retry policy that matches the arguments of synapseclient.core.retry.with_retry_time_based_async. TYPE: Dict[str, Any] DEFAULT: {}
requests_session_async_synapse	The async client to use when making this specific call. TYPE: AsyncClient DEFAULT: None
kwargs	Any other arguments taken by a request method DEFAULT: {}

RETURNS	DESCRIPTION
Union[Dict[str, Any], str]	JSON encoding of response

Source code in synapseclient/client.py

async def rest_post_async(
    self,
    uri: str,
    body: Any = None,
    endpoint: str = None,
    headers: httpx.Headers = None,
    retry_policy: Dict[str, Any] = {},
    requests_session_async_synapse: httpx.AsyncClient = None,
    **kwargs,
) -> Union[Dict[str, Any], str]:
    """
    Sends an HTTP POST request to the Synapse server.

    Arguments:
        uri: URI on which get is performed
        body: The payload to be delivered
        endpoint: Server endpoint, defaults to self.repoEndpoint
        headers: Dictionary of headers to use.
        retry_policy: A retry policy that matches the arguments of
            [synapseclient.core.retry.with_retry_time_based_async][].
        requests_session_async_synapse: The async client to use when making this
            specific call.
        kwargs: Any other arguments taken by a
            [request](https://www.python-httpx.org/api/) method

    Returns:
        JSON encoding of response
    """
    response = await self._rest_call_async(
        "post",
        uri,
        body,
        endpoint,
        headers,
        retry_policy,
        requests_session_async_synapse,
        **kwargs,
    )
    return self._return_rest_body(response)

rest_put_async async

rest_put_async(uri: str, body: Any = None, endpoint: str = None, headers: Headers = None, retry_policy: Dict[str, Any] = {}, requests_session_async_synapse: AsyncClient = None, **kwargs) -> Union[Dict[str, Any], str]

Sends an HTTP PUT request to the Synapse server.

PARAMETER	DESCRIPTION
uri	URI on which get is performed TYPE: str
body	The payload to be delivered. TYPE: Any DEFAULT: None
endpoint	Server endpoint, defaults to self.repoEndpoint TYPE: str DEFAULT: None
headers	Dictionary of headers to use. TYPE: Headers DEFAULT: None
retry_policy	A retry policy that matches the arguments of synapseclient.core.retry.with_retry_time_based_async. TYPE: Dict[str, Any] DEFAULT: {}
requests_session_async_synapse	The async client to use when making this specific call. TYPE: AsyncClient DEFAULT: None
kwargs	Any other arguments taken by a request method DEFAULT: {}

Returns JSON encoding of response

Source code in synapseclient/client.py

async def rest_put_async(
    self,
    uri: str,
    body: Any = None,
    endpoint: str = None,
    headers: httpx.Headers = None,
    retry_policy: Dict[str, Any] = {},
    requests_session_async_synapse: httpx.AsyncClient = None,
    **kwargs,
) -> Union[Dict[str, Any], str]:
    """
    Sends an HTTP PUT request to the Synapse server.

    Arguments:
        uri: URI on which get is performed
        body: The payload to be delivered.
        endpoint: Server endpoint, defaults to self.repoEndpoint
        headers: Dictionary of headers to use.
        retry_policy: A retry policy that matches the arguments of
            [synapseclient.core.retry.with_retry_time_based_async][].
        requests_session_async_synapse: The async client to use when making this
            specific call.
        kwargs: Any other arguments taken by a
            [request](https://www.python-httpx.org/api/) method

    Returns
        JSON encoding of response
    """
    response = await self._rest_call_async(
        "put",
        uri,
        body,
        endpoint,
        headers,
        retry_policy,
        requests_session_async_synapse,
        **kwargs,
    )
    return self._return_rest_body(response)

rest_delete_async async

rest_delete_async(uri: str, endpoint: str = None, headers: Headers = None, retry_policy: Dict[str, Any] = {}, requests_session_async_synapse: AsyncClient = None, **kwargs) -> None

Sends an HTTP DELETE request to the Synapse server.

PARAMETER	DESCRIPTION
uri	URI of resource to be deleted TYPE: str
endpoint	Server endpoint, defaults to self.repoEndpoint TYPE: str DEFAULT: None
headers	Dictionary of headers to use. TYPE: Headers DEFAULT: None
retry_policy	A retry policy that matches the arguments of synapseclient.core.retry.with_retry_time_based_async. TYPE: Dict[str, Any] DEFAULT: {}
requests_session_async_synapse	The async client to use when making this specific call TYPE: AsyncClient DEFAULT: None
kwargs	Any other arguments taken by a request method DEFAULT: {}

Source code in synapseclient/client.py

async def rest_delete_async(
    self,
    uri: str,
    endpoint: str = None,
    headers: httpx.Headers = None,
    retry_policy: Dict[str, Any] = {},
    requests_session_async_synapse: httpx.AsyncClient = None,
    **kwargs,
) -> None:
    """
    Sends an HTTP DELETE request to the Synapse server.

    Arguments:
        uri: URI of resource to be deleted
        endpoint: Server endpoint, defaults to self.repoEndpoint
        headers: Dictionary of headers to use.
        retry_policy: A retry policy that matches the arguments of
            [synapseclient.core.retry.with_retry_time_based_async][].
        requests_session_async_synapse: The async client to use when making this
            specific call
        kwargs: Any other arguments taken by a [request](https://www.python-httpx.org/api/) method

    """
    await self._rest_call_async(
        "delete",
        uri,
        None,
        endpoint,
        headers,
        retry_policy,
        requests_session_async_synapse,
        **kwargs,
    )

More information

See also the Synapse API documentation