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.

This reverts commit e83999b.

bergundy · 2025-06-30T18:05:52Z

pyproject.toml

+packages = ["src/nexusrpc"]
+
+[tool.pyright]
+include = ["src", "tests"]


Hmm... maybe this pattern started being adopted more, I have typically seen Python project not have an src directory.

bergundy · 2025-06-30T18:06:07Z

src/nexus_rpc/__init__.py

Clean this up?

Looks like this comment was made on a deleted file.

bergundy · 2025-06-30T18:07:40Z

src/nexusrpc/__init__.py

Wonder if we should be exporting handler here too so users can use nexusrpc.handler.service_handler directly without having to import handler separately.

I was thinking the same. I've done it.

bergundy · 2025-06-30T18:08:23Z

src/nexusrpc/__init__.py

+from ._serializer import Content as Content, LazyValue as LazyValue
+from ._service import (
+    Operation as Operation,
+    ServiceDefinition as ServiceDefinition,
+    service as service,
+)


Why do you need import as if you're not renaming the items?

OK so

(a) Type checkers complain if the imported name is unused. So this style is just how modern Python does it, and how the de-factor formatter ruff formats it.

(b) But you're right, I recently added __all__ collections of exported names to all __init__.pys, because the API docs needed it, and with that we no longer need the as stuff.

bergundy · 2025-06-30T18:23:03Z

src/nexusrpc/handler/_common.py

+
+    Includes information from the request."""
+
+    request_id: str


FTR, an empty request ID is not rejected by the server. This string may be empty.

bergundy · 2025-06-30T18:43:46Z

src/nexusrpc/syncio/handler/_core.py

+from nexusrpc.handler._core import BaseServiceCollectionHandler
+from nexusrpc.handler._util import get_start_method_input_and_output_type_annotations
+
+from ...handler._operation_handler import OperationHandler


Given that the OperationHandler works for both sync and async, this separate syncio module seems like overkill.

What arrangement do you prefer? We have the following components that at the moment have sync and asynv versions:

Handler

LazyValue

sync_operation

In any case, I think that what we should do is delete all of the above sync support, until we're sure how we want to present it. I'll do that in a follow-up PR.

To be clear for anyone else reading: when we "delete sync support", the SDK will continue to support user operation handlers with def methods (as long as an executor has been supplied).

bergundy

Added a few comments but AFAIC, there's nothing major.

cretz · 2025-07-01T20:25:41Z

src/nexusrpc/_serializer.py

+        ...
+
+
+class LazyValueT(Protocol):


But I thought we were removing sync form? At which point is there value here?

cretz · 2025-07-01T20:25:53Z

src/nexusrpc/_serializer.py

+    """Request or response data."""
+
+
+class Serializer(Protocol):


It's not incorrect, it's just too limiting and not common for these use cases. I think we should revisit this since it makes sense for serializer to be a base class one extends instead of duck-typed.

cretz · 2025-07-01T20:26:15Z

src/nexusrpc/_serializer.py

+        ...
+
+
+class LazyValueT(Protocol):


Yeah, I think my main problem was that this didn't make sense as a protocol

cretz · 2025-07-01T20:29:37Z

src/nexusrpc/_service.py

+            )
+        return defn
+
+    def _validation_errors(self) -> list[str]:


Can we get a general decision on operation-less Nexus service contracts and whether we generally believe they are valid? A dataclass with no fields may be valid, but a service with no calls may not be.

cretz · 2025-07-01T20:31:19Z

src/nexusrpc/_util.py

+    from nexusrpc.handler._operation_handler import OperationHandler
+
+
+def get_service_definition(


Concern about the name is different than concern about the placement. I think there's not a need to clutter the top-level API with a top-level function here. Whether we call this from_class or get_from_class or whatever I think is a secondary question (I don't see a from_whatever to be a constructor, but can be documented away).

cretz · 2025-07-01T20:38:30Z

src/nexusrpc/handler/_common.py

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


I think it's also a signal of intent as well (i.e. "this is always used as a base class")

cretz · 2025-07-01T20:41:28Z

src/nexusrpc/handler/_core.py

+        ...
+
+
+class BaseServiceCollectionHandler(AbstractHandler):


👍 Would definitely like to reduce class/abstraction count if we can

cretz · 2025-07-01T20:42:10Z

src/nexusrpc/handler/_core.py

+                        )
+            self.service_handlers[sh.service.name] = sh
+
+    async def start_operation(


👍 I trust the removal of the unused syncio stuff is being tracked

cretz · 2025-07-01T20:42:52Z

src/nexusrpc/handler/_decorators.py

+def service_handler(cls: Type[ServiceHandlerT]) -> Type[ServiceHandlerT]: ...
+
+
+# TODO(preview): allow service to be provided as positional argument?


I guess what I mean is why is service before * in the impl but after the * here?

cretz · 2025-07-01T20:47:31Z

src/nexusrpc/syncio/_serializer.py

+        self.headers = headers
+        self.stream = stream
+
+    def consume(self, as_type: Optional[Type[Any]] = None) -> Any:


A thought while we're here - arguably a sync implementation should allow async operations and provide an event loop to run them on via run_coroutine_threadsafe similar to how an executor is provided to go from async to sync.

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 3 commits June 30, 2025 13:27

Revert "TEMP: reduce GHA matrix"

95d821e

This reverts commit e83999b.

ServiceDefinitionT -> ServiceT

375c1f4

Docstrings

717bdbe

bergundy reviewed Jun 30, 2025

View reviewed changes

bergundy approved these changes Jun 30, 2025

View reviewed changes

Do not expose get_operation_factory

c439b88

dandavison force-pushed the v0 branch from 24d3b90 to c439b88 Compare June 30, 2025 19:29

dandavison added 17 commits June 30, 2025 15:31

Stope doing as imports

c9629c4

Docstring

84388d1

Make Content.data non-nullable

a48958c

Move content out of __init__.py

ba528f0

Import handler in nexusrpc

963d9c3

Delete spurious check

065faee

Failing test of enforcement of method name uniqueness

5430973

Enforce method name uniqueness and 1:1 between op_handler and op_defn

3ea58ff

Remove accidentally exposed utility function

5fa431a

Cleanup

56b0c6a

Add is_callable utility

72daeab

Support callable instances as operation methods

6f6e01a

Cleanup

79e08a1

Fix test assertion

e6e2b95

Skip test

901ac9b

Add no type annotations invalid usage test

d2db821

Fix CI test matrix

112c242

cretz reviewed Jul 1, 2025

View reviewed changes

Make OperationContext an ABC

84b288a

dandavison force-pushed the v0 branch from e22ef77 to 84b288a Compare July 1, 2025 21:46

Fix position of * in signature

00b7afa

		from nexusrpc.handler._operation_handler import OperationHandler


		def get_service_definition(

		def service_handler(cls: Type[ServiceHandlerT]) -> Type[ServiceHandlerT]: ...


		# TODO(preview): allow service to be provided as positional argument?

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!

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!

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