Hishel HTTP Caching

Hishel provides a pure-Python, RFC 9111-compliant state machine for HTTP caching. Instead of managing cache logic manually, you interact with a state machine that dictates the next required action, the inputs needed for state transitions, and the meaning of the current state.

To use the state machine, you must follow these rules:

1. Initialization: Start by creating an IdleClient state. Do not manually instantiate other states.
2. Transitions: Use the .next() method on the current state to transition to the next state. The .next() method is fully typed and returns a new state object.
3. State-Specific Logic: Each state (e.g., CacheMiss, FromCache, NeedRevalidation) has its own properties and a .next() method signature tailored to the specific inputs required for that stage of the HTTP lifecycle.

from hishel import IdleClient, Request

# 1. Initialize the state machine
state = IdleClient()

# 2. Transition to the next state using .next()
request = Request(url="https://example.com")
next_state = state.next(request, associated_entries=[])

# next_state will now be a specific state type like CacheMiss, 
# FromCache, or NeedRevalidation

Hishel uses an unasync strategy to provide both async and sync APIs without duplicating code.

The Workflow

1. Write async code once: All shared functionality is written in async files (e.g., hishel/_core/_storages/_async_*.py or tests/_core/_async/*.py).
2. Automatic transformation: The scripts/unasync script transforms the async code into synchronous versions (e.g., hishel/_core/_storages/_sync_*.py).

Critical Rules

• ✅ DO: Write and edit async files only (_async_*.py).
• ✅ DO: Run ./scripts/fix before committing to ensure sync files are updated.
• ❌ DON'T: Manually edit synchronous files (_sync_*.py).
• ❌ DON'T: Commit async changes without running unasync.
• ❌ DON'T: Modify sync test files directly.

# Async code (you write this)
async def store(self, key: str) -> None:
    async with self.connection as conn:
        await conn.execute(...)

# Sync code (automatically generated)
def store(self, key: str) -> None:
    with self.connection as conn:
        conn.execute(...)

Hishel provides read-only metadata on responses to inspect cache operations. These fields are prefixed with hishel_.

Available Response Metadata

• hishel_from_cache (bool | None): True if the response was served from cache; False if fetched from the origin server.
• hishel_revalidated (bool | None): True if a stale cached response was revalidated with the origin server (e.g., resulting in a 304 Not Modified).
• hishel_stored (bool | None): True if the response was successfully saved to the cache. False if it was not cacheable (e.g., due to Cache-Control: no-store).
• hishel_created_at (float | None): A POSIX timestamp indicating when the response entry was created in the cache.

Accessing Metadata

For HTTPX: Access via response.extensions.get("field_name").

For Requests: Access via response.headers.get("X-Hishel-Field-Name") (note the header mapping).

from hishel.httpx import SyncCacheClient

client = SyncCacheClient()
response = client.get("https://api.example.com/data")

if response.extensions.get("hishel_from_cache"):
    print("✓ Cache hit")

if response.extensions.get("hishel_revalidated"):
    print("Response was revalidated (304 Not Modified)")

if response.extensions.get("hishel_stored"):
    print("✓ Response stored in cache")

created = response.extensions.get("hishel_created_at")
if created:
    print("Cached at:", created)

You can control how Hishel caches requests by setting specific metadata. All metadata fields are prefixed with hishel_ to avoid collisions.

Available Request Metadata

• hishel_ttl (float | None): Sets a custom time-to-live (TTL) in seconds for the cached response. Overrides the storage's default_ttl.
• hishel_refresh_ttl_on_access (bool | None): If True, accessing a cached entry resets its TTL (sliding expiration). If False, the TTL countdown is fixed from the original storage time.
• hishel_body_key (bool | None): If True, includes the request body in the cache key generation. This is essential for caching POST requests or GraphQL queries where the same URL might have different payloads.

How to set metadata

For HTTPX:

• Use the extensions parameter in your request (recommended).
• Or use X-Hishel-* headers.

For Requests:

• Use X-Hishel-* headers.

from hishel.httpx import SyncCacheClient

client = SyncCacheClient()

response = client.get(
    "https://api.example.com/data",
    extensions={"hishel_ttl": 3600, "hishel_refresh_ttl_on_access": True, "hishel_body_key": True}
)

Hishel policies can be applied across different HTTP clients and frameworks:

HTTPX (Async)

import httpx
from hishel import AsyncCacheClient, SpecificationPolicy, CacheOptions

policy = SpecificationPolicy(cache_options=CacheOptions(shared=False))
async with AsyncCacheClient(policy=policy) as client:
    response = await client.get("https://api.example.com/data")

HTTPX (Sync)

import httpx
from hishel import SyncCacheClient, SpecificationPolicy, CacheOptions

policy = SpecificationPolicy(cache_options=CacheOptions(shared=True))
with SyncCacheClient(policy=policy) as client:
    response = client.get("https://api.example.com/data")

Requests

import requests
from hishel.requests import CacheAdapter
from hishel import SpecificationPolicy, CacheOptions

policy = SpecificationPolicy(cache_options=CacheOptions(shared=False))
session = requests.Session()
session.mount("https://", CacheAdapter(policy=policy))
session.mount("http://", CacheAdapter(policy=policy))

response = session.get("https://api.example.com/data")

ASGI Middleware

from hishel.asgi import ASGICacheMiddleware
from hishel import SpecificationPolicy, CacheOptions

policy = SpecificationPolicy(cache_options=CacheOptions(shared=True))
app = ASGICacheMiddleware(app=your_asgi_app, policy=policy)