threecommon 0.1.0__py3-none-any.whl

threecommon/_core/retry.py

@@ -0,0 +1,80 @@
+"""Retry policy + backoff math.
+
+Pure module — no I/O, no timing. The sync/async HTTP clients call
+[compute_backoff][threecommon._core.retry.compute_backoff] and pass the
+result to ``time.sleep`` / ``asyncio.sleep`` themselves.
+"""
+
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass
+
+from threecommon.config import RetryDelay
+
+#: HTTP status codes the SDK considers retryable for idempotent methods.
+RETRYABLE_STATUSES: frozenset[int] = frozenset({408, 425, 429, 500, 502, 503, 504})
+
+#: HTTP methods the SDK retries automatically. ``POST`` and ``DELETE`` opt
+#: in via an explicit idempotency key.
+IDEMPOTENT_METHODS: frozenset[str] = frozenset({"GET", "PATCH", "PUT"})
+
+
+@dataclass(frozen=True, slots=True)
+class RetryPolicy:
+    """Bundled retry configuration for the HTTP client."""
+
+    max_retries: int
+    initial_seconds: float
+    max_seconds: float
+    jitter: bool
+
+    @classmethod
+    def from_delay(cls, max_retries: int, delay: RetryDelay) -> RetryPolicy:
+        """Build a [RetryPolicy] from the public [RetryDelay]."""
+        return cls(
+            max_retries=max_retries,
+            initial_seconds=delay.initial_seconds,
+            max_seconds=delay.max_seconds,
+            jitter=delay.jitter,
+        )
+
+
+def is_idempotent(method: str, *, has_idempotency_key: bool) -> bool:
+    """Whether the SDK may safely retry a request with this method."""
+    return has_idempotency_key or method.upper() in IDEMPOTENT_METHODS
+
+
+def is_retryable_status(status: int) -> bool:
+    """Whether ``status`` is in the retry set (alongside method idempotency)."""
+    return status in RETRYABLE_STATUSES
+
+
+def compute_backoff(
+    *,
+    attempt: int,
+    retry_after_seconds: float | None,
+    policy: RetryPolicy,
+) -> float:
+    """Return the next sleep duration in seconds.
+
+    When ``retry_after_seconds`` is provided (e.g. parsed from a
+    ``Retry-After`` header) it takes precedence, capped at
+    ``policy.max_seconds``. Otherwise: exponential ``2**attempt * initial``,
+    capped, with optional full-jitter randomization.
+    """
+    if retry_after_seconds is not None and retry_after_seconds >= 0:
+        return min(retry_after_seconds, policy.max_seconds)
+
+    safe_attempt = max(attempt, 0)
+    exp: float = policy.initial_seconds * (2**safe_attempt)
+    capped: float = min(exp, policy.max_seconds)
+
+    if not policy.jitter:
+        return capped
+    if capped <= 0:
+        return 0.0
+    # Full jitter: pick uniformly in [0, capped). secrets.randbits avoids
+    # the math.random global-state lock and isn't security-sensitive here.
+    bits = secrets.randbits(32)
+    return float(capped * (bits / (1 << 32)))

threecommon/_core/telemetry.py

@@ -0,0 +1,77 @@
+"""Threecommon-Client-Telemetry header builder + last-request tracker.
+
+The header carries SDK version, language, and the previous request's
+latency snapshot.
+
+both sync and async paths share one [Telemetry][threecommon._core.telemetry.Telemetry]
+instance per client.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class _Snapshot:
+    method: str
+    path: str
+    status: int
+    duration_ms: int
+
+
+class Telemetry:
+    """Tracks one previous-request snapshot and emits the header value."""
+
+    __slots__ = ("_enabled", "_last", "_lock")
+
+    def __init__(self, *, enabled: bool) -> None:
+        self._enabled = enabled
+        self._last: _Snapshot | None = None
+        self._lock = threading.Lock()
+
+    @property
+    def enabled(self) -> bool:
+        with self._lock:
+            return self._enabled
+
+    def disable(self) -> None:
+        """Turn telemetry off and clear the cached snapshot."""
+        with self._lock:
+            self._enabled = False
+            self._last = None
+
+    def record(self, *, method: str, path: str, status: int, duration_seconds: float) -> None:
+        """Store a snapshot of the just-completed request. No-op when disabled."""
+        with self._lock:
+            if not self._enabled:
+                return
+            self._last = _Snapshot(
+                method=method,
+                path=path,
+                status=status,
+                duration_ms=int(duration_seconds * 1000),
+            )
+
+    def header_value(self, *, sdk_version: str, api_version: str) -> str | None:
+        """Return the JSON header value, or ``None`` to omit the header."""
+        with self._lock:
+            if not self._enabled:
+                return None
+            last = self._last
+
+        payload: dict[str, object] = {
+            "lang": "python",
+            "sdk": sdk_version,
+            "api": api_version,
+        }
+        if last is not None:
+            payload["last"] = {
+                "m": last.method,
+                "p": last.path,
+                "s": last.status,
+                "d": last.duration_ms,
+            }
+        return json.dumps(payload, separators=(",", ":"))

threecommon/_core/url.py

@@ -0,0 +1,31 @@
+"""URL builder. Pure function — no I/O."""
+
+from __future__ import annotations
+
+from urllib.parse import urlencode
+
+
+def build_url(
+    *,
+    base_url: str,
+    api_path: str,
+    path: str,
+    query: dict[str, str] | None = None,
+) -> str:
+    """Concatenate ``base_url + api_path + path`` and append a sorted query string.
+
+    Trailing slashes on ``base_url`` are trimmed; missing leading slashes on
+    ``path`` are added. Query keys are stable-sorted for deterministic output.
+    """
+    base = base_url.rstrip("/")
+    p = path if path.startswith("/") else "/" + path
+    out = base + api_path + p
+
+    if not query:
+        return out
+
+    pairs = [(k, v) for k, v in sorted(query.items()) if v]
+    if not pairs:
+        return out
+
+    return f"{out}?{urlencode(pairs)}"

threecommon/_generated/__init__.py

@@ -0,0 +1,8 @@
+"""Generated Pydantic v2 models — DO NOT EDIT.
+
+Regenerated from `../../openapi/spec.yaml` via `uv run datamodel-codegen ...`.
+The auto-generated names (`V1EventsGetResponse`,`Datum`, `Status1`, ...) are intentional
+
+Treat this package as a contract-reference artifact: nothing inside should be imported from outside
+the SDK.
+"""