Metadata-Version: 2.1
Name: asgi-caches
Version: 0.3.1
Summary: Server-side HTTP caching for ASGI applications, inspired by Django's cache framework
Home-page: http://github.com/florimondmanca/asgi-caches
Author: Florimond Manca
Author-email: florimond.manca@gmail.com
License: MIT
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: async-caches (==0.*)
Requires-Dist: starlette (==0.*)

# asgi-caches

[![Build Status](https://travis-ci.com/florimondmanca/asgi-caches.svg?branch=master)](https://travis-ci.com/florimondmanca/asgi-caches)
[![Coverage](https://codecov.io/gh/florimondmanca/asgi-caches/branch/master/graph/badge.svg)](https://codecov.io/gh/florimondmanca/asgi-caches)
[![Package version](https://badge.fury.io/py/asgi-caches.svg)](https://pypi.org/project/asgi-caches)

`asgi-caches` provides middleware and utilities for adding server-side HTTP caching to ASGI applications. It is powered by [`async-caches`](https://rafalp.github.io/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

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

## Quickstart

```python
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](https://rafalp.github.io/async-caches/) 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](https://asgi-caches.florimond.dev).

## 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](https://docs.djangoproject.com/en/2.2/topics/cache/).

## License

MIT


# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

## 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)


