diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/cache.txt | 73 | ||||
| -rw-r--r-- | docs/db-api.txt | 19 | ||||
| -rw-r--r-- | docs/legacy_databases.txt | 24 | ||||
| -rw-r--r-- | docs/request_response.txt | 4 | ||||
| -rw-r--r-- | docs/sessions.txt | 42 | ||||
| -rw-r--r-- | docs/tutorial04.txt | 3 |
6 files changed, 122 insertions, 43 deletions
diff --git a/docs/cache.txt b/docs/cache.txt index c1b1352bca..f8986b9115 100644 --- a/docs/cache.txt +++ b/docs/cache.txt @@ -272,39 +272,64 @@ and a list/tuple of header names as its second argument. .. _`HTTP Vary headers`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44 -Controlling cache: Using Vary headers -===================================== +Controlling cache: Using other headers +====================================== + +Another problem with caching is the privacy of data and the question of where +data should be stored in a cascade of caches. + +A user usually faces two kinds of caches: his own browser cache (a private +cache) and his provider's cache (a public cache). A public cache is used by +multiple users and controlled by someone else. This poses problems with +sensitive data: You don't want, say, your banking-account number stored in a +public cache. So Web applications need a way to tell caches which data is +private and which is public. + +The solution is to indicate a page's cache should be "private." To do this in +Django, use the ``cache_control`` view decorator. Example:: + + from django.views.decorators.cache import cache_control + @cache_control(private=True) + def my_view(request): + ... + +This decorator takes care of sending out the appropriate HTTP header behind the +scenes. -Another problem with caching is the privacy of data, and the question where data can -be stored in a cascade of caches. A user usually faces two kinds of caches: his own -browser cache (a private cache) and his providers cache (a public cache). A public cache -is used by multiple users and controlled by someone else. This poses problems with private -(in the sense of sensitive) data - you don't want your social security number or your -banking account numbers stored in some public cache. So web applications need a way -to tell the caches what data is private and what is public. +There are a few other ways to control cache parameters. For example, HTTP +allows applications to do the following: -Other aspects are the definition how long a page should be cached at max, or wether the -cache should allways check for newer versions and only deliver the cache content when -there were no changes (some caches might deliver cached content even if the server page -changed - just because the cache copy isn't yet expired). + * Define the maximum time a page should be cached. + * Specify whether a cache should always check for newer versions, only + delivering the cached content when there are no changes. (Some caches + might deliver cached content even if the server page changed -- simply + because the cache copy isn't yet expired.) -So there are a multitude of options you can control for your pages. This is where the -Cache-Control header (more infos in `HTTP Cache-Control headers`_) comes in. The usage -is quite simple:: +In Django, use the ``cache_control`` view decorator to specify these cache +parameters. In this example, ``cache_control`` tells caches to revalidate the +cache on every access and to store cached versions for, at most, 3600 seconds:: - @cache_control(private=True, must_revalidate=True, max_age=3600) + from django.views.decorators.cache import cache_control + @cache_control(must_revalidate=True, max_age=3600) def my_view(request): ... -This would define the view as private, to be revalidated on every access and cache -copies will only be stored for 3600 seconds at max. +Any valid ``Cache-Control`` directive is valid in ``cache_control()``. For a +full list, see the `Cache-Control spec`_. Just pass the directives as keyword +arguments to ``cache_control()``, substituting underscores for hyphens. For +directives that don't take an argument, set the argument to ``True``. + +Examples: + + * ``@cache_control(max_age=3600)`` turns into ``max-age=3600``. + * ``@cache_control(public=True)`` turns into ``public``. -The caching middleware already set's this header up with a max-age of the CACHE_MIDDLEWARE_SETTINGS -setting. And the cache_page decorator does the same. The cache_control decorator correctly merges -different values into one big header, though. But you should take into account that middlewares -might overwrite some of your headers or set their own defaults if you don't give that header yourself. +(Note that the caching middleware already sets the cache header's max-age with +the value of the ``CACHE_MIDDLEWARE_SETTINGS`` setting. If you use a custom +``max_age`` in a ``cache_control`` decorator, the decorator will take +precedence, and the header values will be merged correctly.) -.. _`HTTP Cache-Control headers`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9 +.. _`Cache-Control spec`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9 Other optimizations =================== diff --git a/docs/db-api.txt b/docs/db-api.txt index b80d4e8647..01aacf49b1 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -161,9 +161,9 @@ The DB API supports the following lookup types: ``foo``, ``FOO``, ``fOo``, etc. contains Case-sensitive containment test: ``polls.get_list(question__contains="spam")`` returns all polls - that contain "spam" in the question. (PostgreSQL only. MySQL - doesn't support case-sensitive LIKE statements; ``contains`` - will act like ``icontains`` for MySQL.) + that contain "spam" in the question. (PostgreSQL and MySQL + only. SQLite doesn't support case-sensitive LIKE statements; + ``contains`` will act like ``icontains`` for SQLite.) icontains Case-insensitive containment test. gt Greater than: ``polls.get_list(id__gt=4)``. gte Greater than or equal to. @@ -174,11 +174,10 @@ The DB API supports the following lookup types: a list of polls whose IDs are either 1, 3 or 4. startswith Case-sensitive starts-with: ``polls.get_list(question_startswith="Would")``. (PostgreSQL - only. MySQL doesn't support case-sensitive LIKE statements; - ``startswith`` will act like ``istartswith`` for MySQL.) - endswith Case-sensitive ends-with. (PostgreSQL only. MySQL doesn't - support case-sensitive LIKE statements; ``endswith`` will act - like ``iendswith`` for MySQL.) + and MySQL only. SQLite doesn't support case-sensitive LIKE + statements; ``startswith`` will act like ``istartswith`` for + SQLite.) + endswith Case-sensitive ends-with. (PostgreSQL and MySQL only.) istartswith Case-insensitive starts-with. iendswith Case-insensitive ends-with. range Range test: @@ -240,6 +239,10 @@ so:: polls.get_list(order_by=['?']) +There's no way to specify whether ordering should be case sensitive. With +respect to case-sensitivity, Django will order results however your database +backend normally orders them. + Relationships (joins) ===================== diff --git a/docs/legacy_databases.txt b/docs/legacy_databases.txt index e08580504c..beddc74134 100644 --- a/docs/legacy_databases.txt +++ b/docs/legacy_databases.txt @@ -16,17 +16,22 @@ Give Django your database parameters You'll need to tell Django what your database connection parameters are, and what the name of the database is. Do that by editing these settings in your -settings file: +`settings file`_: - * ``DATABASE_ENGINE`` - * ``DATABASE_USER`` - * ``DATABASE_PASSWORD`` - * ``DATABASE_NAME`` - * ``DATABASE_HOST`` + * `DATABASE_ENGINE`_ + * `DATABASE_USER`_ + * `DATABASE_PASSWORD`_ + * `DATABASE_NAME`_ + * `DATABASE_HOST`_ + * `DATABASE_PORT`_ -For more information on these settings see `Tutorial 1`_. - -.. _Tutorial 1: http://www.djangoproject.com/documentation/tutorial1/ +.. _settings file: http://www.djangoproject.com/documentation/settings/ +.. _DATABASE_ENGINE: http://www.djangoproject.com/documentation/settings/#database-engine +.. _DATABASE_USER: http://www.djangoproject.com/documentation/settings/#database-user +.. _DATABASE_PASSWORD: http://www.djangoproject.com/documentation/settings/#database-password +.. _DATABASE_NAME: http://www.djangoproject.com/documentation/settings/#database-name +.. _DATABASE_HOST: http://www.djangoproject.com/documentation/settings/#database-host +.. _DATABASE_PORT: http://www.djangoproject.com/documentation/settings/#database-port Auto-generate the models ======================== @@ -72,7 +77,6 @@ following names: * ``auth_groups`` * ``auth_users`` * ``auth_messages`` - * ``auth_admin_log`` * ``auth_groups_permissions`` * ``auth_users_groups`` * ``auth_users_user_permissions`` diff --git a/docs/request_response.txt b/docs/request_response.txt index 150a5bc92c..85a5e091db 100644 --- a/docs/request_response.txt +++ b/docs/request_response.txt @@ -284,12 +284,14 @@ Methods Returns ``True`` or ``False`` based on a case-insensitive check for a header with the given name. -``set_cookie(key, value='', max_age=None, path='/', domain=None, secure=None)`` +``set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=None)`` Sets a cookie. The parameters are the same as in the `cookie Morsel`_ object in the Python standard library. * ``max_age`` should be a number of seconds, or ``None`` (default) if the cookie should last only as long as the client's browser session. + * ``expires`` should be a string in the format + ``"Wdy, DD-Mon-YY HH:MM:SS GMT"``. * Use ``domain`` if you want to set a cross-domain cookie. For example, ``domain=".lawrence.com"`` will set a cookie that is readable by the domains www.lawrence.com, blogs.lawrence.com and diff --git a/docs/sessions.txt b/docs/sessions.txt index b18ca25a2c..8aa711ea23 100644 --- a/docs/sessions.txt +++ b/docs/sessions.txt @@ -158,6 +158,39 @@ This is necessary because the dictionary is stored in an encoded format:: >>> s.get_decoded() {'user_id': 42} +Session cookies +=============== + +A few `Django settings`_ give you control over the session cookie: + +SESSION_COOKIE_AGE +------------------ + +Default: ``1209600`` (2 weeks, in seconds) + +The age of session cookies, in seconds. + +SESSION_COOKIE_DOMAIN +--------------------- + +Default: ``None`` + +The domain to use for session cookies. Set this to a string such as +``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard +domain cookie. + +SESSION_COOKIE_NAME +------------------- + +Default: ``'hotclub'`` + +The name of the cookie to use for sessions. This can be whatever you want. + +``'hotclub'`` is a reference to the Hot Club of France, the band Django +Reinhardt played in. + +.. _Django settings: http://www.djangoproject.com/documentation/settings/ + Technical details ================= @@ -170,3 +203,12 @@ Technical details data, it won't send a session cookie. .. _`the pickle module`: http://www.python.org/doc/current/lib/module-pickle.html + +Session IDs in URLs +=================== + +The Django sessions framework is entirely, and solely, cookie-based. It does +not fall back to putting session IDs in URLs as a last resort, as PHP does. +This is an intentional design decision. Not only does that behavior make URLs +ugly, it makes your site vulnerable to session-ID theft via the "Referer" +header. diff --git a/docs/tutorial04.txt b/docs/tutorial04.txt index 737d8deb1f..4f9ef3baff 100644 --- a/docs/tutorial04.txt +++ b/docs/tutorial04.txt @@ -213,6 +213,9 @@ The generic views pass ``object`` and ``object_list`` to their templates, so change your templates so that ``latest_poll_list`` becomes ``object_list`` and ``poll`` becomes ``object``. +In the ``vote()`` view, change the template call from ``polls/detail`` to +``polls/polls_detail``, and pass ``object`` in the context instead of ``poll``. + Finally, you can delete the ``index()``, ``detail()`` and ``results()`` views from ``polls/views/polls.py``. We don't need them anymore. |