beaker.session – Session classes

Module Contents

class beaker.session.CookieSession(request, key='beaker.session.id', timeout=None, save_accessed_time=True, cookie_expires=True, cookie_domain=None, cookie_path='/', encrypt_key=None, validate_key=None, secure=False, httponly=False, data_serializer='pickle', encrypt_nonce_bits=128, invalidate_corrupt=False, crypto_type='default', samesite='Lax', **kwargs)

Pure cookie-based session

Options recognized when using cookie-based sessions are slightly more restricted than general sessions.

Parameters:

  • key – The name the cookie should be set to.

  • timeout (int) – How long session data is considered valid. This is used regardless of the cookie being present or not to determine whether session data is still valid.

  • save_accessed_time – Whether beaker should save the session’s access time (True) or only modification time (False). Defaults to True.

  • cookie_expires (bool, datetime, timedelta, or int) – 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).

  • cookie_domain – Domain to use for the cookie.

  • cookie_path – Path to use for the cookie.

  • data_serializer – If "json" or "pickle" should be used to serialize data. Can also be an object with loads` and ``dumps methods. By default "pickle" is used.

  • secure – Whether or not the cookie should only be sent over SSL.

  • httponly – Whether or not the cookie should only be accessible by the browser not by JavaScript.

  • encrypt_key – The key to use for the local session encryption, if not provided the session will not be encrypted.

  • validate_key – The key used to sign the local encrypted session

  • invalidate_corrupt (bool) – How to handle corrupt data when loading. When set to True, then corrupt data will be silently invalidated and a new session created, otherwise invalid data will cause an exception.

  • crypto_type – The crypto module to use.

  • samesite – SameSite value for the cookie – should be either ‘Lax’, ‘Strict’, or None.

delete()

Delete the cookie, and clear the session

invalidate()

Clear the contents and start a new session

save(accessed_only=False)

Saves the data for this session to persistent storage

class beaker.session.Session(request, id=None, invalidate_corrupt=False, use_cookies=True, type=None, data_dir=None, key='beaker.session.id', timeout=None, save_accessed_time=True, cookie_expires=True, cookie_domain=None, cookie_path='/', data_serializer='pickle', secret=None, secure=False, namespace_class=None, httponly=False, encrypt_key=None, validate_key=None, encrypt_nonce_bits=128, crypto_type='default', samesite='Lax', **namespace_args)

Session object that uses container package for storage.

Parameters:

  • invalidate_corrupt (bool) – How to handle corrupt data when loading. When set to True, then corrupt data will be silently invalidated and a new session created, otherwise invalid data will cause an exception.

  • use_cookies (bool) – Whether or not cookies should be created. When set to False, it is assumed the user will handle storing the session on their own.

  • type – What data backend type should be used to store the underlying session data

  • key – The name the cookie should be set to.

  • timeout (int or None) – How long session data is considered valid. This is used regardless of the cookie being present or not to determine whether session data is still valid. Can be set to None to disable session time out.

  • save_accessed_time – Whether beaker should save the session’s access time (True) or only modification time (False). Defaults to True.

  • cookie_expires (bool, datetime, timedelta, or int) – 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).

  • cookie_domain – Domain to use for the cookie.

  • cookie_path – Path to use for the cookie.

  • data_serializer – If "json" or "pickle" should be used to serialize data. Can also be an object with loads` and ``dumps methods. By default "pickle" is used.

  • secure – Whether or not the cookie should only be sent over SSL.

  • httponly – Whether or not the cookie should only be accessible by the browser not by JavaScript.

  • encrypt_key – The key to use for the local session encryption, if not provided the session will not be encrypted.

  • validate_key – The key used to sign the local encrypted session

  • encrypt_nonce_bits – Number of bits used to generate nonce for encryption key salt. For security reason this is 128bits be default. If you want to keep backward compatibility with sessions generated before 1.8.0 set this to 48.

  • crypto_type – encryption module to use

  • samesite – SameSite value for the cookie – should be either ‘Lax’, ‘Strict’, or None.

delete()

Clear the current session contents and expire its cookie, if enabled.

SessionMiddleware persists the cleared session and sends the expired cookie at response start. Physical removal of the back-end record is not guaranteed.

invalidate()

Invalidates this session, creates a new session id, returns to the is_new state

lock()

Locks this session against other processes/threads. This is automatic when load/save is called.

*use with caution* and always with a corresponding ‘unlock’ inside a “finally:” block, as a stray lock typically cannot be unlocked without shutting down the whole application.

regenerate_id()

creates a new session id, retains all session data

Its a good security practice to regenerate the id after a client elevates privileges.

revert()

Revert the session to its original state from its first access in the request

save(accessed_only=False)

Saves the data for this session to persistent storage

If accessed_only is True, then only the original data loaded at the beginning of the request will be saved, with the updated last accessed time.

unlock()

Unlocks this session against other processes/threads. This is automatic when load/save is called.

*use with caution* and always within a “finally:” block, as a stray lock typically cannot be unlocked without shutting down the whole application.

class beaker.session.SessionObject(environ, **params)

Session proxy/lazy creator

This object proxies access to the actual session object, so that in the case that the session hasn’t been used before, it will be setup. This avoid creating and loading the session from persistent storage unless its actually used during the request.

accessed()

Returns whether or not the session has been accessed

get_by_id(id)

Loads a session given a session ID

persist()

Persist the session to the storage

Always saves the whole session if save() or delete() have been called. If they haven’t:

  • If autosave is set to true, saves the the entire session regardless.

  • If save_accessed_time is set to true or unset, only saves the updated access time.

  • If save_accessed_time is set to false, doesn’t save anything.

class beaker.session.SignedCookie(secret, input=None)

Extends python cookie to give digital signature support

beaker.session.InvalidSignature = <beaker.session._InvalidSignatureType object>

Returned from SignedCookie when the value’s signature was invalid.