Add Temporal Operation Handler by VegetarianOrc · Pull Request #1503 · temporalio/sdk-python

VegetarianOrc · 2026-05-07T15:50:21Z

What was changed

Added support for Temporal-backed Nexus operation handlers.

This introduces @temporalio.nexus.temporal_operation, TemporalNexusClient, and TemporalOperationResult, allowing Nexus operation handlers to either return a synchronous result or start a Temporal workflow as the async backing operation. The branch also adds token parsing support for generic operation tokens, cancellation support for Temporal-backed workflow operations, Nexus workflow client overloads for the new operation shape, and focused runtime/type coverage.

Why?

This gives Nexus operation handlers a first-class way to interact with Temporal while preserving Nexus async operation semantics, workflow linking/callback behavior, cancellation handling, and typed workflow-start ergonomics.

Checklist

How was this tested:
- Existing tests
- Added type tests
- Added tests for temporal operation
Any docs updates needed?

Yes. The Nexus docs should cover @temporalio.nexus.temporal_operation, TemporalNexusClient.start_workflow,
TemporalOperationResult.sync, and async workflow-backed operation behavior.

Evanthx

Found a few nitpicks!

VegetarianOrc · 2026-05-14T16:53:46Z

+        for index, (param_type, expected_param_type) in enumerate(
+            zip(param_types, expected_param_types), start=1
+        ):
+            if not _is_subclass(expected_param_type, param_type):


I've swapped expected_param_type and param_type in this check here. Parameters should be contravariant (e.g. you could provide a function that accepts nexusrpc.StartOperationContext) but the previous direction was covariance (e.g. you could provide a function that accepts a child of WorkflowRunOperationContext).

In the covariant case, the type provided at runtime will never fulfill the decorated function's requirement of the more specific type. Type checkers already prevent this, but bug was that the warning below would not trigger at runtime so users that don't type check would not receive the warning.

In the contravariant case, the type provided at runtime will fulfill the decorated function's requirement of the less specific type.

The new tests in test_handler_operation_definitions.py demonstrate both paths and assert that the warning is or is not delivered as appropriate.

Rename the Temporal operation start context to TemporalNexusStartOperationContext and add TemporalNexusCancelOperationContext with access to the worker client. Make TemporalNexusOperationHandler a public abstract base with overrideable start_operation and cancel_workflow_run hooks, while keeping the decorator-backed implementation private. Update type annotations, exports, and tests, including coverage for custom Temporal operation cancellation.

VegetarianOrc · 2026-05-22T22:50:58Z

+        class CustomCancelNexusOpHandler(
+            nexus.TemporalNexusOperationHandler[str, None]
+        ):
+            @override
+            async def start_operation(
+                self,
+                ctx: nexus.TemporalNexusStartOperationContext,
+                client: nexus.TemporalNexusClient,
+                input: str,
+            ) -> nexus.TemporalOperationResult[None]:
+                result = await client.start_workflow(BlockingWorkflow.run, id=input)
+                event.set()
+                return result
+
+            @override
+            async def cancel_workflow_run(
+                self, ctx: nexus.TemporalNexusCancelOperationContext, workflow_id: str
+            ):
+                # get a handle to the workflow
+                handle = ctx.client.get_workflow_handle(workflow_id)
+
+                # cancel the workflow
+                await handle.cancel()
+
+        return CustomCancelNexusOpHandler()


Added this test to demonstrate how users can customize cancellation.

VegetarianOrc · 2026-05-22T22:53:45Z

    await client_workflow_handle.cancel(**kwargs)
+
+
+class TemporalNexusOperationHandler(OperationHandler[InputT, OutputT], ABC):


Base class is ABC to allow customization of cancellation and require implementors to override start_operation. The decorator uses the concrete internal implementation _TemporalNexusOperationHandler to invoke the decorated method.

… to prevent users from instantiating.

Evanthx

Nothing major, just some nitpicks!

Evanthx · 2026-05-23T00:15:13Z

+        namespace = token_details.get("ns")
+        if not isinstance(namespace, str) or not namespace:
+            raise TypeError(
+                f"invalid token: expected namespace to be a non-empty string, got {type(namespace)}"


If namespace is an empty string, this is going to be a weird error message - it'll say "expected namespace to be non-empty string, got string".

There is also a comment above in token.py saying "Allow empty string for ns" - is it allowed then? Seems like that comment or this check should change? (I noticed that this time after a prior comment from the last code review!)

Good call on the error message, I didn't quite realize that! Also good call on the conflicting behavior. I got overzealous with validation here. I've changed the namespace logic to reflect what was previously supported so that should clear up both issues!

Evanthx · 2026-05-23T00:27:36Z

+    """
+
+    value: _ResultT | object = temporalio.common._arg_unset
+    token: str | None = None


Just out of pure paranoia ... should you add a check to make sure no one calls TemporalOperationResult(token=None)? (or async_token with a None value?) It looks like that will work, then will fail with a runtime error below in _to_nexus_result if I read this right. Either way, seems worth validating the inputs in the constructor.

Also you have a constructor and then it looks like the desire is that the two class methods call the constructor? In Python, can you hide the constructor from the user to avoid confusion? If we don't want them to call it, then it's nice if it's not there to be called. But that is very much just a nitpick.

You can't truly hide a constructor in Python. You can do some kinda gross things to do it, but IMO it's not worth it.

I have added a __post_init__ implementation to validate that it's been constructed in an expected state to help out with that. Now regardless of how it is constructed, it will assert that it has exactly one of value & token, and if it has a token that it's a non-empty string.

…ior logic of accepting empty strings

tconley1428 · 2026-05-28T16:35:38Z

+        return self._temporal_context.client
+
+
+class TemporalNexusCancelOperationContext(CancelOperationContext):


I think these can just be aliases.

I swapped back to classes for those contexts after doing some experimentation. The reasons were largely around runtime type checking and printing the type of them that leaked the nexusrpc type rather than using the named alias.

The extra functionality that was just exposing metric meter and client have been removed from them though to avoid duplicating access patterns.

…xt to be type aliases. Remove overly cautious _is_subclass helper. Add typedef for TemporalNexusOperationStartHandlerFunc to improve readability

…hecking concerns

…against new options

VegetarianOrc force-pushed the amazzeo/temporal-nexus-operation-handler branch from 26c52b8 to b0dd232 Compare May 11, 2026 17:29

VegetarianOrc marked this pull request as ready for review May 12, 2026 21:44

VegetarianOrc requested a review from a team as a code owner May 12, 2026 21:44

VegetarianOrc requested review from Evanthx and Quinn-With-Two-Ns May 12, 2026 21:45

Evanthx reviewed May 13, 2026

View reviewed changes

VegetarianOrc requested a review from Evanthx May 13, 2026 19:30

Quinn-With-Two-Ns reviewed May 13, 2026

View reviewed changes

Comment thread temporalio/workflow.py Outdated

Quinn-With-Two-Ns reviewed May 13, 2026

View reviewed changes

Comment thread tests/nexus/test_temporal_operation.py Outdated

VegetarianOrc commented May 14, 2026

View reviewed changes

VegetarianOrc requested a review from Quinn-With-Two-Ns May 14, 2026 17:01

VegetarianOrc added 6 commits May 21, 2026 11:50

Narrow overloads on the sano client.

6941750

remove result_type params for overloads that don't need them

fc95b99

Add Temporal Nexus operation handler

9454188

Add overloads to sano client and increase type test coverage

6cabb13

Merge branch 'main' into amazzeo/temporal-nexus-operation-handler

d04eed5

VegetarianOrc force-pushed the amazzeo/temporal-nexus-operation-handler branch from 57af53b to eb3c560 Compare May 22, 2026 22:44

Merge branch 'main' into amazzeo/temporal-nexus-operation-handler

1341843

VegetarianOrc commented May 22, 2026

View reviewed changes

VegetarianOrc added 2 commits May 22, 2026 16:06

Add time-skippping check in test that leverages sano

e8905f3

Address claude/codex review suggestions. Make TemporalNexusClient ABC…

16f2af1

… to prevent users from instantiating.

Evanthx approved these changes May 23, 2026

View reviewed changes

VegetarianOrc added 3 commits May 26, 2026 09:24

Add tests for valid token forms. Update namespace check to reflect pr…

4d1bd5d

…ior logic of accepting empty strings

Add validation for TemporalOperationResult construction

a842673

Add docstring to __post_init__

bded883

VegetarianOrc requested review from THardy98 and tconley1428 May 26, 2026 18:07

Merge branch 'main' into amazzeo/temporal-nexus-operation-handler

b9c7eb5

run formatter

3a38a3f

Quinn-With-Two-Ns approved these changes May 27, 2026

View reviewed changes

Merge branch 'main' into amazzeo/temporal-nexus-operation-handler

a172b56

tconley1428 reviewed May 28, 2026

View reviewed changes

Comment thread temporalio/nexus/_decorators.py Outdated

tconley1428 reviewed May 28, 2026

View reviewed changes

Comment thread temporalio/nexus/_util.py Outdated

tconley1428 approved these changes May 28, 2026

View reviewed changes

VegetarianOrc added 6 commits May 28, 2026 10:57

Address PR feedback. Change TemporalNexus[Start|Cancel]OperationConte…

972f25b

…xt to be type aliases. Remove overly cautious _is_subclass helper. Add typedef for TemporalNexusOperationStartHandlerFunc to improve readability

Remove leftover commented code

ff7c0b8

Swap type aliases back to classes to avoid printing or runtime type c…

e687fc6

…hecking concerns

move to an options dataclass for cancel_workflow_run to future proof …

589e39b

…against new options

Merge branch 'main' into amazzeo/temporal-nexus-operation-handler

c166e08

clean up a docstring

19b331f

		await client_workflow_handle.cancel(**kwargs)


		class TemporalNexusOperationHandler(OperationHandler[InputT, OutputT], ABC):

		return self._temporal_context.client


		class TemporalNexusCancelOperationContext(CancelOperationContext):

Conversation

VegetarianOrc commented May 7, 2026

What was changed

Why?

Checklist

Uh oh!

Evanthx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

VegetarianOrc May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Evanthx left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

VegetarianOrc May 14, 2026 •

edited

Loading