diff options
| author | sarahboyce <sarahvboyce95@gmail.com> | 2022-03-26 20:54:48 +0100 |
|---|---|---|
| committer | Carlton Gibson <carlton.gibson@noumenal.es> | 2022-03-31 18:37:55 +0200 |
| commit | 51374161b003db263068f828537edec50129a098 (patch) | |
| tree | 05232c829e512a9901d936a9f1ab338e753580ea | |
| parent | 7d540d67a8fb17f820e1657ccb1509af86b27582 (diff) | |
[4.0.x] Fixed #32129 -- Adjusted the docs for session expiry helpers.
Updated the docs for `get_session_cookie_age`, `get_expiry_age`, and
`get_expiry_date` to clarify their intended usage by session backends
when saving the session.
Backport of ae506181f7fb9d9e74f4935686540bef29b60255 from main
| -rw-r--r-- | AUTHORS | 1 | ||||
| -rw-r--r-- | docs/topics/http/sessions.txt | 21 |
2 files changed, 19 insertions, 3 deletions
@@ -839,6 +839,7 @@ answer newbie questions, and generally made Django that much better: Sander Dijkhuis <sander.dijkhuis@gmail.com> Sanket Saurav <sanketsaurav@gmail.com> Sanyam Khurana <sanyam.khurana01@gmail.com> + Sarah Boyce <https://github.com/sarahboyce> Sarthak Mehrish <sarthakmeh03@gmail.com> schwank@gmail.com Scot Hacker <shacker@birdhouse.org> diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt index 1837ff1c6d..5ee2a34249 100644 --- a/docs/topics/http/sessions.txt +++ b/docs/topics/http/sessions.txt @@ -245,8 +245,8 @@ You can edit it multiple times. .. method:: get_session_cookie_age() - Returns the age of session cookies, in seconds. Defaults to - :setting:`SESSION_COOKIE_AGE`. + Returns the value of the setting :setting:`SESSION_COOKIE_AGE`. This can + be overridden in a custom session backend. .. method:: set_expiry(value) @@ -288,13 +288,28 @@ You can edit it multiple times. ``None``. Defaults to the value stored in the session by :meth:`set_expiry`, if there is one, or ``None``. + .. note:: + + This method is used by session backends to determine the session expiry + age in seconds when saving the session. It is not really intended for + usage outside of that context. + + In particular, while it is **possible** to determine the remaining + lifetime of a session **just when** you have the correct + ``modification`` value **and** the ``expiry`` is set as a ``datetime`` + object, where you do have the ``modification`` value, it is more + straight-forward to calculate the expiry by-hand:: + + expires_at = modification + timedelta(seconds=settings.SESSION_COOKIE_AGE) + .. method:: get_expiry_date() Returns the date this session will expire. For sessions with no custom expiration (or those set to expire at browser close), this will equal the date :setting:`SESSION_COOKIE_AGE` seconds from now. - This function accepts the same keyword arguments as :meth:`get_expiry_age`. + This function accepts the same keyword arguments as + :meth:`get_expiry_age`, and similar notes on usage apply. .. method:: get_expire_at_browser_close() |