hishel 0.1.4

Persistent cache implementation for httpx and httpcore

Hishel - An elegant HTTP Cache implementation for httpx and httpcore.

---

Hishel (հիշել, remember) is a library that implements HTTP Caching for HTTPX and HTTP Core libraries in accordance with RFC 9111, the most recent caching specification.

Features

• 💾 Persistence: Responses are cached in the persistent memory for later use.
• 🤲 Compatibility: It is completely compatible with your existing transports or connection pools, whether they are default, custom, or provided by third-party libraries.
• 🤗 Easy to use: You continue to use httpx while also enabling web cache.
• 🧠 Smart: Attempts to clearly implement RFC 9111, understands Vary, Etag, Last-Modified, Cache-Control, and Expires headers, and handles response re-validation automatically.
• ⚙️ Configurable: You have complete control over how the responses are stored and serialized.
• 📦 From the package:
  • Built-in support for File system, Redis, SQLite, and AWS S3 backends.
  • Built-in support for JSON, YAML, and pickle serializers.
• 🚀 Very fast: Your requests will be even faster if there are no IO operations.

Documentation

Go through the Hishel documentation.

QuickStart

Install Hishel using pip:

$ pip install hishel

Let's begin with an example of a httpx client.

import hishel

with hishel.CacheClient() as client:
    client.get("https://hishel.com")  # 0.4749558370003797s
    client.get("https://hishel.com")  # 0.002873589000046195s (~250x faster!)

or in asynchronous context

import hishel

async with hishel.AsyncCacheClient() as client:
    await client.get("https://hishel.com")
    await client.get("https://hishel.com")  # takes from the cache

Configurations

Configure when and how you want to store your responses.

import hishel

# All the specification configs
controller = hishel.Controller(
        # Cache only GET and POST methods
        cacheable_methods=["GET", "POST"],

        # Cache only 200 status codes
        cacheable_status_codes=[200],

        # Use the stale response if there is a connection issue and the new response cannot be obtained.
        allow_stale=True,

        # First, revalidate the response and then utilize it.
        # If the response has not changed, do not download the
        # entire response data from the server; instead,
        # use the one you have because you know it has not been modified.
        always_revalidate=True,
)

# All the storage configs
storage = hishel.S3Storage(
        bucket_name="my_bucket_name", # store my cache files in the `my_bucket_name` bucket
        ttl=3600, # delete the response if it is in the cache for more than an hour
)
client = hishel.CacheClient(controller=controller, storage=storage)


# Ignore the fact that the server does not recommend you cache this request!
client.post(
        "https://example.com",
        extensions={"force_cache": True}
)


# Return a regular response if it is in the cache; else, return a 504 status code. DO NOT SEND A REQUEST!
client.post(
        "https://example.com",
        headers=[("Cache-Control", "only-if-cached")]
)


# Ignore cached responses and do not store incoming responses!
response = client.post(
        "https://example.com",
        extensions={"cache_disabled": True}
)

How and where are the responses saved?

The responses are stored by Hishel in storages. You have complete control over them; you can change storage or even write your own if necessary.

Support the project

You can support the project by simply leaving a GitHub star ⭐ or by contributing. Help us grow and continue developing good software for you ❤️

[0.1.4] - 2025-10-14

🚀 Features

• Add support for requests library
• Add support for Python 3.14
• 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
• Added Metadata to public API. (#363)
• Fix race condition in FileStorage initialization. (#353)

🐛 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 (1st July, 2025)

• Remove types-redis from dev dependencies (#336)
• Bump redis to 6.0.0 and address async .close() deprecation warning (#336)
• Avoid race condition when unlinking files in FileStorage. (#334)
• Allow prodiving a path_prefix in S3Storage and AsyncS3Storage. (#342)

0.1.2 (5th April, 2025)

• Add check for fips compliant python. (#325)
• Fix compatibility with httpx. (#291)
• Use SyncByteStream instead of ByteStream. (#298)
• Don't raise exceptions if date-containing headers are invalid. (#318)
• Fix for S3 Storage missing metadata in API request. (#320)

0.1.1 (2nd Nov, 2024)

• Fix typing extensions not found. (#290)

0.1.0 (2nd Nov, 2024)

• Add support for Python 3.12 / drop Python 3.8. (#286)
• Specify usedforsecurity=False in blake2b. (#285)

0.0.33 (4th Oct, 2024)

• Added a Logging section to the documentation.

0.0.32 (27th Sep, 2024)

• Don't raise an exception if the Date header is not present. (#273)

0.0.31 (22nd Sep, 2024)

• Ignore file not found error when cleaning up a file storage. (#264)
• Fix AssertionError on client.close() when use SQLiteStorage. (#269)
• Fix ignored flags when use force_cache. (#271)

0.0.30 (12th July, 2024)

• Fix cache update on revalidation response with content (rfc9111 section 4.3.3) (#239)
• Fix request extensions that were not passed into revalidation request for transport-based implementation (but were passed for the pool-based impl) (#247).
• Add cache_private property to the controller to support acting as shared cache. (#224)
• Improve efficiency of scanning cached responses in FileStorage by reducing number of syscalls. (#252)
• Add remove support for storages (#241)

0.0.29 (23th June, 2024)

• Documentation hotfix. (#244)

0.0.28 (23th June, 2024)

• Add revalidated response extension. (#242)

0.0.27 (31th May, 2024)

• Fix RedisStorage when using without ttl. (#231)

0.0.26 (12th April, 2024)

• Expose AsyncBaseStorage and BaseStorage. (#220)
• Prevent cache hits from resetting the ttl. (#215)

0.0.25 (26th March, 2024)

• Add force_cache property to the controller, allowing RFC9111 rules to be completely disabled. (#204)
• Add .gitignore to cache directory created by FIleStorage. (#197)
• Remove stale_* headers from the CacheControl class. (#199)

0.0.24 (14th February, 2024)

• Fix botocore is not installed exception when using any kind of storage. (#186)

0.0.23 (14th February, 2024)

• Make S3Storage to check staleness of all cache files with set interval. (#182)
• Fix an issue where an empty file in FileCache could cause a parsing error. (#181)
• Support caching for POST and other HTTP methods. (#183)

0.0.22 (31th January, 2024)

• Make FileStorage to check staleness of all cache files with set interval. (#169)
• Support AWS S3 storages. (#164)
• Move typing_extensions from requirements.txt to pyproject.toml. (#161)

0.0.21 (29th December, 2023)

• Fix inner transport and connection pool instances closing. (#147)
• Improved error message when the storage type is incorrect. (#138)

0.0.20 (12th December, 2023)

• Add in-memory storage. (#133)
• Allow customization of cache key generation. (#130)

0.0.19 (30th November, 2023)

• Add force_cache extension to enforce the request to be cached, ignoring the HTTP headers. (#117)
• Fix issue where sqlite storage cache get deleted immediately. (#119)
• Support float numbers for storage ttl. (#107)

0.0.18 (23rd November, 2023)

• Fix issue where freshness cannot be calculated to re-send request. (#104)
• Add cache_disabled extension to temporarily disable the cache (#109)
• Update datetime.datetime.utcnow() to datetime.datetime.now(datetime.timezone.utc) since datetime.datetime.utcnow() has been deprecated. (#111)

0.0.17 (6th November, 2023)

• Fix Last-Modified validation.

0.0.16 (25th October, 2023)

• Add install_cache function. (#95)
• Add sqlite support. (#92)
• Move ttl argument to BaseStorage class. (#94)

0.0.14 (23rd October, 2023)

• Replace AsyncResponseStream with AsyncCacheStream. (#86)
• Add must-understand response directive support. (#90)

0.0.13 (5th October, 2023)

• Add support for Python 3.12. (#71)
• Fix connections releasing from the connection pool. (#83)

0.0.12 (8th September, 2023)

• Add metadata into the response extensions. (#56)

0.0.11 (15th August, 2023)

• Add support for request cache-control directives. (#42)
• Drop httpcore dependency. (#40)
• Support HTTP methods only if they are defined as cacheable. (#37)

0.0.10 (7th August, 2023)

• Add Response metadata. (#33)
• Add API Reference documentation. (#30)
• Use stale responses only if the client is disconnected. (#28)

0.0.9 (1st August, 2023)

• Expose Controller API. (#23)

0.0.8 (31st July, 2023)

• Skip redis tests if the server was not found. (#16)
• Decrease sleep time for the storage ttl tests. (#18)
• Fail coverage under 100. (#19)

0.0.7 (30th July, 2023)

• Add support for Heuristic Freshness. (#11)
• Change Controller.cache_heuristically to Controller.allow_heuristics. (#12)
• Handle import errors. (#13)

0.0.6 (29th July, 2023)

• Fix Vary header validation. (#8)
• Dump original requests with the responses. (#7)

0.0.5 (29th July, 2023)

• Fix httpx response streaming.

0.0.4 (29th July, 2023)

• Change YamlSerializer name to YAMLSerializer.

0.0.3 (28th July, 2023)

• Add from_cache response extension.
• Add typing_extensions into the requirements.

0.0.2 (25th July, 2023)

• Add redis support.
• Make backends thread and task safe.
• Add black as a new linter.
• Add an expire time for cached responses.