Hishel

1.1.9 · active · verified Thu Apr 09

Hishel is an elegant HTTP caching library for Python, implementing RFC 9111 specifications to provide seamless caching integration for popular HTTP clients like HTTPX and Requests. It offers flexible storage backends, including SQLite, and supports both synchronous and asynchronous workflows with a focus on high performance and type safety. The library is actively maintained with frequent minor releases, ensuring ongoing compatibility and feature enhancements.

Warnings

breaking Hishel 1.1.9 officially dropped support for Python 3.9. Users on Python 3.9 or older must use an earlier version of Hishel.
Fix: Upgrade to Python 3.10 or newer, or pin Hishel to `<1.1.9`.
gotcha The `hishel.install_cache` function is intended for experimental use only and is not recommended for production environments.
Fix: For reliable caching, use `hishel.CacheClient`, `hishel.AsyncCacheClient`, or `hishel.CacheTransport` directly with your HTTP client.
gotcha For stream-based responses to be properly stored in Hishel storages, you must consume (iterate through) the response stream. Simply creating an entry with a stream does not store its data.
Fix: Always iterate over the response stream (e.g., `for chunk in response.iter_bytes(): pass`) to ensure its content is saved to the cache.
gotcha Hishel's `CacheClient` and `AsyncCacheClient` classes hide the constructor signature of the underlying `httpx` client. This means IDEs might not suggest arguments that are still valid for configuration.
Fix: Refer to the `httpx` documentation for available client arguments, as they are compatible with Hishel's cache clients.
gotcha Earlier versions (before 1.1.8) had potential race conditions in storage operations.
Fix: Upgrade to Hishel 1.1.8 or newer to benefit from race condition fixes.
gotcha Python's mutable default arguments (e.g., lists, dicts) are evaluated only once when the function is defined. Using them as defaults for `FilterPolicy` or other configurable components can lead to unintended shared state across calls.
Fix: Always use `None` as a default for mutable arguments and initialize them inside the function if `None` is passed (e.g., `if filters is None: filters = []`).

Install

pip install hishel Base installation
pip install hishel[httpx] For HTTPX integration
pip install hishel[requests] For Requests integration
pip install hishel[fastapi] For FastAPI/ASGI integration

Imports

CacheClient
```
from hishel import CacheClient
```
Generic synchronous cache client. For HTTPX, prefer hishel.httpx.SyncCacheClient.
AsyncCacheClient
```
from hishel import AsyncCacheClient
```
Generic asynchronous cache client. For HTTPX, prefer hishel.httpx.AsyncCacheClient.
SyncCacheClient
```
from hishel.httpx import SyncCacheClient
```
Recommended synchronous cache client for HTTPX.
AsyncCacheClient
```
from hishel.httpx import AsyncCacheClient
```
Recommended asynchronous cache client for HTTPX.
CacheTransport
```
from hishel import CacheTransport
```
For integrating caching with an existing HTTPX Transport.
SyncSqliteStorage
```
from hishel import SyncSqliteStorage
```
Synchronous SQLite storage backend.
AsyncSqliteStorage
```
from hishel import AsyncSqliteStorage
```
Asynchronous SQLite storage backend.
BaseFilter
```
from hishel import BaseFilter
```
Base class for creating custom cache filters, exposed since 1.1.3.

Quickstart

This quickstart demonstrates using Hishel's `SyncCacheClient` with HTTPX for both in-memory (default) and file-based (SQLite) caching. The first request fetches data from the origin, while subsequent requests for the same URL will be served from the cache, if applicable according to HTTP caching rules.

import hishel
import httpx

def main():
    # Use SyncCacheClient for synchronous HTTPX requests
    with hishel.httpx.SyncCacheClient() as client:
        print("First request (from origin):")
        response1 = client.get("https://httpbin.org/get")
        print(f"Status: {response1.status_code}, From cache: {response1.extensions.get('hishel_from_cache', False)}")

        print("\nSecond request (from cache if cachable):")
        response2 = client.get("https://httpbin.org/get")
        print(f"Status: {response2.status_code}, From cache: {response2.extensions.get('hishel_from_cache', False)}")

    # Example with explicit SQLite storage
    # Ensure 'my_cache.db' is created in a writable directory
    storage = hishel.SyncSqliteStorage(database_path="./my_cache.db")
    with hishel.httpx.SyncCacheClient(storage=storage) as client:
        print("\nFirst request with SQLite storage (from origin):")
        response3 = client.get("https://httpbin.org/get?item=1")
        print(f"Status: {response3.status_code}, From cache: {response3.extensions.get('hishel_from_cache', False)}")

        print("\nSecond request with SQLite storage (from cache):")
        response4 = client.get("https://httpbin.org/get?item=1")
        print(f"Status: {response4.status_code}, From cache: {response4.extensions.get('hishel_from_cache', False)}")

if __name__ == "__main__":
    main()

view raw JSON →