py_gen_server 0.0.0__tar.gz

py_gen_server-0.0.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.3
+Name: py_gen_server
+Version: 0.0.0
+Summary: Erlang-style generic server (GenServer) actors
+Author: Steven Hé (Sīchàng)
+Author-email: Steven Hé (Sīchàng) <stevensichanghe@gmail.com>
+Requires-Dist: aio-sync>=0.2.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# PyGenServer
+
+TODO: summary
+
+## Usage
+
+TODO
+
+## Type checking
+
+Add the following to `pyproject.toml` (enabled here) for Pyright to validate subclasses of `Actor`:
+
+```toml
+[tool.pyright]
+typeCheckingMode = "basic"
+reportIncompatibleMethodOverride = "error"
+```

py_gen_server-0.0.0/README.md

@@ -0,0 +1,17 @@
+# PyGenServer
+
+TODO: summary
+
+## Usage
+
+TODO
+
+## Type checking
+
+Add the following to `pyproject.toml` (enabled here) for Pyright to validate subclasses of `Actor`:
+
+```toml
+[tool.pyright]
+typeCheckingMode = "basic"
+reportIncompatibleMethodOverride = "error"
+```

py_gen_server-0.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "py_gen_server"
+version = "0.0.0"
+description = "Erlang-style generic server (GenServer) actors"
+readme = "README.md"
+authors = [
+    { name = "Steven Hé (Sīchàng)", email = "stevensichanghe@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "aio-sync>=0.2.0",
+]
+
+[tool.pyright]
+typeCheckingMode = "basic"
+reportIncompatibleMethodOverride = "error"
+
+[build-system]
+requires = ["uv_build>=0.9.15,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

py_gen_server-0.0.0/src/py_gen_server/__init__.py

@@ -0,0 +1,13 @@
+"""Erlang-style generic server actors."""
+
+from .actor import Actor, ActorEnv, ActorRef, ActorRunResult, Msg, MsgCall, MsgCast
+
+__all__ = [
+    "Actor",
+    "ActorEnv",
+    "ActorRef",
+    "ActorRunResult",
+    "Msg",
+    "MsgCall",
+    "MsgCast",
+]

py_gen_server-0.0.0/src/py_gen_server/actor.py

@@ -0,0 +1,258 @@
+"""An Elixir/Erlang-GenServer-like actor."""
+
+from __future__ import annotations
+
+import asyncio
+from asyncio import FIRST_COMPLETED, QueueShutDown, Task, TaskGroup, create_task, wait
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from aio_sync.mpmc import MPMC, MPMCReceiver, MPMCSender, mpmc_channel
+from aio_sync.oneshot import OneShot, OneShotSender
+
+
+@dataclass(slots=True)
+class MsgCall[Call, Reply]:
+    """A "call" message (request-reply)."""
+
+    msg: Call
+    reply_sender: OneShotSender[Reply]
+
+
+@dataclass(slots=True)
+class MsgCast[Cast]:
+    """A "cast" message (fire-and-forget)."""
+
+    msg: Cast
+
+
+type Msg[Call, Cast, Reply] = MsgCall[Call, Reply] | MsgCast[Cast]
+"""A message sent to an actor."""
+
+
+@dataclass(slots=True)
+class ActorRunResult[Call, Cast, Reply]:
+    """The result when the `Actor` exits."""
+
+    actor: Actor[Call, Cast, Reply]
+    env: ActorEnv[Call, Cast, Reply]
+    exit_result: Exception | None
+
+
+@dataclass(slots=True)
+class Env[Call, Cast, Reply]:
+    """The environment the `Actor` runs in."""
+
+    ref_: ActorRef[Call, Cast, Reply]
+    msg_receiver: MPMCReceiver[Msg[Call, Cast, Reply]]
+
+
+type ActorEnv[Call, Cast, Reply] = Env[Call, Cast, Reply]
+"""The environment the `Actor` runs in."""
+
+
+@dataclass(slots=True)
+class ActorRef[Call, Cast, Reply]:
+    """A reference to an instance of `Actor`, to cast or call messages on it."""
+
+    msg_sender: MPMCSender[Msg[Call, Cast, Reply]]
+    actor_task: Task[ActorRunResult[Call, Cast, Reply]] | None = None
+
+    async def cast(self, msg: Cast) -> QueueShutDown | None:
+        """Cast a message to the actor and do not expect a reply."""
+        return await self.msg_sender.send(MsgCast(msg))
+
+    async def call(self, msg: Call) -> Reply | QueueShutDown:
+        """Call the actor and wait for a reply.
+        To time out the call, use `asyncio.wait_for`."""
+        reply_sender, reply_receiver = OneShot[Reply].channel()
+        send_err = await self.msg_sender.send(MsgCall(msg, reply_sender))
+        if send_err is not None:
+            return send_err
+
+        recv_task = create_task(reply_receiver.recv())
+        try:
+            if self.actor_task is None:
+                return await recv_task
+            done, _pending = await wait(
+                {recv_task, self.actor_task}, return_when=FIRST_COMPLETED
+            )
+            if recv_task in done:
+                return recv_task.result()
+            else:
+                try:
+                    rr = self.actor_task.result()
+                except asyncio.CancelledError:
+                    return QueueShutDown("Actor exited.")
+                if rr.exit_result is not None:
+                    raise rr.exit_result
+                return QueueShutDown("Actor exited.")
+        finally:
+            recv_task.cancel()
+
+    async def relay_call(
+        self, msg: Call, reply_sender: OneShotSender[Reply]
+    ) -> QueueShutDown | None:
+        """Call the actor and let it reply via a given one-shot sender.
+        Useful for relaying a call from some other caller."""
+        return await self.msg_sender.send(MsgCall(msg, reply_sender))
+
+    def cancel(self) -> bool:
+        """Cancel the actor referred to, so it exits, and does not wait for
+        it to exit.
+        @return True if the task was cancelled, False if it already finished or
+        never started."""
+        if self.actor_task is None:
+            return False
+        return self.actor_task.cancel()
+
+
+class Actor[Call, Cast, Reply](Protocol):
+    """An Elixir/Erlang-GenServer-like actor"""
+
+    async def init(self, _env: ActorEnv[Call, Cast, Reply]) -> Exception | None:
+        """Called when the actor starts.
+        # Snippet for copying
+        ```py
+        async def init(self, env: ActorEnv[Call, Cast, Reply]) -> None:
+            return
+        ```
+        """
+        return
+
+    async def handle_cast(
+        self, _msg: Cast, _env: ActorEnv[Call, Cast, Reply]
+    ) -> Exception | None:
+        """Called when the actor receives a message and does not need to reply.
+        # Snippet for copying
+        ```py
+        async def handle_cast(self, msg: Cast, env: ActorEnv[Call, Cast, Reply]) -> None:
+            return
+        ```
+        """
+        return
+
+    async def handle_call(
+        self,
+        _msg: Call,
+        _env: ActorEnv[Call, Cast, Reply],
+        _reply_sender: OneShotSender[Reply],
+    ) -> Exception | None:
+        """Called when the actor receives a message and needs to reply.
+
+        Implementations should send the reply using `reply_sender`, otherwise the caller
+        may hang.
+        # Snippet for copying
+        ```py
+        async def handle_call(
+            self,
+            msg: Call,
+            env: ActorEnv[Call, Cast, Reply],
+            reply_sender: OneShotSender[Reply],
+        ) -> None:
+            reply_sender.send(...)
+        ```
+        """
+        return
+
+    async def before_exit(
+        self,
+        run_result: Exception | None,
+        _env: ActorEnv[Call, Cast, Reply],
+    ) -> Exception | None:
+        """Called before the actor exits.
+        There are 3 cases when this method is called:
+        - The actor task is cancelled. `run_result` is `None`.
+        - All message senders are closed / channel is shut down.
+            `run_result` is `None`.
+        - `init`, `handle_cast`, or `handle_call` returned an exception or
+            raised. `run_result` is that exception.
+
+        This method's return value becomes `ActorRunResult.exit_result`.
+
+        # Snippet for copying
+        ```py
+        async def before_exit(self, run_result: Exception | None, env: ActorEnv[Call, Cast, Reply]) -> Exception | None:
+            return run_result
+        ```
+        """
+        return run_result
+
+    async def _handle_call_or_cast(
+        self, msg: Msg[Call, Cast, Reply], env: ActorEnv[Call, Cast, Reply]
+    ) -> Exception | None:
+        match msg:
+            case MsgCall(msg=call, reply_sender=reply_sender):
+                return await self.handle_call(call, env, reply_sender)
+            case MsgCast(msg=cast):
+                return await self.handle_cast(cast, env)
+
+    async def _handle_continuously(
+        self, env: ActorEnv[Call, Cast, Reply]
+    ) -> Exception | None:
+        while not isinstance(msg := await env.msg_receiver.recv(), QueueShutDown):
+            if (err := await self._handle_call_or_cast(msg, env)) is not None:
+                return err
+
+    async def _run_till_exit(
+        self, env: ActorEnv[Call, Cast, Reply]
+    ) -> Exception | None:
+        if (err := await self.init(env)) is not None:
+            return err
+        return await self._handle_continuously(env)
+
+    async def _run_and_handle_exit(
+        self, env: ActorEnv[Call, Cast, Reply]
+    ) -> Exception | None:
+        run_result: Exception | None = None
+        try:
+            run_result = await self._run_till_exit(env)
+        except asyncio.CancelledError:
+            pass
+        except Exception as err:
+            run_result = err
+        env.msg_receiver.shutdown(immediate=False)
+        try:
+            return await self.before_exit(run_result, env)
+        finally:
+            env.msg_receiver.shutdown(immediate=True)
+
+    def spawn(
+        self,
+        channel: MPMC[Msg[Call, Cast, Reply]] | None = None,
+        task_group: TaskGroup | None = None,
+    ) -> ActorRef[Call, Cast, Reply]:
+        """Spawn the actor in an asyncio task.
+
+        `channel` can be:
+        - `None`: create an unbounded `MPMC`
+        - `MPMC`: reuse an existing channel
+        """
+        match channel:
+            case None:
+                msg_sender, msg_receiver = mpmc_channel()
+            case MPMC(sender=sender, receiver=receiver):
+                msg_sender, msg_receiver = sender, receiver
+        actor_ref = ActorRef[Call, Cast, Reply](msg_sender)
+        env: ActorEnv[Call, Cast, Reply] = Env(actor_ref, msg_receiver)
+
+        async def _runner() -> ActorRunResult[Call, Cast, Reply]:
+            exit_result = await self._run_and_handle_exit(env)
+            return ActorRunResult(actor=self, env=env, exit_result=exit_result)
+
+        actor_ref.actor_task = (
+            asyncio.create_task(_runner())
+            if task_group is None
+            else task_group.create_task(_runner())
+        )
+        return actor_ref
+
+
+_DOC_PATH = Path(__file__).with_name("actor_doc.md")
+try:
+    _DOC = _DOC_PATH.read_text(encoding="utf-8")
+    __doc__ = _DOC
+    Actor.__doc__ = _DOC
+except OSError:
+    pass

py_gen_server-0.0.0/src/py_gen_server/actor_doc.md

@@ -0,0 +1,104 @@
+<!-- DO NOT modify manually! Keep this file very close to tokio_gen_server/src/actor_doc.md. -->
+# An Elixir/Erlang-GenServer-like actor
+
+Define 3 message types and at least one callback handler on your class to make it an actor.
+
+A GenServer-like actor simply receives messages and acts upon them.
+A message is either a "call" (request-reply) or a "cast" (fire-and-forget).
+Upon a "call" message, we call `Actor.handle_call`;
+upon a "cast" message, we call `Actor.handle_cast`.
+Upon cancellation or error, we call `Actor.before_exit`,
+so you can gracefully shut down.
+
+## Usage
+
+1. Define your actor class that stores your states and implement `Actor`.
+1. Declare your message types.
+   - If your actor does not expect any "cast", set `Cast` to `object`.
+   - If your actor does not expect any "call", set both `Call` and `Reply` to `object`.
+   > Tip: use your editor to automatically generate "required fields".
+1. Implement `handle_call` and/or `handle_cast`.
+   > Tip: use your editor to automatically generate "provided implementations",
+   > then hover on the methods you need and copy the snippets in their docstrings.
+1. Implement `init` and `before_exit` if needed.
+1. Spawn your actor with `Actor.spawn` (or module-level `spawn`) and get `(handle, actor_ref)`.
+1. Use `ActorRef` to send messages to your actor.
+
+## Example
+
+```py
+import asyncio
+from dataclasses import dataclass
+from enum import Enum, auto
+
+from py_gen_server import Actor, ActorEnv
+
+
+class PingOrBang(Enum):
+    Ping = auto()
+    Bang = auto()
+
+
+class PingOrPong(Enum):
+    Ping = auto()
+    Pong = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class Count:
+    counter: int
+
+
+type PongOrCount = str | Count
+
+
+class PingPongServer(Actor[PingOrPong, PingOrBang, PongOrCount]):
+    def __init__(self) -> None:
+        self.counter = 0
+
+    async def init(self, _env: ActorEnv[PingOrPong, PingOrBang, PongOrCount]) -> Exception | None:
+        print("PingPongServer starting.")
+        return None
+
+    async def handle_cast(
+        self,
+        msg: PingOrBang,
+        _env: ActorEnv[PingOrPong, PingOrBang, PongOrCount],
+    ) -> Exception | None:
+        if msg is PingOrBang.Bang:
+            return ValueError("Received Bang! Blowing up.")
+        self.counter += 1
+        print(f"Received ping #{self.counter}")
+        return None
+
+    async def handle_call(
+        self,
+        msg: PingOrPong,
+        _env: ActorEnv[PingOrPong, PingOrBang, PongOrCount],
+        reply_sender,
+    ) -> Exception | None:
+        match msg:
+            case PingOrPong.Ping:
+                self.counter += 1
+                print(f"Received ping #{self.counter} as a call")
+                reply_sender.send("pong")
+            case PingOrPong.Pong:
+                reply_sender.send(Count(self.counter))
+        return None
+
+
+async def main() -> None:
+    handle, server_ref = PingPongServer().spawn()
+    _ = await server_ref.cast(PingOrBang.Ping)
+    pong = await server_ref.call(PingOrPong.Ping)
+    assert pong == "pong"
+    count = await server_ref.call(PingOrPong.Pong)
+    assert count == Count(2)
+    server_ref.cancel()
+    async with asyncio.timeout(0.1):
+        rr = await handle
+    assert rr.exit_result is None
+
+
+asyncio.run(main())
+```