put CreateTunnelData back and add TunnelCreateDocument and TunnelUpdateDocument

aaschaer · aaschaer · commit 6a6c22039b0b · 2026-03-27T16:00:04.000-05:00
diff --git a/changelog.d/20260226_154303_aaschaer_transfer_v2.rst b/changelog.d/20260226_154303_aaschaer_transfer_v2.rst
@@ -1,7 +1,8 @@
 Added
 -----
 
-- Added the experimental ``TransferClientV2`` client class (:pr:`NUMBER`)
+- Added the experimental ``TransferClientV2`` client class along with helper
+  classes ``TunnelCreateDocument`` and ``TunnelUpdateDocument`` (:pr:`NUMBER`)
 - JSON:API iteration and pagination is now supported through
   ``IterableJSONAPIResponse`` and ``JSONAPIPaginator`` (:pr:`NUMBER`)
 
diff --git a/src/globus_sdk/experimental/__init__.py b/src/globus_sdk/experimental/__init__.py
@@ -1,6 +1,7 @@
-from .transfer_v2 import CreateTunnelData, TransferClientV2
+from .transfer_v2 import TransferClientV2, TunnelCreateDocument, TunnelUpdateDocument
 
 __all__ = (
     "TransferClientV2",
-    "CreateTunnelData",
+    "TunnelCreateDocument",
+    "TunnelUpdateDocument",
 )
diff --git a/src/globus_sdk/experimental/transfer_v2/__init__.py b/src/globus_sdk/experimental/transfer_v2/__init__.py
@@ -1,7 +1,8 @@
 from .client import TransferClientV2
-from .data import CreateTunnelData
+from .data import TunnelCreateDocument, TunnelUpdateDocument
 
 __all__ = (
     "TransferClientV2",
-    "CreateTunnelData",
+    "TunnelCreateDocument",
+    "TunnelUpdateDocument",
 )
diff --git a/src/globus_sdk/experimental/transfer_v2/client.py b/src/globus_sdk/experimental/transfer_v2/client.py
@@ -4,14 +4,13 @@
 import typing as t
 import uuid
 
-from globus_sdk import client, exc, paging, response
-from globus_sdk._missing import MISSING
+from globus_sdk import client, paging, response
 from globus_sdk.response import IterableJSONAPIResponse
 from globus_sdk.scopes import TransferScopes
 from globus_sdk.services.transfer.errors import TransferAPIError
 from globus_sdk.transport import RetryConfig
 
-from .data import CreateTunnelData
+from .data import TunnelCreateDocument, TunnelUpdateDocument
 from .transport import TRANSFER_V2_DEFAULT_RETRY_CHECKS
 
 log = logging.getLogger(__name__)
@@ -46,7 +45,7 @@ class TransferClientV2(client.BaseClient):
             for stream_access_point in page:
                 print(stream_access_point["attributes"]["display_name"])
 
-    .. automethodlist:: globus_sdk.TransferClient
+    .. automethodlist:: globus_sdk.experimental.TransferClientV2
     """
 
     service_name = "transfer"
@@ -62,7 +61,7 @@ def _register_standard_retry_checks(self, retry_config: RetryConfig) -> None:
 
     def create_tunnel(
         self,
-        data: dict[str, t.Any] | CreateTunnelData,
+        data: dict[str, t.Any] | TunnelCreateDocument,
     ) -> response.GlobusHTTPResponse:
         """
         :param data: Parameters for the tunnel creation
@@ -73,7 +72,8 @@ def create_tunnel(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TrasferClientV2(...)
+                    data = globus_sdk.experimental.TunnelCreateDocument(...)
                     result = tc.create_tunnel(data)
                     print(result["data"]["id"])
 
@@ -82,30 +82,13 @@ def create_tunnel(
                 ``POST /v2/tunnels``
         """
         log.debug("TransferClientV2.create_tunnel(...)")
-        try:
-            data_element = data["data"]
-        except KeyError as e:
-            raise exc.GlobusSDKUsageError(
-                "create_tunnel() body was malformed (missing the 'data' key). "
-                "Use CreateTunnelData to easily create correct documents."
-            ) from e
-
-        try:
-            attributes = data_element["attributes"]
-        except KeyError:
-            data_element["attributes"] = {}
-            attributes = data_element["attributes"]
-        if attributes.get("submission_id", MISSING) is MISSING:
-            log.debug("create_tunnel auto-creating submission_id")
-            attributes["submission_id"] = str(uuid.uuid1())
-
         r = self.post("/v2/tunnels", data=data)
         return r
 
     def update_tunnel(
         self,
         tunnel_id: str | uuid.UUID,
-        update_doc: dict[str, t.Any],
+        update_doc: dict[str, t.Any] | TunnelUpdateDocument,
     ) -> response.GlobusHTTPResponse:
         r"""
         :param tunnel_id: The ID of the Tunnel.
@@ -117,13 +100,8 @@ def update_tunnel(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.TrasferClientV2(...)
-                    "data" = {
-                        "type": "Tunnel",
-                        "attributes": {
-                            "state": "STOPPING",
-                        },
-                    }
+                    tc = globus_sdk.experimental.TrasferClientV2(...)
+                    data = globus_sdk.experimental.TunnelUpdateDocument(...)
                     result = tc.update_tunnel(tunnel_id, data)
                     print(result["data"])
 
@@ -152,7 +130,7 @@ def get_tunnel(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TrasferClientV2(...)
                     result = tc.show_tunnel(tunnel_id)
                     print(result["data"])
 
@@ -180,7 +158,7 @@ def delete_tunnel(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TrasferClientV2(...)
                     tc.delete_tunnel(tunnel_id)
 
             .. tab-item:: API Info
@@ -208,7 +186,7 @@ def list_tunnels(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TrasferClientV2(...)
                     tc.list_tunnels(tunnel_id)
 
             .. tab-item:: API Info
@@ -236,7 +214,7 @@ def get_tunnel_events(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TrasferClientV2(...)
                     result = tc.get_tunnel_events(tunnel_id)
                     print(result["data"])
 
@@ -269,7 +247,7 @@ def get_stream_access_point(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TrasferClientV2(...)
                     tc.get_stream_access_point(stream_ap_id)
 
             .. tab-item:: API Info
@@ -302,7 +280,7 @@ def list_stream_access_points(
 
                 .. code-block:: python
 
-                    tc = globus_sdk.TrasferClientV2(...)
+                    tc = globus_sdk.experimental.TrasferClientV2(...)
                     tc.list_stream_access_points()
 
             .. tab-item:: API Info
diff --git a/src/globus_sdk/experimental/transfer_v2/data/__init__.py b/src/globus_sdk/experimental/transfer_v2/data/__init__.py
@@ -4,6 +4,6 @@
 :class:`TransferClient <globus_sdk.TransferClient>` methods without conversion.
 """
 
-from .tunnel_data import CreateTunnelData
+from .tunnel_documents import TunnelCreateDocument, TunnelUpdateDocument
 
-__all__ = ("CreateTunnelData",)
+__all__ = ("TunnelCreateDocument", "TunnelUpdateDocument")
diff --git a/src/globus_sdk/experimental/transfer_v2/data/tunnel_documents.py b/src/globus_sdk/experimental/transfer_v2/data/tunnel_documents.py
@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import logging
+import typing as t
+import uuid
+
+from globus_sdk._missing import MISSING, MissingType
+from globus_sdk._payload import GlobusPayload
+
+log = logging.getLogger(__name__)
+
+
+class TunnelCreateDocument(GlobusPayload):
+    """
+    Convenience class for constructing a tunnel document to use as the
+    ``data`` parameter to
+    :meth:`create_tunnel <globus_sdk.TransferClientV2.create_tunnel>`.
+    """
+
+    def __init__(
+        self,
+        initiator_stream_access_point: uuid.UUID | str,
+        listener_stream_access_point: uuid.UUID | str,
+        *,
+        label: str | MissingType = MISSING,
+        listener_port: int | MissingType = MISSING,
+        listener_ip_address: str | MissingType = MISSING,
+        submission_id: uuid.UUID | str | MissingType = MISSING,
+        lifetime_mins: int | MissingType = MISSING,
+        restartable: bool | MissingType = MISSING,
+        additional_fields: dict[str, t.Any] | None = None,
+    ) -> None:
+        super().__init__()
+        log.debug("Creating a new TunnelCreateDocument object")
+
+        # Auto-create submission_id if not given now so that the same
+        # submission_id will be used across retries
+        if submission_id is MISSING:
+            submission_id = uuid.uuid1()
+
+        relationships = {
+            "listener": {
+                "data": {
+                    "type": "StreamAccessPoint",
+                    "id": listener_stream_access_point,
+                }
+            },
+            "initiator": {
+                "data": {
+                    "type": "StreamAccessPoint",
+                    "id": initiator_stream_access_point,
+                }
+            },
+        }
+        attributes = {
+            "label": label,
+            "listener_port": listener_port,
+            "listener_ip_address": listener_ip_address,
+            "submission_id": submission_id,
+            "restartable": restartable,
+            "lifetime_mins": lifetime_mins,
+        }
+        if additional_fields is not None:
+            attributes.update(additional_fields)
+
+        self["data"] = {
+            "type": "Tunnel",
+            "relationships": relationships,
+            "attributes": attributes,
+        }
+
+
+class TunnelUpdateDocument(GlobusPayload):
+    """
+    Convenience class for constructing a tunnel document to use as the
+    ``data`` parameter to
+    :meth:`update_tunnel <globus_sdk.TransferClientV2.update_tunnel>`.
+    """
+
+    def __init__(
+        self,
+        *,
+        label: str | MissingType = MISSING,
+        listener_port: int | MissingType = MISSING,
+        listener_ip_address: str | MissingType = MISSING,
+        state: t.Literal["STOPPING"] | MissingType = MISSING,
+        additional_fields: dict[str, t.Any] | None = None,
+    ) -> None:
+        super().__init__()
+        log.debug("Creating a new TunnelUpdateDocument object")
+
+        attributes = {
+            "label": label,
+            "listener_port": listener_port,
+            "listener_ip_address": listener_ip_address,
+            "state": state,
+        }
+        if additional_fields is not None:
+            attributes.update(additional_fields)
+
+        self["data"] = {
+            "type": "Tunnel",
+            "attributes": attributes,
+        }
diff --git a/src/globus_sdk/services/transfer/data/__init__.py b/src/globus_sdk/services/transfer/data/__init__.py
@@ -4,11 +4,8 @@
 :class:`TransferClient <globus_sdk.TransferClient>` methods without conversion.
 """
 
-# CreateTunnelData has been moved to experimental but is provided here for
-# backwards compatibility
-from globus_sdk.experimental.transfer_v2.data import CreateTunnelData
-
 from .delete_data import DeleteData
 from .transfer_data import TransferData
+from .tunnel_data import CreateTunnelData
 
 __all__ = ("TransferData", "DeleteData", "CreateTunnelData")
diff --git a/src/globus_sdk/services/transfer/data/tunnel_data.py b/src/globus_sdk/services/transfer/data/tunnel_data.py
@@ -14,7 +14,7 @@ class CreateTunnelData(GlobusPayload):
     """
     Convenience class for constructing a tunnel document to use as the
     ``data`` parameter to
-    :meth:`create_tunnel <globus_sdk.TransferClientV2.create_tunnel>`.
+    :meth:`create_tunnel <globus_sdk.TransferClient.create_tunnel>`.
     """
 
     def __init__(
diff --git a/tests/functional/services/transfer/v2/test_create_tunnel.py b/tests/functional/services/transfer/v2/test_create_tunnel.py
@@ -1,18 +1,15 @@
 import json
 import uuid
 
-import pytest
-
-from globus_sdk import exc
-from globus_sdk.experimental import CreateTunnelData
+from globus_sdk.experimental import TunnelCreateDocument
 from globus_sdk.testing import get_last_request, load_response
 
 
 def test_create_tunnel(client):
     meta = load_response(client.create_tunnel).metadata
 
     submission_id = uuid.uuid4()
-    data = CreateTunnelData(
+    data = TunnelCreateDocument(
         meta["initiator_ap"],
         meta["listener_ap"],
         submission_id=submission_id,
@@ -38,33 +35,17 @@ def test_create_tunnel(client):
 def test_create_tunnel_no_submission(client):
     meta = load_response(client.create_tunnel).metadata
 
-    data = CreateTunnelData(
+    data = TunnelCreateDocument(
         meta["initiator_ap"], meta["listener_ap"], label=meta["display_name"]
     )
 
+    # confirm TunnelCreateDocument auto-generated a submission_id
+    generated_uuid = data["data"]["attributes"]["submission_id"]
+    assert isinstance(generated_uuid, uuid.UUID)
+
     res = client.create_tunnel(data)
     assert res.http_status == 200
 
     req = get_last_request()
     sent = json.loads(req.body)
-    assert sent["data"]["attributes"]["submission_id"] is not None
-
-
-def test_create_tunnel_bad_input(client):
-    data = {
-        "relationships": {
-            "listener": {
-                "data": {
-                    "type": "StreamAccessPoint",
-                }
-            },
-            "initiator": {
-                "data": {
-                    "type": "StreamAccessPoint",
-                }
-            },
-        }
-    }
-
-    with pytest.raises(exc.GlobusSDKUsageError):
-        client.create_tunnel(data)
+    assert sent["data"]["attributes"]["submission_id"] == str(generated_uuid)
diff --git a/tests/functional/services/transfer/v2/test_get_tunnel_events.py b/tests/functional/services/transfer/v2/test_get_tunnel_events.py
@@ -0,0 +1,12 @@
+from globus_sdk.testing import get_last_request, load_response
+
+
+def test_get_tunnel_events(client):
+    meta = load_response(client.get_tunnel_events).metadata
+    res = client.get_tunnel_events(meta["tunnel_id"])
+    assert res.http_status == 200
+    assert res["data"][0]["type"] == "TunnelEvent"
+    assert res["data"][1]["type"] == "TunnelEvent"
+
+    req = get_last_request()
+    assert req.body is None
diff --git a/tests/functional/services/transfer/v2/test_list_tunnels.py b/tests/functional/services/transfer/v2/test_list_tunnels.py
@@ -6,7 +6,7 @@ def test_list_tunnels(client):
 
     res = client.list_tunnels()
     assert res.http_status == 200
-    assert len(res["data"]) == 2
+    assert len(list(res)) == 2
 
     req = get_last_request()
     assert req.body is None
diff --git a/tests/functional/services/transfer/v2/test_update_tunnel.py b/tests/functional/services/transfer/v2/test_update_tunnel.py

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`		`-from .transfer_v2 import CreateTunnelData, TransferClientV2`
	`1`	`+from .transfer_v2 import TransferClientV2, TunnelCreateDocument, TunnelUpdateDocument`
`2`	`2`
`3`	`3`	`__all__ = (`
`4`	`4`	`"TransferClientV2",`
`5`		`- "CreateTunnelData",`
	`5`	`+ "TunnelCreateDocument",`
	`6`	`+ "TunnelUpdateDocument",`
`6`	`7`	`)`