relaykit-tools 0.1.1__tar.gz

relaykit_tools-0.1.1/.gitignore

@@ -0,0 +1,8 @@
+
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/

relaykit_tools-0.1.1/LICENSE

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

relaykit_tools-0.1.1/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: relaykit-tools
+Version: 0.1.1
+Summary: A tiny, dependency-free event bus for Python applications.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: event-bus,event-driven,events,publish-subscribe,pubsub
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+
+# RelayKit Tools
+
+**A tiny, dependency-free event bus for Python.**
+
+RelayKit Tools lets different parts of your application communicate through
+events without needing to know about each other.
+
+## Features
+
+- Simple publish/subscribe API
+- Decorator-based event handlers
+- One-time event listeners
+- Wildcard listeners for observing events
+- Remove listeners individually or clear them all
+- Zero runtime dependencies
+- Type-annotated Python API
+
+## Installation
+
+```bash
+pip install relaykit-tools
+```
+
+## Quick start
+
+```python
+from relaykit_tools import EventBus
+
+bus = EventBus()
+
+def greet(name):
+    print(f"Hello, {name}!")
+
+bus.on("user.joined", greet)
+bus.emit("user.joined", "Alex")
+
+# Output: Hello, Alex!
+```
+
+## Use decorators
+
+```python
+from relaykit_tools import EventBus
+
+bus = EventBus()
+
+@bus.on("order.created")
+def process_order(order_id):
+    print(f"Processing order {order_id}")
+
+bus.emit("order.created", 123)
+```
+
+## One-time listeners
+
+A one-time listener removes itself before its first invocation.
+
+```python
+@bus.once("app.started")
+def initialize():
+    print("Application initialized")
+
+bus.emit("app.started")
+bus.emit("app.started")  # Does not invoke initialize again
+```
+
+## Wildcard listeners
+
+Listen to events regardless of their names. Wildcard handlers receive
+the event name as their first argument.
+
+```python
+@bus.on("*")
+def log_event(event_name, *args, **kwargs):
+    print(f"Event: {event_name}")
+
+bus.emit("user.created", 42)
+bus.emit("user.deleted", 42)
+```
+
+## Remove listeners
+
+```python
+def handle_message(message):
+    print(message)
+
+bus.on("message", handle_message)
+bus.off("message", handle_message)
+
+# Remove every listener for one event
+bus.off("message")
+
+# Remove every listener for every event
+bus.clear()
+```
+
+## Inspect listeners
+
+```python
+bus.listener_count("message")  # Listeners for one event
+bus.listener_count()           # All registered listeners
+```
+
+## Error handling
+
+Handlers run in registration order. By default, if a handler raises
+an exception, the exception propagates to the caller and subsequent
+handlers are not invoked.
+
+```python
+try:
+    bus.emit("task.started")
+except Exception as exc:
+    print(f"Event handler failed: {exc}")
+```
+
+## Limitations
+
+- Event dispatch is synchronous.
+- The event bus is not thread-safe.
+- Handler exceptions stop the current dispatch.
+- Event names are case-sensitive.
+- Wildcard listeners use `"*"` as their event name.
+
+## Requirements
+
+Python 3.10 or newer.
+
+## License
+
+MIT

relaykit_tools-0.1.1/README.md

@@ -0,0 +1,132 @@
+
+# RelayKit Tools
+
+**A tiny, dependency-free event bus for Python.**
+
+RelayKit Tools lets different parts of your application communicate through
+events without needing to know about each other.
+
+## Features
+
+- Simple publish/subscribe API
+- Decorator-based event handlers
+- One-time event listeners
+- Wildcard listeners for observing events
+- Remove listeners individually or clear them all
+- Zero runtime dependencies
+- Type-annotated Python API
+
+## Installation
+
+```bash
+pip install relaykit-tools
+```
+
+## Quick start
+
+```python
+from relaykit_tools import EventBus
+
+bus = EventBus()
+
+def greet(name):
+    print(f"Hello, {name}!")
+
+bus.on("user.joined", greet)
+bus.emit("user.joined", "Alex")
+
+# Output: Hello, Alex!
+```
+
+## Use decorators
+
+```python
+from relaykit_tools import EventBus
+
+bus = EventBus()
+
+@bus.on("order.created")
+def process_order(order_id):
+    print(f"Processing order {order_id}")
+
+bus.emit("order.created", 123)
+```
+
+## One-time listeners
+
+A one-time listener removes itself before its first invocation.
+
+```python
+@bus.once("app.started")
+def initialize():
+    print("Application initialized")
+
+bus.emit("app.started")
+bus.emit("app.started")  # Does not invoke initialize again
+```
+
+## Wildcard listeners
+
+Listen to events regardless of their names. Wildcard handlers receive
+the event name as their first argument.
+
+```python
+@bus.on("*")
+def log_event(event_name, *args, **kwargs):
+    print(f"Event: {event_name}")
+
+bus.emit("user.created", 42)
+bus.emit("user.deleted", 42)
+```
+
+## Remove listeners
+
+```python
+def handle_message(message):
+    print(message)
+
+bus.on("message", handle_message)
+bus.off("message", handle_message)
+
+# Remove every listener for one event
+bus.off("message")
+
+# Remove every listener for every event
+bus.clear()
+```
+
+## Inspect listeners
+
+```python
+bus.listener_count("message")  # Listeners for one event
+bus.listener_count()           # All registered listeners
+```
+
+## Error handling
+
+Handlers run in registration order. By default, if a handler raises
+an exception, the exception propagates to the caller and subsequent
+handlers are not invoked.
+
+```python
+try:
+    bus.emit("task.started")
+except Exception as exc:
+    print(f"Event handler failed: {exc}")
+```
+
+## Limitations
+
+- Event dispatch is synchronous.
+- The event bus is not thread-safe.
+- Handler exceptions stop the current dispatch.
+- Event names are case-sensitive.
+- Wildcard listeners use `"*"` as their event name.
+
+## Requirements
+
+Python 3.10 or newer.
+
+## License
+
+MIT

relaykit_tools-0.1.1/pyproject.toml

@@ -0,0 +1,43 @@
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "relaykit-tools"
+version = "0.1.1"
+description = "A tiny, dependency-free event bus for Python applications."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "events",
+    "event-bus",
+    "pubsub",
+    "publish-subscribe",
+    "event-driven",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/relaykit_tools"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]

relaykit_tools-0.1.1/src/relaykit_tools/__init__.py

@@ -0,0 +1,158 @@
+
+"""RelayKit Tools: a tiny, dependency-free event bus for Python."""
+
+from collections.abc import Callable
+from typing import Any, TypeVar, overload
+
+__version__ = "0.1.1"
+
+Handler = Callable[..., Any]
+T = TypeVar("T", bound=Handler)
+
+
+class EventBus:
+    """Publish events and let independent components subscribe to them.
+
+    Regular handlers receive the emitted positional and keyword arguments.
+    Wildcard handlers registered for '*' receive the event name first.
+    Exceptions raised by handlers propagate to the caller.
+    """
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, list[Handler]] = {}
+
+    @staticmethod
+    def _validate_event(event: str) -> None:
+        if not isinstance(event, str) or not event.strip():
+            raise ValueError("Event name must be a non-empty string.")
+
+    @staticmethod
+    def _validate_handler(handler: Handler) -> None:
+        if not callable(handler):
+            raise TypeError("Handler must be callable.")
+
+    @overload
+    def on(self, event: str) -> Callable[[T], T]: ...
+
+    @overload
+    def on(self, event: str, handler: T) -> T: ...
+
+    def on(
+        self, event: str, handler: T | None = None
+    ) -> T | Callable[[T], T]:
+        """Register a handler. Can be used directly or as a decorator."""
+        self._validate_event(event)
+
+        def register(callback: T) -> T:
+            self._validate_handler(callback)
+            self._handlers.setdefault(event, []).append(callback)
+            return callback
+
+        if handler is None:
+            return register
+
+        return register(handler)
+
+    @overload
+    def once(self, event: str) -> Callable[[T], T]: ...
+
+    @overload
+    def once(self, event: str, handler: T) -> T: ...
+
+    def once(
+        self, event: str, handler: T | None = None
+    ) -> T | Callable[[T], T]:
+        """Register a handler that is removed before its first invocation."""
+        self._validate_event(event)
+
+        def register(callback: T) -> T:
+            self._validate_handler(callback)
+
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                self.off(event, wrapper)
+                return callback(*args, **kwargs)
+
+            # Keep the original callback available for off(event, callback).
+            setattr(wrapper, "__relaykit_original__", callback)
+            self._handlers.setdefault(event, []).append(wrapper)
+            return callback
+
+        if handler is None:
+            return register
+
+        return register(handler)
+
+    def off(self, event: str, handler: Handler | None = None) -> bool:
+        """Remove a handler, or all handlers for an event.
+
+        Returns True if anything was removed, otherwise False.
+        Passing no handler removes every listener for the event.
+        """
+        self._validate_event(event)
+        listeners = self._handlers.get(event)
+
+        if not listeners:
+            return False
+
+        if handler is None:
+            del self._handlers[event]
+            return True
+
+        remaining = [
+            registered
+            for registered in listeners
+            if registered is not handler
+            and getattr(registered, "__relaykit_original__", None)
+            is not handler
+        ]
+
+        removed = len(remaining) != len(listeners)
+
+        if remaining:
+            self._handlers[event] = remaining
+        else:
+            self._handlers.pop(event, None)
+
+        return removed
+
+    def emit(self, event: str, *args: Any, **kwargs: Any) -> int:
+        """Emit an event and return the number of handlers invoked.
+
+        Listeners are called in registration order. Wildcard listeners
+        registered for '*' receive (event, *args, **kwargs).
+        Listener lists are snapshotted before dispatch.
+        """
+        self._validate_event(event)
+
+        listeners = list(self._handlers.get(event, ()))
+        if event != "*":
+            listeners.extend(self._handlers.get("*", ()))
+
+        for handler in listeners[:len(self._handlers.get(event, ())) if event != "*" else len(listeners)]:
+            handler(*args, **kwargs)
+
+        if event != "*":
+            for handler in list(self._handlers.get("*", ())):
+                handler(event, *args, **kwargs)
+
+        return len(listeners)
+
+    def listener_count(self, event: str | None = None) -> int:
+        """Return the listener count for one event or all events."""
+        if event is None:
+            return sum(len(handlers) for handlers in self._handlers.values())
+
+        self._validate_event(event)
+        return len(self._handlers.get(event, ()))
+
+    def clear(self, event: str | None = None) -> None:
+        """Remove listeners for one event, or all listeners."""
+        if event is None:
+            self._handlers.clear()
+            return
+
+        self._validate_event(event)
+        self._handlers.pop(event, None)
+
+
+__all__ = ["EventBus", "__version__"]