diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt index af27d54257..1fd6a5c031 100644 --- a/docs/topics/http/sessions.txt +++ b/docs/topics/http/sessions.txt @@ -17,14 +17,15 @@ Sessions are implemented via a piece of :doc:`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 ` give you control over session behavior: +A few :doc:`Django settings ` give you control over session +behavior: SESSION_ENGINE --------------