Metadata-Version: 2.4
Name: protobunny
Version: 0.1.2a1
Summary: A type-safe, sync/async Python messaging framework.
Author: Domenico Nappo, Sander Koelstra, Sem Mulder
Author-email: Domenico Nappo <domenico.nappo@am-flow.com>, Sander Koelstra <sander.koelstra@am-flow.com.com>, Sem Mulder <sem.mulder@am-flow.com>
Project-URL: homepage, https://am-flow.github.io/protobunny
Project-URL: repository, https://github.com/am-flow/protobunny
Project-URL: issues, https://github.com/am-flow/protobunny/issues
Keywords: protobuf,queues,mqtt,messaging,rabbitmq,redis,amqp,aio-pika,betterproto,mosquitto
Classifier: Development Status :: 3 - Alpha
Requires-Python: >=3.10,<3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: betterproto[compiler]<3,>=2.0.0b7
Requires-Dist: can-ada>=2.0.0
Requires-Dist: click>=8.2.1
Requires-Dist: grpcio-tools<2,>=1.62.0
Requires-Dist: pytest-env>=1.1.3
Requires-Dist: tomli; python_version < "3.11"
Requires-Dist: typing-extensions; python_version < "3.11"
Provides-Extra: rabbitmq
Requires-Dist: aio-pika>=7.1.0; extra == "rabbitmq"
Provides-Extra: redis
Requires-Dist: redis<8; extra == "redis"
Provides-Extra: numpy
Requires-Dist: numpy>=1.26; extra == "numpy"
Provides-Extra: mosquitto
Requires-Dist: aiomqtt>=2.4.0; extra == "mosquitto"
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# Protobunny

```{warning}
Note: The project is in early development.
```

Protobunny is the open-source evolution of [AM-Flow](https://am-flow.com)'s internal messaging library. 
While the original was purpose-built for RabbitMQ, this version has been completely re-engineered to provide a unified, 
type-safe interface for any message broker, including Redis and MQTT.

It simplifies messaging for asynchronous tasks by providing:

* A clean “message-first” API
* Python class generation from Protobuf messages using betterproto
* Connections facilities for backends
* Message publishing/subscribing with typed topics
* Support also “task-like” queues (shared/competing consumers) vs. broadcast subscriptions
* Generate and consume `Result` messages (success/failure + optional return payload)
* Transparent messages serialization/deserialization
 * Support async and sync contexts
* Transparently serialize "JSON-like" payload fields (numpy-friendly)


## Requirements

- Python >= 3.10, < 3.14
- Backend message broker (e.g. RabbitMQ)

## Project scope

Protobunny is designed for teams who use messaging to coordinate work between microservices or different python processes and want:

- A small API surface, easy to learn and use, both async and sync
- Typed messaging with protobuf messages as payloads
- Supports various backends by simple configuration: RabbitMQ, Redis, Mosquitto, local in-process queues
- Consistent topic naming and routing
- Builtin task queue semantics and result messages
- Transparent handling of JSON-like payload fields as plain dictionaries/lists
- Optional validation of required fields
- Builtin logging service

---

## Usage

See the [Quick example on GitHub](https://github.com/am-flow/protobunny/blob/main/QUICK_START.md) for installation and quick start guide.

Full docs are available at [https://am-flow.github.io/protobunny/](https://am-flow.github.io/protobunny/).

---

## Development

### Run tests
```bash
make test
```

### Integration tests (RabbitMQ required)

Integration tests expect RabbitMQ to be running (for example via Docker Compose in this repo):
```bash
docker compose up -d
make integration-test
```
---

### Future work

- Support grcp
- Support for RabbitMQ certificates (through `pika`)
- More backends:
  - NATS
  - Kafka
  - Cloud providers (AWS SQS/SNS)

---

## License
`MIT`
Copyright (c) 2026 AM-Flow b.v.
