From c3ec5e45ec50ee0a16e33b2fddd5ea9793098aa7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 28 Nov 2025 22:19:02 +0000
Subject: [PATCH 1/2] Initial plan


From 962b48d747f5921e24174a5153390be5e372537c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 28 Nov 2025 22:23:17 +0000
Subject: [PATCH 2/2] Fix documentation for cookie_expires parameter

Update docstrings for Session and CookieSession classes in session.py
to properly document:
- True (default): session cookie that expires when browser closes
- False: cookie set to never expire (year 2038)
- datetime: specific expiration date
- timedelta: expiration relative to current time
- int: seconds until expiration

Also update configuration.rst with complete and accurate documentation
about cookie_expires, including the relationship to the timeout parameter.

Resolves issues #116 and #31 by clarifying boolean behavior and fixing
the incorrect default value documentation.

Co-authored-by: amol- <601423+amol-@users.noreply.github.com>
---
 beaker/docs/configuration.rst | 18 +++++++++++++-----
 beaker/session.py             | 28 ++++++++++++++++++++++++++--
 2 files changed, 39 insertions(+), 7 deletions(-)

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