detent-sdk 0.1.0__tar.gz

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

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel superseded runs on the same ref (e.g. rapid PR pushes).
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (py ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The SDK targets Python 3.11+ (pyproject requires-python). Cover the
+        # supported minors. The OpenAPI drift-guard test (tests/test_contract.py)
+        # runs as part of pytest — no separate job needed.
+        python: ['3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install (with dev extras)
+        run: pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: ruff check src tests
+
+      - name: Ruff format check
+        run: ruff format --check src tests
+
+      - name: Mypy (strict)
+        run: mypy src/detent
+
+      - name: Test
+        run: pytest -q

detent_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,75 @@
+name: Release
+
+# Publishes detent-sdk to PyPI when a version tag is pushed (e.g. `v0.1.0`).
+# Auth is tokenless via PyPI Trusted Publishing (OIDC) — no API token secret.
+# One-time setup on PyPI: add a Trusted Publisher for project `detent-sdk`
+# (a "pending" publisher works before the first release) with:
+#   owner cguillerminet, repo detent-sdk-python, workflow release.yml.
+on:
+  push:
+    tags: ['v*']
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write # create the GitHub Release
+  id-token: write # OIDC token for PyPI Trusted Publishing
+
+jobs:
+  release:
+    name: publish to PyPI
+    runs-on: ubuntu-latest
+    # Don't let forks attempt to publish under this name.
+    if: github.repository == 'cguillerminet/detent-sdk-python'
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install (dev extras + build)
+        run: pip install -e ".[dev]" build
+
+      - name: Verify tag matches package version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          PKG="v$(python -c 'import tomllib,pathlib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          echo "tag=$TAG package=$PKG"
+          if [ "$TAG" != "$PKG" ]; then
+            echo "::error::Tag $TAG does not match package version $PKG — bump pyproject or fix the tag."
+            exit 1
+          fi
+
+      - name: Lint + type-check + test
+        run: |
+          ruff check src tests
+          ruff format --check src tests
+          mypy src/detent
+          pytest -q
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      # Tokenless: PyPI Trusted Publishing exchanges the OIDC token. Uploads dist/*.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      # Cut the matching GitHub Release (auto-generated notes). Idempotent.
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Release $TAG already exists — skipping."
+          else
+            gh release create "$TAG" \
+              --title "$TAG" \
+              --generate-notes \
+              --latest \
+              --verify-tag
+          fi

detent_sdk-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

detent_sdk-0.1.0/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.

detent_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,52 @@
+# 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`.