Rate Keeper

中文 | English

Rate Keeper: Used to limit function call frequency. It ensures your function is called evenly within the limit rather than being called intensively in a short time. Moreover, it can dynamically adjust the call frequency based on remaining calls and time.

Installation

pip install rate-keeper

Quick Start

from rate_keeper import RateKeeper

if __name__ == "__main__":
    rate_keeper = RateKeeper(limit=3, period=1)

    @rate_keeper.decorator
    def request(url: str) -> str:
        print(f"Requesting {url}, {rate_keeper}, {rate_keeper.recommend_delay:.2f}")

    count = 0
    while count < 6:
        request(f"https://www.example.com/{count}")
        count += 1

# Output:
# Requesting https://www.example.com/0, RateKeeper(limit=3, period=1, used=1, reset=55981.89), 0.50
# Requesting https://www.example.com/1, RateKeeper(limit=3, period=1, used=2, reset=55981.89), 0.50
# Requesting https://www.example.com/2, RateKeeper(limit=3, period=1, used=1, reset=55982.89), 0.50
# Requesting https://www.example.com/3, RateKeeper(limit=3, period=1, used=2, reset=55982.89), 0.50
# Requesting https://www.example.com/4, RateKeeper(limit=3, period=1, used=1, reset=55983.906), 0.50
# Requesting https://www.example.com/5, RateKeeper(limit=3, period=1, used=2, reset=55983.906), 0.50

Dynamic Adjust

from typing import Dict
import requests
from requests import Response
from datetime import datetime, timezone
from rate_keeper import RateKeeper

timestamp_clock = datetime.now(timezone.utc).timestamp
rate_keeper = RateKeeper(limit=5000, period=3600, clock=timestamp_clock)


@rate_keeper.decorator
def fetch(
    method: str, url: str, headers: Dict[str, str] = {}, params: Dict[str, str] = {}
) -> Response:
    # https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api#checking-the-status-of-your-rate-limit
    response = requests.request(method, url, headers=headers, params=params)

    headers_map = {
        "x-ratelimit-limit": rate_keeper.update_limit,
        "x-ratelimit-used": rate_keeper.update_used,
        "x-ratelimit-reset": rate_keeper.update_reset,
    }

    for key, value in response.headers.items():
        lower_key = key.lower()
        if lower_key in headers_map:
            headers_map[lower_key](int(value))

    return response


def create_headers(token: str) -> Dict[str, str]:
    return {
        "Accept": "application/vnd.github.v3+json",
        "User-Agent": "Follower Bot",
        "Authorization": f"token {token}",
    }


print(rate_keeper)
response = fetch("GET", "https://api.github.com/user", create_headers("github_token"))
print(response.json())
print(rate_keeper)

# Output:
# RateKeeper(limit=5000, period=3600, used=0, reset=1745863571.523727)
# {'message': 'Bad credentials', 'documentation_url': 'https://docs.github.com/rest', 'status': '401'}
# RateKeeper(limit=60, period=3600, used=7, reset=1745862671)