Metadata-Version: 2.4
Name: protobunny
Version: 0.1.0
Summary: Protobuf messages and python mqtt messaging toolkit
Author-email: Sander Koelstra <sander.koelstra@am-flow.com.com>, Domenico Nappo <domenico.nappo@am-flow.com>, Sem Mulder <sem.mulder@am-flow.com>
Requires-Python: >=3.10,<3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aio-pika>=7.1.0
Requires-Dist: betterproto[compiler]<3,>=2.0.0b7
Requires-Dist: grpcio-tools<2,>=1.62.0
Requires-Dist: numpy>=1.26
Requires-Dist: pytest-env>=1.1.3
Requires-Dist: tomli; python_version < "3.11"
Dynamic: license-file
Dynamic: requires-python

<div style="width: 50%; margin: 0 auto;">
  <img src="./images/logo.png" alt="protobunny Logo" height="512">
</div>

# Protobunny

Note: The project is in early development.

The `protobunny` library simplifies messaging for asynchronous tasks by providing:

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

## Requirements

- Python >= 3.10, < 3.13
- A running RabbitMQ instance (v4.0+ is preferred)

## 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 RabbitMQ messaging
- 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](QUICK_START.md) for installation and quick start guide on this repo.

Full documentation is 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:
  - multiprocessing.Queue or queue.Queue for simple local scenarios
  - Redis
  - NATS
  - Cloud providers (AWS SQS/SNS)
---

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