Hishel

Common errors

• ModuleNotFoundError: No module named 'hishel._serializers'

  cause This error typically occurs when there's a version mismatch between `hishel` and a dependent library, or when upgrading `hishel` to a major version (like 1.0.0) that changed internal module structure, while the application or another dependency expects an older structure.
  fix Ensure `hishel` and any libraries using it are compatible. If using `hishel==1.0.0` or newer, and a dependent library expects an older version, try pinning `hishel` to the version specified by the dependent library (e.g., `pip install hishel==0.1.3`). If possible, update the dependent library to a version compatible with the latest `hishel`.

• ModuleNotFoundError: No module named 'hishel'

  cause This error means the `hishel` package is not installed in the Python environment being used, or the environment is not correctly configured for the Python interpreter.
  fix Install the `hishel` library using pip: `pip install hishel`. If using specific integrations, install with extras, e.g., `pip install hishel[httpx]` or `pip install hishel[requests]`.

• ImportError: cannot import name 'SyncCacheClient' from 'hishel'

  cause The caching client classes for specific HTTP libraries (like HTTPX or Requests) are located in submodules, not directly under the top-level `hishel` package.
  fix Import `SyncCacheClient` (or `AsyncCacheClient`, `CacheClient`, `CacheAdapter`) from their respective integration submodules. For HTTPX, use `from hishel.httpx import SyncCacheClient`. For Requests, use `from hishel.requests import CacheAdapter`.

• ModuleNotFoundError: No module named 'httpx'

  cause This error occurs when trying to use `hishel`'s HTTPX integration (e.g., `SyncCacheClient` or `AsyncCacheClient`) without having the `httpx` library installed as a dependency.
  fix Install `httpx` explicitly or install `hishel` with the `httpx` extra: `pip install httpx` or `pip install hishel[httpx]`.

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()