babelqueue 0.1.0__py3-none-any.whl

babelqueue/__init__.py

@@ -0,0 +1,33 @@
+"""BabelQueue — Polyglot Queues, Simplified.
+
+The framework-agnostic Python core: the canonical wire-envelope codec, contracts,
+and dead-letter helpers. Framework adapters (Celery, Django, ...) build on this.
+
+    from babelqueue import EnvelopeCodec
+
+    payload = EnvelopeCodec.make("urn:babel:orders:created", {"order_id": 1042})
+    body = EnvelopeCodec.encode(payload)   # send `body` over Redis/RabbitMQ
+"""
+
+from __future__ import annotations
+
+from . import dead_letter
+from .codec import SCHEMA_VERSION, SOURCE_LANG, EnvelopeCodec
+from .contracts import HasTraceId, PolyglotMessage
+from .exceptions import BabelQueueError, UnknownUrnError
+from .routing import UnknownUrnStrategy
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "EnvelopeCodec",
+    "SCHEMA_VERSION",
+    "SOURCE_LANG",
+    "PolyglotMessage",
+    "HasTraceId",
+    "UnknownUrnStrategy",
+    "BabelQueueError",
+    "UnknownUrnError",
+    "dead_letter",
+    "__version__",
+]

babelqueue/codec.py

@@ -0,0 +1,96 @@
+"""The canonical BabelQueue wire envelope — the single Python implementation.
+
+The shape is frozen as ``{job, trace_id, data, meta, attempts}`` (schema_version 1)
+so a Python service interoperates byte-for-byte with the PHP/Laravel, Go, ... SDKs.
+The ``job`` field carries the message URN (never a class name); ``trace_id`` is a
+cross-service correlation id preserved across every hop. Pure stdlib — no deps.
+
+Full spec: https://babelqueue.com
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from typing import Any, Dict, Mapping, Optional
+
+from .exceptions import BabelQueueError
+
+SCHEMA_VERSION = 1
+SOURCE_LANG = "python"
+
+
+class EnvelopeCodec:
+    """Builds, encodes and decodes the canonical envelope."""
+
+    SCHEMA_VERSION = SCHEMA_VERSION
+    SOURCE_LANG = SOURCE_LANG
+
+    @staticmethod
+    def make(
+        urn: str,
+        data: Mapping[str, Any],
+        *,
+        queue: str = "default",
+        trace_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Build the canonical envelope for a ``(urn, data)`` pair.
+
+        ``trace_id`` is reused when given (trace continuation), otherwise a fresh
+        UUID is minted. ``attempts`` starts at 0 and is the top-level transport
+        counter (kept out of the immutable ``meta`` block).
+        """
+        urn = (urn or "").strip()
+        if not urn:
+            raise BabelQueueError(
+                "A polyglot message must expose a stable, non-empty URN so consumers "
+                "can identify it without any class name."
+            )
+
+        trace_id = (trace_id or "").strip() or str(uuid.uuid4())
+
+        return {
+            "job": urn,
+            "trace_id": trace_id,
+            "data": dict(data),
+            "meta": {
+                "id": str(uuid.uuid4()),
+                "queue": queue,
+                "lang": SOURCE_LANG,
+                "schema_version": SCHEMA_VERSION,
+                "created_at": int(time.time() * 1000),
+            },
+            "attempts": 0,
+        }
+
+    @staticmethod
+    def from_message(message: Any, queue: str = "default") -> Dict[str, Any]:
+        """Build the envelope from a message object (see :class:`PolyglotMessage`).
+
+        If the message also exposes ``get_babel_trace_id()`` (see
+        :class:`HasTraceId`) and returns a non-empty value, that trace id is reused.
+        """
+        get_trace = getattr(message, "get_babel_trace_id", None)
+        trace_id = get_trace() if callable(get_trace) else None
+
+        return EnvelopeCodec.make(
+            message.get_babel_urn(),
+            message.to_payload(),
+            queue=queue,
+            trace_id=trace_id,
+        )
+
+    @staticmethod
+    def encode(envelope: Mapping[str, Any]) -> str:
+        """Encode the envelope as compact UTF-8 JSON (unescaped unicode/slashes)."""
+        return json.dumps(envelope, ensure_ascii=False, separators=(",", ":"))
+
+    @staticmethod
+    def decode(raw: str) -> Dict[str, Any]:
+        """Decode a raw JSON body; returns ``{}`` for malformed/non-object input."""
+        try:
+            decoded = json.loads(raw)
+        except (ValueError, TypeError):
+            return {}
+        return decoded if isinstance(decoded, dict) else {}

babelqueue/contracts.py

@@ -0,0 +1,31 @@
+"""Typed, duck-typing-friendly contracts for polyglot messages.
+
+These mirror the other SDKs' contracts so a typed message class can be checked,
+but the codec also accepts plain ``(urn, data)`` — Python does not require a class.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class PolyglotMessage(Protocol):
+    """A producible message: a stable URN plus a pure, JSON-serialisable payload."""
+
+    def get_babel_urn(self) -> str:
+        """The message URN (e.g. ``urn:babel:orders:created``), never a class name."""
+        ...
+
+    def to_payload(self) -> Mapping[str, Any]:
+        """The pure, JSON-serialisable payload carried under the envelope ``data``."""
+        ...
+
+
+@runtime_checkable
+class HasTraceId(Protocol):
+    """Optional: lets a message continue an existing distributed trace."""
+
+    def get_babel_trace_id(self) -> Optional[str]:
+        """An inherited trace id to reuse, or ``None`` to mint a new one."""
+        ...

babelqueue/dead_letter.py

@@ -0,0 +1,39 @@
+"""Builds the additive ``dead_letter`` block attached when a message is
+dead-lettered. Pure: returns an annotated copy; the original identity
+(trace_id, meta.id, data) is preserved. Because the field is additive and
+optional, the envelope stays at schema_version 1. See https://babelqueue.com.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Mapping, Optional
+
+from .codec import SOURCE_LANG
+
+
+def annotate(
+    envelope: Mapping[str, Any],
+    reason: str,
+    original_queue: str,
+    attempts: int,
+    *,
+    error: Optional[str] = None,
+    exception: Optional[str] = None,
+    lang: str = SOURCE_LANG,
+) -> Dict[str, Any]:
+    """Return a copy of ``envelope`` with a ``dead_letter`` block.
+
+    ``reason`` is one of ``failed`` | ``unknown_urn`` | ``poison``.
+    """
+    result = dict(envelope)
+    result["dead_letter"] = {
+        "reason": reason,
+        "error": error,
+        "exception": exception,
+        "failed_at": int(time.time() * 1000),
+        "original_queue": original_queue,
+        "attempts": attempts,
+        "lang": lang,
+    }
+    return result

babelqueue/exceptions.py

@@ -0,0 +1,11 @@
+"""Exception hierarchy for BabelQueue."""
+
+from __future__ import annotations
+
+
+class BabelQueueError(Exception):
+    """Base for every recoverable BabelQueue error (bad config, empty URN, ...)."""
+
+
+class UnknownUrnError(BabelQueueError):
+    """A consumed message carries a URN with no mapped handler (strategy "fail")."""

babelqueue/routing.py

@@ -0,0 +1,14 @@
+"""Unknown-URN strategy names, shared with every other SDK."""
+
+from __future__ import annotations
+
+
+class UnknownUrnStrategy:
+    """What a consumer does with a message whose URN has no mapped handler."""
+
+    FAIL = "fail"
+    DELETE = "delete"
+    RELEASE = "release"
+    DEAD_LETTER = "dead_letter"
+
+    ALL = (FAIL, DELETE, RELEASE, DEAD_LETTER)

babelqueue-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: babelqueue
+Version: 0.1.0
+Summary: Polyglot Queues, Simplified — the Python core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers.
+Project-URL: Homepage, https://babelqueue.com
+Project-URL: Source, https://github.com/BabelQueue/babelqueue-python
+Project-URL: Issues, https://github.com/BabelQueue/babelqueue-python/issues
+Project-URL: Changelog, https://github.com/BabelQueue/babelqueue-python/blob/main/CHANGELOG.md
+Author-email: Muhammet Şafak <info@muhammetsafak.com.tr>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: envelope,json,messaging,microservices,polyglot,queue
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: amqp
+Requires-Dist: pika>=1.3; extra == 'amqp'
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=4; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# BabelQueue for Python
+
+[![CI](https://github.com/BabelQueue/babelqueue-python/actions/workflows/ci.yml/badge.svg)](https://github.com/BabelQueue/babelqueue-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/babelqueue.svg)](https://pypi.org/project/babelqueue/)
+[![Python](https://img.shields.io/pypi/pyversions/babelqueue.svg)](https://pypi.org/project/babelqueue/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+> **Polyglot Queues, Simplified.** Read and write the canonical BabelQueue message
+> envelope from Python — so your Python services (AI/ML, data processing, …)
+> exchange messages with Laravel, Symfony, Go, .NET and Node over one strict JSON
+> format, on the broker you already run.
+
+This is the framework-agnostic **Python core**: the wire-envelope codec,
+contracts, and dead-letter helpers — **zero runtime dependencies** (standard
+library only). The full standard is documented at
+**[babelqueue.com](https://babelqueue.com)**.
+
+## Installation
+
+```bash
+pip install babelqueue
+```
+
+Requires Python `>=3.9`.
+
+## Usage
+
+```python
+from babelqueue import EnvelopeCodec
+
+# Produce — build the canonical envelope and publish the JSON to your broker.
+envelope = EnvelopeCodec.make("urn:babel:orders:created", {"order_id": 1042})
+body = EnvelopeCodec.encode(envelope)        # -> UTF-8 JSON string
+# redis.rpush("queues:orders", body)  /  channel.basic_publish(body=body, ...)
+
+# Consume — decode a message produced by ANY BabelQueue SDK.
+incoming = EnvelopeCodec.decode(body)
+urn      = incoming["job"]          # "urn:babel:orders:created"
+data     = incoming["data"]         # {"order_id": 1042}
+trace_id = incoming["trace_id"]     # correlate across services
+```
+
+The envelope is identical to every other SDK's:
+
+```json
+{
+  "job": "urn:babel:orders:created",
+  "trace_id": "…",
+  "data": { "order_id": 1042 },
+  "meta": { "id": "…", "queue": "default", "lang": "python", "schema_version": 1, "created_at": 1749132727000 },
+  "attempts": 0
+}
+```
+
+### Typed messages (optional)
+
+```python
+from babelqueue import EnvelopeCodec, PolyglotMessage
+
+class OrderCreated:                      # structurally a PolyglotMessage
+    def __init__(self, order_id: int):
+        self.order_id = order_id
+    def get_babel_urn(self) -> str:
+        return "urn:babel:orders:created"
+    def to_payload(self) -> dict:
+        return {"order_id": self.order_id}
+
+envelope = EnvelopeCodec.from_message(OrderCreated(1042), queue="orders")
+```
+
+Continue an existing trace by adding `get_babel_trace_id(self) -> str | None`
+(see `HasTraceId`), or pass `trace_id=` to `EnvelopeCodec.make`.
+
+### Dead-letter
+
+```python
+from babelqueue import dead_letter
+
+dlq = dead_letter.annotate(envelope, "failed", "orders", attempts=3, error="boom")
+# publish `EnvelopeCodec.encode(dlq)` to the "orders.dlq" queue
+```
+
+## What's here vs. coming
+
+- **Now (this package):** the codec, contracts, dead-letter and unknown-URN
+  helpers, plus the shared conformance fixtures. Bring your own broker client.
+- **Next (planned):** a built-in runtime — `BabelQueue(broker_url=...)` with an
+  `@app.handler("urn:…")` decorator over `redis`/`pika` — and **Celery** / **Django**
+  adapters. Install via extras (`babelqueue[redis]`, `babelqueue[celery]`, …).
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+# (or, dependency-free) python -m unittest discover -s tests
+```
+
+## License
+
+MIT © Muhammet Şafak. See [LICENSE](LICENSE).

babelqueue-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+babelqueue/__init__.py,sha256=7h4_jURrYdOcIIul38ck2FRFjipvMyXRJkTpFw466i4,940
+babelqueue/codec.py,sha256=l54YTPC9ScieUqjQh-eEoQ3oEq20JoSmy2Q00zebynQ,3218
+babelqueue/contracts.py,sha256=zl7137t2agSdKnGjUDxajSXR8xLQTaAsqWEY69zDG0A,1030
+babelqueue/dead_letter.py,sha256=BbNJF6E9BsLom6iOsVTOABbKQwLRWLztsaxmyebmqK0,1112
+babelqueue/exceptions.py,sha256=R6p4tPmRRYbEUTvf9baBdmDvvyKhl5xubqk-NGhhD-w,325
+babelqueue/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+babelqueue/routing.py,sha256=WRTEKrBWd9Tm0BVLm_axwNLA1F5_ljRQyFaGiCuhmB8,351
+babelqueue-0.1.0.dist-info/METADATA,sha256=o6Q5Mns9r0tzbD2efLj37gQTIhOLkQRCgFwLWM-1SuA,4895
+babelqueue-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+babelqueue-0.1.0.dist-info/licenses/LICENSE,sha256=OJMGANMbwEJV5fkqnS8MDTiZJp9ZizRpOo4HYWR0m6E,1072
+babelqueue-0.1.0.dist-info/RECORD,,

babelqueue-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

babelqueue-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammet Şafak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.