or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cache-clients.mdcache-controller.mdcache-transports.mdhttp-headers.mdindex.mdserializers.mdstorage-backends.mdtesting-utilities.md
tile.json

tessl/pypi-hishel

Persistent cache implementation for httpx and httpcore following RFC 9111 specification

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/hishel@0.1.x

To install, run

npx @tessl/cli install tessl/pypi-hishel@0.1.0

index.mddocs/

Hishel

An elegant HTTP caching library that implements RFC 9111 caching specification for HTTPX and HTTP Core libraries. Hishel provides persistent memory caching with smart cache management, understanding HTTP headers like Vary, Etag, Last-Modified, Cache-Control, and Expires for automatic response re-validation.

Package Information

  • Package Name: hishel
  • Language: Python
  • Installation: pip install hishel
  • Requirements: Python >= 3.9, httpx >= 0.28.0

Core Imports

import hishel

For direct access to main components:

from hishel import CacheClient, AsyncCacheClient, Controller, FileStorage

Basic Usage

Drop-in Replacement for HTTPX

import hishel

# Replace httpx.Client with hishel.CacheClient
with hishel.CacheClient() as client:
    response = client.get("https://httpbin.org/get")
    print(response.status_code)  # 200, fetched from server
    
    # Second request is served from cache
    response = client.get("https://httpbin.org/get") 
    print(response.status_code)  # 200, served from cache

# Async version
import asyncio

async def main():
    async with hishel.AsyncCacheClient() as client:
        response = await client.get("https://httpbin.org/get")
        print(response.status_code)

asyncio.run(main())

Global Installation

import hishel
import httpx

# Monkey-patch httpx to use caching globally
hishel.install_cache()

# Now all httpx clients automatically use caching
with httpx.Client() as client:
    response = client.get("https://httpbin.org/get")

Architecture

Hishel follows a modular architecture with four main components:

  • Cache Clients: Drop-in replacements for httpx.Client and httpx.AsyncClient
  • Cache Transports: HTTPX transport layer with caching logic
  • Storage Backends: Pluggable storage implementations (File, Redis, SQLite, S3, In-Memory)
  • Cache Controller: RFC 9111 compliant caching logic and validation

This design provides complete compatibility with existing HTTPX workflows while adding transparent HTTP caching capabilities.

Capabilities

HTTP Cache Clients

Drop-in replacements for httpx.Client and httpx.AsyncClient that provide transparent HTTP caching with configurable storage backends and caching policies.

class CacheClient(httpx.Client):
    def __init__(self, *, storage=None, controller=None, **kwargs): ...

class AsyncCacheClient(httpx.AsyncClient):
    def __init__(self, *, storage=None, controller=None, **kwargs): ...

HTTP Cache Clients

Storage Backends

Pluggable storage implementations for persisting cached HTTP responses across various backends including file system, Redis, SQLite, AWS S3, and in-memory storage.

class FileStorage(BaseStorage):
    def __init__(self, *, serializer=None, base_path=None, ttl=None, check_ttl_every=60): ...

class AsyncFileStorage(AsyncBaseStorage):
    def __init__(self, *, serializer=None, base_path=None, ttl=None, check_ttl_every=60): ...

Storage Backends

Cache Controller

RFC 9111 compliant cache controller that determines cacheability, validates cached responses, and handles cache directives from HTTP headers.

class Controller:
    def __init__(self, *, cacheable_methods=None, cacheable_status_codes=None, 
                 cache_private=True, allow_heuristics=False, clock=None, 
                 allow_stale=False, always_revalidate=False, force_cache=False, 
                 key_generator=None): ...
    
    def is_cachable(self, request: Request, response: Response) -> bool: ...
    def construct_response_from_cache(self, request: Request, response: Response, 
                                    original_request: Request): ...

Cache Controller

Serializers

Serialization formats for persisting HTTP request/response pairs including Pickle, JSON, and YAML serializers with metadata support.

class PickleSerializer(BaseSerializer):
    def dumps(self, response: Response, request: Request, metadata: Metadata) -> bytes: ...
    def loads(self, data: bytes) -> tuple[Response, Request, Metadata]: ...

class JSONSerializer(BaseSerializer):
    def dumps(self, response: Response, request: Request, metadata: Metadata) -> str: ...
    def loads(self, data: str) -> tuple[Response, Request, Metadata]: ...

Serializers

Cache Transports

HTTPX transport implementations that add caching layer on top of existing transports, handling cache lookups, storage, and validation.

class CacheTransport(httpx.BaseTransport):
    def __init__(self, *, transport: httpx.BaseTransport, storage=None, controller=None): ...

class AsyncCacheTransport(httpx.AsyncBaseTransport):
    def __init__(self, *, transport: httpx.AsyncBaseTransport, storage=None, controller=None): ...

Cache Transports

HTTP Headers

Cache-Control and Vary header parsing and representation with RFC 9111 compliant validation and directive handling.

class CacheControl:
    def __init__(self, *, immutable=False, max_age=None, max_stale=None, 
                 min_fresh=None, must_revalidate=False, must_understand=False,
                 no_cache=False, no_store=False, no_transform=False, 
                 only_if_cached=False, private=False, proxy_revalidate=False,
                 public=False, s_maxage=None): ...

def parse_cache_control(cache_control_values: list[str]) -> CacheControl: ...

HTTP Headers

Utilities

Testing utilities including mock connection pools and transports for unit testing cached HTTP interactions.

class MockTransport(httpx.BaseTransport):
    def add_responses(self, responses: list[httpx.Response]) -> None: ...

class MockAsyncTransport(httpx.AsyncBaseTransport):
    def add_responses(self, responses: list[httpx.Response]) -> None: ...

Testing Utilities

Global Functions

def install_cache() -> None:
    """Monkey-patch httpx to use Hishel caching globally"""

Utility Classes

class LFUCache:
    def __init__(self, capacity: int): ...
    def get(self, key) -> Any: ...
    def put(self, key, value) -> None: ...
    def remove_key(self, key) -> None: ...

Least Frequently Used cache implementation for internal use and advanced caching scenarios.

Exception Handling

class CacheControlError(Exception): ...
class ParseError(CacheControlError): ...
class ValidationError(CacheControlError): ...