[SYNPY-1426] Deprecate create_snapshot_version in client (#1217)

* Add create_table_snapshot function and update snapshot methods in Table model

- Implemented create_table_snapshot in table_services.py for creating table snapshots via the Synapse REST API.
- Updated the Table model to use create_table_snapshot instead of the deprecated _create_table_snapshot method.
- Added unit tests for snapshot creation in both asynchronous and synchronous test files.

Author: BryanFauble

synapseclient/api/__init__.py

@@ -68,6 +68,7 @@
 from .table_services import (
     ViewEntityType,
     ViewTypeMask,
+    create_table_snapshot,
     get_columns,
     get_default_columns,
     post_columns,
@@ -181,4 +182,6 @@
     "get_user_profile_by_id",
     "get_user_profile_by_username",
     "is_user_certified",
+    # table_services
+    "create_table_snapshot",
 ]

synapseclient/api/table_services.py

@@ -5,7 +5,9 @@
 
 import json
 from enum import Enum
-from typing import TYPE_CHECKING, List, Optional
+from typing import TYPE_CHECKING, Dict, List, Optional, Union
+
+from synapseclient.core.utils import delete_none_keys, id_of
 
 if TYPE_CHECKING:
     from synapseclient import Synapse
@@ -43,6 +45,54 @@ class ViewTypeMask(int, Enum):
     MATERIALIZED_VIEW = 0x200
 
 
+async def create_table_snapshot(
+    table_id: str,
+    comment: Optional[str] = None,
+    label: Optional[str] = None,
+    activity_id: Optional[str] = None,
+    *,
+    synapse_client: Optional["Synapse"] = None,
+) -> Dict[str, Union[str, int]]:
+    """
+    Creates a table snapshot using the Synapse REST API.
+
+    Arguments:
+        table_id: Table ID to create a snapshot for.
+        comment: Optional snapshot comment.
+        label: Optional snapshot label.
+        activity_id: Optional activity ID or activity instance applied to snapshot version.
+        synapse_client: If not passed in and caching was not disabled by
+            `Synapse.allow_client_caching(False)` this will use the last created
+            instance from the Synapse class constructor.
+
+    Returns:
+        A dictionary containing the snapshot response.
+    """
+    from synapseclient import Synapse
+
+    client = Synapse.get_client(synapse_client=synapse_client)
+
+    if activity_id and not isinstance(activity_id, str):
+        activity_id = str(activity_id)
+
+    snapshot_body = {
+        "snapshotComment": comment,
+        "snapshotLabel": label,
+        "snapshotActivityId": activity_id,
+    }
+
+    delete_none_keys(snapshot_body)
+
+    table_id = id_of(table_id)
+    uri = f"/entity/{table_id}/table/snapshot"
+
+    snapshot_response = await client.rest_post_async(
+        uri, body=json.dumps(snapshot_body)
+    )
+
+    return snapshot_response
+
+
 async def get_columns(
     table_id: str,
     *,

synapseclient/client.py

@@ -5973,6 +5973,12 @@ def getColumns(self, x, limit=100, offset=0):
         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[
@@ -5983,7 +5989,11 @@ def create_snapshot_version(
         activity: typing.Union[Activity, str] = None,
         wait: bool = True,
     ) -> int:
-        """Create a new Table Version, new View version, or new Dataset version.
+        """
+        **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.
@@ -5996,6 +6006,69 @@ def create_snapshot_version(
 
         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)):
@@ -6023,6 +6096,10 @@ def create_snapshot_version(
         # 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],
@@ -6065,6 +6142,10 @@ def _create_table_snapshot(
         )
         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],

synapseclient/models/table.py

@@ -1,4 +1,3 @@
-import asyncio
 import dataclasses
 from collections import OrderedDict
 from copy import deepcopy
@@ -10,6 +9,7 @@
 
 from synapseclient import Synapse
 from synapseclient import Table as Synapse_Table
+from synapseclient.api import create_table_snapshot
 from synapseclient.core.async_utils import async_to_sync
 from synapseclient.core.constants import concrete_types
 from synapseclient.core.utils import MB, delete_none_keys
@@ -1508,17 +1508,14 @@ async def main():
             f"[{self.id}:{self.name}]: Creating a snapshot of the table."
         )
 
-        loop = asyncio.get_event_loop()
-        snapshot_response = await loop.run_in_executor(
-            None,
-            lambda: client._create_table_snapshot(
-                table=self.id,
-                comment=comment,
-                label=label,
-                activity=(
-                    self.activity.id if self.activity and include_activity else None
-                ),
+        snapshot_response = await create_table_snapshot(
+            table_id=self.id,
+            comment=comment,
+            label=label,
+            activity_id=(
+                self.activity.id if self.activity and include_activity else None
             ),
+            synapse_client=synapse_client,
         )
 
         if associate_activity_to_new_version and self.activity: