[Django] #32129: Confusing documentation on how to get cookie's time until it expires in seconds.
Django
seconds.
-----------------------------------------+---------------------------------
Reporter: mangelozzi | Owner: nobody
Type: Uncategorized | Status: new
Component: Uncategorized | Version: 3.1
Severity: Normal | Keywords: session cookies
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
-----------------------------------------+---------------------------------
Firstly, I find the django documentation to be first class, and superb,
some of the best I have ever read. The following is what I percieve to be
a weak point in the otherwise brillant docs:
A common use case is trying to get the number of seconds left until a
cookie expires.
This method sounds like it:
get_session_cookie_age()
Returns the age of session cookies, in seconds. Defaults to
SESSION_COOKIE_AGE.
The description sounds like it returns the age of a cookie, and if not
set, defaults to SESSION_COOKIE_AGE. But looking into the code:
{{{
def get_session_cookie_age(self):
return settings.SESSION_COOKIE_AGE
}}}
Should not the documentation be updated to saying something along the
lines of "Returns the value of the SESSION_COOKIE_AGE setting."
There theres:
get_expiry_age()¶
Returns the number of seconds until this session expires.
A reasonable way of interpretting the phrase "until this sessons expires"
is to believe it returns the time between now and when the cookie expires
in seconds. Maybe we could update the documentation to be something like
"Returns the total expiry age or lifespan in seconds, the time from when
it was set until when it expires".
If I have it wrong, maybe the documentation could be updated to clarify
how the methods work.
I have been reading the following:
-
[https://docs.djangoproject.com/en/3.1/topics/http/sessions/#django.contrib.sessions.backends.base.SessionBase.get_expiry_age]
- [https://stackoverflow.com/questions/27059630/session-get-expiry-age-
never-decreases]
- [https://code.djangoproject.com/ticket/18458]
Other things that confuse me:
`get_expiry_age()` What is the use case of passing in `modification` ?
How would one know when it last modified other than now? And the `expiry`
arg? It says "expiry information for the session", is that not what one is
trying to get from the method? If one knew the expiry information why
would one pass it in to get it back? To me it sounds like I need to pass
information from `get_expiry_date` into `get_expirary_age()` but the
`get_expirary_age` documentation says:
> This function accepts the same keyword arguments as get_expiry_age().
Which then means one doesnt get the `expiry` from either of the two.
Sorry if I am not smart enough to understand how it works. But as I read
around there seems to be others also confused. Is it possible to get the
time in seconds from the current point in time until a session expires
without writing custom functions? It's okay if theres not, just seems like
there is from the documentation.
--
Ticket URL: <https://code.djangoproject.com/ticket/32129>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
seconds.
Reporter: mangelozzi | Owner: nobody
Type: Uncategorized | Status: new
Component: Uncategorized | Version: 3.1
Keywords: session cookies | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by mangelozzi):
Answers like this: [https://stackoverflow.com/a/11423845/5506400] show a
misunderstanding of how these methods work.
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:1>
Django
seconds.
Reporter: mangelozzi | Owner: nobody
Type: Uncategorized | Status: new
Component: Uncategorized | Version: 3.1
Keywords: session cookies | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Description changed by mangelozzi:
Old description:
New description:
There theres:
- Answers like this: [https://stackoverflow.com/a/11423845/5506400] show
a misunderstanding of how these methods work.
Other things that confuse me:
`get_expiry_age()` What is the use case of passing in `modification` ?
How would one know when it last modified other than now? And the `expiry`
arg? It says "expiry information for the session", is that not what one is
trying to get from the method? If one knew the expiry information why
would one pass it in to get it back? To me it sounds like I need to pass
information from `get_expiry_date` into `get_expirary_age()` but the
`get_expirary_age` documentation says:
> This function accepts the same keyword arguments as get_expiry_age().
Which then means one doesnt get the `expiry` from either of the two.
Sorry if I am not smart enough to understand how it works. But as I read
around there seems to be others also confused. Is it possible to get the
time in seconds from the current point in time until a session expires
without writing custom functions? It's okay if theres not, just seems like
there is from the documentation.
--
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:2>
Django
seconds.
Reporter: mangelozzi | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 3.1
Severity: Normal | Resolution:
Keywords: session cookies | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Changes (by Carlton Gibson):
* type: Uncategorized => Cleanup/optimization
* component: Uncategorized => Documentation
* easy: 1 => 0
* stage: Unreviewed => Accepted
Comment:
OK, it’s a bit ill-defined, but I’m happy to take this as a request for
clarification on the docs here.
I’m going to remove the ''Easy pickings'' flag, as I think it’s a decent
mini-project to sit down, review, and correctly rephrase the descriptions
here.
(Fun, but not a nothing project.)
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:3>
Django
seconds.
Reporter: mangelozzi | Owner: Sourabh
Type: | Rana
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 3.1
Severity: Normal | Resolution:
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Changes (by Sourabh Rana):
* owner: nobody => Sourabh Rana
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:4>
Django
seconds.
Reporter: mangelozzi | Owner: Sourabh
Type: | Rana
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 3.1
Severity: Normal | Resolution:
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Changes (by Sourabh Rana):
* cc: Sourabh Rana (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:5>
Django
seconds.
Reporter: Michael | Owner: Sourabh
Type: | Rana
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 3.1
Severity: Normal | Resolution:
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Comment (by Michael):
Thanks so much!
Some reading material which may help to illustrate how the community
perceives how it is used:
Here the accepted answer is incorrect once again (I am `run_the_race`
commenting that I don't think its quite right):
- [https://stackoverflow.com/posts/27059826/timeline]
Here I got a answer on what I was working on:
- [https://stackoverflow.com/questions/64466605/django-how-to-get-the-
time-until-a-cookie-expires/64484904#64484904]
Here's the original post from above (compiled them all together for easy
navigation) (upvoted quite a few times, but is incorrect).
- [https://stackoverflow.com/questions/3044799/in-django-how-to-renew-
expiry-date-for-current-session/11423845#11423845]
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:6>
Django
seconds.
Reporter: Michael | Owner: (none)
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: 3.1
Severity: Normal | Resolution:
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
* owner: nobody => (none)
* status: new => assigned
Comment:
I'm happy to pick this up, will try to submit a patch next week
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:7>
Django
seconds.
Reporter: Michael | Owner: (none)
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: 3.1
Severity: Normal | Resolution:
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Changes (by Sarah Boyce):
* has_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:8>
Django
seconds.
Reporter: Michael | Owner: (none)
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: 3.1
Severity: Normal | Resolution:
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Comment (by Sarah Boyce):
Submitted a patch:
https://github.com/django/django/pull/15549#issuecomment-1079767354
The wording is quite hard to get right so happy for any feedback
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:9>
Django
seconds.
Reporter: Michael | Owner: (none)
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: 3.1
Severity: Normal | Resolution:
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Comment (by Michael):
Thanks so much!
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:10>
Django
seconds.
Reporter: Michael | Owner: Sarah
Type: | Boyce
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 3.1
Severity: Normal | Resolution:
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
* owner: (none) => Sarah Boyce
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:11>
Django
seconds.
Reporter: Michael | Owner: Sarah
Type: | Boyce
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 3.1
Severity: Normal | Resolution:
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* needs_better_patch: 0 => 1
Comment:
> What is the use case of passing in modification ?
That's needed in order to get the remaining time, rather than the ''max
age'', which is what these methods are originally for.
Comment from Aymeric #18458:
> I recently worked on this code and came to the conclusion that
get_expiry_age and get_expiry_date are designed to work at the time when
the session is saved, and not at any other point in time.
https://code.djangoproject.com/ticket/18458#comment:2
Adding the `modification` parameter allows working out the remaining time
(modulo a certain expiry) — the commit for #18458 notes it as a testing
aid, and for allowing file backed session invalidation.
The interesting thing with the file case if you can stat for the
`modified` where otherwise you don't really have that in hand... 🤔
I've left a
[https://github.com/django/django/pull/15549#pullrequestreview-925855361
comment on PR]
Last bit:
> Overall, perhaps an admonition steering people away from this API would
be better: assuming I've got modification in hand (which I need for this
use-case) I think I'd just do:
>
> expires_at = modification +
timedelta(seconds=settings.SESSION_COOKIE_AGE)
>
> ... and not use these methods at all. (Loops back to comment from #18458
at the top...)
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:12>
Django
seconds.
Reporter: Michael | Owner: Sarah
Type: | Boyce
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 3.1
Severity: Normal | Resolution:
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Changes (by Carlton Gibson):
* needs_better_patch: 1 => 0
* stage: Accepted => Ready for checkin
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:13>
Django
seconds.
Reporter: Michael | Owner: Sarah
Type: | Boyce
Component: Documentation | Version: 3.1
Severity: Normal | Resolution: fixed
Keywords: session cookies | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"ae506181f7fb9d9e74f4935686540bef29b60255" ae50618]:
{{{
#!CommitTicketReference repository=""
revision="ae506181f7fb9d9e74f4935686540bef29b60255"
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.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:14>
Django
seconds.
Reporter: Michael | Owner: Sarah
Type: | Boyce
Cleanup/optimization | Status: closed
Component: Documentation | Version: 3.1
Severity: Normal | Resolution: fixed
Keywords: session cookies | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Comment (by Carlton Gibson <carlton.gibson@…>):
In [changeset:"51374161b003db263068f828537edec50129a098" 5137416]:
{{{
#!CommitTicketReference repository=""
revision="51374161b003db263068f828537edec50129a098"
[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
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32129#comment:15>