nexus-rpc · dandavison · Jul 2, 2025 · Jan 30, 2025 · Jun 9, 2025 · Jun 9, 2025
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  lint-test-docs:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.13', '3.14']
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv sync
+
+      - name: Lint and type check
+        run: uv run poe lint
+
+      - name: Run tests
+        run: |
+          uv run pytest --cov=src --cov-report=html:coverage_html_report
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html-report-${{ matrix.os }}-${{ matrix.python-version }}
+          path: coverage_html_report/
+
+  deploy-docs:
+    runs-on: ubuntu-latest
+    needs: lint-test-docs
+    # TODO(preview): deploy on releases only
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.9'
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Build API docs
+        run: uv run poe docs
+
+      - name: Upload docs to GitHub Pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: apidocs
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -1,10 +1,5 @@
-# Python-generated files
-__pycache__/
-*.py[oc]
-build/
-dist/
-wheels/
-*.egg-info
-
-# Virtual environments
+__pycache__
 .venv
+apidocs
+dist
+docs
diff --git a/.python-version b/.python-version
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,22 @@
+We will welcome contributions once the SDK has reached a stable release.
+
+### Type-check and lint
+
+```sh
+uv run poe lint
+```
+
+### Format
+```
+uv run poe format
+```
+
+### Test
+```
+uv run pytest
+```
+
+### API docs
+```
+uv run poe docs
+```
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Temporal Technologies Inc. All Rights Reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,80 @@
+# Nexus Python SDK
+
+⚠️  **This SDK is currently at an experimental release stage. Backwards-incompatible changes are anticipated until a stable release is announced.** ⚠️
+
+## What is Nexus?
+
+[Nexus](https://github.com/nexus-rpc/) is a synchronous RPC protocol. Arbitrary duration operations are modeled on top of
+a set of pre-defined synchronous RPCs.
+
+A Nexus caller calls a handler. The handler may respond inline (synchronous response) or
+return a token referencing the ongoing operation (asynchronous response). The caller can
+cancel an asynchronous operation, check for its outcome, or fetch its current state. The
+caller can also specify a callback URL, which the handler uses to deliver the result of
+an asynchronous operation when it is ready.
+
+## Installation
+
+```
+uv add nexus-rpc
+```
+or
+```
+pip install nexus-rpc
+```
+
+## Usage
+
+The SDK currently supports two use cases:
+
+1. As an end user, defining Nexus services and operations.
+
+2. Implementing a Nexus handler that can accept and respond to incoming Nexus requests, dispatching to the corresponding user-defined Nexus operation.
+
+The handler in (2) would form part of a server or worker that processes Nexus requests; the SDK does not yet provide reference implementations of these, or of a Nexus client.
+
+### Defining Nexus services and operations
+
+```python
+from dataclasses import dataclass
+
+import nexusrpc
+from nexusrpc.handler import StartOperationContext, service_handler, sync_operation
+
+
+@dataclass
+class MyInput:
+    name: str
+
+
+@dataclass
+class MyOutput:
+    message: str
+
+
+@nexusrpc.service
+class MyNexusService:
+    my_sync_operation: nexusrpc.Operation[MyInput, MyOutput]
+
+
+@service_handler(service=MyNexusService)
+class MyNexusServiceHandler:
+    # You can create an __init__ method accepting what is needed by your operation
+    # handlers to handle requests. You will typically instantiate your service handler class
+    # when starting your Nexus server/worker.
+
+    # This is a Nexus operation that responds synchronously to all requests. That means
+    # that the `start` method returns the final operation result.
+    #
+    # Sync operations are free to make arbitrary network calls.
+    @sync_operation
+    async def my_sync_operation(
+        self, ctx: StartOperationContext, input: MyInput
+    ) -> MyOutput:
+        return MyOutput(message=f"Hello {input.name}!")
+```
+
+
+## Note regarding version number
+The nexus-rpc name in PyPi was originally held by an unrelated project. Despite the
+version being at `v1.x` it is currently at an experimental release stage.
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,14 +1,67 @@
 [project]
 name = "nexus-rpc"
-version = "0.1.0"
+# The nexus-rpc name in PyPi was originally held by an unrelated project that reached
+# 1.0.1 and was abandoned in 2018. The name was inherited by the Python Nexus SDK in
+# 2025 and version numbering started from 1.1.0. Despite the version number, this is an
+# experimental release and backwards-incompatible changes are anticipated until a GA
+# release is announced.
+version = "1.1.0"
 description = "Nexus Python SDK"
 readme = "README.md"
 authors = [
-    { name = "Dan Davison", email = "dandavison7@gmail.com" }
+    { name = "Temporal Technologies", email = "sdk@temporal.io" }
+]
+requires-python = ">=3.9"
+dependencies = [
+    "typing-extensions>=4.12.2",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.15.0",
+    "poethepoet>=0.35.0",
+    "pydoctor>=25.4.0",
+    "pyright>=1.1.402",
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.26.0",
+    "pytest-cov>=6.1.1",
+    "pytest-pretty>=1.3.0",
+    "ruff>=0.12.0",
 ]
-requires-python = ">=3.13"
-dependencies = []
 
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nexusrpc"]
+
+[tool.poe.tasks]
+lint = [
+  {cmd = "uv run pyright src"},
+  {cmd = "uv run mypy --check-untyped-defs src"},
+  {cmd = "uv run ruff check --select I"},
+  {cmd = "uv run ruff format --check"},
+]
+format = [
+  {cmd = "uv run ruff check --select I --fix"},
+  {cmd = "uv run ruff format"},
+]
+docs = [
+  {cmd = "uv run pydoctor src/nexusrpc"},
+]
+
+[tool.pyright]
+include = ["src", "tests"]
+
+[tool.mypy]
+disable_error_code = ["empty-body"]
+
+[tool.ruff]
+target-version = "py39"
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+
+[tool.pydoctor]
+docformat = "google"
diff --git a/src/nexus_rpc/__init__.py b/src/nexus_rpc/__init__.py
diff --git a/src/nexusrpc/__init__.py b/src/nexusrpc/__init__.py
@@ -0,0 +1,57 @@
+"""
+nexusrpc is a library for building Nexus handlers.
+
+See https://github.com/nexus-rpc and https://github.com/nexus-rpc/api/blob/main/SPEC.md.
+
+Nexus is a synchronous RPC protocol. Arbitrary duration operations are modeled on top of
+a set of pre-defined synchronous RPCs.
+
+A Nexus caller calls a handler. The handler may respond inline (synchronous response) or
+return a token referencing the ongoing operation (asynchronous response). The caller can
+cancel an asynchronous operation, check for its outcome, or fetch its current state. The
+caller can also specify a callback URL, which the handler uses to deliver the result of
+an asynchronous operation when it is ready.
+"""
+
+from __future__ import annotations
+
+from . import handler
+from ._common import (
+    HandlerError,
+    HandlerErrorType,
+    InputT,
+    Link,
+    OperationError,
+    OperationErrorState,
+    OperationInfo,
+    OperationState,
+    OutputT,
+)
+from ._serializer import Content, LazyValue
+from ._service import Operation, ServiceDefinition, service
+from ._util import (
+    get_operation_definition,
+    get_service_definition,
+    set_operation_definition,
+)
+
+__all__ = [
+    "Content",
+    "get_operation_definition",
+    "get_service_definition",
+    "handler",
+    "HandlerError",
+    "HandlerErrorType",
+    "InputT",
+    "LazyValue",
+    "Link",
+    "Operation",
+    "OperationError",
+    "OperationErrorState",
+    "OperationInfo",
+    "OperationState",
+    "OutputT",
+    "service",
+    "ServiceDefinition",
+    "set_operation_definition",
+]