objectspell 0.1.0__py3-none-any.whl

objectspell/__init__.py

@@ -0,0 +1,13 @@
+"""
+ObjectSpell: a small asyncio framework for wiring components together with signals.
+
+The public API lives in `objectspell.struct`.
+"""
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("objectspell")
+except PackageNotFoundError:  # running from a source tree, not an install
+    __version__ = "0.0.0.dev0"
+
+__all__ = ("__version__",)

objectspell/connector.py

@@ -0,0 +1,123 @@
+"""
+Starts and stops a topology, after checking that its wiring makes sense.
+"""
+import inspect
+from contextlib import AsyncExitStack
+from typing import cast
+
+# Imported directly rather than via `objectspell.struct`: struct imports this module, so
+# going back through it would make struct's own import order load-bearing.
+from objectspell.emitter import Emitter as BaseEmitter
+from objectspell.state import State
+
+
+class Emitter(BaseEmitter):
+    """
+    The two signals the Connector sends: one once everything is wired, one to shut down.
+    """
+    async def connected(self) -> None:
+        pass
+
+    async def disconnected(self) -> None:
+        pass
+
+
+class Connector(State, Emitter):
+    """
+    Starts and stops a topology.
+
+    `connect` opens every State's listener loop, wires emitters to receivers, then emits
+    `connected`. `disconnect` emits `disconnected`, which every State listens for, so that
+    single signal shuts the whole topology down.
+    """
+
+    async def connect(self, states: list[State]) -> None:
+        """
+        Check the wiring, start every State, link senders to listeners, then emit `connected`.
+
+        Does not return until the topology has shut down, so it is normally the whole program.
+        """
+        states.append(self)
+
+        emitters: dict[str, BaseEmitter] = {}
+        routes: dict[str, set[str]] = {}
+
+        for state in states:
+            state_class = type(state)
+
+            for base_class in state_class.__bases__:
+                if BaseEmitter in base_class.__bases__:
+                    if state_class.__name__ in emitters:
+                        raise RuntimeError(
+                            f"Two connected States are both named {state_class.__name__!r}. "
+                            f"Routing is by class name, so State names must be unique."
+                        )
+
+                    # The base-class check above establishes that this State is an Emitter.
+                    emitters[state_class.__name__] = cast(BaseEmitter, state)
+                    routes[state_class.__name__] = self._o9l_signal_routes(state_class=state_class)
+
+        # Checked before any listener starts. A broken topology never delivers the signal that
+        # stops the listeners, so raising once they are running would hang in __aexit__.
+        self._o9l_check_wiring(states=states, routes=routes)
+
+        async with AsyncExitStack() as stack:
+            for state in states:
+                await stack.enter_async_context(state)
+
+            for state in states:
+                state.o9l_connecting(emitters)
+
+            await self.connected()
+
+    async def disconnect(self) -> None:
+        """
+        Emit `disconnected`. Every State listens for it, so this stops all of them.
+        """
+        await self.disconnected()
+
+    def _o9l_signal_routes(self, state_class: type[State]) -> set[str]:
+        """
+        The signals a State sends: the public async methods declared by its Emitter base.
+
+        Read from the base class, not from the State itself, because Emitter.__new__
+        overwrites those methods on the State with generated senders.
+        """
+        routes: set[str] = set()
+
+        for base_class in state_class.__bases__:
+            if BaseEmitter in base_class.__bases__:
+                routes.update(
+                    attr_name
+                    for (attr_name, attr_ref) in base_class.__dict__.items()
+                    if not attr_name.startswith("_") and inspect.iscoroutinefunction(attr_ref)
+                )
+
+        return routes
+
+    def _o9l_check_wiring(self, states: list[State], routes: dict[str, set[str]]) -> None:
+        """
+        Verify the topology before any signal moves.
+
+        Both problems caught here would otherwise surface far from their cause: a receiver
+        named after nothing leaves the system waiting for a signal that never arrives, and a
+        receiver missing a route fails only once that route is used, often during shutdown.
+        """
+        for state in states:
+            state_name = type(state).__name__
+
+            for (channel, receiver_class) in state.o9l_receiver_classes().items():
+                if channel not in routes:
+                    channels = ", ".join(sorted(routes)) or "none"
+                    raise RuntimeError(
+                        f"{state_name} declares a receiver named {channel!r}, but no connected State "
+                        f"emits on that channel. A receiver class must be named exactly after the "
+                        f"State whose signals it handles. Connected channels: {channels}."
+                    )
+
+                if missing := sorted(routes[channel] - receiver_class.__dict__.keys()):
+                    raise RuntimeError(
+                        f"{state_name}.{channel} does not handle every signal on channel "
+                        f"{channel!r}: missing {', '.join(missing)}. A receiver must define one "
+                        f"method per signal its channel declares."
+                    )

objectspell/emitter.py

@@ -0,0 +1,69 @@
+"""
+The sending half of the wiring: turns declared async methods into signal senders.
+"""
+import inspect
+from typing import Any
+
+from objectspell.receiver import Receivable
+from objectspell.types import Signal, SignalSender
+
+
+class Emitter:
+    """
+    A base class for signal emitters. Subclasses can define async methods that act as signal triggers.
+    When triggered, the Emitter sends a Signal to all connected Receivables.
+    """
+    _o9l_receivables: list[Receivable]
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> "Emitter":
+        """
+        Replace every public async method declared by the Emitter base with a sender.
+
+        The declared bodies are never run: they only name the signal and its arguments.
+        """
+        for base_class in cls.__bases__:
+            if Emitter in base_class.__bases__:
+                for (attr_name, attr_ref) in base_class.__dict__.items():
+                    if not attr_name.startswith("_") and inspect.iscoroutinefunction(attr_ref):
+                        setattr(cls, attr_name, cls._o9l_signal_sender(signal_route=attr_name))
+
+        return super().__new__(cls)
+
+    @classmethod
+    def _o9l_signal_sender(cls, signal_route: str) -> SignalSender:
+        """
+        Build the sender that replaces one declared method.
+
+        `cls` is the concrete State being created, so its name becomes the signal's channel.
+        """
+        async def _send(self: Any, **kwargs: Any) -> None:
+            for receivable in self._o9l_receivables:
+                await receivable.o9l_receive(
+                    signal=Signal(
+                        channel=cls.__name__,
+                        route=signal_route,
+                        message=kwargs
+                    )
+                )
+
+        return _send
+
+    def __init__(self) -> None:
+        """
+        Start with nothing connected. The Connector fills this in during `connect`.
+        """
+        super().__init__()
+
+        self._o9l_receivables = []
+
+    def o9l_connect(self, receivable: Receivable) -> None:
+        """
+        Connect a Receivable to this Emitter. The Receivable will receive Signals when this Emitter triggers.
+        """
+        if receivable not in self._o9l_receivables:
+            self._o9l_receivables.append(receivable)
+        else:
+            raise RuntimeError(
+                f"Receivable {receivable.__class__.__name__} already connected "
+                f"to {self.__class__.__name__}"
+            )

objectspell/receiver.py

@@ -0,0 +1,21 @@
+"""
+The receiving half of the wiring: where a signal is delivered, and how handlers are grouped.
+"""
+from objectspell.types import Signal
+
+
+class Receivable:
+    """
+    Anything a Signal can be delivered to. State is the only implementation.
+    """
+    async def o9l_receive(self, signal: Signal) -> None:
+        raise NotImplementedError
+
+
+class Receiver:
+    """
+    Marks a class as a group of signal handlers rather than a component.
+
+    Subclass it alongside the State the handlers belong to, and name the subclass after the
+    State whose signals it handles. That name is the wiring.
+    """

objectspell/state.py

@@ -0,0 +1,178 @@
+"""
+A component: its signal queue, its listener loop, and the receivers routed to it.
+"""
+import asyncio
+import inspect
+from types import TracebackType
+from typing import Any, cast
+
+from objectspell.emitter import Emitter
+from objectspell.receiver import Receivable, Receiver
+from objectspell.types import Signal, SignalHandler
+
+
+class State(Receivable):
+    """
+    A base class for maintaining state and managing signal routing between Emitters and Receivers.
+    It runs an asynchronous listener loop to process incoming signals.
+    """
+    _o9l_receiver_classes: dict[str, type[Receiver]]
+
+    _o9l_queue: asyncio.Queue[Signal]
+    _o9l_is_stopped: bool
+    _o9l_listener: asyncio.Task[None]
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> "State":
+        """
+        Collect this class's Receiver subclasses, keyed by class name -- the channel they listen to.
+
+        Any State that listens to something also listens to the Connector, so it can be told
+        to stop. If no Connector receiver was written, the default one is used.
+        """
+        cls._o9l_receiver_classes = {}
+
+        for sub_class in cls.__subclasses__():
+            if Receiver in sub_class.__bases__:
+                channel = sub_class.__name__
+                cls._o9l_receiver_classes[channel] = cast(type[Receiver], sub_class)
+
+        if cls._o9l_receiver_classes:
+            if "Connector" in cls._o9l_receiver_classes:
+                cls._o9l_enrich_connector(connector_cls=cls._o9l_receiver_classes["Connector"])
+            else:
+                cls._o9l_receiver_classes["Connector"] = Connector
+
+        return super().__new__(cls)
+
+    @classmethod
+    def _o9l_enrich_connector(cls, connector_cls: type[Receiver]) -> None:
+        """
+        Keep the built-in Connector behaviour when a custom Connector receiver overrides it.
+
+        Without this, writing your own `disconnected` would replace the one that stops the
+        listener, and the State would never shut down.
+        """
+        for (attr_name, attr_ref) in Connector.__dict__.items():
+            if (
+                not attr_name.startswith("_")
+                and inspect.iscoroutinefunction(attr_ref)
+                and (signal_handler := connector_cls.__dict__.get(attr_name))
+            ):
+                setattr(
+                    connector_cls,
+                    attr_name,
+                    cls._o9l_extended_signal_handler(signal_handler=signal_handler, extra_handler=attr_ref)
+                )
+
+    @classmethod
+    def _o9l_extended_signal_handler(cls, signal_handler: SignalHandler, extra_handler: SignalHandler) -> SignalHandler:
+        """
+        Chain two handlers into one, running the custom handler before the built-in one.
+        """
+        async def _handle(self: Any, **kwargs: Any) -> None:
+            await signal_handler(self, **kwargs)
+            await extra_handler(self, **kwargs)
+
+        return _handle
+
+    def __init__(self) -> None:
+        """
+        Create the signal queue. The listener that drains it starts on `__aenter__`.
+        """
+        super().__init__()
+
+        self._o9l_queue = asyncio.Queue()
+        self._o9l_is_stopped = False
+
+    async def __aenter__(self) -> "State":
+        """
+        Enter the asynchronous context, starting the signal listener loop if receivers are present.
+        """
+        if self._o9l_receiver_classes:
+            # Start listening for signals
+            self._o9l_listener = asyncio.create_task(self._o9l_listening())
+
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """
+        Exit the asynchronous context, waiting for the listener to complete if it was started.
+        """
+        if self._o9l_receiver_classes:
+            # Wait for the listener to complete listening for signals
+            await self._o9l_listener
+
+    def o9l_receiver_classes(self) -> dict[str, type[Receiver]]:
+        """
+        The receiver classes of this State, keyed by the channel each one listens to.
+        """
+        return self._o9l_receiver_classes
+
+    def o9l_connecting(self, emitters: dict[str, Emitter]) -> None:
+        """
+        Connect the provided emitters to this State based on registered receiver classes.
+        """
+        for channel in self._o9l_receiver_classes.keys():
+            if emitter := emitters.get(channel):
+                emitter.o9l_connect(receivable=self)
+
+    async def o9l_receive(self, signal: Signal) -> None:
+        """
+        Receive a signal and enqueue it for processing by the listener loop.
+        """
+        await self._o9l_queue.put(signal)
+
+    async def _o9l_listening(self) -> None:
+        """
+        Start processing signals in the queue
+        """
+        while not self._o9l_is_stopped:
+            try:
+                signal = await self._o9l_queue.get()
+
+                if receiver_class := self._o9l_receiver_classes.get(signal.channel):
+                    if signal_handler := receiver_class.__dict__.get(signal.route):
+                        await signal_handler(self, **signal.message)
+                    else:
+                        raise RuntimeError(
+                            f"No handler found for {signal.channel}.{signal.route} "
+                            f"in {receiver_class.__name__}"
+                        )
+                else:
+                    raise RuntimeError(f"[{self.__class__.__name__}] No receiver found for {signal.channel}")
+
+                self._o9l_queue.task_done()
+            except asyncio.CancelledError:
+                self._o9l_is_stopped = True
+
+    def _o9l_stop_listening(self) -> None:
+        """
+        Stop processing signals
+        """
+        self._o9l_is_stopped = True
+
+
+class Connector(Receiver, State):
+    """
+    The default handling of the Connector channel, given to every State that listens.
+
+    This is what makes one `disconnected` signal stop the whole topology. Not to be confused
+    with `objectspell.connector.Connector`, the component you instantiate.
+    """
+
+    async def connected(self) -> None:
+        """
+        Nothing to do by default. Override it in your own receiver named `Connector`.
+        """
+        pass
+
+    async def disconnected(self) -> None:
+        """
+        Stop this State's listener loop.
+        """
+        self._o9l_stop_listening()

objectspell/struct.py

@@ -0,0 +1,15 @@
+"""
+Core components of the objectspell library.
+Provides Emitter, Receiver, State, and Connector for building asynchronous messaging topologies.
+"""
+from objectspell.connector import Connector
+from objectspell.emitter import Emitter
+from objectspell.receiver import Receiver
+from objectspell.state import State
+
+__all__ = (
+    "Emitter",
+    "Receiver",
+    "State",
+    "Connector",
+)

objectspell/types.py

@@ -0,0 +1,22 @@
+"""
+What a signal is, and the shape of the callables that send and handle one.
+"""
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class Signal:
+    """
+    One message in flight: which State sent it, which method it maps to, and its payload.
+    """
+    channel: str
+    route: str
+    message: dict[str, Any]
+
+
+# Both are unbound methods called as `fn(self, **message)`, so the parameters
+# cannot be described more precisely than `...`.
+type SignalSender = Callable[..., Awaitable[None]]
+type SignalHandler = Callable[..., Awaitable[None]]

objectspell-0.1.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: objectspell
+Version: 0.1.0
+Summary: A library for building asynchronous messaging topologies using declarative implicit wiring.
+Keywords: asyncio,event-driven,messaging,signals,pubsub
+Author: Max Sukhorukov
+Author-email: Max Sukhorukov <signaldetect@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/invertedpoint/objectspell-py
+Project-URL: Issues, https://github.com/invertedpoint/objectspell-py/issues
+Description-Content-Type: text/markdown
+
+# ObjectSpell
+
+A small asyncio framework for wiring components together with signals, without registries,
+decorators, or callback lists. You declare what a component sends and what it listens to;
+ObjectSpell connects them by name.
+
+Zero dependencies. Python 3.12+.
+
+## Install
+
+```bash
+pip install objectspell   # or: uv add objectspell
+```
+
+## Quick start
+
+Each component lives in its own module. Here `X` sends a message, `Y` prints it, and the
+program stops once `Y` is done.
+
+**`x.py`** — sends `something_happened`
+
+```python
+from objectspell import struct
+
+
+class Emitter(struct.Emitter):
+    async def something_happened(self, message: str) -> None:
+        pass  # a declaration, not an implementation
+
+
+class X(struct.State, Emitter):
+    async def action(self) -> None:
+        await self.something_happened(message="OK Computer")
+
+
+class Connector(struct.Receiver, X):
+    async def connected(self) -> None:
+        await self.action()
+
+    async def disconnected(self) -> None:
+        pass
+```
+
+**`y.py`** — listens to `X`, then reports it is done
+
+```python
+from objectspell import struct
+
+
+class Emitter(struct.Emitter):
+    async def completed(self) -> None:
+        pass
+
+
+class Y(struct.State, Emitter):
+    async def show(self, message: str) -> None:
+        print("Y received:", message)
+        await self.completed()
+
+
+class X(struct.Receiver, Y):
+    async def something_happened(self, message: str) -> None:
+        await self.show(message)
+```
+
+**`connector.py`** — stops everything when `Y` is done
+
+```python
+from objectspell import struct
+from objectspell.struct import Connector
+
+
+class Y(struct.Receiver, Connector):
+    async def completed(self) -> None:
+        await self.disconnect()
+```
+
+**`main.py`**
+
+```python
+import asyncio
+
+from connector import Connector
+from x import X
+from y import Y
+
+
+async def main() -> None:
+    await Connector().connect([X(), Y()])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+```console
+$ python main.py
+Y received: OK Computer
+```
+
+Notice that `X` and `Y` never import each other. The only thing linking them is the class
+name: `y.py` declares `class X(struct.Receiver, Y)`, which means "on `Y`, handle signals
+from `X`".
+
+## The four pieces
+
+- **Emitter** — declares the signals a component can send. The method bodies are never run;
+  ObjectSpell replaces them with senders.
+- **State** — a component. It owns a queue and handles one signal at a time.
+- **Receiver** — a handler group attached to a State, **named after the State it listens to**.
+- **Connector** — starts and stops the whole topology.
+
+## Documentation
+
+- [Concepts](https://github.com/invertedpoint/objectspell-py/blob/main/docs/concepts.md) — the four pieces and how a signal travels
+- [Wiring](https://github.com/invertedpoint/objectspell-py/blob/main/docs/wiring.md) — the naming rule, and why each component gets its own module
+- [Lifecycle](https://github.com/invertedpoint/objectspell-py/blob/main/docs/lifecycle.md) — starting up, shutting down, and message order
+- [Limitations](https://github.com/invertedpoint/objectspell-py/blob/main/docs/limitations.md) — what this library does not do
+
+Runnable examples live in [`examples/`](https://github.com/invertedpoint/objectspell-py/tree/main/examples).
+
+## License
+
+MIT — see [LICENSE](https://github.com/invertedpoint/objectspell-py/blob/main/LICENSE).

objectspell-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+objectspell/__init__.py,sha256=3VBfY4ru8LFvuEy28OHarY3dEtaqkIX2UTkg0plp6hg,381
+objectspell/connector.py,sha256=P4pUbtBL_6c7YRlUKZc_qAhKK2xf9RYG0Ppegs0xGh4,5029
+objectspell/emitter.py,sha256=Jh6bw0NxzSVBu_cm8uJ7pMqUilg0s8OYj5y9_l6GA6s,2470
+objectspell/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+objectspell/receiver.py,sha256=4-J2KuNJKczvZsImhhOTFmiGA8nFWcadr8YeDK6bNQk,603
+objectspell/state.py,sha256=qdW2QGjB2th_XfAipkef375ny4Rmpi7Tcu9VqDVlyGg,6446
+objectspell/struct.py,sha256=xkkAsDcsKEvYxBWab7y8h2FX2iUd4hHmCcrr2XT-IoM,387
+objectspell/types.py,sha256=rzyZZ94lbPY57ZJFJ7HryaG78IxR4uT-5dG2dBW-XAA,613
+objectspell-0.1.0.dist-info/licenses/LICENSE,sha256=i9ERMU0hxNnGgTKMHfRhN8nzZaY_z1_edb2R_6-2Fmg,1096
+objectspell-0.1.0.dist-info/WHEEL,sha256=y6e-a5KI2W-qDAJKfh9Xr81bin8NgUdfWgz3VSXXpe4,80
+objectspell-0.1.0.dist-info/METADATA,sha256=dt5xRtUNUQKXOf3eKsur21gWW7SO9KGv6c6KJPhbiMY,4281
+objectspell-0.1.0.dist-info/RECORD,,

objectspell-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.9
+Root-Is-Purelib: true
+Tag: py3-none-any

objectspell-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Sukhorukov <signaldetect@gmail.com>
+
+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.