{"id":7292,"library":"httpxthrottlecache","title":"HTTPX Throttle Cache Client","description":"httpxthrottlecache is a Python library that provides an HTTPX client with integrated rate limiting and caching capabilities. It abstracts away complex configurations for managing network requests, improving performance and adhering to API limits. The library is actively maintained, currently at version 0.3.5, and releases frequently to add features and address issues.","status":"active","version":"0.3.5","language":"en","source_language":"en","source_url":"https://github.com/paultiq/httpxthrottlecache","tags":["httpx","caching","rate-limiting","http-client","async","sync"],"install":[{"cmd":"pip install httpxthrottlecache","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core HTTP client library that httpxthrottlecache extends.","package":"httpx"},{"reason":"Provides the underlying rate-limiting functionality.","package":"pyrate-limiter","optional":false},{"reason":"Optional dependency required for 'Hishel-File' or 'Hishel-S3' cache modes. It is no longer the default caching backend since v0.3.0.","package":"hishel","optional":true}],"imports":[{"symbol":"HttpxThrottleCache","correct":"from httpxthrottlecache import HttpxThrottleCache"}],"quickstart":{"code":"import os\nfrom httpxthrottlecache import HttpxThrottleCache\n\n# Example usage with a dummy URL and basic configuration\n# For real usage, replace 'https://api.example.com' and 'your_user_agent'\nurl = \"https://httpbingo.org/get\"\n\nwith HttpxThrottleCache(\n    cache_mode=\"FileCache\", # Use 'FileCache' or 'Hishel-File' (if hishel is installed)\n    cache_dir=\"_my_cache\",\n    rate_limiter_enabled=True,\n    request_per_sec_limit=5,\n    user_agent=os.environ.get('MY_APP_USER_AGENT', 'httpxthrottlecache-example/1.0'),\n    # Example cache_rules to cache all paths for an hour\n    cache_rules={\n        '.*': {\n            '.*': 3600 # Cache all responses for 3600 seconds (1 hour)\n        }\n    }\n) as manager:\n    with manager.http_client() as client:\n        response = client.get(url)\n        print(f\"Status Code: {response.status_code}\")\n        print(f\"Response headers: {response.headers}\")\n        # Uncomment to see response body:\n        # print(response.json())\n","lang":"python","description":"Initializes the HttpxThrottleCache client with file-based caching and rate limiting. It demonstrates a synchronous GET request to an example URL, printing the status code and headers. Users can configure cache mode, directory, rate limits, user agent, and specific caching rules using regular expressions. The client can be used as a context manager to ensure proper resource handling."},"warnings":[{"fix":"For `hishel` caching, ensure `pip install hishel` and initialize `HttpxThrottleCache(cache_mode=\"Hishel-File\", ...)`. Otherwise, update your code to account for `FileCache` behavior or explicitly choose a different `cache_mode`.","message":"The default caching backend changed in v0.3.0. Previously, `hishel` was the default, but it was removed as a default due to breaking API changes. The new default is `FileCache`. If your application relied on `hishel` being the default, you must explicitly set `cache_mode=\"Hishel-File\"` and ensure `hishel` is installed.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Ensure your `pyrate-limiter` installation is version 4.x or higher when using `httpxthrottlecache>=0.3.5`. If you need to maintain an older `pyrate-limiter` version, consider pinning `httpxthrottlecache<0.3.5`.","message":"Version 0.3.5 bumps the internal `pyrate-limiter` dependency to 4.x. If you are also directly using `pyrate-limiter` in your project and have an older version installed, you might encounter compatibility issues. Older versions of `pyrate-limiter` are likely incompatible with `httpxthrottlecache>=0.3.5`.","severity":"breaking","affected_versions":">=0.3.5"},{"fix":"Implement your own cache cleanup strategy (e.g., a scheduled job to clear old files from the `cache_dir`) if using `FileCache` and needing to manage disk space.","message":"The `FileCache` implementation does not perform any automatic cache cleanup. Cached files will persist on disk indefinitely unless manually removed by the user.","severity":"gotcha","affected_versions":"All versions using `FileCache`"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the optional `hishel` dependency: `pip install hishel`.","cause":"Attempting to use `cache_mode='Hishel-File'` or `cache_mode='Hishel-S3'` without installing the `hishel` library.","error":"ModuleNotFoundError: No module named 'hishel'"},{"fix":"This is expected behavior for rate limiting. To mitigate, decrease the request rate, increase `request_per_sec_limit`, or implement retry logic with backoff in your application.","cause":"The rate limiter has prevented a request because it would exceed the configured `request_per_sec_limit` or `burst_limit`.","error":"pyrate_limiter.exceptions.BucketFullException: Too many requests for bucket 'default'"},{"fix":"Check the `httpxthrottlecache` documentation or `httpx` documentation for the correct way to enable HTTP/2 if needed. In `httpx`, HTTP/2 support is typically enabled by installing `httpx[http2]` and configuring the client with `http2=True` or `http1=False, http2=True` if supported by `httpxthrottlecache`'s current API. Ensure you've installed `httpx[http2]` if you intend to use HTTP/2.","cause":"Passing an `http2` argument directly to `HttpxThrottleCache` or its `http_client()` method in a way that is not supported by the underlying `httpx` version or `httpxthrottlecache` wrapper.","error":"TypeError: __init__ got an unexpected keyword argument 'http2'"}]}