[1.3.X] Tidy up the sessions documentation creating links for session methods and crosslinking settings
Backport of r16245 from trunk. git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.3.X@16246 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Chris Beaven
parent
770b91ca7b
commit
be776521db
|
|
@ -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:
|
||||
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
|
||||
--------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue