Permalink
Browse files

[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
  • Loading branch information...
1 parent 770b91c commit be776521dbe535497223b314c4d58874f1ae6992 @SmileyChris SmileyChris committed May 20, 2011
Showing with 65 additions and 55 deletions.
  1. +65 −55 docs/topics/http/sessions.txt
@@ -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,82 +87,88 @@ 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
used if you want to ensure that the previous session data can't be
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,21 +369,22 @@ 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
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
--------------

0 comments on commit be77652

Please sign in to comment.