Omni-Box Documentation¶
omni-box is a Python 3.12+ library that implements the Transactional Outbox and Transactional Inbox patterns for async services.
Contents¶
- Architecture — layers, pipeline, commit semantics.
- User guide — quick start, customisation, observability.
- Storage adapters — protocols and how to write a new backend.
- Migrations & DDL — PostgreSQL schema details.
- Troubleshooting — common issues and tuning tips.
- API reference — public surface re-exported from
omni_box.
Installation¶
Optional extras¶
| Extra | Purpose |
|---|---|
postgres |
SQLAlchemy 2 + asyncpg adapter (omni_box.infra.storage.postgres). |
kafka |
Pure aiokafka publisher/consumer (omni_box.infra.brokers.kafka). |
metrics |
Prometheus implementations of the metrics protocols. |
opentelemetry |
Enables OpenTelemetryStep. |
settings |
pydantic-settings helpers in omni_box.contrib.settings. |
dishka |
DI providers in omni_box.contrib.dishka. |
The Kafka adapter talks to aiokafka directly — no third-party publisher/consumer wrapper is required.
Key features¶
- Transactional Outbox — guarantee reliable event publishing tied to your DB transaction.
- Transactional Inbox — effectively-once processing via the unique
(message_id, consumer_group)index plusEXACTLY_ONCE_INBOXcommit semantics. - Pipeline architecture —
EventProcessorBuildercomposes built-in or custom steps and strategies. - No UoW lock-in — the library never opens transactions; the caller (or the
InboxTransactionProviderProtocol) owns the session. - Observability hooks —
InboxMetrics,OutboxMetrics,ProcessingMetrics, OpenTelemetry, structured logging.