:py:mod:`core.session`
======================

.. py:module:: core.session


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   core.session.Session



Functions
~~~~~~~~~

.. autoapisummary::

   core.session.killSessionByUser
   core.session.start_clear_sessions



.. py:class:: Session


   Store Sessions inside the datastore.
   The behaviour of this module can be customized in the following ways:

   - :prop:same_site can be set to None, "none", "lax" or "strict" to influence the same-site tag on the cookies
       we set
   - :prop:use_session_cookie is set to True by default, causing the cookie to be treated as a session cookie
       (it will be deleted on browser close). If set to False, it will be emitted with the life-time in
       conf.user.session_life_time.
   - The config variable conf.user.session_life_time: Determines, how long (in seconds) a session is valid.
       Even if :prop:use_session_cookie is set to True, the session is voided server-side after no request has been
       made within the configured lifetime.
   - The config variables conf.user.session_persistent_fields_on_login and
       conf.user.session_persistent_fields_on_logout lists fields, that may survive a login/logout action.
       For security reasons, we completely destroy a session on login/logout (it will be deleted, a new empty
       database object will be created and a new cookie with a different key is sent to the browser). This causes
       all data currently stored to be lost. Only keys listed in these variables will be copied into the new
       session.

   .. py:attribute:: kindName
      :value: 'viur-session'

      

   .. py:attribute:: same_site
      :value: 'lax'

      

   .. py:attribute:: use_session_cookie
      :value: True

      

   .. py:attribute:: cookie_name

      

   .. py:attribute:: GUEST_USER
      :value: '__guest__'

      

   .. py:method:: load(req)

      Initializes the Session.

      If the client supplied a valid Cookie, the session is read from the datastore, otherwise a new,
      empty session will be initialized.


   .. py:method:: save(req)

      Writes the session into the database.

      Does nothing, in case the session hasn't been changed in the current request.


   .. py:method:: __contains__(key)

      Returns True if the given *key* is set in the current session.


   .. py:method:: __delitem__(key)

      Removes a *key* from the session.

      This key must exist.


   .. py:method:: __getitem__(key)

      Returns the value stored under the given *key*.

      The key must exist.


   .. py:method:: __ior__(other)

      Merges the contents of a dict into the session.


   .. py:method:: get(key, default = None)

      Returns the value stored under the given key.

      :param key: Key to retrieve from the session variables.
      :param default: Default value to return when key does not exist.


   .. py:method:: __setitem__(key, item)

      Stores a new value under the given key.

      If that key exists before, its value is
      overwritten.


   .. py:method:: markChanged()

      Explicitly mark the current session as changed.
      This will force save() to write into the datastore,
      even if it believes that this session hasn't changed.


   .. py:method:: reset()

      Invalidates the current session and starts a new one.

      This function is especially useful at login, where
      we might need to create an SSL-capable session.

      :warning: Everything is flushed.


   .. py:method:: items()

      Returns all items in the current session.



.. py:function:: killSessionByUser(user = None)

   Invalidates all active sessions for the given *user*.

   This means that this user is instantly logged out.
   If no user is given, it tries to invalidate **all** active sessions.

   Use "__guest__" to kill all sessions not associated with a user.

   :param user: UserID, "__guest__" or None.


.. py:function:: start_clear_sessions()

   Removes old (expired) Sessions