event-forge 1.1.0__tar.gz

event_forge-1.1.0/.gitignore

@@ -0,0 +1,75 @@
+.idea/
+.claude/tasks/
+.claude/knowledge-base/
+
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Build outputs
+dist/
+*.tsbuildinfo
+
+# Backup files
+*.bak
+*.bak*
+
+# Test coverage
+coverage/
+.nyc_output/
+
+# IDE
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# Cache
+.turbo/
+.cache/
+.eslintcache
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.venv/
+venv/
+ENV/
+env/

event_forge-1.1.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: event-forge
+Version: 1.1.0
+Summary: Universal Inbox-Outbox Pattern Library for Python - reliable message delivery in distributed systems
+Project-URL: Homepage, https://github.com/codeforprod/Event-Forge
+Project-URL: Documentation, https://github.com/codeforprod/Event-Forge/tree/main/packages/python
+Project-URL: Repository, https://github.com/codeforprod/Event-Forge
+Project-URL: Issues, https://github.com/codeforprod/Event-Forge/issues
+Author-email: ProdForCode <dev@prodforcode.com>
+License: MIT
+Keywords: inbox,message,mongodb,outbox,pattern,postgresql,rabbitmq,sqlalchemy,transactional
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.7.0; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.0.285; extra == 'dev'
+Provides-Extra: mongodb
+Requires-Dist: motor<4.0.0,>=3.3.0; extra == 'mongodb'
+Provides-Extra: rabbitmq
+Requires-Dist: aio-pika<10.0.0,>=9.0.0; extra == 'rabbitmq'
+Description-Content-Type: text/markdown
+
+# Event-Forge (Python)
+
+Python implementation of the Universal Inbox-Outbox Pattern for reliable message delivery in distributed systems.
+
+## Installation
+
+```bash
+pip install event-forge
+```
+
+With RabbitMQ support:
+```bash
+pip install event-forge[rabbitmq]
+```
+
+With MongoDB support:
+```bash
+pip install event-forge[mongodb]
+```
+
+## Requirements
+
+- Python >=3.10
+- SQLAlchemy >= 2.0 (async support)
+- Pydantic >= 2.0
+
+## Quick Start
+
+### PostgreSQL + SQLAlchemy
+
+```python
+from event_forge import OutboxService, CreateOutboxMessageDto, OutboxConfig
+from event_forge.repositories.sqlalchemy import (
+    SQLAlchemyOutboxRepository,
+    Base,
+)
+from event_forge.publishers.aio_pika_publisher import AioPikaPublisher
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+
+# Setup database
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
+session_factory = async_sessionmaker(engine, expire_on_commit=False)
+
+# Create tables
+async with engine.begin() as conn:
+    await conn.run_sync(Base.metadata.create_all)
+
+# Setup repository and publisher
+repository = SQLAlchemyOutboxRepository(session_factory)
+publisher = AioPikaPublisher(
+    url="amqp://guest:guest@localhost/",
+    exchange_name="events",
+)
+
+# Create service
+outbox = OutboxService(
+    repository=repository,
+    publisher=publisher,
+    config=OutboxConfig(polling_interval=1.0, batch_size=10),
+)
+
+# Connect publisher and start polling
+await publisher.connect()
+outbox.start_polling()
+
+# Create message in transaction
+async def create_user_event(session):
+    dto = CreateOutboxMessageDto(
+        aggregate_type="User",
+        aggregate_id="user-123",
+        event_type="user.created",
+        payload={"email": "user@example.com", "name": "John Doe"},
+    )
+    return await outbox.create_message(dto, session)
+
+await outbox.with_transaction(create_user_event)
+```
+
+### Fire-and-Forget Client
+
+```python
+from event_forge import EventForgeAgentClient, OutboxConfig
+from event_forge.repositories.sqlalchemy import SQLAlchemyOutboxRepository
+from event_forge.publishers.aio_pika_publisher import AioPikaPublisher
+
+client = EventForgeAgentClient(
+    repository=SQLAlchemyOutboxRepository(session_factory),
+    publisher=AioPikaPublisher(url="amqp://localhost/", exchange_name="events"),
+)
+
+await client.start()
+
+# Fire-and-forget
+await client.fire(
+    aggregate_type="Call",
+    aggregate_id="call-123",
+    event_type="call.completed",
+    payload={"duration": 120, "status": "success"},
+)
+
+await client.stop()
+```
+
+### Inbox Pattern
+
+```python
+from event_forge import InboxService, CreateInboxMessageDto, InboxConfig
+from event_forge.repositories.sqlalchemy import SQLAlchemyInboxRepository
+
+# Setup
+repository = SQLAlchemyInboxRepository(session_factory)
+inbox = InboxService(
+    repository=repository,
+    config=InboxConfig(enable_retry=True),
+)
+
+# Register handler
+async def handle_order(message):
+    print(f"Processing order: {message.payload}")
+
+inbox.register_handler("order.placed", handle_order)
+
+# Process incoming message (with automatic deduplication)
+dto = CreateInboxMessageDto(
+    message_id="ext-msg-123",
+    source="external-system",
+    event_type="order.placed",
+    payload={"order_id": "order-456", "amount": 99.99},
+)
+
+await inbox.receive_message(dto)
+
+# Start retry polling for failed messages
+inbox.start_retry_polling()
+```
+
+### RabbitMQ Consumer
+
+```python
+from event_forge.consumers import AioPikaConsumer
+
+consumer = AioPikaConsumer(
+    url="amqp://guest:guest@localhost/",
+    inbox_service=inbox,
+    queue_name="my-service-inbox",
+    exchange_name="events",
+    routing_keys=["Order.*", "User.*"],
+)
+
+await consumer.start()
+```
+
+## Architecture
+
+Matches the TypeScript implementation with full wire format compatibility:
+
+- **Models**: Pydantic v2 models (type-safe DTOs)
+- **Repositories**: SQLAlchemy async for PostgreSQL (SELECT FOR UPDATE SKIP LOCKED)
+- **Services**: `OutboxService`, `InboxService` with exponential backoff and event emission
+- **Publishers**: `AioPikaPublisher` for RabbitMQ (connect_robust, auto-reconnect)
+- **Consumers**: `AioPikaConsumer` with inbox recording and deduplication
+- **Client**: `EventForgeAgentClient` fire-and-forget facade
+
+## Features
+
+- **Transactional Guarantees** — Messages created in same transaction as business logic
+- **Automatic Retry** — Exponential backoff with jitter for failed publishes
+- **Duplicate Detection** — Inbox pattern prevents duplicate processing
+- **Async/Await** — Full async support with SQLAlchemy 2.0
+- **Type Safety** — Pydantic v2 models for validation
+- **Wire Format Compatible** — camelCase JSON body, AMQP headers match Node.js publisher
+- **Auto-Reconnect** — aio-pika connect_robust for RabbitMQ resilience
+- **Event Emission** — SimpleEventEmitter for lifecycle hooks
+
+## Node.js Compatibility
+
+For TypeScript/JavaScript projects, use the NPM packages:
+- `@prodforcode/event-forge-core`
+- `@prodforcode/event-forge-typeorm`
+- `@prodforcode/event-forge-mongoose`
+- `@prodforcode/event-forge-rabbitmq-publisher`
+- `@prodforcode/event-forge-nestjs`
+
+## Documentation
+
+For full documentation, see the [main README](../../README_INBOX_OUTBOX.md).
+
+## License
+
+MIT

event_forge-1.1.0/README.md

@@ -0,0 +1,190 @@
+# Event-Forge (Python)
+
+Python implementation of the Universal Inbox-Outbox Pattern for reliable message delivery in distributed systems.
+
+## Installation
+
+```bash
+pip install event-forge
+```
+
+With RabbitMQ support:
+```bash
+pip install event-forge[rabbitmq]
+```
+
+With MongoDB support:
+```bash
+pip install event-forge[mongodb]
+```
+
+## Requirements
+
+- Python >=3.10
+- SQLAlchemy >= 2.0 (async support)
+- Pydantic >= 2.0
+
+## Quick Start
+
+### PostgreSQL + SQLAlchemy
+
+```python
+from event_forge import OutboxService, CreateOutboxMessageDto, OutboxConfig
+from event_forge.repositories.sqlalchemy import (
+    SQLAlchemyOutboxRepository,
+    Base,
+)
+from event_forge.publishers.aio_pika_publisher import AioPikaPublisher
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+
+# Setup database
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
+session_factory = async_sessionmaker(engine, expire_on_commit=False)
+
+# Create tables
+async with engine.begin() as conn:
+    await conn.run_sync(Base.metadata.create_all)
+
+# Setup repository and publisher
+repository = SQLAlchemyOutboxRepository(session_factory)
+publisher = AioPikaPublisher(
+    url="amqp://guest:guest@localhost/",
+    exchange_name="events",
+)
+
+# Create service
+outbox = OutboxService(
+    repository=repository,
+    publisher=publisher,
+    config=OutboxConfig(polling_interval=1.0, batch_size=10),
+)
+
+# Connect publisher and start polling
+await publisher.connect()
+outbox.start_polling()
+
+# Create message in transaction
+async def create_user_event(session):
+    dto = CreateOutboxMessageDto(
+        aggregate_type="User",
+        aggregate_id="user-123",
+        event_type="user.created",
+        payload={"email": "user@example.com", "name": "John Doe"},
+    )
+    return await outbox.create_message(dto, session)
+
+await outbox.with_transaction(create_user_event)
+```
+
+### Fire-and-Forget Client
+
+```python
+from event_forge import EventForgeAgentClient, OutboxConfig
+from event_forge.repositories.sqlalchemy import SQLAlchemyOutboxRepository
+from event_forge.publishers.aio_pika_publisher import AioPikaPublisher
+
+client = EventForgeAgentClient(
+    repository=SQLAlchemyOutboxRepository(session_factory),
+    publisher=AioPikaPublisher(url="amqp://localhost/", exchange_name="events"),
+)
+
+await client.start()
+
+# Fire-and-forget
+await client.fire(
+    aggregate_type="Call",
+    aggregate_id="call-123",
+    event_type="call.completed",
+    payload={"duration": 120, "status": "success"},
+)
+
+await client.stop()
+```
+
+### Inbox Pattern
+
+```python
+from event_forge import InboxService, CreateInboxMessageDto, InboxConfig
+from event_forge.repositories.sqlalchemy import SQLAlchemyInboxRepository
+
+# Setup
+repository = SQLAlchemyInboxRepository(session_factory)
+inbox = InboxService(
+    repository=repository,
+    config=InboxConfig(enable_retry=True),
+)
+
+# Register handler
+async def handle_order(message):
+    print(f"Processing order: {message.payload}")
+
+inbox.register_handler("order.placed", handle_order)
+
+# Process incoming message (with automatic deduplication)
+dto = CreateInboxMessageDto(
+    message_id="ext-msg-123",
+    source="external-system",
+    event_type="order.placed",
+    payload={"order_id": "order-456", "amount": 99.99},
+)
+
+await inbox.receive_message(dto)
+
+# Start retry polling for failed messages
+inbox.start_retry_polling()
+```
+
+### RabbitMQ Consumer
+
+```python
+from event_forge.consumers import AioPikaConsumer
+
+consumer = AioPikaConsumer(
+    url="amqp://guest:guest@localhost/",
+    inbox_service=inbox,
+    queue_name="my-service-inbox",
+    exchange_name="events",
+    routing_keys=["Order.*", "User.*"],
+)
+
+await consumer.start()
+```
+
+## Architecture
+
+Matches the TypeScript implementation with full wire format compatibility:
+
+- **Models**: Pydantic v2 models (type-safe DTOs)
+- **Repositories**: SQLAlchemy async for PostgreSQL (SELECT FOR UPDATE SKIP LOCKED)
+- **Services**: `OutboxService`, `InboxService` with exponential backoff and event emission
+- **Publishers**: `AioPikaPublisher` for RabbitMQ (connect_robust, auto-reconnect)
+- **Consumers**: `AioPikaConsumer` with inbox recording and deduplication
+- **Client**: `EventForgeAgentClient` fire-and-forget facade
+
+## Features
+
+- **Transactional Guarantees** — Messages created in same transaction as business logic
+- **Automatic Retry** — Exponential backoff with jitter for failed publishes
+- **Duplicate Detection** — Inbox pattern prevents duplicate processing
+- **Async/Await** — Full async support with SQLAlchemy 2.0
+- **Type Safety** — Pydantic v2 models for validation
+- **Wire Format Compatible** — camelCase JSON body, AMQP headers match Node.js publisher
+- **Auto-Reconnect** — aio-pika connect_robust for RabbitMQ resilience
+- **Event Emission** — SimpleEventEmitter for lifecycle hooks
+
+## Node.js Compatibility
+
+For TypeScript/JavaScript projects, use the NPM packages:
+- `@prodforcode/event-forge-core`
+- `@prodforcode/event-forge-typeorm`
+- `@prodforcode/event-forge-mongoose`
+- `@prodforcode/event-forge-rabbitmq-publisher`
+- `@prodforcode/event-forge-nestjs`
+
+## Documentation
+
+For full documentation, see the [main README](../../README_INBOX_OUTBOX.md).
+
+## License
+
+MIT

event_forge-1.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "event-forge"
+version = "1.1.0"
+description = "Universal Inbox-Outbox Pattern Library for Python - reliable message delivery in distributed systems"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "ProdForCode", email = "dev@prodforcode.com"}
+]
+keywords = ["inbox", "outbox", "transactional", "message", "pattern", "postgresql", "mongodb", "rabbitmq", "sqlalchemy"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Framework :: AsyncIO",
+]
+
+dependencies = [
+    "pydantic>=2.0.0,<3.0.0",
+    "sqlalchemy[asyncio]>=2.0.0,<3.0.0",
+]
+
+[project.optional-dependencies]
+rabbitmq = [
+    "aio-pika>=9.0.0,<10.0.0",
+]
+mongodb = [
+    "motor>=3.3.0,<4.0.0",
+]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.1.0",
+    "black>=23.7.0",
+    "ruff>=0.0.285",
+    "mypy>=1.5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/codeforprod/Event-Forge"
+Documentation = "https://github.com/codeforprod/Event-Forge/tree/main/packages/python"
+Repository = "https://github.com/codeforprod/Event-Forge"
+Issues = "https://github.com/codeforprod/Event-Forge/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/event_forge"]
+
+[tool.black]
+line-length = 100
+target-version = ['py310', 'py311', 'py312']
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-v --tb=short"

event_forge-1.1.0/src/event_forge/__init__.py

@@ -0,0 +1,65 @@
+"""Event-Forge Inbox-Outbox Pattern Library for Python."""
+__version__ = "1.1.0"
+
+# Models
+from .models import (
+    CreateInboxMessageDto,
+    CreateOutboxMessageDto,
+    InboxMessage,
+    InboxMessageStatus,
+    OutboxMessage,
+    OutboxMessageStatus,
+)
+
+# Errors
+from .errors import DuplicateMessageError, ProcessingError
+
+# Config
+from .config import InboxConfig, OutboxConfig
+
+# Events
+from .events import InboxEvents, OutboxEvents, SimpleEventEmitter
+
+# Services
+from .services import InboxService, OutboxService
+
+# Repository interfaces
+from .repositories import IInboxRepository, IOutboxRepository, RecordInboxMessageResult
+
+# Publisher interfaces
+from .publishers import IMessagePublisher, PublishOptions
+
+# Client facade
+from .client import EventForgeAgentClient
+
+__all__ = [
+    # Models
+    "CreateInboxMessageDto",
+    "CreateOutboxMessageDto",
+    "InboxMessage",
+    "InboxMessageStatus",
+    "OutboxMessage",
+    "OutboxMessageStatus",
+    # Errors
+    "DuplicateMessageError",
+    "ProcessingError",
+    # Config
+    "InboxConfig",
+    "OutboxConfig",
+    # Events
+    "InboxEvents",
+    "OutboxEvents",
+    "SimpleEventEmitter",
+    # Services
+    "InboxService",
+    "OutboxService",
+    # Repository interfaces
+    "IInboxRepository",
+    "IOutboxRepository",
+    "RecordInboxMessageResult",
+    # Publisher interfaces
+    "IMessagePublisher",
+    "PublishOptions",
+    # Client facade
+    "EventForgeAgentClient",
+]