Ticket #2548: session_middleware.5.diff

File session_middleware.5.diff, 28.0 KB (added by upadhyay@…, 17 years ago)

with docs.

  • django/contrib/sessions/middleware.py

     
    11from django.conf import settings
    2 from django.contrib.sessions.models import Session
     2from django.contrib.sessions.models import Session, TILL_BROWSER_CLOSE
    33from django.core.exceptions import SuspiciousOperation
    44from django.utils.cache import patch_vary_headers
    55import datetime
    … …  
    4848    def delete_test_cookie(self):
    4949        del self[TEST_COOKIE_NAME]
    5050
     51    def set_life(self, val):
     52        """
     53            sets the life of the session, irrespective of global settings.
     54            val is in seconds.
     55
     56            django.contrib.sessions.models.TILL_BROWSER_CLOSE can also be passed
     57            to ask django to quell session on browser close, overwriting global settings.
     58        """
     59        if val == TILL_BROWSER_CLOSE:
     60            self["_expires_on"] = TILL_BROWSER_CLOSE
     61        else:
     62            self["_expires_on"] = datetime.datetime.now() + datetime.timedelta(seconds=val)
     63
    5164    def _get_session(self):
    5265        # Lazily loads session from storage.
    5366        self.accessed = True
    … …  
    92105                    obj = Session.objects.get_new_session_object()
    93106                    session_key = obj.session_key
    94107
    95                 if settings.SESSION_EXPIRE_AT_BROWSER_CLOSE:
    96                     max_age = None
    97                     expires = None
    98                 else:
    99                     max_age = settings.SESSION_COOKIE_AGE
    100                     expires = datetime.datetime.strftime(datetime.datetime.utcnow() + datetime.timedelta(seconds=settings.SESSION_COOKIE_AGE), "%a, %d-%b-%Y %H:%M:%S GMT")
    101                 new_session = Session.objects.save(session_key, request.session._session,
    102                     datetime.datetime.now() + datetime.timedelta(seconds=settings.SESSION_COOKIE_AGE))
    103                 response.set_cookie(settings.SESSION_COOKIE_NAME, session_key,
     108                now = datetime.datetime.now()
     109                delta_yield = now + datetime.timedelta(seconds=settings.SESSION_COOKIE_AGE)
     110                if (
     111                    (
     112                        # if session is set to expire on browser close globally
     113                        settings.SESSION_EXPIRE_AT_BROWSER_CLOSE and
     114                        # but someone did not set _expires_on, or set it to TILL_BROWSER_CLOSE
     115                        request.session.get("_expires_on", TILL_BROWSER_CLOSE) == TILL_BROWSER_CLOSE
     116                    ) or
     117                    (
     118                        # if someone asked as to expire on browser close irrespective of global setting
     119                        request.session.get("_expires_on") == TILL_BROWSER_CLOSE
     120                    )
     121                ):
     122                    max_age = None # session expiry is simulated by cookie deletion.
     123                    expires = None # which is done by setting these two to None
     124                else: # session need to be preserved, cookie has to be set
     125                    delta_yield = request.session.get("_expires_on", delta_yield)
     126                    max_age_timedelta = delta_yield - now
     127                    max_age = max_age_timedelta.days * 24 * 60 * 60 + max_age_timedelta.seconds
     128                    expires = datetime.datetime.strftime(delta_yield, "%a, %d-%b-%Y %H:%M:%S GMT")
     129                Session.objects.save(session_key, request.session._session, delta_yield)
     130                response.set_cookie(
     131                    settings.SESSION_COOKIE_NAME, session_key,
    104132                    max_age=max_age, expires=expires, domain=settings.SESSION_COOKIE_DOMAIN,
    105                     secure=settings.SESSION_COOKIE_SECURE or None)
     133                    secure=settings.SESSION_COOKIE_SECURE or None
     134                )
    106135        return response

  • django/contrib/sessions/models.py

     
    44from django.utils.translation import gettext_lazy as _
    55from django.conf import settings
    66
     7TILL_BROWSER_CLOSE = -1
     8
    79class SessionManager(models.Manager):
    810    def encode(self, session_dict):
    911        "Returns the given session dictionary pickled and encoded as a string."

  • docs/sessions.txt

     
    1 ===================
    2 How to use sessions
    3 ===================
    4 
    5 Django provides full support for anonymous sessions. The session framework lets
    6 you store and retrieve arbitrary data on a per-site-visitor basis. It stores
    7 data on the server side and abstracts the sending and receiving of cookies.
    8 Cookies contain a session ID -- not the data itself.
    9 
    10 Enabling sessions
    11 =================
    12 
    13 Sessions are implemented via a piece of middleware_ and a Django model.
    14 
    15 To enable session functionality, do these two things:
    16 
    17     * Edit the ``MIDDLEWARE_CLASSES`` setting and make sure
    18       ``MIDDLEWARE_CLASSES`` contains ``'django.contrib.sessions.middleware.SessionMiddleware'``.
    19       The default ``settings.py`` created by ``django-admin.py startproject`` has
    20       ``SessionMiddleware`` activated.
    21 
    22     * Add ``'django.contrib.sessions'`` to your ``INSTALLED_APPS`` setting, and
    23       run ``manage.py syncdb`` to install the single database table that stores
    24       session data.
    25 
    26 If you don't want to use sessions, you might as well remove the
    27 ``SessionMiddleware`` line from ``MIDDLEWARE_CLASSES`` and ``'django.contrib.sessions'``
    28 from your ``INSTALLED_APPS``. It'll save you a small bit of overhead.
    29 
    30 .. _middleware: ../middleware/
    31 
    32 Using sessions in views
    33 =======================
    34 
    35 When ``SessionMiddleware`` is activated, each ``HttpRequest`` object -- the
    36 first argument to any Django view function -- will have a ``session``
    37 attribute, which is a dictionary-like object. You can read it and write to it.
    38 
    39 It implements the following standard dictionary methods:
    40 
    41     * ``__getitem__(key)``
    42       Example: ``fav_color = request.session['fav_color']``
    43 
    44     * ``__setitem__(key, value)``
    45       Example: ``request.session['fav_color'] = 'blue'``
    46 
    47     * ``__delitem__(key)``
    48       Example: ``del request.session['fav_color']``. This raises ``KeyError``
    49       if the given ``key`` isn't already in the session.
    50 
    51     * ``__contains__(key)``
    52       Example: ``'fav_color' in request.session``
    53 
    54     * ``get(key, default=None)``
    55       Example: ``fav_color = request.session.get('fav_color', 'red')``
    56 
    57     * ``keys()``
    58 
    59     * ``items()``
    60 
    61 It also has these three methods:
    62 
    63     * ``set_test_cookie()``
    64       Sets a test cookie to determine whether the user's browser supports
    65       cookies. Due to the way cookies work, you won't be able to test this
    66       until the user's next page request. See "Setting test cookies" below for
    67       more information.
    68 
    69     * ``test_cookie_worked()``
    70       Returns either ``True`` or ``False``, depending on whether the user's
    71       browser accepted the test cookie. Due to the way cookies work, you'll
    72       have to call ``set_test_cookie()`` on a previous, separate page request.
    73       See "Setting test cookies" below for more information.
    74 
    75     * ``delete_test_cookie()``
    76       Deletes the test cookie. Use this to clean up after yourself.
    77 
    78 You can edit ``request.session`` at any point in your view. You can edit it
    79 multiple times.
    80 
    81 Session object guidelines
    82 -------------------------
    83 
    84     * Use normal Python strings as dictionary keys on ``request.session``. This
    85       is more of a convention than a hard-and-fast rule.
    86 
    87     * Session dictionary keys that begin with an underscore are reserved for
    88       internal use by Django.
    89 
    90     * Don't override ``request.session`` with a new object, and don't access or
    91       set its attributes. Use it like a Python dictionary.
    92 
    93 Examples
    94 --------
    95 
    96 This simplistic view sets a ``has_commented`` variable to ``True`` after a user
    97 posts a comment. It doesn't let a user post a comment more than once::
    98 
    99     def post_comment(request, new_comment):
    100         if request.session.get('has_commented', False):
    101             return HttpResponse("You've already commented.")
    102         c = comments.Comment(comment=new_comment)
    103         c.save()
    104         request.session['has_commented'] = True
    105         return HttpResponse('Thanks for your comment!')
    106 
    107 This simplistic view logs in a "member" of the site::
    108 
    109     def login(request):
    110         m = Member.objects.get(username=request.POST['username'])
    111         if m.password == request.POST['password']:
    112             request.session['member_id'] = m.id
    113             return HttpResponse("You're logged in.")
    114         else:
    115             return HttpResponse("Your username and password didn't match.")
    116 
    117 ...And this one logs a member out, according to ``login()`` above::
    118 
    119     def logout(request):
    120         try:
    121             del request.session['member_id']
    122         except KeyError:
    123             pass
    124         return HttpResponse("You're logged out.")
    125 
    126 Setting test cookies
    127 ====================
    128 
    129 As a convenience, Django provides an easy way to test whether the user's
    130 browser accepts cookies. Just call ``request.session.set_test_cookie()`` in a
    131 view, and call ``request.session.test_cookie_worked()`` in a subsequent view --
    132 not in the same view call.
    133 
    134 This awkward split between ``set_test_cookie()`` and ``test_cookie_worked()``
    135 is necessary due to the way cookies work. When you set a cookie, you can't
    136 actually tell whether a browser accepted it until the browser's next request.
    137 
    138 It's good practice to use ``delete_test_cookie()`` to clean up after yourself.
    139 Do this after you've verified that the test cookie worked.
    140 
    141 Here's a typical usage example::
    142 
    143     def login(request):
    144         if request.method == 'POST':
    145             if request.session.test_cookie_worked():
    146                 request.session.delete_test_cookie()
    147                 return HttpResponse("You're logged in.")
    148             else:
    149                 return HttpResponse("Please enable cookies and try again.")
    150         request.session.set_test_cookie()
    151         return render_to_response('foo/login_form.html')
    152 
    153 Using sessions out of views
    154 ===========================
    155 
    156 Internally, each session is just a normal Django model. The ``Session`` model
    157 is defined in ``django/contrib/sessions/models.py``. Because it's a normal
    158 model, you can access sessions using the normal Django database API::
    159 
    160     >>> from django.contrib.sessions.models import Session
    161     >>> s = Session.objects.get(pk='2b1189a188b44ad18c35e113ac6ceead')
    162     >>> s.expire_date
    163     datetime.datetime(2005, 8, 20, 13, 35, 12)
    164 
    165 Note that you'll need to call ``get_decoded()`` to get the session dictionary.
    166 This is necessary because the dictionary is stored in an encoded format::
    167 
    168     >>> s.session_data
    169     'KGRwMQpTJ19hdXRoX3VzZXJfaWQnCnAyCkkxCnMuMTExY2ZjODI2Yj...'
    170     >>> s.get_decoded()
    171     {'user_id': 42}
    172 
    173 When sessions are saved
    174 =======================
    175 
    176 By default, Django only saves to the session database when the session has been
    177 modified -- that is if any of its dictionary values have been assigned or
    178 deleted::
    179 
    180     # Session is modified.
    181     request.session['foo'] = 'bar'
    182 
    183     # Session is modified.
    184     del request.session['foo']
    185 
    186     # Session is modified.
    187     request.session['foo'] = {}
    188 
    189     # Gotcha: Session is NOT modified, because this alters
    190     # request.session['foo'] instead of request.session.
    191     request.session['foo']['bar'] = 'baz'
    192 
    193 To change this default behavior, set the ``SESSION_SAVE_EVERY_REQUEST`` setting
    194 to ``True``. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, Django will save
    195 the session to the database on every single request.
    196 
    197 Note that the session cookie is only sent when a session has been created or
    198 modified. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, the session cookie
    199 will be sent on every request.
    200 
    201 Similarly, the ``expires`` part of a session cookie is updated each time the
    202 session cookie is sent.
    203 
    204 Browser-length sessions vs. persistent sessions
    205 ===============================================
    206 
    207 You can control whether the session framework uses browser-length sessions vs.
    208 persistent sessions with the ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` setting.
    209 
    210 By default, ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``False``, which
    211 means session cookies will be stored in users' browsers for as long as
    212 ``SESSION_COOKIE_AGE``. Use this if you don't want people to have to log in
    213 every time they open a browser.
    214 
    215 If ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``True``, Django will use
    216 browser-length cookies -- cookies that expire as soon as the user closes his or
    217 her browser. Use this if you want people to have to log in every time they open
    218 a browser.
    219 
    220 Clearing the session table
    221 ==========================
    222 
    223 Note that session data can accumulate in the ``django_session`` database table
    224 and Django does *not* provide automatic purging. Therefore, it's your job to
    225 purge expired sessions on a regular basis.
    226 
    227 To understand this problem, consider what happens when a user uses a session.
    228 When a user logs in, Django adds a row to the ``django_session`` database
    229 table. Django updates this row each time the session data changes. If the user
    230 logs out manually, Django deletes the row. But if the user does *not* log out,
    231 the row never gets deleted.
    232 
    233 Django provides a sample clean-up script in ``django/bin/daily_cleanup.py``.
    234 That script deletes any session in the session table whose ``expire_date`` is
    235 in the past -- but your application may have different requirements.
    236 
    237 Settings
    238 ========
    239 
    240 A few `Django settings`_ give you control over session behavior:
    241 
    242 SESSION_COOKIE_AGE
    243 ------------------
    244 
    245 Default: ``1209600`` (2 weeks, in seconds)
    246 
    247 The age of session cookies, in seconds.
    248 
    249 SESSION_COOKIE_DOMAIN
    250 ---------------------
    251 
    252 Default: ``None``
    253 
    254 The domain to use for session cookies. Set this to a string such as
    255 ``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard
    256 domain cookie.
    257 
    258 SESSION_COOKIE_NAME
    259 -------------------
    260 
    261 Default: ``'sessionid'``
    262 
    263 The name of the cookie to use for sessions. This can be whatever you want.
    264 
    265 SESSION_COOKIE_SECURE
    266 ---------------------
    267 
    268 Default: ``False``
    269 
    270 Whether to use a secure cookie for the session cookie. If this is set to
    271 ``True``, the cookie will be marked as "secure," which means browsers may
    272 ensure that the cookie is only sent under an HTTPS connection.
    273 
    274 SESSION_EXPIRE_AT_BROWSER_CLOSE
    275 -------------------------------
    276 
    277 Default: ``False``
    278 
    279 Whether to expire the session when the user closes his or her browser. See
    280 "Browser-length sessions vs. persistent sessions" above.
    281 
    282 SESSION_SAVE_EVERY_REQUEST
    283 --------------------------
    284 
    285 Default: ``False``
    286 
    287 Whether to save the session data on every request. If this is ``False``
    288 (default), then the session data will only be saved if it has been modified --
    289 that is, if any of its dictionary values have been assigned or deleted.
    290 
    291 .. _Django settings: ../settings/
    292 
    293 Technical details
    294 =================
    295 
    296     * The session dictionary should accept any pickleable Python object. See
    297       `the pickle module`_ for more information.
    298 
    299     * Session data is stored in a database table named ``django_session`` .
    300 
    301     * Django only sends a cookie if it needs to. If you don't set any session
    302       data, it won't send a session cookie.
    303 
    304 .. _`the pickle module`: http://www.python.org/doc/current/lib/module-pickle.html
    305 
    306 Session IDs in URLs
    307 ===================
    308 
    309 The Django sessions framework is entirely, and solely, cookie-based. It does
    310 not fall back to putting session IDs in URLs as a last resort, as PHP does.
    311 This is an intentional design decision. Not only does that behavior make URLs
    312 ugly, it makes your site vulnerable to session-ID theft via the "Referer"
    313 header.
     1===================
     2How to use sessions
     3===================
     4
     5Django provides full support for anonymous sessions. The session framework lets
     6you store and retrieve arbitrary data on a per-site-visitor basis. It stores
     7data on the server side and abstracts the sending and receiving of cookies.
     8Cookies contain a session ID -- not the data itself.
     9
     10Enabling sessions
     11=================
     12
     13Sessions are implemented via a piece of middleware_ and a Django model.
     14
     15To enable session functionality, do these two things:
     16
     17    * Edit the ``MIDDLEWARE_CLASSES`` setting and make sure
     18      ``MIDDLEWARE_CLASSES`` contains ``'django.contrib.sessions.middleware.SessionMiddleware'``.
     19      The default ``settings.py`` created by ``django-admin.py startproject`` has
     20      ``SessionMiddleware`` activated.
     21
     22    * Add ``'django.contrib.sessions'`` to your ``INSTALLED_APPS`` setting, and
     23      run ``manage.py syncdb`` to install the single database table that stores
     24      session data.
     25
     26If you don't want to use sessions, you might as well remove the
     27``SessionMiddleware`` line from ``MIDDLEWARE_CLASSES`` and ``'django.contrib.sessions'``
     28from your ``INSTALLED_APPS``. It'll save you a small bit of overhead.
     29
     30.. _middleware: ../middleware/
     31
     32Using sessions in views
     33=======================
     34
     35When ``SessionMiddleware`` is activated, each ``HttpRequest`` object -- the
     36first argument to any Django view function -- will have a ``session``
     37attribute, which is a dictionary-like object. You can read it and write to it.
     38
     39It implements the following standard dictionary methods:
     40
     41    * ``__getitem__(key)``
     42      Example: ``fav_color = request.session['fav_color']``
     43
     44    * ``__setitem__(key, value)``
     45      Example: ``request.session['fav_color'] = 'blue'``
     46
     47    * ``__delitem__(key)``
     48      Example: ``del request.session['fav_color']``. This raises ``KeyError``
     49      if the given ``key`` isn't already in the session.
     50
     51    * ``__contains__(key)``
     52      Example: ``'fav_color' in request.session``
     53
     54    * ``get(key, default=None)``
     55      Example: ``fav_color = request.session.get('fav_color', 'red')``
     56
     57    * ``keys()``
     58
     59    * ``items()``
     60
     61It also has these four methods:
     62
     63    * ``set_test_cookie()``
     64      Sets a test cookie to determine whether the user's browser supports
     65      cookies. Due to the way cookies work, you won't be able to test this
     66      until the user's next page request. See "Setting test cookies" below for
     67      more information.
     68
     69    * ``test_cookie_worked()``
     70      Returns either ``True`` or ``False``, depending on whether the user's
     71      browser accepted the test cookie. Due to the way cookies work, you'll
     72      have to call ``set_test_cookie()`` on a previous, separate page request.
     73      See "Setting test cookies" below for more information.
     74
     75    * ``delete_test_cookie()``
     76      Deletes the test cookie. Use this to clean up after yourself.
     77
     78    * ``set_life(val)``
     79      It takes an integer, number of seconds for which the session should be
     80      valid. It can also take django.contrib.session.models.TILL_BROWSER_CLOSE,
     81      that will quell the session at the close of browser. Calling set_life
     82      will overwrite the global/default session expiry policy. See
     83      `browser-length sessions vs. persistent sessions` for default session expiry
     84      policy.
     85
     86You can edit ``request.session`` at any point in your view. You can edit it
     87multiple times.
     88
     89Session object guidelines
     90-------------------------
     91
     92    * Use normal Python strings as dictionary keys on ``request.session``. This
     93      is more of a convention than a hard-and-fast rule.
     94
     95    * Session dictionary keys that begin with an underscore are reserved for
     96      internal use by Django.
     97
     98    * Don't override ``request.session`` with a new object, and don't access or
     99      set its attributes. Use it like a Python dictionary.
     100
     101Examples
     102--------
     103
     104This simplistic view sets a ``has_commented`` variable to ``True`` after a user
     105posts a comment. It doesn't let a user post a comment more than once::
     106
     107    def post_comment(request, new_comment):
     108        if request.session.get('has_commented', False):
     109            return HttpResponse("You've already commented.")
     110        c = comments.Comment(comment=new_comment)
     111        c.save()
     112        request.session['has_commented'] = True
     113        return HttpResponse('Thanks for your comment!')
     114
     115This simplistic view logs in a "member" of the site::
     116
     117    def login(request):
     118        m = Member.objects.get(username=request.POST['username'])
     119        if m.password == request.POST['password']:
     120            request.session['member_id'] = m.id
     121            return HttpResponse("You're logged in.")
     122        else:
     123            return HttpResponse("Your username and password didn't match.")
     124
     125...And this one logs a member out, according to ``login()`` above::
     126
     127    def logout(request):
     128        try:
     129            del request.session['member_id']
     130        except KeyError:
     131            pass
     132        return HttpResponse("You're logged out.")
     133
     134Setting test cookies
     135====================
     136
     137As a convenience, Django provides an easy way to test whether the user's
     138browser accepts cookies. Just call ``request.session.set_test_cookie()`` in a
     139view, and call ``request.session.test_cookie_worked()`` in a subsequent view --
     140not in the same view call.
     141
     142This awkward split between ``set_test_cookie()`` and ``test_cookie_worked()``
     143is necessary due to the way cookies work. When you set a cookie, you can't
     144actually tell whether a browser accepted it until the browser's next request.
     145
     146It's good practice to use ``delete_test_cookie()`` to clean up after yourself.
     147Do this after you've verified that the test cookie worked.
     148
     149Here's a typical usage example::
     150
     151    def login(request):
     152        if request.method == 'POST':
     153            if request.session.test_cookie_worked():
     154                request.session.delete_test_cookie()
     155                return HttpResponse("You're logged in.")
     156            else:
     157                return HttpResponse("Please enable cookies and try again.")
     158        request.session.set_test_cookie()
     159        return render_to_response('foo/login_form.html')
     160
     161Using sessions out of views
     162===========================
     163
     164Internally, each session is just a normal Django model. The ``Session`` model
     165is defined in ``django/contrib/sessions/models.py``. Because it's a normal
     166model, you can access sessions using the normal Django database API::
     167
     168    >>> from django.contrib.sessions.models import Session
     169    >>> s = Session.objects.get(pk='2b1189a188b44ad18c35e113ac6ceead')
     170    >>> s.expire_date
     171    datetime.datetime(2005, 8, 20, 13, 35, 12)
     172
     173Note that you'll need to call ``get_decoded()`` to get the session dictionary.
     174This is necessary because the dictionary is stored in an encoded format::
     175
     176    >>> s.session_data
     177    'KGRwMQpTJ19hdXRoX3VzZXJfaWQnCnAyCkkxCnMuMTExY2ZjODI2Yj...'
     178    >>> s.get_decoded()
     179    {'user_id': 42}
     180
     181When sessions are saved
     182=======================
     183
     184By default, Django only saves to the session database when the session has been
     185modified -- that is if any of its dictionary values have been assigned or
     186deleted::
     187
     188    # Session is modified.
     189    request.session['foo'] = 'bar'
     190
     191    # Session is modified.
     192    del request.session['foo']
     193
     194    # Session is modified.
     195    request.session['foo'] = {}
     196
     197    # Gotcha: Session is NOT modified, because this alters
     198    # request.session['foo'] instead of request.session.
     199    request.session['foo']['bar'] = 'baz'
     200
     201To change this default behavior, set the ``SESSION_SAVE_EVERY_REQUEST`` setting
     202to ``True``. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, Django will save
     203the session to the database on every single request.
     204
     205Note that the session cookie is only sent when a session has been created or
     206modified. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, the session cookie
     207will be sent on every request.
     208
     209Similarly, the ``expires`` part of a session cookie is updated each time the
     210session cookie is sent.
     211
     212Browser-length sessions vs. persistent sessions
     213===============================================
     214
     215You can control whether the session framework uses browser-length sessions vs.
     216persistent sessions with the ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` setting.
     217
     218By default, ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``False``, which
     219means session cookies will be stored in users' browsers for as long as
     220``SESSION_COOKIE_AGE``. Use this if you don't want people to have to log in
     221every time they open a browser.
     222
     223If ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``True``, Django will use
     224browser-length cookies -- cookies that expire as soon as the user closes his or
     225her browser. Use this if you want people to have to log in every time they open
     226a browser.
     227
     228These settings are global defaults, and can be overwritten by explicitly calling
     229``request.session.set_life()`` as described above.
     230
     231Clearing the session table
     232==========================
     233
     234Note that session data can accumulate in the ``django_session`` database table
     235and Django does *not* provide automatic purging. Therefore, it's your job to
     236purge expired sessions on a regular basis.
     237
     238To understand this problem, consider what happens when a user uses a session.
     239When a user logs in, Django adds a row to the ``django_session`` database
     240table. Django updates this row each time the session data changes. If the user
     241logs out manually, Django deletes the row. But if the user does *not* log out,
     242the row never gets deleted.
     243
     244Django provides a sample clean-up script in ``django/bin/daily_cleanup.py``.
     245That script deletes any session in the session table whose ``expire_date`` is
     246in the past -- but your application may have different requirements.
     247
     248Settings
     249========
     250
     251A few `Django settings`_ give you control over session behavior:
     252
     253SESSION_COOKIE_AGE
     254------------------
     255
     256Default: ``1209600`` (2 weeks, in seconds)
     257
     258The age of session cookies, in seconds.
     259
     260SESSION_COOKIE_DOMAIN
     261---------------------
     262
     263Default: ``None``
     264
     265The domain to use for session cookies. Set this to a string such as
     266``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard
     267domain cookie.
     268
     269SESSION_COOKIE_NAME
     270-------------------
     271
     272Default: ``'sessionid'``
     273
     274The name of the cookie to use for sessions. This can be whatever you want.
     275
     276SESSION_COOKIE_SECURE
     277---------------------
     278
     279Default: ``False``
     280
     281Whether to use a secure cookie for the session cookie. If this is set to
     282``True``, the cookie will be marked as "secure," which means browsers may
     283ensure that the cookie is only sent under an HTTPS connection.
     284
     285SESSION_EXPIRE_AT_BROWSER_CLOSE
     286-------------------------------
     287
     288Default: ``False``
     289
     290Whether to expire the session when the user closes his or her browser. See
     291"Browser-length sessions vs. persistent sessions" above.
     292
     293SESSION_SAVE_EVERY_REQUEST
     294--------------------------
     295
     296Default: ``False``
     297
     298Whether to save the session data on every request. If this is ``False``
     299(default), then the session data will only be saved if it has been modified --
     300that is, if any of its dictionary values have been assigned or deleted.
     301
     302.. _Django settings: ../settings/
     303
     304Technical details
     305=================
     306
     307    * The session dictionary should accept any pickleable Python object. See
     308      `the pickle module`_ for more information.
     309
     310    * Session data is stored in a database table named ``django_session`` .
     311
     312    * Django only sends a cookie if it needs to. If you don't set any session
     313      data, it won't send a session cookie.
     314
     315.. _`the pickle module`: http://www.python.org/doc/current/lib/module-pickle.html
     316
     317Session IDs in URLs
     318===================
     319
     320The Django sessions framework is entirely, and solely, cookie-based. It does
     321not fall back to putting session IDs in URLs as a last resort, as PHP does.
     322This is an intentional design decision. Not only does that behavior make URLs
     323ugly, it makes your site vulnerable to session-ID theft via the "Referer"
     324header.
Back to Top