Skip to content

docs(state): correct state, migration, development and example docs against master - #367

Merged
allen0099 merged 1 commit into
masterfrom
docs/audit-state-dev
Sep 29, 2026
Merged

allen0099 merged 1 commit into
masterfrom
docs/audit-state-dev

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Docs and docstring accuracy audit for OAuth state, the 0.4.0 migration guide, the development guide and the examples, checked against master. Docs and docstrings/comments only; no code change (AST-compared against master).

Corrections

docs/MIGRATING_0_4.md (+ zh-TW)

  • Redis encoding: the page said any encoding emits a DeprecationWarning. In backends/redis.py (_warn_encoding), only a UTF-8 alias passed to AsyncRedisCacheBackend gets the DeprecationWarning; any other value gets only a RuntimeWarning (whose message announces the removal). A RedisConfig that sets encoding warns in load_from_config() (DeprecationWarning, plus the RuntimeWarning for non-UTF-8). The summary table row now names the RuntimeWarning too.
  • Monitoring routes: the UserWarning for a missing dependencies is new in 0.3.9, not "0.3.x".

docs/STATE.md (+ zh-TW)

  • The INFO-logging note applies to consume_state(); validate_state() / get_state_metadata() log a missing or expired state at DEBUG.
  • InvalidStateError in the exception tree also covers a binding mismatch.

docs/DEVELOPMENT.md

  • Opted-out coverage figures: a run with no live servers measures about 94.5% total and 42% for redis.py (was 92.2% / 27%).
  • "Checking that a test can fail": git stash -- fastapi_cachex/ reverts changes rather than creating a mutation; the block now says to edit a function and restore with git checkout.
  • Release steps: the release body starts with the notice when there is one; the GitHub release is created from release-notes.md, to which the workflow appends the installation snippet and (with a previous tag) the compare link.

Docstrings and comments

  • fastapi_cachex/state/manager.py: the module/class docstrings no longer mention session state; __init__ and create_state document TypeError (float/bool TTL) and ValueError above MAX_TTL (from validate_ttl); consume_state notes that backend errors propagate (Memcached's CacheXError after repeated CAS conflicts).
  • fastapi_cachex/state/exceptions.py: InvalidStateError mentions a binding mismatch.
  • scripts/changelog_release.py: the module docstring mentions the notice copied to the top of the release body.
  • examples/session_redis.py, examples/session_jwt.py: in 0.3.9, ClientIPDep gets the manager the middleware registered on app.state and warns when the proxy holds a different one. Only 0.4.0 resolves it through the proxy.
  • examples/redis_backend.py: the lifespan creates the client, which connects lazily; it does not connect on startup.

Possible code issues (not changed here)

  • fastapi_cachex/state/manager.py _decode_state (return StateData(**state_dict)): stored JSON that is valid but not an object (for example [1, 2]) raises TypeError instead of StateDataError, so validate_state() / get_state_metadata() raise instead of returning False / None.
  • changelog.d/126.deprecated.md says any encoding passed to AsyncRedisCacheBackend gets a DeprecationWarning; a non-UTF-8 value gets only the RuntimeWarning.

@allen0099
allen0099 merged commit ab3983e into master Sep 29, 2026
12 checks passed
@allen0099
allen0099 deleted the docs/audit-state-dev branch September 29, 2026 08:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant