streambus 0.1.0__py3-none-any.whl

streambus/__init__.py

@@ -0,0 +1,16 @@
+from .config import RedisConfig
+from .event import StreamBusEvent
+from .exceptions import ConfigurationError, EventValidationError, StreambusError
+from .listener import EventListener
+from .publisher import EventPublisher
+
+__all__ = [
+    "EventListener",
+    "EventPublisher",
+    "RedisConfig",
+    "StreamBusEvent",
+    "StreambusError",
+    "ConfigurationError",
+    "EventValidationError",
+]
+__version__ = "0.1.0"

streambus/config.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class RedisConfig:
+    url: str
+    socket_timeout: float | None = field(default=None)
+    socket_connect_timeout: float | None = field(default=5.0)

streambus/event.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass, asdict, field, fields as dc_fields
+from datetime import datetime, timezone
+
+
+@dataclass(kw_only=True)
+class StreamBusEvent:
+    event_type: str
+    occurred_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    def to_dict(self) -> dict[str, str]:
+        return {k: str(v) for k, v in asdict(self).items()}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, str]) -> "StreamBusEvent":
+        known = {f.name for f in dc_fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in known})

streambus/exceptions.py

@@ -0,0 +1,10 @@
+class StreambusError(Exception):
+    pass
+
+
+class ConfigurationError(StreambusError):
+    pass
+
+
+class EventValidationError(StreambusError):
+    pass

streambus/listener.py

@@ -0,0 +1,94 @@
+import logging
+import time
+from typing import Callable
+
+import redis as redis_lib
+
+from streambus.config import RedisConfig
+from streambus.event import StreamBusEvent
+from streambus.exceptions import ConfigurationError
+
+logger = logging.getLogger(__name__)
+
+
+class EventListener:
+    def __init__(
+        self,
+        stream: str,
+        group: str,
+        handler: Callable[[StreamBusEvent], None],
+        event_class: type[StreamBusEvent],
+        config: RedisConfig,
+        consumer: str | None = None,
+        batch_size: int = 10,
+        block_ms: int = 5000,
+        retry_delay: float = 3.0,
+    ):
+        if not stream:
+            raise ConfigurationError("stream is required")
+        if not group:
+            raise ConfigurationError("group is required")
+        if not callable(handler):
+            raise ConfigurationError("handler must be callable")
+        if not (isinstance(event_class, type) and issubclass(event_class, StreamBusEvent)):
+            raise ConfigurationError("event_class must be a subclass of StreamBusEvent")
+        if not isinstance(config, RedisConfig):
+            raise ConfigurationError("config must be a RedisConfig instance")
+        if not config.url:
+            raise ConfigurationError("config.url is required")
+
+        self.stream = stream
+        self.group = group
+        self.handler = handler
+        self.event_class = event_class
+        self.config = config
+        self.consumer = consumer or f"{group}-1"
+        self.batch_size = batch_size
+        self.block_ms = block_ms
+        self.retry_delay = retry_delay
+
+    def run(self) -> None:
+        r = self._connect()
+        self._ensure_group(r)
+        logger.info("[%s] listening on %s", self.group, self.stream)
+
+        while True:
+            try:
+                results = r.xreadgroup(
+                    self.group,
+                    self.consumer,
+                    {self.stream: ">"},
+                    count=self.batch_size,
+                    block=self.block_ms,
+                )
+                for _stream, messages in (results or []):
+                    for msg_id, data in messages:
+                        try:
+                            event = self.event_class.from_dict(data)
+                            self.handler(event)
+                            r.xack(self.stream, self.group, msg_id)
+                        except Exception:
+                            logger.exception("error processing message %s", msg_id)
+            except redis_lib.exceptions.ConnectionError:
+                logger.warning(
+                    "[%s] redis connection lost, retrying in %.1fs",
+                    self.group,
+                    self.retry_delay,
+                )
+                time.sleep(self.retry_delay)
+                r = self._connect()
+
+    def _connect(self) -> redis_lib.Redis:
+        return redis_lib.from_url(
+            self.config.url,
+            decode_responses=True,
+            socket_timeout=self.config.socket_timeout,
+            socket_connect_timeout=self.config.socket_connect_timeout,
+        )
+
+    def _ensure_group(self, r: redis_lib.Redis) -> None:
+        try:
+            r.xgroup_create(self.stream, self.group, id="0", mkstream=True)
+        except redis_lib.exceptions.ResponseError as exc:
+            if "BUSYGROUP" not in str(exc):
+                raise

streambus/publisher.py

@@ -0,0 +1,40 @@
+import logging
+
+import redis as redis_lib
+
+from streambus.config import RedisConfig
+from streambus.event import StreamBusEvent
+from streambus.exceptions import ConfigurationError, EventValidationError
+
+logger = logging.getLogger(__name__)
+
+
+class EventPublisher:
+    def __init__(self, stream: str, config: RedisConfig):
+        if not stream:
+            raise ConfigurationError("stream is required")
+        if not isinstance(config, RedisConfig):
+            raise ConfigurationError("config must be a RedisConfig instance")
+        if not config.url:
+            raise ConfigurationError("config.url is required")
+
+        self.stream = stream
+        self.config = config
+        self._redis: redis_lib.Redis | None = None
+
+    def publish(self, event: StreamBusEvent) -> None:
+        if not isinstance(event, StreamBusEvent):
+            raise EventValidationError("event must be a StreamBusEvent instance")
+        if not event.event_type:
+            raise EventValidationError("event.event_type is required")
+
+        self._connect().xadd(self.stream, event.to_dict())
+
+    def _connect(self) -> redis_lib.Redis:
+        if self._redis is None:
+            self._redis = redis_lib.from_url(
+                self.config.url,
+                socket_timeout=self.config.socket_timeout,
+                socket_connect_timeout=self.config.socket_connect_timeout,
+            )
+        return self._redis

streambus-0.1.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: streambus
+Version: 0.1.0
+Summary: Lightweight Redis Streams event listener with a clean callback API
+Project-URL: Homepage, https://github.com/jmeiracorbal/streambus
+Project-URL: Repository, https://github.com/jmeiracorbal/streambus
+Project-URL: Issues, https://github.com/jmeiracorbal/streambus/issues
+Author-email: Jose Meira <jmeiracorbal@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Jose Meira
+        
+        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.
+License-File: LICENSE
+Keywords: consumer,event-bus,events,producer,pubsub,redis,streams
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Requires-Dist: redis>=5.0
+Description-Content-Type: text/markdown
+
+# streambus
+
+[![PyPI version](https://img.shields.io/pypi/v/streambus?color=e8445a&label=pypi)](https://pypi.org/project/streambus/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-4584b6?logo=python&logoColor=white)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-22c55e)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-18%20passed-22c55e)](#development)
+
+Lightweight event bus over Redis Streams. Define typed events, publish from one service, consume in others without boilerplate or framework dependencies.
+
+## Install
+
+```bash
+pip install streambus
+```
+
+```bash
+uv add streambus
+```
+
+## Quick start
+
+Define an event:
+
+```python
+from dataclasses import dataclass
+from streambus import StreamBusEvent
+
+@dataclass(kw_only=True)
+class OrderCreated(StreamBusEvent):
+    order_id: str
+    customer_id: str
+    total: str
+```
+
+Publish it:
+
+```python
+from streambus import EventPublisher, RedisConfig
+
+publisher = EventPublisher(
+    stream="orders:events",
+    config=RedisConfig(url="redis://localhost:6379"),
+)
+
+publisher.publish(
+    OrderCreated(
+        event_type="order.created",
+        order_id="ord_123",
+        customer_id="cust_456",
+        total="99.90",
+    )
+)
+```
+
+Consume it:
+
+```python
+from streambus import EventListener, RedisConfig
+
+def handle_order(event: OrderCreated) -> None:
+    print(f"New order {event.order_id}: total {event.total}")
+
+EventListener(
+    stream="orders:events",
+    group="notifications",
+    handler=handle_order,
+    event_class=OrderCreated,
+    config=RedisConfig(url="redis://localhost:6379"),
+).run()
+```
+
+## How it works
+
+streambus uses [Redis Streams](https://redis.io/docs/data-types/streams/) for transport: persistent storage, consumer groups, and at-least-once delivery. The library manages group creation, the blocking read loop, message acknowledgement, and automatic reconnection on connection loss.
+
+Each consumer group processes events independently. A message published to a stream reaches every group exactly once.
+
+## Events
+
+All events extend `StreamBusEvent`:
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `event_type` | `str` | yes | Identifies the event. Convention: `noun.verb` |
+| `occurred_at` | `str` | no | ISO 8601 timestamp. Auto-set on creation. |
+
+Subclasses declare only the fields they need. Unknown fields arriving from the stream are silently discarded — each consumer maps what it uses, nothing more.
+
+Both `StreamBusEvent` and its subclasses must use `@dataclass(kw_only=True)`. This is required: the base class has a field with a default (`occurred_at`), and `kw_only=True` prevents the ordering conflict that would otherwise block subclasses from adding required fields.
+
+## Configuration
+
+**RedisConfig**
+
+```python
+RedisConfig(
+    url="redis://localhost:6379",  # required
+    socket_timeout=None,           # None = no timeout (correct for blocking reads)
+    socket_connect_timeout=5.0,    # seconds to wait on initial connect
+)
+```
+
+**EventListener**
+
+```python
+EventListener(
+    stream="stream:name",     # required
+    group="consumer-group",   # required
+    handler=my_handler,       # required — callable(event) -> None
+    event_class=MyEvent,      # required — must subclass StreamBusEvent
+    config=RedisConfig(...),  # required
+    consumer=None,            # defaults to "{group}-1"
+    batch_size=10,
+    block_ms=5000,
+    retry_delay=3.0,
+)
+```
+
+**EventPublisher**
+
+```python
+EventPublisher(
+    stream="stream:name",    # required
+    config=RedisConfig(...), # required
+)
+```
+
+## Exceptions
+
+| Exception | When |
+|---|---|
+| `ConfigurationError` | Invalid or missing parameters at construction time |
+| `EventValidationError` | `publish()` receives a non-`StreamBusEvent` or empty `event_type` |
+| `StreambusError` | Base class for all streambus exceptions |
+
+## Development
+
+```bash
+git clone https://github.com/yourorg/streambus
+cd streambus
+uv sync --group dev
+uv run pytest tests/ -v
+```
+
+Run the example (requires Docker):
+
+```bash
+cd example
+docker compose up -d        # start Redis
+uv sync
+uv run python consume.py    # terminal 1
+uv run python publish.py    # terminal 2
+```
+
+## License
+
+MIT

streambus-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+streambus/__init__.py,sha256=27cx-b9a7fjQZl3N_3YQ9QFEhYr18VZec8nQVhzr38g,418
+streambus/config.py,sha256=Lt8j3W2i-nhsBJnCw7X5-RmStcjHXifIUkth2_GhJjM,203
+streambus/event.py,sha256=6mVQ-wRjoMZ-JWawjnGBX1QFCreECi5wXbXOy5Mglo4,575
+streambus/exceptions.py,sha256=JlcWovNkFmdrCKt7m6C7-ib-rx572VrhHIIcisQ5M9o,150
+streambus/listener.py,sha256=MNIdBjilRqHDyvvVPLD4Fhqdq4hMd0eeGpQdTx7nxB4,3353
+streambus/publisher.py,sha256=HoRyF_OWErhQp9RnQZCQ8vwZS17jhj1WcWtzeHCjgLA,1410
+streambus-0.1.0.dist-info/METADATA,sha256=zEdAsq-uQrEqsqllLOpIvGDasIPG4rXCWXBAJOBd1zY,6365
+streambus-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+streambus-0.1.0.dist-info/licenses/LICENSE,sha256=uFoMIS8c0UtdA2qO2wnC4EvksMXQb8pTyvY8oBMkgEg,1067
+streambus-0.1.0.dist-info/RECORD,,

streambus-0.1.0.dist-info/WHEEL

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

streambus-0.1.0.dist-info/licenses/LICENSE

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