Skip to content

docs(cache): state that @cache goes below the route decorator - #340

Merged
allen0099 merged 1 commit into
masterfrom
docs/cache-decorator-order-324
Sep 28, 2026
Merged

allen0099 merged 1 commit into
masterfrom
docs/cache-decorator-order-324

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Summary

With @cache written above @app.get(...), FastAPI registers the undecorated handler and never calls the cache wrapper. The route works, but nothing is cached and nothing warns. The docs never stated the required order.

  • README quick start: an [!IMPORTANT] callout with a short ✅/❌ example, linking to the new section.
  • docs/HTTP_CACHING.md: a new "Decorator order" subsection under "The @cache decorator". It explains why the order matters (decorators apply bottom-up, and FastAPI registers whatever reaches the route decorator), shows a ✅/❌ example, and notes that add_api_route must be given the decorated function.
  • zh-TW mirrors in i18n/zh-TW/docs/index.md and i18n/zh-TW/docs/HTTP_CACHING.md ({#decorator-order} anchor, no line breaks inside Chinese paragraphs).

CACHE_FLOW.md has no usage section, so it is unchanged.

Why no runtime warning

The issue asked whether the reversed order could be detected at decoration time. No reliable, cheap signal exists:

  • app.get(...) / router.get(...) return the function unchanged, with no attribute or marker. The only link is the APIRoute holding it, and @cache has no reference to any app or router, so it could only find one by scanning.
  • gc.get_referrers(func) does find the APIRoute/Dependant, but it walks every GC-tracked object. That is tens of milliseconds per call on a large heap, and it would run for every decorated route at import time.
  • It also has false positives. Registering a function uncached on one route and wrapping it with @cache for another route (app.add_api_route("/raw", f) plus app.get("/cached")(cache(ttl=60)(f))) is legitimate, but it looks identical to the reversed order.

Because a no-false-positive check is not possible, this PR is docs-only and has no changelog fragment.

Test plan

  • uv run pytest -q --cov=fastapi_cachex
  • uv run ruff check, uv run mypy fastapi_cachex --strict
  • uv run pre-commit run --all-files
  • zensical build for both the English and zh-TW sites; the callout and its code block render

Closes #324

With @cache above @app.get(...), FastAPI registers the undecorated
handler and never calls the cache wrapper: the route works, but nothing
is cached and nothing warns. Say so in the README quick start and add a
"Decorator order" section to HTTP_CACHING.md with a correct/incorrect
example, mirrored in the zh-TW docs.

Closes #324
@allen0099 allen0099 added this to the 0.3.9 milestone Sep 28, 2026
@allen0099 allen0099 added documentation Improvements or additions to documentation http-cache The @cache decorator, cache keys and Cache-Control handling developer-experience Surprising behaviour, missing warnings or unclear errors for library users labels Sep 28, 2026
@allen0099
allen0099 merged commit 16c49ce into master Sep 28, 2026
12 checks passed
@allen0099
allen0099 deleted the docs/cache-decorator-order-324 branch September 28, 2026 05:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

developer-experience Surprising behaviour, missing warnings or unclear errors for library users documentation Improvements or additions to documentation http-cache The @cache decorator, cache keys and Cache-Control handling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

@cache above the route decorator silently caches nothing, and the order is not documented

1 participant