Fix cookie_expires documentation to clarify boolean behavior and correct default value

[Copilot]

The cookie_expires documentation was incorrect: stated default was "never expiring" when it's actually True (session cookie), and boolean behavior was unclear. Fixes #116 and #31.

Changes

• session.py: Updated docstrings for Session and CookieSession classes with complete type semantics:

  • True (default): session cookie, expires when browser closes
  • False: never expires (year 2038)
  • datetime/timedelta/int: specific expiration
  • Added note distinguishing cookie_expires (browser-side) from timeout (server-side)

• configuration.rst: Fixed default value, clarified boolean meanings, documented timedelta type

Example

# Session cookie (expires when browser closes) - this is the DEFAULT
SessionMiddleware(app, {'session.cookie_expires': True})

# "Never" expires (year 2038)
SessionMiddleware(app, {'session.cookie_expires': False})

# Expires in 5 minutes
SessionMiddleware(app, {'session.cookie_expires': 300})

Original prompt

---

This section details on the original issue you should resolve

<issue_title>beaker.session class documentation wrong about cookie_expires (expiration of the session cookie)</issue_title>
<issue_description>The documentation of session.beaker specifies its cookie_expires parameter as follows:

Expiration date for cookie

Just looking at the defaults suffices to see this is incorrect. In reality, the value can also be a boolean (false or true) or a duration. The code of _set_cookie_expires() confirms the above definition is highly misleading.

Moreover, there is no explanation of how cookie_expires relates to timeout.

Ticket #116 tracks that even the Configuration documentation page is incomplete on the topic, and ticket #31 tracks that it is wrong.

</issue_description>

<agent_instructions>Study the behaviour of the class, the issue and any other linked issue and fix the documentation and docstring accordingly</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes beaker.session class documentation wrong about cookie_expires (expiration of the session cookie) #240

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.