deegzlibs-command-bus 1.2.0__tar.gz

deegzlibs_command_bus-1.2.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: deegzlibs-command-bus
+Version: 1.2.0
+Summary: A small command bus with pluggable queue adapters and response stores (e.g. SQS, RabbitMQ, Redis, etc.)
+Home-page: https://github.com/deegzlibs/deegzlibs
+Author: Diego Alejos
+Author-email: Diego Alejos <lego.admin@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/deegzlibs/deegzlibs-command-bus
+Project-URL: Repository, https://github.com/deegzlibs/deegzlibs-command-bus
+Project-URL: Issues, https://github.com/deegzlibs/deegzlibs-command-bus/issues
+Keywords: command-bus,command-pattern,queue,sqs,rabbitmq,redis,async,pydantic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Provides-Extra: sqs
+Requires-Dist: boto3; extra == "sqs"
+Provides-Extra: rabbitmq
+Requires-Dist: pika>=1.0; extra == "rabbitmq"
+Provides-Extra: redis
+Requires-Dist: redis>=4.0; extra == "redis"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# DeegzLibs CommandBus (Python)
+
+A small command bus with pluggable queue adapters. Define command messages as Pydantic models, register handlers, and execute commands in-process or via a queue (e.g. AWS SQS, RabbitMQ, Redis).
+
+## Installation
+
+```bash
+pip install deegzlibs-command-bus
+```
+
+Optional extras: **`[sqs]`**, **`[redis]`**, **`[rabbitmq]`**. See [Installation](docs/installation.md).
+
+## Quick start
+
+```python
+from command_bus import CommandBus, CommandBusRouter, CommandMessage, CommandHandler
+from command_bus.adapters import InMemoryCommandBusAdapter
+
+router = CommandBusRouter()
+adapter = InMemoryCommandBusAdapter(queue_name="commands")
+bus = CommandBus(queue_adapter=adapter, command_router=router)
+
+@router.command()
+def on_order_created(order_id: str, amount_cents: int):
+    print(f"Order {order_id}: {amount_cents} cents")
+
+# Fire-and-forget
+await bus.execute(on_order_created(order_id="ord-1", amount_cents=1999), wait=False)
+
+# Worker: poll and dispatch
+await bus.work()
+```
+
+To run workers as **separate OS processes** (useful when handlers do a lot of CPU work), use the built-in CLI, e.g. **`command-bus-worker myapp.worker:bus --workers 4`** (omit **`:bus`** if your bus lives on attribute **`bus`**). For several queues in one supervised tree, point at a **`CommandBusGroup`**, e.g. **`myapp.worker:command_bus_group`** (see [Worker CLI](docs/cli.md)).
+
+For full examples (messages, handlers, SQS/Redis, execute-and-wait), see the [documentation](docs/index.md).
+
+## Documentation
+
+| Topic | Description |
+|-------|-------------|
+| [Installation](docs/installation.md) | Package and extras. |
+| [Quick start](docs/quickstart.md) | Messages, handlers, register, execute. |
+| [Handler decorator](docs/handler-decorator.md) | `@router.command()` and message factory. |
+| [Message formats and parsers](docs/message-formats-and-parsers.md) | Repr, JSON, Base64, custom parser. |
+| [Client and worker](docs/client-and-worker.md) | Shared module, producer, consumer. |
+| [Worker CLI](docs/cli.md) | `command-bus-worker module[:attr]` — `CommandBus` or `CommandBusGroup`, fork/spawn. |
+| [Queue adapters](docs/queue-adapters.md) | In-memory, SQS, RabbitMQ, Redis. |
+| [Execute and wait](docs/execute-and-wait.md) | Response store, request/response. |
+| [API reference](docs/api-reference.md) | Types and methods overview. |
+
+## License
+
+MIT

deegzlibs_command_bus-1.2.0/README.md

@@ -0,0 +1,54 @@
+# DeegzLibs CommandBus (Python)
+
+A small command bus with pluggable queue adapters. Define command messages as Pydantic models, register handlers, and execute commands in-process or via a queue (e.g. AWS SQS, RabbitMQ, Redis).
+
+## Installation
+
+```bash
+pip install deegzlibs-command-bus
+```
+
+Optional extras: **`[sqs]`**, **`[redis]`**, **`[rabbitmq]`**. See [Installation](docs/installation.md).
+
+## Quick start
+
+```python
+from command_bus import CommandBus, CommandBusRouter, CommandMessage, CommandHandler
+from command_bus.adapters import InMemoryCommandBusAdapter
+
+router = CommandBusRouter()
+adapter = InMemoryCommandBusAdapter(queue_name="commands")
+bus = CommandBus(queue_adapter=adapter, command_router=router)
+
+@router.command()
+def on_order_created(order_id: str, amount_cents: int):
+    print(f"Order {order_id}: {amount_cents} cents")
+
+# Fire-and-forget
+await bus.execute(on_order_created(order_id="ord-1", amount_cents=1999), wait=False)
+
+# Worker: poll and dispatch
+await bus.work()
+```
+
+To run workers as **separate OS processes** (useful when handlers do a lot of CPU work), use the built-in CLI, e.g. **`command-bus-worker myapp.worker:bus --workers 4`** (omit **`:bus`** if your bus lives on attribute **`bus`**). For several queues in one supervised tree, point at a **`CommandBusGroup`**, e.g. **`myapp.worker:command_bus_group`** (see [Worker CLI](docs/cli.md)).
+
+For full examples (messages, handlers, SQS/Redis, execute-and-wait), see the [documentation](docs/index.md).
+
+## Documentation
+
+| Topic | Description |
+|-------|-------------|
+| [Installation](docs/installation.md) | Package and extras. |
+| [Quick start](docs/quickstart.md) | Messages, handlers, register, execute. |
+| [Handler decorator](docs/handler-decorator.md) | `@router.command()` and message factory. |
+| [Message formats and parsers](docs/message-formats-and-parsers.md) | Repr, JSON, Base64, custom parser. |
+| [Client and worker](docs/client-and-worker.md) | Shared module, producer, consumer. |
+| [Worker CLI](docs/cli.md) | `command-bus-worker module[:attr]` — `CommandBus` or `CommandBusGroup`, fork/spawn. |
+| [Queue adapters](docs/queue-adapters.md) | In-memory, SQS, RabbitMQ, Redis. |
+| [Execute and wait](docs/execute-and-wait.md) | Response store, request/response. |
+| [API reference](docs/api-reference.md) | Types and methods overview. |
+
+## License
+
+MIT

deegzlibs_command_bus-1.2.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.poetry]
+name = "deegzlibs-command-bus"
+version = "1.2.0"
+description = "A small command bus with pluggable queue adapters (e.g. AWS SQS)"
+readme = "README.md"
+authors = ["Diego Alejos <lego.admin@gmail.com>"]
+license = "MIT"
+packages = [{include = "command_bus", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.8"
+pydantic = ">=2.0"
+boto3 = {version = "*", optional = true}
+pika = {version = ">=1.0", optional = true}
+redis = {version = ">=4.0", optional = true}
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.0.0"
+pytest-cov = "^4.0.0"
+pytest-asyncio = "^0.21.0"
+commitizen = "^3.0.0"
+
+[tool.poetry.extras]
+sqs = ["boto3"]
+rabbitmq = ["pika"]
+redis = ["redis"]
+
+[project]
+name = "deegzlibs-command-bus"
+version = "1.2.0"
+description = "A small command bus with pluggable queue adapters and response stores (e.g. SQS, RabbitMQ, Redis, etc.)"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [
+    {name = "Diego Alejos", email = "lego.admin@gmail.com"}
+]
+keywords = ["command-bus", "command-pattern", "queue", "sqs", "rabbitmq", "redis", "async", "pydantic"]
+dependencies = [
+    "pydantic>=2.0",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Distributed Computing",
+]
+
+[project.scripts]
+command-bus-worker = "command_bus.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/deegzlibs/deegzlibs-command-bus"
+Repository = "https://github.com/deegzlibs/deegzlibs-command-bus"
+Issues = "https://github.com/deegzlibs/deegzlibs-command-bus/issues"
+
+[project.optional-dependencies]
+sqs = ["boto3"]
+rabbitmq = ["pika>=1.0"]
+redis = ["redis>=4.0"]
+dev = ["pytest>=7.0.0", "pytest-cov>=4.0.0", "pytest-asyncio>=0.21.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "1.2.0"
+tag_format = "v$version"
+version_files = [
+    "pyproject.toml:version",
+    "setup.py:version",
+]

deegzlibs_command_bus-1.2.0/setup.cfg

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

deegzlibs_command_bus-1.2.0/setup.py

@@ -0,0 +1,43 @@
+from setuptools import find_packages, setup
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="deegzlibs-command-bus",
+    version="1.2.0",
+    author="Diego Alejos",
+    author_email="lego.admin@gmail.com",
+    description="A small command bus with pluggable queue adapters (e.g. AWS SQS)",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/deegzlibs/deegzlibs",
+    packages=find_packages(where="src"),
+    package_dir={"": "src"},
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+    ],
+    python_requires=">=3.8",
+    install_requires=[
+        "pydantic>=2.0",
+    ],
+    extras_require={
+        "sqs": ["boto3"],
+        "rabbitmq": ["pika>=1.0"],
+        "redis": ["redis>=4.0"],
+        "dev": [
+            "pytest>=7.0.0",
+            "pytest-cov>=4.0.0",
+            "pytest-asyncio>=0.21.0",
+        ],
+    },
+)

deegzlibs_command_bus-1.2.0/src/command_bus/__init__.py

@@ -0,0 +1,45 @@
+"""
+DeegzLibs CommandBus: a small command bus with pluggable queue adapters (e.g. SQS).
+"""
+
+from .bus import CommandBus
+from .command_bus_group import CommandBusGroup, WorkerConfig, resolve_bus_attr_on_module
+from .interfaces import (
+    CommandBusAdapter,
+    CommandBusInterface,
+    CommandBusRouterInterface,
+    CommandMessage,
+    CommandHandler,
+    ResponseStore,
+    TransmissibleBaseModel,
+)
+from .parsers import (
+    Base64MessageParser,
+    JsonMessageParser,
+    MessageParser,
+    MessageParserBase,
+    ReprMessageParser,
+)
+from .registry import CommandBusRouter, CommandBusRouterEntry, get_qual_name
+
+__all__ = [
+    "Base64MessageParser",
+    "CommandBus",
+    "CommandBusGroup",
+    "CommandBusAdapter",
+    "ResponseStore",
+    "CommandBusInterface",
+    "CommandBusRouter",
+    "CommandBusRouterEntry",
+    "CommandBusRouterInterface",
+    "CommandMessage",
+    "CommandHandler",
+    "JsonMessageParser",
+    "MessageParser",
+    "MessageParserBase",
+    "ReprMessageParser",
+    "TransmissibleBaseModel",
+    "WorkerConfig",
+    "resolve_bus_attr_on_module",
+    "get_qual_name",
+]

deegzlibs_command_bus-1.2.0/src/command_bus/adapters/__init__.py

@@ -0,0 +1,30 @@
+"""Queue and response adapters for the command bus."""
+
+from .queue import FileQueueAdapter, InMemoryCommandBusAdapter, SqsCommandBusAdapter
+
+__all__ = ["InMemoryCommandBusAdapter", "SqsCommandBusAdapter", "FileQueueAdapter"]
+
+try:
+    from .queue import RabbitMqCommandBusAdapter
+
+    __all__ += ["RabbitMqCommandBusAdapter"]
+except ImportError:
+    pass
+
+try:
+    from .queue import RedisCommandBusAdapter
+
+    __all__ += ["RedisCommandBusAdapter"]
+except ImportError:
+    pass
+
+from .response import FileResponseStore, InMemoryResponseStore
+
+__all__ += ["InMemoryResponseStore", "FileResponseStore"]
+
+try:
+    from .response import RedisResponseStore
+
+    __all__ += ["RedisResponseStore"]
+except ImportError:
+    pass

deegzlibs_command_bus-1.2.0/src/command_bus/adapters/queue/__init__.py

@@ -0,0 +1,21 @@
+"""Queue adapters for the command bus (SQS, RabbitMQ, Redis, in-memory, file, etc.)."""
+
+from .file import FileQueueAdapter
+from .in_memory import InMemoryCommandBusAdapter
+from .sqs import SqsCommandBusAdapter
+
+__all__ = ["InMemoryCommandBusAdapter", "SqsCommandBusAdapter", "FileQueueAdapter"]
+
+try:
+    from .rabbitmq import RabbitMqCommandBusAdapter
+
+    __all__ += ["RabbitMqCommandBusAdapter"]
+except ImportError:
+    pass
+
+try:
+    from .redis import RedisCommandBusAdapter
+
+    __all__ += ["RedisCommandBusAdapter"]
+except ImportError:
+    pass

deegzlibs_command_bus-1.2.0/src/command_bus/adapters/queue/file.py

@@ -0,0 +1,193 @@
+"""File-based queue adapter for persistent cross-process command queuing."""
+
+import fcntl
+import json
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List
+
+from ...interfaces import CommandBusAdapter, CommandMessage
+
+
+class FileQueueAdapter(CommandBusAdapter):
+    """File-based queue adapter that persists to disk for cross-process access."""
+
+    def __init__(
+        self, 
+        queue_name: str = "events", 
+        storage_file: Path = None,
+        default_visibility_timeout: int = 60
+    ) -> None:
+        """
+        Initialize file-based queue adapter.
+        
+        Args:
+            queue_name: Name of the queue
+            storage_file: Path to JSON file for storage. Defaults to ~/.qubot/queue.json
+            default_visibility_timeout: Default visibility timeout in seconds (how long a message
+                is hidden after being retrieved). Defaults to 60 seconds.
+        """
+        self.queue_name = queue_name
+        self.default_visibility_timeout = default_visibility_timeout
+        
+        if storage_file is None:
+            storage_dir = Path.home() / ".qubot"
+            storage_dir.mkdir(exist_ok=True)
+            storage_file = storage_dir / "queue.json"
+        
+        self.storage_file = Path(storage_file)
+        self._lock_file = self.storage_file.with_suffix('.lock')
+        self._lock = None
+
+    def _acquire_lock(self):
+        """Simple file-based lock."""
+        self._lock = open(self._lock_file, 'w', encoding='utf-8')
+        fcntl.flock(self._lock.fileno(), fcntl.LOCK_EX)
+
+    def _release_lock(self):
+        """Release file-based lock."""
+        if self._lock is not None:
+            try:
+                fcntl.flock(self._lock.fileno(), fcntl.LOCK_UN)
+            except (OSError, ValueError):
+                pass
+            finally:
+                self._lock.close()
+                self._lock = None
+
+    def _load_queue(self) -> List[Dict[str, Any]]:
+        """Load queue from disk."""
+        if not self.storage_file.exists():
+            return []
+        try:
+            with open(self.storage_file, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except (json.JSONDecodeError, FileNotFoundError):
+            return []
+
+    def _save_queue(self, queue: List[Dict[str, Any]]) -> None:
+        """Save queue to disk."""
+        try:
+            # Create parent directory if it doesn't exist
+            self.storage_file.parent.mkdir(parents=True, exist_ok=True)
+            with open(self.storage_file, 'w', encoding='utf-8') as f:
+                json.dump(queue, f, indent=2)
+        except Exception as e:
+            raise RuntimeError(f"Failed to save queue: {e}") from e
+
+    def enqueue(self, message_instance: CommandMessage, delay_seconds: int = 0) -> None:
+        """Add a message to the queue."""
+        try:
+            self._acquire_lock()
+            queue = self._load_queue()
+
+            # Serialize the message with full module path
+            # Format: module.ClassName(arg1=val1, arg2=val2, ...)
+            class_name = message_instance.__class__.__name__
+            module_name = message_instance.__class__.__module__
+            full_class_path = f"{module_name}.{class_name}"
+
+            # Get the arguments from the message instance
+            if hasattr(message_instance, 'model_dump'):
+                args_dict = message_instance.model_dump()
+            else:
+                args_dict = message_instance.__dict__
+            
+            args_str = ", ".join(f"{k}={repr(v)}" for k, v in args_dict.items())
+            message_str = f"{full_class_path}({args_str})"
+
+            queue.append({
+                "id": str(uuid.uuid4()),
+                "message": message_str,
+                "delay_until": time.time() + delay_seconds,
+                "queue_name": self.queue_name,
+                "hidden_until": 0  # Initially visible
+            })
+
+            self._save_queue(queue)
+        finally:
+            self._release_lock()
+
+    def dequeue(self, message_instance: Any) -> None:
+        """Remove a message from the queue."""
+        try:
+            self._acquire_lock()
+            queue = self._load_queue()
+
+            # Find and remove the message by ID (more reliable than message string)
+            msg_id = None
+            if hasattr(message_instance, '_data') and isinstance(message_instance._data, dict):
+                msg_id = message_instance._data.get("id")  # noqa: SLF001
+            
+            if msg_id:
+                queue[:] = [msg for msg in queue if msg.get("id") != msg_id]
+            else:
+                # Fallback to message string matching
+                message_str = message_instance.body if hasattr(message_instance, 'body') else str(message_instance)
+                queue[:] = [msg for msg in queue if msg.get("message") != message_str]
+
+            self._save_queue(queue)
+        finally:
+            self._release_lock()
+
+    def get_messages(
+        self,
+        max_messages: int = 1,
+        wait_seconds: int = 0,  # noqa: ARG002
+        visibility_timeout: int = None,
+        **kwargs: Any
+    ) -> List[Any]:
+        """
+        Get messages from the queue.
+        
+        Args:
+            max_messages: Maximum number of messages to retrieve
+            wait_seconds: Not used (file-based queue doesn't support blocking)
+            visibility_timeout: How long (in seconds) to hide the message after retrieval.
+                If None, uses the adapter's default_visibility_timeout.
+        """
+        try:
+            self._acquire_lock()
+            queue = self._load_queue()
+            current_time = time.time()
+            
+            # Use provided visibility timeout or default
+            vis_timeout = visibility_timeout if visibility_timeout is not None else self.default_visibility_timeout
+
+            # Filter messages for this queue that are:
+            # 1. For this queue name
+            # 2. Delay has passed (delay_until <= current_time)
+            # 3. Not currently hidden (hidden_until <= current_time)
+            visible_messages = [
+                msg for msg in queue
+                if msg.get("queue_name") == self.queue_name
+                and msg.get("delay_until", 0) <= current_time
+                and msg.get("hidden_until", 0) <= current_time
+            ]
+
+            # Limit to max_messages
+            messages_to_return = visible_messages[:max_messages]
+            
+            # Update hidden_until for returned messages (only if visibility_timeout > 0)
+            if vis_timeout > 0:
+                for msg in messages_to_return:
+                    msg["hidden_until"] = current_time + vis_timeout
+                
+                # Save the updated queue with new hidden_until values
+                if messages_to_return:
+                    self._save_queue(queue)
+
+            # Return as message objects (the bus will parse them)
+            class QueueMessage:
+                def __init__(self, msg_data: Dict[str, Any]):
+                    self.body = msg_data["message"]
+                    self._data = msg_data
+
+                def __repr__(self):
+                    return self.body
+
+            return [QueueMessage(msg) for msg in messages_to_return]
+        finally:
+            self._release_lock()
+

deegzlibs_command_bus-1.2.0/src/command_bus/adapters/queue/in_memory.py

@@ -0,0 +1,59 @@
+"""In-memory command bus adapter for tests or in-process use."""
+
+from collections import deque
+from typing import Any, List
+
+from ...interfaces import CommandBusAdapter, CommandMessage
+
+
+class _InMemoryMessage:
+    """Message wrapper with .body and .delete() for bus compatibility."""
+
+    __slots__ = ("body",)
+
+    def __init__(self, body: str) -> None:
+        self.body = body
+
+    def delete(self) -> None:
+        """No-op: message already removed from queue when get_messages() popped it."""
+        pass
+
+
+class InMemoryCommandBusAdapter(CommandBusAdapter):
+    """
+    In-memory FIFO queue adapter. Useful for tests or single-process command dispatch.
+    delay_seconds is ignored (no native delay); messages are available immediately.
+    """
+
+    def __init__(self, queue_name: str = "default") -> None:
+        self.queue_name = queue_name
+        self._queue: deque[str] = deque()
+
+    def enqueue(
+        self,
+        message_instance: CommandMessage,
+        delay_seconds: int = 0,
+    ) -> None:
+        """Append message to the queue. delay_seconds is ignored."""
+        self._queue.append(str(message_instance))
+
+    def dequeue(self, message_instance: Any) -> None:
+        """No-op: message was already removed when get_messages() popped it."""
+        if hasattr(message_instance, "delete"):
+            message_instance.delete()
+
+    def get_messages(
+        self,
+        max_messages: int = 1,
+        wait_seconds: int = 0,
+        **kwargs: Any,
+    ) -> List[_InMemoryMessage]:
+        """Pop up to max_messages from the queue. wait_seconds is ignored (no blocking)."""
+        out: List[_InMemoryMessage] = []
+        for _ in range(max_messages):
+            try:
+                body = self._queue.popleft()
+            except IndexError:
+                break
+            out.append(_InMemoryMessage(body=body))
+        return out