move to an options dataclass for cancel_workflow_run to future proof against new options

Author: VegetarianOrc

temporalio/nexus/__init__.py

@@ -24,12 +24,16 @@
     wait_for_worker_shutdown,
     wait_for_worker_shutdown_sync,
 )
-from ._operation_handlers import TemporalNexusOperationHandler
+from ._operation_handlers import (
+    CancelWorkflowRunOptions,
+    TemporalNexusOperationHandler,
+)
 from ._temporal_client import TemporalNexusClient, TemporalOperationResult
 from ._token import WorkflowHandle
 
 __all__ = (
     "workflow_run_operation",
+    "CancelWorkflowRunOptions",
     "Info",
     "LoggerAdapter",
     "NexusCallback",

temporalio/nexus/_operation_handlers.py

@@ -2,6 +2,7 @@
 
 from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
 from typing import Any
 
 from nexusrpc import (
@@ -123,6 +124,22 @@ async def _cancel_workflow(
     await client_workflow_handle.cancel(**kwargs)
 
 
+@dataclass(frozen=True)
+class CancelWorkflowRunOptions:
+    """Options for cancelling the workflow backing a Nexus operation.
+
+    These options are built by :py:class:`TemporalNexusOperationHandler` and passed to
+    :py:meth:`TemporalNexusOperationHandler.cancel_workflow_run`. Fields may be added in
+    the future; overrides should consume the fields they need.
+
+    .. warning::
+       This API is experimental and unstable.
+    """
+
+    workflow_id: str
+    """The ID of the workflow to cancel."""
+
+
 class TemporalNexusOperationHandler(OperationHandler[InputT, OutputT], ABC):
     """Operation handler for Nexus operations that interact with Temporal.
     Implementations override the start_operation method.
@@ -175,19 +192,24 @@ async def cancel(self, ctx: CancelOperationContext, token: str) -> None:
         )
         match operation_token.type:
             case OperationTokenType.WORKFLOW:
-                await self.cancel_workflow_run(cancel_ctx, operation_token.workflow_id)
+                options = CancelWorkflowRunOptions(
+                    workflow_id=operation_token.workflow_id
+                )
+                await self.cancel_workflow_run(cancel_ctx, options)
 
     async def cancel_workflow_run(
         self,
         ctx: TemporalNexusCancelOperationContext,  # pyright: ignore[reportUnusedParameter]
-        workflow_id: str,
-    ):
-        """Cancels the workflow identified by workflow_id.
+        options: CancelWorkflowRunOptions,
+    ) -> None:
+        """Cancels the workflow backing the Nexus operation.
 
         .. warning::
            This API is experimental and unstable.
         """
-        workflow_handle = temporalio.nexus.client().get_workflow_handle(workflow_id)
+        workflow_handle = temporalio.nexus.client().get_workflow_handle(
+            options.workflow_id
+        )
         await workflow_handle.cancel()
 
 

tests/nexus/test_temporal_operation.py

@@ -205,10 +205,12 @@ async def start_operation(
 
             @override
             async def cancel_workflow_run(
-                self, ctx: nexus.TemporalNexusCancelOperationContext, workflow_id: str
+                self,
+                ctx: nexus.TemporalNexusCancelOperationContext,
+                options: nexus.CancelWorkflowRunOptions,
             ):
                 # get a handle to the workflow
-                handle = nexus.client().get_workflow_handle(workflow_id)
+                handle = nexus.client().get_workflow_handle(options.workflow_id)
 
                 # cancel the workflow
                 await handle.cancel()