hishel 1.0.0.dev0

Elegant HTTP Caching for Python

Hishel

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.

✨ Features

• 🎯 RFC 9111 Compliant - Fully compliant with the latest HTTP caching specification
• 🔌 Easy Integration - Drop-in support for HTTPX and Requests
• 💾 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
• 🌐 Future Ready - Designed for easy integration with any HTTP client/server

📦 Installation

pip install hishel

Optional Dependencies

Install with specific HTTP client support:

pip install hishel[httpx]      # For HTTPX support
pip install hishel[requests]   # For Requests support

Or install both:

pip install hishel[httpx,requests]

🚀 Quick Start

With HTTPX

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"])  # True

Asynchronous:

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"])  # True

With Requests

import 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"

🎛️ Advanced Configuration

Custom Cache Options

from hishel import CacheOptions
from hishel.httpx import SyncCacheClient

client = SyncCacheClient(
    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
    )
)

Custom Storage Backend

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)

🏗️ Architecture

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

🔮 Roadmap

While Hishel currently supports HTTPX and Requests, we're actively working on:

• 🎯 Additional HTTP client integrations
• 🎯 Server-side caching support
• 🎯 More storage backends
• 🎯 Advanced caching strategies
• 🎯 Performance optimizations

📚 Documentation

Comprehensive documentation is available at https://hishel.com/dev

• Getting Started
• HTTPX Integration
• Requests Integration
• Storage Backends
• RFC 9111 Specification

🤝 Contributing

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.

📄 License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

💖 Support

If you find Hishel useful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs and issues
• 💡 Suggesting new features
• 📖 Improving documentation
• ☕ Buying me a coffee

🙏 Acknowledgments

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

[1.0.0dev0] - 2025-10-19

⚙️ Miscellaneous Tasks

• (docs) Use mike powered versioning
• (docs) Improve docs versioning, deploy dev doc on ci

[0.1.5] - 2025-10-18

🚀 Features

• (perf) Set chunk size to 128KB for httpx to reduce SQLite read/writes
• Better cache-control parsing
• Add close method to storages API (#384)
• (perf) Increase requests buffer size to 128KB, disable charset detection

🐛 Bug Fixes

• (docs) Fix some line breaks

⚙️ Miscellaneous Tasks

• Remove some redundant files from repo

[0.1.4] - 2025-10-14

🚀 Features

• Add support for a sans-IO API (#366)
• Allow already consumed streams with CacheTransport (#377)
• Add sqlite storage for beta storages
• Get rid of some locks from sqlite storage
• Better async implemetation for sqlite storage

🐛 Bug Fixes

• Create an sqlite file in a cache folder
• Fix beta imports

⚙️ Miscellaneous Tasks

• Improve CI (#369)
• (internal) Remove src folder (#373)
• (internal) Temporary remove python3.14 from CI
• (tests) Add sqlite tests for new storage
• (tests) Move some tests to beta

[0.1.3] - 2025-07-06

🚀 Features

• Support providing a path prefix to S3 storage (#342)

📚 Documentation

• Update link to httpx transports page (#337)

[0.1.2] - 2025-04-04

🐛 Bug Fixes

• Requirements.txt to reduce vulnerabilities (#263)

[0.0.30] - 2024-07-12

🐛 Bug Fixes

• Requirements.txt to reduce vulnerabilities (#245)
• Requirements.txt to reduce vulnerabilities (#255)

[0.0.27] - 2024-05-31

🐛 Bug Fixes

• (redis) Do not update metadata with negative ttl (#231)

[0.0.1] - 2023-07-22