0.5.0: remove session and OAuth state, lower the dependency floors, migrating from fastapi-cache2

[allen0099]

Fixes #421
Fixes #423

Warning

Do not merge until 0.4.x is finished. release.yml releases only from master, so merging this ends 0.4.x patch releases. The pending 0.4.2 fragments (#242, #248, #252, #253, #334, #335) would then ship in 0.5.0 instead.

Summary

#421: remove session and OAuth state (feat! commit, plus a fix commit)

• Removed: fastapi_cachex.session and fastapi_cachex.state, deprecated in 0.4.0 (Deprecate fastapi_cachex.session and fastapi_cachex.state; remove them in 0.5.0 #420). This includes their tests, examples, docs pages (en and zh-TW), API reference pages, nav entries, the lazy deprecated names, _deprecation.py, and the jwt extra / PyJWT. Removed names now raise AttributeError / ModuleNotFoundError.
• @cache: only Authorization and a non-empty request.session from any session middleware still bypass the shared backend. A plain Cookie header still does not bypass, the same as today. The bypass tests moved to tests/ and now use Starlette's SessionMiddleware.
• X-Session-Token in vary= stays hashed. The issue asked to drop this special case. Apps may still send the header under their own session scheme, and keyed on its raw value the token would show up in the Redis/Memcached keyspace, the monitoring routes and DEBUG logs. Hashing costs nothing, and keys stay the same as in 0.4.x. A general way to hash custom headers fits better with @cache: normaliser for vary= headers to bound the number of entries #310.
• Dependencies:
  • itsdangerous and the direct starlette>=1.0.0 requirement are dropped.
  • The fastapi floor goes from 0.133.0 to 0.128.2, found by bisecting with tox -e lowest:
    • 0.128.1 and older fail the dependency-Response tests.
    • 0.127.x and older hit pydantic 2.7 deprecations in OpenAPI.
  • The lowest env now pins starlette>=0.40.0, the oldest version that fastapi 0.128.2 accepts.
  • itsdangerous moved to the dev group, for the SessionMiddleware tests.
• From the issue comment: BaseCacheBackend's fallbacks read delete() with bool(). A third-party delete() that returns None now counts as not removed, with no FutureWarning.
• Docs and changelog:
  • New docs/MIGRATING_0_5.md and its zh-TW copy, with nav entries.
  • README, CLAUDE.md, SECURITY.md, CI workflows and the pre-commit mypy deps are updated.
  • Fragments: 421.removed.md, 421.removed.2.md, 421.changed.md, 421.changed.2.md.

#423: migrating from fastapi-cache2 (docs commit)

New docs/MIGRATING_FROM_FASTAPI_CACHE2.md and its zh-TW copy. It covers:

• a route before and after
• an API mapping table: FastAPICache.init, @cache(expire, namespace, key_builder, coder), the backends, FastAPICache.clear, X-FastAPI-Cache, enable
• the behaviour that differs: keys come from the request, credentialed requests bypass the cache, the client's Cache-Control is ignored, and storage is the rendered response with no pickle
• what has no equivalent

It is linked from the comparison page, both navs, the README and the zh-TW index. The fastapi-cache2 facts come from the source of 0.2.2.

Checklist

• The issues above are assigned to me (maintainer's own issues)
• Tests under tests/ cover the change. Each new test fails when the code it guards is broken; for example, removing x-session-token from the hashed headers fails test_credential_headers_are_hashed_in_any_case[session-token].
• Changelog fragments added (the docs: migrating from fastapi-cache2 (long2ice/fastapi-cache) #423 commit is docs only)
• uv run pre-commit run --all-files and uv run pytest pass:
  • pytest: 1202 passed, 192 skipped
  • coverage: 92.87%
  • mypy tests and mypy scripts: clean
  • tox -e lowest: passes
  • both zensical build --strict runs: clean