Author: SmileyChris
Date: 2011-05-19 17:52:36 -0700 (Thu, 19 May 2011)
New Revision: 16246
Modified:
django/branches/releases/1.3.X/docs/topics/http/sessions.txt
Log:
[1.3.X] Tidy up the sessions documentation creating links for session methods
and crosslinking settings
Backport of r16245 from trunk.
Modified: django/branches/releases/1.3.X/docs/topics/http/sessions.txt
===================================================================
--- django/branches/releases/1.3.X/docs/topics/http/sessions.txt
2011-05-20 00:51:25 UTC (rev 16245)
+++ django/branches/releases/1.3.X/docs/topics/http/sessions.txt
2011-05-20 00:52:36 UTC (rev 16246)
@@ -17,14 +17,15 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
===============================================
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 @@
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 @@
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
--------------
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to django-updates@googlegroups.com.
To unsubscribe from this group, send email to
django-updates+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
