[1.5.x] Added optional kwargs to get_expiry_age/date.

This change allows for cleaner tests: we can test the exact output.

Refs #18194: this change makes it possible to compute session expiry
dates at times other than when the session is saved.

Fixed #18458: the existence of the `modification` kwarg implies that you
must pass it to get_expiry_age/date if you call these functions outside
of a short request - response cycle (the intended use case).

Backport of cd17a24 from master.

1 files changed, 11 insertions, 0 deletions

diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt
index 0082b75db1..1e043405f4 100644
--- a/docs/topics/http/sessions.txt
+++ b/docs/topics/http/sessions.txt
@@ -250,12 +250,23 @@ You can edit it multiple times.
       with no custom expiration (or those set to expire at browser close), this
       will equal :setting:`SESSION_COOKIE_AGE`.
 
+      This function accepts two optional keyword arguments:
+
+      - ``modification``: last modification of the session, as a
+        :class:`~datetime.datetime` object. Defaults to the current time.
+      - ``expiry``: expiry information for the session, as a
+        :class:`~datetime.datetime` object, an :class:`int` (in seconds), or
+        ``None``. Defaults to the value stored in the session by
+        :meth:`set_expiry`, if there is one, or ``None``.
+
     .. method:: get_expiry_date
 
       Returns the date this session will expire. For sessions with no custom
       expiration (or those set to expire at browser close), this will equal the
       date :setting:`SESSION_COOKIE_AGE` seconds from now.
 
+      This function accepts the same keyword argumets as :meth:`get_expiry_age`.
+
     .. method:: get_expire_at_browser_close
 
       Returns either ``True`` or ``False``, depending on whether the user's