pigeonmq 1.1.0__tar.gz

pigeonmq-1.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Dependencies
+node_modules/
+
+# Next.js build output (web/, demo/)
+.next/
+next-env.d.ts
+
+# Vercel deployment metadata (demo/)
+.vercel
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Internal scratch / generated notes (not for distribution)
+work/
+outputs/
+
+# Agent / tooling scratch
+.agents/
+.codex/
+
+# Local Claude Code settings (permissions etc.) - personal, not shared.
+# The shared .claude/commands and .claude/agents ARE tracked.
+.claude/settings.local.json
+
+# Personal npm-token setup reminder (see release workflow) - not for distribution.
+NPM_TOKEN_SETUP.md
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Verification / screenshot artifacts (the banner ships as .svg)
+*.png
+.playwright-mcp/
+
+# OS / editor cruft
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp

pigeonmq-1.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: pigeonmq
+Version: 1.1.0
+Summary: Python client for the Pigeon contract-native message broker
+Project-URL: Homepage, https://pigeonmq.cc
+Project-URL: Documentation, https://pigeonmq.cc
+Project-URL: Repository, https://github.com/vishnu-77/pigeon
+Project-URL: Issues, https://github.com/vishnu-77/pigeon/issues
+Author: vishnu-77
+License: Apache-2.0
+Keywords: broker,communication-contracts,governance,messaging
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Pigeon Python SDK
+
+Official Python client for the Pigeon contract-native message broker.
+
+> PyPI and TestPyPI Trusted Publishing are wired into `.github/workflows/release.yml`. Until the first registry release is cut, install from the repository subdirectory for development.
+
+```bash
+pip install ./sdk/python
+```
+
+After the first PyPI release:
+
+```bash
+pip install pigeonmq
+```
+
+```python
+from pigeonmq import PigeonClient, PigeonClientError
+
+client = PigeonClient(token="checkout-token")
+client.connect(["payments.authorize"])
+
+try:
+    result = client.request(
+        "payments.authorize",
+        {
+            "merchantId": "m",
+            "orderId": "order_42",
+            "amount": 42.0,
+            "currency": "GBP",
+            "paymentToken": "tok",
+        },
+        intent="authorize_payment",
+        idempotency_key="order_42:authorize",
+        classification="pci",
+        region="uk",
+    )
+    print(result["status"])
+except PigeonClientError as error:
+    print(error.code, error.status)
+```
+
+The client exposes `connect`, `publish`, `request`, `receive`, `subjects`, `audit`, and `quarantine`. Errors surface as `PigeonClientError` with `code`, `status`, and `details`.

pigeonmq-1.1.0/README.md

@@ -0,0 +1,43 @@
+# Pigeon Python SDK
+
+Official Python client for the Pigeon contract-native message broker.
+
+> PyPI and TestPyPI Trusted Publishing are wired into `.github/workflows/release.yml`. Until the first registry release is cut, install from the repository subdirectory for development.
+
+```bash
+pip install ./sdk/python
+```
+
+After the first PyPI release:
+
+```bash
+pip install pigeonmq
+```
+
+```python
+from pigeonmq import PigeonClient, PigeonClientError
+
+client = PigeonClient(token="checkout-token")
+client.connect(["payments.authorize"])
+
+try:
+    result = client.request(
+        "payments.authorize",
+        {
+            "merchantId": "m",
+            "orderId": "order_42",
+            "amount": 42.0,
+            "currency": "GBP",
+            "paymentToken": "tok",
+        },
+        intent="authorize_payment",
+        idempotency_key="order_42:authorize",
+        classification="pci",
+        region="uk",
+    )
+    print(result["status"])
+except PigeonClientError as error:
+    print(error.code, error.status)
+```
+
+The client exposes `connect`, `publish`, `request`, `receive`, `subjects`, `audit`, and `quarantine`. Errors surface as `PigeonClientError` with `code`, `status`, and `details`.

pigeonmq-1.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pigeonmq"
+version = "1.1.0"
+description = "Python client for the Pigeon contract-native message broker"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "vishnu-77" }]
+keywords = ["messaging", "broker", "communication-contracts", "governance"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent"
+]
+
+[project.urls]
+Homepage = "https://pigeonmq.cc"
+Documentation = "https://pigeonmq.cc"
+Repository = "https://github.com/vishnu-77/pigeon"
+Issues = "https://github.com/vishnu-77/pigeon/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pigeonmq"]

pigeonmq-1.1.0/src/pigeonmq/__init__.py

@@ -0,0 +1,3 @@
+from .client import PigeonClient, PigeonClientError
+
+__all__ = ["PigeonClient", "PigeonClientError"]

pigeonmq-1.1.0/src/pigeonmq/client.py

@@ -0,0 +1,143 @@
+"""Small standard-library client for Pigeon Protocol v1."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+
+class PigeonClientError(RuntimeError):
+    def __init__(self, code: str, message: str, status: int, details: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.details = details or {}
+
+
+class PigeonClient:
+    def __init__(
+        self,
+        url: str = "http://localhost:8787",
+        *,
+        token: str | None = None,
+        region: str = "uk",
+        timeout: float = 10.0,
+    ) -> None:
+        self.url = url.rstrip("/")
+        self.token = token
+        self.region = region
+        self.timeout = timeout
+        self.contract: dict[str, Any] | None = None
+        self.contract_id: str | None = None
+
+    def connect(self, subjects: list[str], *, ttl_ms: int | None = None) -> dict[str, Any]:
+        body: dict[str, Any] = {"subjects": subjects}
+        if ttl_ms is not None:
+            body["ttlMs"] = ttl_ms
+        payload = self._post("/v1/contracts", body, with_contract=False)
+        self.contract = payload["contract"]
+        self.contract_id = self.contract["id"]
+        return self.contract
+
+    def publish(self, message: dict[str, Any]) -> dict[str, Any]:
+        self._require_contract()
+        return self._post("/v1/messages", message, with_contract=True)
+
+    def request(
+        self,
+        subject: str,
+        data: dict[str, Any],
+        *,
+        intent: str | None = None,
+        idempotency_key: str | None = None,
+        classification: str | None = None,
+        region: str | None = None,
+        message_type: str | None = None,
+        source: str = "sdk-python",
+        correlation_id: str | None = None,
+    ) -> dict[str, Any]:
+        message = {
+            "subject": subject,
+            "type": message_type or f"{subject}.request",
+            "source": source,
+            "intent": intent,
+            "idempotencyKey": idempotency_key,
+            "classification": classification,
+            "region": region or self.region,
+            "correlationId": correlation_id,
+            "data": data,
+        }
+        return self.publish({key: value for key, value in message.items() if value is not None})
+
+    def receive(self, subject: str, *, max_messages: int = 1) -> list[dict[str, Any]]:
+        self._require_contract()
+        payload = self._post(
+            f"/v1/subjects/{subject}/receive",
+            {"max": max_messages},
+            with_contract=True,
+        )
+        return payload["messages"]
+
+    def subjects(self) -> list[dict[str, Any]]:
+        return self._get("/v1/subjects")["subjects"]
+
+    def audit(self) -> list[dict[str, Any]]:
+        return self._get("/v1/audit")["records"]
+
+    def quarantine(self) -> list[dict[str, Any]]:
+        return self._get("/v1/quarantine")["records"]
+
+    def _require_contract(self) -> None:
+        if not self.contract_id:
+            raise PigeonClientError(
+                "CONTRACT_REQUIRED",
+                "Call connect() to negotiate a contract first.",
+                0,
+            )
+
+    def _headers(self, with_contract: bool) -> dict[str, str]:
+        headers = {
+            "content-type": "application/json",
+            "x-pigeon-region": self.region,
+        }
+        if self.token:
+            headers["authorization"] = f"Bearer {self.token}"
+        if with_contract and self.contract_id:
+            headers["x-pigeon-contract"] = self.contract_id
+        return headers
+
+    def _post(self, path: str, body: dict[str, Any], *, with_contract: bool) -> dict[str, Any]:
+        request = Request(
+            f"{self.url}{path}",
+            data=json.dumps(body).encode("utf-8"),
+            headers=self._headers(with_contract),
+            method="POST",
+        )
+        return self._send(request)
+
+    def _get(self, path: str) -> dict[str, Any]:
+        request = Request(
+            f"{self.url}{path}",
+            headers=self._headers(False),
+            method="GET",
+        )
+        return self._send(request)
+
+    def _send(self, request: Request) -> dict[str, Any]:
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except HTTPError as error:
+            try:
+                payload = json.loads(error.read().decode("utf-8"))
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                payload = {}
+            details = payload.get("error", {})
+            raise PigeonClientError(
+                details.get("code", "REQUEST_FAILED"),
+                details.get("message", f"HTTP {error.code}"),
+                error.code,
+                details.get("details", {}),
+            ) from error

pigeonmq-1.1.0/tests/test_integration.py

@@ -0,0 +1,62 @@
+import os
+import unittest
+
+from pigeonmq import PigeonClient, PigeonClientError
+
+
+BASE = os.environ.get("PIGEON_URL", "http://localhost:8787")
+
+
+class PigeonIntegrationTests(unittest.TestCase):
+    def test_contract_and_publish(self):
+        client = PigeonClient(BASE, token="checkout-token")
+        contract = client.connect(["payments.authorize"])
+        self.assertTrue(contract["id"])
+
+        result = client.request(
+            "payments.authorize",
+            {
+                "merchantId": "m",
+                "orderId": "python_1",
+                "amount": 12.5,
+                "currency": "GBP",
+                "paymentToken": "tok",
+            },
+            intent="authorize_payment",
+            idempotency_key="python_1:authorize",
+            classification="pci",
+            region="uk",
+        )
+        self.assertEqual(result["status"], "accepted")
+
+    def test_unauthorized_principal_is_denied_at_negotiation(self):
+        client = PigeonClient(BASE, token="catalog-token")
+        with self.assertRaises(PigeonClientError) as raised:
+            client.connect(["payments.authorize"])
+        self.assertEqual(raised.exception.code, "NO_PERMITTED_SUBJECTS")
+        self.assertEqual(raised.exception.status, 403)
+
+    def test_sensitive_field_violation_is_denied(self):
+        client = PigeonClient(BASE, token="checkout-token")
+        client.connect(["payments.authorize"])
+        with self.assertRaises(PigeonClientError) as raised:
+            client.request(
+                "payments.authorize",
+                {
+                    "merchantId": "m",
+                    "orderId": "python_sensitive",
+                    "amount": 12.5,
+                    "currency": "GBP",
+                    "paymentToken": "tok",
+                    "card": {"pan": "TEST_ONLY"},
+                },
+                intent="authorize_payment",
+                idempotency_key="python_sensitive:authorize",
+                classification="pci",
+                region="uk",
+            )
+        self.assertIn(raised.exception.code, {"SENSITIVE_FIELD_DENIED", "RAW_PAN_DETECTED"})
+
+
+if __name__ == "__main__":
+    unittest.main()