Partial revert

Author: dandavison

temporalio/client.py

@@ -10,7 +10,6 @@
 import inspect
 import json
 import re
-import typing
 import uuid
 import warnings
 from abc import ABC, abstractmethod
@@ -1391,119 +1390,95 @@ async def count_activities(
         # Issues a workflowservice CountActivityExecutions call
         raise NotImplementedError
 
-    @typing.overload
     def get_activity_handle(
         self,
         *,
         activity_id: str,
         run_id: Optional[str] = None,
     ) -> ActivityHandle[Any]:
-        raise NotImplementedError
-
-    @typing.overload
-    def get_activity_handle(
-        self,
-        *,
-        activity_id: str,
-        workflow_id: str,
-        run_id: Optional[str],
-    ) -> WorkflowActivityHandle:
-        raise NotImplementedError
+        """Get a handle to an existing activity, as the caller of that activity.
 
-    @typing.overload
-    def get_activity_handle(
-        self,
-        *,
-        task_token: bytes,
-    ) -> WorkflowActivityHandle:
-        raise NotImplementedError
-
-    def get_activity_handle(
-        self,
-        *,
-        activity_id: Optional[str] = None,
-        workflow_id: Optional[str] = None,
-        run_id: Optional[str] = None,
-        task_token: Optional[bytes] = None,
-    ) -> Union[ActivityHandle[Any], WorkflowActivityHandle]:
-        """Get a handle to an existing activity.
+        To get a handle to an activity execution that you control for manual completion and
+        heartbeating, see :py:meth:`Client.get_async_activity_handle`.
 
         Args:
             activity_id: The activity ID.
-            workflow_id: The workflow ID if the activity was started from a workflow.
-            run_id:      The run ID. If not provided, targets the latest run.
-            task_token:  Optional task token for the activity if the activity was
-                         started from a workflow. Cannot be set if any of the id parameters
-                         are set.
+            run_id:      The run ID. If not provided, targets the
+                         latest run.
 
         Returns:
             A handle to the activity.
         """
         raise NotImplementedError
 
-    # Deprecated: get_activity_handle has an equivalent override
     @overload
-    def get_workflow_activity_handle(
+    def get_async_activity_handle(
+        self, *, activity_id: str, run_id: Optional[str]
+    ) -> AsyncActivityHandle:
+        pass
+
+    @overload
+    def get_async_activity_handle(
         self, *, workflow_id: str, run_id: Optional[str], activity_id: str
-    ) -> WorkflowActivityHandle:
+    ) -> AsyncActivityHandle:
         pass
 
-    # Deprecated: get_activity_handle has an equivalent override
     @overload
-    def get_workflow_activity_handle(
-        self, *, task_token: bytes
-    ) -> WorkflowActivityHandle:
+    def get_async_activity_handle(self, *, task_token: bytes) -> AsyncActivityHandle:
         pass
 
-    def get_workflow_activity_handle(
+    def get_async_activity_handle(
         self,
         *,
         workflow_id: Optional[str] = None,
         run_id: Optional[str] = None,
         activity_id: Optional[str] = None,
         task_token: Optional[bytes] = None,
-    ) -> WorkflowActivityHandle:
-        """Get a handle to an activity started by a workflow.
+    ) -> AsyncActivityHandle:
+        """Get a handle to an activity execution that you control, for manual completion and heartbeating.
 
-        .. warning::
-            DEPRECATED: This method is deprecated.
-            Use :py:meth:`Client.get_activity_handle` instead.
+        To get a handle to a standalone activity execution as the caller of that activity, see
+        :py:meth:`Client.get_activity_handle`.
+
+        This function may be used to get a handle to a standalone activity started by a client, or
+        an activity started by a workflow.
+
+        To get a handle to an activity started by a workflow, use one of the following two calls:
+        - Supply ``workflow_id``, ``run_id``, and ``activity_id``
+        - Supply the activity ``task_token`` alone
+
+        To get a handle to a standalone activity started by a client, supply ``activity_id`` and
+        ``run_id``
 
-        Either the workflow_id, run_id, and activity_id can be provided, or a
-        singular task_token can be provided.
 
         Args:
-            workflow_id: Workflow ID for the activity. Cannot be set if
-                task_token is set.
-            run_id: Run ID for the activity. Cannot be set if task_token is set.
-            activity_id: ID for the activity. Cannot be set if task_token is
-                set.
-            task_token: Task token for the activity. Cannot be set if any of the
-                id parameters are set.
+            workflow_id: Workflow ID for the activity.
+            run_id: Run ID for the activity. Cannot be
+                    set if task_token is set.
+            activity_id: ID for the activity.
+            activity_id: ID for the activity.
+            task_token: Task token for the activity.
 
         Returns:
-            A handle that can be used for completion or heartbeat.
+            A handle that can be used for completion or heartbeating.
         """
         if task_token is not None:
             if workflow_id is not None or run_id is not None or activity_id is not None:
                 raise ValueError("Task token cannot be present with other IDs")
-            return WorkflowActivityHandle(self, task_token)
+            return AsyncActivityHandle(self, task_token)
         elif workflow_id is not None:
             if activity_id is None:
                 raise ValueError(
                     "Workflow ID, run ID, and activity ID must all be given together"
                 )
-            return WorkflowActivityHandle(
+            return AsyncActivityHandle(
                 self,
                 AsyncActivityIDReference(
                     workflow_id=workflow_id, run_id=run_id, activity_id=activity_id
                 ),
             )
         raise ValueError("Task token or workflow/run/activity ID must be present")
 
-    # Deprecated alias
-    get_async_activity_handle = get_workflow_activity_handle
-
     async def create_schedule(
         self,
         id: str,
@@ -3078,12 +3053,19 @@ class ActivityIDReference:
 AsyncActivityIDReference = ActivityIDReference
 
 
-class _BaseActivityHandle(WithSerializationContext):
-    """Handle representing an activity."""
+class AsyncActivityHandle(WithSerializationContext):
+    """Handle representing an external activity for completion and heartbeat."""
 
-    _client: Client
-    _id_or_token: Union[ActivityIDReference, bytes]
-    _data_converter_override: Optional[DataConverter]
+    def __init__(
+        self,
+        client: Client,
+        id_or_token: Union[AsyncActivityIDReference, bytes],
+        data_converter_override: Optional[DataConverter] = None,
+    ) -> None:
+        """Create an async activity handle."""
+        self._client = client
+        self._id_or_token = id_or_token
+        self._data_converter_override = data_converter_override
 
     async def heartbeat(
         self,
@@ -3291,21 +3273,6 @@ async def reset(
             timeout=rpc_timeout,
         )
 
-
-class WorkflowActivityHandle(_BaseActivityHandle):
-    """Handle representing an activity started by a workflow."""
-
-    def __init__(
-        self,
-        client: Client,
-        id_or_token: Union[ActivityIDReference, bytes],
-        data_converter_override: Optional[DataConverter] = None,
-    ) -> None:
-        """Create an async activity handle."""
-        self._client = client
-        self._id_or_token = id_or_token
-        self._data_converter_override = data_converter_override
-
     def with_context(self, context: SerializationContext) -> Self:
         """Create a new AsyncActivityHandle with a different serialization context.
 
@@ -3330,14 +3297,10 @@ def with_context(self, context: SerializationContext) -> Self:
         )
 
 
-# Deprecated alias
-AsyncActivityHandle = WorkflowActivityHandle
-
-
 # TODO: in the future when messages can be sent to activities, we will want the activity handle to
 # be generic in the activity type in addition to the return type (as WorkflowHandle), to support
 # static type inference for signal/query/update.
-class ActivityHandle(Generic[ReturnType], _BaseActivityHandle):
+class ActivityHandle(Generic[ReturnType]):
     """Handle representing a standalone activity execution."""
 
     def __init__(

tests/worker/test_workflow.py

@@ -8017,7 +8017,7 @@ async def test_external_activity_cancellation_details(
         # Assert not paused
         assert not activity_info.paused
 
-        external_activity_handle = client.get_workflow_activity_handle(
+        external_activity_handle = client.get_async_activity_handle(
             workflow_id=wf_desc.id, run_id=wf_desc.run_id, activity_id=test_activity_id
         )
 
@@ -8473,7 +8473,7 @@ async def test_search_attribute_codec(client: Client, env_type: str):
         result = await client.execute_workflow(
             SearchAttributeCodecParentWorkflow.run,
             "Temporal",
-            id=f"encryption-workflow-id",
+            id="encryption-workflow-id",
             task_queue=worker.task_queue,
             search_attributes=TypedSearchAttributes(
                 [