Tidy up the sessions documentation creating links for session methods and crosslinking settings

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16245 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Chris Beaven 2011-05-20 00:51:25 +00:00
parent 9f02d80b58
commit 26156794f1
1 changed files with 65 additions and 55 deletions

View File

@ -17,14 +17,15 @@ Sessions are implemented via a piece of :doc:`middleware </ref/middleware>`.
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
==============================
@ -86,56 +87,62 @@ configuration instructions for the `using database-backed sessions`_.
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
@ -143,25 +150,25 @@ It also has these methods:
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:
@ -184,26 +191,23 @@ It also has these methods:
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
-------------------------
@ -249,25 +253,29 @@ This simplistic view logs in a "member" of the site::
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::
@ -346,9 +354,9 @@ the session object::
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
@ -361,12 +369,13 @@ Browser-length sessions vs. persistent sessions
===============================================
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
@ -374,8 +383,8 @@ her browser. Use this if you want people to have to log in every time they open
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
==========================
@ -397,7 +406,8 @@ in the past -- but your application may have different requirements.
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
--------------