Skip to content

refactor(cache): split cache.py into smaller modules (#422) - #436

Merged
allen0099 merged 1 commit into
masterfrom
refactor/422-split-cache
Oct 3, 2026
Merged

allen0099 merged 1 commit into
masterfrom
refactor/422-split-cache

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Closes #422.

fastapi_cachex/cache.py had grown to about 1,800 lines. This PR splits it into private modules next to it. The public API and behaviour do not change.

Module Contents
_key_builders.py build_cache_key, default_key_builder, key builder checks
_vary.py vary= validation and the key components it adds
_cache_control.py CacheControl, the decorator's Cache-Control, checks for responses that must not be shared
_stored_response.py cacheable headers, Age, ETags, 304s, the stored CacheEntry
_rendering.py running the handler, building its response, dependency headers (#233)
_callables.py whether a handler or key builder returns a coroutine
cache.py the decorator, invalidate(), the credential-bypass warnings (about 970 lines)

How

  • Every top-level definition was moved verbatim, together with its leading comments, by name.
  • A review compared the source of every moved definition on master and on this branch with ast.get_source_segment. All of them are byte-identical, with one exception: the decorator now calls the new _entry_for() instead of building the CacheEntry inline, so the clock behind stored_at and Age lives in one module.
  • Module-level state (_now, _ADAPTER_ATTR, the _BypassWarner lock) exists in exactly one place.
  • There are no import cycles.

Compatibility

  • Every name fastapi_cachex.cache defined on master is still importable from it. These names are now listed in __all__, and tests/test_cache_module.py pins them.
  • Every module that logs uses the documented fastapi_cachex.cache logger. The new test checks this too.
  • The docs/api references (fastapi_cachex.cache.cache, invalidate, default_key_builder) still resolve.
  • Names cache.py only imported for its own use are no longer reachable through fastapi_cachex.cache. For example, from fastapi_cachex.cache import CacheEntry now fails; import it from fastapi_cachex.types. Their documented homes are unchanged.
  • Private names moved, so code that monkeypatches fastapi_cachex.cache._now must patch fastapi_cachex._stored_response._now. The repository's own tests are repointed.
  • There is no changelog fragment, because behaviour does not change (changelog.d/README.md).

Docs

CACHE_FLOW.md (EN and zh-TW) no longer says that all the behaviour lives in cache.py. It now names the module for each part.

Checks

  • pre-commit
  • mypy fastapi_cachex --strict, mypy tests and mypy scripts
  • the full suite with live Redis and Memcached: 1829 passed, coverage 99.85%, each new module 100%
  • both zensical builds with --strict
  • an independent read-only review: no blockers. Two of its nits are fixed: the helper _key_builders imported from _rendering moved to _callables.py, and the __all__ comment was reworded.

cache.py held key building, vary handling, Cache-Control rendering,
stored-response handling, response rendering and the decorator in one
1,800-line file. Move each part into a private module beside it:

- _key_builders.py: build_cache_key, default_key_builder, key builder checks
- _vary.py: vary= validation and key components
- _cache_control.py: CacheControl, the decorator's header, unshareable checks
- _stored_response.py: cacheable headers, Age, ETags, 304s, the stored entry
- _rendering.py: running the handler, the response, dependency headers
- _callables.py: whether a handler or key builder returns a coroutine

cache.py keeps the decorator, invalidate() and the credential bypass, and
still exports every name it defined (now listed in __all__). Every module
logs under the documented fastapi_cachex.cache logger. The only code change
is _entry_for(), which builds the stored CacheEntry so the clock behind
stored_at and Age lives in one module. No behaviour change.
@allen0099 allen0099 added enhancement New feature or request http-cache The @cache decorator, cache keys and Cache-Control handling labels Oct 3, 2026
@allen0099
allen0099 merged commit 74a870a into master Oct 3, 2026
15 checks passed
@allen0099
allen0099 deleted the refactor/422-split-cache branch October 3, 2026 14:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request http-cache The @cache decorator, cache keys and Cache-Control handling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Split cache.py into smaller modules

1 participant