asgi-caches

asgi-caches provides middleware and utilities for adding server-side HTTP caching to ASGI applications. It is powered by async-caches, and inspired by Django's cache framework.

Documentation is available at: https://asgi-caches.florimond.dev

Note: this project is in an "alpha" status. Several features still need to be implemented, and you should expect breaking API changes across minor versions.

Features

• Compatibility with any ASGI application (e.g. Starlette, FastAPI, Quart, etc.).
• Support for application-wide or per-endpoint caching.
• Ability to fine-tune the cache behavior (TTL, cache control) down to the endpoint level.
• Clean and explicit API enabled by a loose coupling with async-caches.
• Fully type annotated.
• 100% test coverage.

Installation

pip install "asgi-caches==0.*"

Quickstart

from asgi_caches.middleware import CacheMiddleware

cache = Cache("locmem://null")

async def app(scope, receive, send):
    assert scope["type"] == "http"
    headers = [(b"content-type", "text/plain")]
    await send({"type": "http.response.start", "status": 200, "headers": headers})
    await send({"type": "http.response.body", "body": b"Hello, world!"})

app = CacheMiddleware(app, cache=cache)

This example:

• Sets up an in-memory cache (see the async-caches docs for specifics).
• Sets up an application (in this case, a raw-ASGI 'Hello, world!' app).
• Applies caching on the entire application.

To learn more, head to the documentation.

Credits

Due credit goes to the Django developers and maintainers, as a lot of the API and implementation was directly inspired by the Django cache framework.

License

MIT

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

0.3.1 - 2019-11-23

Changed

• Disallow applying cache middleware multiple times. (Pull #21)

0.3.0 - 2019-11-12

Added

• Add @cache_control() decorator and its underlying middleware. (Pull #19)

0.2.0 - 2019-11-12

Added

• Add @cached() decorator. (Pull #15)

0.1.1 - 2019-11-12

Added

• Add DEBUG and TRACE logs. (Pull #14)

0.1.0 - 2019-11-12

Added

• Add CacheMiddleware. (Pull #8)
• Prevent caching of responses that have cookies when the request has none. (Pull #9)
• Prevent caching of responses if the cache TTL is zero. (Pull #10)