limitra 0.0.1__py3-none-any.whl

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
+
+from ._version import __version__
+
+__all__ = [
+    "LimitraConfig",
+    "rate_limit",
+    "RateLimitExceeded",
+    "BaseRateLimiter",
+    "TokenBucketLimiter",
+    "LeakyBucketLimiter",
+    "FixedWindowRateLimiter",
+    "SlidingWindowRateLimiter",
+    "LIMITERS",
+]

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/_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 LimitraConfig() 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/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

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/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),
+        }

limitra/algorithms/leaky_bucket.py

@@ -0,0 +1,139 @@
+"""Leaky bucket rate limiter: smooths traffic by draining at a constant rate."""
+
+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 key = KEYS[1]
+local capacity = tonumber(ARGV[1])
+local fill_rate = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local ttl = tonumber(ARGV[4])
+local data = redis.call('GET', key)
+local level, last
+if data then
+    local s = cjson.decode(data)
+    level = tonumber(s.level)
+    last = tonumber(s.last)
+else
+    level = 0
+    last = now
+end
+level = math.max(0, level - (now - last) * fill_rate)
+local allowed = 0
+if level + 1 <= capacity then
+    level = level + 1
+    allowed = 1
+end
+redis.call('SETEX', key, ttl, cjson.encode({level=level, last=now}))
+return {allowed, level}
+"""
+
+
+class LeakyBucketLimiter(BaseRateLimiter):
+    """Smooths traffic: requests drain at fill_rate/sec, bursts are absorbed up to capacity."""
+
+    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._ttl = int((capacity / fill_rate) * 2) + 60
+
+    def _current_level(self, data: Any, now: float) -> float:
+        return max(0.0, float(data["level"]) - (now - float(data["last"])) * self.fill_rate)
+
+    def allow_request(self, identifier: Optional[str] = None) -> bool:
+        """Return True if the bucket has room; add one unit and return False otherwise."""
+        key = self.get_key(identifier)
+        if self.backend == "redis":
+            try:
+                result = self._redis.eval(
+                    _LUA_SCRIPT,
+                    1,
+                    key,
+                    self.capacity,
+                    self.fill_rate,
+                    time.time(),
+                    self._ttl,
+                )
+                return bool(result[0])
+            except _RedisError:
+                if self.fail_open:
+                    return True
+        return self._allow_memory(key)
+
+    def _allow_memory(self, key: str) -> bool:
+        """In-memory leaky bucket logic protected by a per-key lock."""
+        now = time.time()
+        with self._get_key_lock(key):
+            data = self._get_from_backend(key)
+            if data is None:
+                self._set_to_backend(key, {"level": 1.0, "last": now}, self._ttl)
+                return True
+            level = self._current_level(data, now)
+            if level + 1 <= self.capacity:
+                self._set_to_backend(key, {"level": level + 1, "last": now}, self._ttl)
+                return True
+            self._set_to_backend(key, {"level": level, "last": now}, self._ttl)
+            return False
+
+    def get_wait_time(self, identifier: Optional[str] = None) -> float:
+        """Return seconds until the bucket drains enough to accept a request."""
+        _, now, data = self._get_state(identifier)
+        if data is None:
+            return 0.0
+        level = self._current_level(data, now)
+        if level + 1 <= self.capacity:
+            return 0.0
+        return max(0.0, (level + 1 - self.capacity) / self.fill_rate)
+
+    def get_status(self, identifier: Optional[str] = None) -> Dict[str, Any]:
+        """Return current water level and available capacity for the given identifier."""
+        _, now, data = self._get_state(identifier)
+        if data is None:
+            return {"water_level": 0.0, "capacity": self.capacity, "available": float(self.capacity)}
+        level = self._current_level(data, now)
+        return {
+            "water_level": round(level, 2),
+            "capacity": self.capacity,
+            "available": round(max(0.0, self.capacity - level), 2),
+            "utilization_pct": round((level / self.capacity) * 100, 1),
+        }
+
+    def get_usage(self, identifier: Optional[str] = None) -> Dict[str, Any]:
+        """Return usage information in a consistent format."""
+        _, now, data = self._get_state(identifier)
+        water_level = self._current_level(data, now) if data is not None else 0.0
+        return {
+            "count": int(water_level),
+            "limit": self.capacity,
+            "remaining": max(0, int(self.capacity - water_level)),
+            "limited": water_level + 1 > self.capacity,
+        }

limitra/algorithms/sliding_window.py

@@ -0,0 +1,144 @@
+"""Sliding window rate limiter: weighted count prevents boundary bursts."""
+
+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 key = KEYS[1]
+local capacity = tonumber(ARGV[1])
+local window = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local ttl = tonumber(ARGV[4])
+local data = redis.call('GET', key)
+local slot = math.floor(now / window)
+local curr, prev, stored_slot
+if data then
+    local s = cjson.decode(data)
+    curr = tonumber(s.curr)
+    prev = tonumber(s.prev)
+    stored_slot = tonumber(s.slot)
+else
+    curr = 0
+    prev = 0
+    stored_slot = slot
+end
+if stored_slot < slot then
+    prev = (stored_slot == slot - 1) and curr or 0
+    curr = 0
+    stored_slot = slot
+end
+local elapsed_pct = (now % window) / window
+local weighted = curr + (1 - elapsed_pct) * prev
+local allowed = 0
+if weighted < capacity then
+    curr = curr + 1
+    allowed = 1
+end
+redis.call('SETEX', key, ttl, cjson.encode({slot=stored_slot, curr=curr, prev=prev}))
+return allowed
+"""
+
+
+class SlidingWindowRateLimiter(BaseRateLimiter):
+    """Best general-purpose choice: fast and prevents boundary bursts via weighted count."""
+
+    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 * 3) + 60
+
+    def _resolve_window(self, data: Optional[Any], now: float) -> "tuple[int, int, int, float]":
+        """Return (slot, curr, prev, weighted_count) with slot-advance applied."""
+        slot = int(now / self._window)
+        if data is None:
+            return slot, 0, 0, 0.0
+        stored_slot = int(data["slot"])
+        curr = int(data["curr"])
+        prev = int(data["prev"])
+        if stored_slot < slot:
+            prev = curr if stored_slot == slot - 1 else 0
+            curr = 0
+        elapsed_pct = (now % self._window) / self._window
+        return slot, curr, prev, curr + (1 - elapsed_pct) * prev
+
+    def allow_request(self, identifier: Optional[str] = None) -> bool:
+        """Return True if the weighted request count is below capacity."""
+        key = self.get_key(identifier)
+        now = time.time()
+        if self.backend == "redis":
+            try:
+                result = self._redis.eval(
+                    _LUA_SCRIPT, 1, key, self.capacity, self._window, now, self._ttl
+                )
+                return bool(result)
+            except _RedisError:
+                if self.fail_open:
+                    return True
+        return self._allow_memory(key, now)
+
+    def _allow_memory(self, key: str, now: float) -> bool:
+        """In-memory sliding window logic protected by a per-key lock."""
+        with self._get_key_lock(key):
+            data = self._get_from_backend(key)
+            slot, curr, prev, weighted = self._resolve_window(data, now)
+            allowed = weighted < self.capacity
+            if allowed:
+                curr += 1
+            self._set_to_backend(key, {"slot": slot, "curr": curr, "prev": prev}, self._ttl)
+            return allowed
+
+    def get_wait_time(self, identifier: Optional[str] = None) -> float:
+        """Return seconds until the weighted count will drop below capacity (0 if allowed)."""
+        _, now, data = self._get_state(identifier)
+        if data is None:
+            return 0.0
+        _, curr, prev, weighted = self._resolve_window(data, now)
+        if weighted < self.capacity:
+            return 0.0
+        if prev > 0 and curr < self.capacity:
+            needed_elapsed = self._window * (1 - (self.capacity - curr) / prev)
+            wait = needed_elapsed - (now % self._window)
+            if wait > 0:
+                return wait
+        return self._window - (now % self._window)
+
+    def get_status(self, identifier: Optional[str] = None) -> Dict[str, Any]:
+        """Return weighted request count and remaining capacity."""
+        _, now, data = self._get_state(identifier)
+        if data is None:
+            return {"count": 0, "capacity": self.capacity, "available": self.capacity}
+        _, _, _, weighted = self._resolve_window(data, now)
+        weighted_int = int(weighted)
+        return {
+            "count": weighted_int,
+            "capacity": self.capacity,
+            "available": max(0, self.capacity - weighted_int),
+        }

limitra/algorithms/token_bucket.py

@@ -0,0 +1,136 @@
+"""Token bucket rate limiter: allows bursts up to capacity, then throttles."""
+
+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 key = KEYS[1]
+local capacity = tonumber(ARGV[1])
+local fill_rate = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local ttl = tonumber(ARGV[4])
+local data = redis.call('GET', key)
+local tokens, last_fill
+if data then
+    local s = cjson.decode(data)
+    tokens = tonumber(s.tokens)
+    last_fill = tonumber(s.last_fill)
+    tokens = math.min(capacity, tokens + (now - last_fill) * fill_rate)
+else
+    redis.call('SETEX', key, ttl, cjson.encode({tokens=capacity-1, last_fill=now}))
+    return 1
+end
+local allowed = 0
+if tokens >= 1 then
+    tokens = tokens - 1
+    allowed = 1
+end
+redis.call('SETEX', key, ttl, cjson.encode({tokens=tokens, last_fill=now}))
+return allowed
+"""
+
+
+class TokenBucketLimiter(BaseRateLimiter):
+    """Allows bursts up to capacity, then throttles to fill_rate tokens/sec."""
+
+    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._ttl = int((capacity / fill_rate) * 2) + 60
+
+    def _current_tokens(self, data: Any, now: float) -> float:
+        return min(
+            self.capacity,
+            float(data["tokens"]) + (now - float(data["last_fill"])) * self.fill_rate,
+        )
+
+    def allow_request(self, identifier: Optional[str] = None) -> bool:
+        """Return True if a token is available; consume it and return False otherwise."""
+        key = self.get_key(identifier)
+        now = time.time()
+        if self.backend == "redis":
+            try:
+                result = self._redis.eval(
+                    _LUA_SCRIPT, 1, key, self.capacity, self.fill_rate, now, self._ttl
+                )
+                return bool(result)
+            except _RedisError:
+                if self.fail_open:
+                    return True
+        return self._allow_memory(key, now)
+
+    def _allow_memory(self, key: str, now: float) -> bool:
+        """In-memory token bucket logic protected by a per-key lock."""
+        with self._get_key_lock(key):
+            data = self._get_from_backend(key)
+            if data is None:
+                self._set_to_backend(
+                    key, {"tokens": self.capacity - 1, "last_fill": now}, self._ttl
+                )
+                return True
+            tokens = self._current_tokens(data, now)
+            if tokens >= 1:
+                self._set_to_backend(
+                    key, {"tokens": tokens - 1, "last_fill": now}, self._ttl
+                )
+                return True
+            self._set_to_backend(key, {"tokens": tokens, "last_fill": now}, self._ttl)
+            return False
+
+    def get_wait_time(self, identifier: Optional[str] = None) -> float:
+        """Return seconds until the next token is available (0 if tokens remain)."""
+        _, now, data = self._get_state(identifier)
+        if data is None:
+            return 0.0
+        tokens = self._current_tokens(data, now)
+        return max(0.0, (1 - tokens) / self.fill_rate) if tokens < 1 else 0.0
+
+    def get_status(self, identifier: Optional[str] = None) -> Dict[str, Any]:
+        """Return current token count and utilisation for the given identifier."""
+        _, now, data = self._get_state(identifier)
+        if data is None:
+            return {"tokens_remaining": self.capacity, "capacity": self.capacity}
+        tokens = self._current_tokens(data, now)
+        return {
+            "tokens_remaining": round(tokens, 2),
+            "capacity": self.capacity,
+            "utilization_pct": round((1 - tokens / self.capacity) * 100, 1),
+        }
+
+    def get_usage(self, identifier: Optional[str] = None) -> Dict[str, Any]:
+        """Return usage information in a consistent format."""
+        _, now, data = self._get_state(identifier)
+        tokens = self._current_tokens(data, now) if data is not None else float(self.capacity)
+        return {
+            "count": int(self.capacity - tokens),
+            "limit": self.capacity,
+            "remaining": int(tokens),
+            "limited": tokens < 1,
+        }

limitra/base.py

@@ -0,0 +1,152 @@
+"""Base class for all limitra rate limiter implementations."""
+
+import json
+import threading
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, Tuple
+
+
+class BaseRateLimiter(ABC):
+    """Abstract base for all rate limiters.
+
+    Provides backend storage helpers, key generation, and thread-safe
+    per-key locking used by every concrete algorithm.
+    """
+
+    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,
+    ):
+        if capacity <= 0:
+            raise ValueError("capacity must be positive")
+        if fill_rate <= 0:
+            raise ValueError("fill_rate must be positive")
+        if backend not in ("memory", "redis"):
+            raise ValueError("backend must be 'memory' or 'redis'")
+        if backend == "redis" and redis_client is None:
+            raise ValueError("redis_client is required when backend='redis'")
+
+        self.capacity = capacity
+        self.fill_rate = fill_rate
+        self.scope = scope
+        self.backend = backend
+        self.redis_client = redis_client
+        self.project = project
+        self.prefix = prefix
+        self.suffix = suffix
+        self.fail_open = fail_open
+
+        self._memory_storage: Dict[str, Any] = {}
+        self._lock = threading.Lock()
+        self._key_locks: Dict[str, threading.Lock] = {}
+        self._key_locks_lock = threading.Lock()
+
+    def _get_key_lock(self, key: str) -> threading.Lock:
+        """Return a per-key Lock, creating it lazily."""
+        with self._key_locks_lock:
+            if key not in self._key_locks:
+                self._key_locks[key] = threading.Lock()
+            return self._key_locks[key]
+
+    @property
+    def _redis(self) -> Any:
+        """Narrowed, non-optional access to redis_client (only valid when backend='redis')."""
+        assert self.redis_client is not None
+        return self.redis_client
+
+    def get_key(self, identifier: Optional[str] = None) -> str:
+        """Build the storage key for the given identifier.
+
+        Format: [prefix:][ project:]scope[:identifier][:suffix]
+        """
+        parts = []
+        if self.prefix:
+            parts.append(self.prefix)
+        if self.project:
+            parts.append(self.project)
+        parts.append(self.scope)
+        if self.scope != "global" and identifier is not None:
+            parts.append(str(identifier))
+        if self.suffix:
+            parts.append(self.suffix)
+        return ":".join(parts)
+
+    def _get_state(self, identifier: Optional[str]) -> Tuple[str, float, Any]:
+        """Return (key, now, stored_data) — shared prelude for status/wait methods."""
+        key = self.get_key(identifier)
+        return key, time.time(), self._get_from_backend(key)
+
+    def _get_from_backend(self, key: str) -> Optional[Any]:
+        """Fetch the stored value for key from the active backend."""
+        if self.backend == "memory":
+            with self._lock:
+                return self._memory_storage.get(key)
+        data = self._redis.get(key)
+        return json.loads(data) if data else None
+
+    def _set_to_backend(self, key: str, value: Any, ttl: Optional[int] = None) -> None:
+        """Persist value for key in the active backend."""
+        if self.backend == "memory":
+            with self._lock:
+                self._memory_storage[key] = value
+        else:
+            self._redis.set(key, json.dumps(value))
+            if ttl:
+                self._redis.expire(key, int(ttl))
+
+    def _delete_from_backend(self, key: str) -> None:
+        """Delete key from the active backend."""
+        if self.backend == "memory":
+            with self._lock:
+                self._memory_storage.pop(key, None)
+        else:
+            self._redis.delete(key)
+
+    @abstractmethod
+    def allow_request(self, identifier: Optional[str] = None) -> bool:
+        """Return True if the request is allowed, False if the limit is exceeded."""
+
+    def reset(self, identifier: Optional[str] = None) -> None:
+        """Reset rate limit counters for the given identifier."""
+        self._delete_from_backend(self.get_key(identifier))
+
+    def get_wait_time(self, _identifier: Optional[str] = None) -> float:
+        """Return seconds until the next request is allowed (0 if allowed now)."""
+        return 0.0
+
+    def get_usage(self, identifier: Optional[str] = None) -> Dict[str, Any]:
+        """Return usage in a consistent format: count, limit, remaining, limited."""
+        status = self.get_status(identifier)
+        count: int = status["count"]
+        available: int = status["available"]
+        return {
+            "count": count,
+            "limit": self.capacity,
+            "remaining": available,
+            "limited": count >= self.capacity,
+        }
+
+    def get_status(self, _identifier: Optional[str] = None) -> Dict[str, Any]:
+        """Return algorithm-specific status for the given identifier."""
+        return {"count": 0, "capacity": self.capacity, "available": self.capacity}
+
+    def get_config(self) -> Dict[str, Any]:
+        """Return a dictionary of the limiter's configuration."""
+        return {
+            "capacity": self.capacity,
+            "fill_rate": self.fill_rate,
+            "scope": self.scope,
+            "backend": self.backend,
+            "project": self.project,
+            "prefix": self.prefix,
+            "suffix": self.suffix,
+        }

limitra/exceptions.py

@@ -0,0 +1,15 @@
+"""Exceptions raised by limitra rate limiters."""
+
+
+class RateLimitExceeded(Exception):
+    """Raised when a rate limit is exceeded and no on_exceeded handler is set."""
+
+    def __init__(self, requests: int, window: float, retry_after: float = 0.0):
+        self.requests = requests
+        self.window = window
+        self.retry_after = retry_after
+        self.remaining = 0
+        msg = f"Rate limit exceeded: {requests} requests per {window}s"
+        if retry_after:
+            msg += f". Retry after {retry_after:.2f}s"
+        super().__init__(msg)

limitra-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,18 @@
+limitra/__init__.py,sha256=mJGJ9QJ4fpX6JEwKCRkC1Eml6iVp3SNSczIr15rTg1E,633
+limitra/_config.py,sha256=3fCeOU16Ao1dAF3Dj1Qk4Als4l7d36vIFkcGkjGz8xY,2944
+limitra/_decorator.py,sha256=-Ox-JsU15Jh3vFPaEGwx6H4bg72S_eIYnzjcLdT3Da4,11373
+limitra/_version.py,sha256=8OsTLsIVB9D0HdPTmt5rVwyVUBe9xTVGkRslXicxzkM,520
+limitra/base.py,sha256=NUsw2URLlnufU-W5HJ5J-FB29cwimuDK1gOfD6hnw1I,5639
+limitra/exceptions.py,sha256=Fkyc04Nm7WbntyOSVc8tmXWSJpceKOkl0oO-fMeyh5k,560
+limitra/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+limitra/algorithms/__init__.py,sha256=zH1c2Q0ywECpYh9tcIa875Kk22WLbWl_CQkMP6YwlsM,619
+limitra/algorithms/fixed_window.py,sha256=EoliEXOmpdE8OtsBdUPk60cijYsEuSS0SyO0oYFjV4M,4625
+limitra/algorithms/leaky_bucket.py,sha256=xJ8-7qbXpHM4IKYDhmiilyzSxDfJpG8Dxi_xAvkCvBM,4809
+limitra/algorithms/sliding_window.py,sha256=U94yEHXj_tw4XShU8soKBX91ttzA7r2ulSZ1WqGFeT8,4938
+limitra/algorithms/token_bucket.py,sha256=O2rt5HygMUAwmAzMwhwJ18fLVg2n7ZIvFNOMRJfsqzo,4761
+limitra/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+limitra-0.0.1.dist-info/licenses/LICENSE,sha256=oK6JyCyjjebB4Mvy4PFdOfY8x50ilr07XzC0Wg2AH9I,1067
+limitra-0.0.1.dist-info/METADATA,sha256=LE71rhL21YWGzMqaKhAQtm7PENjDEbmHWPxYrJ1uWII,2419
+limitra-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+limitra-0.0.1.dist-info/top_level.txt,sha256=QmzUUCVtKj3s7E3wmm72Ms5B9TGTFJ5XH9-vBGvi5QM,8
+limitra-0.0.1.dist-info/RECORD,,

limitra-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

limitra-0.0.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+limitra