Opened 3 years ago

Closed 2 years ago

Last modified 2 years ago

#32129 closed Cleanup/optimization (fixed)

Confusing documentation on how to get cookie's time until it expires in seconds.

Reported by: Michael Owned by: Sarah Boyce
Component: Documentation Version: 3.1
Severity: Normal Keywords: session cookies
Cc: Sourabh Rana Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description (last modified by Michael)

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:

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:

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:

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.

Change History (14)

comment:1 by Michael, 3 years ago

Answers like this: show a misunderstanding of how these methods work.

comment:2 by Michael, 3 years ago

Description: modified (diff)

comment:3 by Carlton Gibson, 3 years ago

Component: UncategorizedDocumentation
Easy pickings: unset
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

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.)

comment:5 by Sourabh Rana, 3 years ago

Cc: Sourabh Rana added

comment:6 by Michael, 3 years ago

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):

Here I got a answer on what I was working on:

Here's the original post from above (compiled them all together for easy navigation) (upvoted quite a few times, but is incorrect).

comment:7 by Sarah Boyce, 2 years ago

Owner: nobody removed
Status: newassigned

I'm happy to pick this up, will try to submit a patch next week

comment:8 by Sarah Boyce, 2 years ago

Has patch: set

comment:9 by Sarah Boyce, 2 years ago

Submitted a patch:
The wording is quite hard to get right so happy for any feedback

comment:10 by Michael, 2 years ago

Thanks so much!

comment:11 by Mariusz Felisiak, 2 years ago

Owner: set to Sarah Boyce

comment:12 by Carlton Gibson, 2 years ago

Patch needs improvement: set

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.

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 is you can stat for the modification where otherwise you don't really have that in hand... 🤔

I've left a 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...)

Last edited 2 years ago by Carlton Gibson (previous) (diff)

comment:13 by Carlton Gibson, 2 years ago

Patch needs improvement: unset
Triage Stage: AcceptedReady for checkin

comment:14 by Carlton Gibson <carlton@…>, 2 years ago

Resolution: fixed
Status: assignedclosed

In ae50618:

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.

comment:15 by Carlton Gibson <carlton.gibson@…>, 2 years ago

In 5137416:

[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

Note: See TracTickets for help on using tickets.
Back to Top