{"author":null,"author_email":"Kar Petrosyan ","bugtrack_url":null,"classifiers":["Development Status :: 3 - Alpha","Environment :: Web Environment","Framework :: AsyncIO","Framework :: Trio","Intended Audience :: Developers","License :: OSI Approved :: BSD License","Operating System :: OS Independent","Programming Language :: Python :: 3","Programming Language :: Python :: 3 :: Only","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Programming Language :: Python :: 3.9","Topic :: Internet :: WWW/HTTP"],"description":"

\n\n\n\n

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

\n\n

\n\n \n $\"pypi\"$ \n \n\n \n $\"license\"$ \n \n\n \n $\"license\"$ \n \n\n \n $\"Downloads\"$ \n \n

\n\n-----\n\n**Hishel (հիշել, remember)** is a library that implements HTTP Caching for [HTTPX](https://github.com/encode/httpx) and [HTTP Core](https://github.com/encode/httpcore) libraries in accordance with [**RFC 9111**](https://www.rfc-editor.org/rfc/rfc9111.html), the most recent caching specification.\n\n## Features\n\n- 💾 **Persistence**: Responses are cached in the [**persistent memory**](https://en.m.wikipedia.org/wiki/Persistent_memory) for later use.\n- 🤲 **Compatibility**: It is completely compatible with your existing transports or connection pools, *whether they are default, custom, or provided by third-party libraries.*\n- 🤗 **Easy to use**: You continue to use httpx while also enabling [web cache](https://en.wikipedia.org/wiki/Web_cache).\n- 🧠 **Smart**: Attempts to clearly implement RFC 9111, understands `Vary`, `Etag`, `Last-Modified`, `Cache-Control`, and `Expires` headers, and *handles response re-validation automatically*.\n- ⚙️ **Configurable**: You have complete control over how the responses are stored and serialized.\n- 📦 **From the package**:\n - Built-in support for [File system](https://en.wikipedia.org/wiki/File_system), [Redis](https://en.wikipedia.org/wiki/Redis), [SQLite](https://en.wikipedia.org/wiki/SQLite), and [AWS S3](https://aws.amazon.com/s3/) backends.\n - Built-in support for [JSON](https://en.wikipedia.org/wiki/JSON), [YAML](https://en.wikipedia.org/wiki/YAML), and [pickle](https://docs.python.org/3/library/pickle.html) serializers.\n- 🚀 **Very fast**: Your requests will be even faster if there are *no IO operations*.\n\n## Documentation\nGo through the [Hishel documentation](https://hishel.com).\n\n## QuickStart\n\nInstall `Hishel` using pip:\n``` shell\n$ pip install hishel\n```\n\nLet's begin with an example of a httpx client.\n\n```python\nimport hishel\n\nwith hishel.CacheClient() as client:\n client.get(\"https://hishel.com\") # 0.4749558370003797s\n client.get(\"https://hishel.com\") # 0.002873589000046195s (~250x faster!)\n```\n\nor in asynchronous context\n\n```python\nimport hishel\n\nasync with hishel.AsyncCacheClient() as client:\n await client.get(\"https://hishel.com\")\n await client.get(\"https://hishel.com\") # takes from the cache\n```\n\n## Configurations\n\nConfigure when and how you want to store your responses.\n\n```python\nimport hishel\n\n# All the specification configs\ncontroller = hishel.Controller(\n # Cache only GET and POST methods\n cacheable_methods=[\"GET\", \"POST\"],\n\n # Cache only 200 status codes\n cacheable_status_codes=[200],\n\n # Use the stale response if there is a connection issue and the new response cannot be obtained.\n allow_stale=True,\n\n # First, revalidate the response and then utilize it.\n # If the response has not changed, do not download the\n # entire response data from the server; instead,\n # use the one you have because you know it has not been modified.\n always_revalidate=True,\n)\n\n# All the storage configs\nstorage = hishel.S3Storage(\n bucket_name=\"my_bucket_name\", # store my cache files in the `my_bucket_name` bucket\n ttl=3600, # delete the response if it is in the cache for more than an hour\n)\nclient = hishel.CacheClient(controller=controller, storage=storage)\n\n\n# Ignore the fact that the server does not recommend you cache this request!\nclient.post(\n \"https://example.com\",\n extensions={\"force_cache\": True}\n)\n\n\n# Return a regular response if it is in the cache; else, return a 504 status code. DO NOT SEND A REQUEST!\nclient.post(\n \"https://example.com\",\n headers=[(\"Cache-Control\", \"only-if-cached\")]\n)\n\n\n# Ignore cached responses and do not store incoming responses!\nresponse = client.post(\n \"https://example.com\",\n extensions={\"cache_disabled\": True}\n)\n```\n\n## How and where are the responses saved?\n\nThe responses are stored by `Hishel` in [storages](https://hishel.com/userguide/#storages).\nYou have complete control over them; you can change storage or even write your own if necessary.\n\n\n## Support the project\n\nYou can support the project by simply leaving a GitHub star ⭐ or by [contributing](https://hishel.com/contributing/).\nHelp us grow and continue developing good software for you ❤️\n\n# Changelog\n\n## 0.1.2 (5th April, 2025)\n\n- Add check for fips compliant python. (#325)\n- Fix compatibility with httpx. (#291)\n- Use `SyncByteStream` instead of `ByteStream`. (#298)\n- Don't raise exceptions if date-containing headers are invalid. (#318)\n- Fix for S3 Storage missing metadata in API request. (#320)\n\n## 0.1.1 (2nd Nov, 2024)\n\n- Fix typing extensions not found. (#290)\n\n## 0.1.0 (2nd Nov, 2024)\n\n- Add support for Python 3.12 / drop Python 3.8. (#286)\n- Specify usedforsecurity=False in blake2b. (#285)\n\n## 0.0.33 (4th Oct, 2024)\n\n- Added a [Logging](https://hishel.com/advanced/logging/) section to the documentation.\n\n## 0.0.32 (27th Sep, 2024)\n\n- Don't raise an exception if the `Date` header is not present. (#273)\n\n## 0.0.31 (22nd Sep, 2024)\n\n- Ignore file not found error when cleaning up a file storage. (#264) \n- Fix `AssertionError` on `client.close()` when use SQLiteStorage. (#269) \n- Fix ignored flags when use `force_cache`. (#271) \n\n## 0.0.30 (12th July, 2024)\n\n- Fix cache update on revalidation response with content (rfc9111 section 4.3.3) (#239)\n- Fix request extensions that were not passed into revalidation request for transport-based implementation (but were\n passed for the pool-based impl) (#247).\n- Add `cache_private` property to the controller to support acting as shared cache. (#224)\n- Improve efficiency of scanning cached responses in `FileStorage` by reducing number of syscalls. (#252)\n- Add `remove` support for storages (#241)\n\n## 0.0.29 (23th June, 2024)\n\n- Documentation hotfix. (#244)\n\n## 0.0.28 (23th June, 2024)\n\n- Add `revalidated` response extension. (#242)\n\n## 0.0.27 (31th May, 2024)\n\n- Fix `RedisStorage` when using without ttl. (#231)\n\n## 0.0.26 (12th April, 2024)\n\n- Expose `AsyncBaseStorage` and `BaseStorage`. (#220)\n- Prevent cache hits from resetting the ttl. (#215)\n\n## 0.0.25 (26th March, 2024)\n\n- Add `force_cache` property to the controller, allowing RFC9111 rules to be completely disabled. (#204)\n- Add `.gitignore` to cache directory created by `FIleStorage`. (#197)\n- Remove `stale_*` headers from the `CacheControl` class. (#199)\n\n## 0.0.24 (14th February, 2024)\n\n- Fix `botocore is not installed` exception when using any kind of storage. (#186)\n\n## 0.0.23 (14th February, 2024)\n\n- Make `S3Storage` to check staleness of all cache files with set interval. (#182)\n- Fix an issue where an empty file in `FileCache` could cause a parsing error. (#181)\n- Support caching for `POST` and other HTTP methods. (#183)\n\n## 0.0.22 (31th January, 2024)\n\n- Make `FileStorage` to check staleness of all cache files with set interval. (#169)\n- Support AWS S3 storages. (#164)\n- Move `typing_extensions` from requirements.txt to pyproject.toml. (#161)\n\n## 0.0.21 (29th December, 2023)\n\n- Fix inner transport and connection pool instances closing. (#147)\n- Improved error message when the storage type is incorrect. (#138)\n\n## 0.0.20 (12th December, 2023)\n\n- Add in-memory storage. (#133)\n- Allow customization of cache key generation. (#130)\n\n## 0.0.19 (30th November, 2023)\n\n- Add `force_cache` extension to enforce the request to be cached, ignoring the HTTP headers. (#117)\n- Fix issue where sqlite storage cache get deleted immediately. (#119)\n- Support float numbers for storage ttl. (#107)\n\n## 0.0.18 (23rd November, 2023)\n\n- Fix issue where freshness cannot be calculated to re-send request. (#104)\n- Add `cache_disabled` extension to temporarily disable the cache (#109)\n- Update `datetime.datetime.utcnow()` to `datetime.datetime.now(datetime.timezone.utc)` since `datetime.datetime.utcnow()` has been deprecated. (#111)\n\n## 0.0.17 (6th November, 2023)\n\n- Fix `Last-Modified` validation.\n\n## 0.0.16 (25th October, 2023)\n\n- Add `install_cache` function. (#95)\n- Add sqlite support. (#92)\n- Move `ttl` argument to `BaseStorage` class. (#94)\n\n## 0.0.14 (23rd October, 2023)\n\n- Replace `AsyncResponseStream` with `AsyncCacheStream`. (#86)\n- Add `must-understand` response directive support. (#90)\n\n## 0.0.13 (5th October, 2023)\n\n- Add support for Python 3.12. (#71)\n- Fix connections releasing from the connection pool. (#83)\n\n## 0.0.12 (8th September, 2023)\n\n- Add metadata into the response extensions. (#56)\n\n## 0.0.11 (15th August, 2023)\n\n- Add support for request `cache-control` directives. (#42)\n- Drop httpcore dependency. (#40)\n- Support HTTP methods only if they are defined as cacheable. (#37)\n\n## 0.0.10 (7th August, 2023)\n\n- Add Response metadata. (#33)\n- Add API Reference documentation. (#30)\n- Use stale responses only if the client is disconnected. (#28)\n\n## 0.0.9 (1st August, 2023)\n\n- Expose Controller API. (#23)\n\n## 0.0.8 (31st July, 2023)\n\n- Skip redis tests if the server was not found. (#16)\n- Decrease sleep time for the storage ttl tests. (#18)\n- Fail coverage under 100. (#19)\n\n## 0.0.7 (30th July, 2023)\n\n- Add support for `Heuristic Freshness`. (#11)\n- Change `Controller.cache_heuristically` to `Controller.allow_heuristics`. (#12)\n- Handle import errors. (#13)\n\n## 0.0.6 (29th July, 2023)\n\n- Fix `Vary` header validation. (#8)\n- Dump original requests with the responses. (#7)\n\n## 0.0.5 (29th July, 2023)\n\n- Fix httpx response streaming.\n\n## 0.0.4 (29th July, 2023)\n\n- Change `YamlSerializer` name to `YAMLSerializer`.\n\n## 0.0.3 (28th July, 2023)\n\n- Add `from_cache` response extension.\n- Add `typing_extensions` into the requirements.\n\n## 0.0.2 (25th July, 2023)\n\n- Add [redis](https://redis.io/) support.\n- Make backends thread and task safe.\n- Add black as a new linter.\n- Add an expire time for cached responses.\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":null,"license":null,"license_expression":"BSD-3-Clause","license_files":["LICENSE"],"maintainer":null,"maintainer_email":null,"name":"hishel","package_url":"https://pypi.org/project/hishel/","platform":null,"project_url":"https://pypi.org/project/hishel/","project_urls":{"Homepage":"https://hishel.com","Source":"https://github.com/karpetrosyan/hishel"},"provides_extra":["redis","s3","sqlite","yaml"],"release_url":"https://pypi.org/project/hishel/0.1.2/","requires_dist":["httpx>=0.28.0","redis==5.0.4; extra == \"redis\"","boto3<=1.15.3,>=1.15.0; python_version < \"3.12\" and extra == \"s3\"","boto3>=1.15.3; python_version >= \"3.12\" and extra == \"s3\"","anysqlite>=0.0.5; extra == \"sqlite\"","pyyaml==6.0.1; extra == \"yaml\""],"requires_python":">=3.9","summary":"Persistent cache implementation for httpx and httpcore","version":"0.1.2","yanked":false,"yanked_reason":null}

Dependencies of hishel (5).
Dependency	Optional
httpx	false
anysqlite	true
boto3	true
pyyaml	true
redis	true

Package search

hishel

project_urls

Dependencies

All package metadata

Releases