domubus 0.1.0__py3-none-any.whl

domubus/handlers.py

@@ -0,0 +1,161 @@
+"""Handler management for domubus.
+
+This module provides HandlerEntry (individual handler) and HandlerRegistry
+(collection of handlers with priority ordering and wildcard support).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+if TYPE_CHECKING:
+    from domubus.types import EventFilter, Handler
+
+WILDCARD = "*"
+
+
+@dataclass
+class HandlerEntry:
+    """Represents a registered event handler.
+
+    Attributes:
+        id: Unique identifier for this handler registration.
+        event_type: The event type this handler listens to ("*" for wildcard).
+        callback: The handler function (sync or async).
+        priority: Execution priority (higher = earlier execution).
+        once: If True, handler is removed after first execution.
+        filter_fn: Optional filter function to conditionally execute.
+    """
+
+    id: str
+    event_type: str
+    callback: Handler
+    priority: int = 0
+    once: bool = False
+    filter_fn: EventFilter | None = None
+
+    @property
+    def is_async(self) -> bool:
+        """Check if the handler is an async function."""
+        return asyncio.iscoroutinefunction(self.callback)
+
+    @property
+    def name(self) -> str:
+        """Get the handler function name."""
+        return getattr(self.callback, "__name__", repr(self.callback))
+
+
+class HandlerRegistry:
+    """Manages event handlers with priority ordering and wildcard support.
+
+    Handlers are stored per event type and sorted by priority (highest first).
+    Wildcard handlers ("*") receive all events.
+
+    Example:
+        registry = HandlerRegistry()
+        handler_id = registry.subscribe("device.light.on", my_handler, priority=10)
+        handlers = registry.get_handlers("device.light.on")
+        registry.unsubscribe(handler_id)
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty handler registry."""
+        self._handlers: dict[str, list[HandlerEntry]] = {}
+        self._wildcard_handlers: list[HandlerEntry] = []
+
+    def subscribe(
+        self,
+        event_type: str,
+        callback: Handler,
+        priority: int = 0,
+        once: bool = False,
+        filter_fn: EventFilter | None = None,
+    ) -> str:
+        """Register a handler for an event type.
+
+        Args:
+            event_type: Event type to subscribe to ("*" for all events).
+            callback: Handler function (sync or async).
+            priority: Execution priority (higher = earlier, default 0).
+            once: If True, handler is removed after first call.
+            filter_fn: Optional filter function to conditionally execute.
+
+        Returns:
+            Unique handler ID for later unsubscription.
+        """
+        handler_id = str(uuid4())
+        entry = HandlerEntry(
+            id=handler_id,
+            event_type=event_type,
+            callback=callback,
+            priority=priority,
+            once=once,
+            filter_fn=filter_fn,
+        )
+
+        if event_type == WILDCARD:
+            self._wildcard_handlers.append(entry)
+            self._wildcard_handlers.sort(key=lambda h: -h.priority)
+        else:
+            if event_type not in self._handlers:
+                self._handlers[event_type] = []
+            self._handlers[event_type].append(entry)
+            self._handlers[event_type].sort(key=lambda h: -h.priority)
+
+        return handler_id
+
+    def unsubscribe(self, handler_id: str) -> bool:
+        """Remove a handler by its ID.
+
+        Args:
+            handler_id: The ID returned from subscribe().
+
+        Returns:
+            True if handler was found and removed, False otherwise.
+        """
+        # Check specific handlers
+        for handlers in self._handlers.values():
+            for i, h in enumerate(handlers):
+                if h.id == handler_id:
+                    handlers.pop(i)
+                    return True
+
+        # Check wildcard handlers
+        for i, h in enumerate(self._wildcard_handlers):
+            if h.id == handler_id:
+                self._wildcard_handlers.pop(i)
+                return True
+
+        return False
+
+    def get_handlers(self, event_type: str) -> list[HandlerEntry]:
+        """Get all handlers for an event type (including wildcards).
+
+        Args:
+            event_type: The event type to get handlers for.
+
+        Returns:
+            List of handlers sorted by priority (highest first).
+        """
+        specific = self._handlers.get(event_type, [])
+        # Merge specific and wildcard, re-sort by priority
+        all_handlers = list(specific) + list(self._wildcard_handlers)
+        return sorted(all_handlers, key=lambda h: -h.priority)
+
+    def clear(self) -> None:
+        """Remove all handlers."""
+        self._handlers.clear()
+        self._wildcard_handlers.clear()
+
+    def handler_count(self, event_type: str | None = None) -> int:
+        """Count handlers, optionally filtered by event type."""
+        if event_type is None:
+            total = sum(len(h) for h in self._handlers.values())
+            return total + len(self._wildcard_handlers)
+        if event_type == WILDCARD:
+            return len(self._wildcard_handlers)
+        return len(self._handlers.get(event_type, []))
+

domubus/persistence.py

@@ -0,0 +1,156 @@
+"""Persistence layer for domubus.
+
+This module provides WAL-style (Write-Ahead Logging) persistence to JSONL files.
+Events are appended one per line as JSON, enabling efficient append and recovery.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import IO, Any
+
+
+class JSONLPersistence:
+    """WAL-style persistence to JSONL file.
+
+    Events are appended as JSON lines to a file. On load, corrupted lines are
+    skipped gracefully. The file can be compacted to remove old events.
+
+    Example:
+        persistence = JSONLPersistence("~/.myapp/events.jsonl", max_events=10000)
+        persistence.open()
+        persistence.append({"event_type": "test", "data": {}})
+        events = persistence.load()
+        persistence.close()
+    """
+
+    def __init__(
+        self,
+        file_path: str | Path,
+        *,
+        max_events: int = 10000,
+        fsync: bool = True,
+    ) -> None:
+        """Initialize persistence.
+
+        Args:
+            file_path: Path to the JSONL file (will be created if not exists).
+            max_events: Maximum events to keep when loading/compacting.
+            fsync: If True, flush and fsync after each write for durability.
+        """
+        self.file_path = Path(file_path).expanduser()
+        self.max_events = max_events
+        self.fsync = fsync
+        self._file: IO[str] | None = None
+
+    def open(self) -> None:
+        """Open file for appending."""
+        self.file_path.parent.mkdir(parents=True, exist_ok=True)
+        self._file = open(self.file_path, "a", encoding="utf-8")
+
+    def close(self) -> None:
+        """Close file handle."""
+        if self._file:
+            self._file.close()
+            self._file = None
+
+    def is_open(self) -> bool:
+        """Check if the file is currently open."""
+        return self._file is not None
+
+    def append(self, event: dict[str, Any]) -> None:
+        """Append an event to file (WAL-style).
+
+        Args:
+            event: Event dictionary to persist.
+        """
+        if not self._file:
+            self.open()
+
+        assert self._file is not None  # For type checker
+        line = json.dumps(event, separators=(",", ":"), default=str)
+        self._file.write(line + "\n")
+
+        if self.fsync:
+            self._file.flush()
+            os.fsync(self._file.fileno())
+
+    def load(self) -> list[dict[str, Any]]:
+        """Load all events from file.
+
+        Corrupted lines are skipped. Only returns the last max_events.
+
+        Returns:
+            List of event dictionaries.
+        """
+        if not self.file_path.exists():
+            return []
+
+        events: list[dict[str, Any]] = []
+        with open(self.file_path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    try:
+                        events.append(json.loads(line))
+                    except json.JSONDecodeError:
+                        continue  # Skip corrupted lines
+
+        # Return only last max_events
+        return events[-self.max_events :]
+
+    def _load_all(self) -> list[dict[str, Any]]:
+        """Load ALL events from file (ignores max_events limit)."""
+        if not self.file_path.exists():
+            return []
+
+        events: list[dict[str, Any]] = []
+        with open(self.file_path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    try:
+                        events.append(json.loads(line))
+                    except json.JSONDecodeError:
+                        continue
+        return events
+
+    def compact(self) -> int:
+        """Compact file to only keep max_events.
+
+        Returns:
+            Number of events removed.
+        """
+        events = self._load_all()
+        if len(events) <= self.max_events:
+            return 0
+
+        removed = len(events) - self.max_events
+        kept = events[-self.max_events :]
+
+        # Rewrite file
+        self.close()
+        with open(self.file_path, "w", encoding="utf-8") as f:
+            for event in kept:
+                line = json.dumps(event, separators=(",", ":"), default=str)
+                f.write(line + "\n")
+
+        self.open()
+        return removed
+
+    def clear(self) -> None:
+        """Clear all events from the file."""
+        self.close()
+        if self.file_path.exists():
+            self.file_path.unlink()
+        self.open()
+
+    def event_count(self) -> int:
+        """Count events in the file."""
+        if not self.file_path.exists():
+            return 0
+        with open(self.file_path, encoding="utf-8") as f:
+            return sum(1 for line in f if line.strip())
+

domubus/py.typed

@@ -0,0 +1 @@
+

domubus/types.py

@@ -0,0 +1,70 @@
+"""Type definitions for domubus event bus."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any, Protocol, TypeVar, Union, runtime_checkable
+
+# TypeVar for event types
+EventT = TypeVar("EventT", bound="BaseEventProtocol")
+EventT_co = TypeVar("EventT_co", bound="BaseEventProtocol", covariant=True)
+
+
+@runtime_checkable
+class BaseEventProtocol(Protocol):
+    """Protocol that all events must satisfy.
+
+    All events (Pydantic BaseEvent, StringEvent, or custom) must have these attributes.
+    """
+
+    @property
+    def event_type(self) -> str:
+        """The event type identifier (e.g., 'device.light.on')."""
+        ...
+
+    @property
+    def timestamp(self) -> float:
+        """Unix timestamp when the event was created."""
+        ...
+
+    @property
+    def id(self) -> str:
+        """Unique identifier for this event instance."""
+        ...
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the event to a dictionary."""
+        ...
+
+
+# Handler callback types
+SyncHandler = Callable[[Any], None]
+"""Synchronous handler that receives an event and returns nothing."""
+
+AsyncHandler = Callable[[Any], Awaitable[None]]
+"""Asynchronous handler that receives an event and returns nothing."""
+
+Handler = Union[SyncHandler, AsyncHandler]
+"""Union type for both sync and async handlers."""
+
+# Error callback type
+ErrorCallback = Callable[[Exception, Any, Handler], None]
+"""Callback invoked when a handler raises an exception.
+
+Args:
+    exception: The exception that was raised.
+    event: The event that was being processed.
+    handler: The handler that raised the exception.
+"""
+
+# Filter function type
+EventFilter = Callable[[Any], bool]
+"""Filter function to conditionally execute handlers.
+
+Args:
+    event: The event to check.
+
+Returns:
+    True if the handler should be executed, False otherwise.
+"""
+

domubus/watcher.py

@@ -0,0 +1,131 @@
+"""File watcher for cross-process event synchronization.
+
+This module provides file watching capability to enable multiple processes
+to share events via the same JSONL persistence file.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    pass
+
+
+class FileWatcher:
+    """Watches a JSONL file for new events appended by other processes.
+
+    Uses file position tracking to efficiently detect new lines.
+    Only reads events appended after the watcher starts.
+
+    Example:
+        watcher = FileWatcher(
+            "events.jsonl",
+            on_event=lambda e: print(f"New event: {e}"),
+            process_id="chat-123",
+        )
+        await watcher.start()
+        # ... events from other processes are now detected ...
+        await watcher.stop()
+    """
+
+    def __init__(
+        self,
+        file_path: str | Path,
+        *,
+        on_event: Callable[[dict[str, Any]], None],
+        process_id: str | None = None,
+        poll_interval: float = 0.1,
+    ) -> None:
+        """Initialize the file watcher.
+
+        Args:
+            file_path: Path to the JSONL file to watch.
+            on_event: Callback for each new event detected.
+            process_id: Unique ID for this process (to filter own events).
+            poll_interval: Seconds between file checks.
+        """
+        self.file_path = Path(file_path).expanduser()
+        self._on_event = on_event
+        self._process_id = process_id or f"proc-{os.getpid()}"
+        self._poll_interval = poll_interval
+
+        self._position: int = 0
+        self._running = False
+        self._task: asyncio.Task[None] | None = None
+
+    async def start(self) -> None:
+        """Start watching the file for new events."""
+        if self._running:
+            return
+
+        # Start from end of file (only watch new events)
+        if self.file_path.exists():
+            self._position = self.file_path.stat().st_size
+
+        self._running = True
+        self._task = asyncio.create_task(self._watch_loop())
+
+    async def stop(self) -> None:
+        """Stop watching the file."""
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+            self._task = None
+
+    async def _watch_loop(self) -> None:
+        """Main watch loop - polls file for new content."""
+        while self._running:
+            try:
+                await self._check_file()
+            except Exception:
+                pass  # Ignore errors, keep watching
+
+            await asyncio.sleep(self._poll_interval)
+
+    async def _check_file(self) -> None:
+        """Check file for new lines and process them."""
+        if not self.file_path.exists():
+            return
+
+        current_size = self.file_path.stat().st_size
+        if current_size <= self._position:
+            return  # No new data
+
+        # Read new lines
+        with open(self.file_path, encoding="utf-8") as f:
+            f.seek(self._position)
+            new_content = f.read()
+            self._position = f.tell()
+
+        # Process each new line
+        for line in new_content.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue  # Skip corrupted lines
+
+            # Skip events from this process (avoid echo)
+            if event.get("_source_process") == self._process_id:
+                continue
+
+            # Dispatch to handler
+            self._on_event(event)
+
+    @property
+    def is_running(self) -> bool:
+        """Check if the watcher is currently running."""
+        return self._running
+

domubus-0.1.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: domubus
+Version: 0.1.0
+Summary: Async/sync event bus with optional Pydantic integration, persistence, and priority handlers
+Project-URL: Homepage, https://github.com/lensator/domubus
+Project-URL: Documentation, https://github.com/lensator/domubus#readme
+Project-URL: Repository, https://github.com/lensator/domubus
+Project-URL: Issues, https://github.com/lensator/domubus/issues
+Author: voxDomus Team
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,event-bus,event-driven,home-automation,pubsub,pydantic
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+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 :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pydantic>=2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == 'pydantic'
+Description-Content-Type: text/markdown
+
+# domubus
+
+A type-safe, async/sync event bus for Python with optional Pydantic integration, persistence, and priority handlers. **Zero required dependencies.**
+
+## Features
+
+- ✅ **Async & Sync** - Both async and sync handlers, emit from either context
+- ✅ **Zero Dependencies** - Core package uses only Python stdlib
+- ✅ **Optional Pydantic** - Type-safe events when Pydantic is installed
+- ✅ **Priority Handlers** - Control execution order with priority values
+- ✅ **Wildcard Subscriptions** - Subscribe to all events with `*`
+- ✅ **One-time Handlers** - Auto-unsubscribe after first execution
+- ✅ **Event Filters** - Conditionally execute handlers
+- ✅ **JSONL Persistence** - WAL-style event persistence
+- ✅ **Fully Typed** - PEP 561 compatible with `py.typed` marker
+
+## Installation
+
+```bash
+pip install domubus
+
+# With Pydantic support
+pip install domubus[pydantic]
+```
+
+## Quick Start
+
+```python
+import asyncio
+from domubus import EventBus
+
+bus = EventBus()
+
+@bus.on("device.light.on")
+async def handle_light_on(event):
+    print(f"Light turned on: {event.data}")
+
+@bus.on("device.light.on", priority=100)
+def high_priority_handler(event):
+    print("This runs first (sync handler)")
+
+async def main():
+    await bus.emit_async("device.light.on", {"brightness": 100})
+
+asyncio.run(main())
+```
+
+## Typed Events with Pydantic
+
+```python
+from typing import ClassVar
+from domubus import EventBus, BaseEvent
+
+class DeviceStateChanged(BaseEvent):
+    event_type: ClassVar[str] = "device.state.changed"
+    device_id: str
+    new_state: str
+
+bus = EventBus()
+
+@bus.on("device.state.changed")
+async def handle_state_change(event: DeviceStateChanged):
+    print(f"Device {event.device_id} -> {event.new_state}")
+
+await bus.emit_async(DeviceStateChanged(device_id="light1", new_state="on"))
+```
+
+## Persistence
+
+```python
+from domubus import EventBus
+
+# Events are persisted to JSONL file
+async with EventBus(persistence_path="~/.myapp/events.jsonl") as bus:
+    await bus.emit_async("user.login", {"user_id": "123"})
+    
+    # History is automatically loaded on context enter
+    history = bus.get_history(event_type="user.login")
+```
+
+## Wildcard Subscriptions
+
+```python
+@bus.on("*")
+def log_all_events(event):
+    print(f"Event: {event.event_type}")
+```
+
+## One-time Handlers
+
+```python
+@bus.once("system.ready")
+async def on_ready(event):
+    print("System ready! (only runs once)")
+```
+
+## Event Filters
+
+```python
+def only_important(event):
+    return event.data.get("priority") == "high"
+
+@bus.on("notification", filter_fn=only_important)
+def handle_important(event):
+    print(f"Important: {event.data}")
+```
+
+## Error Handling
+
+```python
+def on_error(exception, event, handler):
+    print(f"Handler {handler.__name__} failed: {exception}")
+
+bus = EventBus(error_callback=on_error)
+```
+
+## API Reference
+
+### EventBus
+
+- `subscribe(event_type, handler, priority=0, once=False, filter_fn=None)` - Subscribe handler
+- `unsubscribe(handler_id)` - Unsubscribe by ID
+- `on(event_type, ...)` - Decorator for subscribing
+- `once(event_type, ...)` - Decorator for one-time handler
+- `emit_async(event, data=None)` - Emit event asynchronously
+- `emit(event, data=None)` - Emit (async from sync context)
+- `emit_sync(event, data=None)` - Emit synchronously (sync handlers only)
+- `get_history(event_type=None, limit=None)` - Get event history
+- `clear_history()` - Clear in-memory history
+- `clear_handlers()` - Remove all handlers
+
+### Events
+
+- `BaseEvent` - Pydantic-based event (or dataclass fallback)
+- `StringEvent` - Simple string-based event with data dict
+
+## License
+
+MIT
+