detent-sdk 0.1.0__py3-none-any.whl

detent/__init__.py

@@ -0,0 +1,35 @@
+"""Typed Python client for the Detent rate-limiting API."""
+
+from .async_client import AsyncDetent
+from .client import Detent
+from .errors import (
+    DetentAPIError,
+    DetentError,
+    DetentLeaseDenied,
+    DetentTransportError,
+)
+from .models import (
+    AcquireResult,
+    Algorithm,
+    DayStat,
+    LimitResult,
+    MonthSummary,
+    ReleaseResult,
+    StatsResult,
+)
+
+__all__ = [
+    "Detent",
+    "AsyncDetent",
+    "DetentError",
+    "DetentAPIError",
+    "DetentTransportError",
+    "DetentLeaseDenied",
+    "LimitResult",
+    "AcquireResult",
+    "ReleaseResult",
+    "StatsResult",
+    "DayStat",
+    "MonthSummary",
+    "Algorithm",
+]

detent/_config.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from typing import Literal
+
+FailMode = Literal["open", "closed"]
+
+DEFAULT_BASE_URL = "https://api.detent.dev"
+DEFAULT_TIMEOUT = 1.0

detent/_core.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import quote
+
+from ._config import FailMode
+from .errors import DetentAPIError, DetentError, DetentTransportError
+from .models import (
+    AcquireResult,
+    DayStat,
+    LimitResult,
+    MonthSummary,
+    ReleaseResult,
+    StatsResult,
+)
+
+LIMIT_PATH = "/v1/limit"
+LEASES_PATH = "/v1/leases"
+
+
+def limit_body(
+    namespace: str,
+    key: str,
+    algorithm: str | None,
+    limit: int | None,
+    window_ms: int | None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {"namespace": namespace, "key": key}
+    if algorithm is not None:
+        body["algorithm"] = algorithm
+    if limit is not None:
+        body["limit"] = limit
+    if window_ms is not None:
+        body["window_ms"] = window_ms
+    return body
+
+
+def acquire_body(
+    namespace: str, key: str, limit: int | None, window_ms: int | None
+) -> dict[str, Any]:
+    body: dict[str, Any] = {"namespace": namespace, "key": key}
+    if limit is not None:
+        body["limit"] = limit
+    if window_ms is not None:
+        body["window_ms"] = window_ms
+    return body
+
+
+def stats_path(namespace: str) -> str:
+    return f"/v1/namespaces/{quote(namespace, safe='')}/stats"
+
+
+def release_path(lease_id: str) -> str:
+    return f"/v1/leases/{quote(lease_id, safe='')}"
+
+
+def parse_limit(data: dict[str, Any]) -> LimitResult:
+    return LimitResult(
+        allowed=data["allowed"],
+        remaining=data["remaining"],
+        reset_ms=data["reset_ms"],
+        limit=data["limit"],
+        degraded=False,
+    )
+
+
+def degraded_limit(fail_mode: FailMode, limit: int | None) -> LimitResult:
+    return LimitResult(
+        allowed=(fail_mode == "open"),
+        remaining=0,
+        reset_ms=0,
+        limit=limit or 0,
+        degraded=True,
+    )
+
+
+def parse_acquire(data: dict[str, Any]) -> AcquireResult:
+    return AcquireResult(
+        allowed=data["allowed"],
+        lease_id=data.get("lease_id"),
+        active=data["active"],
+        limit=data["limit"],
+        reset_ms=data["reset_ms"],
+    )
+
+
+def parse_release(data: dict[str, Any]) -> ReleaseResult:
+    return ReleaseResult(released=data["released"], active=data["active"])
+
+
+def parse_stats(data: dict[str, Any]) -> StatsResult:
+    month = data["month"]
+    return StatsResult(
+        namespace=data["namespace"],
+        total=data["total"],
+        blocked=data["blocked"],
+        days=[DayStat(day=d["day"], total=d["total"], blocked=d["blocked"]) for d in data["days"]],
+        month=MonthSummary(
+            month=month["month"],
+            total=month["total"],
+            quota=month["quota"],
+            over_quota=month["over_quota"],
+        ),
+    )
+
+
+def error_body(status: int, text: str) -> dict[str, str]:
+    try:
+        parsed = json.loads(text)
+        if isinstance(parsed, dict) and "error" in parsed:
+            return {"error": str(parsed["error"])}
+    except ValueError:
+        pass
+    return {"error": f"HTTP {status}"}
+
+
+def api_error(status: int, body: dict[str, str]) -> DetentAPIError:
+    return DetentAPIError(status, body)
+
+
+def should_degrade(err: DetentError) -> bool:
+    if isinstance(err, DetentTransportError):
+        return True
+    if isinstance(err, DetentAPIError):
+        return err.status >= 500
+    return False

detent/async_client.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from . import _core
+from ._config import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, FailMode
+from .errors import DetentError, DetentLeaseDenied, DetentTransportError
+from .models import AcquireResult, Algorithm, LimitResult, ReleaseResult, StatsResult
+
+
+class AsyncDetent:
+    """Asynchronous Detent client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        fail_mode: FailMode = "open",
+        on_error: Callable[[DetentError], None] | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.fail_mode: FailMode = fail_mode
+        self.on_error = on_error
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {api_key}"},
+            transport=transport,
+        )
+
+    async def _request(
+        self, method: str, path: str, body: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        try:
+            resp = await self._client.request(method, path, json=body)
+        except httpx.TransportError as exc:
+            raise DetentTransportError("Detent request failed") from exc
+        if resp.is_success:
+            data: dict[str, Any] = resp.json()
+            return data
+        raise _core.api_error(resp.status_code, _core.error_body(resp.status_code, resp.text))
+
+    async def limit(
+        self,
+        *,
+        namespace: str,
+        key: str,
+        algorithm: Algorithm | None = None,
+        limit: int | None = None,
+        window_ms: int | None = None,
+    ) -> LimitResult:
+        body = _core.limit_body(namespace, key, algorithm, limit, window_ms)
+        try:
+            data = await self._request("POST", _core.LIMIT_PATH, body)
+        except DetentError as err:
+            if _core.should_degrade(err):
+                if self.on_error is not None:
+                    self.on_error(err)
+                return _core.degraded_limit(self.fail_mode, limit)
+            raise
+        return _core.parse_limit(data)
+
+    async def acquire(
+        self,
+        *,
+        namespace: str,
+        key: str,
+        limit: int | None = None,
+        window_ms: int | None = None,
+    ) -> AcquireResult:
+        data = await self._request(
+            "POST", _core.LEASES_PATH, _core.acquire_body(namespace, key, limit, window_ms)
+        )
+        return _core.parse_acquire(data)
+
+    async def release(self, lease_id: str) -> ReleaseResult:
+        return _core.parse_release(await self._request("DELETE", _core.release_path(lease_id)))
+
+    @asynccontextmanager
+    async def lease(
+        self,
+        *,
+        namespace: str,
+        key: str,
+        limit: int | None = None,
+        window_ms: int | None = None,
+    ) -> AsyncIterator[AcquireResult]:
+        acq = await self.acquire(namespace=namespace, key=key, limit=limit, window_ms=window_ms)
+        if not acq.allowed:
+            raise DetentLeaseDenied(acq)
+        try:
+            yield acq
+        except BaseException:
+            if acq.lease_id is not None:
+                try:
+                    await self.release(acq.lease_id)
+                except Exception:
+                    pass  # never mask the in-body exception
+            raise
+        else:
+            if acq.lease_id is not None:
+                await self.release(acq.lease_id)
+
+    async def get_stats(self, *, namespace: str) -> StatsResult:
+        return _core.parse_stats(await self._request("GET", _core.stats_path(namespace)))
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncDetent:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()

detent/client.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from . import _core
+from ._config import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, FailMode
+from .errors import DetentError, DetentLeaseDenied, DetentTransportError
+from .models import AcquireResult, Algorithm, LimitResult, ReleaseResult, StatsResult
+
+
+class Detent:
+    """Synchronous Detent client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        fail_mode: FailMode = "open",
+        on_error: Callable[[DetentError], None] | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.fail_mode: FailMode = fail_mode
+        self.on_error = on_error
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {api_key}"},
+            transport=transport,
+        )
+
+    def _request(
+        self, method: str, path: str, body: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        try:
+            resp = self._client.request(method, path, json=body)
+        except httpx.TransportError as exc:
+            raise DetentTransportError("Detent request failed") from exc
+        if resp.is_success:
+            data: dict[str, Any] = resp.json()
+            return data
+        raise _core.api_error(resp.status_code, _core.error_body(resp.status_code, resp.text))
+
+    def limit(
+        self,
+        *,
+        namespace: str,
+        key: str,
+        algorithm: Algorithm | None = None,
+        limit: int | None = None,
+        window_ms: int | None = None,
+    ) -> LimitResult:
+        body = _core.limit_body(namespace, key, algorithm, limit, window_ms)
+        try:
+            data = self._request("POST", _core.LIMIT_PATH, body)
+        except DetentError as err:
+            if _core.should_degrade(err):
+                if self.on_error is not None:
+                    self.on_error(err)
+                return _core.degraded_limit(self.fail_mode, limit)
+            raise
+        return _core.parse_limit(data)
+
+    def acquire(
+        self,
+        *,
+        namespace: str,
+        key: str,
+        limit: int | None = None,
+        window_ms: int | None = None,
+    ) -> AcquireResult:
+        data = self._request(
+            "POST", _core.LEASES_PATH, _core.acquire_body(namespace, key, limit, window_ms)
+        )
+        return _core.parse_acquire(data)
+
+    def release(self, lease_id: str) -> ReleaseResult:
+        return _core.parse_release(self._request("DELETE", _core.release_path(lease_id)))
+
+    @contextmanager
+    def lease(
+        self,
+        *,
+        namespace: str,
+        key: str,
+        limit: int | None = None,
+        window_ms: int | None = None,
+    ) -> Iterator[AcquireResult]:
+        acq = self.acquire(namespace=namespace, key=key, limit=limit, window_ms=window_ms)
+        if not acq.allowed:
+            raise DetentLeaseDenied(acq)
+        try:
+            yield acq
+        except BaseException:
+            if acq.lease_id is not None:
+                try:
+                    self.release(acq.lease_id)
+                except Exception:
+                    pass  # never mask the in-body exception
+            raise
+        else:
+            if acq.lease_id is not None:
+                self.release(acq.lease_id)
+
+    def get_stats(self, *, namespace: str) -> StatsResult:
+        return _core.parse_stats(self._request("GET", _core.stats_path(namespace)))
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Detent:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()

detent/errors.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models import AcquireResult
+
+
+class DetentError(Exception):
+    """Base class for all Detent SDK errors."""
+
+
+class DetentAPIError(DetentError):
+    """A 4xx/5xx response from the Detent API."""
+
+    def __init__(self, status: int, body: dict[str, str]) -> None:
+        super().__init__(f"Detent API error {status}: {body.get('error', '')}")
+        self.status = status
+        self.body = body
+
+
+class DetentTransportError(DetentError):
+    """A network/DNS/timeout failure reaching the Detent API."""
+
+
+class DetentLeaseDenied(DetentError):
+    """Raised by lease() when a concurrent slot could not be acquired."""
+
+    def __init__(self, result: AcquireResult) -> None:
+        super().__init__("Lease denied: no concurrent slot available")
+        self.result = result

detent/models.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Algorithm = Literal["sliding_window", "token_bucket", "fixed_window"]
+
+
+@dataclass(frozen=True)
+class LimitResult:
+    allowed: bool
+    remaining: int
+    reset_ms: int
+    limit: int
+    degraded: bool
+
+
+@dataclass(frozen=True)
+class AcquireResult:
+    allowed: bool
+    lease_id: str | None
+    active: int
+    limit: int
+    reset_ms: int
+
+
+@dataclass(frozen=True)
+class ReleaseResult:
+    released: bool
+    active: int
+
+
+@dataclass(frozen=True)
+class DayStat:
+    day: str
+    total: int
+    blocked: int
+
+
+@dataclass(frozen=True)
+class MonthSummary:
+    month: str
+    total: int
+    quota: int | None
+    over_quota: bool
+
+
+@dataclass(frozen=True)
+class StatsResult:
+    namespace: str
+    total: int
+    blocked: int
+    days: list[DayStat]
+    month: MonthSummary

detent_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: detent-sdk
+Version: 0.1.0
+Summary: Typed Python client for the Detent rate-limiting API.
+Project-URL: Homepage, https://github.com/cguillerminet/detent-sdk-python
+Project-URL: Issues, https://github.com/cguillerminet/detent-sdk-python/issues
+Author: Cyril GUILLERMINET
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,detent,rate-limit,rate-limiter,sdk
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# detent-sdk
+
+Typed Python client for the [Detent](https://detent.dev) rate-limiting API. Sync and async, one dependency (httpx).
+
+```bash
+pip install detent-sdk
+```
+
+## Usage
+
+```python
+from detent import Detent
+
+rg = Detent(api_key="rg_live_...")
+
+# Rate-limit check (fails open by default on transport error or 5xx)
+r = rg.limit(namespace="api", key=user_id)
+if not r.allowed:
+    ...  # return HTTP 429
+
+# Concurrent-limit lease (auto-released)
+with rg.lease(namespace="jobs", key=user_id):
+    run_expensive_job()
+
+# Read-only usage stats
+stats = rg.get_stats(namespace="api")
+```
+
+### Async
+
+```python
+from detent import AsyncDetent
+
+async with AsyncDetent(api_key="rg_live_...") as rg:
+    r = await rg.limit(namespace="api", key=user_id)
+    async with rg.lease(namespace="jobs", key=user_id):
+        await run_expensive_job()
+```
+
+### Configuration
+
+| Option      | Default                    | Notes                                                    |
+|-------------|----------------------------|----------------------------------------------------------|
+| `api_key`   | — (required)               | `rg_live_…` / `rg_test_…`                                 |
+| `base_url`  | `https://api.detent.dev`   | Override for self-host / tests                            |
+| `timeout`   | `1.0`                      | Seconds; client-side transport timeout                    |
+| `fail_mode` | `"open"`                   | `"open"` allows, `"closed"` denies on a degraded backend  |
+| `on_error`  | `None`                     | Called on a degraded (transport/5xx) `limit()` call       |
+
+`limit()` never raises on a degraded backend (transport error or 5xx) — it
+returns a result with `degraded=True`. A `4xx` (bad key, plan gate, unknown
+rule) raises `DetentAPIError`.

detent_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+detent/__init__.py,sha256=W8pwA1cQrostXovgU6kQI-Ure4c7XvzDeVzz8K1P0nk,652
+detent/_config.py,sha256=PmDrIbNMR6Z4cCAI2rDLaGgOAYwwd2AUmC3b_Ukmo7A,168
+detent/_core.py,sha256=z5o7UoMfk6gF1q_iwOUlyS1ihbr-6BGieh-PpRToPRU,3291
+detent/async_client.py,sha256=tJKUicp5Vv7OmholCXpltZgXwT-jiHUR50sS3ZUdC9Y,4199
+detent/client.py,sha256=vMRU9kKTBZK775srjYNDROI7LSmpt5w2Waz3OVhby-c,4039
+detent/errors.py,sha256=7G3rmMfXBEH9ZN8x3Qpf4amBbgr73GgDmUa_KBZx3qM,873
+detent/models.py,sha256=Cl7OF_Oo1LOGQOvsNSxS-7WTTKucyjX7Sho_JZFqAvo,872
+detent/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+detent_sdk-0.1.0.dist-info/METADATA,sha256=vWFgLjfCdhBtUqWbenXLdKhU7gQaMkr1nxaoOqNysIc,2471
+detent_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+detent_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=16r9xrd4FhxMgENcfa02GE7epOzbRJB8N_7RIsRuIbA,1075
+detent_sdk-0.1.0.dist-info/RECORD,,

detent_sdk-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

detent_sdk-0.1.0.dist-info/licenses/LICENSE

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