<commit_before>===================
How to use sessions
===================

.. module:: django.contrib.sessions
   :synopsis: Provides session management for Django projects.

Django provides full support for anonymous sessions. The session framework
lets you store and retrieve arbitrary data on a per-site-visitor basis. It
stores data on the server side and abstracts the sending and receiving of
cookies. Cookies contain a session ID -- not the data itself (unless you're
using the :ref:`cookie based backend<cookie-session-backend>`).

Enabling sessions
=================

Sessions are implemented via a piece of :doc:`middleware </ref/middleware>`.

To enable session functionality, do the following:

* Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure
  it contains ``'django.contrib.sessions.middleware.SessionMiddleware'``.
  The default ``settings.py`` created by ``django-admin.py startproject``
  has ``SessionMiddleware`` activated.

If you don't want to use sessions, you might as well remove the
``SessionMiddleware`` line from :setting:`MIDDLEWARE_CLASSES` and
``'django.contrib.sessions'`` from your :setting:`INSTALLED_APPS`.
It'll save you a small bit of overhead.

Configuring the session engine
==============================

By default, Django stores sessions in your database (using the model
``django.contrib.sessions.models.Session``). Though this is convenient, in
some setups it's faster to store session data elsewhere, so Django can be
configured to store session data on your filesystem or in your cache.

Using database-backed sessions
------------------------------

If you want to use a database-backed session, you need to add
``'django.contrib.sessions'`` to your :setting:`INSTALLED_APPS` setting.

Once you have configured your installation, run ``manage.py syncdb``
to install the single database table that stores session data.

Using cached sessions
---------------------

For better performance, you may want to use a cache-based session backend.

To store session data using Django's cache system, you'll first need to make
sure you've configured your cache; see the :doc:`cache documentation
</topics/cache>` for details.

.. warning::

    You should only use cache-based sessions if you're using the Memcached
    cache backend. The local-memory cache backend doesn't retain data long
    enough to be a good choice, and it'll be faster to use file or database
    sessions directly instead of sending everything through the file or
    database cache backends.

Once your cache is configured, you've got two choices for how to store data in
the cache:

* Set :setting:`SESSION_ENGINE` to
  ``"django.contrib.sessions.backends.cache"`` for a simple caching session
  store. Session data will be stored directly your cache. However, session
  data may not be persistent: cached data can be evicted if the cache fills
  up or if the cache server is restarted.

* For persistent, cached data, set :setting:`SESSION_ENGINE` to
  ``"django.contrib.sessions.backends.cached_db"``. This uses a
  write-through cache -- every write to the cache will also be written to
  the database. Session reads only use the database if the data is not
  already in the cache.

Both session stores are quite fast, but the simple cache is faster because it
disregards persistence. In most cases, the ``cached_db`` backend will be fast
enough, but if you need that last bit of performance, and are willing to let
session data be expunged from time to time, the ``cache`` backend is for you.

If you use the ``cached_db`` session backend, you also need to follow the
configuration instructions for the `using database-backed sessions`_.

Using file-based sessions
-------------------------

To use file-based sessions, set the :setting:`SESSION_ENGINE` setting to
``"django.contrib.sessions.backends.file"``.

You might also want to set the :setting:`SESSION_FILE_PATH` setting (which
defaults to output from ``tempfile.gettempdir()``, most likely ``/tmp``) to
control where Django stores session files. Be sure to check that your Web
server has permissions to read and write to this location.

.. _cookie-session-backend:

Using cookie-based sessions
---------------------------

.. versionadded:: 1.4

To use cookies-based sessions, set the :setting:`SESSION_ENGINE` setting to
``"django.contrib.sessions.backends.cookies"``. The session data will be
stored using Django's tools for :doc:`cryptographic signing </topics/signing>`
and the :setting:`SECRET_KEY` setting.

.. note::

    It's recommended to set the :setting:`SESSION_COOKIE_HTTPONLY` setting
    to ``True`` to prevent tampering of the stored data from JavaScript.

.. warning::

    **The session data is signed but not encrypted**

    When using the cookies backend the session data can be read by the client.

    A MAC (Message Authentication Code) is used to protect the data against
    changes by the client, so that the session data will be invalidated when being
    tampered with. The same invalidation happens if the client storing the
    cookie (e.g. your user's browser) can't store all of the session cookie and
    drops data. Even though Django compresses the data, it's still entirely
    possible to exceed the `common limit of 4096 bytes`_ per cookie.

    **No freshness guarantee**

    Note also that while the MAC can guarantee the authenticity of the data
    (that it was generated by your site, and not someone else), and the
    integrity of the data (that it is all there and correct), it cannot
    guarantee freshness i.e. that you are being sent back the last thing you
    sent to the client. This means that for some uses of session data, the
    cookie backend might open you up to `replay attacks`_. Cookies will only
    detected as 'stale' if they are older than your
    :setting:`SESSION_COOKIE_AGE`.<commit_msg>Fixed typo in my last commit.<commit_after>===================
How to use sessions
===================

.. module:: django.contrib.sessions
   :synopsis: Provides session management for Django projects.

Django provides full support for anonymous sessions. The session framework
lets you store and retrieve arbitrary data on a per-site-visitor basis. It
stores data on the server side and abstracts the sending and receiving of
cookies. Cookies contain a session ID -- not the data itself (unless you're
using the :ref:`cookie based backend<cookie-session-backend>`).

Enabling sessions
=================

Sessions are implemented via a piece of :doc:`middleware </ref/middleware>`.

To enable session functionality, do the following:

* Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure
  it contains ``'django.contrib.sessions.middleware.SessionMiddleware'``.
  The default ``settings.py`` created by ``django-admin.py startproject``
  has ``SessionMiddleware`` activated.

If you don't want to use sessions, you might as well remove the
``SessionMiddleware`` line from :setting:`MIDDLEWARE_CLASSES` and
``'django.contrib.sessions'`` from your :setting:`INSTALLED_APPS`.
It'll save you a small bit of overhead.

Configuring the session engine
==============================

By default, Django stores sessions in your database (using the model
``django.contrib.sessions.models.Session``). Though this is convenient, in
some setups it's faster to store session data elsewhere, so Django can be
configured to store session data on your filesystem or in your cache.

Using database-backed sessions
------------------------------

If you want to use a database-backed session, you need to add
``'django.contrib.sessions'`` to your :setting:`INSTALLED_APPS` setting.

Once you have configured your installation, run ``manage.py syncdb``
to install the single database table that stores session data.

Using cached sessions
---------------------

For better performance, you may want to use a cache-based session backend.

To store session data using Django's cache system, you'll first need to make
sure you've configured your cache; see the :doc:`cache documentation
</topics/cache>` for details.

.. warning::

    You should only use cache-based sessions if you're using the Memcached
    cache backend. The local-memory cache backend doesn't retain data long
    enough to be a good choice, and it'll be faster to use file or database
    sessions directly instead of sending everything through the file or
    database cache backends.

Once your cache is configured, you've got two choices for how to store data in
the cache:

* Set :setting:`SESSION_ENGINE` to
  ``"django.contrib.sessions.backends.cache"`` for a simple caching session
  store. Session data will be stored directly your cache. However, session
  data may not be persistent: cached data can be evicted if the cache fills
  up or if the cache server is restarted.

* For persistent, cached data, set :setting:`SESSION_ENGINE` to
  ``"django.contrib.sessions.backends.cached_db"``. This uses a
  write-through cache -- every write to the cache will also be written to
  the database. Session reads only use the database if the data is not
  already in the cache.

Both session stores are quite fast, but the simple cache is faster because it
disregards persistence. In most cases, the ``cached_db`` backend will be fast
enough, but if you need that last bit of performance, and are willing to let
session data be expunged from time to time, the ``cache`` backend is for you.

If you use the ``cached_db`` session backend, you also need to follow the
configuration instructions for the `using database-backed sessions`_.

Using file-based sessions
-------------------------

To use file-based sessions, set the :setting:`SESSION_ENGINE` setting to
``"django.contrib.sessions.backends.file"``.

You might also want to set the :setting:`SESSION_FILE_PATH` setting (which
defaults to output from ``tempfile.gettempdir()``, most likely ``/tmp``) to
control where Django stores session files. Be sure to check that your Web
server has permissions to read and write to this location.

.. _cookie-session-backend:

Using cookie-based sessions
---------------------------

.. versionadded:: 1.4

To use cookies-based sessions, set the :setting:`SESSION_ENGINE` setting to
``"django.contrib.sessions.backends.cookies"``. The session data will be
stored using Django's tools for :doc:`cryptographic signing </topics/signing>`
and the :setting:`SECRET_KEY` setting.

.. note::

    It's recommended to set the :setting:`SESSION_COOKIE_HTTPONLY` setting
    to ``True`` to prevent tampering of the stored data from JavaScript.

.. warning::

    **The session data is signed but not encrypted**

    When using the cookies backend the session data can be read by the client.

    A MAC (Message Authentication Code) is used to protect the data against
    changes by the client, so that the session data will be invalidated when being
    tampered with. The same invalidation happens if the client storing the
    cookie (e.g. your user's browser) can't store all of the session cookie and
    drops data. Even though Django compresses the data, it's still entirely
    possible to exceed the `common limit of 4096 bytes`_ per cookie.

    **No freshness guarantee**

    Note also that while the MAC can guarantee the authenticity of the data
    (that it was generated by your site, and not someone else), and the
    integrity of the data (that it is all there and correct), it cannot
    guarantee freshness i.e. that you are being sent back the last thing you
    sent to the client. This means that for some uses of session data, the
    cookie backend might open you up to `replay attacks`_. Cookies will only be
    detected as 'stale' if they are older than your
    :setting:`SESSION_COOKIE_AGE`.
{'fraction_non_alphanumeric': 0.09731343283582089, 'fraction_numerical': 0.001023454157782516, 'mean_word_length': 3.9813084112149535, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3195081', 'n_tokens_mistral': 3044, 'n_tokens_neox': 2929, 'n_words': 1557}