throttlekit-py 0.1.0__tar.gz

throttlekit_py-0.1.0/.gitattributes

@@ -0,0 +1,4 @@
+# Force LF everywhere. The vendored contract artifacts are sha256-pinned in contract/manifest.sha256
+# (hashed as LF); a CRLF checkout would change their bytes and break the drift gate on a fresh clone.
+* text=auto eol=lf
+*.png binary

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

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint & types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e .[dev]
+      - run: python scripts/gen_proto.py # ServiceBackend imports the generated stubs
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+
+  test:
+    name: Test (py ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      # The full cross-language conformance (tests/test_redis_backend.py) replays every golden vector
+      # through the vendored Lua against this Redis. The service-door integration test skips (no Node
+      # server is built in this repo's CI) — the rigorous time-parametrized proof is the Redis one.
+      THROTTLEKIT_REDIS_URL: redis://localhost:6379
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e .[dev]
+      - run: python scripts/gen_proto.py
+      - run: pytest -v

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

@@ -0,0 +1,48 @@
+name: Release
+
+# Publishes throttlekit-py to PyPI when a `v*` tag is pushed, e.g.
+#   git tag v0.1.0 && git push origin v0.1.0
+#
+# Auth: a PyPI API token stored as the repo secret PYPI_API_TOKEN. Add it once with
+#   gh secret set PYPI_API_TOKEN -R AmeyaBorkar/throttlekit-py
+# (paste the token — starting `pypi-` — at the prompt; it lands only in GitHub's encrypted secrets).
+# For the FIRST publish of a not-yet-existing project the token must be ACCOUNT-scoped (a
+# project-scoped token can't exist until the project does); swap to a project-scoped token afterward.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build dists
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/* # validates metadata + README rendering before any upload
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

throttlekit_py-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Generated gRPC stubs (reproduce with `python scripts/gen_proto.py` from the vendored proto)
+src/throttlekit/_generated/

throttlekit_py-0.1.0/LICENSE

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

throttlekit_py-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: throttlekit-py
+Version: 0.1.0
+Summary: Python client for ThrottleKit — distributed rate limiting via gRPC or direct Redis.
+Project-URL: Homepage, https://github.com/AmeyaBorkar/throttlekit-py
+Project-URL: Core (Node), https://www.npmjs.com/package/throttlekit
+Author: Ameya Borkar
+License: MIT
+License-File: LICENSE
+Keywords: gcra,grpc,rate-limiting,throttlekit,token-bucket
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: grpcio>=1.60
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: redis>=5; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# throttlekit (Python)
+
+Python client for [**ThrottleKit**](https://www.npmjs.com/package/throttlekit) — distributed rate
+limiting against the **one** Node core, reached through either of two pluggable backends and proven
+against the **same** golden vectors:
+
+| Backend | Path | Decision computed in | Use it when |
+|---|---|---|---|
+| `ServiceBackend` | gRPC → [`throttlekit-server`](https://github.com/AmeyaBorkar/throttlekit/tree/main/server) | the service (= the core) | you want the full surface (`check`/`check_many`/`peek`/`forecast`) and to never touch the raw wire |
+| `RedisBackend` | vendored Lua → the **same Redis** a Node fleet uses | Lua-in-Redis (the core's own script) | you already run Redis and want one hop, no extra service — `check` only |
+
+> **Status: experimental (alpha).** The contract (`throttlekit.proto`, the golden vectors, and the
+> extracted Lua) is vendored and checksum-pinned from the frozen `throttlekit` 1.0 core; this client
+> tracks it. The raw Lua wire is **not** a frozen contract yet (it ships `frozen: false`), so the
+> `RedisBackend` is explicitly experimental and may change with the core's scripts.
+
+## The one invariant
+
+The whole ThrottleKit design rests on it: **exactly one thing computes a `Decision`** — the Node core,
+directly or as Lua-in-Redis. Neither backend re-implements an algorithm, so there is no second rate
+limiter to keep in sync and no float-determinism risk. The `RedisBackend` marshals ARGV, runs the
+core's vendored script, and decodes the reply; the decision is produced **server-side, in Lua**.
+
+## Install
+
+Installed as **`throttlekit-py`**, imported as **`throttlekit`** (PyPI's `throttlekit` is an unrelated
+project):
+
+```bash
+pip install throttlekit-py            # (alpha; not yet published) — the gRPC ServiceBackend
+pip install "throttlekit-py[redis]"   # + a redis client for the direct RedisBackend
+```
+
+## Use — the service door
+
+```python
+from throttlekit import ServiceBackend
+
+with ServiceBackend("localhost:50051") as rl:
+    d = rl.check("api", api_key)
+    if not d.allowed:
+        ...  # 429 — retry after d.retry_after_ms
+```
+
+`check` / `check_many` / `peek` / `forecast` return frozen `Decision` / `Forecast` dataclasses. A
+*denial* is a normal `Decision` (`allowed is False`), never an exception; gRPC faults map to
+`PolicyNotFoundError` / `OperationNotSupportedError` / `ServiceUnavailableError`.
+
+## Use — the direct Redis door
+
+Configure a strategy and point it at the Redis your fleet shares. `check` is the whole surface (it is
+the contract-vectored, Lua-computed decision); `peek` / `forecast` deliberately stay on the service
+door, where the core — not a re-derived client port — computes them.
+
+```python
+import redis
+from throttlekit import RedisBackend, Gcra
+
+client = redis.Redis.from_url("redis://localhost:6379")
+api = RedisBackend(client, Gcra(limit=100, period_ms=60_000, burst=20), prefix="prod")
+
+d = api.check(api_key)             # now defaults to the Redis server clock (skew-free across a fleet)
+if not d.allowed:
+    ...                            # 429 — retry after d.retry_after_ms
+```
+
+Strategies: `Gcra`, `TokenBucket`, `FixedWindow`, `SlidingWindow`, `SlidingWindowLog`. The `prefix`
+joins as `f"{prefix}:{key}"` — the **same** key scheme the core uses, so a Python and a Node client on
+one limit address the same Redis key. The backend is client-agnostic: pass any object with `evalsha` /
+`eval` (`redis-py` satisfies it structurally), exactly as the Node `RedisStore` does.
+
+## How this stays in lock-step with the core
+
+`scripts/sync_contract.py` vendors, with checksums, from the core repo:
+
+* `contract/` — the dev/test artifacts: `throttlekit.proto` (→ gRPC stubs) and `golden-vectors.json`.
+* `src/throttlekit/_scripts/` — the **runtime** Lua the `RedisBackend` executes (shipped in the wheel),
+  with the core's `manifest.json` (which carries each script's sha256).
+
+`tests/test_contract.py` is the **drift-gate** (the vendored bytes must match their checksums and the
+pinned `contractVersion`). But the real proof is behavioral:
+
+* **`tests/test_redis_backend.py`** replays **every** rate-limit golden vector — the full,
+  time-parametrized timeline — through the Python client → vendored Lua → **real Redis**, and asserts
+  every reply field equals the Node oracle bit-for-bit. (Because the direct path puts an explicit `now`
+  in ARGV, it can do the rigorous time-parametrized replay the cross-process service door can't.)
+* `tests/test_service_backend.py` starts a real `throttlekit-server` and asserts the clock-independent
+  behavior over gRPC.
+
+## Develop
+
+```bash
+pip install -e .[dev]
+python scripts/sync_contract.py          # vendor proto + vectors + Lua from ../GreenfeildProject (the core)
+python scripts/gen_proto.py              # generate the gRPC stubs from the vendored proto
+pytest                                   # unit + contract; the Redis/service tests skip if their backend is absent
+ruff check . && mypy                     # lint + types
+```
+
+The `RedisBackend` conformance needs a reachable Redis: it uses `THROTTLEKIT_REDIS_URL` or the project
+default `redis://localhost:6380`, and skips cleanly when neither is up.

throttlekit_py-0.1.0/README.md

@@ -0,0 +1,101 @@
+# throttlekit (Python)
+
+Python client for [**ThrottleKit**](https://www.npmjs.com/package/throttlekit) — distributed rate
+limiting against the **one** Node core, reached through either of two pluggable backends and proven
+against the **same** golden vectors:
+
+| Backend | Path | Decision computed in | Use it when |
+|---|---|---|---|
+| `ServiceBackend` | gRPC → [`throttlekit-server`](https://github.com/AmeyaBorkar/throttlekit/tree/main/server) | the service (= the core) | you want the full surface (`check`/`check_many`/`peek`/`forecast`) and to never touch the raw wire |
+| `RedisBackend` | vendored Lua → the **same Redis** a Node fleet uses | Lua-in-Redis (the core's own script) | you already run Redis and want one hop, no extra service — `check` only |
+
+> **Status: experimental (alpha).** The contract (`throttlekit.proto`, the golden vectors, and the
+> extracted Lua) is vendored and checksum-pinned from the frozen `throttlekit` 1.0 core; this client
+> tracks it. The raw Lua wire is **not** a frozen contract yet (it ships `frozen: false`), so the
+> `RedisBackend` is explicitly experimental and may change with the core's scripts.
+
+## The one invariant
+
+The whole ThrottleKit design rests on it: **exactly one thing computes a `Decision`** — the Node core,
+directly or as Lua-in-Redis. Neither backend re-implements an algorithm, so there is no second rate
+limiter to keep in sync and no float-determinism risk. The `RedisBackend` marshals ARGV, runs the
+core's vendored script, and decodes the reply; the decision is produced **server-side, in Lua**.
+
+## Install
+
+Installed as **`throttlekit-py`**, imported as **`throttlekit`** (PyPI's `throttlekit` is an unrelated
+project):
+
+```bash
+pip install throttlekit-py            # (alpha; not yet published) — the gRPC ServiceBackend
+pip install "throttlekit-py[redis]"   # + a redis client for the direct RedisBackend
+```
+
+## Use — the service door
+
+```python
+from throttlekit import ServiceBackend
+
+with ServiceBackend("localhost:50051") as rl:
+    d = rl.check("api", api_key)
+    if not d.allowed:
+        ...  # 429 — retry after d.retry_after_ms
+```
+
+`check` / `check_many` / `peek` / `forecast` return frozen `Decision` / `Forecast` dataclasses. A
+*denial* is a normal `Decision` (`allowed is False`), never an exception; gRPC faults map to
+`PolicyNotFoundError` / `OperationNotSupportedError` / `ServiceUnavailableError`.
+
+## Use — the direct Redis door
+
+Configure a strategy and point it at the Redis your fleet shares. `check` is the whole surface (it is
+the contract-vectored, Lua-computed decision); `peek` / `forecast` deliberately stay on the service
+door, where the core — not a re-derived client port — computes them.
+
+```python
+import redis
+from throttlekit import RedisBackend, Gcra
+
+client = redis.Redis.from_url("redis://localhost:6379")
+api = RedisBackend(client, Gcra(limit=100, period_ms=60_000, burst=20), prefix="prod")
+
+d = api.check(api_key)             # now defaults to the Redis server clock (skew-free across a fleet)
+if not d.allowed:
+    ...                            # 429 — retry after d.retry_after_ms
+```
+
+Strategies: `Gcra`, `TokenBucket`, `FixedWindow`, `SlidingWindow`, `SlidingWindowLog`. The `prefix`
+joins as `f"{prefix}:{key}"` — the **same** key scheme the core uses, so a Python and a Node client on
+one limit address the same Redis key. The backend is client-agnostic: pass any object with `evalsha` /
+`eval` (`redis-py` satisfies it structurally), exactly as the Node `RedisStore` does.
+
+## How this stays in lock-step with the core
+
+`scripts/sync_contract.py` vendors, with checksums, from the core repo:
+
+* `contract/` — the dev/test artifacts: `throttlekit.proto` (→ gRPC stubs) and `golden-vectors.json`.
+* `src/throttlekit/_scripts/` — the **runtime** Lua the `RedisBackend` executes (shipped in the wheel),
+  with the core's `manifest.json` (which carries each script's sha256).
+
+`tests/test_contract.py` is the **drift-gate** (the vendored bytes must match their checksums and the
+pinned `contractVersion`). But the real proof is behavioral:
+
+* **`tests/test_redis_backend.py`** replays **every** rate-limit golden vector — the full,
+  time-parametrized timeline — through the Python client → vendored Lua → **real Redis**, and asserts
+  every reply field equals the Node oracle bit-for-bit. (Because the direct path puts an explicit `now`
+  in ARGV, it can do the rigorous time-parametrized replay the cross-process service door can't.)
+* `tests/test_service_backend.py` starts a real `throttlekit-server` and asserts the clock-independent
+  behavior over gRPC.
+
+## Develop
+
+```bash
+pip install -e .[dev]
+python scripts/sync_contract.py          # vendor proto + vectors + Lua from ../GreenfeildProject (the core)
+python scripts/gen_proto.py              # generate the gRPC stubs from the vendored proto
+pytest                                   # unit + contract; the Redis/service tests skip if their backend is absent
+ruff check . && mypy                     # lint + types
+```
+
+The `RedisBackend` conformance needs a reachable Redis: it uses `THROTTLEKIT_REDIS_URL` or the project
+default `redis://localhost:6380`, and skips cleanly when neither is up.