#32129: Confusing documentation on how to get cookie's time until it expires in
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.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to django-updates+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/053.7485c4f30b0f29a40c8f7ef34f2619bb%40djangoproject.com.
