@rate_limit(calls=5, period=10) def api_call(): pass

Decorators & Metaclasses

Meaning

Applies a rate limiter to a function, allowing at most N calls within a given time period. This prevents excessive calls to APIs or resources and helps avoid HTTP 429 errors.

Primary Function

Rate limiting / Throttling

Communicative Purpose

Prevents excessive calls to an API or resource by enforcing a call quota.

Pattern

@rate_limit(calls=limit, period=seconds) def func(): pass

Core Structure

@rate_limit(calls=..., period=...) def ...():

Função primária

Rate limiting / Throttling

Propósito comunicativo

Prevents excessive calls to an API or resource by enforcing a call quota.

Situações de gatilho

Calling external APIs with usage limits; protecting internal services from overload; implementing retry‑safe clients.

Contextos

Python web services, data pipelines, SDKs, any code that interacts with rate‑limited APIs.

Padrão

@rate_limit(calls=limit, period=seconds) def func(): pass

Estrutura central

@rate_limit(calls=..., period=...) def ...():

Slots de substituição

limit: int (max calls allowed), seconds: int/float (time period in seconds), func: identifier (function name)

Colocados típicos

time.sleep
retry decorators
circuit breaker
async functions

Substituições comuns

Token bucket algorithm
leaky bucket
limits library
tenacity's wait_fixed

Erros comuns

Setting period too short causing throttling; forgetting to apply decorator to async functions; misinterpreting calls as per‑second vs per‑period.

Similar / contraste

@retry (retries on failure) vs @rate_limit (limits frequency); @timeout (limits execution duration).

Interferências

Coming from Java: may expect synchronized blocks for rate limiting → Python uses decorator syntax to wrap individual functions. Coming from Go: may look for middleware-based rate limiting → Python decorators apply per-function rate limits.

Família do chunk

rate limiting
retry
circuit breaker
backoff

Nuance

Does not guarantee exact spacing; works best with synchronous calls; for async use an async‑compatible decorator; may accumulate calls across threads unless thread‑safe.

Efeito pragmático

Prevents hitting API rate limits, reducing HTTP 429 errors and avoiding bans.

Dica de memória

Like a bouncer at a club door—only lets N people in every T seconds, making the rest wait outside.

Nota

Ensure thread‑safety when used across threads; for async functions use an async‑compatible rate limiter (e.g., limits with sleep_and_retry).

Upgrade path

Combine with @retry and @circuit_breaker for resilient service calls.

Frequência: MediumFormulaicidade: Semi-fixedTipo de construção: decorator syntaxPrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

from ratelimit import limits, sleep_and_retry import requests @sleep_and_retry @limits(calls=5, period=10) def fetch_user_data(user_id): resp = requests.get(f'https://api.example.com/users/{user_id}') resp.raise_for_status() return resp.json()

from ratelimit import limits class GitHubClient: @limits(calls=10, period=10) def get_repo(self, owner, repo): return requests.get(f'https://api.github.com/repos/{owner}/{repo}').json()

from ratelimit import limits, sleep_and_retry import asyncio, aiohttp @sleep_and_retry @limits(calls=5, period=10) async def async_fetch(session, url): async with session.get(url) as resp: resp.raise_for_status() return await resp.json() async def main(): async with aiohttp.ClientSession() as session: data = await async_fetch(session, 'https://api.example.com/data') print(data) asyncio.run(main())