fastapi-cache-stable 0.3.0a2__tar.gz → 0.3.0b1__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.
Files changed (23) hide show
  1. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/CHANGELOG.md +40 -0
  2. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/COMPATIBILITY.md +12 -8
  3. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/MIGRATION.md +77 -38
  4. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/PKG-INFO +24 -17
  5. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/README.md +22 -15
  6. fastapi_cache_stable-0.3.0b1/SECURITY.md +18 -0
  7. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/fastapi_cache/__init__.py +8 -2
  8. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/fastapi_cache/decorator.py +9 -10
  9. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/pyproject.toml +30 -3
  10. fastapi_cache_stable-0.3.0a2/SECURITY.md +0 -15
  11. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/FORK_ORIGIN.md +0 -0
  12. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/LICENSE +0 -0
  13. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/NOTICE +0 -0
  14. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/SUPPORT.md +0 -0
  15. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/fastapi_cache/backends/__init__.py +0 -0
  16. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/fastapi_cache/backends/dynamodb.py +0 -0
  17. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/fastapi_cache/backends/inmemory.py +0 -0
  18. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/fastapi_cache/backends/memcached.py +0 -0
  19. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/fastapi_cache/backends/redis.py +0 -0
  20. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/fastapi_cache/coder.py +0 -0
  21. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/fastapi_cache/key_builder.py +0 -0
  22. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/fastapi_cache/py.typed +0 -0
  23. {fastapi_cache_stable-0.3.0a2 → fastapi_cache_stable-0.3.0b1}/fastapi_cache/types.py +0 -0
@@ -8,6 +8,46 @@ This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the chang
8
8
 
9
9
  <!-- towncrier release notes start -->
10
10
 
11
+ ## [0.3.0b1](https://github.com/agustin18/fastapi-cache/tree/v0.3.0b1) - 2026-11-16
12
+
13
+ ### Bugfixes
14
+
15
+ - `FastAPICache.init()` now raises `RuntimeError` when called a second time instead of
16
+ silently keeping the first configuration. Call `FastAPICache.reset()` before
17
+ re-initializing, or pass the keyword-only `force=True` to replace the current configuration
18
+ explicitly. Applications that call `init()` from a lifespan handler must pass `force=True`
19
+ or reset first, because the handler runs on every startup. The bundled examples do this.
20
+
21
+ The decorator now resolves the coder and expiry per request instead of overwriting the
22
+ values captured at decoration time, so a re-initialization also applies to endpoints that
23
+ were already called. Reusing the same backend and namespace across coders can leave
24
+ entries in an incompatible format; flush or rotate the namespace when the coder changes. [#18](https://github.com/agustin18/fastapi-cache/issues/18)
25
+
26
+ ### Improved Documentation
27
+
28
+ - Add GitHub issue forms for bug reports and feature requests, with a template chooser that
29
+ links to the support policy, migration guide, compatibility contract and private
30
+ vulnerability reporting. Blank issues are disabled so reports arrive with the information
31
+ needed to triage them.
32
+
33
+ Enable GitHub Issues for the repository and point every bug-reporting reference at a real
34
+ channel instead of "when issues are enabled". Security reports continue to use private
35
+ vulnerability reporting, never a public issue. The security response targets are now stated
36
+ as best-effort targets rather than contractual guarantees. [#20](https://github.com/agustin18/fastapi-cache/issues/20)
37
+
38
+ ### Misc
39
+
40
+ - Remove the unused `tox.ini` and the `tox` development dependency. CI already runs the
41
+ supported matrix through GitHub Actions, and `CONTRIBUTING.md` documents `pip`, `pytest`,
42
+ Ruff and pre-commit instead of tox, so the tox file only declared a stale Python 3.7-3.11
43
+ matrix that no longer matched reality.
44
+
45
+ Add unit tests for the Memcached and DynamoDB backends using fake clients, and run them in a
46
+ new `optional-backends` CI job. They cover key encoding, get/set, TTL handling and the
47
+ unimplemented `clear`. Both backends remain Experimental: there are no integration tests
48
+ against a real service, and `MemcachedBackend.get_with_ttl()` still returns a fixed `3600`
49
+ instead of the real remaining time. [#19](https://github.com/agustin18/fastapi-cache/issues/19)
50
+
11
51
  ## [0.3.0a2](https://github.com/agustin18/fastapi-cache/tree/v0.3.0a2) - 2026-11-14
12
52
 
13
53
  ### Bugfixes
@@ -156,8 +156,8 @@ Status definitions:
156
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
157
  | Redis Cluster | Unsupported for namespace clear | Key-only clear is supported; namespace clear raises `NotImplementedError`; no complete namespace clearing |
158
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 |
159
+ | Memcached | Experimental | Unit tests with a fake client; `get_with_ttl` returns a fixed `3600` instead of the real remaining time; `clear` raises `NotImplementedError` |
160
+ | DynamoDB | Experimental | Unit tests with a fake client covering get/set, TTL and the expired-entry path; `clear` raises `NotImplementedError`; the client cleanup issue remains open and is targeted for a future fix |
161
161
  | Import `fastapi_cache` | Verified | Covered by compatibility tests |
162
162
 
163
163
  > Redis results in `0.3.0a2` cover Redis 7 with redis-py 4.6.0. Other client or server
@@ -186,7 +186,9 @@ or a background task are never cached. The injected `response` object is checked
186
186
  cache read and before a write; those directives, a non-`200` status, or any header other than
187
187
  the automatic `content-length` bypass the cache for dict/list returns.
188
188
 
189
- Targeted for later pre-releases: explicit re-`init()` and the Redis client/server matrix.
189
+ Merged on `stable`, ships in `0.3.0b1`: a second `FastAPICache.init()` call raises
190
+ `RuntimeError` unless you pass `force=True`. In the published `0.3.0a2` it is still a silent
191
+ no-op. Still targeted for later pre-releases: the Redis client/server matrix.
190
192
 
191
193
  ### Clear semantics
192
194
 
@@ -206,7 +208,7 @@ Targeted for later pre-releases: explicit re-`init()` and the Redis client/serve
206
208
  These are bug fixes targeted for `0.3.0`. The error-response, typed-decode and
207
209
  clear-semantics fixes are implemented in `0.3.0a1`; the auth/privacy, InMemory,
208
210
  `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
211
+ the second-`init` row is merged on `stable` and ships in `0.3.0b1`. Each one is documented in [`MIGRATION.md`](MIGRATION.md) and covered by a
210
212
  regression test when implemented.
211
213
 
212
214
  | Version | Change | Why | Status |
@@ -225,7 +227,7 @@ regression test when implemented.
225
227
  | 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
228
  | 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
229
  | 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 |
230
+ | 0.3.0 | A second `FastAPICache.init(...)` is not a silent no-op | Configuration was impossible to change | Merged on `stable`; ships in `0.3.0b1` |
229
231
 
230
232
  ## Cache data compatibility
231
233
 
@@ -261,15 +263,17 @@ regression test when implemented.
261
263
  plus Python 3.10/3.11 with Pydantic 1.10.27.
262
264
  - A `legacy-smoke` job builds the wheel and installs it on Python 3.8 with Pydantic 1.10.27.
263
265
  - 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
+ - Redis 7 integration tests run in CI.
267
+ - Memcached and DynamoDB have unit tests with fake clients in CI (`optional-backends` job).
268
+ They cover key encoding, get/set, TTL handling and the unimplemented `clear`. They do not
269
+ use a real service, so both backends stay Experimental.
266
270
  - Migration tests that install the package and run a small app.
267
271
 
268
272
  ## If we break something
269
273
 
270
274
  We treat a compatibility break as a bug:
271
275
 
272
- 1. Open an issue (when issues are enabled) or a private security advisory for a
276
+ 1. Open an issue with the bug report form, or use private vulnerability reporting for a
273
277
  vulnerability.
274
278
  2. Document the break and the rollback path in `MIGRATION.md`.
275
279
  3. Publish a patch release with a regression test.
@@ -14,13 +14,13 @@ normal success-path behavior. Bug fixes that change edge-case behavior are liste
14
14
  are covered by regression tests. See [`COMPATIBILITY.md`](COMPATIBILITY.md) for the full
15
15
  contract.
16
16
 
17
- > **Status:** this guide describes `0.3.0a2` and the target `0.3.0` behavior. `0.3.0a2`
18
- > implements the error-response fix, the opt-in `TypedJsonCoder`, the `clear()` fixes, the
19
- > legacy compatibility matrix, the auth/privacy bypass, the InMemory
20
- > `expire=None`/instance-isolation fixes, the `Cache-Control` fix, the stable ETag, the
21
- > `_spec_type` namespacing and the non-JSON response bypass. The second-`init` fix is targeted
22
- > for a later `0.3.0` pre-release. Check the installed version before relying on a behavior
23
- > listed here.
17
+ > **Status:** this guide describes `0.3.0b1` and the target `0.3.0` behavior. `0.3.0b1`
18
+ > keeps every behavior from `0.3.0a2` and adds an explicit second-`init()` contract: a second
19
+ > `FastAPICache.init()` call raises `RuntimeError` unless you pass `force=True`. Call it once
20
+ > at application startup (for example in the FastAPI `lifespan`), or call
21
+ > `FastAPICache.reset()` before reconfiguring. See
22
+ > [Second `init()` call](#second-init-call). Check the installed version before relying on a
23
+ > behavior listed here.
24
24
 
25
25
  ## Who should migrate
26
26
 
@@ -52,7 +52,6 @@ for Pydantic v1 models and annotations that cannot be represented by a Pydantic
52
52
  ## Who should not migrate yet
53
53
 
54
54
  - You need full Memcached or DynamoDB parity. They are experimental in `0.3.x`.
55
- - You need the second-`init` fix; it is targeted for a later `0.3.0` pre-release.
56
55
  - You use Redis Cluster and need complete namespace clearing.
57
56
  - You need typed restoration on Pydantic v1; the legacy decoded behavior is preserved instead.
58
57
  Pydantic v1 is end-of-life; plan an upgrade to Pydantic v2 for typed restoration and
@@ -62,13 +61,13 @@ for Pydantic v1 models and annotations that cannot be represented by a Pydantic
62
61
 
63
62
  ## Install
64
63
 
65
- `0.3.0a2` is a pre-release. Install the exact version:
64
+ `0.3.0b1` is a pre-release. Install the exact version:
66
65
 
67
66
  ```sh
68
67
  pip uninstall -y fastapi-cache2
69
- pip install "fastapi-cache-stable==0.3.0a2"
68
+ pip install "fastapi-cache-stable==0.3.0b1"
70
69
  # with extras:
71
- pip install "fastapi-cache-stable[redis]==0.3.0a2"
70
+ pip install "fastapi-cache-stable[redis]==0.3.0b1"
72
71
  ```
73
72
 
74
73
  Do **not** install both distributions in the same environment: they provide the same
@@ -81,18 +80,17 @@ python -c "import fastapi_cache; print(fastapi_cache.__version__)"
81
80
  python -c "from fastapi_cache import FastAPICache; print('ok')"
82
81
  ```
83
82
 
84
- ### Alpha installation from TestPyPI
83
+ ### Pre-release installation from TestPyPI
85
84
 
86
- `0.3.0a2` is the next pre-release; it will be published to TestPyPI and PyPI. The previous
87
- `0.3.0a1` is already published. TestPyPI is a separate index and may not have all
88
- dependencies. To verify the exact artifact uploaded to TestPyPI, download it from that index
89
- and install the local wheel:
85
+ Pre-releases are published to TestPyPI and PyPI. TestPyPI is a separate index and may not
86
+ have all dependencies. To verify the exact artifact uploaded to TestPyPI, download it from
87
+ that index and install the local wheel:
90
88
 
91
89
  ```sh
92
90
  python -m pip download --no-deps --only-binary=:all: \
93
91
  --index-url https://test.pypi.org/simple/ \
94
92
  -d testpypi-dist \
95
- "fastapi-cache-stable==0.3.0a2"
93
+ "fastapi-cache-stable==0.3.0b1"
96
94
 
97
95
  python -m pip install testpypi-dist/*.whl
98
96
  python -m pip check
@@ -100,7 +98,8 @@ python -c "import fastapi_cache; print(fastapi_cache.__version__)"
100
98
  ```
101
99
 
102
100
  Dependencies are resolved from PyPI by the normal install of the wheel. TestPyPI is for
103
- validating the distribution, not for production. The same version is also published to PyPI.
101
+ validating the distribution, not for production. After that verification, the same version is
102
+ published separately to PyPI.
104
103
 
105
104
  ## Compatibility matrix
106
105
 
@@ -127,15 +126,15 @@ validating the distribution, not for production. The same version is also publis
127
126
 
128
127
  > The Redis integration job installs the resolver-selected `redis` version from the project
129
128
  > constraint (`^4.2.0rc1`), currently 4.6.0, and runs against a Redis 7 service. Other client
130
- > or server versions are not verified in `0.3.0a2`.
129
+ > or server versions are not verified in `0.3.0b1`.
131
130
 
132
131
  ## Behavior changes in 0.3.0
133
132
 
134
133
  These are intentional bug fixes targeted for `0.3.0`. `0.3.0a1` implements the error-response,
135
134
  typed-decode and clear-semantics fixes; `0.3.0a2` implements the auth/privacy bypass, the
136
- InMemory, `Cache-Control`, ETag, `_spec_type` and non-JSON fixes. The remaining changes are
137
- targeted for later pre-releases. Each one has a regression test and is listed here so you can
138
- decide whether it affects you.
135
+ InMemory, `Cache-Control`, ETag, `_spec_type` and non-JSON fixes; `0.3.0b1` implements the
136
+ explicit second-`init()` contract. Each one has a regression test and is listed here so you
137
+ can decide whether it affects you.
139
138
 
140
139
  | Change | Before (0.2.2) | After (0.3.0) | Status |
141
140
  |---|---|---|---|
@@ -150,11 +149,12 @@ decide whether it affects you.
150
149
  | `Cache-Control` | Could emit `max-age=None` or `max-age=-1` | Only valid values; `max-age` is omitted when no valid expiry exists | Implemented in 0.3.0a2 |
151
150
  | `_spec_type` | User payloads with that key raised `TypeError` | Internal marker is namespaced as `__fastapi_cache_spec_type__`; user data is preserved | Implemented in 0.3.0a2 |
152
151
  | Response caching | Streaming/file/redirect and metadata-bearing `JSONResponse` could be cached incorrectly | `JsonCoder` caches only simple `200`/`application/json` `JSONResponse`; other responses bypass; `PickleCoder` bypasses streaming/file/template; `Set-Cookie`, `Cache-Control: no-store/private` and background tasks never cache | Implemented in 0.3.0a2 |
153
- | Second `init` | Silent no-op | Reconfiguration is explicit and documented | Targeted |
152
+ | Second `init` | Silent no-op | Reconfiguration is explicit: `reset()` or `force=True` | Implemented in 0.3.0b1 |
154
153
 
155
154
  The error-response, typed-decode and clear-semantics fixes are implemented in `0.3.0a1`.
156
155
  The auth/privacy bypass, InMemory, `Cache-Control`, ETag, `_spec_type` and non-JSON fixes are
157
- implemented in `0.3.0a2`. The second-`init` row is targeted for a later `0.3.0` pre-release.
156
+ implemented in `0.3.0a2`. The second-`init` fix is implemented in `0.3.0b1`; no alpha
157
+ contains it.
158
158
 
159
159
  ### Authenticated requests
160
160
 
@@ -299,6 +299,42 @@ administrative operation; do not expose it to untrusted input. If the ETag chang
299
299
  revalidate once. If you previously cached responses with cookies or private data, flush the
300
300
  namespace as well.
301
301
 
302
+ ### Second `init()` call
303
+
304
+ In `0.3.0a1` and `0.3.0a2`, a second `FastAPICache.init()` was a silent no-op: the first
305
+ configuration stayed active and the new arguments were ignored. In `0.3.0b1` a second call
306
+ raises `RuntimeError`.
307
+
308
+ ```python
309
+ FastAPICache.init(InMemoryBackend(), prefix="first")
310
+
311
+ # Raises RuntimeError: init() was already called
312
+ FastAPICache.init(InMemoryBackend(), prefix="second")
313
+
314
+ # Explicit replacement
315
+ FastAPICache.init(InMemoryBackend(), prefix="second", force=True)
316
+
317
+ # Or reset first
318
+ FastAPICache.reset()
319
+ FastAPICache.init(InMemoryBackend(), prefix="second")
320
+ ```
321
+
322
+ **Action required:** if you call `init()` from a lifespan handler, pass `force=True`, because
323
+ the handler runs on every startup in the same process (for example under `TestClient` or a
324
+ reloader). If you relied on the silent no-op to keep the first configuration, remove the
325
+ second call or guard it with your own flag. `reset()` clears configuration only; it does not
326
+ delete cached data.
327
+
328
+ `force=True` replaces the global configuration; it does not release resources owned by the
329
+ previous backend (for example a Redis connection pool). Close those yourself on shutdown.
330
+ It also does not isolate two FastAPI applications running in the same process: the
331
+ configuration stays global.
332
+
333
+ Changing the coder while reusing the same backend and namespace can leave entries in an
334
+ incompatible format. For example, `PickleCoder` bytes cannot be decoded by `JsonCoder`, and
335
+ the read raises `UnicodeDecodeError`. Flush or rotate the namespace when you change the
336
+ coder; the library does not delete data automatically.
337
+
302
338
  ## Step by step
303
339
 
304
340
  1. **Inventory.** Note your `fastapi-cache2` version, backend, return types, `clear` usage,
@@ -312,8 +348,8 @@ namespace as well.
312
348
  5. **Run tests.** Expect changes in error responses and `clear()` in `0.3.0a1`; in `0.3.0a2`,
313
349
  authenticated requests bypass the cache, InMemory expiry/isolation changes apply, the ETag
314
350
  format changes once, `_spec_type` user payloads are preserved, and non-JSON responses
315
- bypass the cache. The second-`init` change remains targeted. Update asserts with the
316
- documented behavior.
351
+ bypass the cache. A second `init()` now raises `RuntimeError` unless you pass `force=True`.
352
+ Update asserts with the documented behavior.
317
353
  6. **Flush if needed.** If the key format or ETag changed, clear the old namespace. For the
318
354
  auth bypass, clearing or rotating the namespace is required, not optional.
319
355
  7. **Observe.** Compare HIT/MISS, latency, errors and memory with your baseline.
@@ -336,14 +372,15 @@ restore cache entries written with the new format; they are regenerated.
336
372
  **Can I install both packages?** No, not in the same environment.
337
373
  **What happens to my cached data?** If the key format or ETag changed, entries are
338
374
  regenerated. Flush the namespace if you were affected by an error-response or clear bug.
339
- **Is `0.3.0a2` production-ready?** No. It is an alpha for migration and distribution testing.
340
- **What is implemented in `0.3.0a2`?** Error responses are not cached, opt-in `TypedJsonCoder`
341
- for Pydantic v2, `clear()` key/namespace semantics, the legacy compatibility matrix, the
342
- auth/privacy bypass, the InMemory fixes, `Cache-Control`, the stable ETag, `_spec_type`
343
- preservation, and the non-JSON response bypass.
344
- **What is still missing?** Explicit re-`init()` is targeted for a later `0.3.0` pre-release.
345
- The auth/privacy, InMemory, `Cache-Control`, ETag, `_spec_type` and non-JSON fixes are
346
- implemented in `0.3.0a2`.
375
+ **Is `0.3.0b1` production-ready?** No. It is a beta for migration and distribution testing.
376
+ Test it against your own application before relying on it.
377
+ **What is implemented in `0.3.0b1`?** Everything from `0.3.0a2`: error responses are not
378
+ cached, opt-in `TypedJsonCoder` for Pydantic v2, `clear()` key/namespace semantics, the
379
+ legacy compatibility matrix, the auth/privacy bypass, the InMemory fixes, `Cache-Control`,
380
+ the stable ETag, `_spec_type` preservation, and the non-JSON response bypass. It also adds
381
+ the explicit second-`init()` contract.
382
+ **What is still missing?** `0.3.0` final is not released. Memcached and DynamoDB remain
383
+ experimental with unit-level coverage only, and DynamoDB `clear` is still not implemented.
347
384
  **Is Pydantic v1 supported?** Migration compatibility only. Pydantic v1 is end-of-life
348
385
  (1.10.27 is the final release) and receives no new security fixes. Typed restoration requires
349
386
  Pydantic v2.
@@ -355,13 +392,15 @@ clearing is not promised.
355
392
  DynamoDB `clear` is not implemented and the client cleanup issue remains open.
356
393
  **Is this an official successor?** No. It is an independent fork, not endorsed by the
357
394
  original author.
358
- **How do I report a bug?** Use the fork's issues (when enabled) or a private security
359
- advisory for vulnerabilities.
395
+ **How do I report a bug?** Open an issue on the fork and pick the bug report form. For a
396
+ vulnerability, use [private vulnerability reporting](https://github.com/agustin18/fastapi-cache/security/advisories/new)
397
+ instead of a public issue; see [SECURITY.md](SECURITY.md).
360
398
 
361
399
  ## Known limitations in 0.3.x
362
400
 
363
401
  - No tags, stale-while-revalidate, stampede protection or POST caching.
364
- - The second-`init` fix is not in `0.3.0a2`; it is targeted for a later `0.3.0` pre-release.
402
+ - A second `FastAPICache.init()` call raises `RuntimeError`; pass `force=True` or call
403
+ `FastAPICache.reset()` first. This is implemented in `0.3.0b1` and is not in the alphas.
365
404
  The auth/privacy, InMemory, `Cache-Control`, ETag, `_spec_type` and non-JSON fixes are
366
405
  implemented in `0.3.0a2`.
367
406
  - Redis standalone is verified with Redis 7 and redis-py 4.6.0; redis-py 5/6 are not
@@ -397,7 +436,7 @@ advisory for vulnerabilities.
397
436
  `Set-Cookie`, `Cache-Control: no-store/private`, or a background task are never cached
398
437
  (implemented in `0.3.0a2`).
399
438
  - [x] `_spec_type` user payloads are preserved (implemented in `0.3.0a2`).
400
- - [ ] A second `init()` is explicit.
439
+ - [x] A second `init()` is explicit (merged on `stable`; ships in `0.3.0b1`).
401
440
 
402
441
  ## See also
403
442
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: fastapi-cache-stable
3
- Version: 0.3.0a2
3
+ Version: 0.3.0b1
4
4
  Summary: Community-maintained, drop-in stable fork of fastapi-cache2
5
5
  License: Apache-2.0
6
6
  License-File: LICENSE
@@ -9,7 +9,7 @@ Keywords: fastapi,cache,caching
9
9
  Author: Agustin Saiz
10
10
  Author-email: agustinsaiz02@gmail.com
11
11
  Requires-Python: >=3.8,<4.0
12
- Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Development Status :: 4 - Beta
13
13
  Classifier: Framework :: FastAPI
14
14
  Classifier: License :: OSI Approved :: Apache Software License
15
15
  Classifier: Programming Language :: Python :: 3
@@ -43,16 +43,17 @@ Description-Content-Type: text/markdown
43
43
  # fastapi-cache-stable
44
44
 
45
45
  > **Community-maintained stable fork of fastapi-cache2.**
46
- > This is an alpha (`0.3.0a2`) based on `v0.2.2`. It is experimental and not recommended for
47
- > production. The `fastapi_cache` import and public API are unchanged.
46
+ > This is a beta (`0.3.0b1`) based on `v0.2.2`. It is experimental and still not recommended
47
+ > for production. The `fastapi_cache` import and public API are unchanged.
48
48
  > See [COMPATIBILITY.md](COMPATIBILITY.md), [MIGRATION.md](MIGRATION.md), [SUPPORT.md](SUPPORT.md),
49
49
  > [SECURITY.md](SECURITY.md) and [FORK_ORIGIN.md](FORK_ORIGIN.md). Not affiliated with the original author.
50
50
 
51
- > **Implemented in this alpha:** error responses are not cached, opt-in `TypedJsonCoder` for
51
+ > **Implemented in this beta:** error responses are not cached, opt-in `TypedJsonCoder` for
52
52
  > Pydantic v2, the `clear()` fixes, the auth/privacy bypass, the InMemory
53
53
  > `expire=None`/instance-isolation fixes, the `Cache-Control` fix, the stable ETag, the
54
- > `_spec_type` namespacing and the non-JSON response bypass. The second-`init` fix remains
55
- > targeted for a later `0.3.0` pre-release; see [MIGRATION.md](MIGRATION.md).
54
+ > `_spec_type` namespacing, the non-JSON response bypass, and an explicit second
55
+ > `FastAPICache.init()` call that raises unless you pass `force=True`. See
56
+ > [MIGRATION.md](MIGRATION.md).
56
57
 
57
58
  > **Branch model:** `stable` is the only maintained and release branch. `main` mirrors the
58
59
  > upstream project and is not a second development branch.
@@ -74,10 +75,11 @@ backends supporting Redis, Memcached, and Amazon DynamoDB.
74
75
  requests. `Cache-Control` emits only valid `max-age` values, and ETags are stable,
75
76
  quoted weak validators.
76
77
 
77
- > **Alpha caveat:** `0.3.0a2` includes the auth/privacy bypass, the InMemory
78
+ > **Beta caveat:** `0.3.0b1` includes the auth/privacy bypass, the InMemory
78
79
  > `expire=None`/instance-isolation fixes, the `Cache-Control` fix, the stable ETag, the
79
- > `_spec_type` namespacing, and the non-JSON response bypass. The second-`init` fix remains
80
- > targeted for a later `0.3.0` pre-release. See [COMPATIBILITY.md](COMPATIBILITY.md).
80
+ > `_spec_type` namespacing, the non-JSON response bypass, and explicit re-configuration
81
+ > through `FastAPICache.reset()` or `force=True`. Memcached and DynamoDB remain
82
+ > experimental. See [COMPATIBILITY.md](COMPATIBILITY.md).
81
83
 
82
84
  ## Requirements
83
85
 
@@ -88,28 +90,28 @@ backends supporting Redis, Memcached, and Amazon DynamoDB.
88
90
 
89
91
  ## Install
90
92
 
91
- `0.3.0a2` is a pre-release. Install the exact version:
93
+ `0.3.0b1` is a pre-release. Install the exact version:
92
94
 
93
95
  ```shell
94
- > pip install "fastapi-cache-stable==0.3.0a2"
96
+ > pip install "fastapi-cache-stable==0.3.0b1"
95
97
  ```
96
98
 
97
99
  or
98
100
 
99
101
  ```shell
100
- > pip install "fastapi-cache-stable[redis]==0.3.0a2"
102
+ > pip install "fastapi-cache-stable[redis]==0.3.0b1"
101
103
  ```
102
104
 
103
105
  or
104
106
 
105
107
  ```shell
106
- > pip install "fastapi-cache-stable[memcache]==0.3.0a2"
108
+ > pip install "fastapi-cache-stable[memcache]==0.3.0b1"
107
109
  ```
108
110
 
109
111
  or
110
112
 
111
113
  ```shell
112
- > pip install "fastapi-cache-stable[dynamodb]==0.3.0a2"
114
+ > pip install "fastapi-cache-stable[dynamodb]==0.3.0b1"
113
115
  ```
114
116
 
115
117
  ## Usage
@@ -134,7 +136,7 @@ from redis import asyncio as aioredis
134
136
  @asynccontextmanager
135
137
  async def lifespan(_: FastAPI) -> AsyncIterator[None]:
136
138
  redis = aioredis.from_url("redis://localhost")
137
- FastAPICache.init(RedisBackend(redis), prefix="fastapi-cache")
139
+ FastAPICache.init(RedisBackend(redis), prefix="fastapi-cache", force=True)
138
140
  yield
139
141
 
140
142
 
@@ -154,7 +156,12 @@ async def index():
154
156
 
155
157
  ### Initialization
156
158
 
157
- First you must call `FastAPICache.init` during startup FastAPI startup; this is where you set global configuration.
159
+ First you must call `FastAPICache.init` during FastAPI startup; this is where you set global configuration.
160
+
161
+ `init()` runs once per process. A second call raises `RuntimeError` instead of silently
162
+ keeping the first configuration: call `FastAPICache.reset()` before re-initializing, or pass
163
+ `force=True` to replace it explicitly. Lifespan handlers run on every startup, so pass
164
+ `force=True` there if the handler may run more than once in the same process.
158
165
 
159
166
  ### Use the `@cache` decorator
160
167
 
@@ -1,16 +1,17 @@
1
1
  # fastapi-cache-stable
2
2
 
3
3
  > **Community-maintained stable fork of fastapi-cache2.**
4
- > This is an alpha (`0.3.0a2`) based on `v0.2.2`. It is experimental and not recommended for
5
- > production. The `fastapi_cache` import and public API are unchanged.
4
+ > This is a beta (`0.3.0b1`) based on `v0.2.2`. It is experimental and still not recommended
5
+ > for production. The `fastapi_cache` import and public API are unchanged.
6
6
  > See [COMPATIBILITY.md](COMPATIBILITY.md), [MIGRATION.md](MIGRATION.md), [SUPPORT.md](SUPPORT.md),
7
7
  > [SECURITY.md](SECURITY.md) and [FORK_ORIGIN.md](FORK_ORIGIN.md). Not affiliated with the original author.
8
8
 
9
- > **Implemented in this alpha:** error responses are not cached, opt-in `TypedJsonCoder` for
9
+ > **Implemented in this beta:** error responses are not cached, opt-in `TypedJsonCoder` for
10
10
  > Pydantic v2, the `clear()` fixes, the auth/privacy bypass, the InMemory
11
11
  > `expire=None`/instance-isolation fixes, the `Cache-Control` fix, the stable ETag, the
12
- > `_spec_type` namespacing and the non-JSON response bypass. The second-`init` fix remains
13
- > targeted for a later `0.3.0` pre-release; see [MIGRATION.md](MIGRATION.md).
12
+ > `_spec_type` namespacing, the non-JSON response bypass, and an explicit second
13
+ > `FastAPICache.init()` call that raises unless you pass `force=True`. See
14
+ > [MIGRATION.md](MIGRATION.md).
14
15
 
15
16
  > **Branch model:** `stable` is the only maintained and release branch. `main` mirrors the
16
17
  > upstream project and is not a second development branch.
@@ -32,10 +33,11 @@ backends supporting Redis, Memcached, and Amazon DynamoDB.
32
33
  requests. `Cache-Control` emits only valid `max-age` values, and ETags are stable,
33
34
  quoted weak validators.
34
35
 
35
- > **Alpha caveat:** `0.3.0a2` includes the auth/privacy bypass, the InMemory
36
+ > **Beta caveat:** `0.3.0b1` includes the auth/privacy bypass, the InMemory
36
37
  > `expire=None`/instance-isolation fixes, the `Cache-Control` fix, the stable ETag, the
37
- > `_spec_type` namespacing, and the non-JSON response bypass. The second-`init` fix remains
38
- > targeted for a later `0.3.0` pre-release. See [COMPATIBILITY.md](COMPATIBILITY.md).
38
+ > `_spec_type` namespacing, the non-JSON response bypass, and explicit re-configuration
39
+ > through `FastAPICache.reset()` or `force=True`. Memcached and DynamoDB remain
40
+ > experimental. See [COMPATIBILITY.md](COMPATIBILITY.md).
39
41
 
40
42
  ## Requirements
41
43
 
@@ -46,28 +48,28 @@ backends supporting Redis, Memcached, and Amazon DynamoDB.
46
48
 
47
49
  ## Install
48
50
 
49
- `0.3.0a2` is a pre-release. Install the exact version:
51
+ `0.3.0b1` is a pre-release. Install the exact version:
50
52
 
51
53
  ```shell
52
- > pip install "fastapi-cache-stable==0.3.0a2"
54
+ > pip install "fastapi-cache-stable==0.3.0b1"
53
55
  ```
54
56
 
55
57
  or
56
58
 
57
59
  ```shell
58
- > pip install "fastapi-cache-stable[redis]==0.3.0a2"
60
+ > pip install "fastapi-cache-stable[redis]==0.3.0b1"
59
61
  ```
60
62
 
61
63
  or
62
64
 
63
65
  ```shell
64
- > pip install "fastapi-cache-stable[memcache]==0.3.0a2"
66
+ > pip install "fastapi-cache-stable[memcache]==0.3.0b1"
65
67
  ```
66
68
 
67
69
  or
68
70
 
69
71
  ```shell
70
- > pip install "fastapi-cache-stable[dynamodb]==0.3.0a2"
72
+ > pip install "fastapi-cache-stable[dynamodb]==0.3.0b1"
71
73
  ```
72
74
 
73
75
  ## Usage
@@ -92,7 +94,7 @@ from redis import asyncio as aioredis
92
94
  @asynccontextmanager
93
95
  async def lifespan(_: FastAPI) -> AsyncIterator[None]:
94
96
  redis = aioredis.from_url("redis://localhost")
95
- FastAPICache.init(RedisBackend(redis), prefix="fastapi-cache")
97
+ FastAPICache.init(RedisBackend(redis), prefix="fastapi-cache", force=True)
96
98
  yield
97
99
 
98
100
 
@@ -112,7 +114,12 @@ async def index():
112
114
 
113
115
  ### Initialization
114
116
 
115
- First you must call `FastAPICache.init` during startup FastAPI startup; this is where you set global configuration.
117
+ First you must call `FastAPICache.init` during FastAPI startup; this is where you set global configuration.
118
+
119
+ `init()` runs once per process. A second call raises `RuntimeError` instead of silently
120
+ keeping the first configuration: call `FastAPICache.reset()` before re-initializing, or pass
121
+ `force=True` to replace it explicitly. Lifespan handlers run on every startup, so pass
122
+ `force=True` there if the handler may run more than once in the same process.
116
123
 
117
124
  ### Use the `@cache` decorator
118
125
 
@@ -0,0 +1,18 @@
1
+ # Security policy
2
+
3
+ ## Supported versions
4
+
5
+ - `0.3.x`: security fixes.
6
+ - `1.x`: security fixes (planned).
7
+
8
+ ## Reporting a vulnerability
9
+
10
+ Use GitHub private vulnerability reporting:
11
+
12
+ https://github.com/agustin18/fastapi-cache/security/advisories/new
13
+
14
+ Do not open a public issue for security reports.
15
+
16
+ Response targets, on a best-effort basis for a single maintainer: acknowledge within about
17
+ 3 business days and share a remediation plan within about 10 business days. These are
18
+ targets, not contractual guarantees; see `SUPPORT.md` for the support policy.
@@ -39,9 +39,15 @@ class FastAPICache:
39
39
  cache_status_header: str = "X-FastAPI-Cache",
40
40
  enable: bool = True,
41
41
  cache_authenticated: bool = False,
42
+ *,
43
+ force: bool = False,
42
44
  ) -> None:
43
- if cls._init:
44
- return
45
+ if cls._init and not force:
46
+ raise RuntimeError(
47
+ "FastAPICache.init() was already called. Call FastAPICache.reset() "
48
+ "before re-initializing, or pass force=True to replace the current "
49
+ "configuration explicitly."
50
+ )
45
51
  cls._init = True
46
52
  cls._backend = backend
47
53
  cls._prefix = prefix
@@ -247,9 +247,6 @@ def cache(
247
247
 
248
248
  @wraps(func)
249
249
  async def inner(*args: P.args, **kwargs: P.kwargs) -> Union[R, Response]:
250
- nonlocal coder
251
- nonlocal expire
252
-
253
250
  async def ensure_async_func(*args: P.args, **kwargs: P.kwargs) -> R:
254
251
  """Run cached sync functions in thread pool just like FastAPI."""
255
252
  # if the wrapped function does NOT have request or response in
@@ -286,8 +283,8 @@ def cache(
286
283
  if has_auth_headers and not cache_authenticated_enabled:
287
284
  return await ensure_async_func(*args, **kwargs)
288
285
 
289
- coder = coder or FastAPICache.get_coder()
290
- expire = expire or FastAPICache.get_expire()
286
+ effective_coder = coder or FastAPICache.get_coder()
287
+ effective_expire = expire or FastAPICache.get_expire()
291
288
  effective_key_builder = key_builder or FastAPICache.get_key_builder()
292
289
  if (
293
290
  has_auth_headers
@@ -338,12 +335,12 @@ def cache(
338
335
  return result
339
336
  if _injected_response_cache_bypass(response):
340
337
  return result
341
- if not coder.can_encode(result):
338
+ if not effective_coder.can_encode(result):
342
339
  return result
343
- to_cache = coder.encode(result)
340
+ to_cache = effective_coder.encode(result)
344
341
 
345
342
  try:
346
- await backend.set(cache_key, to_cache, expire)
343
+ await backend.set(cache_key, to_cache, effective_expire)
347
344
  except Exception as exc:
348
345
  logger.warning(
349
346
  "Error setting cache entry for %s.%s in namespace %r "
@@ -360,7 +357,7 @@ def cache(
360
357
  "ETag": etag,
361
358
  cache_status_header: "MISS",
362
359
  }
363
- cache_control = _cache_control_header(expire)
360
+ cache_control = _cache_control_header(effective_expire)
364
361
  if cache_control is not None:
365
362
  headers["Cache-Control"] = cache_control
366
363
  response.headers.update(headers)
@@ -385,7 +382,9 @@ def cache(
385
382
  response.status_code = HTTP_304_NOT_MODIFIED
386
383
  return response
387
384
 
388
- result = cast(R, coder.decode_as_type(cached, type_=return_type))
385
+ result = cast(
386
+ R, effective_coder.decode_as_type(cached, type_=return_type)
387
+ )
389
388
 
390
389
  return result
391
390
 
@@ -1,6 +1,6 @@
1
1
  [tool.poetry]
2
2
  name = "fastapi-cache-stable"
3
- version = "0.3.0a2"
3
+ version = "0.3.0b1"
4
4
  description = "Community-maintained, drop-in stable fork of fastapi-cache2"
5
5
  authors = ["Agustin Saiz <agustinsaiz02@gmail.com>"]
6
6
  license = "Apache-2.0"
@@ -10,7 +10,7 @@ repository = "https://github.com/agustin18/fastapi-cache.git"
10
10
  documentation = "https://github.com/agustin18/fastapi-cache#readme"
11
11
  keywords = ["fastapi", "cache", "caching"]
12
12
  classifiers = [
13
- "Development Status :: 3 - Alpha",
13
+ "Development Status :: 4 - Beta",
14
14
  "Framework :: FastAPI",
15
15
  "License :: OSI Approved :: Apache Software License",
16
16
  "Programming Language :: Python :: 3",
@@ -64,7 +64,6 @@ pytest = "*"
64
64
  requests = "*"
65
65
  coverage = ">=6.5,<8.0"
66
66
  httpx = "*"
67
- tox = "^4.5.1"
68
67
  towncrier = { version = ">=26,<27", python = ">=3.9" }
69
68
 
70
69
  [tool.poetry.group.distributing]
@@ -112,6 +111,34 @@ template = "changelog.d/changelog_template.jinja"
112
111
  title_format = "## [{version}](https://github.com/agustin18/fastapi-cache/tree/v{version}) - {project_date}"
113
112
  issue_format = "[#{issue}](https://github.com/agustin18/fastapi-cache/issues/{issue})"
114
113
 
114
+ # Declare every fragment type explicitly. The built-in default hides the content of `misc`
115
+ # fragments, which renders an empty bullet as soon as the fragment carries an issue number.
116
+ # Keep this list in sync with the fragment types documented in CONTRIBUTING.md.
117
+ [[tool.towncrier.type]]
118
+ directory = "feature"
119
+ name = "Features"
120
+ showcontent = true
121
+
122
+ [[tool.towncrier.type]]
123
+ directory = "bugfix"
124
+ name = "Bugfixes"
125
+ showcontent = true
126
+
127
+ [[tool.towncrier.type]]
128
+ directory = "doc"
129
+ name = "Improved Documentation"
130
+ showcontent = true
131
+
132
+ [[tool.towncrier.type]]
133
+ directory = "removal"
134
+ name = "Deprecations and Removals"
135
+ showcontent = true
136
+
137
+ [[tool.towncrier.type]]
138
+ directory = "misc"
139
+ name = "Misc"
140
+ showcontent = true
141
+
115
142
  [tool.pyright]
116
143
  strict = ["fastapi_cache", "tests"]
117
144
  pythonVersion = "3.10"
@@ -1,15 +0,0 @@
1
- # Security policy
2
-
3
- ## Supported versions
4
-
5
- - `0.3.x`: security fixes.
6
- - `1.x`: security fixes (planned).
7
-
8
- ## Reporting a vulnerability
9
-
10
- Use GitHub private vulnerability reporting:
11
-
12
- https://github.com/agustin18/fastapi-cache/security/advisories/new
13
-
14
- Do not open a public issue for security reports. We aim to acknowledge within
15
- 3 business days and provide a remediation plan within 10 business days.