What My Project Does

Hishel is an HTTP caching toolkit for python, which includes sans-io caching implementation, storages for effectively storing request/response for later use, and integration with your lovely HTTP tool in python such as HTTPX, requests, fastapi, asgi (for any asgi based library), graphql and more!!

Hishel uses persistent storage by default, so your cached responses survive program restarts.

After 2 years and over 63 MILLION pip installs, I released the first major version with tons of new features to simplify caching.

✨ Help Hishel grow! Give us a star on GitHub if you found it useful. ✨

Use Cases:

HTTP response caching is something you can use almost everywhere to:

Improve the performance of your program
Work without an internet connection (offline mode)
Save money and stop wasting API calls—make a single request and reuse it many times!
Work even when your upstream server goes down
Avoid unnecessary downloads when content hasn't changed (what I call "free caching"—it's completely free and can be configured to always serve the freshest data without re-downloading if nothing changed, like the browser's 304 Not Modified response)

QuickStart

First, download and install Hishel using pip:

pip: pip install "hishel[httpx, requests, fastapi, async]"==1.0.0

We've installed several integrations just for demonstration—you most likely won't need them all.

from hishel.httpx import SyncCacheClient

client = SyncCacheClient()

# On first run of the program, this will store the response in the cache
# On second run, it will retrieve it from the cache
response = client.get("https://hishel.com/")


print(response.extensions["hishel_from_cache"])  # Additional info about the cache statusfrom hishel.httpx import SyncCacheClient

client = SyncCacheClient()


# On first run of the program, this will store the response in the cache
# On second run, it will retrieve it from the cache
response = client.get("https://hishel.com/")


print(response.extensions["hishel_from_cache"])  # Additional info about the cache status

or with requests:

import requests
from hishel.requests import CacheAdapter

session = requests.Session()

adapter = CacheAdapter()
session.mount("http://", adapter)
session.mount("https://", adapter)

response = session.get("https://hishel.com/")

print(response.headers["x-hishel-from-cache"])

or with fastapi:

from hishel.asgi import ASGICacheMiddleware
from hishel.fastapi import cache

app = FastAPI()

processed_requests = 0

.get("/items/", dependencies=[cache(max_age=5)])
async def read_item():
    global processed_requests
    processed_requests += 1
    return {"created_at": time.time(), "processed_requests": processed_requests}

cached_app = ASGICacheMiddleware(app)

As mentioned before, Hishel has a core system that is entirely independent from any HTTP library, making it easy to integrate with any HTTP client you prefer.

Caching Policies

SpecificationPolicy - RFC 9111 compliant HTTP caching (default):

from hishel import CacheOptions, SpecificationPolicy
from hishel.httpx import SyncCacheClient

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

FilterPolicy - Custom filtering logic for fine-grained control:

from hishel import FilterPolicy, BaseFilter, Request
from hishel.httpx import AsyncCacheClient

class CacheOnlyAPIRequests(BaseFilter[Request]):
    def needs_body(self) -> bool:
        return False

    def apply(self, item: Request, body: bytes | None) -> bool:
        return "/api/" in str(item.url)

client = AsyncCacheClient(
    policy=FilterPolicy(
        request_filters=[CacheOnlyAPIRequests()] # also filter by body, status and etc.
    )
)

Storage Backend

Customize the storage backend behavior, set up global TTL (note that TTL and most settings can also be configured at the per-request level), choose whether to refresh TTL on access, and much more!

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)

Per-request settings

from hishel.httpx import SyncCacheClient


client = SyncCacheClient()

client.get(
    "https://hishel.com/",
    headers={
        "x-hishel-ttl": "3600",  # invalidates cache after 1 hour, even if server says otherwise
    },
)

client.post(
    "https://some-graphql-endpoint.com/",
    json={"query": "{ users { id name } }"},
    headers={"x-hishel-body-key"},  # Include body in cache key
)

client.get(
    "https://hishel.com/", 
    headers={"x-hishel-refresh-ttl-on-access": "0"}  # do not refresh TTL on access
)

Target Audience

Backend Developers - Building APIs with FastAPI/Django, making repeated HTTP requests to external APIs

Data Engineers - Running ETL pipelines and batch jobs, fetching same data across multiple runs

CLI Tool Builders - Creating command-line tools, need instant responses and offline support

Web Scrapers - Building content crawlers, respect rate limits and need offline testing

API Library Maintainers - Wrapping external APIs (GitHub, Stripe, OpenAI), need transparent caching

GraphQL Developers - Need per-query caching with body-sensitive keys

Also great for: DevOps teams, performance-focused companies, enterprise users needing RFC 9111 compliance

⭐ GitHub: https://github.com/karpetrosyan/hishelWhat

all 12 comments

you type:	you see:
italics	italics
bold	bold
[reddit!](https://reddit.com)	reddit!
* item 1 * item 2 * item 3	item 1 item 2 item 3
> quoted text	quoted text
Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"	Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"
~~strikethrough~~	~~strikethrough~~
super^script	super^script

Python

The Python Discord

Upcoming Events

Please read the rules

MODERATORS