Description
<p align="center"> <img alt="Hishel Logo" width="350" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_yellow.png#gh-dark-mode-only"> </p> <h1 align="center">Hishel</h1> <p align="center"> <strong>Elegant HTTP Caching for Python</strong> </p> <p align="center"> <a href="https://pypi.org/project/hishel"> <img src="https://img.shields.io/pypi/v/hishel.svg" alt="PyPI version"> </a> <a href="https://pypi.org/project/hishel"> <img src="https://img.shields.io/pypi/pyversions/hishel.svg" alt="Python versions"> </a> <a href="https://github.com/karpetrosyan/hishel/blob/master/LICENSE"> <img src="https://img.shields.io/pypi/l/hishel" alt="License"> </a> <a href="https://coveralls.io/github/karpetrosyan/hishel"> <img src="https://img.shields.io/coverallsCoverage/github/karpetrosyan/hishel" alt="Coverage"> </a> <a href="https://static.pepy.tech/badge/hishel/month"> <img src="https://static.pepy.tech/badge/hishel/month" alt="Downloads"> </a> </p> --- **Hishel** (ีฐีซีทีฅีฌ, *to remember* in Armenian) is a modern HTTP caching library for Python that implements [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111.html) 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, 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 Documentation is available at: [https://hishel.com](https://hishel.com)## What's Changed in 1.1.10 ### โ๏ธ Miscellaneous Tasks * fix non-existing rfc reference by @karpetrosyan ### ๐ Bug Fixes * don't discard no-cache and vary-mismatched entries by @karpetrosyan * fix: properly save per-request hishel_ttl setting by @LiteralGenie in [#445](https://github.com/karpetrosyan/hishel/pull/445) ### ๐ Documentation * document storages by @karpetrosyan * move docs to vitepress by @karpetrosyan ### Contributors * @karpetrosyan * @LiteralGenie **Full Changelog**: https://github.com/karpetrosyan/hishel/compare/1.1.9...1.1.10 ## What's Changed in 1.1.9 ### โ๏ธ Miscellaneous Tasks * chore: drop python 3.9 support by @CharString in [#418](https://github.com/karpetrosyan/hishel/pull/418) ### ๐ฆ Dependencies * chore(deps-dev): bump the python-packages group across 1 directory with 5 updates by @dependabot[bot] in [#440](https://github.com/karpetrosyan/hishel/pull/440) ### Contributors * @karpetrosyan * @CharString * @dependabot[bot] **Full Changelog**: https://github.com/karpetrosyan/hishel/compare/1.1.8...1.1.9 ## What's Changed in 1.1.8 ### โ๏ธ Miscellaneous Tasks * chore(ci): remove redis action by @karpetrosyan in [#428](https://github.com/karpetrosyan/hishel/pull/428) ### ๐ Bug Fixes * fix: prevent race conditions by @karpetrosyan in [#436](https://github.com/karpetrosyan/hishel/pull/436) ### Contributors * @karpetrosyan **Full Changelog**: https://github.com/karpetrosyan/hishel/compare/1.1.7...1.1.8 ## What's Changed in 1.1.7 ### โป๏ธ Refactoring * refactor(storage): create sqlite database path only when creating connections by @jeefberkey in [#426](https://github.com/karpetrosyan/hishel/pull/426) ### โ๏ธ Miscellaneous Tasks * chore(deps-dev): bump the python-packages group with 5 updates by @dependabot[bot] in [#424](https://github.com/karpetrosyan/hishel/pull/424) ### ๐ Bug Fixes * fix(cache): Lambda parameter name clashes the loop variable being closed over by @dump247 in [#427](https://github.com/karpetrosyan/hishel/pull/427) ### ๐ Documentation * add release process guidelines for maintainers by @karpetrosyan ### ๐ Features * Feature/accept pathlib path in SqliteStorage by @daudef in [#419](https://github.com/karpetrosyan/hishel/pull/419) ### Contributors * @karpetrosyan * @daudef * @dependabot[bot] * @jeefberkey * @dump247 **Full Changelog**: https://github.com/karpetrosyan/hishel/compare/1.1.6...1.1.7 ## What's Changed in 1.1.6 ### ๐ Documentation * remove some stale httpx configs by @karpetrosyan ### ๐ Features * Add support for request no-cache directive by @karpetrosyan in [#416](https://github.com/karpetrosyan/hishel/pull/416) ### Contributors * @karpetrosyan **Full Changelog**: https://github.
Release History
| Version | Changes | Urgency | Date |
|---|---|---|---|
| 1.1.10 | Imported from PyPI (1.1.10) | Low | 4/21/2026 |
| 1.1.9 | ## What's Changed in 1.1.9 ### โ๏ธ Miscellaneous Tasks * chore: drop python 3.9 support by @CharString in [#418](https://github.com/karpetrosyan/hishel/pull/418) ### ๐ฆ Dependencies * chore(deps-dev): bump the python-packages group across 1 directory with 5 updates by @dependabot[bot] in [#440](https://github.com/karpetrosyan/hishel/pull/440) ### Contributors * @karpetrosyan * @CharString * @dependabot[bot] **Full Changelog**: https://github.com/karpetrosyan/hishel/compare/1.1.8...1.1.9 | Low | 2/5/2026 |
| 1.1.8 | ## What's Changed in 1.1.8 ### โ๏ธ Miscellaneous Tasks * chore(ci): remove redis action by @karpetrosyan in [#428](https://github.com/karpetrosyan/hishel/pull/428) ### ๐ Bug Fixes * fix: prevent race conditions by @karpetrosyan in [#436](https://github.com/karpetrosyan/hishel/pull/436) ### Contributors * @karpetrosyan **Full Changelog**: https://github.com/karpetrosyan/hishel/compare/1.1.7...1.1.8 | Low | 1/11/2026 |
| 1.1.7 | ## What's Changed in 1.1.7 ### โป๏ธ Refactoring * refactor(storage): create sqlite database path only when creating connections by @jeefberkey in [#426](https://github.com/karpetrosyan/hishel/pull/426) ### โ๏ธ Miscellaneous Tasks * chore(deps-dev): bump the python-packages group with 5 updates by @dependabot[bot] in [#424](https://github.com/karpetrosyan/hishel/pull/424) ### ๐ Bug Fixes * fix(cache): Lambda parameter name clashes the loop variable being closed over by @dump247 in [#427](https:/ | Low | 12/3/2025 |
| 1.1.6 | ## What's Changed in 1.1.6 ### ๐ Documentation * remove some stale httpx configs by @karpetrosyan ### ๐ Features * Add support for request no-cache directive by @karpetrosyan in [#416](https://github.com/karpetrosyan/hishel/pull/416) ### Contributors * @karpetrosyan **Full Changelog**: https://github.com/karpetrosyan/hishel/compare/1.1.5...1.1.6 | Low | 11/17/2025 |
| 1.1.5 | ## What's Changed in 1.1.5 ### ๐ Bug Fixes * filter out soft-deleted, expired and incomplete entries in `get_entries` by @karpetrosyan ### Contributors * @karpetrosyan **Full Changelog**: https://github.com/karpetrosyan/hishel/compare/1.1.4...1.1.5 | Low | 11/8/2025 |
| 1.1.4 | ## What's Changed in 1.1.4 ### ๐ Bug Fixes * don't raise an error on consumed streams that were read into memory by @karpetrosyan * close sqlite connections properly by @karpetrosyan ### Contributors * @karpetrosyan **Full Changelog**: https://github.com/karpetrosyan/hishel/compare/1.1.3...1.1.4 | Low | 11/6/2025 |
| 1.1.3 | ## What's Changed in 1.1.3 ### โ๏ธ Miscellaneous Tasks * improve git-cliff docs by @karpetrosyan ### ๐ Bug Fixes * fix: add BaseFilter to __all__ exports by @martinblech in [#408](https://github.com/karpetrosyan/hishel/pull/408) * fix: set `after_revalidation=True` for `NeedsToBeUpdated` -> `FromCache` transition by @jlopex in [#402](https://github.com/karpetrosyan/hishel/pull/402) **Full Changelog**: https://github.com/karpetrosyan/hishel/compare/1.1.2...1.1.3 | Low | 11/6/2025 |
| 1.1.2 | ## What's Changed in 1.1.2 * fix: respect shared option when excluding unstorable headers by @jlopex in [#401](https://github.com/karpetrosyan/hishel/pull/401) * fix: remove s-maxage consideration for private caches by @jlopex in [#400](https://github.com/karpetrosyan/hishel/pull/400) * fix: ensure 304 responses don't leak by @karpetrosyan ### New Contributors * @jlopex made their first contribution in [#401](https://github.com/karpetrosyan/hishel/pull/401) **Full Changelog**: https:// | Low | 11/3/2025 |
| 1.1.1 | # Changelog All notable changes to this project will be documented in this file. ## 1.1.1 - 2025-11-01 ### โ๏ธ Miscellaneous Tasks - Bump the python-packages group with 10 updates (#396) ### ๐ฆ Dependencies - Bump actions/upload-artifact from 4 to 5 (#395) - Bump actions/download-artifact from 4 to 6 (#394) - Bump astral-sh/setup-uv from 5 to 7 (#393) | Low | 11/1/2025 |
| 1.1.0 | # Changelog All notable changes to this project will be documented in this file. ## 1.1.0 - 2025-10-31 ### โ๏ธ Miscellaneous Tasks - Add in memory example ### ๐ Bug Fixes - Pass any response with non-expected status code on revalidation to client ### ๐ Features - Allow setting storage `base` via `database_path` for sqlite storage | Low | 10/31/2025 |
| 1.0.0 | # Changelog All notable changes to this project will be documented in this file. ## 1.0.0 - 2025-10-28 ### โ๏ธ Miscellaneous Tasks - Add examples, improve docs | Low | 10/28/2025 |
| 1.0.0b1 | # Changelog All notable changes to this project will be documented in this file. ## 1.0.0b1 - 2025-10-28 ### โป๏ธ Refactoring - Add policies ### โ๏ธ Miscellaneous Tasks - Improve sans-io diagram colors - Add graphql docs ### ๐ Bug Fixes - Body-sensitive responses caching - Filter out `Transfer-Encoding` header for asgi responses ### ๐ Features - Add global `use_body_key` setting | Low | 10/28/2025 |
| 1.0.0.dev3 | # Changelog All notable changes to this project will be documented in this file. ## 1.0.0.dev3 - 2025-10-26 ### โป๏ธ Refactoring - Replace pairs with entries, simplify storage API - Automatically generate httpx sync integration from async ### โ๏ธ Miscellaneous Tasks - Simplify metadata docs - Add custom integrations docs - More robust compressed response caching ### ๐ Bug Fixes - Add missing permissions into `publish.yml` - Raise on consumed httpx streams, which we can't store as is (it's alre | Low | 10/26/2025 |
| 1.0.0.dev2 | # Changelog All notable changes to this project will be documented in this file. ## 1.0.0.dev2 - 2025-10-21 ### โ๏ธ Miscellaneous Tasks - Remove redundant utils and tests - Add import without extras check in ci - Fix time travel date, explicitly specify the timezone ### ๐ Bug Fixes - Fix check for storing auth requests - Don't raise an error on 3xx during revalidation ### ๐ Features - Add hishel_created_at response metadata | Low | 10/21/2025 |
| 1.0.0.dev1 | # Changelog All notable changes to this project will be documented in this file. ## 1.0.0.dev1 - 2025-10-21 ### โ๏ธ Miscellaneous Tasks - Remove some redundant utils methods ### ๐ฆ Dependencies - Make httpx and async libs optional dependencies - Make `anysqlite` optional dependency - Install async extra with httpx - Improve git-cliff | Low | 10/21/2025 |
| 1.0.0.dev0 | ## [1.0.0.dev0] - 2025-10-19 ### โ๏ธ Miscellaneous Tasks - *(docs)* Use mike powered versioning - *(docs)* Improve docs versioning, deploy dev doc on ci | Low | 10/19/2025 |
| 0.1.5 | ## [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 | Low | 10/18/2025 |
| 0.1.4 | ## [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 ### ๐ Bug Fixes - Create an sqlite file in a cache folder - Fix beta imports ### โ๏ธ Miscellaneous Tasks - Improve CI (#369) - *(internal | Low | 10/14/2025 |
| 0.1.3 | # Changelog ## 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) | Low | 7/6/2025 |
| 0.1.2 | ## 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) | Low | 4/4/2025 |
| 0.1.1 | # Changelog ## 0.1.1 (2nd Nov, 2024) - FIx typig extensions nor found. (#290) | Low | 11/2/2024 |
| 0.1.0 | # Changelog ## 0.1.0 (2nd Nov, 2024) - Add support for Python 3.12 / drop Python 3.8. (#286) - Specify usedforsecurity=False in blake2b. (#285) ## Contributors [<img src="https://wsrv.nl/?url=github.com/mturiansky.png?w=64&h=64&mask=circle&fit=cover&maxage=1w" width="32" height="32" alt="mturiansky" />](https://github.com/mturiansky) [<img src="https://wsrv.nl/?url=github.com/Secrus.png?w=64&h=64&mask=circle&fit=cover&maxage=1w" width="32" height="32" alt="Secrus" />](https://github | Low | 11/2/2024 |
| 0.0.33 | # Changelog ## 0.0.33 (4th Oct, 2024) - Added a [Logging](https://hishel.com/advanced/logging/) section to the documentation. | Low | 10/4/2024 |
| 0.0.32 | # Changelog ## 0.0.32 (27th Sep, 2024) - Don't raise an exception if the `Date` header is not present. (#273) | Low | 10/2/2024 |
| 0.0.31 | # Changelog ## 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) ## Contributors [<img src="https://wsrv.nl/?url=github.com/daudef.png?w=64&h=64&mask=circle&fit=cover&maxage=1w" width="32" height="32" alt="daudef" />](https://github.com/daudef) [<img src="https://wsrv.nl/?url=github.com/yazmolod.png?w=64&h=64&ma | Low | 9/22/2024 |
| 0.0.30 | # Changelog ## 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 | Low | 7/12/2024 |
| 0.0.29 | # Changelog ## 0.0.29 (23th June, 2024) - Add `revalidated` response extension. (#242) | Low | 6/23/2024 |
| 0.0.27 | # Changelog ## 0.0.27 (31th May, 2024) - Fix `RedisStorage` when using without ttl. (#231) | Low | 5/31/2024 |
| 0.0.26 | # Changelog ## 0.0.26 (12th April, 2024) - Expose `AsyncBaseStorage` and `BaseStorage`. (#220) - Prevent cache hits from resetting the ttl. (#215) | Low | 4/12/2024 |
| 0.0.25 | # Changelog ## 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) | Low | 3/26/2024 |
| 0.0.24 | # Changelog (hotfix release) ## 0.0.24 (14th February, 2024) - Fix `botocore is not installed` exception when using any kind of storage. (#186) | Low | 2/14/2024 |
| 0.0.23 | # Changelog ## 0.0.23 (12th February, 2024) - Support caching for `POST` and other HTTP methods. (#183) - 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) | Low | 2/14/2024 |
| 0.0.22 | # Changelog ## 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) | Low | 1/31/2024 |
| 0.0.21 | # Changelog ## 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) | Low | 12/29/2023 |
| 0.0.20 | # Changelog ## 0.0.20 (12/12/2023) - Add in-memory storage. (#133) - Allow customization of cache key generation. (#130) | Low | 12/12/2023 |
| 0.0.19 | # Changelog ## 0.0.19 (30/11/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) | Low | 11/30/2023 |
| 0.0.18 | # Changelog ## 0.0.18 (23/11/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) | Low | 11/23/2023 |
| 0.0.17 | # Changelog ## 0.0.17 (6/11/2023) - Fix `Last-Modified` validation. | Low | 11/6/2023 |
| 0.0.16 | # Changelog ## 0.0.16 (25/10/2023) - Add `install_cache` function. (#95) - Add sqlite support. (#92) - Move `ttl` argument to `BaseStorage` class. (#94) | Low | 10/25/2023 |
| 0.0.14 | # Changelog ## 0.0.14 (23/10/2023) - Replace `AsyncResponseStream` with `AsyncCacheStream`. (#86) - Add `must-understand` response directive support. (#90) | Low | 10/23/2023 |
| 0.0.13 | # Changelog ## 0.0.13 (10/5/2023) - Add support for Python 3.12. (#71) - Fix connections releasing from the connection pool. (#83) | Low | 10/5/2023 |
| 0.0.12 | # Changelog ## 0.0.12 (8/9/2023) - Add metadata into the response extensions. (#56) | Low | 9/8/2023 |
| 0.0.11 | ## 0.0.11 (8/15/2023) - Add support for request `cache-control` directives. (#42) - Drop httpcore dependencie. (#40) - Support HTTP methods only if they are defined as cacheable. (#37) | Low | 8/15/2023 |
| 0.0.10 | # Changelog ## 0.0.10 (8/7/2023) - Add Response metadata. (#33) - Add API Reference documentation. (#30) - Use stale responses only if the client is disconnected. (#28) | Low | 8/7/2023 |
| 0.0.9 | # Changelog ## 0.0.9 (8/1/2023) - Expose Controller API. (#23) | Low | 8/1/2023 |
| 0.0.8 | # Changelog ## 0.0.8 (7/31/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) | Low | 7/31/2023 |
| 0.0.7 | # Changelog ## 0.0.7 (7/30/2023) - Add support for `Heuristic Freshness`. (#11) - Change `Controller.cache_heuristically` to `Controller.allow_heuristics`. (#12) - Handle import errors. (#13) | Low | 7/30/2023 |
| 0.0.6 | # Changelog ## 0.0.6 (7/29/2023) - Fix `Vary` header validation. (#8) - Dump original requests with the responses (#7) | Low | 7/29/2023 |
| 0.0.5 | # Changelog ## 0.0.5 (7/29/2023) - Fix httpx response streaming. | Low | 7/29/2023 |