hishel

library1.3.1pypypi✓ verified 24d ago

Hishel is an elegant HTTP caching library for Python, implementing RFC 9111 specifications to provide seamless caching integration for popular HTTP clients like HTTPX and Requests. It offers flexible storage backends, including SQLite, and supports both synchronous and asynchronous workflows with a focus on high performance and type safety. The library is actively maintained with frequent minor releases, ensuring ongoing compatibility and feature enhancements.

http-networking serialization database

pip install hishel

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HISHEL

hishel

http-networkingpythonv1.3.1

Install

2.7s avg

Import

—

Disk

32MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 33.6MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.7s · import 0.000s · 34MB

32MB installed

● package 32MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CacheClient

✓ from hishel import CacheClient

✗ from hishel import CacheClient

This quickstart demonstrates using Hishel's `SyncCacheClient` with HTTPX for both in-memory (default) and file-based (SQLite) caching. The first request fetches data from the origin, while subsequent requests for the same URL will be served from the cache, if applicable according to HTTP caching rules.

import hishel import httpx def main(): # Use SyncCacheClient for synchronous HTTPX requests with hishel.httpx.SyncCacheClient() as client: print("First request (from origin):") response1 = client.get("https://httpbin.org/get") print(f"Status: {response1.status_code}, From cache: {response1.extensions.get('hishel_from_cache', False)}") print("\nSecond request (from cache if cachable):") response2 = client.get("https://httpbin.org/get") print(f"Status: {response2.status_code}, From cache: {response2.extensions.get('hishel_from_cache', False)}") # Example with explicit SQLite storage # Ensure 'my_cache.db' is created in a writable directory storage = hishel.SyncSqliteStorage(database_path="./my_cache.db") with hishel.httpx.SyncCacheClient(storage=storage) as client: print("\nFirst request with SQLite storage (from origin):") response3 = client.get("https://httpbin.org/get?item=1") print(f"Status: {response3.status_code}, From cache: {response3.extensions.get('hishel_from_cache', False)}") print("\nSecond request with SQLite storage (from cache):") response4 = client.get("https://httpbin.org/get?item=1") print(f"Status: {response4.status_code}, From cache: {response4.extensions.get('hishel_from_cache', False)}") if __name__ == "__main__": main()

Debug

Known issues

breakingHishel 1.1.9 officially dropped support for Python 3.9. Users on Python 3.9 or older must use an earlier version of Hishel.

fix

Upgrade to Python 3.10 or newer, or pin Hishel to `<1.1.9`.

affects: >=1.1.9

gotchaThe `hishel.install_cache` function is intended for experimental use only and is not recommended for production environments.

fix

For reliable caching, use `hishel.CacheClient`, `hishel.AsyncCacheClient`, or `hishel.CacheTransport` directly with your HTTP client.

affects: All

gotchaFor stream-based responses to be properly stored in Hishel storages, you must consume (iterate through) the response stream. Simply creating an entry with a stream does not store its data.

fix

Always iterate over the response stream (e.g., `for chunk in response.iter_bytes(): pass`) to ensure its content is saved to the cache.

affects: All

gotchaHishel's `CacheClient` and `AsyncCacheClient` classes hide the constructor signature of the underlying `httpx` client. This means IDEs might not suggest arguments that are still valid for configuration.

fix

Refer to the `httpx` documentation for available client arguments, as they are compatible with Hishel's cache clients.

affects: All

gotchaEarlier versions (before 1.1.8) had potential race conditions in storage operations.

fix

Upgrade to Hishel 1.1.8 or newer to benefit from race condition fixes.

affects: <1.1.8

gotchaPython's mutable default arguments (e.g., lists, dicts) are evaluated only once when the function is defined. Using them as defaults for `FilterPolicy` or other configurable components can lead to unintended shared state across calls.

fix

Always use `None` as a default for mutable arguments and initialize them inside the function if `None` is passed (e.g., `if filters is None: filters = []`).

affects: All

Upgrade

Version history

1.3.1latest on PyPI · released Aug 10, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.10 or newer.

anyiorequiredRequired for asynchronous operations and internals.

anysqliterequiredRequired for SQLite storage backend.

httpcorerequiredUnderlying HTTP library dependency.

msgpackrequiredRequired for serialization.

typing_extensionsrequiredProvides backported type hints.

httpxoptionalOptional dependency for HTTPX client integration.

requestsoptionalOptional dependency for Requests client integration.

fastapioptionalOptional dependency for FastAPI and ASGI middleware integration.

boto3optionalOptional dependency for AWS S3 storage backend.

PyYAMLoptionalOptional dependency for YAML serialization.

redisoptionalOptional dependency for Redis storage backend.

Agent activity

40 hits · last 30 days

node

Perplexity

Resources

githubhttps://github.com/karpetrosyan/hishel ↗

packagehttps://pypi.org/project/hishel/ ↗

homepagehttps://hishel.com ↗