[1.3.X] Tidy up the sessions documentation creating links for session methods...

To enable session functionality, do the following:

    * Edit the ``MIDDLEWARE_CLASSES`` setting and make sure

      ``MIDDLEWARE_CLASSES`` contains ``'django.contrib.sessions.middleware.SessionMiddleware'``.

      The default ``settings.py`` created by ``django-admin.py startproject`` has

      ``SessionMiddleware`` activated.

    * 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 ``MIDDLEWARE_CLASSES`` and ``'django.contrib.sessions'``

from your ``INSTALLED_APPS``. It'll save you a small bit of overhead.

``SessionMiddleware`` line from ``MIDDLEWARE_CLASSES`` and

``'django.contrib.sessions'`` from your :setting:`INSTALLED_APPS`.

It'll save you a small bit of overhead.

Configuring the session engine

==============================

Using file-based sessions

-------------------------

To use file-based sessions, set the ``SESSION_ENGINE`` setting to

To use file-based sessions, set the :setting:`SESSION_ENGINE` setting to

``"django.contrib.sessions.backends.file"``.

You might also want to set the ``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.

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.

Using sessions in views

=======================

When ``SessionMiddleware`` is activated, each ``HttpRequest`` object -- the

first argument to any Django view function -- will have a ``session``

attribute, which is a dictionary-like object. You can read it and write to it.

When ``SessionMiddleware`` is activated, each :class:`~django.http.HttpRequest`

object -- the first argument to any Django view function -- will have a

``session`` attribute, which is a dictionary-like object.

A session object has the following standard dictionary methods:

You can read it and write to ``request.session`` at any point in your view.

You can edit it multiple times.

    * ``__getitem__(key)``

.. class:: backends.base.SessionBase

    This is the base class for all session objects. It has the following

    standard dictionary methods:

    .. method:: __getitem__(key)

      Example: ``fav_color = request.session['fav_color']``

    * ``__setitem__(key, value)``

    .. method:: __setitem__(key, value)

      Example: ``request.session['fav_color'] = 'blue'``

    * ``__delitem__(key)``

    .. method:: __delitem__(key)

      Example: ``del request.session['fav_color']``. This raises ``KeyError``

      if the given ``key`` isn't already in the session.

    * ``__contains__(key)``

    .. method:: __contains__(key)

      Example: ``'fav_color' in request.session``

    * ``get(key, default=None)``

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

      Example: ``fav_color = request.session.get('fav_color', 'red')``

    * ``keys()``

    .. method:: keys

    * ``items()``

    .. method:: items

    * ``setdefault()``

    .. method:: setdefault

    * ``clear()``

    .. method:: clear

    It also has these methods:

    * ``flush()``

    .. method:: flush

      Delete the current session data from the session and regenerate the

      session key value that is sent back to the user in the cookie. This is

      accessed again from the user's browser (for example, the

      :func:`django.contrib.auth.logout()` function calls it).

    * ``set_test_cookie()``

    .. method:: set_test_cookie

      Sets a test cookie to determine whether the user's browser supports

      cookies. Due to the way cookies work, you won't be able to test this

      until the user's next page request. See `Setting test cookies`_ below for

      more information.

    * ``test_cookie_worked()``

    .. method:: test_cookie_worked

      Returns either ``True`` or ``False``, depending on whether the user's

      browser accepted the test cookie. Due to the way cookies work, you'll

      have to call ``set_test_cookie()`` on a previous, separate page request.

      See `Setting test cookies`_ below for more information.

    * ``delete_test_cookie()``

    .. method:: delete_test_cookie

      Deletes the test cookie. Use this to clean up after yourself.

    * ``set_expiry(value)``

    .. method:: set_expiry(value)

      Sets the expiration time for the session. You can pass a number of

      different values:

      purposes. Session expiration is computed from the last time the

      session was *modified*.

    * ``get_expiry_age()``

    .. method:: get_expiry_age

      Returns the number of seconds until this session expires. For sessions

      with no custom expiration (or those set to expire at browser close), this

      will equal ``settings.SESSION_COOKIE_AGE``.

      will equal :setting:`SESSION_COOKIE_AGE`.

    * ``get_expiry_date()``

    .. method:: get_expiry_date

      Returns the date this session will expire. For sessions with no custom

      expiration (or those set to expire at browser close), this will equal the

      date ``settings.SESSION_COOKIE_AGE`` seconds from now.

      date :setting:`SESSION_COOKIE_AGE` seconds from now.

    * ``get_expire_at_browser_close()``

    .. method:: get_expire_at_browser_close

      Returns either ``True`` or ``False``, depending on whether the user's

      session cookie will expire when the user's Web browser is closed.

You can edit ``request.session`` at any point in your view. You can edit it

multiple times.

Session object guidelines

-------------------------

            pass

        return HttpResponse("You're logged out.")

The standard ``django.contrib.auth.logout()`` function actually does a bit

more than this to prevent inadvertent data leakage. It calls

``request.session.flush()``. We are using this example as a demonstration of

how to work with session objects, not as a full ``logout()`` implementation.

The standard :meth:`django.contrib.auth.logout` function actually does a bit

more than this to prevent inadvertent data leakage. It calls the

:meth:`~backends.base.SessionBase.flush` method of ``request.session``.

We are using this example as a demonstration of how to work with session

objects, not as a full ``logout()`` implementation.

Setting test cookies

====================

As a convenience, Django provides an easy way to test whether the user's

browser accepts cookies. Just call ``request.session.set_test_cookie()`` in a

view, and call ``request.session.test_cookie_worked()`` in a subsequent view --

browser accepts cookies. Just call the

:meth:`~backends.base.SessionBase.set_test_cookie` method of

``request.session`` in a view, and call

:meth:`~backends.base.SessionBase.test_cookie_worked` in a subsequent view --

not in the same view call.

This awkward split between ``set_test_cookie()`` and ``test_cookie_worked()``

is necessary due to the way cookies work. When you set a cookie, you can't

actually tell whether a browser accepted it until the browser's next request.

It's good practice to use ``delete_test_cookie()`` to clean up after yourself.

Do this after you've verified that the test cookie worked.

It's good practice to use

:meth:`~backends.base.SessionBase.delete_test_cookie()` to clean up after

yourself. Do this after you've verified that the test cookie worked.

Here's a typical usage example::

    request.session.modified = True

To change this default behavior, set the ``SESSION_SAVE_EVERY_REQUEST`` setting

to ``True``. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, Django will save

the session to the database on every single request.

To change this default behavior, set the :setting:`SESSION_SAVE_EVERY_REQUEST`

setting to ``True``. When set to ``True``, Django will save the session to the

database on every single request.

Note that the session cookie is only sent when a session has been created or

modified. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, the session cookie

===============================================

You can control whether the session framework uses browser-length sessions vs.

persistent sessions with the ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` setting.

persistent sessions with the :setting:`SESSION_EXPIRE_AT_BROWSER_CLOSE`

setting.

By default, ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``False``, which

means session cookies will be stored in users' browsers for as long as

``SESSION_COOKIE_AGE``. Use this if you don't want people to have to log in

every time they open a browser.

:setting:`SESSION_COOKIE_AGE`. Use this if you don't want people to have to

log in every time they open a browser.

If ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``True``, Django will use

browser-length cookies -- cookies that expire as soon as the user closes his or

a browser.

This setting is a global default and can be overwritten at a per-session level

by explicitly calling ``request.session.set_expiry()`` as described above in

`using sessions in views`_.

by explicitly calling the :meth:`~backends.base.SessionBase.set_expiry` method

of ``request.session`` as described above in `using sessions in views`_.

Clearing the session table

==========================

Settings

========

A few :doc:`Django settings </ref/settings>` give you control over session behavior:

A few :doc:`Django settings </ref/settings>` give you control over session

behavior:

SESSION_ENGINE

--------------