Skip to content

docs(session): show a login that sets session.user - #294

Merged
allen0099 merged 1 commit into
masterfrom
docs/login-sets-session-user
Sep 27, 2026
Merged

allen0099 merged 1 commit into
masterfrom
docs/login-sets-session-user

Conversation

@allen0099

Copy link
Copy Markdown
Owner

The session guide's login examples write request.session["user_id"] = "123". That is application data: session.user stays None, so require_user_session / AuthenticatedSession answer 401 for such a session. The same guide recommends those dependencies for routes that need a logged-in user, so following it produced a login that never authenticates.

This PR documents the working pattern (found while writing examples/session_login.py, #291):

  • docs/SESSION.md section 2: states that only create_session(user=...) or assigning session.user and saving sets the user, and that request.session keys are not a login.
  • docs/SESSION.md section 5: a second example that rotates the ID, assigns session.user, and calls update_session(). The explicit save is needed because assigning session.user does not mark request.session as modified. Links to examples/session_login.py for the full version, including the cookie for a new visitor.
  • The rotate_session_id docstring gets the same note.
  • zh-TW mirrors of both guide changes.

Docs only; no behaviour change. The pattern is exercised by tests/test_examples.py (session login example).

Refs #293 (a login() helper that removes these steps, planned for 0.3.9).

CHANGELOG

Under ### Documentation:

- **Logging a user in.** The session guide now shows how to attach a
  `SessionUser` at login so `require_user_session` and
  `AuthenticatedSession` accept the session; writing to `request.session`
  alone does not.

Writing request.session["user_id"] is application data and does not
satisfy require_user_session / AuthenticatedSession. Document the
rotate, assign session.user, update_session pattern in the session
guide (EN and zh-TW) and the rotate_session_id docstring, and point to
examples/session_login.py and the planned login() helper (#293).
@allen0099 allen0099 added this to the 0.3.8 milestone Sep 27, 2026
@allen0099 allen0099 added the documentation Improvements or additions to documentation label Sep 27, 2026
@allen0099
allen0099 merged commit 9feb2e6 into master Sep 27, 2026
12 checks passed
@allen0099
allen0099 deleted the docs/login-sets-session-user branch September 27, 2026 11:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant