address comments 2, fix docstrings, clarify signatures and errors

Author: mavemuri

temporalio/client/_interceptor.py

@@ -322,7 +322,7 @@ class StartWorkflowUpdateInput:
     ret_type: type | None
     rpc_metadata: Mapping[str, str | bytes]
     rpc_timeout: timedelta | None
-    # The following options are for Nexus Operation-backed updates. Experimental and unstable
+    # The following options are for Workflow Updates exposed as Nexus Operations. Experimental and unstable
     callbacks: Sequence[Callback] | None = None
     links: Sequence[temporalio.api.common.v1.Link] | None = None
     request_id: str | None = None

temporalio/client/_workflow.py

@@ -956,7 +956,7 @@ async def _start_update(
         result_type: type | None = None,
         rpc_metadata: Mapping[str, str | bytes] = {},
         rpc_timeout: timedelta | None = None,
-        # The following options are for Nexus Operation-backed updates. Experimental and unstable
+        # The following options are for Workflow Updates exposed as Nexus Operations. Experimental and unstable
         callbacks: Sequence[Callback] | None = None,
         links: Sequence[temporalio.api.common.v1.Link] | None = None,
         request_id: str | None = None,

temporalio/nexus/_operation_context.py

@@ -717,7 +717,7 @@ async def _start_nexus_backing_workflow(
     return WorkflowHandle[ReturnType]._unsafe_from_client_workflow_handle(wf_handle)
 
 
-async def _start_nexus_backed_workflow_update(  # pyright: ignore[reportUnusedFunction]
+async def _start_nexus_operation_workflow_update(  # pyright: ignore[reportUnusedFunction]
     *,
     temporal_context: _TemporalStartOperationContext,
     workflow_id: str,

temporalio/nexus/_operation_handlers.py

@@ -154,7 +154,7 @@ class CancelUpdateWorkflowOptions:
     update_id: str
     """The ID of the update to cancel."""
     run_id: str
-    """The workflow runID that accepted the update"""
+    """The workflow runID that accepted the update."""
 
 
 class TemporalOperationHandler(OperationHandler[InputT, OutputT], ABC):
@@ -239,17 +239,17 @@ async def cancel_workflow_update(
         ctx: TemporalCancelOperationContext,  # pyright: ignore[reportUnusedParameter]
         options: CancelUpdateWorkflowOptions,  # pyright: ignore[reportUnusedParameter]
     ) -> None:
-        """Cancels the workflow update backing the Nexus operation. Cancellation is not natively supported for update-workflow Nexus operations.
-        Inherit a TemporalOperationHandler and override this method to run cancellable workflow updates.
+        """Cancels the Workflow Update triggered by the Nexus operation. There is no native way to cancel an accepted Update, so cancellation depends on the Update handler itself.
+        Override this method and coordinate with the specific Update handler to trigger a cancellation.
 
 
         .. warning::
            This API is experimental and unstable.
         """
         raise HandlerError(
             """
-                Cancellation is not natively supported for update-workflow Nexus operations.
-                Inherit a TemporalOperationHandler and override this method to run cancellable workflow updates.
+                There is no native way to cancel an accepted Update, so cancellation depends on the Update handler itself. 
+                Override this method and coordinate with the specific Update handler to trigger a cancellation.
             """,
             type=HandlerErrorType.NOT_IMPLEMENTED,
         )

temporalio/nexus/_temporal_client.py

@@ -21,8 +21,8 @@
 
 import temporalio.common
 from temporalio.nexus._operation_context import (
-    _start_nexus_backed_workflow_update,
     _start_nexus_backing_workflow,
+    _start_nexus_operation_workflow_update,
     _TemporalStartOperationContext,
 )
 from temporalio.types import (
@@ -361,7 +361,7 @@ async def start_workflow_update(
         run_id: str | None = None,
         first_execution_run_id: str | None = None,
     ) -> TemporalOperationResult[Any]:
-        """Start a workflow update as the backing asynchronous Nexus operation.
+        """Start a Workflow Update-backed Nexus Operation.
 
         .. warning::
             This API is experimental and unstable.
@@ -481,14 +481,14 @@ async def start_workflow_update(
         run_id: str | None = None,
         first_execution_run_id: str | None = None,
     ) -> TemporalOperationResult[Any]:
-        """Start a workflow update as the backing asynchronous Nexus operation."""
+        """Start a Workflow Update-backed Nexus Operation."""
         if not self._temporal_context.nexus_context.callback_url:
             raise HandlerError(
                 "callback URL is required for a workflow update Nexus operation",
                 type=HandlerErrorType.BAD_REQUEST,
             )
         with self._reserve_async_start():
-            update_handle = await _start_nexus_backed_workflow_update(
+            update_handle = await _start_nexus_operation_workflow_update(
                 temporal_context=self._temporal_context,
                 workflow_id=workflow_id,
                 update=update,

temporalio/nexus/_token.py

@@ -107,7 +107,7 @@ def decode(cls, token: str) -> Self:
         update_id = token_details.get("uid")
         if not isinstance(update_id, str | None):
             raise TypeError(
-                f"invalid token: expected update_id id to be a string or None, got {type(update_id)}"
+                f"invalid token: expected update_id to be a string or None, got {type(update_id)}"
             )
 
         if token_type == OperationTokenType.UPDATE_WORKFLOW and not update_id: