vs-queue 0.1.0__tar.gz → 0.1.2__tar.gz

{vs_queue-0.1.0 → vs_queue-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vs-queue
-Version: 0.1.0
+Version: 0.1.2
 Summary: Pluggable async message queue library for Viveka Sutra — Redis Streams, RabbitMQ, retry, dead letter, and annotation-based consumers
 Project-URL: Homepage, https://vivekasutra.com/
 Project-URL: Source, https://github.com/vivekasutra/viveka-mula
@@ -315,13 +315,13 @@ Abstract base class for all consumers. Extend this and implement `handle` to pro
 | Method | Description |
 |---|---|
 | `handle(message)` | Called for every message received. Raise any exception to trigger retry. |
-| `start()` | Called once when the consumer begins. Use for setup. |
-| `stop()` | Called once on graceful shutdown. Use for cleanup. |
 
-**Optional override:**
+**Optional overrides** (concrete no-ops by default — override only if you need them):
 
 | Method | Description |
 |---|---|
+| `start()` | Called once when the consumer begins. Use for setup. |
+| `stop()` | Called once on graceful shutdown. Use for cleanup. |
 | `on_error(message, error)` | Called when `handle` raises an exception, before retry logic runs. Use for logging or alerting. |
 
 **Example with error hook:**
@@ -374,9 +374,6 @@ Decorator that registers a `VsBaseConsumer` subclass as a listener. `VsQueueMana
 class SimpleConsumer(VsBaseConsumer):
     async def handle(self, message: VsMessage) -> None:
         print(message.payload)
-
-    async def start(self) -> None: pass
-    async def stop(self) -> None: pass
 ```
 
 **Example — full configuration:**
@@ -543,9 +540,6 @@ class DlqConsumer(VsBaseConsumer):
             f"Message permanently failed | id={message.id} retries={message.retry_count}",
             payload=message.payload,
         )
-
-    async def start(self) -> None: pass
-    async def stop(self) -> None: pass
 ```
 
 **Example — replaying a DLQ message:**
@@ -560,6 +554,42 @@ await queue.publish("orchestrator:tasks", dlq_message)
 
 ---
 
+## Logging
+
+Both backends log consumer lifecycle and per-message activity on the provider logger
+(`vs_queue.provider.vs_redis_queue` / `vs_queue.provider.vs_rabbitmq_queue`). Every line uses a
+`Label | key=value` format.
+
+| Level | Line | When |
+|---|---|---|
+| `INFO` | `Subscribed \| queue=<q> consumer=<ClassName>` | `consumer.start()` has run and the queue / consumer group is ready — the loop is now listening |
+| `INFO` | `Message received \| queue=<q> id=<msg_id> retry_count=<n>` | Each message pulled off the queue, before `handle()` is called |
+| `DEBUG` | `Message processed \| queue=<q> id=<msg_id>` | `handle()` returned and the message was acked |
+| `INFO` | `Unsubscribed \| queue=<q> consumer=<ClassName>` | The subscribe loop exited (graceful shutdown or permanent failure) |
+| `ERROR` | `Message failed, no retry policy \| id=<msg_id> error=<e>` | `handle()` raised and no `VsRetryPolicy` was supplied |
+
+`VsQueueManager` logs lifecycle events on its own logger (`vs_queue.manager.vs_queue_manager`):
+
+| Level | Line |
+|---|---|
+| `INFO` | `Listener registered \| queue=<q> uuid=<uid>` |
+| `INFO` | `Listeners registered \| queue=<q> concurrency=<n>` |
+| `INFO` | `Listener stopped \| queue=<q> uuid=<uid>` |
+| `ERROR` | `Consumer crashed, restarting in <n>s \| queue=<q> attempt=<n> error=<e>` |
+| `CRITICAL` | `Consumer permanently failed after <n> restarts \| queue=<q> error=<e>` |
+
+`Subscribed` / `Message received` land only once the loop is actually consuming, so the absence of
+`Subscribed` after `Listener registered` means `subscribe()` is failing before it starts.
+
+Turn on the debug lines:
+
+```python
+import logging
+logging.getLogger("vs_queue").setLevel(logging.DEBUG)
+```
+
+---
+
 ## Redis Streams Backend
 
 `VsRedisQueue` implements the queue using Redis Streams (`XADD` / `XREADGROUP`). Redis Streams provide persistent, ordered, consumer-group-aware message delivery.
@@ -902,9 +932,9 @@ Abstract base. Extend and implement `handle` to process messages.
 | Method | Required | Description |
 |---|---|---|
 | `handle(message)` | Yes | Process a message. Raise to trigger retry. |
-| `start()` | Yes | Setup before consuming begins |
-| `stop()` | Yes | Cleanup on shutdown — called on graceful cancel |
-| `on_error(message, error)` | No | Called on `handle` failure before retry |
+| `start()` | No — no-op by default | Setup before consuming begins |
+| `stop()` | No — no-op by default | Cleanup on shutdown — called on graceful cancel |
+| `on_error(message, error)` | No — no-op by default | Called on `handle` failure before retry |
 
 ---
 

{vs_queue-0.1.0 → vs_queue-0.1.2}/README.md

@@ -284,13 +284,13 @@ Abstract base class for all consumers. Extend this and implement `handle` to pro
 | Method | Description |
 |---|---|
 | `handle(message)` | Called for every message received. Raise any exception to trigger retry. |
-| `start()` | Called once when the consumer begins. Use for setup. |
-| `stop()` | Called once on graceful shutdown. Use for cleanup. |
 
-**Optional override:**
+**Optional overrides** (concrete no-ops by default — override only if you need them):
 
 | Method | Description |
 |---|---|
+| `start()` | Called once when the consumer begins. Use for setup. |
+| `stop()` | Called once on graceful shutdown. Use for cleanup. |
 | `on_error(message, error)` | Called when `handle` raises an exception, before retry logic runs. Use for logging or alerting. |
 
 **Example with error hook:**
@@ -343,9 +343,6 @@ Decorator that registers a `VsBaseConsumer` subclass as a listener. `VsQueueMana
 class SimpleConsumer(VsBaseConsumer):
     async def handle(self, message: VsMessage) -> None:
         print(message.payload)
-
-    async def start(self) -> None: pass
-    async def stop(self) -> None: pass
 ```
 
 **Example — full configuration:**
@@ -512,9 +509,6 @@ class DlqConsumer(VsBaseConsumer):
             f"Message permanently failed | id={message.id} retries={message.retry_count}",
             payload=message.payload,
         )
-
-    async def start(self) -> None: pass
-    async def stop(self) -> None: pass
 ```
 
 **Example — replaying a DLQ message:**
@@ -529,6 +523,42 @@ await queue.publish("orchestrator:tasks", dlq_message)
 
 ---
 
+## Logging
+
+Both backends log consumer lifecycle and per-message activity on the provider logger
+(`vs_queue.provider.vs_redis_queue` / `vs_queue.provider.vs_rabbitmq_queue`). Every line uses a
+`Label | key=value` format.
+
+| Level | Line | When |
+|---|---|---|
+| `INFO` | `Subscribed \| queue=<q> consumer=<ClassName>` | `consumer.start()` has run and the queue / consumer group is ready — the loop is now listening |
+| `INFO` | `Message received \| queue=<q> id=<msg_id> retry_count=<n>` | Each message pulled off the queue, before `handle()` is called |
+| `DEBUG` | `Message processed \| queue=<q> id=<msg_id>` | `handle()` returned and the message was acked |
+| `INFO` | `Unsubscribed \| queue=<q> consumer=<ClassName>` | The subscribe loop exited (graceful shutdown or permanent failure) |
+| `ERROR` | `Message failed, no retry policy \| id=<msg_id> error=<e>` | `handle()` raised and no `VsRetryPolicy` was supplied |
+
+`VsQueueManager` logs lifecycle events on its own logger (`vs_queue.manager.vs_queue_manager`):
+
+| Level | Line |
+|---|---|
+| `INFO` | `Listener registered \| queue=<q> uuid=<uid>` |
+| `INFO` | `Listeners registered \| queue=<q> concurrency=<n>` |
+| `INFO` | `Listener stopped \| queue=<q> uuid=<uid>` |
+| `ERROR` | `Consumer crashed, restarting in <n>s \| queue=<q> attempt=<n> error=<e>` |
+| `CRITICAL` | `Consumer permanently failed after <n> restarts \| queue=<q> error=<e>` |
+
+`Subscribed` / `Message received` land only once the loop is actually consuming, so the absence of
+`Subscribed` after `Listener registered` means `subscribe()` is failing before it starts.
+
+Turn on the debug lines:
+
+```python
+import logging
+logging.getLogger("vs_queue").setLevel(logging.DEBUG)
+```
+
+---
+
 ## Redis Streams Backend
 
 `VsRedisQueue` implements the queue using Redis Streams (`XADD` / `XREADGROUP`). Redis Streams provide persistent, ordered, consumer-group-aware message delivery.
@@ -871,9 +901,9 @@ Abstract base. Extend and implement `handle` to process messages.
 | Method | Required | Description |
 |---|---|---|
 | `handle(message)` | Yes | Process a message. Raise to trigger retry. |
-| `start()` | Yes | Setup before consuming begins |
-| `stop()` | Yes | Cleanup on shutdown — called on graceful cancel |
-| `on_error(message, error)` | No | Called on `handle` failure before retry |
+| `start()` | No — no-op by default | Setup before consuming begins |
+| `stop()` | No — no-op by default | Cleanup on shutdown — called on graceful cancel |
+| `on_error(message, error)` | No — no-op by default | Called on `handle` failure before retry |
 
 ---
 

{vs_queue-0.1.0 → vs_queue-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vs-queue"
-version = "0.1.0"
+version = "0.1.2"
 description = "Pluggable async message queue library for Viveka Sutra — Redis Streams, RabbitMQ, retry, dead letter, and annotation-based consumers"
 readme = "README.md"
 requires-python = ">=3.11"

{vs_queue-0.1.0 → vs_queue-0.1.2}/vs_queue/base/vs_base_consumer.py

@@ -13,12 +13,12 @@ class VsBaseConsumer(ABC):
     async def handle(self, message: VsMessage) -> None:
         pass
 
-    @abstractmethod
     async def start(self) -> None:
+        """Called once before consuming begins. Override for setup."""
         pass
 
-    @abstractmethod
     async def stop(self) -> None:
+        """Called once on graceful shutdown. Override for cleanup."""
         pass
 
     async def on_error(self, message: VsMessage, error: Exception) -> None:

{vs_queue-0.1.0 → vs_queue-0.1.2}/vs_queue/provider/vs_rabbitmq_queue.py

@@ -62,6 +62,7 @@ class VsRabbitMQQueue(VsBaseQueue):
     async def subscribe(self, queue: str, consumer: VsBaseConsumer, retry_policy: Optional[VsRetryPolicy] = None) -> None:
         q = await self._channel.declare_queue(queue, durable=True)
         await consumer.start()
+        _logger.info(f"Subscribed | queue={queue} consumer={type(consumer).__name__}")
         try:
             async with q.iterator() as iterator:
                 async for amqp_message in iterator:
@@ -73,9 +74,11 @@ class VsRabbitMQQueue(VsBaseQueue):
                         headers=data["headers"],
                         payload=data["payload"],
                     )
+                    _logger.info(f"Message received | queue={queue} id={message.id} retry_count={message.retry_count}")
                     try:
                         await consumer.handle(message)
                         await amqp_message.ack()
+                        _logger.debug(f"Message processed | queue={queue} id={message.id}")
                     except Exception as e:
                         await consumer.on_error(message, e)
                         if retry_policy:
@@ -89,3 +92,4 @@ class VsRabbitMQQueue(VsBaseQueue):
                             _logger.error(f"Message failed, no retry policy | id={message.id} error={e}")
         finally:
             await consumer.stop()
+            _logger.info(f"Unsubscribed | queue={queue} consumer={type(consumer).__name__}")

{vs_queue-0.1.0 → vs_queue-0.1.2}/vs_queue/provider/vs_redis_queue.py

@@ -68,6 +68,7 @@ class VsRedisQueue(VsBaseQueue):
             pass
 
         await consumer.start()
+        _logger.info(f"Subscribed | queue={queue} consumer={type(consumer).__name__}")
         try:
             while True:
                 results = await self._client.xreadgroup(
@@ -89,9 +90,11 @@ class VsRedisQueue(VsBaseQueue):
                             headers=json.loads(data["headers"]),
                             payload=json.loads(data["payload"]),
                         )
+                        _logger.info(f"Message received | queue={queue} id={message.id} retry_count={message.retry_count}")
                         try:
                             await consumer.handle(message)
                             await self._client.xack(queue, group, msg_id)
+                            _logger.debug(f"Message processed | queue={queue} id={message.id}")
                         except Exception as e:
                             await consumer.on_error(message, e)
                             if retry_policy:
@@ -102,3 +105,4 @@ class VsRedisQueue(VsBaseQueue):
                                 _logger.error(f"Message failed, no retry policy | id={message.id} error={e}")
         finally:
             await consumer.stop()
+            _logger.info(f"Unsubscribed | queue={queue} consumer={type(consumer).__name__}")

{vs_queue-0.1.0 → vs_queue-0.1.2}/vs_queue.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vs-queue
-Version: 0.1.0
+Version: 0.1.2
 Summary: Pluggable async message queue library for Viveka Sutra — Redis Streams, RabbitMQ, retry, dead letter, and annotation-based consumers
 Project-URL: Homepage, https://vivekasutra.com/
 Project-URL: Source, https://github.com/vivekasutra/viveka-mula
@@ -315,13 +315,13 @@ Abstract base class for all consumers. Extend this and implement `handle` to pro
 | Method | Description |
 |---|---|
 | `handle(message)` | Called for every message received. Raise any exception to trigger retry. |
-| `start()` | Called once when the consumer begins. Use for setup. |
-| `stop()` | Called once on graceful shutdown. Use for cleanup. |
 
-**Optional override:**
+**Optional overrides** (concrete no-ops by default — override only if you need them):
 
 | Method | Description |
 |---|---|
+| `start()` | Called once when the consumer begins. Use for setup. |
+| `stop()` | Called once on graceful shutdown. Use for cleanup. |
 | `on_error(message, error)` | Called when `handle` raises an exception, before retry logic runs. Use for logging or alerting. |
 
 **Example with error hook:**
@@ -374,9 +374,6 @@ Decorator that registers a `VsBaseConsumer` subclass as a listener. `VsQueueMana
 class SimpleConsumer(VsBaseConsumer):
     async def handle(self, message: VsMessage) -> None:
         print(message.payload)
-
-    async def start(self) -> None: pass
-    async def stop(self) -> None: pass
 ```
 
 **Example — full configuration:**
@@ -543,9 +540,6 @@ class DlqConsumer(VsBaseConsumer):
             f"Message permanently failed | id={message.id} retries={message.retry_count}",
             payload=message.payload,
         )
-
-    async def start(self) -> None: pass
-    async def stop(self) -> None: pass
 ```
 
 **Example — replaying a DLQ message:**
@@ -560,6 +554,42 @@ await queue.publish("orchestrator:tasks", dlq_message)
 
 ---
 
+## Logging
+
+Both backends log consumer lifecycle and per-message activity on the provider logger
+(`vs_queue.provider.vs_redis_queue` / `vs_queue.provider.vs_rabbitmq_queue`). Every line uses a
+`Label | key=value` format.
+
+| Level | Line | When |
+|---|---|---|
+| `INFO` | `Subscribed \| queue=<q> consumer=<ClassName>` | `consumer.start()` has run and the queue / consumer group is ready — the loop is now listening |
+| `INFO` | `Message received \| queue=<q> id=<msg_id> retry_count=<n>` | Each message pulled off the queue, before `handle()` is called |
+| `DEBUG` | `Message processed \| queue=<q> id=<msg_id>` | `handle()` returned and the message was acked |
+| `INFO` | `Unsubscribed \| queue=<q> consumer=<ClassName>` | The subscribe loop exited (graceful shutdown or permanent failure) |
+| `ERROR` | `Message failed, no retry policy \| id=<msg_id> error=<e>` | `handle()` raised and no `VsRetryPolicy` was supplied |
+
+`VsQueueManager` logs lifecycle events on its own logger (`vs_queue.manager.vs_queue_manager`):
+
+| Level | Line |
+|---|---|
+| `INFO` | `Listener registered \| queue=<q> uuid=<uid>` |
+| `INFO` | `Listeners registered \| queue=<q> concurrency=<n>` |
+| `INFO` | `Listener stopped \| queue=<q> uuid=<uid>` |
+| `ERROR` | `Consumer crashed, restarting in <n>s \| queue=<q> attempt=<n> error=<e>` |
+| `CRITICAL` | `Consumer permanently failed after <n> restarts \| queue=<q> error=<e>` |
+
+`Subscribed` / `Message received` land only once the loop is actually consuming, so the absence of
+`Subscribed` after `Listener registered` means `subscribe()` is failing before it starts.
+
+Turn on the debug lines:
+
+```python
+import logging
+logging.getLogger("vs_queue").setLevel(logging.DEBUG)
+```
+
+---
+
 ## Redis Streams Backend
 
 `VsRedisQueue` implements the queue using Redis Streams (`XADD` / `XREADGROUP`). Redis Streams provide persistent, ordered, consumer-group-aware message delivery.
@@ -902,9 +932,9 @@ Abstract base. Extend and implement `handle` to process messages.
 | Method | Required | Description |
 |---|---|---|
 | `handle(message)` | Yes | Process a message. Raise to trigger retry. |
-| `start()` | Yes | Setup before consuming begins |
-| `stop()` | Yes | Cleanup on shutdown — called on graceful cancel |
-| `on_error(message, error)` | No | Called on `handle` failure before retry |
+| `start()` | No — no-op by default | Setup before consuming begins |
+| `stop()` | No — no-op by default | Cleanup on shutdown — called on graceful cancel |
+| `on_error(message, error)` | No — no-op by default | Called on `handle` failure before retry |
 
 ---