Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[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...
commit be776521dbe535497223b314c4d58874f1ae6992 1 parent 770b91c
Chris Beaven authored May 20, 2011

Showing 1 changed file with 65 additions and 55 deletions. Show diff stats Hide diff stats

  1. 120  docs/topics/http/sessions.txt
120  docs/topics/http/sessions.txt
@@ -17,14 +17,15 @@ Sessions are implemented via a piece of :doc:`middleware </ref/middleware>`.
17 17
 
18 18
 To enable session functionality, do the following:
19 19
 
20  
-    * Edit the ``MIDDLEWARE_CLASSES`` setting and make sure
21  
-      ``MIDDLEWARE_CLASSES`` contains ``'django.contrib.sessions.middleware.SessionMiddleware'``.
22  
-      The default ``settings.py`` created by ``django-admin.py startproject`` has
23  
-      ``SessionMiddleware`` activated.
  20
+    * Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure
  21
+      it contains ``'django.contrib.sessions.middleware.SessionMiddleware'``.
  22
+      The default ``settings.py`` created by ``django-admin.py startproject``
  23
+      has ``SessionMiddleware`` activated.
24 24
 
25 25
 If you don't want to use sessions, you might as well remove the
26  
-``SessionMiddleware`` line from ``MIDDLEWARE_CLASSES`` and ``'django.contrib.sessions'``
27  
-from your ``INSTALLED_APPS``. It'll save you a small bit of overhead.
  26
+``SessionMiddleware`` line from ``MIDDLEWARE_CLASSES`` and
  27
+``'django.contrib.sessions'`` from your :setting:`INSTALLED_APPS`.
  28
+It'll save you a small bit of overhead.
28 29
 
29 30
 Configuring the session engine
30 31
 ==============================
@@ -86,56 +87,62 @@ configuration instructions for the `using database-backed sessions`_.
86 87
 Using file-based sessions
87 88
 -------------------------
88 89
 
89  
-To use file-based sessions, set the ``SESSION_ENGINE`` setting to
  90
+To use file-based sessions, set the :setting:`SESSION_ENGINE` setting to
90 91
 ``"django.contrib.sessions.backends.file"``.
91 92
 
92  
-You might also want to set the ``SESSION_FILE_PATH`` setting (which defaults
93  
-to output from ``tempfile.gettempdir()``, most likely ``/tmp``) to control
94  
-where Django stores session files. Be sure to check that your Web server has
95  
-permissions to read and write to this location.
  93
+You might also want to set the :setting:`SESSION_FILE_PATH` setting (which
  94
+defaults to output from ``tempfile.gettempdir()``, most likely ``/tmp``) to
  95
+control where Django stores session files. Be sure to check that your Web
  96
+server has permissions to read and write to this location.
96 97
 
97 98
 
98 99
 Using sessions in views
99 100
 =======================
100 101
 
101  
-When ``SessionMiddleware`` is activated, each ``HttpRequest`` object -- the
102  
-first argument to any Django view function -- will have a ``session``
103  
-attribute, which is a dictionary-like object. You can read it and write to it.
  102
+When ``SessionMiddleware`` is activated, each :class:`~django.http.HttpRequest`
  103
+object -- the first argument to any Django view function -- will have a
  104
+``session`` attribute, which is a dictionary-like object.
104 105
 
105  
-A session object has the following standard dictionary methods:
  106
+You can read it and write to ``request.session`` at any point in your view.
  107
+You can edit it multiple times.
106 108
 
107  
-    * ``__getitem__(key)``
  109
+.. class:: backends.base.SessionBase
  110
+
  111
+    This is the base class for all session objects. It has the following
  112
+    standard dictionary methods:
  113
+
  114
+    .. method:: __getitem__(key)
108 115
 
109 116
       Example: ``fav_color = request.session['fav_color']``
110 117
 
111  
-    * ``__setitem__(key, value)``
  118
+    .. method:: __setitem__(key, value)
112 119
 
113 120
       Example: ``request.session['fav_color'] = 'blue'``
114 121
 
115  
-    * ``__delitem__(key)``
  122
+    .. method:: __delitem__(key)
116 123
 
117 124
       Example: ``del request.session['fav_color']``. This raises ``KeyError``
118 125
       if the given ``key`` isn't already in the session.
119 126
 
120  
-    * ``__contains__(key)``
  127
+    .. method:: __contains__(key)
121 128
 
122 129
       Example: ``'fav_color' in request.session``
123 130
 
124  
-    * ``get(key, default=None)``
  131
+    .. method:: get(key, default=None)
125 132
 
126 133
       Example: ``fav_color = request.session.get('fav_color', 'red')``
127 134
 
128  
-    * ``keys()``
  135
+    .. method:: keys
129 136
 
130  
-    * ``items()``
  137
+    .. method:: items
131 138
 
132  
-    * ``setdefault()``
  139
+    .. method:: setdefault
133 140
 
134  
-    * ``clear()``
  141
+    .. method:: clear
135 142
 
136  
-It also has these methods:
  143
+    It also has these methods:
137 144
 
138  
-    * ``flush()``
  145
+    .. method:: flush
139 146
 
140 147
       Delete the current session data from the session and regenerate the
141 148
       session key value that is sent back to the user in the cookie. This is
@@ -143,25 +150,25 @@ It also has these methods:
143 150
       accessed again from the user's browser (for example, the
144 151
       :func:`django.contrib.auth.logout()` function calls it).
145 152
 
146  
-    * ``set_test_cookie()``
  153
+    .. method:: set_test_cookie
147 154
 
148 155
       Sets a test cookie to determine whether the user's browser supports
149 156
       cookies. Due to the way cookies work, you won't be able to test this
150 157
       until the user's next page request. See `Setting test cookies`_ below for
151 158
       more information.
152 159
 
153  
-    * ``test_cookie_worked()``
  160
+    .. method:: test_cookie_worked
154 161
 
155 162
       Returns either ``True`` or ``False``, depending on whether the user's
156 163
       browser accepted the test cookie. Due to the way cookies work, you'll
157 164
       have to call ``set_test_cookie()`` on a previous, separate page request.
158 165
       See `Setting test cookies`_ below for more information.
159 166
 
160  
-    * ``delete_test_cookie()``
  167
+    .. method:: delete_test_cookie
161 168
 
162 169
       Deletes the test cookie. Use this to clean up after yourself.
163 170
 
164  
-    * ``set_expiry(value)``
  171
+    .. method:: set_expiry(value)
165 172
 
166 173
       Sets the expiration time for the session. You can pass a number of
167 174
       different values:
@@ -184,26 +191,23 @@ It also has these methods:
184 191
       purposes. Session expiration is computed from the last time the
185 192
       session was *modified*.
186 193
 
187  
-    * ``get_expiry_age()``
  194
+    .. method:: get_expiry_age
188 195
 
189 196
       Returns the number of seconds until this session expires. For sessions
190 197
       with no custom expiration (or those set to expire at browser close), this
191  
-      will equal ``settings.SESSION_COOKIE_AGE``.
  198
+      will equal :setting:`SESSION_COOKIE_AGE`.
192 199
 
193  
-    * ``get_expiry_date()``
  200
+    .. method:: get_expiry_date
194 201
 
195 202
       Returns the date this session will expire. For sessions with no custom
196 203
       expiration (or those set to expire at browser close), this will equal the
197  
-      date ``settings.SESSION_COOKIE_AGE`` seconds from now.
  204
+      date :setting:`SESSION_COOKIE_AGE` seconds from now.
198 205
 
199  
-    * ``get_expire_at_browser_close()``
  206
+    .. method:: get_expire_at_browser_close
200 207
 
201 208
       Returns either ``True`` or ``False``, depending on whether the user's
202 209
       session cookie will expire when the user's Web browser is closed.
203 210
 
204  
-You can edit ``request.session`` at any point in your view. You can edit it
205  
-multiple times.
206  
-
207 211
 Session object guidelines
208 212
 -------------------------
209 213
 
@@ -249,25 +253,29 @@ This simplistic view logs in a "member" of the site::
249 253
             pass
250 254
         return HttpResponse("You're logged out.")
251 255
 
252  
-The standard ``django.contrib.auth.logout()`` function actually does a bit
253  
-more than this to prevent inadvertent data leakage. It calls
254  
-``request.session.flush()``. We are using this example as a demonstration of
255  
-how to work with session objects, not as a full ``logout()`` implementation.
  256
+The standard :meth:`django.contrib.auth.logout` function actually does a bit
  257
+more than this to prevent inadvertent data leakage. It calls the
  258
+:meth:`~backends.base.SessionBase.flush` method of ``request.session``.
  259
+We are using this example as a demonstration of how to work with session
  260
+objects, not as a full ``logout()`` implementation.
256 261
 
257 262
 Setting test cookies
258 263
 ====================
259 264
 
260 265
 As a convenience, Django provides an easy way to test whether the user's
261  
-browser accepts cookies. Just call ``request.session.set_test_cookie()`` in a
262  
-view, and call ``request.session.test_cookie_worked()`` in a subsequent view --
  266
+browser accepts cookies. Just call the
  267
+:meth:`~backends.base.SessionBase.set_test_cookie` method of
  268
+``request.session`` in a view, and call
  269
+:meth:`~backends.base.SessionBase.test_cookie_worked` in a subsequent view --
263 270
 not in the same view call.
264 271
 
265 272
 This awkward split between ``set_test_cookie()`` and ``test_cookie_worked()``
266 273
 is necessary due to the way cookies work. When you set a cookie, you can't
267 274
 actually tell whether a browser accepted it until the browser's next request.
268 275
 
269  
-It's good practice to use ``delete_test_cookie()`` to clean up after yourself.
270  
-Do this after you've verified that the test cookie worked.
  276
+It's good practice to use
  277
+:meth:`~backends.base.SessionBase.delete_test_cookie()` to clean up after
  278
+yourself. Do this after you've verified that the test cookie worked.
271 279
 
272 280
 Here's a typical usage example::
273 281
 
@@ -346,9 +354,9 @@ the session object::
346 354
 
347 355
     request.session.modified = True
348 356
 
349  
-To change this default behavior, set the ``SESSION_SAVE_EVERY_REQUEST`` setting
350  
-to ``True``. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, Django will save
351  
-the session to the database on every single request.
  357
+To change this default behavior, set the :setting:`SESSION_SAVE_EVERY_REQUEST`
  358
+setting to ``True``. When set to ``True``, Django will save the session to the
  359
+database on every single request.
352 360
 
353 361
 Note that the session cookie is only sent when a session has been created or
354 362
 modified. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, the session cookie
@@ -361,12 +369,13 @@ Browser-length sessions vs. persistent sessions
361 369
 ===============================================
362 370
 
363 371
 You can control whether the session framework uses browser-length sessions vs.
364  
-persistent sessions with the ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` setting.
  372
+persistent sessions with the :setting:`SESSION_EXPIRE_AT_BROWSER_CLOSE`
  373
+setting.
365 374
 
366 375
 By default, ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``False``, which
367 376
 means session cookies will be stored in users' browsers for as long as
368  
-``SESSION_COOKIE_AGE``. Use this if you don't want people to have to log in
369  
-every time they open a browser.
  377
+:setting:`SESSION_COOKIE_AGE`. Use this if you don't want people to have to
  378
+log in every time they open a browser.
370 379
 
371 380
 If ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``True``, Django will use
372 381
 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
374 383
 a browser.
375 384
 
376 385
 This setting is a global default and can be overwritten at a per-session level
377  
-by explicitly calling ``request.session.set_expiry()`` as described above in
378  
-`using sessions in views`_.
  386
+by explicitly calling the :meth:`~backends.base.SessionBase.set_expiry` method
  387
+of ``request.session`` as described above in `using sessions in views`_.
379 388
 
380 389
 Clearing the session table
381 390
 ==========================
@@ -397,7 +406,8 @@ in the past -- but your application may have different requirements.
397 406
 Settings
398 407
 ========
399 408
 
400  
-A few :doc:`Django settings </ref/settings>` give you control over session behavior:
  409
+A few :doc:`Django settings </ref/settings>` give you control over session
  410
+behavior:
401 411
 
402 412
 SESSION_ENGINE
403 413
 --------------

0 notes on commit be77652

Please sign in to comment.
Something went wrong with that request. Please try again.