Nexus RPC Python SDK

Common errors

• ModuleNotFoundError: No module named 'nexusrpc'

  cause The `nexus-rpc` library has not been installed, or there's an issue with the Python environment where it's not accessible.
  fix Ensure the library is installed using pip: `pip install nexus-rpc` or `uv add nexus-rpc`.

• nexusrpc.HandlerError

  cause This is a custom exception raised by the `nexus-rpc` framework to indicate errors that occur during the handling of a Nexus operation, intended to be reported back to the caller.
  fix Developers should catch `nexusrpc.HandlerError` in their handler implementations to gracefully manage and report operation failures, optionally specifying a `HandlerErrorType` and message for more context. Example: `raise nexusrpc.HandlerError("Invalid input", type=nexusrpc.HandlerErrorType.BAD_REQUEST)`.

• AttributeError: 'module' object has no attribute 'service'

  cause This error likely occurs when attempting to define a Nexus service without correctly importing or using the `@nexusrpc.service` decorator. The `service` attribute is expected to be part of the `nexusrpc` module for decorating service classes.
  fix Ensure that `nexusrpc` is imported and the service class is correctly decorated with `@nexusrpc.service`, like this: `import nexusrpc` followed by `@nexusrpc.service class MyNexusService: ...`.

• AttributeError: 'module' object has no attribute 'handler'

  cause This error occurs when trying to use decorators like `@nexusrpc.handler.service_handler` or `@nexusrpc.handler.sync_operation` without properly accessing the `handler` submodule within `nexusrpc`.
  fix Make sure you are explicitly importing or accessing the `handler` submodule for its decorators. For example: `from nexusrpc import handler` or by fully qualifying the name as shown in examples: `@nexusrpc.handler.service_handler(...)`.

Warnings

• breaking The nexus-rpc SDK is currently at an experimental release stage. Backwards-incompatible changes are anticipated until a stable release is announced.
  Fix: Monitor official releases and changelogs for breaking changes. Pin exact versions in your `requirements.txt` to prevent unexpected updates.
• gotcha The PyPI package name 'nexus-rpc' was previously used by an unrelated project. Ensure you are using the correct SDK for the Nexus synchronous RPC protocol from the `nexus-rpc` GitHub organization.
  Fix: Verify the project's origin and documentation (github.com/nexus-rpc/sdk-python) to confirm you are using the intended library.
• gotcha The SDK for the Nexus RPC protocol only provides components for implementing handlers. It does not include reference implementations for Nexus servers or clients.
  Fix: You will need to implement or integrate a Nexus server and client separately to utilize the defined services and handlers. If integrating with Temporal, refer to their Nexus documentation for server-side setup.

Install

• pip install nexus-rpc Install with pip

Imports

• nexusrpc

  import nexusrpc

• service

  from nexusrpc import service

• Operation

  from nexusrpc import Operation

• handler

  from nexusrpc import handler

Quickstart

This quickstart demonstrates how to define a Nexus service and implement a synchronous operation handler. It uses dataclasses for input and output types, decorates a class as a Nexus service, and then implements a service handler with a decorated synchronous operation.

from dataclasses import dataclass
import nexusrpc

@dataclass
class MyInput:
    name: str

@dataclass
class MyOutput:
    message: str

@nexusrpc.service
class MyNexusService:
    my_sync_operation: nexusrpc.Operation[MyInput, MyOutput]

@nexusrpc.handler.service_handler(service=MyNexusService)
class MyNexusServiceHandler:
    @nexusrpc.handler.sync_operation
    async def my_sync_operation(
        self, ctx: nexusrpc.handler.StartOperationContext, input: MyInput
    ) -> MyOutput:
        return MyOutput(message=f"Hello {input.name}!")

# In a real application, you would instantiate MyNexusServiceHandler
# and integrate it with your server/worker to process Nexus requests.
# For example:
# handler_instance = MyNexusServiceHandler()