Metadata-Version: 2.4
Name: broka
Version: 0.0.2
Summary: A typed, asynchronous, transport-agnostic message broker for Python applications
Author: broka contributors
License-Expression: MIT
Project-URL: Documentation, https://github.com/broka-dev/broka#readme
Project-URL: Issues, https://github.com/broka-dev/broka/issues
Project-URL: Source, https://github.com/broka-dev/broka
Keywords: asyncio,events,message-broker,pubsub,rpc
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aio-pika>=10.0.1
Requires-Dist: aiokafka>=0.14.0
Requires-Dist: django>=6.1
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: redis>=8.1.0
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == "redis"
Provides-Extra: rabbitmq
Requires-Dist: aio-pika>=9.4; extra == "rabbitmq"
Provides-Extra: kafka
Requires-Dist: aiokafka>=0.12; extra == "kafka"
Provides-Extra: django
Requires-Dist: Django>=5.0; extra == "django"
Provides-Extra: msgpack
Requires-Dist: msgpack>=1.0; extra == "msgpack"
Provides-Extra: yaml
Requires-Dist: PyYAML>=6.0; extra == "yaml"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.24; extra == "otel"
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Provides-Extra: all
Requires-Dist: redis>=5.0; extra == "all"
Requires-Dist: aio-pika>=9.4; extra == "all"
Requires-Dist: aiokafka>=0.12; extra == "all"
Requires-Dist: Django>=5.0; extra == "all"
Requires-Dist: msgpack>=1.0; extra == "all"
Requires-Dist: PyYAML>=6.0; extra == "all"
Requires-Dist: opentelemetry-api>=1.24; extra == "all"
Dynamic: license-file

# broka

`broka` is a typed, asynchronous, transport-agnostic message broker for Python 3.12+.
Applications publish domain messages through one `Broker` API; pluggable engines decide how the
serialized envelopes travel. The core package contains no application- or framework-specific
business logic.

```python
import asyncio
from dataclasses import dataclass

from broka import Broker, Delivery, event


@event("orders.created", version=1)
@dataclass(frozen=True, slots=True)
class OrderCreated:
  order_id: str
  total: int


async def main() -> None:
  received = asyncio.Event()

  async def handle(delivery: Delivery[OrderCreated]) -> None:
    print(delivery.message.order_id)
    received.set()

  async with Broker.from_config({"engine": "memory"}) as broker:
    await broker.subscribe("orders.*", handle)
    await broker.publish(OrderCreated(order_id="A-100", total=4200))
    await asyncio.wait_for(received.wait(), timeout=1)


asyncio.run(main())
```

## Why broka?

- One stable, fully asynchronous façade for publishing, subscriptions, batches, and request/reply.
- Immutable, independently versioned envelopes and strongly typed event reconstruction.
- Exact, namespace, wildcard, type, and header routing independent of a transport's native syntax.
- Deterministic inbound and outbound middleware pipelines.
- Framework-level acknowledgement state, retries, jittered backoff, circuit breaking, dead letters,
  idempotency, and bounded backpressure.
- Built-in deterministic `local` and queued `memory` engines.
- Optional Redis Pub/Sub/Streams, RabbitMQ, and Kafka engines with truthful capabilities.
- Lazy entry-point discovery under `broka.engines`; imports never open a connection or start a task.
- ASGI lifespan, FastAPI/Starlette, Celery, and optional Django helpers.
- Structured health, metrics, tracing hooks, and deterministic testing utilities.

## Install

```bash
python -m pip install broka
```

External clients are optional:

```bash
python -m pip install "broka[redis]"
python -m pip install "broka[rabbitmq]"
python -m pip install "broka[kafka]"
python -m pip install "broka[django,otel]"
```

Dedicated plugin distributions (`broka-redis`, `broka-rabbitmq`, and `broka-kafka`) expose the same
engine implementations through the same entry-point group.

## Reliability is explicit

`broka` does not pretend Redis Pub/Sub, Redis Streams, AMQP acknowledgements, and Kafka offset
commits are equivalent. Engines publish a structured capability set. An operation requesting an
unsupported guarantee raises `UnsupportedCapabilityError`; it is never silently weakened to a
less reliable mode.

The built-in engines are process-local. Use an external engine whenever independent processes must
communicate. Redis Streams, RabbitMQ, and Kafka require their respective services; integration
tests for those transports are opt-in.

## Documentation

- [Getting started](docs/getting-started.md)
- [Core concepts and architecture](docs/core-concepts.md)
- [Envelope specification and event versioning](docs/envelopes.md)
- [Routing and middleware](docs/routing-and-middleware.md)
- [Acknowledgements, retries, and dead letters](docs/reliability.md)
- [Engine configuration and plugin authoring](docs/engines.md)
- [ASGI, Django, FastAPI/Starlette, and Celery](docs/integrations.md)
- [Observability and security](docs/operations.md)
- [Testing and deployment](docs/testing-and-deployment.md)
- [API reference](docs/api-reference.md)
- [Troubleshooting and migration](docs/troubleshooting.md)

## Development

```bash
python -m pip install -e ".[dev]"
ruff format .
ruff check .
mypy src/broka
pytest
```

The architecture decisions in [`docs/adr`](docs/adr/README.md) explain the important responsibility
boundaries. See [AGENTS.md](AGENTS.md) for the complete build contract; project-facing names in that
source brief are intentionally implemented as `broka`.

## License

MIT
