Halt — Python SDK

SaaS-aware, cross-language rate limiting. Per-user / per-API-key / per-plan limits, quotas, weighted endpoints, abuse controls, atomic Redis accuracy (sync + async), and built-in observability — with a matching TypeScript package.

📖 Full documentation: halt.afroawi.com

Install

pip install halt-rate
# optional extras
pip install "halt-rate[redis]"    # production store (sync + async)
pip install "halt-rate[fastapi]"  # framework adapter
pip install "halt-rate[otel]"     # OpenTelemetry metrics

Installs as halt-rate; import as halt.

Quick start

from halt import RateLimiter, InMemoryStore, presets

limiter = RateLimiter(
    store=InMemoryStore(),      # use RedisStore in production
    policy=presets.PUBLIC_API,  # 100 req/min per IP
)

decision = limiter.check(request)   # or: await limiter.acheck(request)
if not decision.allowed:
    # respond 429, Retry-After: decision.retry_after
    ...

Production Redis (sync + async), FastAPI/Flask/Django adapters, plan-based limits, quotas, penalties, and observability are covered in the docs → halt.afroawi.com/docs.

Resilience

Rate limiting sits in the critical path of every request, so a Redis outage or latency spike must not take down your service. Choose what happens when Redis is unavailable:

import redis
from halt import RateLimiter, RedisStore, presets

store = RedisStore(
    client=redis.Redis.from_url(REDIS_URL, socket_timeout=0.2),  # surface slow Redis as errors
    fail_mode="fallback",  # "open" (default) | "closed" | "fallback"
    # circuit breaker on by default: after 5 failures, skip Redis for 5s (prevents cascades)
)

• open (default) — allow the request; don't take traffic down.
• closed — block (429); safest for abuse-sensitive routes.
• fallback — evaluate against a local in-memory store (LocalStore), so limits are still enforced (per-instance, approximate) instead of blanket allow. Works with AsyncRedisStore too.
• Circuit breaker (on by default) stops hammering a down Redis and serves from the fallback until it recovers. Set the client's socket_timeout so latency spikes trip it.

Features

• Algorithms: token bucket, fixed/sliding window, leaky bucket
• Keys: IP, user, API key, composite, or custom
• Atomic Redis store (Lua, cluster-safe), sync and async, + in-memory dev store
• Resilient: configurable fail-open / fail-closed / local-fallback + built-in circuit breaker
• SaaS: per-plan limits, quotas, weighted endpoints, abuse penalties
• Observability: StatsCollector + OpenTelemetry metrics
• Adapters: FastAPI, Flask, Django

Links

• Docs: https://halt.afroawi.com
• PyPI: https://pypi.org/project/halt-rate/
• Source & issues: https://github.com/surafel-kindu/halt

License

MIT