Initial implementation #1

dandavison · 2025-04-02T19:16:28Z

Nexus Python SDK initial content.

For an overview of the user experience of implementing and calling Nexus handlers, see the Temporal sample, and tests in this PR.

cretz

Started adding some more comments here but started seeing a lot of past comments that still apply so unsure if ready for second round. Stopped at about src/nexus_rpc/nexusrpc/handler/_core.py but will pick back up when told ready for re-review.

cretz · 2025-06-25T13:34:30Z

.github/workflows/ci.yml

+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']


README.md

pyproject.toml

cretz · 2025-06-25T13:43:29Z

src/nexusrpc/_serializer.py

+    User provided keys are treated case-insensitively.
+    """
+
+    data: Optional[bytes] = None


Pedantic, but I don't think we should default to None, I think any instantiator of this should explicitly pass None if they have no data, but creating a Content should always required data IMO. Same for not having default stream on LazyValue constructor.

[Content] ... Pedantic, but I don't think we should default to None

Agree, done.

cretz · 2025-06-25T13:46:56Z

src/nexusrpc/types.py

IMO there aren't enough types here to deserve its own user-facing module. Just put InputT and OutputT in the nexusrpc module. The other ones don't really have any bounds/constraints, so there's not really any value in even having them be user facing, they can just be TypeVars where needed as needed (or shared across files, but don't need to be user facing).

cretz · 2025-06-25T14:00:03Z

src/nexusrpc/_util.py

@@ -0,0 +1,133 @@
+# See
+# https://docs.python.org/3/howto/annotations.html#accessing-the-annotations-dict-of-an-object-in-python-3-9-and-older


3.9 will be EOL by October. I'd be ok if we went ahead and said Python Nexus is 3.10+ and remove any 3.9 polyfills/workarounds

OK let's consider this for Preview; added to list

cretz · 2025-06-25T14:04:22Z

src/nexusrpc/handler/_common.py

+                          provided, the default behavior for the error type is used.
+        """
+        super().__init__(message)
+        self.__cause__ = cause


Hrmm, Python exceptions do not usually accept cause in constructors, they usually rely on the from clause during raise or in the rare case of needing to create the exception with a cause without a raise, users manually set __cause__ themselves after creation. Having it in constructor is confusing, especially in cases where it's unclear it may override.

Ack. I haven't resolved this yet.

cretz · 2025-06-25T14:09:29Z

src/nexusrpc/handler/_core.py

+
+    def __init__(
+        self,
+        user_service_handlers: Sequence[Any],


If this is a base handler, why accept these? What if I want to implement my base handler without any user service handlers? I think we should have a true abstract handler with no implementation defaults (i.e. basically an interface). Can we move all of this constructor stuff to the Handler class and get rid of this constructor? If we need some kind of shared utilities between Handler and SyncHandler so they can accept similar constructor arguments, that can make sense (or even a shared base class), but IMO we still need a no-impl/no-constructor interface for handlers.

cretz · 2025-06-25T14:14:39Z

src/nexusrpc/handler/_core.py

+# TODO(prerelease): we have a syncio module now housing the syncio version of
+# SyncOperationHandler. If we're retaining that then this (and an async version of
+# LazyValue) should go in there.
+class SyncioHandler(BaseHandler):


Is there a use case for this at this time? If so, we should eagerly check at construction that all calls on all operation handlers are not async def based. And we should require the executor on constructor.

Is there a use case for this at this time?

How else will a team using a non-async/await framework such as Django implement a Nexus server/worker?

cretz · 2025-06-25T14:15:24Z

src/nexusrpc/handler/_core.py

+            if not self.executor:
+                raise RuntimeError(
+                    "Operation start handler method is not an `async def` but "
+                    "no executor was provided to the Handler constructor. "
+                )


Can we detect this at construction time? Meaning can we check in the constructor that if an executor is not present, all calls on all operation handlers are async def?

This reverts commit 95f7874.

bergundy

Looks great!

bergundy · 2025-06-27T16:25:36Z

.github/workflows/ci.yml

+
+on:
+  push:
+    branches: [ main, v0 ]


Why v0? Is it to run CI in this PR? Will you remove it eventually?

bergundy · 2025-06-27T16:26:51Z

.github/workflows/ci.yml

+
+jobs:
+  test:
+    # TODO(preview): other platforms


Do you plan on addressing this or tracking in an issue?

bergundy · 2025-06-27T16:28:00Z

.github/workflows/ci.yml

+      - name: Build API docs
+        run: uv run pydoctor src/nexusrpc
+
+      - name: Deploy prod API docs


Is this set up? What domain are you planning to push to? I was planning on using GH docs for TS for now.

bergundy · 2025-06-27T16:28:54Z

.github/workflows/ci.yml

+        run: uv run pydoctor src/nexusrpc
+
+      - name: Deploy prod API docs
+        if: ${{ github.ref == 'refs/heads/main' }}


nit: we should publish docs on a stable release not on push to main. We made this mistake with Temporal SDKs, let's not repeat.

bergundy · 2025-06-27T16:29:29Z

CONTRIBUTING.md

+uv run pyright
+uv run mypy --check-untyped-defs .
+uv run ruff check --select I
+uv run ruff format --check


Can all of this be packaged in one command?

bergundy · 2025-06-27T23:27:06Z

src/nexusrpc/_types.py

+
+from typing import TypeVar
+
+# Operation input type


Can you make sure these comments are considered docstrings?

bergundy · 2025-06-27T23:28:35Z

src/nexusrpc/handler/_common.py

+    BAD_REQUEST = "BAD_REQUEST"
+    UNAUTHENTICATED = "UNAUTHENTICATED"
+    UNAUTHORIZED = "UNAUTHORIZED"
+    NOT_FOUND = "NOT_FOUND"
+    RESOURCE_EXHAUSTED = "RESOURCE_EXHAUSTED"
+    INTERNAL = "INTERNAL"
+    NOT_IMPLEMENTED = "NOT_IMPLEMENTED"
+    UNAVAILABLE = "UNAVAILABLE"
+    UPSTREAM_TIMEOUT = "UPSTREAM_TIMEOUT"


Worth documenting each of these error types.

bergundy · 2025-06-27T23:36:54Z

src/nexusrpc/handler/_core.py

+            )
+            if self.operation_handlers:
+                msg += f": {', '.join(sorted(self.operation_handlers.keys()))}"
+            msg += "."


Is it common to put periods at the end of error messages in Python? Doesn't seem like the standard library does this.

bergundy · 2025-06-27T23:38:22Z

src/nexusrpc/handler/_core.py

+# TODO(prerelease): Do we want to require users to create this wrapper? Two
+# alternatives:


I think just use the standard concurrent futures executor interface here.

bergundy · 2025-06-27T23:41:01Z

src/nexusrpc/handler/_decorators.py

+        )
+
+        method_name = get_callable_name(start)
+        operation_handler_factory.__nexus_operation__ = nexusrpc.Operation(


Why does the factory need to have this attribute?

dandavison force-pushed the v0 branch from e318efe to 4caff2e Compare April 2, 2025 20:39

dandavison force-pushed the v0 branch 2 times, most recently from a0db8c4 to 2733044 Compare April 22, 2025 20:52

dandavison force-pushed the v0 branch from d4c0e54 to fc5c234 Compare April 29, 2025 14:38

dandavison changed the title ~~Initial prototyping~~ Initial implementation May 8, 2025

dandavison force-pushed the v0 branch 3 times, most recently from 4c284df to 9bdf24d Compare May 27, 2025 20:13

dandavison force-pushed the v0 branch 4 times, most recently from fbb91b0 to 659557b Compare May 30, 2025 01:42

dandavison requested a review from Copilot May 30, 2025 01:44

This comment was marked as off-topic.

Sign in to view

nexus-rpc deleted a comment from Copilot AI May 30, 2025

dandavison force-pushed the v0 branch 6 times, most recently from 96f9be3 to 9711999 Compare June 9, 2025 20:58

dandavison marked this pull request as ready for review June 9, 2025 21:00

dandavison force-pushed the v0 branch 6 times, most recently from fa76eac to 706b354 Compare June 9, 2025 22:27

dandavison added 2 commits June 9, 2025 18:28

Initial content

fb231a0

Generate API docs

6e6a28a

dandavison added 2 commits June 24, 2025 23:39

Cleanup

5a88b85

Test all operation methods

a60cb3a

cretz reviewed Jun 25, 2025

View reviewed changes

dandavison added 7 commits June 25, 2025 13:50

Cleanup

964a99a

Cleanup

69c501d

Revert "Delete unused get_start_method types utility"

b6e792c

This reverts commit 95f7874.

New version of sync_operation decorator

a938cfd

Support name override, add overloads

ef3aeb9

Make sync_operation_handler support sync start methods

56f86fe

Fix callable instances

a6a2e97

dandavison force-pushed the v0 branch from 0928a43 to a6a2e97 Compare June 26, 2025 03:06

dandavison added 6 commits June 26, 2025 06:47

rename: @sync_operation

e4a8762

Clean up imports in tests

cf79d71

Remove @operation_handler from public API for now

0e2a28b

CI test on 3.9, 3.13, 3.14

32f9e55

Activate vercel publishing of apidocs

f87ee04

Start adding README content

0508c56

dandavison force-pushed the v0 branch from 9449f64 to 0508c56 Compare June 26, 2025 14:34

dandavison added 10 commits June 26, 2025 10:34

uv remove --group dev httpx

ed75834

Make Content.data required

4494e2a

Rename method: from_user_class -> from_class

5b2fc91

Relocate OperationError

280b8ab

Make dataclasses frozen

59f3f1b

Make OperationContext non-instantiatable

7eb03d5

Make dataclasses frozen=True

937511f

Make request ID required

42a1e34

Eliminate types.module

11d7d4e

Add FetchOperationResultContext timeout with stub implementation

56f8c23

dandavison force-pushed the v0 branch from e90bbb7 to 56f8c23 Compare June 27, 2025 01:06

bergundy reviewed Jun 27, 2025

View reviewed changes

		@@ -0,0 +1,133 @@
		# See
		# https://docs.python.org/3/howto/annotations.html#accessing-the-annotations-dict-of-an-object-in-python-3-9-and-older

		# TODO(prerelease): Do we want to require users to create this wrapper? Two
		# alternatives:

Initial implementation #1

Are you sure you want to change the base?

Initial implementation #1

Uh oh!

Conversation

dandavison commented Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as off-topic.

Uh oh!

cretz left a comment

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!

dandavison Jun 26, 2025 • 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!

dandavison Jun 26, 2025 • 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!

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!

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

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!

dandavison commented Apr 2, 2025 •

edited

Loading

dandavison Jun 26, 2025 •

edited

Loading

dandavison Jun 26, 2025 •

edited

Loading