durable-actors 0.5.5__tar.gz

durable_actors-0.5.5/.gitignore

@@ -0,0 +1,22 @@
+node_modules/
+sdk/node_modules/
+sdk/dist/
+sdk/.test-dist/
+packages/*/dist/
+sdk/src/generated/
+target/
+dist-runtime/
+.durable-actors/
+.artifacts/
+.env
+.env.*
+!.env.example
+.DS_Store
+Thumbs.db
+
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+sdk-python/dist/

durable_actors-0.5.5/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Terse
+
+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.

durable_actors-0.5.5/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: durable-actors
+Version: 0.5.5
+Summary: Typed Python durable actors and generated clients
+Project-URL: Repository, https://github.com/TerseAI/durable-actors
+Project-URL: Documentation, https://github.com/TerseAI/durable-actors/blob/main/docs/reference/python.md
+License-Expression: MIT
+License-File: LICENSE.md
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: jsonschema<5,>=4.23
+Requires-Dist: packaging<27,>=24
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: typing-extensions<5,>=4.12
+Requires-Dist: websockets<17,>=15
+Provides-Extra: codegen
+Requires-Dist: datamodel-code-generator<0.84,>=0.83; extra == 'codegen'
+Requires-Dist: mypy<2,>=1.15; extra == 'codegen'
+Requires-Dist: pip<27,>=25; extra == 'codegen'
+Description-Content-Type: text/markdown
+
+# Little Actors for Python
+
+Define durable actors in Python and generate typed Python clients. Python 3.11+ is supported. Actor state, placement, routing, and WebSocket delivery use the same Rust runtime as the TypeScript SDK.
+
+```sh
+pnpm dlx durable-actors init my-actors --template python
+cd my-actors
+pnpm install
+uv sync
+pnpm exec durable-actors dev
+```
+
+The shared TypeScript CLI manages development, generation, and Python type checking. It selects the project's `.venv` (or the active environment); `DURABLE_ACTORS_PYTHON` overrides the interpreter. Install Node.js 22+, Python 3.11+, and uv. The CLI downloads the matching native runtime on macOS and Linux. When developing this repository, set `DURABLE_ACTORS_BINARY` to an absolute path to your `cargo build --locked` executable.
+
+## Define actors
+
+```python
+from pydantic import BaseModel
+from durable_actors import Actor, emitted, ephemeral
+
+class Message(BaseModel):
+    text: str
+
+class Chat(Actor):
+    count: int = 0
+    messages: list[Message] = emitted(default_factory=list)
+    busy: bool = ephemeral(False)
+
+    def append(self, message: Message) -> list[Message]:
+        self.messages.append(message)
+        return self.messages
+```
+
+Public `def` methods become synchronous RPCs. Annotated fields persist by default. `emitted()` persists a field and broadcasts its saved changes; `ephemeral()` keeps a field temporary. Mutable defaults are copied for each actor, and both helpers accept `default_factory` for values constructed on activation. Use `ephemeral(default_factory=...)` for locks, caches, and service clients, and `ClassVar` for class constants. Classes extend `Actor` directly and use field defaults instead of constructors. Prefix helper methods with `_`. Synchronous handlers run on a worker thread, with calls serialized per actor. Socket hooks can also use ordinary `def`; `self.get_connections()` returns typed sockets.
+
+Add `@reentrant` (imported from `durable_actors`) to a `def` method to let other invocations enter before it finishes. Synchronous reentrant handlers overlap on worker threads; coordinate shared mutations and keep blocking I/O outside shared locks. Ordinary calls still serialize with each other. As in TypeScript, enabling reentrancy disables error rollback for the entire actor class. See the [execution semantics](../docs/reference/python.md#execution-and-failures) for details.
+
+## Generate and use a client
+
+With the actor server running, generate clients in your application:
+
+```sh
+pnpm add -D durable-actors
+uv add 'durable-actors[codegen]'
+pnpm exec durable-actors generate --out-dir generated
+```
+
+You can also generate directly from a trusted source entrypoint:
+
+```sh
+pnpm exec durable-actors generate src/actors.py --out-dir generated
+```
+
+```python
+from generated import actors
+
+chat = actors.Chat.get("lobby")
+messages: actors.Chat.Methods.append.Result = chat.append(actors.Chat.Message(text="hello"))
+print(messages[0].text)
+```
+
+The CLI runs strict mypy on local actor definitions before generation and on the generated package afterward. `dev` checks definitions before startup and every reload; an invalid edit leaves the previous code running.
+
+Generated RPC methods return typed values directly. The SDK creates a shared HTTP client when needed, reads configuration from the environment, and closes its connection pool at process exit. You only need the actor ID.
+
+The generated package exposes `actors`, matching the TypeScript client namespace. Use `actors.Chat.get(id)` for a handle, `actors.Chat.Stub` for its type, and `actors.Chat.Methods.append.Args` / `.Result` for method types. Socket types live at `actors.Chat.Metadata`, `.Incoming`, `.Outgoing`, and `.State`; concrete models such as `actors.Chat.Message` are also available there. The package includes docstrings, independent Pydantic models, and `py.typed`. Consumers need only `durable-actors`, not the actor project or the code generator. Regenerate after changing the actor contract, and include the generated package in your application's type checks.
+
+Typing uses inline annotations and the [PEP 561](https://peps.python.org/pep-0561/) package marker. Both mypy and Pyright check the SDK and generated clients. Pydantic validates inputs, outputs, and persisted state at runtime. Python annotations remain ordinary annotations: `chat.append(42)` is rejected by a type checker and by runtime validation.
+
+## Subscribe to state
+
+Actors with emitted fields have a typed `subscribe` method:
+
+```python
+chat = actors.Chat.get("lobby")
+subscription = chat.subscribe(lambda state: print(state.messages))
+chat.append(actors.Chat.Message(text="hello"))
+```
+
+The SDK receives the initial state and applies later patches in the background. Each callback gets a complete typed snapshot of the emitted fields, and RPC calls continue normally. Call `subscription.close()` when finished. Callbacks run serially on a background thread; the subscription does not keep an otherwise finished process alive.
+
+Pass `on_error=handler` to handle connection, validation, or callback failures. A failure stops the subscription; its exception is available as `subscription.error` and is logged if no handler is supplied. Actors with required connection metadata also require `metadata=...` when subscribing.
+
+See the [Python reference](https://github.com/TerseAI/durable-actors/blob/main/docs/reference/python.md) for supported types, sockets, reentrancy, deployment, and CLI options.
+
+## Resource settings and backend helpers
+
+Use `@sandbox(cpu=2, memory_mib=2048, idle_timeout_ms=60_000, regions=["canada"])` above an actor class to override deployment defaults. Import `sandbox` from `durable_actors`.
+
+Source classes also support `Chat.get("lobby")` with typed synchronous methods, including calls from other actors. Generated handles expose `broadcast(message)`; `actors.Chat.Authorization`, `actors.Chat.prepare_websocket(...)`, and `ActorProxy.handle(...)` issue typed browser access grants. `ActorSessionTransport` renews short-lived application credentials. The [Python reference](../docs/reference/python.md) covers these APIs and their docstrings.

durable_actors-0.5.5/README.md

@@ -0,0 +1,90 @@
+# Little Actors for Python
+
+Define durable actors in Python and generate typed Python clients. Python 3.11+ is supported. Actor state, placement, routing, and WebSocket delivery use the same Rust runtime as the TypeScript SDK.
+
+```sh
+pnpm dlx durable-actors init my-actors --template python
+cd my-actors
+pnpm install
+uv sync
+pnpm exec durable-actors dev
+```
+
+The shared TypeScript CLI manages development, generation, and Python type checking. It selects the project's `.venv` (or the active environment); `DURABLE_ACTORS_PYTHON` overrides the interpreter. Install Node.js 22+, Python 3.11+, and uv. The CLI downloads the matching native runtime on macOS and Linux. When developing this repository, set `DURABLE_ACTORS_BINARY` to an absolute path to your `cargo build --locked` executable.
+
+## Define actors
+
+```python
+from pydantic import BaseModel
+from durable_actors import Actor, emitted, ephemeral
+
+class Message(BaseModel):
+    text: str
+
+class Chat(Actor):
+    count: int = 0
+    messages: list[Message] = emitted(default_factory=list)
+    busy: bool = ephemeral(False)
+
+    def append(self, message: Message) -> list[Message]:
+        self.messages.append(message)
+        return self.messages
+```
+
+Public `def` methods become synchronous RPCs. Annotated fields persist by default. `emitted()` persists a field and broadcasts its saved changes; `ephemeral()` keeps a field temporary. Mutable defaults are copied for each actor, and both helpers accept `default_factory` for values constructed on activation. Use `ephemeral(default_factory=...)` for locks, caches, and service clients, and `ClassVar` for class constants. Classes extend `Actor` directly and use field defaults instead of constructors. Prefix helper methods with `_`. Synchronous handlers run on a worker thread, with calls serialized per actor. Socket hooks can also use ordinary `def`; `self.get_connections()` returns typed sockets.
+
+Add `@reentrant` (imported from `durable_actors`) to a `def` method to let other invocations enter before it finishes. Synchronous reentrant handlers overlap on worker threads; coordinate shared mutations and keep blocking I/O outside shared locks. Ordinary calls still serialize with each other. As in TypeScript, enabling reentrancy disables error rollback for the entire actor class. See the [execution semantics](../docs/reference/python.md#execution-and-failures) for details.
+
+## Generate and use a client
+
+With the actor server running, generate clients in your application:
+
+```sh
+pnpm add -D durable-actors
+uv add 'durable-actors[codegen]'
+pnpm exec durable-actors generate --out-dir generated
+```
+
+You can also generate directly from a trusted source entrypoint:
+
+```sh
+pnpm exec durable-actors generate src/actors.py --out-dir generated
+```
+
+```python
+from generated import actors
+
+chat = actors.Chat.get("lobby")
+messages: actors.Chat.Methods.append.Result = chat.append(actors.Chat.Message(text="hello"))
+print(messages[0].text)
+```
+
+The CLI runs strict mypy on local actor definitions before generation and on the generated package afterward. `dev` checks definitions before startup and every reload; an invalid edit leaves the previous code running.
+
+Generated RPC methods return typed values directly. The SDK creates a shared HTTP client when needed, reads configuration from the environment, and closes its connection pool at process exit. You only need the actor ID.
+
+The generated package exposes `actors`, matching the TypeScript client namespace. Use `actors.Chat.get(id)` for a handle, `actors.Chat.Stub` for its type, and `actors.Chat.Methods.append.Args` / `.Result` for method types. Socket types live at `actors.Chat.Metadata`, `.Incoming`, `.Outgoing`, and `.State`; concrete models such as `actors.Chat.Message` are also available there. The package includes docstrings, independent Pydantic models, and `py.typed`. Consumers need only `durable-actors`, not the actor project or the code generator. Regenerate after changing the actor contract, and include the generated package in your application's type checks.
+
+Typing uses inline annotations and the [PEP 561](https://peps.python.org/pep-0561/) package marker. Both mypy and Pyright check the SDK and generated clients. Pydantic validates inputs, outputs, and persisted state at runtime. Python annotations remain ordinary annotations: `chat.append(42)` is rejected by a type checker and by runtime validation.
+
+## Subscribe to state
+
+Actors with emitted fields have a typed `subscribe` method:
+
+```python
+chat = actors.Chat.get("lobby")
+subscription = chat.subscribe(lambda state: print(state.messages))
+chat.append(actors.Chat.Message(text="hello"))
+```
+
+The SDK receives the initial state and applies later patches in the background. Each callback gets a complete typed snapshot of the emitted fields, and RPC calls continue normally. Call `subscription.close()` when finished. Callbacks run serially on a background thread; the subscription does not keep an otherwise finished process alive.
+
+Pass `on_error=handler` to handle connection, validation, or callback failures. A failure stops the subscription; its exception is available as `subscription.error` and is logged if no handler is supplied. Actors with required connection metadata also require `metadata=...` when subscribing.
+
+See the [Python reference](https://github.com/TerseAI/durable-actors/blob/main/docs/reference/python.md) for supported types, sockets, reentrancy, deployment, and CLI options.
+
+## Resource settings and backend helpers
+
+Use `@sandbox(cpu=2, memory_mib=2048, idle_timeout_ms=60_000, regions=["canada"])` above an actor class to override deployment defaults. Import `sandbox` from `durable_actors`.
+
+Source classes also support `Chat.get("lobby")` with typed synchronous methods, including calls from other actors. Generated handles expose `broadcast(message)`; `actors.Chat.Authorization`, `actors.Chat.prepare_websocket(...)`, and `ActorProxy.handle(...)` issue typed browser access grants. `ActorSessionTransport` renews short-lived application credentials. The [Python reference](../docs/reference/python.md) covers these APIs and their docstrings.

durable_actors-0.5.5/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "durable-actors"
+version = "0.5.5"
+description = "Typed Python durable actors and generated clients"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = ["pydantic>=2.12,<3", "typing-extensions>=4.12,<5", "httpx>=0.28,<1", "websockets>=15,<17", "jsonschema>=4.23,<5", "packaging>=24,<27"]
+
+[project.urls]
+Repository = "https://github.com/TerseAI/durable-actors"
+Documentation = "https://github.com/TerseAI/durable-actors/blob/main/docs/reference/python.md"
+
+[project.optional-dependencies]
+codegen = ["datamodel-code-generator>=0.83,<0.84", "mypy>=1.15,<2", "pip>=25,<27"]
+
+[dependency-groups]
+dev = ["pytest>=8,<10", "pytest-asyncio>=1,<2", "mypy>=1.15,<2", "pyright>=1.1.400,<2", "ruff>=0.11,<1", "types-jsonschema", "datamodel-code-generator>=0.83,<0.84", "build>=1,<2", "pip>=25,<27"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+files = ["src/durable_actors"]
+
+[tool.pyright]
+include = ["src/durable_actors"]
+typeCheckingMode = "strict"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/durable_actors"]

durable_actors-0.5.5/src/durable_actors/__init__.py

@@ -0,0 +1,25 @@
+"""Define durable Python actors and use synchronous typed clients and subscriptions."""
+
+from .actor import Actor as Actor
+from .actor import reentrant as reentrant
+from .client import ActorInvocationError as ActorInvocationError
+from .client import ActorProtocolError as ActorProtocolError
+from .client import ActorTransport as ActorTransport
+from .client import Client as Client
+from .client import SocketGrant as SocketGrant
+from .connection import StateSnapshot as StateSnapshot
+from .connection import StateUpdate as StateUpdate
+from .fields import emitted as emitted
+from .fields import ephemeral as ephemeral
+from .generated import UNSET as UNSET
+from .generated import Unset as Unset
+from .json import JsonValue as JsonValue
+from .proxy import SocketAuthorization as SocketAuthorization
+from .sandbox import SandboxOptions as SandboxOptions
+from .sandbox import SandboxRegion as SandboxRegion
+from .sandbox import sandbox as sandbox
+from .session import ActorSession as ActorSession
+from .session import ActorSessionRejectedError as ActorSessionRejectedError
+from .session import ActorSessionTransport as ActorSessionTransport
+from .socket import ActorSocket as ActorSocket
+from .subscription import Subscription as Subscription

durable_actors-0.5.5/src/durable_actors/actor.py

@@ -0,0 +1,145 @@
+"""Define durable actors and control invocation concurrency."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from copy import deepcopy
+from typing import TYPE_CHECKING, Any, Generic, Literal, Self, TypeVar
+
+from typing_extensions import TypeVar as DefaultTypeVar
+
+from .json import JsonValue
+
+if TYPE_CHECKING:
+    from .client import ActorTransport
+    from .connection import Connection
+    from .socket import ActorSocket
+
+Metadata = DefaultTypeVar("Metadata", default=JsonValue)
+Incoming = DefaultTypeVar("Incoming", default=JsonValue)
+Outgoing = DefaultTypeVar("Outgoing", default=Incoming)
+Tag = DefaultTypeVar("Tag", bound=str, default=str)
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class Actor(Generic[Metadata, Incoming, Outgoing, Tag]):
+    """Base class for durable actors with typed RPCs and WebSocket hooks.
+
+    Public def methods become synchronous RPCs. Annotated fields persist by
+    default; emitted() also broadcasts their saved changes, and ephemeral() excludes
+    temporary values. Use field defaults or factories instead of a constructor.
+
+    Generic parameters describe connection metadata, incoming application
+    messages, outgoing application messages, and allowed connection tags. Outgoing
+    defaults to Incoming, tags to str, and other parameters to JsonValue.
+    """
+
+    def __init__(self) -> None:
+        """Initialize independent field defaults; the runtime restores persisted values afterward."""
+        from .contract import describe_actor
+
+        for field in describe_actor(type(self)).fields.values():
+            value = (
+                field.default_factory()
+                if field.default_factory is not None
+                else deepcopy(field.default)
+            )
+            setattr(self, field.name, value)
+
+    @classmethod
+    def get(cls, actor_id: str, transport: ActorTransport | None = None) -> Self:
+        """Return a typed synchronous reference without activating the actor locally.
+
+        RPC signatures match the source class. Fields and lifecycle hooks belong
+        to the running actor; read state through RPCs or generated subscriptions.
+        """
+        from .reference import actor_reference
+
+        return actor_reference(cls, actor_id, transport)
+
+    def connect(self, metadata: Metadata) -> Connection[Incoming, Outgoing, JsonValue, JsonValue]:
+        """Open a typed WebSocket through a source-class reference from get()."""
+        raise RuntimeError("connect() requires an actor reference from get()")
+
+    @property
+    def id(self) -> str:
+        """Identity of this actor, available during an active invocation or socket hook."""
+        from .socket import current_scope
+
+        return current_scope(self).actor_id
+
+    def on_connect(self, socket: ActorSocket[Metadata, Outgoing, Tag]) -> None:
+        """Handle a new WebSocket connection before it is accepted.
+
+        Override with def to inspect metadata, set tags, send a welcome
+        message, or reject with socket.reject(). The default accepts the connection.
+        """
+        pass
+
+    def on_message(self, socket: ActorSocket[Metadata, Outgoing, Tag], message: Incoming) -> None:
+        """Handle a validated incoming application message from a connected client.
+
+        Override with def to update actor state or send typed replies
+        through socket. The default ignores application messages.
+        """
+        pass
+
+    def on_disconnect(
+        self, socket: ActorSocket[Metadata, Outgoing, Tag], code: int, reason: str, was_clean: bool
+    ) -> None:
+        """Handle a closed connection; override with def for cleanup.
+
+        Args:
+            socket: Connection with its last known metadata and tags.
+            code: WebSocket close status code.
+            reason: WebSocket close reason.
+            was_clean: Whether the connection completed a clean closing handshake.
+        """
+        pass
+
+    def get_connections(self) -> list[ActorSocket[Metadata, Outgoing, Tag]]:
+        """Return connected sockets from a synchronous actor method or hook.
+
+        Use the returned handles only during the current invocation.
+        """
+        from .socket import current_scope
+
+        scope = current_scope(self)
+        return scope.blocking(scope.get_connections)
+
+    def broadcast(
+        self,
+        message: Outgoing,
+        *,
+        except_ids: tuple[str, ...] = (),
+        tags: tuple[Tag, ...] = (),
+        tag_match: Literal["all", "any"] = "all",
+    ) -> None:
+        """Queue a typed application message for selected connections.
+
+        Args:
+            message: Value matching the actor's outgoing message type.
+            except_ids: Connection IDs to exclude.
+            tags: Restrict delivery to matching tags; empty selects all connections.
+            tag_match: Use "all" to require every tag or "any" to require one.
+
+        Must be called during an active actor invocation or socket hook.
+        """
+        from .socket import current_scope
+
+        current_scope(self).broadcast(message, except_ids, tags, tag_match)
+
+
+def reentrant(method: F) -> F:
+    """Allow other invocations to enter before this method finishes.
+
+    Works with def RPCs and socket hooks. Handlers overlap on worker threads.
+    Ordinary invocations still serialize with each other and block new entries.
+    Nested method calls inherit the outer invocation's admission policy.
+
+    Reentrant actors share a live instance. Coordinate shared mutable state
+    across overlapping handlers. Failed invocations do not roll back state
+    anywhere in the actor class, because that could erase another call's work.
+    """
+    setattr(method, "__actor_reentrant__", True)
+    return method