rocketmq-sdk 0.1.0__tar.gz

rocketmq_sdk-0.1.0/.dockerignore

@@ -0,0 +1,19 @@
+.venv/
+.git/
+.github/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+*.egg
+tests/
+examples/
+docs/
+*.md
+Makefile
+.gitignore
+.dockerignore

rocketmq_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check src/ tests/ examples/
+
+      - name: Lint (ruff)
+        run: uv run ruff check src/ tests/ examples/
+
+      - name: Type check (pyright)
+        run: uv run pyright src/ tests/
+
+      - name: Test (pytest)
+        run: uv run pytest tests/ -v

rocketmq_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+# Trigger on GitHub releases (recommended over tag-push for PyPI)
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: rocketmq.py
+    permissions:
+      contents: read   # Required for actions/checkout to clone the repo
+      id-token: write  # Required for trusted publishing (OIDC)
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --no-dev --frozen
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Uses trusted publishing (OIDC) — no API token needed.
+        # Configure at: https://pypi.org/manage/project/rocketmq/settings/publishing/

rocketmq_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+*.egg
+.mypy_cache/

rocketmq_sdk-0.1.0/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.12-slim AS base
+
+WORKDIR /app
+
+# Install uv for fast dependency resolution
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Copy dependency files first for layer caching
+COPY pyproject.toml uv.lock ./
+
+# Install production deps only (no dev group)
+RUN uv sync --no-dev --frozen
+
+# Copy source code
+COPY src/ src/
+
+# Default command: Python shell with rocketmq importable
+CMD ["uv", "run", "python", "-c", "import rocketmq; print(f'rocketmq {rocketmq.__version__}')"]

rocketmq_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edilson Pateguana
+
+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.

rocketmq_sdk-0.1.0/Makefile

@@ -0,0 +1,32 @@
+.DEFAULT_GOAL := help
+.PHONY: help install fmt lint typecheck test check all clean
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install deps + editable package
+	uv sync
+
+fmt: ## Format code (ruff)
+	uv run ruff format src/ tests/ examples/
+
+lint: ## Lint code (ruff)
+	uv run ruff check src/ tests/ examples/
+
+lint-fix: ## Lint + auto-fix (ruff)
+	uv run ruff check --fix src/ tests/ examples/
+
+typecheck: ## Type-check (pyright)
+	uv run pyright src/ tests/
+
+test: ## Run tests (pytest)
+	uv run pytest tests/ -v
+
+check: lint typecheck test ## Run lint + typecheck + test
+
+all: fmt lint-fix typecheck test ## Format + fix + typecheck + test
+
+clean: ## Remove caches and build artifacts
+	rm -rf .venv .pytest_cache .ruff_cache dist build __pycache__
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

rocketmq_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: rocketmq-sdk
+Version: 0.1.0
+Summary: Schema-aware AMQP client for the RocketMQ broker — Pydantic + aio-pika.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aio-pika<10.0,>=9.0
+Requires-Dist: pydantic<3.0,>=2.0
+Description-Content-Type: text/markdown
+
+# rocketmq.py
+
+Schema-aware AMQP client for the RocketMQ broker - **Pydantic v2 + aio-pika**.
+
+Python port of the [`rocketmq.js`](../rocketmq.js) TypeScript SDK.
+
+## Setup
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync          # install deps + editable package
+```
+
+## Quick Start
+
+```python
+import asyncio
+from rocketmq import connect
+from rocketmq.schema import BaseSchema
+
+
+class Order(BaseSchema):
+    id: str
+    customer_id: str
+    qty: int
+
+
+async def main():
+    mq = await connect(url="amqp://localhost")
+    orders = await mq.queue("orders", Order)
+
+    await orders.send(Order(id="1", customer_id="c1", qty=5))
+    await orders.consume(lambda msg: print(msg))
+
+    await asyncio.sleep(2)
+    await mq.close()
+
+
+asyncio.run(main())
+```
+
+## Development
+
+```bash
+make help        # show all commands
+make fmt         # format (ruff)
+make lint        # lint (ruff)
+make typecheck   # type-check (pyright)
+make test        # run tests (pytest)
+make check       # lint + typecheck + test
+make all         # format + fix + typecheck + test
+```
+
+## Architecture
+
+```
+src/rocketmq/
+├── __init__.py          # Public re-exports
+├── py.typed             # PEP 561 marker
+├── amqp.py              # Thin aio-pika wrapper
+├── client.py            # RocketMQ + connect() + QueueHandle
+├── schema.py            # BaseSchema + Proto annotation
+├── proto.py             # Pydantic model -> proto3 string
+├── serializer.py        # Serializer Protocol + JsonSerializer
+├── errors.py            # Error hierarchy
+├── error_codes.py       # BrokerErrorCode enum
+└── error_parser.py      # Broker JSON error parsing
+```
+
+## Cross-Language Type Compatibility
+
+Python types map to proto3 types that match the JS SDK:
+
+| Python | TypeScript (Zod) | Proto3 |
+|---|---|---|
+| `str` | `z.string()` | `string` |
+| `int` | `z.number()` | `double` |
+| `float` | `z.number()` | `double` |
+| `bool` | `z.boolean()` | `bool` |
+| `bytes` | `z.object(...)` | `bytes` |
+| `datetime` | `z.date()` | `Timestamp` |
+| `Annotated[int, Proto("int32")]` | `z.number().int()` | `int32` |

rocketmq_sdk-0.1.0/README.md

@@ -0,0 +1,83 @@
+# rocketmq.py
+
+Schema-aware AMQP client for the RocketMQ broker - **Pydantic v2 + aio-pika**.
+
+Python port of the [`rocketmq.js`](../rocketmq.js) TypeScript SDK.
+
+## Setup
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync          # install deps + editable package
+```
+
+## Quick Start
+
+```python
+import asyncio
+from rocketmq import connect
+from rocketmq.schema import BaseSchema
+
+
+class Order(BaseSchema):
+    id: str
+    customer_id: str
+    qty: int
+
+
+async def main():
+    mq = await connect(url="amqp://localhost")
+    orders = await mq.queue("orders", Order)
+
+    await orders.send(Order(id="1", customer_id="c1", qty=5))
+    await orders.consume(lambda msg: print(msg))
+
+    await asyncio.sleep(2)
+    await mq.close()
+
+
+asyncio.run(main())
+```
+
+## Development
+
+```bash
+make help        # show all commands
+make fmt         # format (ruff)
+make lint        # lint (ruff)
+make typecheck   # type-check (pyright)
+make test        # run tests (pytest)
+make check       # lint + typecheck + test
+make all         # format + fix + typecheck + test
+```
+
+## Architecture
+
+```
+src/rocketmq/
+├── __init__.py          # Public re-exports
+├── py.typed             # PEP 561 marker
+├── amqp.py              # Thin aio-pika wrapper
+├── client.py            # RocketMQ + connect() + QueueHandle
+├── schema.py            # BaseSchema + Proto annotation
+├── proto.py             # Pydantic model -> proto3 string
+├── serializer.py        # Serializer Protocol + JsonSerializer
+├── errors.py            # Error hierarchy
+├── error_codes.py       # BrokerErrorCode enum
+└── error_parser.py      # Broker JSON error parsing
+```
+
+## Cross-Language Type Compatibility
+
+Python types map to proto3 types that match the JS SDK:
+
+| Python | TypeScript (Zod) | Proto3 |
+|---|---|---|
+| `str` | `z.string()` | `string` |
+| `int` | `z.number()` | `double` |
+| `float` | `z.number()` | `double` |
+| `bool` | `z.boolean()` | `bool` |
+| `bytes` | `z.object(...)` | `bytes` |
+| `datetime` | `z.date()` | `Timestamp` |
+| `Annotated[int, Proto("int32")]` | `z.number().int()` | `int32` |

rocketmq_sdk-0.1.0/examples/custom_serializer.py

@@ -0,0 +1,71 @@
+"""
+Example: Custom serializer.
+
+Demonstrates plugging in a custom serializer (MessagePack in this case)
+while keeping the same schema-aware API.
+
+Run::
+
+    pip install msgpack
+    python examples/custom_serializer.py
+"""
+
+import asyncio
+
+from rocketmq import connect
+from rocketmq.schema import BaseSchema
+
+
+class MsgpackSerializer:
+    """MessagePack serializer — drop-in replacement for JsonSerializer.
+
+    Usage::
+
+        mq = await connect(url="amqp://localhost", serializer=MsgpackSerializer())
+    """
+
+    @property
+    def content_type(self) -> str:
+        return "application/x-msgpack"
+
+    def serialize(self, value: object) -> bytes:
+        from typing import cast
+
+        import msgpack
+
+        # WHY: packb is typed as -> bytes | None in stubs, but never
+        # returns None for dict/list inputs.
+        return cast("bytes", msgpack.packb(value, use_bin_type=True))
+
+    def deserialize(self, data: bytes) -> object:
+        import msgpack
+
+        return msgpack.unpackb(data, raw=False)
+
+
+class SensorReading(BaseSchema):
+    sensor_id: str
+    temperature: float
+    humidity: float
+
+
+async def main() -> None:
+    mq = await connect(url="amqp://localhost", serializer=MsgpackSerializer())
+    readings = await mq.queue("sensor-readings", SensorReading)
+
+    await readings.send(
+        SensorReading(
+            sensor_id="s-42",
+            temperature=23.5,
+            humidity=61.2,
+        )
+    )
+
+    _ = await readings.consume(lambda msg: print(f"Sensor {msg.sensor_id}: {msg.temperature}°C"))
+
+    await asyncio.sleep(2)
+    await mq.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

rocketmq_sdk-0.1.0/examples/exchange_routing.py

@@ -0,0 +1,64 @@
+"""
+Example: Exchange routing with Pydantic schemas.
+
+Demonstrates declaring an exchange, binding queues with routing keys,
+and publishing messages that route to specific consumers.
+
+Run::
+
+    python examples/exchange_routing.py
+"""
+
+import asyncio
+
+from rocketmq import connect
+from rocketmq.schema import BaseSchema
+
+
+class OrderEvent(BaseSchema):
+    order_id: str
+    action: str
+    amount: float
+
+
+async def main() -> None:
+    mq = await connect(url="amqp://localhost")
+
+    # Declare exchange + queues
+    await mq.assert_exchange("orders.topic", "direct")
+    await mq.assert_queue("orders.created", OrderEvent)
+    await mq.assert_queue("orders.cancelled", OrderEvent)
+    await mq.bind_queue("orders.created", "orders.topic", "created")
+    await mq.bind_queue("orders.cancelled", "orders.topic", "cancelled")
+
+    # Publish to different routing keys
+    await mq.publish(
+        "orders.topic",
+        "created",
+        {
+            "order_id": "ord-001",
+            "action": "created",
+            "amount": 99.90,
+        },
+    )
+
+    await mq.publish(
+        "orders.topic",
+        "cancelled",
+        {
+            "order_id": "ord-002",
+            "action": "cancelled",
+            "amount": 45.00,
+        },
+    )
+
+    # Consume from specific queues
+    _ = await mq.consume("orders.created", OrderEvent, lambda msg: print(f"NEW: {msg}"))
+    _ = await mq.consume("orders.cancelled", OrderEvent, lambda msg: print(f"CANCEL: {msg}"))
+
+    await asyncio.sleep(2)
+    await mq.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

rocketmq_sdk-0.1.0/examples/publisher.py

@@ -0,0 +1,51 @@
+"""
+Example: Pydantic model schema — publish + consume.
+
+Demonstrates defining a message schema as a Pydantic model, declaring
+a queue with schema metadata, publishing a typed message, and consuming
+with automatic deserialization.
+
+Run::
+
+    python examples/publisher.py
+"""
+
+import asyncio
+from typing import Annotated
+
+from rocketmq import connect
+from rocketmq.schema import BaseSchema, Proto
+
+
+class Notification(BaseSchema):
+    id: Annotated[int, Proto("int32")]
+    content: str
+    timestamp: float
+
+
+async def main() -> None:
+    mq = await connect(url="amqp://localhost")
+    queue = await mq.queue("pending-notifications", Notification)
+
+    message = Notification(
+        id=1,
+        content="Hello from Python SDK",
+        timestamp=1717520000.0,
+    )
+
+    # Publish
+    await queue.send(message)
+
+    # Consume
+    async def on_message(msg: Notification) -> None:
+        print(f"Received: id={msg.id} content={msg.content}")
+
+    _ = await queue.consume(on_message)
+
+    # Keep alive to let messages arrive, then close.
+    await asyncio.sleep(2)
+    await mq.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

rocketmq_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[project]
+name = "rocketmq-sdk"
+version = "0.1.0"
+description = "Schema-aware AMQP client for the RocketMQ broker — Pydantic + aio-pika."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = [
+    "aio-pika>=9.0,<10.0",
+    "pydantic>=2.0,<3.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rocketmq"]
+
+# --------------------------------------------------------------------------
+# ruff — lint + format (replaces flake8, isort, black, pyupgrade)
+# --------------------------------------------------------------------------
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "RUF",  # ruff-specific rules
+    "TCH",  # type-checking imports
+    "PT",   # flake8-pytest-style
+    "PIE",  # flake8-pie
+    "C4",   # flake8-comprehensions
+    "T20",  # flake8-print (catch stray prints)
+]
+ignore = [
+    "T201",   # allow print() in examples
+    "UP007",  # allow Union[X, Y] alongside X | Y in runtime contexts
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["rocketmq"]
+force-single-line = false
+lines-after-imports = 2
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["T201"]       # allow print() in tests
+"examples/**" = ["T201"]    # allow print() in examples
+
+# --------------------------------------------------------------------------
+# pyright — static type checking
+# --------------------------------------------------------------------------
+[tool.pyright]
+pythonVersion = "3.11"
+venvPath = "."
+venv = ".venv"
+typeCheckingMode = "standard"
+include = ["src", "tests", "examples"]
+reportMissingTypeStubs = false
+
+# --------------------------------------------------------------------------
+# pytest
+# --------------------------------------------------------------------------
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pyright>=1.1.410",
+    "ruff>=0.15.16",
+]
+examples = [
+    "msgpack>=1.0,<2.0",
+]