fastapi-cache-stable 0.3.0a0__tar.gz → 0.3.0a2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fastapi_cache_stable-0.3.0a2/CHANGELOG.md +151 -0
- fastapi_cache_stable-0.3.0a2/COMPATIBILITY.md +284 -0
- fastapi_cache_stable-0.3.0a2/FORK_ORIGIN.md +12 -0
- fastapi_cache_stable-0.3.0a2/MIGRATION.md +408 -0
- fastapi_cache_stable-0.3.0a2/PKG-INFO +428 -0
- fastapi_cache_stable-0.3.0a2/README.md +385 -0
- fastapi_cache_stable-0.3.0a2/SECURITY.md +15 -0
- fastapi_cache_stable-0.3.0a2/SUPPORT.md +27 -0
- {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/__init__.py +18 -3
- {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/backends/inmemory.py +27 -15
- fastapi_cache_stable-0.3.0a2/fastapi_cache/backends/redis.py +80 -0
- fastapi_cache_stable-0.3.0a2/fastapi_cache/coder.py +208 -0
- fastapi_cache_stable-0.3.0a2/fastapi_cache/decorator.py +396 -0
- {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/pyproject.toml +32 -8
- fastapi_cache_stable-0.3.0a0/PKG-INFO +0 -281
- fastapi_cache_stable-0.3.0a0/README.md +0 -238
- fastapi_cache_stable-0.3.0a0/fastapi_cache/backends/redis.py +0 -30
- fastapi_cache_stable-0.3.0a0/fastapi_cache/coder.py +0 -129
- fastapi_cache_stable-0.3.0a0/fastapi_cache/decorator.py +0 -231
- {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/LICENSE +0 -0
- {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/NOTICE +0 -0
- {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/backends/__init__.py +0 -0
- {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/backends/dynamodb.py +0 -0
- {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/backends/memcached.py +0 -0
- {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/key_builder.py +0 -0
- {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/py.typed +0 -0
- {fastapi_cache_stable-0.3.0a0 → fastapi_cache_stable-0.3.0a2}/fastapi_cache/types.py +0 -0
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# ChangeLog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
|
|
7
|
+
This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in <https://github.com/agustin18/fastapi-cache/tree/stable/changelog.d/>.
|
|
8
|
+
|
|
9
|
+
<!-- towncrier release notes start -->
|
|
10
|
+
|
|
11
|
+
## [0.3.0a2](https://github.com/agustin18/fastapi-cache/tree/v0.3.0a2) - 2026-11-14
|
|
12
|
+
|
|
13
|
+
### Bugfixes
|
|
14
|
+
|
|
15
|
+
- Bypass the cache for requests with a non-empty `Authorization` or `Cookie` header by
|
|
16
|
+
default. Add `cache_authenticated=True` to opt in with an identity-aware `key_builder`;
|
|
17
|
+
opting in with the default key builder raises `ValueError` for authenticated requests.
|
|
18
|
+
Backend error logs now report only the endpoint, namespace, and exception type; they no
|
|
19
|
+
longer include the cache key, exception message, or traceback.
|
|
20
|
+
Clear or rotate the cache namespace when upgrading from versions that cached authenticated
|
|
21
|
+
responses. [#12](https://github.com/agustin18/fastapi-cache/issues/12)
|
|
22
|
+
- InMemory backend: `expire=None` now means no expiration instead of immediate expiry, and each
|
|
23
|
+
backend instance has its own store and lock. Existing process-local entries are not shared
|
|
24
|
+
between instances; use a shared backend for cross-process caching. [#13](https://github.com/agustin18/fastapi-cache/issues/13)
|
|
25
|
+
- Emit `Cache-Control: max-age` only when the effective expiry is valid and non-negative.
|
|
26
|
+
`expire=None` and no-expiration InMemory hits no longer produce `max-age=None` or
|
|
27
|
+
`max-age=-1`; `ETag` and the cache-status header are still emitted. `expire=0` keeps the
|
|
28
|
+
legacy fallback to the global `expire` value. [#14](https://github.com/agustin18/fastapi-cache/issues/14)
|
|
29
|
+
- Use a stable SHA-256 digest for the ETag and emit it as a quoted weak validator
|
|
30
|
+
(`W/"<digest>"`). `If-None-Match` now uses weak comparison, supports comma-separated lists
|
|
31
|
+
and `*`, and is evaluated on both cache hits and misses, including after
|
|
32
|
+
`Cache-Control: no-cache`. Malformed entity-tags are ignored. The ETag value changes once
|
|
33
|
+
when upgrading; clients revalidate and receive the new value. [#15](https://github.com/agustin18/fastapi-cache/issues/15)
|
|
34
|
+
- Namespace the internal `_spec_type` marker as `__fastapi_cache_spec_type__` so user payloads
|
|
35
|
+
with `_spec_type` are preserved. `JsonCoder` now caches only simple `JSONResponse` objects
|
|
36
|
+
(status `200`, `application/json`, no custom headers, no background task) and bypasses other
|
|
37
|
+
non-JSON responses (`StreamingResponse`, `FileResponse`, `RedirectResponse`, plain `Response`,
|
|
38
|
+
templates). Responses with `Set-Cookie`, `Cache-Control: no-store`/`private`, or a background
|
|
39
|
+
task are never cached, regardless of the coder. The injected `response` object is also
|
|
40
|
+
checked before a cache read and before writing; cookies, `Cache-Control: no-store`/`private`,
|
|
41
|
+
background tasks, non-`200` statuses, and custom headers bypass the cache. `PickleCoder` caches serializable response
|
|
42
|
+
objects it can reproduce faithfully and bypasses streaming, file, and template responses. Old
|
|
43
|
+
cache entries written with `_spec_type` are treated as user data; flush the namespace if you
|
|
44
|
+
cache `datetime`/`date`/`Decimal` values. [#16](https://github.com/agustin18/fastapi-cache/issues/16)
|
|
45
|
+
|
|
46
|
+
### Improved Documentation
|
|
47
|
+
|
|
48
|
+
- Document the published `0.3.0a1` release and pin the alpha install commands. [#11](https://github.com/agustin18/fastapi-cache/issues/11)
|
|
49
|
+
- Document the `0.3.0a2` release status, pin the alpha install commands, and record the tested
|
|
50
|
+
Redis/redis-py compatibility. The auth/privacy, InMemory, `Cache-Control`, ETag,
|
|
51
|
+
`_spec_type`, and response-bypass fixes are now available in `0.3.0a2`. [#17](https://github.com/agustin18/fastapi-cache/issues/17)
|
|
52
|
+
|
|
53
|
+
## [0.3.0a1](https://github.com/agustin18/fastapi-cache/tree/v0.3.0a1) - 2026-11-14
|
|
54
|
+
|
|
55
|
+
### Bugfixes
|
|
56
|
+
|
|
57
|
+
- Avoid caching explicitly returned `Response` objects with status codes >= 400. Adapted from upstream PR #575 by RitiGrover. [#2](https://github.com/agustin18/fastapi-cache/issues/2)
|
|
58
|
+
- Add opt-in `TypedJsonCoder` for Pydantic v2 typed restoration. `JsonCoder` keeps the legacy decoded behavior; Pydantic v1 and unsupported annotations fall back; validation errors propagate. Adapted from upstream PR #576 by bezff. [#4](https://github.com/agustin18/fastapi-cache/issues/4)
|
|
59
|
+
- Fix `clear(key=...)` so it deletes only the requested key, and require the `:` boundary for
|
|
60
|
+
namespace clears in InMemory and Redis. Redis standalone now uses `SCAN`/`UNLINK`; Redis
|
|
61
|
+
Cluster namespace clearing raises `NotImplementedError`. Memcached/DynamoDB clear remains
|
|
62
|
+
unsupported. [#7](https://github.com/agustin18/fastapi-cache/issues/7)
|
|
63
|
+
|
|
64
|
+
### Improved Documentation
|
|
65
|
+
|
|
66
|
+
- Document and verify the legacy compatibility matrix: Python 3.8/3.9, FastAPI 0.111.1, and
|
|
67
|
+
Pydantic 1.10.27/2.8.2. Add a legacy CI job and a Python 3.8 wheel smoke test. No runtime
|
|
68
|
+
behavior changes. [#5](https://github.com/agustin18/fastapi-cache/issues/5)
|
|
69
|
+
|
|
70
|
+
### Misc
|
|
71
|
+
|
|
72
|
+
- Bump the transitive `certifi` dev/test dependency from 2024.7.4 to 2026.10.23. [#6](https://github.com/agustin18/fastapi-cache/issues/6)
|
|
73
|
+
- Add a manual TestPyPI publishing workflow with a separate `testpypi` environment and Trusted Publisher. It never runs on `release: published`. [#8](https://github.com/agustin18/fastapi-cache/issues/8)
|
|
74
|
+
- Make PyPI publishing manual-only by removing the `release: published` trigger. [#9](https://github.com/agustin18/fastapi-cache/issues/9)
|
|
75
|
+
|
|
76
|
+
## 0.3.0a0
|
|
77
|
+
|
|
78
|
+
- Community-maintained stable fork of fastapi-cache2, based on v0.2.2.
|
|
79
|
+
- Distribution renamed to `fastapi-cache-stable`; the `fastapi_cache` import and public API are unchanged.
|
|
80
|
+
- Declare `jinja2` as a direct dependency; the `starlette.templating` import in `coder.py` requires it.
|
|
81
|
+
- This is an alpha to reserve the PyPI distribution name. The 0.3.0 release will include the P0 correctness fixes and compatibility tests.
|
|
82
|
+
|
|
83
|
+
## 0.2
|
|
84
|
+
|
|
85
|
+
### 0.2.1
|
|
86
|
+
- Fix picklecoder
|
|
87
|
+
- Fix connection failure transparency and add logging
|
|
88
|
+
- Add Cache-Control and ETag on first response
|
|
89
|
+
- Support Async RedisCluster client from redis-py
|
|
90
|
+
|
|
91
|
+
### 0.2.0
|
|
92
|
+
|
|
93
|
+
- Make `request` and `response` optional.
|
|
94
|
+
- Add typing info to the `cache` decorator.
|
|
95
|
+
- Support cache jinja2 template response.
|
|
96
|
+
- Support cache `JSONResponse`
|
|
97
|
+
- Add `py.typed` file and type hints
|
|
98
|
+
- Add TestCase
|
|
99
|
+
- Fix cache decorate sync function
|
|
100
|
+
- Transparently handle backend connection failures.
|
|
101
|
+
|
|
102
|
+
## 0.1
|
|
103
|
+
|
|
104
|
+
### 0.1.10
|
|
105
|
+
|
|
106
|
+
- Add `Cache-Control:no-cache` support.
|
|
107
|
+
|
|
108
|
+
### 0.1.9
|
|
109
|
+
|
|
110
|
+
- Replace `aioredis` with `redis-py`.
|
|
111
|
+
|
|
112
|
+
### 0.1.8
|
|
113
|
+
|
|
114
|
+
- Support `dynamodb` backend.
|
|
115
|
+
|
|
116
|
+
### 0.1.7
|
|
117
|
+
|
|
118
|
+
- Fix default json coder for datetime.
|
|
119
|
+
- Add `enable` param to `init`.
|
|
120
|
+
|
|
121
|
+
### 0.1.6
|
|
122
|
+
|
|
123
|
+
- Fix redis cache.
|
|
124
|
+
- Encode key builder.
|
|
125
|
+
|
|
126
|
+
### 0.1.5
|
|
127
|
+
|
|
128
|
+
- Fix setting expire for redis (#24)
|
|
129
|
+
- Update expire key
|
|
130
|
+
|
|
131
|
+
### 0.1.4
|
|
132
|
+
|
|
133
|
+
- Fix default expire for memcached. (#13)
|
|
134
|
+
- Update default key builder. (#12)
|
|
135
|
+
|
|
136
|
+
### 0.1.3
|
|
137
|
+
|
|
138
|
+
- Fix cache key builder.
|
|
139
|
+
|
|
140
|
+
### 0.1.2
|
|
141
|
+
|
|
142
|
+
- Add default config when init.
|
|
143
|
+
- Update JsonEncoder.
|
|
144
|
+
|
|
145
|
+
### 0.1.1
|
|
146
|
+
|
|
147
|
+
- Add in-memory support.
|
|
148
|
+
|
|
149
|
+
### 0.1.0
|
|
150
|
+
|
|
151
|
+
- First version release.
|
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
# Compatibility contract
|
|
2
|
+
|
|
3
|
+
`fastapi-cache-stable` is an independent, community-maintained fork of
|
|
4
|
+
[`fastapi-cache2`](https://pypi.org/project/fastapi-cache2/). This document defines what
|
|
5
|
+
"drop-in" means for this project and what we promise to keep stable.
|
|
6
|
+
|
|
7
|
+
## What "drop-in" means
|
|
8
|
+
|
|
9
|
+
- The distribution is `fastapi-cache-stable`, but the Python import remains `fastapi_cache`.
|
|
10
|
+
- The public names below keep their import paths and call signatures.
|
|
11
|
+
- The normal success path for a GET endpoint keeps the same observable behavior: cache
|
|
12
|
+
miss calls the endpoint, cache hit returns the cached value, and the cache status header
|
|
13
|
+
reports `MISS`/`HIT`.
|
|
14
|
+
- Existing `@cache(...)` and `FastAPICache.init(...)` calls keep working without code changes.
|
|
15
|
+
- Authenticated requests bypass the cache by default. This is an intentional privacy behavior
|
|
16
|
+
change; authenticated endpoints must opt in with `cache_authenticated=True` and an
|
|
17
|
+
identity-aware `key_builder` to keep caching.
|
|
18
|
+
- `InMemoryBackend` instances are isolated: each owns its store and lock. `expire=None` means
|
|
19
|
+
no expiration. InMemory remains process-local; use a shared backend for cross-process
|
|
20
|
+
caching.
|
|
21
|
+
- Existing custom backends, coders and key builders that implement the documented protocols
|
|
22
|
+
keep working.
|
|
23
|
+
- Migration from `fastapi-cache2` does not require application code changes for valid legacy
|
|
24
|
+
use cases.
|
|
25
|
+
- Pydantic v2 users can opt into `TypedJsonCoder` for typed restoration; the default
|
|
26
|
+
`JsonCoder` keeps the legacy decoded behavior. Pydantic v1 and unsupported annotations
|
|
27
|
+
keep the legacy behavior.
|
|
28
|
+
- Python 3.8/3.9 legacy compatibility is validated in CI with FastAPI 0.111.1 and
|
|
29
|
+
Pydantic 1.10.27/2.8.2; it is migration compatibility, not a new-production recommendation.
|
|
30
|
+
|
|
31
|
+
## Public surface
|
|
32
|
+
|
|
33
|
+
```python
|
|
34
|
+
from fastapi_cache import (
|
|
35
|
+
Backend,
|
|
36
|
+
Coder,
|
|
37
|
+
FastAPICache,
|
|
38
|
+
JsonCoder,
|
|
39
|
+
KeyBuilder,
|
|
40
|
+
TypedJsonCoder,
|
|
41
|
+
default_key_builder,
|
|
42
|
+
)
|
|
43
|
+
from fastapi_cache.decorator import cache
|
|
44
|
+
from fastapi_cache.backends.inmemory import InMemoryBackend
|
|
45
|
+
from fastapi_cache.backends.redis import RedisBackend
|
|
46
|
+
from fastapi_cache.backends.memcached import MemcachedBackend
|
|
47
|
+
from fastapi_cache.backends.dynamodb import DynamoBackend
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### `FastAPICache`
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
FastAPICache.init(
|
|
54
|
+
backend,
|
|
55
|
+
prefix="",
|
|
56
|
+
expire=None,
|
|
57
|
+
coder=JsonCoder,
|
|
58
|
+
key_builder=default_key_builder,
|
|
59
|
+
cache_status_header="X-FastAPI-Cache",
|
|
60
|
+
enable=True,
|
|
61
|
+
cache_authenticated=False,
|
|
62
|
+
)
|
|
63
|
+
FastAPICache.clear(namespace=None, key=None)
|
|
64
|
+
FastAPICache.reset()
|
|
65
|
+
FastAPICache.get_backend()
|
|
66
|
+
FastAPICache.get_prefix()
|
|
67
|
+
FastAPICache.get_expire()
|
|
68
|
+
FastAPICache.get_coder()
|
|
69
|
+
FastAPICache.get_key_builder()
|
|
70
|
+
FastAPICache.get_cache_status_header()
|
|
71
|
+
FastAPICache.get_enable()
|
|
72
|
+
FastAPICache.get_cache_authenticated()
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### `@cache(...)`
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
cache(
|
|
79
|
+
expire=None,
|
|
80
|
+
coder=None,
|
|
81
|
+
key_builder=None,
|
|
82
|
+
namespace="",
|
|
83
|
+
injected_dependency_namespace="__fastapi_cache",
|
|
84
|
+
cache_authenticated=None,
|
|
85
|
+
)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### `Backend` protocol
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
async def get_with_ttl(key: str) -> tuple[int, bytes | None]
|
|
92
|
+
async def get(key: str) -> bytes | None
|
|
93
|
+
async def set(key: str, value: bytes, expire: int | None = None) -> None
|
|
94
|
+
async def clear(namespace: str | None = None, key: str | None = None) -> int
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### `KeyBuilder` protocol
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
def __call__(
|
|
101
|
+
function,
|
|
102
|
+
namespace: str = "",
|
|
103
|
+
*,
|
|
104
|
+
request=None,
|
|
105
|
+
response=None,
|
|
106
|
+
args: tuple,
|
|
107
|
+
kwargs: dict,
|
|
108
|
+
) -> str | Awaitable[str]
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### `Coder` protocol
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
classmethod can_encode(value) -> bool
|
|
115
|
+
classmethod encode(value) -> bytes
|
|
116
|
+
classmethod decode(value: bytes) -> Any
|
|
117
|
+
classmethod decode_as_type(value: bytes, *, type_) -> Any
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## Support levels
|
|
121
|
+
|
|
122
|
+
- **Migration compatibility:** tested legacy combinations are kept so existing applications can
|
|
123
|
+
move to this fork without code changes. This is not a recommendation for new production
|
|
124
|
+
deployments.
|
|
125
|
+
- **Security-supported environment:** current Python, FastAPI and Pydantic releases that still
|
|
126
|
+
receive upstream security fixes. This project does not backport security fixes for
|
|
127
|
+
end-of-life upstreams.
|
|
128
|
+
|
|
129
|
+
Python 3.8, 3.9 and 3.10 are end-of-life, and Pydantic v1 is end-of-life with 1.10.27 as its
|
|
130
|
+
final release. They remain in the migration matrix for compatibility, not as supported
|
|
131
|
+
security targets.
|
|
132
|
+
|
|
133
|
+
## Supported matrix for `0.3.x`
|
|
134
|
+
|
|
135
|
+
> The `0.3.0` line keeps `python = "^3.8"` for legacy migration. Python 3.8/3.9/3.10 and
|
|
136
|
+
> Pydantic v1 are end-of-life upstream; they are tested for migration, not recommended for
|
|
137
|
+
> new production deployments. The minimum supported Python will be revisited only after the
|
|
138
|
+
> compatibility matrix and an explicit floor decision.
|
|
139
|
+
|
|
140
|
+
Status definitions:
|
|
141
|
+
|
|
142
|
+
- **Verified**: tested in CI with identified versions.
|
|
143
|
+
- **Targeted for 0.3.0**: intended behavior, not yet guaranteed.
|
|
144
|
+
- **Experimental**: interface available, coverage insufficient.
|
|
145
|
+
- **Unsupported**: outside the compatibility contract.
|
|
146
|
+
|
|
147
|
+
| Component | Status | Notes |
|
|
148
|
+
|---|---|---|
|
|
149
|
+
| Python 3.10–3.13 | Verified | CI matrix runs the suite; Python 3.10 is EOL and kept for migration |
|
|
150
|
+
| Python 3.8/3.9 | Verified for migration | Legacy CI job with FastAPI 0.111.1 and Pydantic 1.10.27/2.8.2; EOL, not recommended for new production |
|
|
151
|
+
| Python 3.14 | Targeted | Evaluated after the first stable release |
|
|
152
|
+
| FastAPI | Verified with 0.111.1 and current 0.x | Older 0.100.x validation is a beta gate; no upper pin yet (`fastapi = "*"`) |
|
|
153
|
+
| Pydantic 2.x | Verified | Typed restoration is opt-in via `TypedJsonCoder`; default `JsonCoder` keeps legacy behavior |
|
|
154
|
+
| Pydantic v1 | Verified for migration | Tested with 1.10.27; EOL, no new security fixes; typed restoration is not applied |
|
|
155
|
+
| `Response`/`JSONResponse` annotations | Legacy decoded behavior | No Pydantic schema generation; cache hits keep working |
|
|
156
|
+
| Redis standalone | Verified for clear semantics | Redis 7 service in CI with redis-py 4.6.0; key-only clear and namespace boundary tested. redis-py 5/6 are not supported by the current `^4.2.0rc1` constraint and are untested |
|
|
157
|
+
| Redis Cluster | Unsupported for namespace clear | Key-only clear is supported; namespace clear raises `NotImplementedError`; no complete namespace clearing |
|
|
158
|
+
| InMemory | Verified for basic operations, clear semantics, `expire=None` and instance isolation | Unit tests; each instance owns its store and lock; no size cap yet |
|
|
159
|
+
| Memcached | Experimental | No full `clear`/TTL parity; `clear` raises `NotImplementedError` |
|
|
160
|
+
| DynamoDB | Experimental | `clear` raises `NotImplementedError`; the client cleanup issue remains open and is targeted for a future fix |
|
|
161
|
+
| Import `fastapi_cache` | Verified | Covered by compatibility tests |
|
|
162
|
+
|
|
163
|
+
> Redis results in `0.3.0a2` cover Redis 7 with redis-py 4.6.0. Other client or server
|
|
164
|
+
> versions are not verified; do not infer support from the Redis 7 job alone.
|
|
165
|
+
|
|
166
|
+
### `0.3.0a1` status
|
|
167
|
+
|
|
168
|
+
Implemented: error responses, opt-in `TypedJsonCoder`, `clear()` key/namespace semantics,
|
|
169
|
+
Redis Cluster namespace `NotImplementedError`, and the legacy compatibility matrix.
|
|
170
|
+
|
|
171
|
+
### `0.3.0a2` status
|
|
172
|
+
|
|
173
|
+
Implemented in `0.3.0a2`: authenticated requests bypass the
|
|
174
|
+
cache by default; opt-in with `cache_authenticated=True` and an identity-aware `key_builder`.
|
|
175
|
+
Opting in with the default key builder raises `ValueError` for authenticated requests.
|
|
176
|
+
`InMemoryBackend` instances are isolated, and `expire=None` means no expiration. The
|
|
177
|
+
decorator emits `Cache-Control: max-age` only for valid, non-negative expiry values; it
|
|
178
|
+
omits `max-age` for `expire=None` and no-expiration hits. `expire=0` keeps the legacy
|
|
179
|
+
fallback to the global `expire` value. ETags are quoted weak validators derived from a
|
|
180
|
+
stable SHA-256 digest; `If-None-Match` uses weak comparison, supports lists and `*`, is
|
|
181
|
+
evaluated on hits and misses, and ignores malformed entity-tags. `_spec_type` user payloads
|
|
182
|
+
are preserved via a namespaced internal marker. `JsonCoder` caches only simple `200`
|
|
183
|
+
`application/json` `JSONResponse` objects; other responses are bypassed unless the coder's
|
|
184
|
+
`can_encode` supports them. Responses with `Set-Cookie`, `Cache-Control: no-store/private`,
|
|
185
|
+
or a background task are never cached. The injected `response` object is checked before a
|
|
186
|
+
cache read and before a write; those directives, a non-`200` status, or any header other than
|
|
187
|
+
the automatic `content-length` bypass the cache for dict/list returns.
|
|
188
|
+
|
|
189
|
+
Targeted for later pre-releases: explicit re-`init()` and the Redis client/server matrix.
|
|
190
|
+
|
|
191
|
+
### Clear semantics
|
|
192
|
+
|
|
193
|
+
- `clear(key=...)` deletes exactly that key. Pass the full key as stored by the backend.
|
|
194
|
+
- `clear(namespace=...)` requires the `:` namespace boundary and includes nested namespaces.
|
|
195
|
+
- `clear()` clears the configured prefix; with an empty prefix it is a no-op.
|
|
196
|
+
- If both `namespace` and `key` are provided, `namespace` wins.
|
|
197
|
+
- Namespace clear is best-effort, not atomic. Keys added during a Redis `SCAN` may survive.
|
|
198
|
+
- Redis standalone uses `SCAN` + `UNLINK`; Redis Cluster namespace clear raises
|
|
199
|
+
`NotImplementedError`; use key-only clear or flush the database out of band.
|
|
200
|
+
- Memcached and DynamoDB do not implement `clear`.
|
|
201
|
+
- `clear()` is an administrative invalidation operation. Do not accept arbitrary keys or
|
|
202
|
+
namespaces from untrusted users.
|
|
203
|
+
|
|
204
|
+
## Intentional behavior changes
|
|
205
|
+
|
|
206
|
+
These are bug fixes targeted for `0.3.0`. The error-response, typed-decode and
|
|
207
|
+
clear-semantics fixes are implemented in `0.3.0a1`; the auth/privacy, InMemory,
|
|
208
|
+
`Cache-Control`, ETag, `_spec_type` and response-caching fixes are implemented in `0.3.0a2`;
|
|
209
|
+
the second-`init` row is targeted for later pre-releases. Each one is documented in [`MIGRATION.md`](MIGRATION.md) and covered by a
|
|
210
|
+
regression test when implemented.
|
|
211
|
+
|
|
212
|
+
| Version | Change | Why | Status |
|
|
213
|
+
|---|---|---|---|
|
|
214
|
+
| 0.3.0 | Error `Response` objects (status >= 400) are not cached | A cached 404 could be returned as 200 | Implemented in `0.3.0a1` |
|
|
215
|
+
| 0.3.0 | Opt-in `TypedJsonCoder` decodes cached JSON into the annotated return type on Pydantic v2 | Default `JsonCoder` and Pydantic v1 keep the legacy decoded behavior; `TypedJsonCoder` propagates validation errors | Implemented in `0.3.0a1` |
|
|
216
|
+
| 0.3.0 | Authenticated requests bypass the cache by default | Prevent cross-user response reuse | Implemented in `0.3.0a2` |
|
|
217
|
+
| 0.3.0 | ETag is stable across processes and correctly quoted | `hash()` is randomized per process and the old header was invalid | Implemented in `0.3.0a2` |
|
|
218
|
+
| 0.3.0 | `clear(key=...)` deletes only that key | It used to delete the whole prefix namespace | Implemented in `0.3.0a1` |
|
|
219
|
+
| 0.3.0 | `clear("app:user")` does not delete `app:users` | Namespace matching requires the `:` boundary | Implemented in `0.3.0a1` |
|
|
220
|
+
| 0.3.0 | Redis Cluster namespace clear raises `NotImplementedError` | Partial/unsafe clearing was not reliable | Implemented in `0.3.0a1` |
|
|
221
|
+
| 0.3.0 | `expire=None` means no expiration in `InMemoryBackend` | It used to expire almost immediately | Implemented in `0.3.0a2` |
|
|
222
|
+
| 0.3.0 | `InMemoryBackend` instances do not share state | The class-level store leaked entries between instances | Implemented in `0.3.0a2` |
|
|
223
|
+
| 0.3.0 | `Cache-Control` never emits `max-age=None` or `max-age=-1` | Invalid headers | Implemented in `0.3.0a2` |
|
|
224
|
+
| 0.3.0 | User payloads with a `_spec_type` key are not interpreted as internal metadata | The marker collided with user data | Implemented in `0.3.0a2` |
|
|
225
|
+
| 0.3.0 | Only simple `JSONResponse` objects are cached by `JsonCoder`; other responses bypass | Status/headers/body were lost or corrupted | Implemented in `0.3.0a2` |
|
|
226
|
+
| 0.3.0 | Responses with `Set-Cookie`, `Cache-Control: no-store/private`, or a background task are never cached | Cookies and private data could be replayed to other clients | Implemented in `0.3.0a2` |
|
|
227
|
+
| 0.3.0 | Injected `response` metadata is checked before cache reads and writes | Dict/list responses could cache cookies, private data, custom statuses, or custom headers | Implemented in `0.3.0a2` |
|
|
228
|
+
| 0.3.0 | A second `FastAPICache.init(...)` is not a silent no-op | Configuration was impossible to change | Targeted |
|
|
229
|
+
|
|
230
|
+
## Cache data compatibility
|
|
231
|
+
|
|
232
|
+
- **ETag:** the value changes once. The new value is a stable SHA-256 digest; clients may
|
|
233
|
+
revalidate after upgrading.
|
|
234
|
+
- **Key format:** if a release changes the default key format, old entries become
|
|
235
|
+
unreachable. Flush the cache namespace after upgrading.
|
|
236
|
+
- **Error responses:** old cached error entries may remain until their TTL expires. Flush
|
|
237
|
+
the cache namespace if you were affected.
|
|
238
|
+
- **Authenticated responses:** entries written by versions that cached authenticated requests
|
|
239
|
+
under the default key may remain. Clear or rotate the cache namespace before deploying the
|
|
240
|
+
bypass, including all instances/workers and persistent Redis caches. The bypass is not
|
|
241
|
+
retroactive.
|
|
242
|
+
- **InMemory:** data is process-local and is lost on restart. Instances no longer share a
|
|
243
|
+
store; a new backend after `FastAPICache.reset()` starts empty. No data-format migration.
|
|
244
|
+
- **Pydantic/dataclass values:** old entries encoded as plain JSON still decode; the
|
|
245
|
+
annotated type is restored on read. No flush required for this fix alone.
|
|
246
|
+
- **`_spec_type`:** the internal marker changed to `__fastapi_cache_spec_type__`. Old entries
|
|
247
|
+
written with `_spec_type` are treated as user data; flush the namespace if you cache
|
|
248
|
+
`datetime`/`date`/`Decimal` values.
|
|
249
|
+
|
|
250
|
+
## How compatibility is tested
|
|
251
|
+
|
|
252
|
+
- API signature tests for the public names above.
|
|
253
|
+
- Characterization tests for the normal GET success path.
|
|
254
|
+
- Auth/privacy tests for default bypass, opt-in isolation, backend non-access, and legacy
|
|
255
|
+
cache-entry invalidation.
|
|
256
|
+
- InMemory tests for `expire=None`, instance isolation, clear isolation, and decorator
|
|
257
|
+
default-expire behavior.
|
|
258
|
+
- Regression tests for every behavior change.
|
|
259
|
+
- CI tests Python 3.10–3.13 with resolver-selected FastAPI and Pydantic versions.
|
|
260
|
+
- A `legacy-compat` job tests Python 3.8/3.9 with FastAPI 0.111.1 and Pydantic 1.10.27/2.8.2,
|
|
261
|
+
plus Python 3.10/3.11 with Pydantic 1.10.27.
|
|
262
|
+
- A `legacy-smoke` job builds the wheel and installs it on Python 3.8 with Pydantic 1.10.27.
|
|
263
|
+
- Wheel and sdist smoke tests in a clean virtual environment.
|
|
264
|
+
- Redis 7 integration tests run in CI; Memcached and DynamoDB backend integration tests are
|
|
265
|
+
planned.
|
|
266
|
+
- Migration tests that install the package and run a small app.
|
|
267
|
+
|
|
268
|
+
## If we break something
|
|
269
|
+
|
|
270
|
+
We treat a compatibility break as a bug:
|
|
271
|
+
|
|
272
|
+
1. Open an issue (when issues are enabled) or a private security advisory for a
|
|
273
|
+
vulnerability.
|
|
274
|
+
2. Document the break and the rollback path in `MIGRATION.md`.
|
|
275
|
+
3. Publish a patch release with a regression test.
|
|
276
|
+
4. If the break is unavoidable, announce it before the release and provide a migration path.
|
|
277
|
+
|
|
278
|
+
## Not covered by this contract
|
|
279
|
+
|
|
280
|
+
- Private APIs of FastAPI, Starlette or Pydantic.
|
|
281
|
+
- Behavior of optional backends marked experimental.
|
|
282
|
+
- Undocumented attributes such as `FastAPICache._backend` or `_enable`.
|
|
283
|
+
- Exact cache key strings, ETag values, header ordering or log messages.
|
|
284
|
+
- Performance characteristics.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Fork origin
|
|
2
|
+
|
|
3
|
+
This project is a community-maintained fork of fastapi-cache (PyPI: `fastapi-cache2`),
|
|
4
|
+
originally by long2ice and contributors:
|
|
5
|
+
|
|
6
|
+
https://github.com/long2ice/fastapi-cache
|
|
7
|
+
|
|
8
|
+
- Baseline: `v0.2.2` (2024-07-24).
|
|
9
|
+
- License: Apache-2.0 (see `LICENSE`).
|
|
10
|
+
- This fork is not affiliated with or endorsed by the original author.
|
|
11
|
+
- The `fastapi_cache` import and public API are preserved for drop-in compatibility.
|
|
12
|
+
- Changes are documented in `CHANGELOG.md`.
|