Skip to content

feat: deprecate session and OAuth state, to be removed in 0.5.0 - #426

Merged
allen0099 merged 2 commits into
masterfrom
feat/420-deprecate-session-state
Oct 2, 2026
Merged

allen0099 merged 2 commits into
masterfrom
feat/420-deprecate-session-state

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Closes #420.

fastapi_cachex.session and fastapi_cachex.state are deprecated in 0.4.0 and will be removed in 0.5.0 (#421). The package narrows to HTTP and application caching.

What changes

  • Importing fastapi_cachex.session or fastapi_cachex.state, or reading one of their names from fastapi_cachex, emits a FutureWarning once per process. The warning points at the application's own line, not at a frame inside the package or the import machinery, and links to the new migration section.
  • A plain import fastapi_cachex stays silent. The top-level session/state names are resolved lazily through a module __getattr__, are no longer in __all__, and are still visible to type checkers through a TYPE_CHECKING block. cache.py no longer imports session.config.
  • The 0.4.0 changes announced for sessions are dropped, since they would make users migrate twice:
  • Docs: MIGRATING_0_4.md has a new "Sessions and OAuth state are deprecated" section with alternatives (Starlette SessionMiddleware / starsessions, Authlib, auth-stack tokens). The session, state and JWT pages get a deprecation banner, and the nav, README and site description are updated. The zh-TW translation follows.
  • SECURITY.md: session and state receive security fixes only during 0.4.x.
  • Changelog fragment changelog.d/420.deprecated.md.

Tests

  • tests/test_session_state_deprecation.py runs each import style in a subprocess and asserts the warning's file and line. It also checks that every core module imports without a FutureWarning, that state does not import session, and that the TYPE_CHECKING imports match the lazy-name table.
  • tests/session/test_dropped_0_4_0_changes.py asserts the dropped notices stay silent.
  • pytest ignores the two deprecation messages globally, so the existing session/state tests and examples/ run as before. The warnings themselves are covered by the subprocess tests, not by test_examples.
  • Mutation-checked: re-adding a session/state import to a core module, dropping a TYPE_CHECKING line, or restoring the old notices each makes the guarding tests fail.

An independent review agent reviewed the change before this PR. Its findings are addressed in the second commit.

Importing fastapi_cachex.session or fastapi_cachex.state, or reading one of
their names from the package, emits a FutureWarning that points at the
importing line. A plain `import fastapi_cachex` no longer imports either
package: the top-level names load lazily and leave __all__, and @cache
inlines the X-Session-Token header name instead of importing it.

The migration guide, the session/state/JWT pages (English and zh-TW), the
README, the examples index and SECURITY.md say where to move.
Address review feedback on #420:
- importing fastapi_cachex no longer imports the session package
- deprecated top-level names resolve lazily and warn at the caller
- the #131 and #75 notices are dropped; #377 is removed in 0.5.0
- docs, MIGRATING_0_4 and the zh-TW translation follow
@allen0099 allen0099 added this to the 0.4.0 milestone Oct 2, 2026
@allen0099 allen0099 added enhancement New feature or request session Session management subsystem labels Oct 2, 2026
@allen0099
allen0099 merged commit b6e1b59 into master Oct 2, 2026
15 checks passed
@allen0099
allen0099 deleted the feat/420-deprecate-session-state branch October 2, 2026 12:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request session Session management subsystem

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Deprecate fastapi_cachex.session and fastapi_cachex.state; remove them in 0.5.0

1 participant