radiodish-actor 1.0.0__tar.gz

radiodish_actor-1.0.0/LICENSE

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

radiodish_actor-1.0.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: radiodish-actor
+Version: 1.0.0
+Summary: An Erlang-actor-model-flavored layer on top of radiodish -- group-addressed message dispatch over an autowired RADIO-DISH mesh.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pow4you/radiodish
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: radiodish>=1.0.0
+Dynamic: license-file
+
+# radiodish-actor
+
+An Erlang-actor-model-flavored layer on top of
+[`radiodish`](../radiodish/), running actors over an autowired RADIO-DISH
+mesh instead of a custom VM. The point of doing it this way: any process,
+in any language, that speaks radiodish's wire protocol can participate as
+a peer actor — interoperability doesn't depend on sharing a runtime the
+way BEAM's process/PID model does.
+
+```python
+from radioactor import Actor, expose
+
+class Greeter(Actor):
+    id = "greeter"
+
+    @expose()
+    async def ping(self, payload):
+        return {"pong": payload}
+
+class Caller(Actor):
+    pass
+
+provider = await Greeter().register()
+caller = await Caller().register()
+result = await caller.call("ping", {"seq": 1}, timeout=2.0)
+```
+
+No manual wiring, no pre-declared dependencies required — `caller`
+discovers `provider` and figures out how to reach `"ping"` entirely on
+its own.
+
+## Install
+
+```
+pip install radiodish-actor
+```
+
+This pulls in `radiodish` automatically. For local/editable development
+against this repo, see the workspace root README — this package is a
+member of a `uv` workspace, developed alongside `radiodish` itself.
+
+## Documentation
+
+- **[docs/index.md](docs/index.md)** — quick start, install
+- **[docs/actor-model.md](docs/actor-model.md)** — the group-addressing
+  model in depth (there's no "call actor X's method Y" — only "send to a
+  group"), dynamic dependency discovery, why direct `Actor()`
+  instantiation is discouraged, and the real bugs found while building it
+- **[docs/examples/](docs/examples/)** — a runnable provider + caller demo
+
+## Why not just RPC?
+
+Because the transport underneath (RADIO-DISH) is fundamentally a
+broadcast/multicast primitive, not a point-to-point one — trying to force
+point-to-point RPC semantics on top of it fights the transport instead of
+using it. This package leans fully into that instead: addressing is
+"send to a group," and a group can legitimately have more than one
+listener. See [docs/actor-model.md](docs/actor-model.md) for what that
+means in practice, including the real trade-offs (at-least-once
+delivery, no built-in "method not found" error) that come with embracing
+it honestly rather than papering over it.

radiodish_actor-1.0.0/README.md

@@ -0,0 +1,61 @@
+# radiodish-actor
+
+An Erlang-actor-model-flavored layer on top of
+[`radiodish`](../radiodish/), running actors over an autowired RADIO-DISH
+mesh instead of a custom VM. The point of doing it this way: any process,
+in any language, that speaks radiodish's wire protocol can participate as
+a peer actor — interoperability doesn't depend on sharing a runtime the
+way BEAM's process/PID model does.
+
+```python
+from radioactor import Actor, expose
+
+class Greeter(Actor):
+    id = "greeter"
+
+    @expose()
+    async def ping(self, payload):
+        return {"pong": payload}
+
+class Caller(Actor):
+    pass
+
+provider = await Greeter().register()
+caller = await Caller().register()
+result = await caller.call("ping", {"seq": 1}, timeout=2.0)
+```
+
+No manual wiring, no pre-declared dependencies required — `caller`
+discovers `provider` and figures out how to reach `"ping"` entirely on
+its own.
+
+## Install
+
+```
+pip install radiodish-actor
+```
+
+This pulls in `radiodish` automatically. For local/editable development
+against this repo, see the workspace root README — this package is a
+member of a `uv` workspace, developed alongside `radiodish` itself.
+
+## Documentation
+
+- **[docs/index.md](docs/index.md)** — quick start, install
+- **[docs/actor-model.md](docs/actor-model.md)** — the group-addressing
+  model in depth (there's no "call actor X's method Y" — only "send to a
+  group"), dynamic dependency discovery, why direct `Actor()`
+  instantiation is discouraged, and the real bugs found while building it
+- **[docs/examples/](docs/examples/)** — a runnable provider + caller demo
+
+## Why not just RPC?
+
+Because the transport underneath (RADIO-DISH) is fundamentally a
+broadcast/multicast primitive, not a point-to-point one — trying to force
+point-to-point RPC semantics on top of it fights the transport instead of
+using it. This package leans fully into that instead: addressing is
+"send to a group," and a group can legitimately have more than one
+listener. See [docs/actor-model.md](docs/actor-model.md) for what that
+means in practice, including the real trade-offs (at-least-once
+delivery, no built-in "method not found" error) that come with embracing
+it honestly rather than papering over it.

radiodish_actor-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "radiodish-actor"
+version = "1.0.0"
+description = "An Erlang-actor-model-flavored layer on top of radiodish -- group-addressed message dispatch over an autowired RADIO-DISH mesh."
+requires-python = ">=3.9"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["radiodish>=1.0.0"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/pow4you/radiodish"
+
+[tool.uv.sources]
+radiodish = { workspace = true }
+
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["radioactor"]
+
+[tool.setuptools.package-dir]
+radioactor = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

radiodish_actor-1.0.0/radiodish_actor.egg-info/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: radiodish-actor
+Version: 1.0.0
+Summary: An Erlang-actor-model-flavored layer on top of radiodish -- group-addressed message dispatch over an autowired RADIO-DISH mesh.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pow4you/radiodish
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: radiodish>=1.0.0
+Dynamic: license-file
+
+# radiodish-actor
+
+An Erlang-actor-model-flavored layer on top of
+[`radiodish`](../radiodish/), running actors over an autowired RADIO-DISH
+mesh instead of a custom VM. The point of doing it this way: any process,
+in any language, that speaks radiodish's wire protocol can participate as
+a peer actor — interoperability doesn't depend on sharing a runtime the
+way BEAM's process/PID model does.
+
+```python
+from radioactor import Actor, expose
+
+class Greeter(Actor):
+    id = "greeter"
+
+    @expose()
+    async def ping(self, payload):
+        return {"pong": payload}
+
+class Caller(Actor):
+    pass
+
+provider = await Greeter().register()
+caller = await Caller().register()
+result = await caller.call("ping", {"seq": 1}, timeout=2.0)
+```
+
+No manual wiring, no pre-declared dependencies required — `caller`
+discovers `provider` and figures out how to reach `"ping"` entirely on
+its own.
+
+## Install
+
+```
+pip install radiodish-actor
+```
+
+This pulls in `radiodish` automatically. For local/editable development
+against this repo, see the workspace root README — this package is a
+member of a `uv` workspace, developed alongside `radiodish` itself.
+
+## Documentation
+
+- **[docs/index.md](docs/index.md)** — quick start, install
+- **[docs/actor-model.md](docs/actor-model.md)** — the group-addressing
+  model in depth (there's no "call actor X's method Y" — only "send to a
+  group"), dynamic dependency discovery, why direct `Actor()`
+  instantiation is discouraged, and the real bugs found while building it
+- **[docs/examples/](docs/examples/)** — a runnable provider + caller demo
+
+## Why not just RPC?
+
+Because the transport underneath (RADIO-DISH) is fundamentally a
+broadcast/multicast primitive, not a point-to-point one — trying to force
+point-to-point RPC semantics on top of it fights the transport instead of
+using it. This package leans fully into that instead: addressing is
+"send to a group," and a group can legitimately have more than one
+listener. See [docs/actor-model.md](docs/actor-model.md) for what that
+means in practice, including the real trade-offs (at-least-once
+delivery, no built-in "method not found" error) that come with embracing
+it honestly rather than papering over it.

radiodish_actor-1.0.0/radiodish_actor.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+radiodish_actor.egg-info/PKG-INFO
+radiodish_actor.egg-info/SOURCES.txt
+radiodish_actor.egg-info/dependency_links.txt
+radiodish_actor.egg-info/requires.txt
+radiodish_actor.egg-info/top_level.txt
+src/__init__.py
+src/base.py
+src/decorators.py
+tests/test_actor.py

radiodish_actor-1.0.0/radiodish_actor.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

radiodish_actor-1.0.0/radiodish_actor.egg-info/requires.txt

@@ -0,0 +1 @@
+radiodish>=1.0.0

radiodish_actor-1.0.0/radiodish_actor.egg-info/top_level.txt

@@ -0,0 +1 @@
+radioactor

radiodish_actor-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

radiodish_actor-1.0.0/src/__init__.py

@@ -0,0 +1,41 @@
+"""
+radioactor — an Erlang-actor-model-flavored layer on top of radish. Not
+RPC bolted onto pub/sub; it leans fully into RADIO-DISH's native broadcast
+nature. There's no "call actor X's method Y" — there's only "send to a
+group." A handler's trigger-set, computed by @expose(groups=...):
+
+    your explicit groups ∪ {the function's own name} ∪ {""}
+
+Every exposed function joins "" by default, so an unaddressed message
+reaches every exposed function on every actor you're connected to — a
+genuine broadcast-to-everyone channel, not accidental. Function names
+aren't actor-namespaced (@expose runs before any actor instance exists,
+so it can't see self.actor_id()) — two actor classes both exposing
+`login` both receive anything sent to bare group "login"; bake your own
+namespace into an explicit group string if you want to avoid that.
+
+    from radioactor import Actor, expose
+
+    class Greeter(Actor):
+        id = "greeter"
+
+        @expose()
+        async def ping(self, payload):
+            return {"pong": payload}
+
+    class Caller(Actor):
+        pass
+
+    provider = await Greeter().register()
+    caller = await Caller().register()
+    result = await caller.call("ping", {"seq": 1}, timeout=2.0)
+
+Depends on the `radiodish` package (imported as `radish`) for its
+transport, discovery, and autowiring -- see that package's docs for how
+the underlying mesh actually forms.
+"""
+
+from radioactor.decorators import expose
+from radioactor.base import Actor
+
+__all__ = ["Actor", "expose"]

radiodish_actor-1.0.0/src/base.py

@@ -0,0 +1,335 @@
+"""
+radioactor/base.py — Actor: an Erlang-actor-model-flavored base class running
+over autowired RadishSockets. See radioactor/__init__.py's docstring for the
+addressing model (groups, not "call actor X's method Y").
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import uuid
+import warnings
+from typing import Callable, Iterable, Optional
+
+from radish import RadioDishError
+from radish.autowire import autowired_radish, DEFAULT_DISCOVERY_PORT
+
+
+class Actor:
+    """
+    Base class for radish-backed actors. Subclass it and tag methods with
+    @expose, then `await register()`.
+
+    `depends_on` is optional now, not required: send()/call() register
+    interest in whatever group they're asked to reach the first time they
+    try, so an actor discovers what it needs on the fly instead of you
+    having to predict it up front. Pass `depends_on` only if you want to
+    pre-warm that wiring before your first call, to skip the latency of
+    waiting for AutoWirer's next poll -- not because anything requires it.
+    """
+
+    def __init__(self, depends_on: Iterable[str] = ()):
+        if type(self) is Actor:
+            warnings.warn(
+                "Instantiating Actor directly is discouraged -- define a "
+                "subclass instead, even an empty `class MyCaller(Actor): "
+                "pass`. actor_id() defaults to the class name, so every "
+                "bare Actor() instance identifies itself as just 'Actor' "
+                "in logs, discovery announcements, and instance_id() -- a "
+                "named subclass makes that identity actually mean "
+                "something, and gives you a natural place to grow into "
+                "(exposed methods, on_register(), etc.) later.",
+                stacklevel=2,
+            )
+        self._instance_id = f"{self.actor_id()}#{uuid.uuid4().hex[:8]}"
+        self._depends_on: set = set(depends_on)
+        self._groups_to_handlers: dict[str, list[Callable]] = self._discover_exposed_methods()
+        self._pending: dict[str, asyncio.Future] = {}
+        self.radish = None
+        self.discoverer = None
+        self.wirer = None
+        self._run_task: Optional[asyncio.Task] = None
+
+    # ---- identity ---------------------------------------------------------
+
+    def actor_id(self) -> str:
+        """Logical, human-readable identity -- shared on purpose if you run
+        several replicas under the same class/id. Not used for routing at
+        all in this design (see module docstring); it's here for logging,
+        discovery bookkeeping, and as a building block if you want to
+        construct your own namespaced group strings."""
+        return getattr(self, "id", self.__class__.__name__)
+
+    def instance_id(self) -> str:
+        """Always unique to this running process. Used only to build the
+        private reply group -- never appears in capability routing."""
+        return self._instance_id
+
+    def _reply_group(self) -> str:
+        return f"{self._instance_id}.replies"
+
+    # ---- setup --------------------------------------------------------------
+
+    def _discover_exposed_methods(self) -> dict[str, list[Callable]]:
+        groups_to_handlers: dict[str, list[Callable]] = {}
+        for _, method in inspect.getmembers(self, predicate=inspect.ismethod):
+            if getattr(method, "_exposed", False):
+                for group in method._exposed_groups:
+                    groups_to_handlers.setdefault(group, []).append(method)
+        return groups_to_handlers
+
+    def _own_groups(self) -> list[str]:
+        return list(self._groups_to_handlers.keys()) + [self._reply_group()]
+
+    async def register(
+        self,
+        *,
+        host: Optional[str] = None,
+        discovery_port: int = DEFAULT_DISCOVERY_PORT,
+        seeds: Iterable[tuple[str, int]] = (),
+        port_range: tuple[int, int] = (20000, 40000),
+    ) -> "Actor":
+        """
+        Finds ports, binds a RadishSocket, joins every exposed group plus
+        this instance's private reply group, starts discovery/autowiring
+        (using `depends_on`, from __init__, as extra connect-worthy
+        interest beyond what this actor itself exposes), then starts the
+        dispatch loop. Returns self so `x = await Foo().register()` works.
+        """
+        own_groups = self._own_groups()
+        interest = set(own_groups) | self._depends_on
+        self.radish, self.discoverer, self.wirer = await autowired_radish(
+            host=host,
+            groups=own_groups,
+            interest_groups=interest,
+            discovery_port=discovery_port,
+            seeds=seeds,
+            port_range=port_range,
+            node_id=self._instance_id,
+        )
+        if hasattr(self, "on_register"):
+            await self.on_register()
+        self._run_task = asyncio.ensure_future(self._run())
+        return self
+
+    def add_endpoint(self, method: Callable) -> None:
+        """
+        Expose a new @expose'd method after registration. No disconnect
+        needed for existing peers to pick it up: DishSocket.join() was
+        already safe to call any time, and radiodish's periodic rejoin
+        announces it to every already-connected peer automatically. What
+        DOES need an explicit push is the Discoverer's advertised group
+        list, so *new* peers (ones not connected yet) can find this
+        capability during discovery -- that's the one line that's genuinely
+        new here, not a disconnect/reconnect.
+        """
+        groups = getattr(method, "_exposed_groups", None)
+        if groups is None:
+            raise RadioDishError("add_endpoint() expects an @expose'd method")
+        new_groups = [g for g in groups if g not in self._groups_to_handlers]
+        for g in groups:
+            self._groups_to_handlers.setdefault(g, []).append(method)
+        if self.radish is not None:
+            for g in new_groups:
+                self.radish.join(g)
+            self.discoverer.update_groups(self._own_groups())
+
+    def add_dependency(self, group: str) -> None:
+        """Declare interest in reaching `group` even though this actor
+        doesn't expose it -- lets AutoWirer connect out to a provider once
+        one is discovered, AND (since connecting is decided from both
+        sides -- see autowire.Discoverer's docstring) lets a provider who's
+        already running connect back to us once it hears our updated
+        interest in our next announcement."""
+        self._depends_on.add(group)
+        if self.wirer is not None:
+            self.wirer.add_interest(group)
+        if self.discoverer is not None:
+            self.discoverer.update_interest(set(self._own_groups()) | self._depends_on)
+
+    def _ensure_interest(self, group: str) -> None:
+        """The dynamic half of dependency discovery: called by send()/call()
+        so an actor registers interest in a group automatically, the first
+        time it actually tries to reach it, instead of requiring that to be
+        predicted upfront via depends_on. Skips the (cheap but not free --
+        it triggers a re-announce) work entirely for groups already covered,
+        either because add_dependency() already ran for this one, or
+        because it's something this actor exposes itself already."""
+        if group in self._depends_on or group in self._groups_to_handlers:
+            return
+        self.add_dependency(group)
+
+    # ---- dispatch loop ---------------------------------------------------
+
+    async def _run(self):
+        try:
+            while True:
+                group, raw = await self.radish.recv()
+                try:
+                    group_str = group.decode("utf-8")
+                except UnicodeDecodeError:
+                    continue
+                if group_str == self._reply_group():
+                    self._handle_reply(raw)
+                    continue
+                try:
+                    msg = json.loads(raw.decode("utf-8"))
+                except (ValueError, UnicodeDecodeError):
+                    continue
+                for handler in self._groups_to_handlers.get(group_str, ()):
+                    await self._dispatch_one(handler, msg)
+        except asyncio.CancelledError:
+            pass
+
+    async def _dispatch_one(self, handler: Callable, msg: dict) -> None:
+        await self._send_status(msg, status=202)  # "accepted" ack -- UDP
+        # gives no delivery confirmation of its own, so this is the only
+        # signal a caller gets that the message actually arrived at all.
+        try:
+            result = await handler(msg.get("payload"))
+            await self._send_result(msg, result=result)
+        except Exception as e:
+            await self._send_result(msg, error=str(e))
+
+    def _handle_reply(self, raw: bytes) -> None:
+        try:
+            msg = json.loads(raw.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return
+        fut = self._pending.get(msg.get("correlation_id"))
+        if fut is None or fut.done():
+            return  # nobody waiting -- timed out already, a dupe, or a
+            # second handler's reply to the same correlation_id (see
+            # call()'s docstring: first reply wins, rest are dropped)
+        if msg.get("status") == 202:
+            return  # just the accept-ack; keep waiting for the real result
+        if msg.get("error") is not None:
+            fut.set_exception(RadioDishError(msg["error"]))
+        else:
+            fut.set_result(msg.get("result"))
+
+    async def _send_status(self, msg: dict, status: int) -> None:
+        target = msg.get("callback_target")
+        if not target:
+            return
+        self.radish.broadcast(
+            json.dumps({"correlation_id": msg.get("correlation_id"), "status": status}).encode(),
+            group=target,
+        )
+
+    async def _send_result(self, msg: dict, result=None, error=None) -> None:
+        target = msg.get("callback_target")
+        if not target:
+            return
+        self.radish.broadcast(
+            json.dumps(
+                {"correlation_id": msg.get("correlation_id"), "result": result, "error": error}
+            ).encode(),
+            group=target,
+        )
+
+    # ---- sending to other actors ------------------------------------------
+
+    def send(self, group: str, payload=None, correlation_id: Optional[str] = None) -> str:
+        """Fire a message at `group`. Fans out to every actor (and every
+        locally-registered handler on each) currently wired and listening
+        on that exact group. Returns the correlation_id immediately without
+        waiting for any reply -- use call() to await one.
+
+        Registers interest in `group` automatically if this is the first
+        time it's been reached (see _ensure_interest) -- no depends_on
+        needed up front. This send itself may still miss its target if the
+        resulting wiring hasn't finished yet; call() handles that with
+        retries, but send() is fire-and-forget by design, so a caller that
+        cares whether THIS particular send lands has to resend it
+        themselves, the same as always."""
+        self._ensure_interest(group)
+        correlation_id = correlation_id or uuid.uuid4().hex
+        self.radish.broadcast(
+            json.dumps(
+                {
+                    "payload": payload,
+                    "callback_target": self._reply_group(),
+                    "correlation_id": correlation_id,
+                }
+            ).encode(),
+            group=group,
+        )
+        return correlation_id
+
+    async def call(
+        self,
+        group: str,
+        payload=None,
+        timeout: Optional[float] = None,
+        retry_interval: Optional[float] = 0.5,
+    ):
+        """
+        send() and await the matching reply, matched by correlation_id. If
+        more than one handler matched `group`, resolves to whichever
+        replies first; later ones are silently dropped. Raises
+        asyncio.TimeoutError if nothing comes back in time.
+
+        Retries by default: a single UDP datagram can genuinely go missing
+        even in normal operation -- not just from packet loss, but because
+        it can legitimately be sent before a peer's reciprocal wiring has
+        finished (two AutoWirers converging on each other isn't
+        instantaneous or synchronized), and nothing resends a dropped
+        datagram on its own. call() resends the same message, same
+        correlation_id, every `retry_interval` seconds until a reply
+        arrives or `timeout` elapses. Pass retry_interval=None to send
+        exactly once instead.
+
+        This makes call() "at least once," not "exactly once": there's no
+        receiver-side deduplication of correlation_ids, so if a resend
+        arrives after the first attempt already reached the handler (its
+        reply was just what got lost, not the request), the handler runs
+        twice. Fine for idempotent handlers (most reads, "ping", cache
+        invalidation); if you're calling something that must not run twice
+        (charging a card), pass retry_interval=None and handle the
+        possible loss yourself, or ensure your handler is idempotent on
+        correlation_id — that dedup layer doesn't exist here yet.
+
+        Also registers interest in `group` automatically if this is the
+        first time it's been reached (see _ensure_interest) -- combined
+        with the retry above, this is what makes depends_on genuinely
+        optional: the first call() to a brand new group declares interest
+        on the fly, then just keeps resending while AutoWirer catches up
+        on its own poll cycle, arriving once wiring completes.
+        """
+        self._ensure_interest(group)
+        loop = asyncio.get_running_loop()
+        correlation_id = uuid.uuid4().hex
+        fut = loop.create_future()
+        self._pending[correlation_id] = fut
+        self.send(group, payload, correlation_id=correlation_id)
+
+        async def _resend_loop():
+            try:
+                while True:
+                    await asyncio.sleep(retry_interval)
+                    if fut.done():
+                        return
+                    self.send(group, payload, correlation_id=correlation_id)
+            except asyncio.CancelledError:
+                pass
+
+        resend_task = asyncio.ensure_future(_resend_loop()) if retry_interval is not None else None
+        try:
+            return await asyncio.wait_for(fut, timeout)
+        finally:
+            if resend_task:
+                resend_task.cancel()
+            self._pending.pop(correlation_id, None)
+
+    async def close(self) -> None:
+        if self._run_task:
+            self._run_task.cancel()
+        if self.wirer:
+            await self.wirer.stop()
+        if self.discoverer:
+            await self.discoverer.stop()
+        if self.radish:
+            await self.radish.close()

radiodish_actor-1.0.0/src/decorators.py

@@ -0,0 +1,36 @@
+"""
+radioactor/decorators.py — @expose: marks a method as network-callable. Pure
+metadata; see radioactor.base.Actor for how the tags get read and dispatched.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional, Union
+
+
+def expose(groups: Optional[Union[str, Iterable[str]]] = None):
+    """
+    Mark a method as network-callable. `groups` (a string, an iterable of
+    strings, or omitted) lists extra topics this handler should ALSO fire
+    on, on top of its two automatic defaults: its own function name, and
+    the empty group "" (see module docstring for what each implies).
+    Pure metadata -- nothing happens at decoration or call time beyond
+    tagging the function; Actor._discover_exposed_methods() reads these
+    tags via reflection when an instance registers.
+    """
+    if groups is None:
+        extra: tuple = ()
+    elif isinstance(groups, str):
+        extra = (groups,)
+    else:
+        extra = tuple(groups)
+
+    def decorator(func):
+        func._exposed = True
+        # de-dupe while preserving order, in case someone passes their own
+        # name or "" explicitly too
+        func._exposed_groups = tuple(dict.fromkeys((*extra, func.__name__, "")))
+        return func
+
+    return decorator
+

radiodish_actor-1.0.0/tests/test_actor.py

@@ -0,0 +1,196 @@
+import asyncio
+import warnings
+
+from radioactor import Actor, expose
+
+
+class Echo(Actor):
+    id = "echo"
+
+    @expose()
+    async def ping(self, payload):
+        return {"pong": payload}
+
+    @expose(groups=["shout_topic"])
+    async def shout(self, payload):
+        return str(payload).upper()
+
+
+class Caller(Actor):
+    """A pure caller, no @expose'd methods -- the recommended way to write
+    one now: a named subclass, even an empty one, rather than instantiating
+    Actor directly (see test_direct_instantiation_warns)."""
+    pass
+
+
+async def _wait_until(predicate, timeout=5.0, interval=0.1):
+    deadline = asyncio.get_event_loop().time() + timeout
+    while asyncio.get_event_loop().time() < deadline:
+        if predicate():
+            return True
+        await asyncio.sleep(interval)
+    return predicate()
+
+
+async def test_call_by_function_name():
+    """No depends_on anywhere here -- call() discovers 'ping' on its own,
+    the first time it's asked to reach it, and its built-in retry carries
+    the caller through the wiring latency. This is the default path now,
+    not a special case."""
+    echo = await Echo().register(port_range=(25000, 25100), discovery_port=27001)
+    caller = await Caller().register(port_range=(25000, 25100), discovery_port=27001)
+
+    assert caller._depends_on == set(), "should start with zero pre-declared dependencies"
+    result = await caller.call("ping", {"x": 1}, timeout=3.0)
+    assert result == {"pong": {"x": 1}}, result
+    assert "ping" in caller._depends_on, "call() should have auto-registered interest"
+
+    await caller.close()
+    await echo.close()
+    print("test_call_by_function_name: PASS")
+
+
+async def test_explicit_group_alias():
+    echo = await Echo().register(port_range=(25100, 25200), discovery_port=27002)
+    caller = await Caller().register(port_range=(25100, 25200), discovery_port=27002)
+
+    # addressed via the *explicit* group, not the function name "shout" --
+    # again with zero depends_on, relying purely on dynamic discovery
+    result = await caller.call("shout_topic", "hi", timeout=3.0)
+    assert result == "HI", result
+
+    await caller.close()
+    await echo.close()
+    print("test_explicit_group_alias: PASS")
+
+
+async def test_explicit_depends_on_still_works():
+    """depends_on at construction is optional now, not required -- but
+    still works, as a way to pre-warm the wiring before the first call
+    rather than paying that latency on it. Confirms it the direct way:
+    wiring should already be in progress before any call() is made."""
+    echo = await Echo().register(port_range=(25150, 25180), discovery_port=27009)
+    caller = await Caller(depends_on=["ping"]).register(port_range=(25150, 25180), discovery_port=27009)
+
+    ok = await _wait_until(lambda: len(caller.wirer.wired_peers) >= 1)
+    assert ok, "pre-declared depends_on should wire before any call() happens"
+
+    result = await caller.call("ping", {"y": 2}, timeout=3.0)
+    assert result == {"pong": {"y": 2}}, result
+
+    await caller.close()
+    await echo.close()
+    print("test_explicit_depends_on_still_works: PASS")
+
+
+async def test_empty_group_broadcasts_to_every_handler():
+    echo = await Echo().register(port_range=(25200, 25300), discovery_port=27003)
+    caller = await Caller().register(port_range=(25200, 25300), discovery_port=27003)
+
+    # send() (not call()) since BOTH ping and shout will independently
+    # reply to the same correlation_id -- we just want to see that both
+    # handlers actually ran, not race for "whichever reply wins".
+    seen = []
+    orig_ping, orig_shout = echo.ping, echo.shout
+
+    async def tracking_ping(payload):
+        seen.append("ping")
+        return await orig_ping(payload)
+
+    async def tracking_shout(payload):
+        seen.append("shout")
+        return await orig_shout(payload)
+
+    echo._groups_to_handlers[""] = [tracking_ping, tracking_shout]
+
+    # send() has no reply to retry against (unlike call(), which resends
+    # internally), so a caller who cares whether a fire-and-forget
+    # broadcast actually landed resends it themselves. The FIRST send()
+    # call also auto-registers interest in "" (see _ensure_interest) --
+    # zero depends_on needed here either, same as everywhere else in this
+    # file now.
+    deadline = asyncio.get_event_loop().time() + 3.0
+    while asyncio.get_event_loop().time() < deadline:
+        if set(seen) == {"ping", "shout"}:
+            break
+        caller.send("", payload="hello")
+        await asyncio.sleep(0.2)
+    ok = set(seen) == {"ping", "shout"}
+    assert ok, f"expected both handlers to fire on the empty group, got {seen}"
+
+    await caller.close()
+    await echo.close()
+    print("test_empty_group_broadcasts_to_every_handler: PASS")
+
+
+async def test_call_times_out_when_nobody_listens():
+    caller = await Caller().register(port_range=(25300, 25400), discovery_port=27004)
+    try:
+        await caller.call("nobody_home", None, timeout=0.5)
+        raised = False
+    except asyncio.TimeoutError:
+        raised = True
+    assert raised, "expected a timeout calling a group with no subscribers"
+    await caller.close()
+    print("test_call_times_out_when_nobody_listens: PASS")
+
+
+async def test_dynamic_expose_and_dependency():
+    echo = await Echo().register(port_range=(25400, 25500), discovery_port=27005)
+
+    class Bare(Actor):
+        pass
+
+    caller = await Bare().register(port_range=(25400, 25500), discovery_port=27005)
+
+    await asyncio.sleep(1.0)
+    assert len(caller.wirer.wired_peers) == 0, "shouldn't be wired without any shared interest"
+
+    @expose(groups=["whisper_topic"])
+    async def whisper(self, payload):
+        return f"...{payload}..."
+
+    echo.add_endpoint(whisper.__get__(echo))
+    caller.add_dependency("whisper_topic")
+
+    ok = await _wait_until(lambda: len(caller.wirer.wired_peers) >= 1)
+    assert ok, "caller never wired after dynamic dependency + dynamic expose"
+
+    result = await caller.call("whisper_topic", "secret", timeout=3.0)
+    assert result == "...secret...", result
+
+    await caller.close()
+    await echo.close()
+    print("test_dynamic_expose_and_dependency: PASS")
+
+
+async def test_direct_instantiation_warns():
+    """Instantiating Actor directly should warn, nudging toward a named
+    subclass instead; a subclass -- even an empty one -- should not."""
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        Actor()
+        assert len(caught) == 1, f"expected exactly one warning, got {len(caught)}"
+        assert issubclass(caught[0].category, UserWarning)
+        assert "subclass" in str(caught[0].message)
+
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        Caller()
+        assert len(caught) == 0, f"a named subclass should not warn, got {caught}"
+
+    print("test_direct_instantiation_warns: PASS")
+
+
+async def main():
+    await test_call_by_function_name()
+    await test_explicit_group_alias()
+    await test_explicit_depends_on_still_works()
+    await test_empty_group_broadcasts_to_every_handler()
+    await test_call_times_out_when_nobody_listens()
+    await test_dynamic_expose_and_dependency()
+    await test_direct_instantiation_warns()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())