docs(cache): state that @cache goes below the route decorator - #340
Merged
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
With
@cachewritten 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.[!IMPORTANT]callout with a short ✅/❌ example, linking to the new section.docs/HTTP_CACHING.md: a new "Decorator order" subsection under "The@cachedecorator". It explains why the order matters (decorators apply bottom-up, and FastAPI registers whatever reaches the route decorator), shows a ✅/❌ example, and notes thatadd_api_routemust be given the decorated function.i18n/zh-TW/docs/index.mdandi18n/zh-TW/docs/HTTP_CACHING.md({#decorator-order}anchor, no line breaks inside Chinese paragraphs).CACHE_FLOW.mdhas 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 theAPIRouteholding it, and@cachehas no reference to any app or router, so it could only find one by scanning.gc.get_referrers(func)does find theAPIRoute/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.@cachefor another route (app.add_api_route("/raw", f)plusapp.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_cachexuv run ruff check,uv run mypy fastapi_cachex --strictuv run pre-commit run --all-fileszensical buildfor both the English and zh-TW sites; the callout and its code block renderCloses #324