durable-actors 0.5.5__py3-none-any.whl

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/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

durable_actors/build.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import importlib
+import json
+import os
+import subprocess
+import sys
+import tomllib
+import zipfile
+from contextlib import redirect_stdout
+from importlib.metadata import distribution, distributions, version
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import Any
+
+from packaging.requirements import Requirement
+from packaging.utils import canonicalize_name
+
+from .actor import Actor
+from .contract import Document, public_contract
+from .guards import is_actor
+
+EXCLUDED_DIRECTORIES = {"node_modules", "venv", "__pycache__", "dist", "target", "generated"}
+
+
+def build_actor(project: Path, entrypoint: str, output: Path, *, local: bool = True) -> Document:
+    project, output = project.resolve(), output.resolve()
+    source = (project / entrypoint).resolve()
+    if not source.is_relative_to(project) or source.suffix != ".py" or not source.is_file():
+        raise ValueError("entrypoint must be a Python file inside the project")
+    if source.is_relative_to(output):
+        raise ValueError("output must not contain the actor source")
+    output.mkdir(parents=True, exist_ok=True)
+    settings = project_settings(project)
+    if not local:
+        install_dependencies(project, output, settings)
+    module = ".".join(source.relative_to(project).with_suffix("").parts)
+    write_artifact(project, output, module, settings)
+    with redirect_stdout(sys.stderr):
+        contract = public_contract(load_artifact(output / "actors.pyz"))
+    if len(json.dumps(contract).encode()) > 4 * 1024 * 1024:
+        raise ValueError("public actor contract exceeds 4 MiB")
+    return contract
+
+
+def project_settings(project: Path) -> Document:
+    manifest = project / "pyproject.toml"
+    return tomllib.loads(manifest.read_text()) if manifest.is_file() else {}
+
+
+def install_dependencies(project: Path, output: Path, settings: Document) -> None:
+    dependencies = settings.get("project", {}).get("dependencies", [])
+    requirements = project / "requirements.txt"
+    if (
+        not requirements.is_file()
+        and settings.get("project", {}).get("dynamic")
+        and "dependencies" in settings["project"]["dynamic"]
+    ):
+        raise ValueError("declare deployment dependencies explicitly or provide requirements.txt")
+    arguments = (
+        ["-r", str(requirements)] if requirements.is_file() else runtime_requirements(dependencies)
+    )
+    versions = runtime_versions()
+    if arguments:
+        install_requirements(project, output / "python", arguments, versions)
+    remove_bundled_runtime(output / "python", versions)
+    sys.path.insert(0, str(output / "python"))
+
+
+def runtime_versions() -> dict[str, str]:
+    versions: dict[str, str] = {}
+    visited: set[tuple[str, tuple[str, ...]]] = set()
+    pending = [Requirement("durable-actors")]
+    while pending:
+        requirement = pending.pop()
+        name = canonicalize_name(requirement.name)
+        extras = tuple(sorted(requirement.extras))
+        if (name, extras) in visited:
+            continue
+        visited.add((name, extras))
+        installed = distribution(name)
+        versions[name] = installed.version
+        for text in installed.requires or []:
+            dependency = Requirement(text)
+            if dependency.marker is None or any(
+                dependency.marker.evaluate({"extra": extra}) for extra in ("", *extras)
+            ):
+                pending.append(dependency)
+    return versions
+
+
+def install_requirements(
+    project: Path, directory: Path, arguments: list[str], versions: dict[str, str]
+) -> None:
+    with TemporaryDirectory(prefix="durable-actors-constraints-") as temporary:
+        constraints = Path(temporary) / "runtime.txt"
+        constraints.write_text("".join(f"{name}=={value}\n" for name, value in versions.items()))
+        subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "pip",
+                "install",
+                "--disable-pip-version-check",
+                "--no-compile",
+                "--target",
+                str(directory),
+                "--constraint",
+                str(constraints),
+                *arguments,
+            ],
+            cwd=project,
+            check=True,
+            stdout=sys.stderr,
+        )
+
+
+def remove_bundled_runtime(directory: Path, versions: dict[str, str]) -> None:
+    for installed in distributions(path=[str(directory)]):
+        name = canonicalize_name(installed.metadata["Name"])
+        if name not in versions:
+            continue
+        if installed.version != versions[name]:
+            raise ValueError(f"{name} version must match the build runtime")
+        if installed.files is None:
+            raise ValueError(f"installed {name} has no file manifest")
+        for file in installed.files:
+            remove_bundled_file(directory, directory / file)
+
+
+def remove_bundled_file(directory: Path, file: Path) -> None:
+    file = file.resolve()
+    if not file.is_relative_to(directory) or not file.is_file():
+        return
+    file.unlink()
+    for parent in file.parents:
+        if parent == directory:
+            break
+        try:
+            parent.rmdir()
+        except OSError:
+            break
+
+
+def runtime_requirements(dependencies: list[str]) -> list[str]:
+    result: list[str] = []
+    for dependency in dependencies:
+        requirement = Requirement(dependency)
+        if canonicalize_name(requirement.name) == "durable-actors":
+            if version("durable-actors") not in requirement.specifier:
+                raise ValueError("actor SDK version must match the build runtime")
+        else:
+            result.append(dependency)
+    return result
+
+
+def write_artifact(project: Path, output: Path, module: str, settings: Document) -> None:
+    paths = source_paths(project, output)
+    for pattern in settings.get("tool", {}).get("durable-actors", {}).get("include", []):
+        for path in project.glob(pattern):
+            if path.is_file():
+                if (
+                    path.is_symlink()
+                    or not path.resolve().is_relative_to(project)
+                    or path.is_relative_to(output)
+                ):
+                    raise ValueError("included resources must stay inside the project")
+                paths.add(path)
+    if sum(path.stat().st_size for path in paths) > 32 * 1024 * 1024:
+        raise ValueError("actor source artifact exceeds 32 MiB")
+    artifact = output / "actors.pyz"
+    with zipfile.ZipFile(artifact, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        archive.writestr("durable-actors.json", json.dumps({"version": 1, "module": module}))
+        directories: set[str] = set()
+        for path in sorted(paths):
+            relative = path.relative_to(project)
+            if str(relative) == "durable-actors.json":
+                raise ValueError("durable-actors.json is reserved for the artifact manifest")
+            archive.write(path, relative.as_posix())
+            directories.update(
+                parent.as_posix() + "/" for parent in relative.parents if parent != Path(".")
+            )
+        for directory in sorted(directories):
+            archive.writestr(directory, "")
+
+
+def source_paths(project: Path, output: Path) -> set[Path]:
+    paths: set[Path] = set()
+    for directory, directories, files in os.walk(project):
+        if "pyvenv.cfg" in files:
+            directories.clear()
+            continue
+        directories[:] = sorted(
+            name
+            for name in directories
+            if not name.startswith(".")
+            and name not in EXCLUDED_DIRECTORIES
+            and not (Path(directory) / name).is_symlink()
+            and (Path(directory) / name).resolve() != output
+        )
+        paths.update(
+            Path(directory) / name
+            for name in files
+            if name.endswith(".py") and not (Path(directory) / name).is_symlink()
+        )
+    return paths
+
+
+def load_artifact(path: Path) -> list[type[Actor[Any, Any, Any, Any]]]:
+    with zipfile.ZipFile(path) as archive:
+        manifest = json.loads(archive.read("durable-actors.json"))
+    if manifest.get("version") != 1:
+        raise ValueError("unsupported Python actor artifact")
+    sys.path.insert(0, str(path.parent / "python"))
+    return load_module(path, manifest["module"])
+
+
+def load_module(root: Path, module: str) -> list[type[Actor[Any, Any, Any, Any]]]:
+    sys.path[:0] = [str(root), str(root / "src")]
+    importlib.invalidate_caches()
+    loaded = importlib.import_module(module)
+    exported = getattr(loaded, "__all__", vars(loaded))
+    return [
+        value
+        for name, value in vars(loaded).items()
+        if name in exported and not name.startswith("_") and is_actor(value)
+    ]
+
+
+def main() -> None:
+    project, entrypoint, output, *mode = sys.argv[1:]
+    contract = build_actor(Path(project), entrypoint, Path(output), local=mode == ["local"])
+    print(json.dumps(contract, separators=(",", ":")))
+
+
+if __name__ == "__main__":
+    main()