NEXUS-484: Support UpdateWorkflow as a Nexus Operation by mavemuri · Pull Request #1631 · temporalio/sdk-python

mavemuri · 2026-07-02T04:02:16Z

What was changed

Adds support for UpdateWorkflow as a Nexus operation

Why?

Part of effort to expose all Temporal primitives via Nexus operations

Checklist

Closes
NEXUS-484
How was this tested:

added integration test

Any docs updates needed?

CLAassistant · 2026-07-02T04:02:23Z

All committers have signed the CLA.

mavemuri · 2026-07-02T20:02:00Z

+        result = await wf_handle.result()
+        assert result == "Updated workflow status from Pending to Created"
+
+        # await assert_event_subsequence(


TODO:

check why this is flaky on ubuntu-arm/windows

verify links are present

check resp is sync on the retried update below

Probably obvious, but just to note we should try to match the test coverage we have in Go

Quinn-With-Two-Ns · 2026-07-15T21:24:04Z

+        result_type: type | None = None,
+        rpc_metadata: Mapping[str, str | bytes] = {},
+        rpc_timeout: timedelta | None = None,
+        # run_id: str | None = None,


Why are these commented out

wasnt sure if they were required at the time, fixed it

Quinn-With-Two-Ns · 2026-07-15T21:24:55Z



+@dataclass(frozen=True)
+class CancelUpdateWorkflowOptions:


Missing run ID

VegetarianOrc · 2026-07-16T20:31:05Z

+        if run_id == None:
+            run_id = self._run_id
+        if first_execution_run_id == None:
+            first_execution_run_id = self.first_execution_run_id
+


If we decide to keep this, let's make sure to use is None

Suggested change

if run_id == None:

run_id = self._run_id

if first_execution_run_id == None:

first_execution_run_id = self.first_execution_run_id

if run_id is None:

run_id = self._run_id

if first_execution_run_id is None:

first_execution_run_id = self.first_execution_run_id

VegetarianOrc · 2026-07-16T20:47:15Z

+        arg: Any = temporalio.common._arg_unset,
+        *,
+        args: Sequence[Any] = [],
+        id: str | None = None,


IMO we should consider naming this update_id to more clearly differentiate between workflow_id and the other IDs necessary.

The current code seems to be using "id" as the defacto operation-relevant unique ID - eg. start_workflow uses "id" for workflowID - this is the case for the primitive start_update/etc as well -

sdk-python/temporalio/client/_workflow.py

Line 923 in c6386e9

id: ID of the update. If not set, the default is a new UUID.

Was trying to follow that but explicit does make sense. It might look inconsistent if update calls out specific and start_workflow doesnt- because that part is already solidified/shipped iiuc

I agree with changing it update_id - because update has both workflow_id and update_id - but just not sure because of this

VegetarianOrc · 2026-07-16T20:48:05Z

+    # draft-review: check why run_id and first_execution_run_id are not used
+    # for update workflow in python sdk


These are sourced from the WorkflowHandle rather than passed as arguments.

VegetarianOrc · 2026-07-16T20:52:42Z

+                first_execution_run_id=first_execution_run_id,
+            )
+            # If the update has already completed, return the result synchronously
+            # This is in-line with the Go implementation as well


Suggested change

# This is in-line with the Go implementation as well

VegetarianOrc · 2026-07-16T20:53:36Z

+        run_id: str | None = None,
+        first_execution_run_id: str | None = None,


As mentioned in other comments, I think we should remove these and always use self._run_id and self._first_execution_run_id

VegetarianOrc · 2026-07-16T20:58:36Z

+        nexus_handle: UpdateHandle[Any] = (
+            UpdateHandle._unsafe_from_client_workflow_update_handle(update_handle)
+        )


I know the workflow variant uses a WorkflowHandle here, but I'm not sure it's necessary. I think we should remove the UpdateHandle and just contruct the appropriate OperationToken here.

Makes sense- will just re-generate from the handle there

VegetarianOrc · 2026-07-16T21:01:39Z

+    # draft-review: maybe just move it inline, no need for a function just to error out
+    # check after review in case theres some other way to override/supply custom cancels


The way to customize cancellation is to inherit from TemporalOperationHandler and override these methods. So we'll either need to rework how that's done or leave these methods in place.

VegetarianOrc · 2026-07-20T17:27:44Z

+                first_execution_run_id=first_execution_run_id,
+            )
+            # If the update has already completed, return the result synchronously
+            if update_handle._known_outcome is not None:


If this case happens should we clear the flag set in _reserve_async_start() that prevents 2 async operations from being triggered by the client? Thinking through it, it probably makes sense to just always leave the flag set otherwise it could feel a little non-deterministic, but thought I'd pose the question for others to also consider.

Agree with leaving as-is - how it ended - sync/async- isnt strictly related to how it started - and its always starts async because we only support wait for Accepted
Also brought up in this PR discussion - temporalio/sdk-java#2945 (comment) - this is consistent there too

VegetarianOrc

LGTM! One question and one double checking for if the new UpdateHandle is used.

VegetarianOrc · 2026-07-20T17:36:03Z

+@dataclass(frozen=True)
+class UpdateHandle(Generic[OutputT]):
+    """A handle to a workflow update that is backing a Nexus operation.


I think this should be removed now? Is it used somewhere?

Missed it, will remove

tconley1428 · 2026-07-21T16:23:39Z

    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


I don't understand the comment. "Nexus operation backed updates" sounds like the update is running as a nexus operation or something. This is just the nexus operation invoking an update, right?

Yes thats right

Makes sense, will update and clarify that this is a workflow updates exposed as Nexus ops

tconley1428 · 2026-07-21T18:35:48Z

+        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.


I don't quite follow this guy either. How would a user implement this in a way that we can't by edfault?

The issue is that any accepted update cannot be cancelled anymore by the server. To work around it, the user would have to add some app-specific code that is aware of the update implementation to cancel it - like sending some term/etc to the update handler. Because of this, the user would have to override themselves (and as there cannot be a default "cancel" for update, raise this error instead)

I would elaborate just a bit that the custom implementation would need to cancel in some way outside temporal.

mavemuri force-pushed the mavemuri/update-nexus-op branch 6 times, most recently from a913bdd to 79d24c1 Compare July 2, 2026 18:52

mavemuri commented Jul 2, 2026

View reviewed changes

mavemuri force-pushed the mavemuri/update-nexus-op branch 2 times, most recently from ecc3c9e to e38becf Compare July 13, 2026 20:00

Quinn-With-Two-Ns reviewed Jul 15, 2026

View reviewed changes

mavemuri force-pushed the mavemuri/update-nexus-op branch 6 times, most recently from d8db6d8 to 351568c Compare July 16, 2026 20:03

VegetarianOrc reviewed Jul 16, 2026

View reviewed changes

mavemuri force-pushed the mavemuri/update-nexus-op branch 8 times, most recently from 83ed716 to a750f5f Compare July 17, 2026 05:24

mavemuri marked this pull request as ready for review July 17, 2026 16:17

mavemuri requested a review from a team as a code owner July 17, 2026 16:17

mavemuri force-pushed the mavemuri/update-nexus-op branch from a750f5f to 1d14414 Compare July 17, 2026 22:22

mavemuri requested review from Quinn-With-Two-Ns and VegetarianOrc July 17, 2026 22:57

VegetarianOrc reviewed Jul 20, 2026

View reviewed changes

VegetarianOrc approved these changes Jul 20, 2026

View reviewed changes

mavemuri force-pushed the mavemuri/update-nexus-op branch from 1d14414 to aa738a4 Compare July 20, 2026 20:39

mavemuri added 2 commits July 20, 2026 13:39

NEXUS-484: Add support for workflow update Nexus operations

852e955

address comments, cleanup run_id, extend tests

5a61843

mavemuri force-pushed the mavemuri/update-nexus-op branch from aa738a4 to 5a61843 Compare July 20, 2026 20:39

tconley1428 reviewed Jul 21, 2026

View reviewed changes

tconley1428 approved these changes Jul 21, 2026

View reviewed changes

address comments 2, fix docstrings, clarify signatures and errors

6c50143

mavemuri force-pushed the mavemuri/update-nexus-op branch from 86eba03 to 6c50143 Compare July 21, 2026 23:39

mavemuri merged commit 29e0c51 into main Jul 22, 2026
30 of 31 checks passed

mavemuri deleted the mavemuri/update-nexus-op branch July 22, 2026 00:23

		# draft-review: check why run_id and first_execution_run_id are not used
		# for update workflow in python sdk

		run_id: str \| None = None,
		first_execution_run_id: str \| None = None,

		# draft-review: maybe just move it inline, no need for a function just to error out
		# check after review in case theres some other way to override/supply custom cancels



		@dataclass(frozen=True)
		class CancelUpdateWorkflowOptions:

Uh oh!

Conversation

mavemuri commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What was changed

Why?

Checklist

Uh oh!

CLAassistant commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mavemuri Jul 2, 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!

mavemuri Jul 16, 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!

Uh oh!

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!

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!

Choose a reason for hiding this comment

Uh oh!

VegetarianOrc 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!

Choose a reason for hiding this comment

Uh oh!

mavemuri Jul 21, 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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mavemuri commented Jul 2, 2026 •

edited

Loading

CLAassistant commented Jul 2, 2026 •

edited

Loading

mavemuri Jul 2, 2026 •

edited

Loading

mavemuri Jul 16, 2026 •

edited

Loading

mavemuri Jul 21, 2026 •

edited

Loading