radiodish 1.0.0__tar.gz

radiodish-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-1.0.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: radiodish
+Version: 1.0.0
+Summary: A standalone, async RADIO-DISH implementation over UDP (ZeroMQ RFC 48), with automatic peer discovery and autowiring.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pow4you/radiodish
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# radiodish
+
+A standalone, dependency-free, **async** implementation of ZeroMQ's
+[RADIO-DISH pattern](https://rfc.zeromq.org/spec/48/), built directly on
+`asyncio`'s UDP transport rather than on libzmq/pyzmq — plus automatic
+port assignment, peer discovery, and autowiring on top.
+
+- **Standalone**: pure Python stdlib (`asyncio`, `struct`, `collections`,
+  `socket`). No libzmq, no third-party dependencies at all.
+- **UDP**: each RADIO and DISH is a plain UDP endpoint. A UDP datagram is
+  already an atomic, non-multipart unit, which lines up naturally with
+  RFC 48's "no multipart messages" requirement for the thread-safe
+  socket family.
+- **Async**: `RadioSocket.send()` never blocks; `DishSocket.recv()` is an
+  `await`-able coroutine fed by `asyncio`'s event loop — no threads.
+
+Looking for the actor-model layer built on top of this? That's a separate
+package, [`radiodish-actor`](../radiodish-actor/), which depends on this
+one.
+
+## Install
+
+```
+pip install radiodish
+```
+
+For local/editable development against this repo specifically, see the
+workspace root README — this package is a member of a `uv` workspace.
+
+## Documentation
+
+Full documentation, with the reasoning behind the design decisions (not
+just the API surface), lives in [`docs/`](docs/index.md):
+
+- **[docs/index.md](docs/index.md)** — quick start, API sketch, package layout
+- **[docs/protocol.md](docs/protocol.md)** — the RFC 48 wire format and how this implementation maps to it
+- **[docs/autowire.md](docs/autowire.md)** — automatic port assignment, peer discovery (two tiers: same-machine and LAN), and autowiring; the real bugs found while building it and how they were fixed
+- **[docs/examples/](docs/examples/)** — runnable examples, each documented with what it demonstrates and why
+
+## 30-second version
+
+```python
+from radish import RadioSocket, DishSocket
+
+radio = await RadioSocket().bind("0.0.0.0", 9000)
+radio.connect("127.0.0.1", 9001)
+await radio.send(b"hello", group="news")
+
+dish = await DishSocket().bind("0.0.0.0", 9001)
+dish.connect("127.0.0.1", 9000)
+dish.join("news")
+group, payload = await dish.recv()
+```
+
+Or skip manual wiring entirely:
+
+```python
+from radish.autowire import autowired_radish
+
+radish, discoverer, wirer = await autowired_radish(groups=["sensors"])
+radish.broadcast("21.5C", group="sensors")
+group, payload = await radish.recv()
+```
+
+See [docs/index.md](docs/index.md) for the full walkthrough.

radiodish-1.0.0/README.md

@@ -0,0 +1,65 @@
+# radiodish
+
+A standalone, dependency-free, **async** implementation of ZeroMQ's
+[RADIO-DISH pattern](https://rfc.zeromq.org/spec/48/), built directly on
+`asyncio`'s UDP transport rather than on libzmq/pyzmq — plus automatic
+port assignment, peer discovery, and autowiring on top.
+
+- **Standalone**: pure Python stdlib (`asyncio`, `struct`, `collections`,
+  `socket`). No libzmq, no third-party dependencies at all.
+- **UDP**: each RADIO and DISH is a plain UDP endpoint. A UDP datagram is
+  already an atomic, non-multipart unit, which lines up naturally with
+  RFC 48's "no multipart messages" requirement for the thread-safe
+  socket family.
+- **Async**: `RadioSocket.send()` never blocks; `DishSocket.recv()` is an
+  `await`-able coroutine fed by `asyncio`'s event loop — no threads.
+
+Looking for the actor-model layer built on top of this? That's a separate
+package, [`radiodish-actor`](../radiodish-actor/), which depends on this
+one.
+
+## Install
+
+```
+pip install radiodish
+```
+
+For local/editable development against this repo specifically, see the
+workspace root README — this package is a member of a `uv` workspace.
+
+## Documentation
+
+Full documentation, with the reasoning behind the design decisions (not
+just the API surface), lives in [`docs/`](docs/index.md):
+
+- **[docs/index.md](docs/index.md)** — quick start, API sketch, package layout
+- **[docs/protocol.md](docs/protocol.md)** — the RFC 48 wire format and how this implementation maps to it
+- **[docs/autowire.md](docs/autowire.md)** — automatic port assignment, peer discovery (two tiers: same-machine and LAN), and autowiring; the real bugs found while building it and how they were fixed
+- **[docs/examples/](docs/examples/)** — runnable examples, each documented with what it demonstrates and why
+
+## 30-second version
+
+```python
+from radish import RadioSocket, DishSocket
+
+radio = await RadioSocket().bind("0.0.0.0", 9000)
+radio.connect("127.0.0.1", 9001)
+await radio.send(b"hello", group="news")
+
+dish = await DishSocket().bind("0.0.0.0", 9001)
+dish.connect("127.0.0.1", 9000)
+dish.join("news")
+group, payload = await dish.recv()
+```
+
+Or skip manual wiring entirely:
+
+```python
+from radish.autowire import autowired_radish
+
+radish, discoverer, wirer = await autowired_radish(groups=["sensors"])
+radish.broadcast("21.5C", group="sensors")
+group, payload = await radish.recv()
+```
+
+See [docs/index.md](docs/index.md) for the full walkthrough.

radiodish-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "radiodish"
+version = "1.0.0"
+description = "A standalone, async RADIO-DISH implementation over UDP (ZeroMQ RFC 48), with automatic peer discovery and autowiring."
+requires-python = ">=3.9"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: System :: Networking",
+]
+
+[project.urls]
+Homepage = "https://github.com/pow4you/radiodish"
+
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["radish", "radish._internal", "radish.autowire"]
+
+[tool.setuptools.package-dir]
+radish = "src"
+"radish._internal" = "src/_internal"
+"radish.autowire" = "src/autowire"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+

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

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: radiodish
+Version: 1.0.0
+Summary: A standalone, async RADIO-DISH implementation over UDP (ZeroMQ RFC 48), with automatic peer discovery and autowiring.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pow4you/radiodish
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# radiodish
+
+A standalone, dependency-free, **async** implementation of ZeroMQ's
+[RADIO-DISH pattern](https://rfc.zeromq.org/spec/48/), built directly on
+`asyncio`'s UDP transport rather than on libzmq/pyzmq — plus automatic
+port assignment, peer discovery, and autowiring on top.
+
+- **Standalone**: pure Python stdlib (`asyncio`, `struct`, `collections`,
+  `socket`). No libzmq, no third-party dependencies at all.
+- **UDP**: each RADIO and DISH is a plain UDP endpoint. A UDP datagram is
+  already an atomic, non-multipart unit, which lines up naturally with
+  RFC 48's "no multipart messages" requirement for the thread-safe
+  socket family.
+- **Async**: `RadioSocket.send()` never blocks; `DishSocket.recv()` is an
+  `await`-able coroutine fed by `asyncio`'s event loop — no threads.
+
+Looking for the actor-model layer built on top of this? That's a separate
+package, [`radiodish-actor`](../radiodish-actor/), which depends on this
+one.
+
+## Install
+
+```
+pip install radiodish
+```
+
+For local/editable development against this repo specifically, see the
+workspace root README — this package is a member of a `uv` workspace.
+
+## Documentation
+
+Full documentation, with the reasoning behind the design decisions (not
+just the API surface), lives in [`docs/`](docs/index.md):
+
+- **[docs/index.md](docs/index.md)** — quick start, API sketch, package layout
+- **[docs/protocol.md](docs/protocol.md)** — the RFC 48 wire format and how this implementation maps to it
+- **[docs/autowire.md](docs/autowire.md)** — automatic port assignment, peer discovery (two tiers: same-machine and LAN), and autowiring; the real bugs found while building it and how they were fixed
+- **[docs/examples/](docs/examples/)** — runnable examples, each documented with what it demonstrates and why
+
+## 30-second version
+
+```python
+from radish import RadioSocket, DishSocket
+
+radio = await RadioSocket().bind("0.0.0.0", 9000)
+radio.connect("127.0.0.1", 9001)
+await radio.send(b"hello", group="news")
+
+dish = await DishSocket().bind("0.0.0.0", 9001)
+dish.connect("127.0.0.1", 9000)
+dish.join("news")
+group, payload = await dish.recv()
+```
+
+Or skip manual wiring entirely:
+
+```python
+from radish.autowire import autowired_radish
+
+radish, discoverer, wirer = await autowired_radish(groups=["sensors"])
+radish.broadcast("21.5C", group="sensors")
+group, payload = await radish.recv()
+```
+
+See [docs/index.md](docs/index.md) for the full walkthrough.

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

@@ -0,0 +1,27 @@
+LICENSE
+README.md
+pyproject.toml
+radiodish.egg-info/PKG-INFO
+radiodish.egg-info/SOURCES.txt
+radiodish.egg-info/dependency_links.txt
+radiodish.egg-info/top_level.txt
+src/__init__.py
+src/dish.py
+src/errors.py
+src/protocol.py
+src/radio.py
+src/transport.py
+src/unified.py
+src/_internal/__init__.py
+src/_internal/errors.py
+src/_internal/groups.py
+src/autowire/__init__.py
+src/autowire/compose.py
+src/autowire/discovery.py
+src/autowire/local_discovery.py
+src/autowire/network.py
+src/autowire/wiring.py
+tests/test_autowire.py
+tests/test_network_resilience.py
+tests/test_radiodish.py
+tests/test_radish_socket.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+radish

radiodish-1.0.0/setup.cfg

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

radiodish-1.0.0/src/__init__.py

@@ -0,0 +1,38 @@
+"""
+radish — a standalone, asyncio-native RADIO/DISH implementation over UDP.
+
+This is an independent implementation of the pattern described in ZeroMQ
+RFC 48 (https://rfc.zeromq.org/spec/48/). It does not depend on libzmq or
+pyzmq at all — it's built directly on asyncio's UDP transport.
+
+Package layout:
+    radish.errors     RadioDishError, InvalidGroupError (re-exported from radish._internal.errors)
+    radish.protocol    wire format: encode_frame/decode_frame, MSG_DATA/JOIN/LEAVE
+    radish.transport    shared plumbing: _UDPProtocol, _BoundedDropQueue, _Peer
+    radish.radio         RadioSocket (RFC 48's RADIO type)
+    radish.dish            DishSocket (RFC 48's DISH type)
+    radish.unified           RadishSocket (radio+dish combined, one object)
+    radish.autowire            automatic port assignment, peer discovery, and
+                                 peer connection on top of RadishSocket
+
+For most uses, everything below is enough:
+
+    from radish import RadioSocket, DishSocket, RadishSocket
+    from radish.autowire import autowired_radish
+"""
+
+from radish.errors import RadioDishError, InvalidGroupError
+from radish.protocol import (
+    MSG_DATA, MSG_JOIN, MSG_LEAVE, MAX_GROUP_LEN, GroupLike, Address,
+    encode_frame, decode_frame,
+)
+from radish.radio import RadioSocket
+from radish.dish import DishSocket
+from radish.unified import RadishSocket
+
+__all__ = [
+    "RadioSocket", "DishSocket", "RadishSocket",
+    "RadioDishError", "InvalidGroupError",
+    "MSG_DATA", "MSG_JOIN", "MSG_LEAVE", "MAX_GROUP_LEN", "GroupLike", "Address",
+    "encode_frame", "decode_frame",
+]

radiodish-1.0.0/src/_internal/__init__.py

@@ -0,0 +1,19 @@
+"""
+radish._internal — private implementation details of the radish package.
+Leading underscore means exactly that: not public API, no stability
+promise, nothing outside radish itself should import from here (and
+nothing does -- radioactor only ever reaches RadioDishError via
+`from radish import RadioDishError`, the public re-export).
+"""
+
+from radish._internal.errors import RadioDishError, InvalidGroupError
+from radish._internal.groups import GroupLike, MAX_GROUP_LEN, normalize_group, groups_as_str
+
+__all__ = [
+    "RadioDishError",
+    "InvalidGroupError",
+    "GroupLike",
+    "MAX_GROUP_LEN",
+    "normalize_group",
+    "groups_as_str",
+]

radiodish-1.0.0/src/_internal/errors.py

@@ -0,0 +1,16 @@
+"""
+radish/_internal/errors.py — the exception hierarchy for the radish
+package. Private subpackage (leading underscore) -- not part of the
+public API, and nothing outside radish itself needs it, including
+radioactor, which only ever imports RadioDishError via `from radish
+import RadioDishError` (radish.errors re-exports these under the public
+namespace for that purpose).
+"""
+
+
+class RadioDishError(Exception):
+    """Base error for the whole project."""
+
+
+class InvalidGroupError(RadioDishError):
+    """Raised when a group name violates RFC 48's length constraint (0-255 bytes)."""

radiodish-1.0.0/src/_internal/groups.py

@@ -0,0 +1,50 @@
+"""
+radish/_internal/groups.py — group-name handling shared between two
+different representations of the same concept within radish itself:
+
+- radish.protocol needs a STRICT, wire-format validator: a group is
+  0-255 raw bytes, full stop, because that's what RFC 48's ABNF requires
+  and what the frame header's single length byte can represent.
+- radish.autowire.discovery needs a LOOSE, JSON-safe converter: group
+  names have to survive being embedded in a discovery announcement
+  payload, so bytes get decoded to str (JSON can't carry raw bytes) and
+  anything already a plain string passes through untouched.
+
+Both directions live here instead of being duplicated (or, worse, subtly
+diverging) between the two modules that need them.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Union
+
+from radish._internal.errors import InvalidGroupError
+
+GroupLike = Union[str, bytes]
+MAX_GROUP_LEN = 255
+
+
+def normalize_group(group: GroupLike) -> bytes:
+    """Strict validator for the wire protocol: str or bytes in, exactly
+    validated bytes out. Raises InvalidGroupError for anything else or
+    anything over RFC 48's 255-byte limit."""
+    if isinstance(group, str):
+        group = group.encode("utf-8")
+    if not isinstance(group, (bytes, bytearray)):
+        raise InvalidGroupError(f"group must be str or bytes, got {type(group)!r}")
+    if len(group) > MAX_GROUP_LEN:
+        raise InvalidGroupError(
+            f"group is {len(group)} bytes, RFC 48 allows at most {MAX_GROUP_LEN}"
+        )
+    return bytes(group)
+
+
+def groups_as_str(groups: Iterable) -> tuple[str, ...]:
+    """Loose converter for discovery announcements: decodes any bytes
+    entries to str (JSON can't carry raw bytes), passes plain strings
+    through untouched. Used for the groups/interest lists that go into a
+    Discoverer's JSON payload, not for wire-protocol frame encoding."""
+    out = []
+    for g in groups:
+        out.append(g.decode("utf-8") if isinstance(g, (bytes, bytearray)) else g)
+    return tuple(out)

radiodish-1.0.0/src/autowire/__init__.py

@@ -0,0 +1,31 @@
+"""
+radish.autowire — automatic port assignment, peer discovery, and peer
+connection on top of radish.RadishSocket.
+
+    radish.autowire.network             find_free_port_pair, detect_local_addresses
+    radish.autowire.local_discovery      the "my machine" file-based tier
+    radish.autowire.discovery             the "my LAN" multicast tier, and Discoverer
+    radish.autowire.wiring                  AutoWirer -- the actual autowiring
+    radish.autowire.compose                  autowired_radish() -- one-call entrypoint
+
+For most uses:
+
+    from radish.autowire import autowired_radish
+    radish, discoverer, wirer = await autowired_radish(groups=["sensors"])
+"""
+
+from radish.autowire.network import find_free_port_pair, detect_local_addresses
+from radish.autowire.discovery import Discoverer, PeerInfo, MULTICAST_GROUP, DEFAULT_DISCOVERY_PORT
+from radish.autowire.wiring import AutoWirer
+from radish.autowire.compose import autowired_radish
+
+__all__ = [
+    "autowired_radish",
+    "Discoverer",
+    "AutoWirer",
+    "PeerInfo",
+    "find_free_port_pair",
+    "detect_local_addresses",
+    "MULTICAST_GROUP",
+    "DEFAULT_DISCOVERY_PORT",
+]

radiodish-1.0.0/src/autowire/compose.py

@@ -0,0 +1,91 @@
+"""
+radish/autowire/compose.py — autowired_radish(): "on the creation of a
+radish, autowire its peers." One call that finds ports, binds, joins
+groups, and starts discovery + autowiring together.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Iterable, Optional
+
+from radish.unified import RadishSocket
+from radish.autowire.network import find_free_port_pair, detect_local_addresses
+from radish.autowire.discovery import Discoverer, DEFAULT_DISCOVERY_PORT
+from radish.autowire.wiring import AutoWirer
+
+
+async def autowired_radish(
+    host: Optional[str] = None,
+    groups: Iterable = (),
+    interest_groups: Optional[Iterable] = None,
+    port_range: tuple[int, int] = (20000, 40000),
+    discovery_port: int = DEFAULT_DISCOVERY_PORT,
+    seeds: Iterable[tuple[str, int]] = (),
+    node_id: Optional[str] = None,
+    autowire_poll_interval: float = 0.3,
+) -> tuple[RadishSocket, Discoverer, AutoWirer]:
+    """
+    One call, "on the creation of a radish": finds a free port pair, binds a
+    RadishSocket on it, joins `groups`, starts announcing/listening for
+    peers, and continuously connects to any discovered peer whose groups
+    overlap `interest_groups` (defaults to the same as `groups` — "only wire
+    me to peers who care about what I care about").
+
+    Leave `host` unset for the normal case: binds on "0.0.0.0" (every local
+    interface at once, loopback included -- always bindable, no guessing
+    needed) and announces every address this machine actually has
+    (detect_local_addresses(): loopback first, then whatever LAN-facing
+    addresses this machine's own hostname resolves to). Peers connect back
+    over whichever of those is actually reachable from where they sit --
+    loopback for a same-machine peer, a LAN address for one elsewhere on
+    the network. Pass an explicit `host` only to override both bind and
+    announce with one specific address (e.g. pairing a container-internal
+    address with `seeds=` on the other end).
+
+    Returns (radish, discoverer, autowirer). Hold onto discoverer/autowirer
+    if you want to inspect known/wired peers later; to tear everything down,
+    stop() the autowirer and discoverer, then close() the radish (see
+    example_autowire.py).
+    """
+    if host is not None:
+        bind_host = host
+        announce_addresses = [host]
+        try:
+            port, radio_sock, dish_sock = find_free_port_pair(bind_host, *port_range)
+        except RuntimeError:
+            if bind_host == "127.0.0.1":
+                raise
+            # an explicitly-given host turned out not to be bindable --
+            # fall back to localhost rather than failing outright.
+            bind_host = "127.0.0.1"
+            announce_addresses = [bind_host]
+            port, radio_sock, dish_sock = find_free_port_pair(bind_host, *port_range)
+    else:
+        bind_host = "0.0.0.0"
+        announce_addresses = detect_local_addresses()
+        port, radio_sock, dish_sock = find_free_port_pair(bind_host, *port_range)
+
+    radish = RadishSocket()
+    await radish.bind(bind_host, port, radio_sock=radio_sock, dish_sock=dish_sock)
+    for g in groups:
+        radish.join(g)
+
+    node_id = node_id or uuid.uuid4().hex[:12]
+    interest = groups if interest_groups is None else interest_groups
+    discoverer = await Discoverer(
+        node_id=node_id,
+        addresses=announce_addresses,
+        port=port,
+        groups=groups,
+        interest=interest,
+        discovery_port=discovery_port,
+        seeds=seeds,
+        auto_refresh_addresses=(host is None),
+    ).start()
+
+    wirer = await AutoWirer(radish, discoverer, interest_groups=interest).start(
+        poll_interval=autowire_poll_interval
+    )
+
+    return radish, discoverer, wirer