Add workflow.uuid7() (#1733)

* Add workflow.uuid7()

* Suppress unreachable-code warning on pre-3.14 type checks

---------

Co-authored-by: Tim Conley <tconley1428@gmail.com>

Author: ribhavjain

CHANGELOG.md

@@ -20,6 +20,14 @@ to include examples, links to docs, or any other relevant information.
 
 ### Added
 
+- `temporalio.workflow.uuid7()` generates a determinism-safe, time-sortable
+  UUIDv7 (RFC 9562) from workflow time and the workflow's deterministic random
+  generator, complementing the existing `workflow.uuid4()`
+  ([#1450](https://github.com/temporalio/sdk-python/issues/1450)). The
+  workflow sandbox now also restricts the non-deterministic `uuid.uuid7()`
+  added to the standard library in Python 3.14, matching the existing
+  `uuid.uuid1()`/`uuid.uuid4()` restrictions.
+
 ### Changed
 
 - `temporalio.contrib.pydantic` converters now reuse Pydantic type adapters

temporalio/worker/workflow_sandbox/_restrictions.py

@@ -769,7 +769,9 @@ def _public_callables(parent: Any, *, exclude: set[str] = set()) -> set[str]:
         "urllib": SandboxMatcher(
             children={"request": SandboxMatcher.all_uses},
         ),
-        "uuid": SandboxMatcher(use={"uuid1", "uuid4"}, only_runtime=True),
+        # uuid7 only exists in the stdlib on Python 3.14+; matching a
+        # nonexistent attribute is harmless on older versions
+        "uuid": SandboxMatcher(use={"uuid1", "uuid4", "uuid7"}, only_runtime=True),
         "webbrowser": SandboxMatcher.all_uses,
         "xmlrpc": SandboxMatcher.all_uses,
         "zipfile": SandboxMatcher(

temporalio/workflow/__init__.py

@@ -94,6 +94,7 @@
     upsert_memo,
     upsert_search_attributes,
     uuid4,
+    uuid7,
     wait_condition,
 )
 from ._definition import (
@@ -225,6 +226,7 @@
     "upsert_memo",
     "upsert_search_attributes",
     "uuid4",
+    "uuid7",
     "wait_condition",
     "DynamicWorkflowConfig",
     "defn",

temporalio/workflow/_context.py

@@ -65,6 +65,7 @@
     "upsert_memo",
     "upsert_search_attributes",
     "uuid4",
+    "uuid7",
     "wait_condition",
 ]
 
@@ -901,6 +902,33 @@ def uuid4() -> uuid.UUID:
     return uuid.UUID(bytes=random().getrandbits(16 * 8).to_bytes(16, "big"), version=4)
 
 
+def uuid7() -> uuid.UUID:
+    """Get a new, determinism-safe v7 UUID based on :py:func:`time_ns` and
+    :py:func:`random`.
+
+    Per RFC 9562, the UUID's leading 48 bits are the current workflow time as
+    milliseconds since the epoch, so UUIDs from successive workflow tasks sort
+    by creation time. The remaining 74 bits are random. UUIDs generated within
+    the same workflow task share the same workflow time and are not guaranteed
+    to be monotonically ordered with respect to one another.
+
+    Note, this UUID is not cryptographically safe and should not be used for
+    security purposes.
+
+    Returns:
+        A deterministically-seeded v7 UUID.
+    """
+    # uuid.UUID's version parameter only accepts 1-5 before Python 3.14, so
+    # the version and variant bits are set manually.
+    unix_ts_ms = (time_ns() // 1_000_000) & 0xFFFF_FFFF_FFFF
+    rand = random()
+    rand_a = rand.getrandbits(12)
+    rand_b = rand.getrandbits(62)
+    return uuid.UUID(
+        int=(unix_ts_ms << 80) | (0x7 << 76) | (rand_a << 64) | (0b10 << 62) | rand_b
+    )
+
+
 async def sleep(duration: float | timedelta, *, summary: str | None = None) -> None:
     """Sleep for the given duration.
 

tests/worker/test_workflow.py

@@ -3934,6 +3934,73 @@ async def test_workflow_uuid(client: Client):
         assert handle2_query_result == await handle2.query(UUIDWorkflow.result)
 
 
+@workflow.defn
+class UUID7Workflow:
+    def __init__(self) -> None:
+        self._result = "<unset>"
+        self._time_ms = -1
+
+    @workflow.run
+    async def run(self) -> None:
+        self._time_ms = workflow.time_ns() // 1_000_000
+        self._result = str(workflow.uuid7())
+
+    @workflow.query
+    def result(self) -> str:
+        return self._result
+
+    @workflow.query
+    def time_ms(self) -> int:
+        return self._time_ms
+
+
+async def test_workflow_uuid7(client: Client):
+    task_queue = str(uuid.uuid4())
+    async with new_worker(
+        client, UUID7Workflow, task_queue=task_queue, max_cached_workflows=0
+    ):
+        # Get two handle UUID results. Need to disable workflow cache since we
+        # restart the worker and don't want to pay the sticky queue penalty.
+        handle1 = await client.start_workflow(
+            UUID7Workflow.run, id=f"workflow-{uuid.uuid4()}", task_queue=task_queue
+        )
+        await handle1.result()
+        handle1_query_result = await handle1.query(UUID7Workflow.result)
+
+        handle2 = await client.start_workflow(
+            UUID7Workflow.run,
+            id=f"workflow-{uuid.uuid4()}",
+            task_queue=task_queue,
+        )
+        await handle2.result()
+        handle2_query_result = await handle2.query(UUID7Workflow.result)
+
+        # Confirm they aren't equal to each other but they are equal to retries
+        # of the same query
+        assert handle1_query_result != handle2_query_result
+        assert handle1_query_result == await handle1.query(UUID7Workflow.result)
+        assert handle2_query_result == await handle2.query(UUID7Workflow.result)
+
+        # Confirm RFC 9562 shape: version 7, RFC variant, and the leading 48
+        # bits are the workflow time in milliseconds at generation
+        for handle, query_result in (
+            (handle1, handle1_query_result),
+            (handle2, handle2_query_result),
+        ):
+            result_uuid = uuid.UUID(query_result)
+            assert result_uuid.version == 7
+            assert result_uuid.variant == uuid.RFC_4122
+            workflow_time_ms = await handle.query(UUID7Workflow.time_ms)
+            assert int(result_uuid) >> 80 == workflow_time_ms
+
+    # Now confirm those results are the same even on a new worker
+    async with new_worker(
+        client, UUID7Workflow, task_queue=task_queue, max_cached_workflows=0
+    ):
+        assert handle1_query_result == await handle1.query(UUID7Workflow.result)
+        assert handle2_query_result == await handle2.query(UUID7Workflow.result)
+
+
 @activity.defn(name="custom-name")
 class CallableClassActivity:
     def __init__(self, orig_field1: str) -> None:

tests/worker/workflow_sandbox/test_runner.py

@@ -197,6 +197,10 @@ async def test_workflow_sandbox_restrictions(client: Client):
         if sys.version_info < (3, 14):
             invalid_code_to_check.append("import os.path\nos.path.abspath('foo')")  # type: ignore[reportUnreachable]
 
+        # uuid7 was only added to the stdlib in 3.14
+        if sys.version_info >= (3, 14):
+            invalid_code_to_check.append("import uuid\nuuid.uuid7()")  # type: ignore[reportUnreachable]
+
         for code in invalid_code_to_check:
             with pytest.raises(WorkflowFailureError) as err:
                 await client.execute_workflow(