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

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.