limitra 0.0.1__tar.gz

limitra-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+permissions: {}
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      - uses: astral-sh/setup-uv@v4
+
+      - uses: jdx/mise-action@v2
+        with:
+          install: false
+
+      - name: Install dependencies
+        run: uv pip install --system -e '.' -r requirements-dev.txt
+
+      - name: Lint
+        run: mise run pylint
+
+      - name: Type check
+        run: mise run mypy
+
+      - name: Run tests
+        run: mise run test
+
+  test-min-deps:
+    name: Min deps / Python 3.10
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - uses: astral-sh/setup-uv@v4
+
+      - uses: jdx/mise-action@v2
+        with:
+          install: false
+
+      - name: Install minimum dependencies
+        run: uv pip install --system --resolution lowest-direct -e '.' -r requirements-dev.txt
+
+      - name: Run tests
+        run: mise run test

limitra-0.0.1/.github/workflows/python-package.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [created]
+
+permissions: {}
+
+jobs:
+  publish:
+    name: Build & publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v4
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish

limitra-0.0.1/.gitignore

@@ -0,0 +1,34 @@
+# Generated by setuptools-scm
+limitra/_version.py
+
+# Virtual environment
+.venv/
+
+# Python bytecode
+__pycache__/
+*.py[cod]
+
+# Build / distribution
+build/
+dist/
+*.egg-info/
+*.egg
+
+# MkDocs
+site/
+
+# Test & coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Type checking & linting
+.mypy_cache/
+.pylint.d/
+
+# OS
+.DS_Store
+
+# mise
+.mise.local.toml

limitra-0.0.1/.mise-tasks/black

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+#MISE description="Format code with black"
+set -e
+black limitra/ tests/

limitra-0.0.1/.mise-tasks/check

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+#MISE description="Run isort, black, pylint, and mypy in sequence"
+set -e
+isort limitra/ tests/
+black limitra/ tests/
+pylint limitra tests/
+mypy limitra --strict

limitra-0.0.1/.mise-tasks/ci

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+#MISE description="Run full CI workflow (lint + typecheck + tests) across all Python versions from the GitHub Actions matrix"
+VERSIONS=("3.10" "3.11" "3.12" "3.13" "3.14")
+FAILED=()
+
+CI_BASE="$HOME/.cache/limitra-ci-$$"
+mkdir -p "$CI_BASE"
+trap 'rm -rf "$CI_BASE"' EXIT
+
+export TMPDIR="$HOME/.cache/limitra-tmp"
+export UV_CACHE_DIR="$HOME/.cache/uv"
+mkdir -p "$TMPDIR" "$UV_CACHE_DIR"
+
+for version in "${VERSIONS[@]}"; do
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "  Python $version"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+    mise install python@$version
+
+    VENV="$CI_BASE/${version}/venv"
+    uv venv "$VENV" --python $version --seed -q
+    uv pip install -q -r requirements-dev.txt -e . --python "$VENV/bin/python"
+
+    echo "--- Lint ---"
+    if ! "$VENV/bin/pylint" limitra tests/; then
+        FAILED+=("$version:lint"); continue
+    fi
+
+    echo "--- Type check ---"
+    if ! "$VENV/bin/mypy" limitra --strict; then
+        FAILED+=("$version:mypy"); continue
+    fi
+
+    echo "--- Tests ---"
+    if ! "$VENV/bin/pytest" -v --tb=short; then
+        FAILED+=("$version:tests")
+    fi
+done
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  Min deps / Python 3.10"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+VENV="$CI_BASE/3.10-min/venv"
+uv venv "$VENV" --python 3.10 --seed -q
+uv pip install -q --resolution lowest-direct -r requirements-dev.txt -e . --python "$VENV/bin/python"
+
+if ! "$VENV/bin/pytest" -v --tb=short; then
+    FAILED+=("3.10:min-deps")
+fi
+
+echo ""
+if [ ${#FAILED[@]} -gt 0 ]; then
+    echo "FAILED: ${FAILED[*]}"
+    exit 1
+fi
+echo "All versions passed!"

limitra-0.0.1/.mise-tasks/doc

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+#MISE description="Build and serve the documentation locally"
+set -e
+export TMPDIR="$HOME/.cache/mkdocs-tmp"
+mkdir -p "$TMPDIR"
+pip install -r requirements-docs.txt -q
+mkdocs serve

limitra-0.0.1/.mise-tasks/install

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+#MISE description="Install project + dev dependencies into the venv"
+set -e
+uv pip install -e '.' -r requirements-dev.txt

limitra-0.0.1/.mise-tasks/isort

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+#MISE description="Sort imports with isort"
+set -e
+isort limitra/ tests/

limitra-0.0.1/.mise-tasks/mypy

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+#MISE description="Type-check with mypy"
+set -e
+mypy limitra --strict

limitra-0.0.1/.mise-tasks/pylint

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+#MISE description="Lint with pylint"
+set -e
+pylint limitra tests/

limitra-0.0.1/.mise-tasks/test

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+#MISE description="Run the full test suite"
+set -e
+pytest tests/ -v

limitra-0.0.1/.mise-tasks/test-no-redis

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+#MISE description="Run tests, skip Redis tests"
+set -e
+pytest tests/ -v -k 'not redis'

limitra-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Léo Kling
+
+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.

limitra-0.0.1/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: limitra
+Version: 0.0.1
+Summary: Simple, framework-agnostic rate limiting for Python — sliding window, token bucket, leaky bucket, fixed window, memory and Redis backends
+Author-email: Léo Kling <contact@leok.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/leo-kling/limitra
+Project-URL: Repository, https://github.com/leo-kling/limitra
+Project-URL: Issues, https://github.com/leo-kling/limitra/issues
+Keywords: rate-limit,rate-limiter,rate-limiting,ratelimit,throttle,throttling,sliding-window,token-bucket,leaky-bucket,fixed-window,fastapi,django,flask,redis,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://limitra.pages.dev/logo.png" alt="Limitra" width="120" />
+</p>
+
+<h1 align="center">Limitra</h1>
+
+<p align="center">
+  <img src="https://github.com/leo-kling/limitra/actions/workflows/ci.yml/badge.svg" alt="CI" />
+  <img src="https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13%20|%203.14-blue" alt="Python versions" />
+  <img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT license" />
+</p>
+
+<p align="center">Simple, framework-agnostic rate limiting for Python.</p>
+
+---
+
+## Install
+
+```bash
+pip install limitra
+```
+
+## Quick start
+
+```python
+from limitra import LimitraConfig, rate_limit
+
+LimitraConfig(redis_url="redis://localhost:6379", project="my-service")
+
+@rate_limit(requests=10, window=60, key="user_id")
+def create_post(user_id: str, content: str):
+    ...
+```
+
+→ Full documentation: **[limitra.leok.dev](https://limitra.leok.dev)**

limitra-0.0.1/README.md

@@ -0,0 +1,35 @@
+<p align="center">
+  <img src="https://limitra.pages.dev/logo.png" alt="Limitra" width="120" />
+</p>
+
+<h1 align="center">Limitra</h1>
+
+<p align="center">
+  <img src="https://github.com/leo-kling/limitra/actions/workflows/ci.yml/badge.svg" alt="CI" />
+  <img src="https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13%20|%203.14-blue" alt="Python versions" />
+  <img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT license" />
+</p>
+
+<p align="center">Simple, framework-agnostic rate limiting for Python.</p>
+
+---
+
+## Install
+
+```bash
+pip install limitra
+```
+
+## Quick start
+
+```python
+from limitra import LimitraConfig, rate_limit
+
+LimitraConfig(redis_url="redis://localhost:6379", project="my-service")
+
+@rate_limit(requests=10, window=60, key="user_id")
+def create_post(user_id: str, content: str):
+    ...
+```
+
+→ Full documentation: **[limitra.leok.dev](https://limitra.leok.dev)**

limitra-0.0.1/docs/getting-started/configuration.md

@@ -0,0 +1,129 @@
+# Configuration
+
+## How it works
+
+Limitra uses two levels of configuration:
+
+| | `LimitraConfig()` | `@rate_limit()` |
+|---|---|---|
+| **When** | Once at app startup | On each function to protect |
+| **What** | Redis connection, namespace, defaults | The rule: how many requests, which window |
+| **Scope** | Global — applies to all limiters | Local — this function only |
+
+In practice: `LimitraConfig()` connects Limitra to Redis and sets global defaults. `@rate_limit()` defines the rule on a specific function and inherits everything set by `LimitraConfig()`.
+
+---
+
+## Full example
+
+```python
+# main.py (or app.py, startup.py...)
+from limitra import LimitraConfig, rate_limit, RateLimitExceeded
+
+# 1. Global setup — call once at startup
+LimitraConfig(
+    redis_url="redis://localhost:6379",
+    project="my-service",   # isolates Redis keys for this service
+)
+
+# 2. Decorate each function to protect
+@rate_limit(requests=10, window=60, key="user_id")
+def create_post(user_id: str, content: str):
+    ...
+
+@rate_limit(requests=1000, window=60)
+def public_feed():
+    ...
+```
+
+---
+
+## Without Redis — memory backend
+
+If you don't need Redis (local development, single-process app), `LimitraConfig()` is not required. The memory backend is used by default:
+
+```python
+from limitra import rate_limit
+
+@rate_limit(requests=10, window=60, key="user_id", backend="memory")
+def create_post(user_id: str, content: str):
+    ...
+```
+
+!!! warning
+    The memory backend is not shared between processes or restarts. For production apps with multiple workers, use Redis.
+
+---
+
+## `LimitraConfig()` parameters
+
+### Redis connection
+
+```python
+# Option A — URL
+LimitraConfig(redis_url="redis://localhost:6379")
+LimitraConfig(redis_url="rediss://user:pass@host:6380/0")  # TLS
+
+# Option B — pre-built client (useful with connection pooling)
+import redis
+client = redis.Redis(host="localhost", port=6379, db=0)
+LimitraConfig(redis_client=client)
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `redis_url` | `str` | `None` | Connection URL passed to `redis.from_url()` |
+| `redis_client` | `Redis` | `None` | Pre-built Redis client |
+| `redis_db` | `int` | `0` | Redis database index (only used with `redis_url`) |
+
+### Key namespace
+
+```python
+LimitraConfig(
+    redis_url="redis://shared:6379",
+    project="user-svc",   # → keys: user-svc:user:alice
+    prefix="rl",          # → keys: rl:user-svc:user:alice
+    suffix="v2",          # → keys: rl:user-svc:user:alice:v2
+)
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `project` | `str` | `None` | Namespace prefix — recommended to isolate microservices sharing the same Redis |
+| `prefix` | `str` | `None` | Key prefix added before `project` |
+| `suffix` | `str` | `None` | Key suffix added after the identifier |
+
+### Defaults
+
+These values are used by `@rate_limit()` when the corresponding parameters are not specified.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `default_algorithm` | `str` | `"sliding_window"` | Default algorithm |
+| `default_backend` | `str` | `"redis"` | Default backend after `LimitraConfig()` is called |
+| `fail_open` | `bool` | `False` | When `True`, allow requests if Redis is unreachable instead of raising an error |
+
+---
+
+## Overriding `LimitraConfig()` per function
+
+Any `@rate_limit()` parameter overrides the global setting for that function only:
+
+```python
+LimitraConfig(redis_url="redis://localhost:6379", project="my-svc")
+
+# Uses all globals — project "my-svc", redis backend
+@rate_limit(requests=100, window=60)
+def normal_endpoint():
+    ...
+
+# Overrides the backend for this function only
+@rate_limit(requests=100, window=60, backend="memory")
+def local_only_endpoint():
+    ...
+
+# Overrides the project for this function only
+@rate_limit(requests=5, window=60, project="billing")
+def billing_endpoint():
+    ...
+```

limitra-0.0.1/docs/getting-started/installation.md

@@ -0,0 +1,30 @@
+# Installation
+
+**Python 3.10+** is required.
+
+```bash
+pip install limitra
+```
+
+Limitra has zero runtime dependencies. The memory backend works out of the box.
+
+## Redis backend
+
+Limitra does not ship `redis` as a dependency — if you're using Redis for rate limiting, you're most likely already using it elsewhere in your project.
+
+Add it to your project's own dependencies:
+
+```bash
+pip install redis        # or: poetry add redis, uv add redis, etc.
+```
+
+Limitra detects it automatically. Any `redis>=4.0` version works.
+
+!!! note
+    If `redis` is not installed and you configure a Redis backend, Limitra raises `ImportError` with a clear message at startup.
+
+## Local Redis for development
+
+```bash
+docker run -p 6379:6379 redis:alpine
+```