feat: [sc-47448] implement bookmark methods in Transfer v2 client

changelog.d/20260408_210055_pjhinton_sc_47448_transfer_v2_bookmark_sdk_support.rst

@@ -0,0 +1,4 @@
+Added
+-----
+
+- Support for managing bookmarks via the Transfer v2 client (:pr:`NUMBER`)

src/globus_sdk/experimental/__init__.py

@@ -3,6 +3,8 @@
 import typing as t
 
 __all__ = (
+    "BookmarkCreateDocument",
+    "BookmarkUpdateDocument",
     "TransferClientV2",
     "TunnelCreateDocument",
     "TunnelUpdateDocument",
@@ -14,13 +16,17 @@
 # components which do not need it
 if t.TYPE_CHECKING:
     from .transfer_v2 import (
+        BookmarkCreateDocument,
+        BookmarkUpdateDocument,
         TransferClientV2,
         TunnelCreateDocument,
         TunnelUpdateDocument,
     )
 else:
     _LAZY_IMPORT_TABLE = {
         "transfer_v2": {
+            "BookmarkCreateDocument",
+            "BookmarkUpdateDocument",
             "TransferClientV2",
             "TunnelCreateDocument",
             "TunnelUpdateDocument",

src/globus_sdk/experimental/transfer_v2/__init__.py

@@ -1,7 +1,14 @@
 from .client import TransferClientV2
-from .data import TunnelCreateDocument, TunnelUpdateDocument
+from .data import (
+    BookmarkCreateDocument,
+    BookmarkUpdateDocument,
+    TunnelCreateDocument,
+    TunnelUpdateDocument,
+)
 
 __all__ = (
+    "BookmarkCreateDocument",
+    "BookmarkUpdateDocument",
     "TransferClientV2",
     "TunnelCreateDocument",
     "TunnelUpdateDocument",

src/globus_sdk/experimental/transfer_v2/client.py

@@ -10,7 +10,12 @@
 from globus_sdk.services.transfer.errors import TransferAPIError
 from globus_sdk.transport import RetryConfig
 
-from .data import TunnelCreateDocument, TunnelUpdateDocument
+from .data import (
+    BookmarkCreateDocument,
+    BookmarkUpdateDocument,
+    TunnelCreateDocument,
+    TunnelUpdateDocument,
+)
 from .transport import TRANSFER_V2_DEFAULT_RETRY_CHECKS
 
 log = logging.getLogger(__name__)
@@ -72,7 +77,7 @@ def create_tunnel(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.experimental.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TransferClientV2(...)
                     data = globus_sdk.experimental.TunnelCreateDocument(...)
                     result = tc.create_tunnel(data)
                     print(result["data"]["id"])
@@ -81,7 +86,7 @@ def create_tunnel(
 
                 ``POST /v2/tunnels``
         """
-        log.debug("TransferClientV2.create_tunnel(...)")
+        log.debug(f"{self.__class__.__name__}.create_tunnel(...)")
         r = self.post("/v2/tunnels", data=data)
         return r
 
@@ -100,7 +105,7 @@ def update_tunnel(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.experimental.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TransferClientV2(...)
                     data = globus_sdk.experimental.TunnelUpdateDocument(...)
                     result = tc.update_tunnel(tunnel_id, data)
                     print(result["data"])
@@ -109,7 +114,7 @@ def update_tunnel(
 
                 ``PATCH /v2/tunnels/<tunnel_id>``
         """
-        log.debug(f"TransferClientV2.update_tunnel({tunnel_id}, {update_doc})")
+        log.debug(f"{self.__class__.__name__}.update_tunnel({tunnel_id}, {update_doc})")
         r = self.patch(f"/v2/tunnels/{tunnel_id}", data=update_doc)
         return r
 
@@ -130,15 +135,15 @@ def get_tunnel(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.experimental.TrasferClientV2(...)
-                    result = tc.show_tunnel(tunnel_id)
+                    tc = globus_sdk.experimental.TransferClientV2(...)
+                    result = tc.get_tunnel(tunnel_id)
                     print(result["data"])
 
             .. tab-item:: API Info
 
                 ``GET /v2/tunnels/<tunnel_id>``
         """
-        log.debug("TransferClientV2.get_tunnel({tunnel_id}, {query_params})")
+        log.debug(f"{self.__class__.__name__}.get_tunnel({tunnel_id}, {query_params})")
         r = self.get(f"/v2/tunnels/{tunnel_id}", query_params=query_params)
         return r
 
@@ -158,14 +163,14 @@ def delete_tunnel(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.experimental.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TransferClientV2(...)
                     tc.delete_tunnel(tunnel_id)
 
             .. tab-item:: API Info
 
                 ``DELETE /v2/tunnels/<tunnel_id>``
         """
-        log.debug(f"TransferClientV2.delete_tunnel({tunnel_id})")
+        log.debug(f"{self.__class__.__name__}.delete_tunnel({tunnel_id})")
         r = self.delete(f"/v2/tunnels/{tunnel_id}")
         return r
 
@@ -186,14 +191,14 @@ def list_tunnels(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.experimental.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TransferClientV2(...)
                     tc.list_tunnels(tunnel_id)
 
             .. tab-item:: API Info
 
                 ``GET /v2/tunnels/``
         """
-        log.debug(f"TransferClientV2.list_tunnels({query_params})")
+        log.debug(f"{self.__class__.__name__}.list_tunnels({query_params})")
         r = self.get("/v2/tunnels", query_params=query_params)
         return IterableJSONAPIResponse(r)
 
@@ -214,15 +219,17 @@ def get_tunnel_events(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.experimental.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TransferClientV2(...)
                     result = tc.get_tunnel_events(tunnel_id)
                     print(result["data"])
 
             .. tab-item:: API Info
 
                 ``GET /v2/tunnels/<tunnel_id>/events``
         """
-        log.debug(f"TransferClientV2.get_tunnel_events({tunnel_id}, {query_params})")
+        log.debug(
+            f"{self.__class__.__name__}.get_tunnel_events({tunnel_id}, {query_params})"
+        )
         r = self.get(f"/v2/tunnels/{tunnel_id}/events", query_params=query_params)
         return IterableJSONAPIResponse(r)
 
@@ -247,15 +254,16 @@ def get_stream_access_point(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.experimental.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TransferClientV2(...)
                     tc.get_stream_access_point(stream_ap_id)
 
             .. tab-item:: API Info
 
                 ``GET /v2/stream_access_points/<stream_ap_id>``
         """
         log.debug(
-            f"TransferClientV2.get_stream_access_point({stream_ap_id}, {query_params})"
+            f"{self.__class__.__name__}."
+            f"get_stream_access_point({stream_ap_id}, {query_params})"
         )
         r = self.get(
             f"/v2/stream_access_points/{stream_ap_id}", query_params=query_params
@@ -280,13 +288,157 @@ def list_stream_access_points(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.experimental.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TransferClientV2(...)
                     tc.list_stream_access_points()
 
             .. tab-item:: API Info
 
                 ``GET /v2/stream_access_points``
         """
-        log.debug(f"TransferClientV2.list_stream_access_points({query_params})")
+        log.debug(
+            f"{self.__class__.__name__}.list_stream_access_points({query_params})"
+        )
         r = self.get("/v2/stream_access_points", query_params=query_params)
         return IterableJSONAPIResponse(r)
+
+    def create_bookmark(
+        self, data: dict[str, t.Any] | BookmarkCreateDocument
+    ) -> response.GlobusHTTPResponse:
+        """
+        :param data: Parameters for bookmark creation
+
+        .. tab-set::
+
+            .. tab-item:: Example Usage
+
+                .. code-block:: python
+
+                    tc = globus_sdk.experimental.TransferClientV2(...)
+                    data = globus_sdk.experimental.BookmarkCreateDocument(...)
+                    result = tc.create_bookmark(data)
+                    print(result["data"]["id"])
+
+            .. tab-item:: API Info
+
+                ``POST /v2/bookmarks``
+        """
+        log.debug(f"{self.__class__.__name__}.create_bookmark(...)")
+        r = self.post("/v2/bookmarks", data=data)
+        return r
+
+    def update_bookmark(
+        self,
+        bookmark_id: uuid.UUID | str,
+        update_document: dict[str, t.Any] | BookmarkUpdateDocument,
+    ) -> response.GlobusHTTPResponse:
+        r"""
+        :param bookmark_id: The ID of the Bookmark.
+        :param update_document: The document that will be sent to the patch API.
+
+        .. tab-set::
+
+            .. tab-item:: Example Usage
+
+                .. code-block:: python
+
+                    tc = globus_sdk.experimental.TransferClientV2(...)
+                    data = globus_sdk.experimental.BookmarkUpdateDocument(...)
+                    result = tc.update_bookmark(bookmark_id, data)
+                    print(result["data"])
+
+            .. tab-item:: API Info
+
+                ``PATCH /v2/bookmarks/<bookmark_id>``
+        """
+        log.debug(
+            f"{self.__class__.__name__}."
+            f"update_bookmark({bookmark_id}, {update_document})"
+        )
+        r = self.patch(f"/v2/bookmarks/{bookmark_id}", data=update_document)
+        return r
+
+    def get_bookmark(
+        self,
+        bookmark_id: uuid.UUID | str,
+        *,
+        query_params: dict[str, t.Any] | None = None,
+    ) -> response.GlobusHTTPResponse:
+        """
+        :param bookmark_id: The ID of the Bookmark for which we are fetching details.
+        :param query_params: Any additional parameters will be passed through
+            as request parameters on the URL.
+
+        .. tab-set::
+
+            .. tab-item:: Example Usage
+
+                .. code-block:: python
+
+                    tc = globus_sdk.experimental.TransferClientV2(...)
+                    query_params = {"include": "collection"}
+                    result = tc.get_bookmark(bookmark_id, query_params)
+                    print(result["data"])
+
+            .. tab-item:: API Info
+
+                ``GET /v2/bookmarks/<bookmark_id>``
+        """
+        log.debug(
+            f"{self.__class__.__name__}.get_bookmark({bookmark_id}, {query_params})"
+        )
+        r = self.get(f"/v2/bookmarks/{bookmark_id}", query_params=query_params)
+        return r
+
+    def delete_bookmark(
+        self,
+        bookmark_id: uuid.UUID | str,
+    ) -> response.GlobusHTTPResponse:
+        """
+        :param bookmark_id: The ID of the Bookmark to be deleted.
+
+        .. tab-set::
+
+            .. tab-item:: Example Usage
+
+                .. code-block:: python
+
+                    tc = globus_sdk.experimental.TransferClientV2(...)
+                    tc.delete_bookmark(bookmark_id)
+
+            .. tab-item:: API Info
+
+                ``DELETE /v2/bookmarks/<bookmark_id>``
+        """
+        log.debug(f"{self.__class__.__name__}.delete_bookmark({bookmark_id})")
+        r = self.delete(f"/v2/bookmarks/{bookmark_id}")
+        return r
+
+    def list_bookmarks(
+        self,
+        *,
+        query_params: dict[str, t.Any] | None = None,
+    ) -> IterableJSONAPIResponse:
+        """
+        :param query_params: Any additional parameters will be passed through
+            as request parameters on the URL.
+
+        This will list all Bookmarks created by the authenticated user's primary
+            and linked identities.
+
+        .. tab-set::
+
+            .. tab-item:: Example Usage
+
+                .. code-block:: python
+
+                    tc = globus_sdk.experimental.TransferClientV2(...)
+                    query_params = {"include": "collection"}
+                    tc.list_bookmarks(query_params)
+
+            .. tab-item:: API Info
+
+                ``GET /v2/bookmarks``
+        """
+        log.debug(f"{self.__class__.__name__}.list_bookmarks({query_params})")
+        r = self.get("/v2/bookmarks", query_params=query_params)
+        return IterableJSONAPIResponse(r)

src/globus_sdk/experimental/transfer_v2/data/__init__.py

@@ -4,6 +4,12 @@
 :class:`TransferClient <globus_sdk.TransferClient>` methods without conversion.
 """
 
+from .bookmark_documents import BookmarkCreateDocument, BookmarkUpdateDocument
 from .tunnel_documents import TunnelCreateDocument, TunnelUpdateDocument
 
-__all__ = ("TunnelCreateDocument", "TunnelUpdateDocument")
+__all__ = (
+    "BookmarkCreateDocument",
+    "BookmarkUpdateDocument",
+    "TunnelCreateDocument",
+    "TunnelUpdateDocument",
+)