Skip to content

Caching ​

Caching in Zapros is implemented as a handler powered by Hishel — wrapping another handler to automatically cache HTTP responses.

Installation ​

The caching handler is available with the caching optional feature:

bash
pip install zapros[caching]

Setup ​

python
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(AsyncStdNetworkHandler())
)
python
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(handler=CacheMiddleware(StdNetworkHandler()))

Basic usage ​

By default, CacheMiddleware caches successful GET and HEAD responses (except 206) by method and URL. It ignores HTTP caching headers, so a stored response is served until the storage expires it:

python
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(AsyncStdNetworkHandler())
)

async with client:
    response = await client.get(
        "https://api.example.com/data",
    )
    print(response.status)
    print(response.context.get("caching"))
python
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(handler=CacheMiddleware(StdNetworkHandler()))

with client:
    response = client.get(
        "https://api.example.com/data",
    )
    print(response.status)
    print(response.context.get("caching"))

RFC 9111 mode ​

Pass rfc=True to follow RFC 9111 instead. The server's Cache-Control, Vary, ETag and related headers then decide what is stored, how long it stays fresh, and when it is revalidated:

python
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(
        AsyncStdNetworkHandler(),
        rfc=True,
    )
)
python
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(
    handler=CacheMiddleware(
        StdNetworkHandler(),
        rfc=True,
    )
)

To configure RFC 9111 mode, pass Hishel's CacheOptions instead of True. For example, shared=False makes it a private cache, which can store responses to requests with an Authorization header. See Hishel's documentation for all options:

python
from hishel import CacheOptions
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(
        AsyncStdNetworkHandler(),
        rfc=CacheOptions(shared=False),
    )
)
python
from hishel import CacheOptions
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(
    handler=CacheMiddleware(
        StdNetworkHandler(),
        rfc=CacheOptions(shared=False),
    )
)

WARNING

In the default mode the cache is shared across users, whatever their Authorization or Cookie headers. If responses differ per user, use RFC 9111 mode or a separate storage per user.

Custom storage ​

By default, responses are cached in an SQLite database (.cache/hishel/hishel_cache_v2.db). Closing the client also closes the middleware's storage, including one you passed in. You can customize the storage backend to use different databases or in-memory storage. See Hishel storage documentation for more options, including Redis.

Expiry ​

Storages accept default_ttl (seconds after the response is stored) and default_tti (seconds without being used). Whichever comes first expires the entry:

python
from hishel import AsyncSqliteStorage
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(
        AsyncStdNetworkHandler(),
        storage=AsyncSqliteStorage(
            default_ttl=86400,
            default_tti=3600,
        ),
    )
)
python
from hishel import SqliteStorage
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(
    handler=CacheMiddleware(
        StdNetworkHandler(),
        storage=SqliteStorage(
            default_ttl=86400,
            default_tti=3600,
        ),
    )
)

In-memory storage ​

For temporary caching without persistent storage:

python
import anysqlite
from hishel import AsyncSqliteStorage
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(
        AsyncStdNetworkHandler(),
        storage=AsyncSqliteStorage(
            connection=await anysqlite.connect(":memory:")
        ),
    )
)
python
import sqlite3
from hishel import SqliteStorage
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(
    handler=CacheMiddleware(
        StdNetworkHandler(),
        storage=SqliteStorage(
            connection=sqlite3.connect(
                ":memory:", check_same_thread=False
            )
        ),
    )
)

Custom SQLite file ​

Specify a custom database file location:

python
from hishel import AsyncSqliteStorage
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(
        AsyncStdNetworkHandler(),
        storage=AsyncSqliteStorage(
            database_path="my_cache.db"
        ),
    )
)
python
from hishel import SqliteStorage
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(
    handler=CacheMiddleware(
        StdNetworkHandler(),
        storage=SqliteStorage(
            database_path="my_cache.db"
        ),
    )
)

Per-request configuration ​

Control caching behavior on a per-request basis using the context parameter.

TTL (Time to Live) ​

Expire this response a number of seconds after it is stored:

python
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(AsyncStdNetworkHandler())
)

async with client:
    response = await client.get(
        "https://api.example.com/data",
        context={
            "caching": {
                "ttl": 30.0,
            }
        },
    )
python
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(handler=CacheMiddleware(StdNetworkHandler()))

with client:
    response = client.get(
        "https://api.example.com/data",
        context={
            "caching": {
                "ttl": 30.0,
            }
        },
    )

TTI (Time to Idle) ​

Expire this response after a number of seconds without being used, so each use keeps it alive:

python
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(AsyncStdNetworkHandler())
)

async with client:
    response = await client.get(
        "https://api.example.com/data",
        context={
            "caching": {
                "tti": 300.0,
            }
        },
    )
python
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(handler=CacheMiddleware(StdNetworkHandler()))

with client:
    response = client.get(
        "https://api.example.com/data",
        context={
            "caching": {
                "tti": 300.0,
            }
        },
    )

Cache key ​

Replace the default key (method and URL) with your own. Requests with the same key share an entry, so here both URLs are answered by one cached response. A custom key alone does not make POST and other unsafe methods cacheable, see Forcing the cache:

python
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(AsyncStdNetworkHandler())
)

async with client:
    response = await client.get(
        "https://api.example.com/data?session=abc",
        context={
            "caching": {
                "key": "data",
            }
        },
    )
python
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(handler=CacheMiddleware(StdNetworkHandler()))

with client:
    response = client.get(
        "https://api.example.com/data?session=abc",
        context={
            "caching": {
                "key": "data",
            }
        },
    )

Forcing the cache ​

POST and other unsafe methods are never cached by default, because serving them from cache means the request never reaches the server. For requests that only read data, such as GraphQL queries or search endpoints, set force to cache the response anyway.

The default key doesn't include the request body, so force on a method other than GET or HEAD requires a key, and raises ValueError without one. Choose a key that changes whenever the body does. A forced request ignores rfc and caches by method and key, storing only successful responses:

python
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(AsyncStdNetworkHandler())
)

async with client:
    response = await client.post(
        "https://api.example.com/graphql",
        json={"query": "{ user(id: 1) { name } }"},
        context={
            "caching": {
                "force": True,
                "key": "user-1-name",
            }
        },
    )
python
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(handler=CacheMiddleware(StdNetworkHandler()))

with client:
    response = client.post(
        "https://api.example.com/graphql",
        json={"query": "{ user(id: 1) { name } }"},
        context={
            "caching": {
                "force": True,
                "key": "user-1-name",
            }
        },
    )

Mode and storage ​

The rfc and storage arguments of CacheMiddleware can also be overridden for a single request:

python
from hishel import AsyncSqliteStorage
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(AsyncStdNetworkHandler())
)
reports_storage = AsyncSqliteStorage(
    database_path="reports.db"
)

async with client:
    response = await client.get(
        "https://api.example.com/reports",
        context={
            "caching": {
                "rfc": True,
                "storage": reports_storage,
            }
        },
    )
python
from hishel import SqliteStorage
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(handler=CacheMiddleware(StdNetworkHandler()))
reports_storage = SqliteStorage(database_path="reports.db")

with client:
    response = client.get(
        "https://api.example.com/reports",
        context={
            "caching": {
                "rfc": True,
                "storage": reports_storage,
            }
        },
    )

Response context ​

The response context provides useful information about caching behavior.

Check if response was cached ​

python
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(AsyncStdNetworkHandler())
)

async with client:
    response = await client.get(
        "https://api.example.com/data",
    )
    caching = response.context.get("caching")

    if caching:
        print(f"From cache: {caching.get('from_cache')}")
python
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(handler=CacheMiddleware(StdNetworkHandler()))

with client:
    response = client.get(
        "https://api.example.com/data",
    )
    caching = response.context.get("caching")

    if caching:
        print(f"From cache: {caching.get('from_cache')}")

Available context fields ​

  • from_cache - Whether the response was served from cache
  • revalidated - Whether the cached response was revalidated with the origin server (RFC 9111 mode only, see RFC 9111 validation)
  • stored - Whether the response was stored in the cache. It is saved once its body has been fully read
python
from zapros import (
    AsyncClient,
    CacheMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(AsyncStdNetworkHandler())
)

async with client:
    response = await client.get(
        "https://api.example.com/data",
    )
    caching = response.context.get("caching")

    if caching:
        print(f"From cache: {caching.get('from_cache')}")
        print(f"Revalidated: {caching.get('revalidated')}")
        print(f"Stored: {caching.get('stored')}")
python
from zapros import (
    Client,
    CacheMiddleware,
    StdNetworkHandler,
)

client = Client(handler=CacheMiddleware(StdNetworkHandler()))

with client:
    response = client.get(
        "https://api.example.com/data",
    )
    caching = response.context.get("caching")

    if caching:
        print(f"From cache: {caching.get('from_cache')}")
        print(f"Revalidated: {caching.get('revalidated')}")
        print(f"Stored: {caching.get('stored')}")

Combining with other handlers ​

Chain CacheMiddleware with other handlers like cookies or retries:

python
from zapros import (
    AsyncClient,
    CacheMiddleware,
    CookieMiddleware,
    AsyncStdNetworkHandler,
)

client = AsyncClient(
    handler=CacheMiddleware(
        CookieMiddleware(AsyncStdNetworkHandler())
    )
)