diff --git a/beaker/docs/configuration.rst b/beaker/docs/configuration.rst index b29f51e..a4d0d9f 100644 --- a/beaker/docs/configuration.rst +++ b/beaker/docs/configuration.rst @@ -146,17 +146,25 @@ auto (**optional**, bool) cookie_expires (**optional**, bool, datetime, timedelta, int) Determines when the cookie used to track the client-side of the session - will expire. When set to a boolean value, it will either expire at the - end of the browsers session, or never expire. + will expire. Note that this only affects when the browser discards the + cookie; it does not affect server-side session validity (see ``timeout`` + for that). - Setting to a datetime forces a hard ending time for the session (generally - used for setting a session to a far off date). + When set to ``True``, the cookie will be a session cookie that expires when + the user closes their browser. When set to ``False``, the cookie is set to + never expire (actually expires in year 2038, the maximum 32-bit timestamp). + + Setting to a datetime forces a hard ending time for the cookie (generally + used for setting a cookie to a far off date). + + Setting to a timedelta will result in the cookie expiring that duration + from the current time. Setting to an integer will result in the cookie being set to expire in that many seconds. I.e. a value of ``300`` will result in the cookie being set to expire in 300 seconds. - Defaults to never expiring. + Defaults to ``True`` (session cookie that expires when the browser closes). .. _cookie_domain_config: diff --git a/beaker/session.py b/beaker/session.py index ab3a075..93f0d0c 100644 --- a/beaker/session.py +++ b/beaker/session.py @@ -110,7 +110,19 @@ class Session(_ConfigurableSession): :param save_accessed_time: Whether beaker should save the session's access time (True) or only modification time (False). Defaults to True. - :param cookie_expires: Expiration date for cookie + :param cookie_expires: Determines when the session cookie expires. When set + to ``True`` (the default), the cookie is a session + cookie that expires when the user closes their + browser. When set to ``False``, the cookie is set to + never expire (actually expires in year 2038). Can also + be set to a ``datetime`` for a specific expiration + date, a ``timedelta`` for an expiration relative to + the current time, or an ``int`` specifying the number + of seconds until expiration. Note that ``cookie_expires`` + only affects the cookie lifetime in the browser, not + the session validity on the server side (see ``timeout`` + for server-side session expiration). + :type cookie_expires: bool, datetime, timedelta, or int :param cookie_domain: Domain to use for the cookie. :param cookie_path: Path to use for the cookie. :param data_serializer: If ``"json"`` or ``"pickle"`` should be used @@ -555,7 +567,19 @@ class CookieSession(Session): :param save_accessed_time: Whether beaker should save the session's access time (True) or only modification time (False). Defaults to True. - :param cookie_expires: Expiration date for cookie + :param cookie_expires: Determines when the session cookie expires. When set + to ``True`` (the default), the cookie is a session + cookie that expires when the user closes their + browser. When set to ``False``, the cookie is set to + never expire (actually expires in year 2038). Can also + be set to a ``datetime`` for a specific expiration + date, a ``timedelta`` for an expiration relative to + the current time, or an ``int`` specifying the number + of seconds until expiration. Note that ``cookie_expires`` + only affects the cookie lifetime in the browser, not + the session validity on the server side (see ``timeout`` + for server-side session expiration). + :type cookie_expires: bool, datetime, timedelta, or int :param cookie_domain: Domain to use for the cookie. :param cookie_path: Path to use for the cookie. :param data_serializer: If ``"json"`` or ``"pickle"`` should be used