limitra 1.0.0__tar.gz

limitra-1.0.0/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-1.0.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: limitra
+Version: 1.0.0
+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="docs/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/python-package.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 configure, rate_limit
+
+configure(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-1.0.0/README.md

@@ -0,0 +1,35 @@
+<p align="center">
+  <img src="docs/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/python-package.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 configure, rate_limit
+
+configure(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-1.0.0/limitra/__init__.py

@@ -0,0 +1,27 @@
+"""limitra — simple, framework-agnostic rate limiting for Python."""
+
+from ._config import LimitraConfig
+from ._decorator import rate_limit
+from .algorithms import (
+    LIMITERS,
+    FixedWindowRateLimiter,
+    LeakyBucketLimiter,
+    SlidingWindowRateLimiter,
+    TokenBucketLimiter,
+)
+from .base import BaseRateLimiter
+from .exceptions import RateLimitExceeded
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "LimitraConfig",
+    "rate_limit",
+    "RateLimitExceeded",
+    "BaseRateLimiter",
+    "TokenBucketLimiter",
+    "LeakyBucketLimiter",
+    "FixedWindowRateLimiter",
+    "SlidingWindowRateLimiter",
+    "LIMITERS",
+]

limitra-1.0.0/limitra/_config.py

@@ -0,0 +1,95 @@
+"""Global configuration singleton for limitra."""
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+try:
+    import redis as _redis_lib
+except ImportError:
+    _redis_lib = None  # type: ignore[assignment]
+
+
+@dataclass
+class _Config:
+    """Holds global defaults applied to every rate limiter."""
+
+    redis_client: Optional[Any] = None
+    project: Optional[str] = None
+    prefix: Optional[str] = None
+    suffix: Optional[str] = None
+    default_algorithm: str = "sliding_window"
+    default_backend: str = "memory"
+    fail_open: bool = False
+
+
+class _ConfigStore:
+    """Mutable holder for the active configuration (avoids module-level global)."""
+
+    _current: _Config = _Config()
+
+    @classmethod
+    def get(cls) -> _Config:
+        """Return the active configuration."""
+        return cls._current
+
+    @classmethod
+    def set(cls, config: _Config) -> None:
+        """Replace the active configuration."""
+        cls._current = config
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset to default configuration."""
+        cls._current = _Config()
+
+
+def LimitraConfig(  # pylint: disable=invalid-name
+    redis_url: Optional[str] = None,
+    redis_client: Optional[Any] = None,
+    redis_db: int = 0,
+    project: Optional[str] = None,
+    prefix: Optional[str] = None,
+    suffix: Optional[str] = None,
+    default_algorithm: str = "sliding_window",
+    default_backend: str = "redis",
+    fail_open: bool = False,
+) -> None:
+    """Configure global defaults for all rate limiters.
+
+    Args:
+        redis_url: Redis connection URL (e.g. "redis://localhost:6379")
+        redis_client: Pre-built Redis client (alternative to redis_url)
+        redis_db: Redis database index when using redis_url
+        project: Namespace prefix for all keys — use to isolate microservices
+                 sharing the same Redis instance (e.g. "user-service")
+        prefix: Optional key prefix added before project (e.g. "rl")
+        suffix: Optional key suffix added after identifier (e.g. "v2")
+        default_algorithm: Algorithm used when none is specified in @rate_limit
+        default_backend: "redis" or "memory"
+    """
+    if redis_url is not None:
+        if _redis_lib is None:
+            raise ImportError("redis package required: pip install limitra")
+        redis_client = _redis_lib.from_url(redis_url, db=redis_db)
+
+    _ConfigStore.set(
+        _Config(
+            redis_client=redis_client or _ConfigStore.get().redis_client,
+            project=project,
+            prefix=prefix,
+            suffix=suffix,
+            default_algorithm=default_algorithm,
+            default_backend=default_backend,
+            fail_open=fail_open,
+        )
+    )
+
+
+def get_config() -> _Config:
+    """Return the active global configuration."""
+    return _ConfigStore.get()
+
+
+def reset_config() -> None:
+    """Reset global configuration to defaults (used in tests)."""
+    _ConfigStore.reset()

limitra-1.0.0/limitra/_decorator.py

@@ -0,0 +1,279 @@
+"""The @rate_limit decorator — works with any sync or async Python function."""
+
+import functools
+from inspect import iscoroutinefunction, signature
+from typing import Any, Callable, Dict, List, Optional, Tuple, TypeVar, Union, cast
+
+
+from ._config import get_config
+from .algorithms import LIMITERS
+from .base import BaseRateLimiter
+from .exceptions import RateLimitExceeded
+
+# Window-based algorithms derive fill_rate as 1/window; others use requests/window.
+_WINDOW_BASED = {"sliding_window", "fixed_window"}
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _build_limiter(
+    requests: int,
+    window: float,
+    algorithm: Optional[str],
+    scope: str,
+    backend: Optional[str],
+    redis_client: Optional[Any],
+    project: Optional[str],
+    prefix: Optional[str],
+    suffix: Optional[str],
+    fail_open: Optional[bool] = None,
+) -> BaseRateLimiter:
+    """Instantiate the appropriate limiter class with resolved configuration."""
+    config = get_config()
+    algorithm = algorithm or config.default_algorithm
+    backend = backend or config.default_backend
+    redis_client = redis_client if redis_client is not None else config.redis_client
+    project = project if project is not None else config.project
+    prefix = prefix if prefix is not None else config.prefix
+    suffix = suffix if suffix is not None else config.suffix
+    resolved_fail_open: bool = config.fail_open if fail_open is None else fail_open
+
+    if backend == "redis" and redis_client is None:
+        raise ValueError(
+            "Redis backend requires a client. "
+            "Call limitra.LimitraConfig(redis_url='redis://...') first."
+        )
+
+    limiter_cls = LIMITERS.get(algorithm)
+    if limiter_cls is None:
+        raise ValueError(f"Unknown algorithm '{algorithm}'. Options: {list(LIMITERS)}")
+
+    fill_rate = (1 / window) if algorithm in _WINDOW_BASED else (requests / window)
+
+    kwargs: Dict[str, Any] = {
+        "capacity": requests,
+        "fill_rate": fill_rate,
+        "scope": scope,
+        "backend": backend,
+        "project": project,
+        "prefix": prefix,
+        "suffix": suffix,
+        "fail_open": resolved_fail_open,
+    }
+    if backend == "redis":
+        kwargs["redis_client"] = redis_client
+
+    return limiter_cls(**kwargs)  # type: ignore[no-any-return]
+
+
+def _extract_identifier(
+    key: Union[str, int, Callable[..., str], None],
+    func: Callable[..., Any],
+    args: Tuple[Any, ...],
+    kwargs: Dict[str, Any],
+) -> Optional[str]:
+    """Extract the rate-limit identifier from the decorated function's arguments."""
+    if key is None:
+        return None
+    if callable(key):
+        return str(key(*args, **kwargs))
+    if isinstance(key, int):
+        return str(args[key])
+    if isinstance(key, str):
+        if key in kwargs:
+            return str(kwargs[key])
+        params = list(signature(func).parameters.keys())
+        if key in params:
+            idx = params.index(key)
+            if idx < len(args):
+                return str(args[idx])
+        raise ValueError(f"rate_limit key='{key}' not found in function arguments")
+    raise TypeError(f"rate_limit key must be str, int, or callable — got {type(key)}")
+
+
+def rate_limit(
+    requests: Union[int, Callable[..., int]] = 0,
+    window: Union[float, Callable[..., float]] = 0,
+    algorithm: Optional[str] = None,
+    key: Union[str, int, Callable[..., str], None] = None,
+    scope: str = "user",
+    backend: Optional[str] = None,
+    redis_client: Optional[Any] = None,
+    project: Optional[str] = None,
+    prefix: Optional[str] = None,
+    suffix: Optional[str] = None,
+    on_exceeded: Optional[Callable[..., Any]] = None,
+    limits: Optional[List[Tuple[int, float]]] = None,
+    block: bool = True,
+    exempt_when: Optional[Callable[..., bool]] = None,
+    fail_open: Optional[bool] = None,
+) -> Callable[[F], F]:
+    """Decorator that rate-limits any Python function (sync or async).
+
+    Args:
+        requests: Maximum calls allowed within the window. Accepts a callable
+                  evaluated per-request as ``requests(*args, **kwargs) → int``
+                  for dynamic per-caller limits (e.g. tiered plans).
+        window:   Time window in seconds. Accepts a callable evaluated
+                  per-request as ``window(*args, **kwargs) → float``.
+        algorithm: One of "sliding_window" (default), "token_bucket",
+                   "leaky_bucket", "fixed_window".
+        key:      How to extract the per-caller identifier from the function args:
+                    - None        → single global counter for this function
+                    - "arg_name"  → use the named argument's value
+                    - 0, 1, ...   → use positional argument by index
+                    - callable    → called as key(*args, **kwargs), return a str
+        scope:    Label stored in the Redis key (e.g. "user", "ip", "team").
+        backend:  "redis" or "memory". Falls back to configure() default.
+        redis_client: Override the global Redis client for this limiter only.
+        project:  Override the global project namespace for this limiter only.
+        prefix:   Override the global key prefix for this limiter only.
+        suffix:   Override the global key suffix for this limiter only.
+        on_exceeded: Optional callable(exc: RateLimitExceeded) — called instead of
+                     raising when the limit is hit.
+        limits:   List of (requests, window) tuples. When given, ALL limits must
+                  pass. Takes precedence over requests/window.
+        block:    When False, the decorated function always runs. If over limit,
+                  on_exceeded is called as a side effect only.
+        exempt_when: Optional callable(*args, **kwargs) → bool. When it returns
+                     True, the request bypasses rate limiting entirely.
+        fail_open: When True, allow requests on backend errors instead of
+                   falling back to memory.
+
+    Raises:
+        RateLimitExceeded: When the limit is hit and on_exceeded is not set.
+    """
+    actual_scope = "global" if key is None else scope
+    _is_dynamic = (callable(requests) or callable(window)) and limits is None
+
+    def decorator(func: F) -> F:
+        """Wrap func with rate-limiting logic."""
+        _static_limiters: Optional[List[BaseRateLimiter]] = None
+        _dynamic_cache: Dict[Tuple[int, float], BaseRateLimiter] = {}
+
+        def _build_static() -> List[BaseRateLimiter]:
+            nonlocal _static_limiters
+            if _static_limiters is not None:
+                return _static_limiters
+            result: List[BaseRateLimiter] = []
+            if limits is not None:
+                use_suffix = len(limits) > 1
+                for req, win in limits:
+                    lim_scope = (
+                        f"{actual_scope}_{int(win)}" if use_suffix else actual_scope
+                    )
+                    result.append(
+                        _build_limiter(
+                            requests=req,
+                            window=win,
+                            algorithm=algorithm,
+                            scope=lim_scope,
+                            backend=backend,
+                            redis_client=redis_client,
+                            project=project,
+                            prefix=prefix,
+                            suffix=suffix,
+                            fail_open=fail_open,
+                        )
+                    )
+            else:
+                result = [
+                    _build_limiter(
+                        requests=int(requests),  # type: ignore[arg-type]
+                        window=float(window),  # type: ignore[arg-type]
+                        algorithm=algorithm,
+                        scope=actual_scope,
+                        backend=backend,
+                        redis_client=redis_client,
+                        project=project,
+                        prefix=prefix,
+                        suffix=suffix,
+                        fail_open=fail_open,
+                    )
+                ]
+            _static_limiters = result
+            return result
+
+        def _get_dynamic(req: int, win: float) -> BaseRateLimiter:
+            cache_key = (req, win)
+            if cache_key not in _dynamic_cache:
+                _dynamic_cache[cache_key] = _build_limiter(
+                    requests=req,
+                    window=win,
+                    algorithm=algorithm,
+                    scope=actual_scope,
+                    backend=backend,
+                    redis_client=redis_client,
+                    project=project,
+                    prefix=prefix,
+                    suffix=suffix,
+                    fail_open=fail_open,
+                )
+            return _dynamic_cache[cache_key]
+
+        def _check(
+            identifier: Optional[str],
+            args: Tuple[Any, ...],
+            kwargs_inner: Dict[str, Any],
+        ) -> Optional[Any]:
+            if exempt_when is not None and exempt_when(*args, **kwargs_inner):
+                return None
+
+            lims: List[BaseRateLimiter]
+            pairs: List[Tuple[int, float]]
+
+            if _is_dynamic:
+                actual_req = (
+                    int(requests(*args, **kwargs_inner))
+                    if callable(requests)
+                    else requests
+                )
+                actual_win = (
+                    float(window(*args, **kwargs_inner)) if callable(window) else window
+                )
+                lims = [_get_dynamic(actual_req, actual_win)]
+                pairs = [(actual_req, actual_win)]
+            else:
+                lims = _build_static()
+                pairs = (
+                    list(limits)
+                    if limits is not None
+                    else [(int(requests), float(window))]  # type: ignore[arg-type]
+                )
+
+            for i, limiter in enumerate(lims):
+                if not limiter.allow_request(identifier):
+                    req, win = pairs[i]
+                    wait = limiter.get_wait_time(identifier)
+                    exc = RateLimitExceeded(requests=req, window=win, retry_after=wait)
+                    if not block:
+                        if on_exceeded is not None:
+                            on_exceeded(exc)
+                        return None
+                    if on_exceeded is not None:
+                        return on_exceeded(exc)
+                    raise exc
+            return None
+
+        @functools.wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            """Async rate-limited wrapper."""
+            identifier = _extract_identifier(key, func, args, kwargs)
+            result = _check(identifier, args, kwargs)
+            if result is not None:
+                return result
+            return await func(*args, **kwargs)
+
+        @functools.wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            """Sync rate-limited wrapper."""
+            identifier = _extract_identifier(key, func, args, kwargs)
+            result = _check(identifier, args, kwargs)
+            if result is not None:
+                return result
+            return func(*args, **kwargs)
+
+        wrapper = async_wrapper if iscoroutinefunction(func) else sync_wrapper
+        return cast(F, wrapper)
+
+    return decorator

limitra-1.0.0/limitra/algorithms/__init__.py

@@ -0,0 +1,23 @@
+"""Rate-limiting algorithm implementations."""
+
+from typing import Any, Dict
+
+from .fixed_window import FixedWindowRateLimiter
+from .leaky_bucket import LeakyBucketLimiter
+from .sliding_window import SlidingWindowRateLimiter
+from .token_bucket import TokenBucketLimiter
+
+LIMITERS: Dict[str, Any] = {
+    "token_bucket": TokenBucketLimiter,
+    "leaky_bucket": LeakyBucketLimiter,
+    "fixed_window": FixedWindowRateLimiter,
+    "sliding_window": SlidingWindowRateLimiter,
+}
+
+__all__ = [
+    "FixedWindowRateLimiter",
+    "LeakyBucketLimiter",
+    "SlidingWindowRateLimiter",
+    "TokenBucketLimiter",
+    "LIMITERS",
+]

limitra-1.0.0/limitra/algorithms/fixed_window.py

@@ -0,0 +1,133 @@
+"""Fixed window rate limiter: counts requests per discrete time slot."""
+
+import time
+from typing import Any, Dict, Optional
+
+from ..base import BaseRateLimiter
+
+try:
+    from redis import RedisError as _RedisError
+except ImportError:
+    _RedisError = Exception  # type: ignore[assignment,misc]
+
+_LUA_SCRIPT = """
+local window_key = KEYS[1]
+local capacity = tonumber(ARGV[1])
+local ttl = tonumber(ARGV[2])
+local count = redis.call('INCR', window_key)
+if count == 1 then
+    redis.call('EXPIRE', window_key, ttl)
+end
+return count <= capacity and 1 or 0
+"""
+
+
+class FixedWindowRateLimiter(BaseRateLimiter):
+    """Fastest algorithm. Counts requests per fixed time slot.
+
+    Known caveat: allows 2× capacity at window boundaries.
+    """
+
+    def __init__(
+        self,
+        capacity: int,
+        fill_rate: float,
+        scope: str = "user",
+        backend: str = "memory",
+        redis_client: Optional[Any] = None,
+        project: Optional[str] = None,
+        prefix: Optional[str] = None,
+        suffix: Optional[str] = None,
+        fail_open: bool = False,
+    ):
+        super().__init__(
+            capacity,
+            fill_rate,
+            scope,
+            backend,
+            redis_client,
+            project,
+            prefix,
+            suffix,
+            fail_open,
+        )
+        self._window = 1 / fill_rate
+        self._ttl = int(self._window * 2) + 60
+
+    def allow_request(self, identifier: Optional[str] = None) -> bool:
+        """Return True if the request count for the current window slot is below capacity."""
+        key = self.get_key(identifier)
+        now = time.time()
+        slot = int(now / self._window)
+        if self.backend == "redis":
+            try:
+                window_key = f"{key}:{slot}"
+                result = self._redis.eval(
+                    _LUA_SCRIPT, 1, window_key, self.capacity, self._ttl
+                )
+                return bool(result)
+            except _RedisError:
+                if self.fail_open:
+                    return True
+        return self._allow_memory(key, slot)
+
+    def _allow_memory(self, key: str, slot: int) -> bool:
+        """In-memory fixed window logic protected by a per-key lock."""
+        with self._get_key_lock(key):
+            data = self._get_from_backend(key)
+            if data is None or int(data["slot"]) < slot:
+                self._set_to_backend(key, {"count": 1, "slot": slot}, self._ttl)
+                return True
+            if data["count"] < self.capacity:
+                self._set_to_backend(
+                    key, {"count": data["count"] + 1, "slot": slot}, self._ttl
+                )
+                return True
+            return False
+
+    def get_wait_time(self, identifier: Optional[str] = None) -> float:
+        """Return seconds until the current window slot resets (0 if requests are allowed)."""
+        key = self.get_key(identifier)
+        now = time.time()
+        slot = int(now / self._window)
+        if self.backend == "redis":
+            try:
+                raw = self._redis.get(f"{key}:{slot}")
+                count = int(raw) if raw else 0
+            except Exception:  # pylint: disable=broad-except
+                return 0.0
+        else:
+            data = self._get_from_backend(key)
+            count = int(data["count"]) if (data and int(data["slot"]) == slot) else 0
+        if count < self.capacity:
+            return 0.0
+        return self._window - (now % self._window)
+
+    def reset(self, identifier: Optional[str] = None) -> None:
+        """Reset counters. For Redis, deletes the window-specific slot key."""
+        key = self.get_key(identifier)
+        if self.backend == "redis":
+            slot = int(time.time() / self._window)
+            self._redis.delete(f"{key}:{slot}")
+        else:
+            self._delete_from_backend(key)
+
+    def get_status(self, identifier: Optional[str] = None) -> Dict[str, Any]:
+        """Return request count and remaining capacity for the current window slot."""
+        key = self.get_key(identifier)
+        now = time.time()
+        slot = int(now / self._window)
+        if self.backend == "redis":
+            try:
+                raw = self._redis.get(f"{key}:{slot}")
+                count = int(raw) if raw else 0
+            except _RedisError:
+                count = 0
+        else:
+            _, _, data = self._get_state(identifier)
+            count = int(data["count"]) if (data and int(data["slot"]) == slot) else 0
+        return {
+            "count": count,
+            "capacity": self.capacity,
+            "available": max(0, self.capacity - count),
+        }