ohra 0.1.0__py3-none-any.whl

ohra/__init__.py

@@ -0,0 +1,215 @@
+"""Apache Pekko Typed semantics on asyncio."""
+
+from .behavior import Behavior, Behaviors, Receive, StashBuffer, StashOverflowError
+from .cell import TimerScheduler
+from .cluster.core import (
+    Cluster,
+    ClusterDomainEvent,
+    ClusterSettings,
+    CurrentClusterState,
+    Down,
+    GetCurrentState,
+    Join,
+    JoinSeedNodes,
+    LeaderChanged,
+    Leave,
+    MemberDowned,
+    MemberEvent,
+    MemberExited,
+    MemberJoined,
+    MemberLeft,
+    MemberRemoved,
+    MemberUp,
+    MemberWeaklyUp,
+    ReachabilityEvent,
+    ReachableMember,
+    SelfRemoved,
+    SelfUp,
+    Subscribe,
+    UnreachableMember,
+    Unsubscribe,
+)
+from .cluster.gossip import Member
+from .cluster.sharding import (
+    ClusterSharding,
+    ClusterShardingSettings,
+    CurrentShardRegionState,
+    Entity,
+    EntityContext,
+    EntityRef,
+    EntityTypeKey,
+    GetShardRegionState,
+    Passivate,
+    ShardCommand,
+    Sharding,
+    ShardingEnvelope,
+)
+from .cluster.sbr import (
+    DownAll,
+    KeepMajority,
+    KeepOldest,
+    SplitBrainResolverSettings,
+    StaticQuorum,
+)
+from .cluster.singleton import ClusterSingleton, ClusterSingletonSettings, SingletonActor
+from .context import ActorContext
+from .discovery import ConfigServiceDiscovery, Lookup, Resolved, ResolvedTarget, ServiceDiscovery
+from .coordinated_shutdown import (
+    ActorSystemTerminateReason,
+    ClusterDowningReason,
+    ClusterLeavingReason,
+    CoordinatedShutdown,
+    CoordinatedShutdownSettings,
+    JvmExitReason,
+    Reason,
+)
+from .mailbox import MailboxOverflowError, MailboxSelector
+from .management import Management, ManagementSettings
+from .management.bootstrap import ClusterBootstrap, ClusterBootstrapSettings
+from .management.kubernetes import KubernetesApiServiceDiscovery, KubernetesApiSettings
+from .management.health import HealthCheckSettings
+from .patterns import AskTimeoutError, Replyable, SpawnProtocol, ask, batching
+from .receptionist import (
+    Deregister,
+    Deregistered,
+    Find,
+    Listing,
+    Receptionist,
+    Register,
+    Registered,
+    ServiceKey,
+)
+from .persistence import (
+    InMemoryStore,
+    Persist,
+    Persisted,
+    PersistenceError,
+    RevisionConflictError,
+    SqliteStore,
+    Store,
+)
+from .ref import ActorRef
+from .remote import Address, RemoteRef, UniqueAddress
+from .remote.serialization import Serialization, SerializationError, remotable
+from .result import Failure, Success, Try
+from .routers import PoolRouter, Routers
+from .signals import ChildFailed, DeathPactError, PostStop, PreRestart, Signal, Terminated
+from .supervision import SupervisorStrategy
+from .system import ActorSystem
+
+__all__ = [
+    "ActorContext",
+    "ActorRef",
+    "ActorSystem",
+    "ActorSystemTerminateReason",
+    "Address",
+    "AskTimeoutError",
+    "Behavior",
+    "Behaviors",
+    "ChildFailed",
+    "Cluster",
+    "ClusterBootstrap",
+    "ClusterBootstrapSettings",
+    "ClusterDomainEvent",
+    "ClusterDowningReason",
+    "ClusterLeavingReason",
+    "ClusterSettings",
+    "ClusterSharding",
+    "ClusterShardingSettings",
+    "ClusterSingleton",
+    "ClusterSingletonSettings",
+    "ConfigServiceDiscovery",
+    "CoordinatedShutdown",
+    "CoordinatedShutdownSettings",
+    "CurrentClusterState",
+    "CurrentShardRegionState",
+    "DeathPactError",
+    "Deregister",
+    "Deregistered",
+    "Down",
+    "DownAll",
+    "Entity",
+    "EntityContext",
+    "EntityRef",
+    "EntityTypeKey",
+    "Failure",
+    "Find",
+    "GetCurrentState",
+    "GetShardRegionState",
+    "HealthCheckSettings",
+    "InMemoryStore",
+    "Join",
+    "JoinSeedNodes",
+    "JvmExitReason",
+    "KubernetesApiServiceDiscovery",
+    "KubernetesApiSettings",
+    "KeepMajority",
+    "KeepOldest",
+    "LeaderChanged",
+    "Leave",
+    "Listing",
+    "Lookup",
+    "MailboxOverflowError",
+    "MailboxSelector",
+    "Member",
+    "MemberDowned",
+    "MemberEvent",
+    "MemberExited",
+    "MemberJoined",
+    "MemberLeft",
+    "MemberRemoved",
+    "MemberUp",
+    "MemberWeaklyUp",
+    "Passivate",
+    "Management",
+    "ManagementSettings",
+    "Persist",
+    "Persisted",
+    "PersistenceError",
+    "PoolRouter",
+    "PostStop",
+    "PreRestart",
+    "ReachabilityEvent",
+    "ReachableMember",
+    "Reason",
+    "Receive",
+    "Receptionist",
+    "Register",
+    "Registered",
+    "RemoteRef",
+    "Replyable",
+    "Resolved",
+    "ResolvedTarget",
+    "RevisionConflictError",
+    "Routers",
+    "SelfRemoved",
+    "SelfUp",
+    "Serialization",
+    "SerializationError",
+    "ServiceDiscovery",
+    "ServiceKey",
+    "ShardCommand",
+    "Sharding",
+    "ShardingEnvelope",
+    "Signal",
+    "SingletonActor",
+    "SplitBrainResolverSettings",
+    "StaticQuorum",
+    "SpawnProtocol",
+    "SqliteStore",
+    "StashBuffer",
+    "StashOverflowError",
+    "Store",
+    "Subscribe",
+    "Success",
+    "SupervisorStrategy",
+    "Terminated",
+    "TimerScheduler",
+    "Try",
+    "UniqueAddress",
+    "UnreachableMember",
+    "Unsubscribe",
+    "ask",
+    "batching",
+    "remotable",
+]

ohra/behavior.py

@@ -0,0 +1,215 @@
+"""Behaviors: values describing how an actor reacts to the next message.
+
+Mirrors org.apache.pekko.actor.typed.scaladsl.Behaviors. A handler returns the
+next behavior; returning ``Behaviors.same`` keeps the current one.
+Handlers may be plain functions or coroutines.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .signals import Signal
+from .supervision import SupervisorStrategy
+
+if TYPE_CHECKING:
+    from .persistence import Store, _Persister  # pyright: ignore[reportPrivateUsage]
+    from .cell import TimerScheduler
+    from .context import ActorContext
+
+type MaybeAwaitable[X] = X | Awaitable[X]
+
+
+class Behavior[T]:
+    """Base of all behaviors. T is the message type the actor accepts."""
+
+    __slots__ = ()
+
+    def _accepts(self, msg: T) -> None:  # pins T as contravariant, never called
+        raise NotImplementedError
+
+
+class _Same(Behavior[Any]):
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "Behaviors.same"
+
+
+class _Unhandled(Behavior[Any]):
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "Behaviors.unhandled"
+
+
+@dataclass(frozen=True, eq=False, slots=True)
+class Stopped(Behavior[Any]):
+    post_stop: Callable[[], None] | None = None
+
+
+@dataclass(frozen=True, eq=False, slots=True)
+class Setup[T](Behavior[T]):
+    factory: Callable[[ActorContext[T]], MaybeAwaitable[Behavior[T]]]
+
+
+@dataclass(frozen=True, eq=False, slots=True)
+class Receive[T](Behavior[T]):
+    on_message: Callable[[ActorContext[T], T], MaybeAwaitable[Behavior[T]]]
+    on_signal: Callable[[ActorContext[T], Signal], MaybeAwaitable[Behavior[T]]] | None = None
+
+    def receive_signal(
+        self, handler: Callable[[ActorContext[T], Signal], MaybeAwaitable[Behavior[T]]]
+    ) -> Receive[T]:
+        return Receive(self.on_message, handler)
+
+
+@dataclass(frozen=True, eq=False, slots=True)
+class WithTimers[T](Behavior[T]):
+    factory: Callable[[TimerScheduler[T]], MaybeAwaitable[Behavior[T]]]
+
+
+@dataclass(frozen=True, eq=False, slots=True)
+class Unstash[T](Behavior[T]):
+    """Returned by StashBuffer.unstash_all: the runtime replays ``messages`` into ``behavior``."""
+
+    messages: deque[T]
+    behavior: Behavior[T]
+
+
+class StashOverflowError(Exception):
+    """Raised by StashBuffer.stash when the buffer is full."""
+
+
+class StashBuffer[T]:
+    """Pekko's StashBuffer. Create one with ``Behaviors.with_stash``."""
+
+    __slots__ = ("_capacity", "_messages")
+
+    def __init__(self, capacity: int) -> None:
+        self._capacity = capacity
+        self._messages: deque[T] = deque()
+
+    @property
+    def size(self) -> int:
+        return len(self._messages)
+
+    @property
+    def is_empty(self) -> bool:
+        return not self._messages
+
+    @property
+    def is_full(self) -> bool:
+        return len(self._messages) >= self._capacity
+
+    def stash(self, msg: T) -> None:
+        if self.is_full:
+            raise StashOverflowError(f"stash buffer is full ({self._capacity})")
+        self._messages.append(msg)
+
+    def unstash_all(self, behavior: Behavior[T]) -> Behavior[T]:
+        """Process the stashed messages, in order, with ``behavior`` before any new message.
+
+        Messages stashed during the replay stay in the buffer. Behaves like
+        ``Behaviors.same`` once the buffer is empty."""
+        return Unstash(self._messages, behavior)
+
+
+@dataclass(frozen=True, eq=False, slots=True)
+class Supervised[T](Behavior[T]):
+    """Template: the runtime wraps it in a supervisor when the actor starts."""
+
+    initial: Behavior[T]
+    strategy: SupervisorStrategy
+    exc_type: type[Exception] = Exception
+
+
+class _SuperviseBuilder[T]:
+    __slots__ = ("_behavior",)
+
+    def __init__(self, behavior: Behavior[T]) -> None:
+        self._behavior = behavior
+
+    def on_failure(
+        self, strategy: SupervisorStrategy, exc_type: type[Exception] = Exception
+    ) -> Behavior[T]:
+        return Supervised(self._behavior, strategy, exc_type)
+
+
+SAME: Behavior[Any] = _Same()
+UNHANDLED: Behavior[Any] = _Unhandled()
+
+
+def _unhandled_message(_ctx: Any, _msg: Any) -> Behavior[Any]:
+    return UNHANDLED
+
+
+def _ignore_message(_ctx: Any, _msg: Any) -> Behavior[Any]:
+    return SAME
+
+
+class Behaviors:
+    """Factory namespace, named after the Scala DSL."""
+
+    same: Behavior[Any] = SAME
+    unhandled: Behavior[Any] = UNHANDLED
+    empty: Behavior[Any] = Receive(_unhandled_message)
+    ignore: Behavior[Any] = Receive(_ignore_message)
+
+    @staticmethod
+    def stopped(post_stop: Callable[[], None] | None = None) -> Behavior[Any]:
+        return Stopped(post_stop)
+
+    @staticmethod
+    def setup[T](factory: Callable[[ActorContext[T]], MaybeAwaitable[Behavior[T]]]) -> Behavior[T]:
+        return Setup(factory)
+
+    @staticmethod
+    def receive[T](
+        handler: Callable[[ActorContext[T], T], MaybeAwaitable[Behavior[T]]],
+    ) -> Receive[T]:
+        return Receive(handler)
+
+    @staticmethod
+    def receive_signal[T](
+        handler: Callable[[ActorContext[T], Signal], MaybeAwaitable[Behavior[T]]],
+    ) -> Receive[T]:
+        """Handle signals only; messages are unhandled."""
+        return Receive(_unhandled_message, handler)
+
+    @staticmethod
+    def receive_message[T](handler: Callable[[T], MaybeAwaitable[Behavior[T]]]) -> Receive[T]:
+        def on_message(_ctx: ActorContext[T], msg: T) -> MaybeAwaitable[Behavior[T]]:
+            return handler(msg)
+
+        return Receive(on_message)
+
+    @staticmethod
+    def supervise[T](behavior: Behavior[T]) -> _SuperviseBuilder[T]:
+        return _SuperviseBuilder(behavior)
+
+    @staticmethod
+    def persisted[S](store: Store[S]) -> _Persister[S]:
+        """Make a state-to-behavior factory persisted: ``@Behaviors.persisted(store)`` on ``def
+        cart(items)``. Calling the factory writes the state before becoming; ``factory.recover(id,
+        empty)`` starts it."""
+        from .persistence import persisted
+
+        return persisted(store)
+
+    @staticmethod
+    def with_timers[T](
+        factory: Callable[[TimerScheduler[T]], MaybeAwaitable[Behavior[T]]],
+    ) -> Behavior[T]:
+        """Give the behavior access to the actor's timers. All timers are cancelled on restart."""
+        return WithTimers(factory)
+
+    @staticmethod
+    def with_stash[T](
+        capacity: int, factory: Callable[[StashBuffer[T]], MaybeAwaitable[Behavior[T]]]
+    ) -> Behavior[T]:
+        """Give the behavior a fresh StashBuffer per incarnation."""
+        return Setup(lambda _ctx: factory(StashBuffer(capacity)))