tessl/pypi-hishel

Persistent cache implementation for httpx and httpcore following RFC 9111 specification

1.48x

Overview

Eval results

Files

HTTP Cache Clients

Name: tessl/pypi-hishel
Rating: 0.74 (1 reviews)
Author: tessl

Drop-in replacements for httpx.Client and httpx.AsyncClient that provide transparent HTTP caching. These clients automatically cache responses according to HTTP caching rules and serve cached responses for subsequent requests.

Capabilities

Synchronous Cache Client

A synchronous HTTP client with built-in caching capabilities, fully compatible with httpx.Client.

class CacheClient(httpx.Client):
    def __init__(self, *, storage=None, controller=None, **kwargs):
        """
        Initialize a synchronous HTTP client with caching.
        
        Parameters:
        - storage: Storage backend for cached responses (defaults to FileStorage)
        - controller: Cache controller for caching logic (defaults to Controller())
        - **kwargs: All httpx.Client parameters (timeout, headers, auth, etc.)
        """

Usage Examples:

import hishel

# Basic usage with default file storage
with hishel.CacheClient() as client:
    response = client.get("https://api.example.com/data")

# Custom storage backend
storage = hishel.RedisStorage()
with hishel.CacheClient(storage=storage) as client:
    response = client.get("https://api.example.com/data")

# Custom cache controller
controller = hishel.Controller(
    cacheable_methods=["GET", "POST"],
    cacheable_status_codes=[200, 204, 301]
)
with hishel.CacheClient(controller=controller) as client:
    response = client.get("https://api.example.com/data")

# All httpx.Client parameters work
with hishel.CacheClient(
    timeout=30.0,
    headers={'User-Agent': 'MyApp/1.0'},
    auth=('username', 'password')
) as client:
    response = client.get("https://api.example.com/data")

Asynchronous Cache Client

An asynchronous HTTP client with built-in caching capabilities, fully compatible with httpx.AsyncClient.

class AsyncCacheClient(httpx.AsyncClient):
    def __init__(self, *, storage=None, controller=None, **kwargs):
        """
        Initialize an asynchronous HTTP client with caching.
        
        Parameters:
        - storage: Async storage backend for cached responses (defaults to AsyncFileStorage)
        - controller: Cache controller for caching logic (defaults to Controller())
        - **kwargs: All httpx.AsyncClient parameters (timeout, headers, auth, etc.)
        """

Usage Examples:

import hishel
import asyncio

async def main():
    # Basic usage with default async file storage
    async with hishel.AsyncCacheClient() as client:
        response = await client.get("https://api.example.com/data")
        
    # Custom async storage backend
    storage = hishel.AsyncRedisStorage()
    async with hishel.AsyncCacheClient(storage=storage) as client:
        response = await client.get("https://api.example.com/data")
        
    # Custom cache controller with async client
    controller = hishel.Controller(allow_heuristics=True)
    async with hishel.AsyncCacheClient(controller=controller) as client:
        response = await client.get("https://api.example.com/data")

asyncio.run(main())

Request-Level Cache Control

Both clients support per-request cache control through request extensions:

# Force cache usage for a specific request
response = client.get("https://api.example.com/data", 
                     extensions={"force_cache": True})

# Disable cache for a specific request  
response = client.get("https://api.example.com/data",
                     extensions={"force_cache": False})

Integration with HTTPX Features

Cache clients fully support all HTTPX features:

Authentication: All auth methods work with caching
Timeouts: Request and connection timeouts are preserved
Headers: Custom headers are included in cache key generation
Cookies: Cookie handling works with cached responses
Redirects: Redirect handling is cache-aware
Streaming: Streaming responses can be cached
HTTP/2: HTTP/2 connections work with caching
Proxies: Proxy support is maintained with caching

Cache Behavior

Automatic: Caching happens transparently according to HTTP headers
RFC 9111 Compliant: Follows HTTP caching specification
Smart Validation: Automatic revalidation using ETags and Last-Modified
Vary Support: Handles Vary headers for content negotiation
Private/Public: Respects Cache-Control private/public directives
TTL Support: Storage-level TTL for cache expiration

Install with Tessl CLI

npx tessl i tessl/pypi-hishel