Some progress on typing

Author: domeniconappo

Makefile

@@ -103,6 +103,7 @@ test-py313:
 copy-md:
 	cp ./README.md docs/source/intro.md
 	cp ./QUICK_START.md docs/source/quick_start.md
+	cp ./RECIPES.md docs/source/recipes.md
 
 docs: copy-md
 	uv run sphinx-build -b html docs/source docs/build/html

QUICK_START.md

@@ -179,13 +179,15 @@ def worker1(task: mml.main.tasks.TaskMessage) -> None:
 
 def worker2(task: mml.main.tasks.TaskMessage) -> None:
     print("2- Working on:", task)
-
-pb.subscribe(mml.main.tasks.TaskMessage, worker1)
+import mymessagelib as mml
+pb.subscribe(mml.main.tasks.TasqkMessage, worker1)
 pb.subscribe(mml.main.tasks.TaskMessage, worker2)
 
 pb.publish(mml.main.tasks.TaskMessage(content="test1"))
 pb.publish(mml.main.tasks.TaskMessage(content="test2"))
 pb.publish(mml.main.tasks.TaskMessage(content="test3"))
+from protobunny.models import ProtoBunnyMessage
+print(isinstance(mml.main.tasks.TaskMessage(), ProtoBunnyMessage))
 ```
 
 You can also introspect/manage an underlying shared queue:

README.md

@@ -1,8 +1,8 @@
 # Protobunny
 
-```{warning}
-The project is in early development.
-```
+::: {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, 
@@ -26,11 +26,11 @@ Supported backends in the current version are:
 - Mosquitto
 - Python "backend" with Queue/asyncio.Queue for local in-processing testing
 
-```{note}
-Protobunny handles backend-specific logic internally to provide a consistent experience and a lean interface. 
-Direct access to the internal NATS or Redis clients is intentionally restricted. 
+::: {note}
+**Note**: Protobunny handles backend-specific logic internally to provide a consistent experience and a lean interface.
+Direct access to the internal NATS or Redis clients is intentionally restricted.
 If your project depends on specialized backend parameters not covered by our API, you may find the abstraction too restrictive.
-```
+:::
 
 
 ## Minimal requirements
@@ -63,8 +63,8 @@ While there are many messaging libraries for Python, Protobunny is built specifi
 
 * **Type-Safe by Design**: Built natively for `protobuf/betterproto`.
 * **Semantic Routing**: Zero-config infrastructure. Protobunny uses your Protobuf package structure to decide if a message should be broadcast (Pub/Sub) or queued (Producer/Consumer).
-* **Backend Agnostic**: Write your logic once. Switch between Redis, RabbitMQ, Mosquitto, or Local Queues by changing a single variable in configuration.
-* **Sync & Async**: Support for both modern `asyncio` and traditional synchronous workloads.
+* **Backend Agnostic**: You can choose between RabbitMQ, Redis, NATS, and Mosquitto. Python for local testing.
+* **Sync & Async**: Support for both `asyncio` and traditional synchronous workloads.
 * **Battle-Tested**: Derived from internal libraries used in production systems at AM-Flow.
 ---
 
@@ -78,6 +78,7 @@ While there are many messaging libraries for Python, Protobunny is built specifi
 | **Pattern Routing**    | ✅ Auto (`tasks` pkg)     | ❌ Manual Config         | ✅ Fixed                 |
 | **Framework Agnostic** | ✅ Yes                    | ⚠️ FastAPI-like focus   | ❌ Heavyweight           |
 
+---
 
 ## Usage
 

RECIPES.md

@@ -0,0 +1,19 @@
+# Recipes
+
+
+## Subscribe to a queue
+
+
+## Subscribe a task worker to a shared topic
+
+
+## Publish
+
+
+## Results workflow
+
+
+## Requeuing
+
+
+

docs/source/conf.py

@@ -28,6 +28,7 @@
     "sphinx.ext.viewcode",
     "myst_parser",
 ]
+myst_enable_extensions = ["colon_fence"]
 
 
 templates_path = ["_templates"]

docs/source/intro.md

@@ -1,29 +1,47 @@
 # Protobunny
 
-```{warning}
-Note: The project is in early development.
-```
+::: {warning}
+**Warning**: 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 several message brokers, including Redis and MQTT.
+type-safe interface for several message brokers, including Redis, NATS, and MQTT.
 
-It simplifies messaging for asynchronous tasks by providing:
+It simplifies messaging for asynchronous message handling by providing:
 
-* A clean “message-first” API
-* Python class generation from Protobuf messages using betterproto
-* Connections facilities for backends
+* A clean “message-first” API by using your protobuf definitions
 * Message publishing/subscribing with typed topics
-* Support also “task-like” queues (shared/competing consumers) vs. broadcast subscriptions
+* Supports "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)
+* Transparently serialize/deserialize custom "JSON-like" payload fields (numpy-friendly)
+* Support async and sync contexts
+
+Supported backends in the current version are:
+
+- RabbitMQ
+- Redis
+- NATS
+- Mosquitto
+- Python "backend" with Queue/asyncio.Queue for local in-processing testing
+
+::: {note}
+**Note**: Protobunny handles backend-specific logic internally to provide a consistent experience and a lean interface. 
+Direct access to the internal NATS or Redis clients is intentionally restricted. 
+If your project depends on specialized backend parameters not covered by our API, you may find the abstraction too restrictive.
+:::
 
 
 ## Minimal requirements
 
-- Python >= 3.10, < 3.14
+- Python >= 3.10 <=3.13
+- Core Dependencies: betterproto 2.0.0b7, grpcio-tools>=1.62.0
+- Backend Drivers (Optional based on your usage):
+  - NATS: nats-py (Requires NATS Server v2.10+ for full JetStream support).
+  - Redis: redis (Requires Redis Server v6.2+ for Stream support).
+  - RabbitMQ: aio-pika
+  - Mosquitto: aiomqtt
 
 
 ## Project scope
@@ -45,8 +63,8 @@ While there are many messaging libraries for Python, Protobunny is built specifi
 
 * **Type-Safe by Design**: Built natively for `protobuf/betterproto`.
 * **Semantic Routing**: Zero-config infrastructure. Protobunny uses your Protobuf package structure to decide if a message should be broadcast (Pub/Sub) or queued (Producer/Consumer).
-* **Backend Agnostic**: Write your logic once. Switch between Redis, RabbitMQ, Mosquitto, or Local Queues by changing a single variable in configuration.
-* **Sync & Async**: Support for both modern `asyncio` and traditional synchronous workloads.
+* **Backend Agnostic**: You can choose between RabbitMQ, Redis, NATS, and Mosquitto. Python for local testing.
+* **Sync & Async**: Support for both `asyncio` and traditional synchronous workloads.
 * **Battle-Tested**: Derived from internal libraries used in production systems at AM-Flow.
 ---
 
@@ -60,6 +78,7 @@ While there are many messaging libraries for Python, Protobunny is built specifi
 | **Pattern Routing**    | ✅ Auto (`tasks` pkg)     | ❌ Manual Config         | ✅ Fixed                 |
 | **Framework Agnostic** | ✅ Yes                    | ⚠️ FastAPI-like focus   | ❌ Heavyweight           |
 
+---
 
 ## Usage
 
@@ -74,7 +93,7 @@ Documentation home page: [https://am-flow.github.io/protobunny/](https://am-flow
 - [x] **Semantic Patterns**: Automatic `tasks` package routing.
 - [x] **Arbistrary dictionary parsing**: Transparently parse JSON-like fields as dictionaries/lists by using protobunny JsonContent type.
 - [x] **Result workflow**: Subscribe to results topics and receive protobunny `Result` messages produced by your callbacks.
-- [ ] **Cloud-Native**: NATS (Core & JetStream) integration.
+- [x] **Cloud-Native**: NATS (Core & JetStream) integration.
 - [ ] **Cloud Providers**: AWS (SQS/SNS) and GCP Pub/Sub.
 - [ ] **More backends**: Kafka support.
 

docs/source/quick_start.md

@@ -33,7 +33,7 @@ messages-directory = "messages"
 messages-prefix = "acme"
 generated-package-name = "mymessagelib.codegen"
 mode = "async"  # or "sync"
-backend = "rabbitmq"  #  available backends are ['rabbitmq', 'redis', 'mosquitto', 'python']
+backend = "rabbitmq"  #  available backends are ['rabbitmq', 'redis', 'nats', 'mosquitto', 'python']
 ```
 
 ### Install the library with `uv`, `poetry` or `pip`
@@ -294,7 +294,7 @@ if conn.is_connected():
     conn.close()
 ```
 
-If you set the `generated-package-root` folder option, you might need to add the path to your `sys.path`.
+If you set the `generated-package-root` folder option, you might need to add that path to your `sys.path`.
 You can do it conveniently by calling `config_lib` on top of your module, before importing the library:
 
 ```python
@@ -429,10 +429,12 @@ class TestLibAsync:
         await pb_asyncio.subscribe(ml.tests.TestMessage, self.on_message)
         await pb_asyncio.subscribe_results(ml.tests.TestMessage, self.on_message_results)
         await pb_asyncio.subscribe(ml.main.MyMessage, self.on_message_mymessage)
-
+        
+        # Send a simple message
         await pb_asyncio.publish(ml.main.MyMessage(content="test"))
+        # Send a message with arbitrary json content
         await pb_asyncio.publish(ml.tests.TestMessage(number=1, content="test", data={"test": 123}))
-
+                # Send three messages to verify the load balancing between the workers
         await pb_asyncio.publish(ml.main.tasks.TaskMessage(content="test1"))
         await pb_asyncio.publish(ml.main.tasks.TaskMessage(content="test2"))
         await pb_asyncio.publish(ml.main.tasks.TaskMessage(content="test3"))
@@ -441,6 +443,7 @@ class TestLibAsync:
 
 
 class TestLib:
+    # Sync version
     def on_message(self, message: ml.tests.TestMessage) -> None:
         log.info("Got: %s", message)
         result = message.make_result()

protobunny/__init__.py

@@ -53,12 +53,7 @@
 
 if tp.TYPE_CHECKING:
     from .core.results import Result
-    from .models import (
-        IncomingMessageProtocol,
-        LoggerCallback,
-        ProtoBunnyMessage,
-        SyncCallback,
-    )
+    from .models import PBM, IncomingMessageProtocol, LoggerCallback, SyncCallback
 
 __version__ = version(PACKAGE_NAME)
 
@@ -93,7 +88,7 @@ def reset_connection(**kwargs: tp.Any) -> "BaseSyncConnection":
     return conn.connect(**kwargs)
 
 
-def publish(message: "ProtoBunnyMessage") -> None:
+def publish(message: "PBM") -> None:
     """Synchronously publish a message to its corresponding queue.
 
     This method automatically determines the correct topic based on the
@@ -122,7 +117,7 @@ def publish_result(
 
 
 def subscribe(
-    pkg_or_msg: "type[ProtoBunnyMessage] | ModuleType",
+    pkg_or_msg: "type[PBM] | ModuleType",
     callback: "SyncCallback",
 ) -> "BaseSyncQueue":
     """Subscribe a callback function to the topic.
@@ -151,7 +146,7 @@ def subscribe(
 
 
 def subscribe_results(
-    pkg: "type[ProtoBunnyMessage] | ModuleType",
+    pkg: "type[PBM] | ModuleType",
     callback: "SyncCallback",
 ) -> "BaseSyncQueue":
     """Subscribe a callback function to the result topic.
@@ -169,7 +164,7 @@ def subscribe_results(
 
 
 def unsubscribe(
-    pkg: "type[ProtoBunnyMessage] | ModuleType",
+    pkg: "type[PBM] | ModuleType",
     if_unused: bool = True,
     if_empty: bool = True,
 ) -> None:
@@ -191,7 +186,7 @@ def unsubscribe(
 
 
 def unsubscribe_results(
-    pkg: "type[ProtoBunnyMessage] | ModuleType",
+    pkg: "type[PBM] | ModuleType",
 ) -> None:
     """Remove all in-process subscriptions for a message/package result topic"""
     with registry.sync_lock:
@@ -223,15 +218,15 @@ def unsubscribe_all(if_unused: bool = True, if_empty: bool = True) -> None:
 
 
 def get_message_count(
-    msg_type: "ProtoBunnyMessage | type[ProtoBunnyMessage] | ModuleType",
+    msg_type: "PBM | type[PBM] | ModuleType",
 ) -> int | None:
     q = get_queue(msg_type)
     count = q.get_message_count()
     return count
 
 
 def get_consumer_count(
-    msg_type: "ProtoBunnyMessage | type[ProtoBunnyMessage] | ModuleType",
+    msg_type: "PBM | type[PBM] | ModuleType",
 ) -> int | None:
     q = get_queue(msg_type)
     count = q.get_consumer_count()

protobunny/__init__.py.j2

@@ -56,7 +56,7 @@ from .helpers import get_backend, get_queue
 from .backends import LoggingSyncQueue, BaseSyncQueue, BaseSyncConnection
 
 if tp.TYPE_CHECKING:
-    from .models import LoggerCallback, ProtoBunnyMessage, SyncCallback, IncomingMessageProtocol
+    from .models import LoggerCallback, PBM, SyncCallback, IncomingMessageProtocol
     from .core.results import Result
 
 __version__ = version(PACKAGE_NAME)
@@ -92,7 +92,7 @@ def reset_connection(**kwargs: tp.Any) -> "BaseSyncConnection":
     return conn.connect(**kwargs)
 
 
-def publish(message: "ProtoBunnyMessage") -> None:
+def publish(message: "PBM") -> None:
     """Synchronously publish a message to its corresponding queue.
 
     This method automatically determines the correct topic based on the
@@ -121,7 +121,7 @@ def publish_result(
 
 
 def subscribe(
-    pkg_or_msg: "type[ProtoBunnyMessage] | ModuleType",
+    pkg_or_msg: "type[PBM] | ModuleType",
     callback: "SyncCallback",
 ) -> "BaseSyncQueue":
     """Subscribe a callback function to the topic.
@@ -150,7 +150,7 @@ def subscribe(
 
 
 def subscribe_results(
-    pkg: "type[ProtoBunnyMessage] | ModuleType",
+    pkg: "type[PBM] | ModuleType",
     callback: "SyncCallback",
 ) -> "BaseSyncQueue":
     """Subscribe a callback function to the result topic.
@@ -168,7 +168,7 @@ def subscribe_results(
 
 
 def unsubscribe(
-    pkg: "type[ProtoBunnyMessage] | ModuleType",
+    pkg: "type[PBM] | ModuleType",
     if_unused: bool = True,
     if_empty: bool = True,
 ) -> None:
@@ -190,7 +190,7 @@ def unsubscribe(
 
 
 def unsubscribe_results(
-    pkg: "type[ProtoBunnyMessage] | ModuleType",
+    pkg: "type[PBM] | ModuleType",
 ) -> None:
     """Remove all in-process subscriptions for a message/package result topic"""
     with registry.sync_lock:
@@ -222,15 +222,15 @@ def unsubscribe_all(if_unused: bool = True, if_empty: bool = True) -> None:
 
 
 def get_message_count(
-    msg_type: "ProtoBunnyMessage | type[ProtoBunnyMessage] | ModuleType",
+    msg_type: "PBM | type[PBM] | ModuleType",
 ) -> int | None:
     q = get_queue(msg_type)
     count = q.get_message_count()
     return count
 
 
 def get_consumer_count(
-    msg_type: "ProtoBunnyMessage | type[ProtoBunnyMessage] | ModuleType",
+    msg_type: "PBM | type[PBM] | ModuleType",
 ) -> int | None:
     q = get_queue(msg_type)
     count = q.get_consumer_count()