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

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

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

[Michael]

Answers like this: ​https://stackoverflow.com/a/11423845/5506400 show a misunderstanding of how these methods work.

[Carlton Gibson]

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

[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

[Sarah Boyce]

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

[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

[Michael]

Thanks so much!

[Carlton Gibson]

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 is you can stat for the modified 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...)

[Carlton Gibson <carlton@…>]

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.

[Carlton Gibson <carlton.gibson@…>]

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