Elegant HTTP Caching for Python
Hishel (հիշել, to remember in Armenian) is a modern HTTP caching library for Python that implements RFC 9111 specifications. It provides seamless caching integration for popular HTTP clients with minimal code changes.
- 🎯 RFC 9111 Compliant - Fully compliant with the latest HTTP caching specification
- 🔌 Easy Integration - Drop-in support for HTTPX, Requests, ASGI, FastAPI, and BlackSheep
- 💾 Flexible Storage - SQLite backend with more coming soon
- ⚡ High Performance - Efficient caching with minimal overhead
- 🔄 Async & Sync - Full support for both synchronous and asynchronous workflows
- 🎨 Type Safe - Fully typed with comprehensive type hints
- 🧪 Well Tested - Extensive test coverage and battle-tested
- 🎛️ Configurable - Fine-grained control over caching behavior with flexible policies
- 💨 Memory Efficient - Streaming support prevents loading large payloads into memory
- 🌐 Universal - Works with any ASGI application (Starlette, Litestar, BlackSheep, etc.)
- 🎯 GraphQL Support - Cache GraphQL queries with body-sensitive content caching
pip install hishelInstall with specific integration support:
pip install hishel[httpx] # For HTTPX support
pip install hishel[requests] # For Requests support
pip install hishel[fastapi] # For FastAPI support (includes ASGI)Or install multiple:
pip install hishel[httpx,requests,fastapi]Note
ASGI middleware has no extra dependencies - it's included in the base installation.
Synchronous:
from hishel.httpx import SyncCacheClient
client = SyncCacheClient()
# First request - fetches from origin
response = client.get("https://api.example.com/data")
print(response.extensions["hishel_from_cache"]) # False
# Second request - served from cache
response = client.get("https://api.example.com/data")
print(response.extensions["hishel_from_cache"]) # TrueAsynchronous:
from hishel.httpx import AsyncCacheClient
async with AsyncCacheClient() as client:
# First request - fetches from origin
response = await client.get("https://api.example.com/data")
print(response.extensions["hishel_from_cache"]) # False
# Second request - served from cache
response = await client.get("https://api.example.com/data")
print(response.extensions["hishel_from_cache"]) # Trueimport requests
from hishel.requests import CacheAdapter
session = requests.Session()
session.mount("https://", CacheAdapter())
session.mount("http://", CacheAdapter())
# First request - fetches from origin
response = session.get("https://api.example.com/data")
# Second request - served from cache
response = session.get("https://api.example.com/data")
print(response.headers.get("X-Hishel-From-Cache")) # "True"Add caching middleware to any ASGI application:
from hishel.asgi import ASGICacheMiddleware
# Wrap your ASGI app
app = ASGICacheMiddleware(app)
# Or configure with options
from hishel import AsyncSqliteStorage, CacheOptions, SpecificationPolicy
app = ASGICacheMiddleware(
app,
storage=AsyncSqliteStorage(),
policy=SpecificationPolicy(
cache_options=CacheOptions(shared=True)
),
)Add Cache-Control headers using the cache() dependency:
from fastapi import FastAPI
from hishel.fastapi import cache
app = FastAPI()
@app.get("/api/data", dependencies=[cache(max_age=300, public=True)])
async def get_data():
# Cache-Control: public, max-age=300
return {"data": "cached for 5 minutes"}
# Optionally wrap with ASGI middleware for local caching according to specified rules
from hishel.asgi import ASGICacheMiddleware
from hishel import AsyncSqliteStorage
app = ASGICacheMiddleware(app, storage=AsyncSqliteStorage())Use BlackSheep's native cache_control decorator with Hishel's ASGI middleware:
from blacksheep import Application, get
from blacksheep.server.headers.cache import cache_control
app = Application()
@get("/api/data")
@cache_control(max_age=300, public=True)
async def get_data():
# Cache-Control: public, max-age=300
return {"data": "cached for 5 minutes"}Hishel supports two types of caching policies:
SpecificationPolicy - RFC 9111 compliant HTTP caching (default):
from hishel import CacheOptions, SpecificationPolicy
from hishel.httpx import SyncCacheClient
client = SyncCacheClient(
policy=SpecificationPolicy(
cache_options=CacheOptions(
shared=False, # Use as private cache (browser-like)
supported_methods=["GET", "HEAD", "POST"], # Cache GET, HEAD, and POST
allow_stale=True # Allow serving stale responses
)
)
)FilterPolicy - Custom filtering logic for fine-grained control:
from hishel import FilterPolicy, BaseFilter, Request
from hishel.httpx import AsyncCacheClient
class CacheOnlyAPIRequests(BaseFilter[Request]):
def needs_body(self) -> bool:
return False
def apply(self, item: Request, body: bytes | None) -> bool:
return "/api/" in str(item.url)
client = AsyncCacheClient(
policy=FilterPolicy(
request_filters=[CacheOnlyAPIRequests()]
)
)from hishel import SyncSqliteStorage
from hishel.httpx import SyncCacheClient
storage = SyncSqliteStorage(
database_path="my_cache.db",
default_ttl=7200.0, # Cache entries expire after 2 hours
refresh_ttl_on_access=True # Reset TTL when accessing cached entries
)
client = SyncCacheClient(storage=storage)Cache GraphQL queries and other POST requests by including the request body in the cache key.
Using per-request header:
from hishel import FilterPolicy
from hishel.httpx import SyncCacheClient
client = SyncCacheClient(
policy=FilterPolicy()
)
# Cache GraphQL queries - different queries get different cache entries
graphql_query = """
query GetUser($id: ID!) {
user(id: $id) {
name
email
}
}
"""
response = client.post(
"https://api.example.com/graphql",
json={"query": graphql_query, "variables": {"id": "123"}},
headers={"X-Hishel-Body-Key": "true"} # Enable body-based caching
)
# Different query will be cached separately
response = client.post(
"https://api.example.com/graphql",
json={"query": graphql_query, "variables": {"id": "456"}},
headers={"X-Hishel-Body-Key": "true"}
)Using global configuration:
from hishel.httpx import SyncCacheClient
from hishel import FilterPolicy
# Enable body-based caching for all requests
client = SyncCacheClient(policy=FilterPolicy(use_body_key=True))
# All POST requests automatically include body in cache key
response = client.post(
"https://api.example.com/graphql",
json={"query": graphql_query, "variables": {"id": "123"}}
)Hishel uses a sans-I/O state machine architecture that separates HTTP caching logic from I/O operations:
- ✅ Correct - Fully RFC 9111 compliant
- ✅ Testable - Easy to test without network dependencies
- ✅ Flexible - Works with any HTTP client or server
- ✅ Type Safe - Clear state transitions with full type hints
We're actively working on:
- 🎯 Performance optimizations
- 🎯 More integrations
- 🎯 Partial responses support
Comprehensive documentation is available at https://hishel.com/dev
- Getting Started
- HTTPX Integration
- Requests Integration
- ASGI Integration
- FastAPI Integration
- BlackSheep Integration
- GraphQL Integration
- Storage Backends
- Request/Response Metadata
- RFC 9111 Specification
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
See our Contributing Guide for more details.
This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.
If you find Hishel useful, please consider:
- ⭐ Starring the repository
- 🐛 Reporting bugs and issues
- 💡 Suggesting new features
- 📖 Improving documentation
- ☕ Buying me a coffee
Hishel is inspired by and builds upon the excellent work in the Python HTTP ecosystem, particularly:
- HTTPX - A next-generation HTTP client for Python
- Requests - The classic HTTP library for Python
- RFC 9111 - HTTP Caching specification
Made with ❤️ by Kar Petrosyan
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
