server-decorator 2.0.0__tar.gz

server_decorator-2.0.0/.gitignore

@@ -0,0 +1,29 @@
+.npmrc
+dist
+node_modules
+
+# GitHub Actions
+.env
+*.log
+
+# Package managers
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+package-lock.json  # Use pnpm-lock.yaml instead
+yarn.lock         # Use pnpm-lock.yaml instead
+
+# iCloud-style duplicate files (D-D)
+* 2
+* 2.*
+* 3
+* 3.*
+
+# Python (added during polyglot migration)
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

server_decorator-2.0.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: server-decorator
+Version: 2.0.0
+Summary: Server-side decorators for caching, tracking, and queue emission. Polyglot sibling of the Node `server-decorator` npm package.
+Project-URL: Homepage, https://github.com/your-username/server-decorator
+Project-URL: Repository, https://github.com/your-username/server-decorator
+Project-URL: Issues, https://github.com/your-username/server-decorator/issues
+Author: server-decorator contributors
+License: MIT
+Keywords: caching,decorators,kafka,queue,rabbitmq,redis,tracking
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: aio-pika>=9.4; extra == 'all'
+Requires-Dist: aiokafka>=0.11; extra == 'all'
+Requires-Dist: redis>=5.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: aio-pika>=9.4; extra == 'dev'
+Requires-Dist: aiokafka>=0.11; extra == 'dev'
+Requires-Dist: jsonschema>=4.21; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: redis>=5.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: testcontainers[kafka,rabbitmq,redis]>=4.7; extra == 'dev'
+Provides-Extra: kafka
+Requires-Dist: aiokafka>=0.11; extra == 'kafka'
+Provides-Extra: rabbitmq
+Requires-Dist: aio-pika>=9.4; extra == 'rabbitmq'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# server-decorator (Python)
+
+Server-side decorators for caching, tracking, and queue emission. Polyglot sibling of the Node `server-decorator` npm package — both share the wire-format contracts in [`../contracts`](../contracts).
+
+## Install
+
+```bash
+pip install server-decorator               # core
+pip install server-decorator[redis]        # + redis adapter
+pip install server-decorator[rabbitmq]     # + aio-pika adapter
+pip install server-decorator[kafka]        # + aiokafka adapter
+pip install server-decorator[all]          # all adapters
+```
+
+Requires Python 3.10+. `asyncio` only — no `trio`/`anyio` (Decision #10).
+
+## Quick start
+
+### Method form
+
+```python
+from server_decorator import tracking, cache, emit_on_success, CACHE_MISS
+
+class InMemoryCache:
+    def __init__(self): self._d = {}
+    def get(self, key): return self._d.get(key, CACHE_MISS)
+    def set(self, key, val, ttl): self._d[key] = val
+
+class OrderService:
+    @tracking
+    @cache(InMemoryCache(), ttl=300)
+    @emit_on_success(use_events=True)
+    async def create_order(self, customer_id: str, total: float) -> dict:
+        return {"customer_id": customer_id, "total": total, "status": "pending"}
+```
+
+### Class form (auto-wrap every public method)
+
+```python
+from server_decorator import tracking_class
+
+@tracking_class()
+class OrderService:
+    async def create_order(self, ...): ...    # auto-wrapped
+    async def cancel_order(self, ...): ...    # auto-wrapped
+    def _internal(self): ...                  # SKIPPED (leading underscore)
+```
+
+`tracking_class`, `cache_class`, and `emit_on_success_class` accept `include`, `exclude`, and `include_private` to override the default predicates.
+
+## Sync vs async
+
+Method-level decorators auto-detect coroutines via `inspect.iscoroutinefunction` and wrap accordingly (Decision #5). For `@emit_on_success(use_queue=True)` on a sync method called outside an event loop, the side effect runs on a single-worker `ThreadPoolExecutor` so the caller doesn't block (D-C). To drain in-flight emits at process exit:
+
+```python
+import atexit
+from server_decorator.decorators.emit_on_success import _EMIT_EXECUTOR
+atexit.register(_EMIT_EXECUTOR.shutdown, wait=True)
+```
+
+## Caching `None` / falsy values
+
+`CacheAdapter.get` returns `CACHE_MISS` (a module-level sentinel) when a key is absent — `None`/`0`/`""`/`False` are valid cached values. See [`../contracts/rules/cache-adapter.md`](../contracts/rules/cache-adapter.md).
+
+## License
+
+MIT.

server_decorator-2.0.0/README.md

@@ -0,0 +1,67 @@
+# server-decorator (Python)
+
+Server-side decorators for caching, tracking, and queue emission. Polyglot sibling of the Node `server-decorator` npm package — both share the wire-format contracts in [`../contracts`](../contracts).
+
+## Install
+
+```bash
+pip install server-decorator               # core
+pip install server-decorator[redis]        # + redis adapter
+pip install server-decorator[rabbitmq]     # + aio-pika adapter
+pip install server-decorator[kafka]        # + aiokafka adapter
+pip install server-decorator[all]          # all adapters
+```
+
+Requires Python 3.10+. `asyncio` only — no `trio`/`anyio` (Decision #10).
+
+## Quick start
+
+### Method form
+
+```python
+from server_decorator import tracking, cache, emit_on_success, CACHE_MISS
+
+class InMemoryCache:
+    def __init__(self): self._d = {}
+    def get(self, key): return self._d.get(key, CACHE_MISS)
+    def set(self, key, val, ttl): self._d[key] = val
+
+class OrderService:
+    @tracking
+    @cache(InMemoryCache(), ttl=300)
+    @emit_on_success(use_events=True)
+    async def create_order(self, customer_id: str, total: float) -> dict:
+        return {"customer_id": customer_id, "total": total, "status": "pending"}
+```
+
+### Class form (auto-wrap every public method)
+
+```python
+from server_decorator import tracking_class
+
+@tracking_class()
+class OrderService:
+    async def create_order(self, ...): ...    # auto-wrapped
+    async def cancel_order(self, ...): ...    # auto-wrapped
+    def _internal(self): ...                  # SKIPPED (leading underscore)
+```
+
+`tracking_class`, `cache_class`, and `emit_on_success_class` accept `include`, `exclude`, and `include_private` to override the default predicates.
+
+## Sync vs async
+
+Method-level decorators auto-detect coroutines via `inspect.iscoroutinefunction` and wrap accordingly (Decision #5). For `@emit_on_success(use_queue=True)` on a sync method called outside an event loop, the side effect runs on a single-worker `ThreadPoolExecutor` so the caller doesn't block (D-C). To drain in-flight emits at process exit:
+
+```python
+import atexit
+from server_decorator.decorators.emit_on_success import _EMIT_EXECUTOR
+atexit.register(_EMIT_EXECUTOR.shutdown, wait=True)
+```
+
+## Caching `None` / falsy values
+
+`CacheAdapter.get` returns `CACHE_MISS` (a module-level sentinel) when a key is absent — `None`/`0`/`""`/`False` are valid cached values. See [`../contracts/rules/cache-adapter.md`](../contracts/rules/cache-adapter.md).
+
+## License
+
+MIT.

server_decorator-2.0.0/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "server-decorator"
+version = "2.0.0"
+description = "Server-side decorators for caching, tracking, and queue emission. Polyglot sibling of the Node `server-decorator` npm package."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "server-decorator contributors"}]
+keywords = ["decorators", "caching", "tracking", "queue", "redis", "rabbitmq", "kafka"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+redis    = ["redis>=5.0"]
+rabbitmq = ["aio-pika>=9.4"]
+kafka    = ["aiokafka>=0.11"]
+all      = ["redis>=5.0", "aio-pika>=9.4", "aiokafka>=0.11"]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5",
+    "ruff>=0.5",
+    "mypy>=1.10",
+    "jsonschema>=4.21",
+    "redis>=5.0",
+    "aio-pika>=9.4",
+    "aiokafka>=0.11",
+    "testcontainers[redis,rabbitmq,kafka]>=4.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/your-username/server-decorator"
+Repository = "https://github.com/your-username/server-decorator"
+Issues = "https://github.com/your-username/server-decorator/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/server_decorator"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N", "ASYNC", "RUF"]
+# RUF022: keep our grouped/commented __all__ ordering (section comments get destroyed
+# by the isort-style sort).
+ignore = ["RUF022"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "ANN"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/server_decorator"]
+
+# Optional adapter dependencies don't ship `py.typed`. Treat them as untyped so
+# strict-mode still passes; the adapter wrappers keep the public-facing types
+# precise on the server-decorator side.
+[[tool.mypy.overrides]]
+module = ["aiokafka.*", "aio_pika.*", "redis.*", "redis.asyncio"]
+# Make the optional adapter deps appear as Any. They don't ship `py.typed`,
+# and we don't want to vendor stubs for one thin wrapper layer.
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "integration: requires Docker / testcontainers",
+]

server_decorator-2.0.0/scripts/check.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# python/scripts/check.sh — lint + type-check + unit tests.
+# Assumes `uv` is installed; `pip install uv` if not.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+if command -v uv >/dev/null 2>&1; then
+  uv sync --extra dev >/dev/null
+  RUN="uv run"
+else
+  echo "warning: uv not found; falling back to plain python+pytest. Install uv for the full dev experience." >&2
+  RUN=""
+fi
+
+$RUN ruff check src tests
+$RUN ruff format --check src tests
+$RUN mypy src
+$RUN pytest -q tests/unit

server_decorator-2.0.0/src/server_decorator/__init__.py

@@ -0,0 +1,61 @@
+"""server-decorator (Python) — public API barrel.
+
+Mirrors `node/src/index.ts`. Method-form decorators behave identically to the Node
+versions on the same inputs (per `contracts/`). Class-form decorators (Decision #4)
+auto-wrap every qualifying method.
+"""
+
+from server_decorator._contract import CONTRACT_VERSION
+from server_decorator._version import __version__
+from server_decorator.decorators.cache import CACHE_MISS, cache, cache_class
+from server_decorator.decorators.emit_on_success import emit_on_success, emit_on_success_class
+from server_decorator.decorators.tracking import tracking, tracking_class
+from server_decorator.emitter import global_emitter
+from server_decorator.logger import Logger, global_logger, set_global_logger
+from server_decorator.queue.adapter import (
+    QueueAdapter,
+    global_queue,
+    has_global_queue,
+    set_global_queue,
+)
+from server_decorator.queue.adapters.inmemory import InMemoryQueueAdapter
+from server_decorator.queue.adapters.noop import NoOpQueueAdapter
+from server_decorator.queue.message import QueueMessage
+from server_decorator.queue.registry import QueueConfig, QueueRegistry, global_queue_registry
+from server_decorator.tracker import Tracker, global_tracker, set_global_tracker
+
+__all__ = [
+    "__version__",
+    "CONTRACT_VERSION",
+    # method-form decorators (mirror Node)
+    "cache",
+    "tracking",
+    "emit_on_success",
+    # class-form decorators (Decision #4)
+    "cache_class",
+    "tracking_class",
+    "emit_on_success_class",
+    # cache miss sentinel (D-B)
+    "CACHE_MISS",
+    # logger
+    "Logger",
+    "global_logger",
+    "set_global_logger",
+    # tracker
+    "Tracker",
+    "global_tracker",
+    "set_global_tracker",
+    # in-process emitter
+    "global_emitter",
+    # queue
+    "QueueMessage",
+    "QueueAdapter",
+    "global_queue",
+    "set_global_queue",
+    "has_global_queue",
+    "QueueRegistry",
+    "global_queue_registry",
+    "QueueConfig",
+    "InMemoryQueueAdapter",
+    "NoOpQueueAdapter",
+]

server_decorator-2.0.0/src/server_decorator/_contract.py

@@ -0,0 +1,3 @@
+"""Contract version this package targets. Mirrors contracts/VERSION."""
+
+CONTRACT_VERSION = "1.0.0"

server_decorator-2.0.0/src/server_decorator/_version.py

@@ -0,0 +1 @@
+__version__ = "2.0.0"

server_decorator-2.0.0/src/server_decorator/decorators/__init__.py

@@ -0,0 +1 @@
+"""Decorators subsystem."""

server_decorator-2.0.0/src/server_decorator/decorators/_cache_key.py

@@ -0,0 +1,35 @@
+"""Cache key algorithm. Spec: contracts/rules/cache-key.md (v1.0.0).
+
+Both Python and Node implement this from the same spec; Node's port lives at
+`node/src/decorators/_cache_key.ts`. Parity tests load
+`contracts/fixtures/cache-key.examples.json`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+MAX_KEY_BYTES = 250
+
+
+def _repr_arg(x: Any) -> str:
+    return json.dumps(x, sort_keys=True, default=str, separators=(",", ":"))
+
+
+def build_cache_key(
+    qualname: str,
+    args: tuple[Any, ...] | list[Any],
+    kwargs: dict[str, Any],
+) -> str:
+    arg_pieces = [_repr_arg(a) for a in args]
+    if kwargs:
+        for k in sorted(kwargs.keys()):
+            arg_pieces.append(f"{k}={_repr_arg(kwargs[k])}")
+    arg_repr = ",".join(arg_pieces)
+    raw = f"{qualname}({arg_repr})"
+    if len(raw.encode("utf-8")) <= MAX_KEY_BYTES:
+        return raw
+    digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()
+    return f"{qualname}(sha256:{digest})"

server_decorator-2.0.0/src/server_decorator/decorators/_class_apply.py

@@ -0,0 +1,67 @@
+"""Class-decorator helper: walk vars(cls), apply a method-decorator to each qualifying member.
+
+Decision #4. The marker `__server_decorator_wrapped_by__` prevents double-wrapping when
+both class-level and method-level decoration apply (method-level wins).
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+_MARKER = "__server_decorator_wrapped_by__"
+
+
+def _is_wrapped_by(fn: Callable[..., Any], name: str) -> bool:
+    return name in getattr(fn, _MARKER, ())
+
+
+def _mark_wrapped(wrapper: Callable[..., Any], name: str) -> None:
+    existing: tuple[str, ...] = getattr(wrapper, _MARKER, ())
+    object.__setattr__(wrapper, _MARKER, (*existing, name))
+
+
+def apply_to_class(
+    cls: type,
+    method_decorator: Callable[[Callable[..., Any]], Callable[..., Any]],
+    *,
+    decorator_name: str,
+    include: tuple[str, ...] = (),
+    exclude: tuple[str, ...] = (),
+    include_private: bool = False,
+    wrap_properties: bool = False,
+) -> type:
+    for attr_name, attr in list(vars(cls).items()):
+        if attr_name in exclude:
+            continue
+        if attr_name.startswith("_") and attr_name not in include and not include_private:
+            continue
+
+        if isinstance(attr, classmethod):
+            inner = attr.__func__
+            if _is_wrapped_by(inner, decorator_name):
+                continue
+            wrapped = method_decorator(inner)
+            _mark_wrapped(wrapped, decorator_name)
+            setattr(cls, attr_name, classmethod(wrapped))
+        elif isinstance(attr, staticmethod):
+            inner = attr.__func__
+            if _is_wrapped_by(inner, decorator_name):
+                continue
+            wrapped = method_decorator(inner)
+            _mark_wrapped(wrapped, decorator_name)
+            setattr(cls, attr_name, staticmethod(wrapped))
+        elif isinstance(attr, property):
+            if not wrap_properties:
+                continue
+            # v1.1+: wrap fget/fset; deferred per N1.
+            continue
+        elif inspect.isfunction(attr) or inspect.iscoroutinefunction(attr):
+            if _is_wrapped_by(attr, decorator_name):
+                continue
+            wrapped = method_decorator(attr)
+            _mark_wrapped(wrapped, decorator_name)
+            setattr(cls, attr_name, wrapped)
+        # else: nested classes, plain attrs — ignored.
+    return cls

server_decorator-2.0.0/src/server_decorator/decorators/_qualname.py

@@ -0,0 +1,11 @@
+"""Qualname normaliser. Drops `<locals>` markers and keeps the last two segments
+so test-defined classes / nested classes match Node's `ClassName.methodName`."""
+
+from __future__ import annotations
+
+
+def shorten_qualname(qualname: str) -> str:
+    parts = [p for p in qualname.split(".") if p != "<locals>"]
+    if len(parts) >= 2:
+        return ".".join(parts[-2:])
+    return qualname

server_decorator-2.0.0/src/server_decorator/decorators/cache.py

@@ -0,0 +1,92 @@
+"""@cache decorator (method form) + cache_class (class form). Decisions #6 + D-B.
+
+The `CACHE_MISS` sentinel (D-B) lets users cache None/0/""/False as legitimate values:
+adapters return CACHE_MISS for absent keys; the decorator uses identity comparison
+(`cached is not CACHE_MISS`) to distinguish hit from miss.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import Any, Protocol, TypeVar, cast
+
+from server_decorator.decorators._cache_key import build_cache_key
+from server_decorator.decorators._class_apply import _mark_wrapped, apply_to_class
+from server_decorator.decorators._qualname import shorten_qualname
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# D-B: distinct sentinel so adapters can signal "absent key" without colliding with
+# legitimately-cached None/0/""/False values. Re-exported from the package barrel.
+CACHE_MISS: Any = object()
+
+
+class CacheAdapter(Protocol):
+    def get(self, key: str) -> Any | Awaitable[Any]: ...
+    def set(self, key: str, value: Any, ttl: int) -> Any | Awaitable[Any]: ...
+
+
+def cache(adapter: CacheAdapter, ttl: int) -> Callable[[F], F]:
+    def decorator(fn: F) -> F:
+        qualname = shorten_qualname(fn.__qualname__)
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                key = build_cache_key(qualname, args, kwargs)
+                cached = adapter.get(key)
+                if inspect.isawaitable(cached):
+                    cached = await cached
+                if cached is not CACHE_MISS:
+                    return cached
+                result = await fn(*args, **kwargs)
+                set_result = adapter.set(key, result, ttl)
+                if inspect.isawaitable(set_result):
+                    await set_result
+                return result
+
+            _mark_wrapped(async_wrapper, "cache")
+            return cast(F, async_wrapper)
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            key = build_cache_key(qualname, args, kwargs)
+            cached = adapter.get(key)
+            if cached is not CACHE_MISS:
+                return cached
+            result = fn(*args, **kwargs)
+            adapter.set(key, result, ttl)
+            return result
+
+        _mark_wrapped(sync_wrapper, "cache")
+        return cast(F, sync_wrapper)
+
+    return decorator
+
+
+def cache_class(
+    adapter: CacheAdapter,
+    ttl: int,
+    *,
+    include: tuple[str, ...] = (),
+    exclude: tuple[str, ...] = (),
+    include_private: bool = False,
+) -> Callable[[type], type]:
+    """Class form: auto-apply @cache to every public method. Decision #4."""
+
+    method_dec = cache(adapter, ttl)
+
+    def wrap(cls: type) -> type:
+        return apply_to_class(
+            cls,
+            method_dec,
+            decorator_name="cache",
+            include=include,
+            exclude=exclude,
+            include_private=include_private,
+        )
+
+    return wrap