wexample-queue 1.0.1__tar.gz → 2.0.0__tar.gz

{wexample_queue-1.0.1 → wexample_queue-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-queue
-Version: 1.0.1
+Version: 2.0.0
 Summary: Manage Queuing
 Author-Email: weeger <contact@wexample.com>
 License: MIT
@@ -8,6 +8,9 @@ Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
+Requires-Dist: pika>=1.3.0
+Requires-Dist: wexample-app>=19.3.0
+Requires-Dist: wexample-helpers>=20.1.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -15,15 +18,66 @@ Description-Content-Type: text/markdown
 
 # queue
 
-Version: 1.0.1
+Version: 2.0.0
 
-The repository does not provide any concrete code that could be documented for now.
+`wexample-queue` is what a worker needs to live on a RabbitMQ queue and nothing more: a connector holding the broker connection, and a service base whose whole subject is one queue. A subclass writes the name of the queue and what to do with a message; connecting, declaring, decoding, acknowledging and giving up are the same for every worker and are already written.
+
+It exists because the other end of the queue is not always Python. The body of a message is plain JSON, published on the default exchange with the queue name as routing key — which is where a Symfony Messenger transport declaring that same queue binds its own exchange, so both ends meet in the same place without either knowing the other.
+
+## A worker
+
+```python
+from wexample_queue.service.abstract_queue_service import AbstractQueueService
+
+@base_class
+class ProcessRunService(AbstractQueueService):
+    queue_name: str = public_field(
+        default="process_run",
+        description="Name of the queue this service consumes",
+    )
+
+    def process_message(self, message: dict[str, Any]) -> None:
+        self.log(f"Run {message['id']} asked for in {message['workdir']}")
+```
+
+Calling `start()` opens the connection, declares the queue and blocks consuming
+until `stop()`. Returning from `process_message()` acknowledges the message;
+raising rejects it without putting it back, because requeueing a message that
+just failed is asking for the same failure at once and for ever. Where it goes
+then is the broker's business — a dead letter exchange if the queue has one,
+nowhere if it has not.
+
+## Publishing
+
+```python
+self.connector.publish("process_run_event", {"kind": "process_run", "id": run_id})
+```
+
+## The broker
+
+Where the broker is comes from the environment, under four keys the connector
+declares as expected:
+
+```
+RABBITMQ_HOST
+RABBITMQ_PORT
+RABBITMQ_USER
+RABBITMQ_PASSWORD
+```
+
+Reading them from there rather than from a caller is what keeps a worker and
+whoever publishes to it from holding two addresses that could disagree.
 
 ## Table of Contents
 
+- [A worker](#a-worker)
+- [Publishing](#publishing)
+- [The broker](#the-broker)
 - [Installation](#installation)
 - [Tests](#tests)
+- [Architecture](#architecture)
 - [Integration in the Suite](#integration-in-the-suite)
+- [Dependencies](#dependencies)
 - [Versioning & Compatibility Policy](#versioning--compatibility-policy)
 - [License](#license)
 - [About us](#about-us)
@@ -40,7 +94,34 @@ pip install wexample-queue
 
 Requires Python >=3.10.
 
-The repository does not provide any concrete code that could be documented for now.
+```bash
+pip install wexample-queue
+```
+
+A worker is a class with a queue name and a `process_message()`:
+
+```python
+from typing import Any
+
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+from wexample_queue.service.abstract_queue_service import AbstractQueueService
+
+@base_class
+class HelloService(AbstractQueueService):
+    queue_name: str = public_field(
+        default="hello",
+        description="Name of the queue this service consumes",
+    )
+
+    def process_message(self, message: dict[str, Any]) -> None:
+        self.log(f"Got {message}")
+
+HelloService(kernel=kernel, queue_name="hello").start()
+```
+
+`start()` blocks. The four `RABBITMQ_*` environment keys have to be readable by
+the kernel, which is where the connector goes to find the broker.
 
 ## Tests
 
@@ -91,7 +172,23 @@ To enforce a minimum coverage percentage:
 
 This will cause the test suite to fail if coverage drops below 80%.
 
-The repository does not provide any concrete code that could be documented for now.
+## Architecture
+
+Two classes, and the line between them is what a broker is against what a worker is.
+
+### The connector
+
+src/wexample_queue/connector/rabbitmq_external_connector.py extends `AbstractExternalConnector` from `wexample-app` and holds a `pika.BlockingConnection` and its channel. It exposes only what this package needs — `connect`, `disconnect`, `declare_queue`, `publish`, `consume`, `stop_consuming` — and reads the broker address from four environment keys it declares in `get_expected_env_keys()`, so a worker never carries one.
+
+`publish()` goes through the default exchange with the queue name as routing key, and marks the message persistent. `declare_queue()` declares it durable, with the same arguments both ends use: neither side depends on the other having started first, and a broker restarted on its own finds its queues again.
+
+### The service
+
+src/wexample_queue/service/abstract_queue_service.py extends `AbstractService` from `wexample-app`, which already brings the run loop, the signal handling and the shutdown. What this adds is the queue: `start()` opens the connection and declares the queue before handing over to the loop, `_run()` blocks consuming, and `_on_message()` decodes one delivery and answers the broker for it.
+
+The answer is the part worth reading. A body that is not JSON, and a message `process_message()` raised on, are both rejected with `requeue=False`. Putting such a message back would be asking for the same failure immediately and for ever; dropping it silently with an `ack` would lose it without saying so. Rejecting it hands the decision to the broker, which is the only place a dead letter exchange can be configured.
+
+Unlike the implementation this was drawn from, constructing a service does not start it. `start()` is called by whoever owns the worker, which is what makes a service testable without a broker.
 
 ## Integration in the Suite
 
@@ -103,6 +200,12 @@ The suite includes packages for configuration management, file handling, prompts
 
 Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
 
+## Dependencies
+
+- pika: >=1.3.0
+- wexample-app: >=19.3.0
+- wexample-helpers: >=20.1.0
+
 ## Versioning & Compatibility Policy
 
 Wexample packages follow **Semantic Versioning** (SemVer):

wexample_queue-2.0.0/README.md

@@ -0,0 +1,243 @@
+# queue
+
+Version: 2.0.0
+
+`wexample-queue` is what a worker needs to live on a RabbitMQ queue and nothing more: a connector holding the broker connection, and a service base whose whole subject is one queue. A subclass writes the name of the queue and what to do with a message; connecting, declaring, decoding, acknowledging and giving up are the same for every worker and are already written.
+
+It exists because the other end of the queue is not always Python. The body of a message is plain JSON, published on the default exchange with the queue name as routing key — which is where a Symfony Messenger transport declaring that same queue binds its own exchange, so both ends meet in the same place without either knowing the other.
+
+## A worker
+
+```python
+from wexample_queue.service.abstract_queue_service import AbstractQueueService
+
+@base_class
+class ProcessRunService(AbstractQueueService):
+    queue_name: str = public_field(
+        default="process_run",
+        description="Name of the queue this service consumes",
+    )
+
+    def process_message(self, message: dict[str, Any]) -> None:
+        self.log(f"Run {message['id']} asked for in {message['workdir']}")
+```
+
+Calling `start()` opens the connection, declares the queue and blocks consuming
+until `stop()`. Returning from `process_message()` acknowledges the message;
+raising rejects it without putting it back, because requeueing a message that
+just failed is asking for the same failure at once and for ever. Where it goes
+then is the broker's business — a dead letter exchange if the queue has one,
+nowhere if it has not.
+
+## Publishing
+
+```python
+self.connector.publish("process_run_event", {"kind": "process_run", "id": run_id})
+```
+
+## The broker
+
+Where the broker is comes from the environment, under four keys the connector
+declares as expected:
+
+```
+RABBITMQ_HOST
+RABBITMQ_PORT
+RABBITMQ_USER
+RABBITMQ_PASSWORD
+```
+
+Reading them from there rather than from a caller is what keeps a worker and
+whoever publishes to it from holding two addresses that could disagree.
+
+## Table of Contents
+
+- [A worker](#a-worker)
+- [Publishing](#publishing)
+- [The broker](#the-broker)
+- [Installation](#installation)
+- [Tests](#tests)
+- [Architecture](#architecture)
+- [Integration in the Suite](#integration-in-the-suite)
+- [Dependencies](#dependencies)
+- [Versioning & Compatibility Policy](#versioning--compatibility-policy)
+- [License](#license)
+- [About us](#about-us)
+- [Known Limitations & Roadmap](#known-limitations--roadmap)
+- [Status & Compatibility](#status--compatibility)
+- [Useful Links](#useful-links)
+- [Migration Notes](#migration-notes)
+
+## Installation
+
+```bash
+pip install wexample-queue
+```
+
+Requires Python >=3.10.
+
+```bash
+pip install wexample-queue
+```
+
+A worker is a class with a queue name and a `process_message()`:
+
+```python
+from typing import Any
+
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+from wexample_queue.service.abstract_queue_service import AbstractQueueService
+
+@base_class
+class HelloService(AbstractQueueService):
+    queue_name: str = public_field(
+        default="hello",
+        description="Name of the queue this service consumes",
+    )
+
+    def process_message(self, message: dict[str, Any]) -> None:
+        self.log(f"Got {message}")
+
+HelloService(kernel=kernel, queue_name="hello").start()
+```
+
+`start()` blocks. The four `RABBITMQ_*` environment keys have to be readable by
+the kernel, which is where the connector goes to find the broker.
+
+## Tests
+
+This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
+
+### Installation
+
+First, install the required testing dependencies:
+```bash
+.venv/bin/python -m pip install pytest pytest-cov
+```
+
+### Basic Usage
+
+Run all tests with coverage:
+```bash
+.venv/bin/python -m pytest --cov --cov-report=html
+```
+
+### Common Commands
+```bash
+# Run tests with coverage for a specific module
+.venv/bin/python -m pytest --cov=your_module
+
+# Show which lines are not covered
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
+
+# Generate an HTML coverage report
+.venv/bin/python -m pytest --cov=your_module --cov-report=html
+
+# Combine terminal and HTML reports
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
+
+# Run specific test file with coverage
+.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
+```
+
+### Viewing HTML Reports
+
+After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
+
+### Coverage Threshold
+
+To enforce a minimum coverage percentage:
+```bash
+.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
+```
+
+This will cause the test suite to fail if coverage drops below 80%.
+
+## Architecture
+
+Two classes, and the line between them is what a broker is against what a worker is.
+
+### The connector
+
+src/wexample_queue/connector/rabbitmq_external_connector.py extends `AbstractExternalConnector` from `wexample-app` and holds a `pika.BlockingConnection` and its channel. It exposes only what this package needs — `connect`, `disconnect`, `declare_queue`, `publish`, `consume`, `stop_consuming` — and reads the broker address from four environment keys it declares in `get_expected_env_keys()`, so a worker never carries one.
+
+`publish()` goes through the default exchange with the queue name as routing key, and marks the message persistent. `declare_queue()` declares it durable, with the same arguments both ends use: neither side depends on the other having started first, and a broker restarted on its own finds its queues again.
+
+### The service
+
+src/wexample_queue/service/abstract_queue_service.py extends `AbstractService` from `wexample-app`, which already brings the run loop, the signal handling and the shutdown. What this adds is the queue: `start()` opens the connection and declares the queue before handing over to the loop, `_run()` blocks consuming, and `_on_message()` decodes one delivery and answers the broker for it.
+
+The answer is the part worth reading. A body that is not JSON, and a message `process_message()` raised on, are both rejected with `requeue=False`. Putting such a message back would be asking for the same failure immediately and for ever; dropping it silently with an `ack` would lose it without saying so. Rejecting it hands the decision to the broker, which is the only place a dead letter exchange can be configured.
+
+Unlike the implementation this was drawn from, constructing a service does not start it. `start()` is called by whoever owns the worker, which is what makes a service testable without a broker.
+
+## Integration in the Suite
+
+This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.
+
+### Related Packages
+
+The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
+
+Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
+
+## Dependencies
+
+- pika: >=1.3.0
+- wexample-app: >=19.3.0
+- wexample-helpers: >=20.1.0
+
+## Versioning & Compatibility Policy
+
+Wexample packages follow **Semantic Versioning** (SemVer):
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes, backward compatible
+
+We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+Free to use in both personal and commercial projects.
+
+## About us
+
+[Wexample](https://wexample.com) stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.
+
+This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.
+
+Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.
+
+## Known Limitations & Roadmap
+
+Current limitations and planned features are tracked in the GitHub issues.
+
+See the [project roadmap](https://github.com/wexample/python-queue/issues) for upcoming features and improvements.
+
+## Status & Compatibility
+
+**Maturity**: Production-ready
+
+**Python Support**: >=3.10
+
+**OS Support**: Linux, macOS, Windows
+
+**Status**: Actively maintained
+
+## Useful Links
+
+- **Homepage**: https://github.com/wexample/python-queue
+- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
+- **Issue Tracker**: https://github.com/wexample/python-queue/issues
+- **Discussions**: https://github.com/wexample/python-queue/discussions
+- **PyPI**: [pypi.org/project/wexample-queue](https://pypi.org/project/wexample-queue/)
+
+## Migration Notes
+
+When upgrading between major versions, refer to the migration guides in the documentation.
+
+Breaking changes are clearly documented with upgrade paths and examples.

{wexample_queue-1.0.1 → wexample_queue-2.0.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-queue"
-version = "1.0.1"
+version = "2.0.0"
 description = "Manage Queuing"
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -17,7 +17,11 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
 ]
-dependencies = []
+dependencies = [
+    "pika>=1.3.0",
+    "wexample-app>=19.3.0",
+    "wexample-helpers>=20.1.0",
+]
 
 [project.readme]
 file = "README.md"

wexample_queue-2.0.0/src/wexample_queue/connector/rabbitmq_external_connector.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pika
+from wexample_app.connector.abstract_external_connector import (
+    AbstractExternalConnector,
+)
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from wexample_helpers.const.types import StringsList
+
+RABBITMQ_ENV_KEY_HEARTBEAT = "RABBITMQ_HEARTBEAT"
+RABBITMQ_ENV_KEY_HOST = "RABBITMQ_HOST"
+RABBITMQ_ENV_KEY_PASSWORD = "RABBITMQ_PASSWORD"
+RABBITMQ_ENV_KEY_PORT = "RABBITMQ_PORT"
+RABBITMQ_ENV_KEY_USER = "RABBITMQ_USER"
+
+
+@base_class
+class RabbitmqExternalConnector(AbstractExternalConnector):
+    """A connection to a RabbitMQ broker, and the few things one does with it.
+
+    Where the broker is comes from the environment and not from a caller: a
+    worker and whoever publishes to it read the same four keys, so neither of
+    them holds an address the other could contradict.
+    """
+
+    channel: Any = public_field(
+        default=None,
+        description="The channel opened on the connection, once connected",
+    )
+    connected: bool = public_field(
+        default=False,
+        description="Whether the connection is currently open",
+    )
+    connection: Any = public_field(
+        default=None,
+        description="The blocking connection to the broker, once connected",
+    )
+    name: str = public_field(
+        default="rabbitmq",
+        description="Name this connector answers to",
+    )
+    thread_id: int | None = public_field(
+        default=None,
+        description="The thread that opened the connection, the only one allowed to use it",
+    )
+
+    def ack(self, delivery_tag: int) -> None:
+        self.channel.basic_ack(delivery_tag)
+
+    def connect(self) -> None:
+        if self.connected:
+            return
+
+        import os
+        import threading
+
+        parameters: dict[str, Any] = {}
+        # Seconds between two signs of life; the broker's proposal when unset.
+        heartbeat = os.environ.get(RABBITMQ_ENV_KEY_HEARTBEAT)
+        if heartbeat:
+            parameters["heartbeat"] = int(heartbeat)
+
+        self.connection = pika.BlockingConnection(
+            pika.ConnectionParameters(
+                host=self._env(RABBITMQ_ENV_KEY_HOST),
+                port=int(self._env(RABBITMQ_ENV_KEY_PORT)),
+                credentials=pika.PlainCredentials(
+                    self._env(RABBITMQ_ENV_KEY_USER),
+                    self._env(RABBITMQ_ENV_KEY_PASSWORD),
+                ),
+                **parameters,
+            )
+        )
+        self.channel = self.connection.channel()
+        self.connected = True
+        self.thread_id = threading.get_ident()
+
+    def declare_queue(self, queue_name: str) -> None:
+        """Makes sure the queue is there, durable, whoever gets there first.
+
+        Both ends declare it with the same arguments so that neither depends on
+        the other having started, and a broker restarted on its own keeps the
+        queue rather than the messages in it.
+        """
+        self.channel.queue_declare(queue=queue_name, durable=True)
+
+    def disconnect(self) -> None:
+        if not self.connected:
+            return
+
+        # A connection the broker already dropped cannot be closed again.
+        if self.connection.is_open:
+            self.connection.close()
+        self.connection = None
+        self.channel = None
+        self.connected = False
+
+    def get(self, queue_name: str) -> tuple[int, bytes] | None:
+        """Takes the next message off the queue, or nothing when it is empty.
+
+        Pulled one at a time rather than pushed: a message the broker pushes
+        while the previous one is still being worked on would wait unacknowledged
+        in the client, and be dropped by the broker's delivery timeout long
+        before its turn came.
+        """
+        method, _properties, body = self.channel.basic_get(queue=queue_name)
+        if method is None:
+            return None
+        return method.delivery_tag, body
+
+    def get_expected_env_keys(self) -> StringsList:
+        return [
+            RABBITMQ_ENV_KEY_HOST,
+            RABBITMQ_ENV_KEY_PORT,
+            RABBITMQ_ENV_KEY_USER,
+            RABBITMQ_ENV_KEY_PASSWORD,
+        ]
+
+    def nack(self, delivery_tag: int) -> None:
+        """Gives a message up, without putting it back on the queue."""
+        self.channel.basic_nack(delivery_tag, requeue=False)
+
+    def publish(self, queue_name: str, payload: dict[str, Any]) -> None:
+        """Puts one message on the queue, marked to survive a broker restart.
+
+        It goes through the default exchange, whose routing key is the queue
+        name — which is also where a Symfony Messenger transport declaring that
+        queue binds its own exchange, so both land in the same place.
+
+        Callable from any thread: a connection belongs to the thread that opened
+        it, so from another one the publication is handed over to that thread,
+        which sends it the next time it tends the connection.
+        """
+        import threading
+
+        if threading.get_ident() != self.thread_id:
+            self.connection.add_callback_threadsafe(
+                lambda: self.publish(queue_name, payload)
+            )
+            return
+
+        import json
+
+        self.channel.basic_publish(
+            exchange="",
+            routing_key=queue_name,
+            body=json.dumps(payload),
+            properties=pika.BasicProperties(delivery_mode=2),
+        )
+
+    def sleep(self, seconds: float) -> None:
+        """Waits while keeping the connection alive — heartbeats answered, and
+        what other threads handed over sent."""
+        self.connection.sleep(seconds)
+
+    def _env(self, key: str) -> str:
+        """One of the four keys, from the process environment or from wex's own.
+
+        Both are read because both are how a worker is configured: a container
+        gets its broker from its environment, and a worker started by hand gets
+        it from the app's env file.
+        """
+        import os
+
+        return os.environ.get(key) or self.kernel.get_env_parameter(key)

wexample_queue-2.0.0/src/wexample_queue/service/abstract_queue_service.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from wexample_app.service.abstract_service import AbstractService
+from wexample_helpers.classes.abstract_method import abstract_method
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from wexample_queue.connector.rabbitmq_external_connector import (
+        RabbitmqExternalConnector,
+    )
+
+
+@base_class
+class AbstractQueueService(AbstractService):
+    """A service whose work is whatever arrives on one queue.
+
+    All a subclass writes is the name of the queue and what to do with a
+    message. Connecting, taking, decoding, acknowledging, keeping the connection
+    alive and coming back after losing it are the same for every worker, so they
+    are here.
+
+    A message may take hours. It is worked on in a thread of its own while this
+    one tends the connection — answering the broker's heartbeats, sending what
+    the work publishes — so the broker never takes a long job for a dead worker.
+    """
+
+    ACKNOWLEDGE_ON_RECEIPT: ClassVar[bool] = False
+    """Acknowledge a message as soon as it is taken, rather than once done.
+
+    For work longer than the broker allows a message to stay unacknowledged
+    (`consumer_timeout`, 30 minutes by default), and whose outcome is recorded
+    somewhere else: a message acknowledged at once is never delivered twice,
+    and nothing the work does can make the broker put it back.
+    """
+    POLL_INTERVAL: ClassVar[float] = 1.0
+    """Seconds between two looks at an empty queue."""
+    RECONNECT_DELAY: ClassVar[float] = 5.0
+    """Seconds before trying again once the connection is lost."""
+    connector: RabbitmqExternalConnector | None = public_field(
+        default=None,
+        description="The broker connection, opened when the service starts",
+    )
+    queue_name: str = public_field(
+        description="Name of the queue this service consumes",
+    )
+
+    def on_idle(self) -> None:
+        """Called each time the queue is found empty. Nothing by default."""
+
+    def on_tick(self, message: dict[str, Any]) -> None:
+        """Called about once a second while a message is being worked on, from the
+        thread that tends the connection. Nothing by default."""
+
+    @abstract_method
+    def process_message(self, message: dict[str, Any]) -> None:
+        """What to do with one message, already decoded — in a thread of its own.
+
+        Returning means the message is acknowledged. Raising means it is given
+        up on — so a subclass that wants a message tried again has to say so by
+        putting it back itself. With `ACKNOWLEDGE_ON_RECEIPT`, it is acknowledged
+        before this is called, whatever comes of it.
+        """
+
+    def start(self) -> None:
+        self._connect()
+
+        super().start()
+
+    def stop(self) -> None:
+        if self.connector:
+            self.connector.disconnect()
+
+        super().stop()
+
+    def _connect(self) -> None:
+        from wexample_queue.connector.rabbitmq_external_connector import (
+            RabbitmqExternalConnector,
+        )
+
+        self.connector = RabbitmqExternalConnector(kernel=self.kernel)
+        self.connector.connect()
+        self.connector.declare_queue(self.queue_name)
+
+    def _decode(self, body: bytes) -> dict[str, Any] | None:
+        import json
+
+        try:
+            return json.loads(body.decode())
+        except json.JSONDecodeError as exception:
+            self.io.error(
+                f"[{self.get_snake_short_class_name()}] Message is not JSON: {exception}",
+                fatal=False,
+            )
+            return None
+
+    def _handle(self, delivery_tag: int, body: bytes) -> None:
+        """Works one message through, keeping the connection alive meanwhile.
+
+        A message that cannot be read, or that the service could not get
+        through, is rejected without being put back: requeueing it would be
+        asking for the same failure at once and for ever.
+        """
+        import threading
+
+        message = self._decode(body)
+        if message is None:
+            self.connector.nack(delivery_tag)
+            return
+
+        if self.ACKNOWLEDGE_ON_RECEIPT:
+            self.connector.ack(delivery_tag)
+
+        outcome: dict[str, Any] = {}
+
+        def work() -> None:
+            try:
+                self.process_message(message)
+            except Exception as exception:
+                import traceback
+
+                outcome["error"] = exception
+                self.io.debug(traceback.format_exc())
+
+        import time
+
+        from pika.exceptions import AMQPError
+
+        worker = threading.Thread(target=work, name=f"{self.queue_name}-message")
+        worker.start()
+
+        # Losing the connection does not stop the work: it is let finish, the
+        # connection being opened again afterwards, and nothing else is taken
+        # meanwhile.
+        lost: AMQPError | None = None
+        while worker.is_alive():
+            if lost is None:
+                try:
+                    self.connector.sleep(self.POLL_INTERVAL)
+                except AMQPError as exception:
+                    lost = exception
+            else:
+                time.sleep(self.POLL_INTERVAL)
+            self.on_tick(message)
+
+        if lost is not None:
+            # An unacknowledged message is given back by the broker with the
+            # connection it was delivered on; one acknowledged on receipt is done.
+            raise lost
+
+        if "error" in outcome:
+            self.io.error(
+                f"[{self.get_snake_short_class_name()}] Message failed: {outcome['error']}",
+                fatal=False,
+            )
+
+        if not self.ACKNOWLEDGE_ON_RECEIPT:
+            if "error" in outcome:
+                self.connector.nack(delivery_tag)
+            else:
+                self.connector.ack(delivery_tag)
+
+    def _run(self) -> None:
+        """One turn: the next message worked through, or a short wait.
+
+        A lost connection is opened again rather than ending the service: a
+        worker left running for a night outlives the odd network hiccup, and a
+        broker restarted under it.
+        """
+        from pika.exceptions import AMQPError
+
+        try:
+            if not self.connector or not self.connector.connected:
+                self._connect()
+                self.log(f"Consuming messages on queue « {self.queue_name} »...")
+
+            delivery = self.connector.get(self.queue_name)
+            if delivery is None:
+                self.on_idle()
+                self.connector.sleep(self.POLL_INTERVAL)
+                return
+
+            self._handle(*delivery)
+        except AMQPError as exception:
+            self.io.error(
+                f"[{self.get_snake_short_class_name()}] Connection lost: "
+                f"{type(exception).__name__}: {exception}. Reconnecting in "
+                f"{self.RECONNECT_DELAY:.0f}s.",
+                fatal=False,
+            )
+            if self.connector:
+                self.connector.connected = False
+            import time
+
+            time.sleep(self.RECONNECT_DELAY)

wexample_queue-1.0.1/README.md

@@ -1,143 +0,0 @@
-# queue
-
-Version: 1.0.1
-
-The repository does not provide any concrete code that could be documented for now.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Tests](#tests)
-- [Integration in the Suite](#integration-in-the-suite)
-- [Versioning & Compatibility Policy](#versioning--compatibility-policy)
-- [License](#license)
-- [About us](#about-us)
-- [Known Limitations & Roadmap](#known-limitations--roadmap)
-- [Status & Compatibility](#status--compatibility)
-- [Useful Links](#useful-links)
-- [Migration Notes](#migration-notes)
-
-## Installation
-
-```bash
-pip install wexample-queue
-```
-
-Requires Python >=3.10.
-
-The repository does not provide any concrete code that could be documented for now.
-
-## Tests
-
-This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
-
-### Installation
-
-First, install the required testing dependencies:
-```bash
-.venv/bin/python -m pip install pytest pytest-cov
-```
-
-### Basic Usage
-
-Run all tests with coverage:
-```bash
-.venv/bin/python -m pytest --cov --cov-report=html
-```
-
-### Common Commands
-```bash
-# Run tests with coverage for a specific module
-.venv/bin/python -m pytest --cov=your_module
-
-# Show which lines are not covered
-.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
-
-# Generate an HTML coverage report
-.venv/bin/python -m pytest --cov=your_module --cov-report=html
-
-# Combine terminal and HTML reports
-.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
-
-# Run specific test file with coverage
-.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
-```
-
-### Viewing HTML Reports
-
-After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
-
-### Coverage Threshold
-
-To enforce a minimum coverage percentage:
-```bash
-.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
-```
-
-This will cause the test suite to fail if coverage drops below 80%.
-
-The repository does not provide any concrete code that could be documented for now.
-
-## Integration in the Suite
-
-This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.
-
-### Related Packages
-
-The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
-
-Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
-
-## Versioning & Compatibility Policy
-
-Wexample packages follow **Semantic Versioning** (SemVer):
-
-- **MAJOR**: Breaking changes
-- **MINOR**: New features, backward compatible
-- **PATCH**: Bug fixes, backward compatible
-
-We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-Free to use in both personal and commercial projects.
-
-## About us
-
-[Wexample](https://wexample.com) stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.
-
-This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.
-
-Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.
-
-## Known Limitations & Roadmap
-
-Current limitations and planned features are tracked in the GitHub issues.
-
-See the [project roadmap](https://github.com/wexample/python-queue/issues) for upcoming features and improvements.
-
-## Status & Compatibility
-
-**Maturity**: Production-ready
-
-**Python Support**: >=3.10
-
-**OS Support**: Linux, macOS, Windows
-
-**Status**: Actively maintained
-
-## Useful Links
-
-- **Homepage**: https://github.com/wexample/python-queue
-- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
-- **Issue Tracker**: https://github.com/wexample/python-queue/issues
-- **Discussions**: https://github.com/wexample/python-queue/discussions
-- **PyPI**: [pypi.org/project/wexample-queue](https://pypi.org/project/wexample-queue/)
-
-## Migration Notes
-
-When upgrading between major versions, refer to the migration guides in the documentation.
-
-Breaking changes are clearly documented with upgrade paths and examples.