diff options
| author | Andrew Godwin <andrew@aeracode.org> | 2013-04-18 17:16:39 +0100 |
|---|---|---|
| committer | Andrew Godwin <andrew@aeracode.org> | 2013-04-18 17:16:39 +0100 |
| commit | 7f3678dc4cd7146c49bac3fb8f5211f647636aa3 (patch) | |
| tree | fdd2a60ccd1a9a3162d89f970db44502e35a3b3f /docs/ref | |
| parent | b62e82365ad56ca930f7abb1d1dbdf9ce5a7c7c3 (diff) | |
| parent | 93c1576f17f6c5ee73f94f8de007f3c33010dc81 (diff) | |
Merge branch 'master' into schema-alteration
Conflicts:
django/db/backends/__init__.py
django/db/backends/mysql/base.py
django/db/backends/oracle/base.py
django/db/backends/oracle/creation.py
django/db/backends/postgresql_psycopg2/base.py
django/db/backends/sqlite3/base.py
django/db/models/fields/related.py
Diffstat (limited to 'docs/ref')
86 files changed, 3520 insertions, 2292 deletions
diff --git a/docs/ref/authbackends.txt b/docs/ref/authbackends.txt deleted file mode 100644 index 55a536e819..0000000000 --- a/docs/ref/authbackends.txt +++ /dev/null @@ -1,33 +0,0 @@ -======================= -Authentication backends -======================= - -.. module:: django.contrib.auth.backends - :synopsis: Django's built-in authentication backend classes. - -This document details the authentication backends that come with Django. For -information on how to use them and how to write your own authentication -backends, see the :ref:`Other authentication sources section -<authentication-backends>` of the :doc:`User authentication guide -</topics/auth>`. - - -Available authentication backends -================================= - -The following backends are available in :mod:`django.contrib.auth.backends`: - -.. class:: ModelBackend - - This is the default authentication backend used by Django. It - authenticates using usernames and passwords stored in the - :class:`~django.contrib.auth.models.User` model. - - -.. class:: RemoteUserBackend - - Use this backend to take advantage of external-to-Django-handled - authentication. It authenticates using usernames passed in - :attr:`request.META['REMOTE_USER'] <django.http.HttpRequest.META>`. See - the :doc:`Authenticating against REMOTE_USER </howto/auth-remote-user>` - documentation. diff --git a/docs/ref/class-based-views/base.txt b/docs/ref/class-based-views/base.txt index cc9aa852f1..2073458314 100644 --- a/docs/ref/class-based-views/base.txt +++ b/docs/ref/class-based-views/base.txt @@ -49,9 +49,13 @@ View **Attributes** - .. attribute:: http_method_names = ['get', 'post', 'put', 'delete', 'head', 'options', 'trace'] + .. attribute:: http_method_names - The default list of HTTP method names that this view will accept. + The list of HTTP method names that this view will accept. + + Default:: + + ['get', 'post', 'put', 'delete', 'head', 'options', 'trace'] **Methods** @@ -68,12 +72,11 @@ View The default implementation will inspect the HTTP method and attempt to delegate to a method that matches the HTTP method; a ``GET`` will be - delegated to :meth:`~View.get()`, a ``POST`` to :meth:`~View.post()`, - and so on. + delegated to ``get()``, a ``POST`` to ``post()``, and so on. - By default, a ``HEAD`` request will be delegated to :meth:`~View.get()`. + By default, a ``HEAD`` request will be delegated to ``get()``. If you need to handle ``HEAD`` requests in a different way than ``GET``, - you can override the :meth:`~View.head()` method. See + you can override the ``head()`` method. See :ref:`supporting-other-http-methods` for an example. The default implementation also sets ``request``, ``args`` and @@ -98,8 +101,13 @@ TemplateView .. class:: django.views.generic.base.TemplateView - Renders a given template, passing it a ``{{ params }}`` template variable, - which is a dictionary of the parameters captured in the URL. + Renders a given template, with the context containing parameters captured + in the URL. + + .. versionchanged:: 1.5 + The context used to be populated with a ``{{ params }}`` dictionary of + the parameters captured in the URL. Now those parameters are first-level + context variables. **Ancestors (MRO)** @@ -111,9 +119,9 @@ TemplateView **Method Flowchart** - 1. :meth:`dispatch()` - 2. :meth:`http_method_not_allowed()` - 3. :meth:`get_context_data()` + 1. :meth:`~django.views.generic.base.View.dispatch()` + 2. :meth:`~django.views.generic.base.View.http_method_not_allowed()` + 3. :meth:`~django.views.generic.base.ContextMixin.get_context_data()` **Example views.py**:: @@ -169,8 +177,8 @@ RedirectView **Method Flowchart** - 1. :meth:`dispatch()` - 2. :meth:`http_method_not_allowed()` + 1. :meth:`~django.views.generic.base.View.dispatch()` + 2. :meth:`~django.views.generic.base.View.http_method_not_allowed()` 3. :meth:`get_redirect_url()` **Example views.py**:: @@ -230,9 +238,8 @@ RedirectView Constructs the target URL for redirection. - The default implementation uses :attr:`~RedirectView.url` as a starting + The default implementation uses :attr:`url` as a starting string, performs expansion of ``%`` parameters in that string, as well - as the appending of query string if requested by - :attr:`~RedirectView.query_string`. Subclasses may implement any - behavior they wish, as long as the method returns a redirect-ready URL - string. + as the appending of query string if requested by :attr:`query_string`. + Subclasses may implement any behavior they wish, as long as the method + returns a redirect-ready URL string. diff --git a/docs/ref/class-based-views/flattened-index.txt b/docs/ref/class-based-views/flattened-index.txt index aa2f51f156..df00f87aa0 100644 --- a/docs/ref/class-based-views/flattened-index.txt +++ b/docs/ref/class-based-views/flattened-index.txt @@ -23,7 +23,7 @@ View * :meth:`~django.views.generic.base.View.as_view` * :meth:`~django.views.generic.base.View.dispatch` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` TemplateView @@ -32,17 +32,18 @@ TemplateView **Attributes** (with optional accessor): +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.base.View.http_method_names` -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.base.TemplateResponseMixin.template_name` [:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`] **Methods** * :meth:`~django.views.generic.base.View.as_view` * :meth:`~django.views.generic.base.View.dispatch` -* :meth:`~django.views.generic.base.TemplateView.get` -* :meth:`~django.views.generic.base.TemplateView.get_context_data` -* :meth:`~django.views.generic.base.View.head` +* ``get()`` +* :meth:`~django.views.generic.base.ContextMixin.get_context_data` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` @@ -60,15 +61,15 @@ RedirectView **Methods** * :meth:`~django.views.generic.base.View.as_view` -* :meth:`~django.views.generic.base.RedirectView.delete` +* ``delete()`` * :meth:`~django.views.generic.base.View.dispatch` -* :meth:`~django.views.generic.base.RedirectView.get` +* ``get()`` * :meth:`~django.views.generic.base.RedirectView.get_redirect_url` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` -* :meth:`~django.views.generic.base.RedirectView.options` -* :meth:`~django.views.generic.base.RedirectView.post` -* :meth:`~django.views.generic.base.RedirectView.put` +* ``options()`` +* ``post()`` +* ``put()`` Detail Views ------------ @@ -79,12 +80,13 @@ DetailView **Attributes** (with optional accessor): +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.detail.SingleObjectMixin.context_object_name` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name`] * :attr:`~django.views.generic.base.View.http_method_names` * :attr:`~django.views.generic.detail.SingleObjectMixin.model` * :attr:`~django.views.generic.detail.SingleObjectMixin.pk_url_kwarg` * :attr:`~django.views.generic.detail.SingleObjectMixin.queryset` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset`] -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.detail.SingleObjectMixin.slug_field` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field`] * :attr:`~django.views.generic.detail.SingleObjectMixin.slug_url_kwarg` * :attr:`~django.views.generic.base.TemplateResponseMixin.template_name` [:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`] @@ -95,10 +97,10 @@ DetailView * :meth:`~django.views.generic.base.View.as_view` * :meth:`~django.views.generic.base.View.dispatch` -* :meth:`~django.views.generic.detail.BaseDetailView.get` +* ``get()`` * :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data` * :meth:`~django.views.generic.detail.SingleObjectMixin.get_object` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` @@ -112,6 +114,7 @@ ListView **Attributes** (with optional accessor): * :attr:`~django.views.generic.list.MultipleObjectMixin.allow_empty` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_allow_empty`] +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.list.MultipleObjectMixin.context_object_name` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name`] * :attr:`~django.views.generic.base.View.http_method_names` * :attr:`~django.views.generic.list.MultipleObjectMixin.model` @@ -119,7 +122,7 @@ ListView * :attr:`~django.views.generic.list.MultipleObjectMixin.paginate_orphans` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_paginate_orphans`] * :attr:`~django.views.generic.list.MultipleObjectMixin.paginator_class` * :attr:`~django.views.generic.list.MultipleObjectMixin.queryset` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset`] -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.base.TemplateResponseMixin.template_name` [:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`] * :attr:`~django.views.generic.list.MultipleObjectTemplateResponseMixin.template_name_suffix` @@ -130,7 +133,7 @@ ListView * :meth:`~django.views.generic.list.BaseListView.get` * :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data` * :meth:`~django.views.generic.list.MultipleObjectMixin.get_paginator` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.list.MultipleObjectMixin.paginate_queryset` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` @@ -144,10 +147,11 @@ FormView **Attributes** (with optional accessor): +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.edit.FormMixin.form_class` [:meth:`~django.views.generic.edit.FormMixin.get_form_class`] * :attr:`~django.views.generic.base.View.http_method_names` * :attr:`~django.views.generic.edit.FormMixin.initial` [:meth:`~django.views.generic.edit.FormMixin.get_initial`] -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.edit.FormMixin.success_url` [:meth:`~django.views.generic.edit.FormMixin.get_success_url`] * :attr:`~django.views.generic.base.TemplateResponseMixin.template_name` [:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`] @@ -161,11 +165,9 @@ FormView * :meth:`~django.views.generic.edit.FormMixin.get_context_data` * :meth:`~django.views.generic.edit.FormMixin.get_form` * :meth:`~django.views.generic.edit.FormMixin.get_form_kwargs` -* :meth:`~django.views.generic.base.View.head` * :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.edit.ProcessFormView.post` * :meth:`~django.views.generic.edit.ProcessFormView.put` -* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` CreateView ~~~~~~~~~~ @@ -173,6 +175,7 @@ CreateView **Attributes** (with optional accessor): +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.detail.SingleObjectMixin.context_object_name` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name`] * :attr:`~django.views.generic.edit.FormMixin.form_class` [:meth:`~django.views.generic.edit.FormMixin.get_form_class`] * :attr:`~django.views.generic.base.View.http_method_names` @@ -180,7 +183,7 @@ CreateView * :attr:`~django.views.generic.detail.SingleObjectMixin.model` * :attr:`~django.views.generic.detail.SingleObjectMixin.pk_url_kwarg` * :attr:`~django.views.generic.detail.SingleObjectMixin.queryset` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset`] -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.detail.SingleObjectMixin.slug_field` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field`] * :attr:`~django.views.generic.detail.SingleObjectMixin.slug_url_kwarg` * :attr:`~django.views.generic.edit.FormMixin.success_url` [:meth:`~django.views.generic.edit.FormMixin.get_success_url`] @@ -199,10 +202,10 @@ CreateView * :meth:`~django.views.generic.edit.FormMixin.get_form` * :meth:`~django.views.generic.edit.FormMixin.get_form_kwargs` * :meth:`~django.views.generic.detail.SingleObjectMixin.get_object` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.edit.ProcessFormView.post` -* :meth:`~django.views.generic.edit.ProcessFormView.put` +* ``put()`` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` UpdateView @@ -211,6 +214,7 @@ UpdateView **Attributes** (with optional accessor): +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.detail.SingleObjectMixin.context_object_name` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name`] * :attr:`~django.views.generic.edit.FormMixin.form_class` [:meth:`~django.views.generic.edit.FormMixin.get_form_class`] * :attr:`~django.views.generic.base.View.http_method_names` @@ -218,7 +222,7 @@ UpdateView * :attr:`~django.views.generic.detail.SingleObjectMixin.model` * :attr:`~django.views.generic.detail.SingleObjectMixin.pk_url_kwarg` * :attr:`~django.views.generic.detail.SingleObjectMixin.queryset` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset`] -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.detail.SingleObjectMixin.slug_field` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field`] * :attr:`~django.views.generic.detail.SingleObjectMixin.slug_url_kwarg` * :attr:`~django.views.generic.edit.FormMixin.success_url` [:meth:`~django.views.generic.edit.FormMixin.get_success_url`] @@ -237,10 +241,10 @@ UpdateView * :meth:`~django.views.generic.edit.FormMixin.get_form` * :meth:`~django.views.generic.edit.FormMixin.get_form_kwargs` * :meth:`~django.views.generic.detail.SingleObjectMixin.get_object` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.edit.ProcessFormView.post` -* :meth:`~django.views.generic.edit.ProcessFormView.put` +* ``put()`` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` DeleteView @@ -249,12 +253,13 @@ DeleteView **Attributes** (with optional accessor): +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.detail.SingleObjectMixin.context_object_name` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name`] * :attr:`~django.views.generic.base.View.http_method_names` * :attr:`~django.views.generic.detail.SingleObjectMixin.model` * :attr:`~django.views.generic.detail.SingleObjectMixin.pk_url_kwarg` * :attr:`~django.views.generic.detail.SingleObjectMixin.queryset` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset`] -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.detail.SingleObjectMixin.slug_field` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field`] * :attr:`~django.views.generic.detail.SingleObjectMixin.slug_url_kwarg` * :attr:`~django.views.generic.edit.DeletionMixin.success_url` [:meth:`~django.views.generic.edit.DeletionMixin.get_success_url`] @@ -265,14 +270,14 @@ DeleteView **Methods** * :meth:`~django.views.generic.base.View.as_view` -* :meth:`~django.views.generic.edit.DeletionMixin.delete` +* ``delete()`` * :meth:`~django.views.generic.base.View.dispatch` -* :meth:`~django.views.generic.detail.BaseDetailView.get` +* ``get()`` * :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data` * :meth:`~django.views.generic.detail.SingleObjectMixin.get_object` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` -* :meth:`~django.views.generic.edit.DeletionMixin.post` +* ``post()`` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` Date-based views @@ -286,6 +291,7 @@ ArchiveIndexView * :attr:`~django.views.generic.list.MultipleObjectMixin.allow_empty` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_allow_empty`] * :attr:`~django.views.generic.dates.DateMixin.allow_future` [:meth:`~django.views.generic.dates.DateMixin.get_allow_future`] +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.list.MultipleObjectMixin.context_object_name` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name`] * :attr:`~django.views.generic.dates.DateMixin.date_field` [:meth:`~django.views.generic.dates.DateMixin.get_date_field`] * :attr:`~django.views.generic.base.View.http_method_names` @@ -294,7 +300,7 @@ ArchiveIndexView * :attr:`~django.views.generic.list.MultipleObjectMixin.paginate_orphans` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_paginate_orphans`] * :attr:`~django.views.generic.list.MultipleObjectMixin.paginator_class` * :attr:`~django.views.generic.list.MultipleObjectMixin.queryset` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset`] -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.base.TemplateResponseMixin.template_name` [:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`] * :attr:`~django.views.generic.list.MultipleObjectTemplateResponseMixin.template_name_suffix` @@ -302,13 +308,13 @@ ArchiveIndexView * :meth:`~django.views.generic.base.View.as_view` * :meth:`~django.views.generic.base.View.dispatch` -* :meth:`~django.views.generic.dates.BaseDateListView.get` +* ``get()`` * :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data` * :meth:`~django.views.generic.dates.BaseDateListView.get_date_list` * :meth:`~django.views.generic.dates.BaseDateListView.get_dated_items` * :meth:`~django.views.generic.dates.BaseDateListView.get_dated_queryset` * :meth:`~django.views.generic.list.MultipleObjectMixin.get_paginator` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.list.MultipleObjectMixin.paginate_queryset` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` @@ -321,16 +327,17 @@ YearArchiveView * :attr:`~django.views.generic.list.MultipleObjectMixin.allow_empty` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_allow_empty`] * :attr:`~django.views.generic.dates.DateMixin.allow_future` [:meth:`~django.views.generic.dates.DateMixin.get_allow_future`] +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.list.MultipleObjectMixin.context_object_name` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name`] * :attr:`~django.views.generic.dates.DateMixin.date_field` [:meth:`~django.views.generic.dates.DateMixin.get_date_field`] * :attr:`~django.views.generic.base.View.http_method_names` -* :attr:`~django.views.generic.dates.BaseYearArchiveView.make_object_list` [:meth:`~django.views.generic.dates.BaseYearArchiveView.get_make_object_list`] +* :attr:`~django.views.generic.dates.YearArchiveView.make_object_list` [:meth:`~django.views.generic.dates.YearArchiveView.get_make_object_list`] * :attr:`~django.views.generic.list.MultipleObjectMixin.model` * :attr:`~django.views.generic.list.MultipleObjectMixin.paginate_by` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_paginate_by`] * :attr:`~django.views.generic.list.MultipleObjectMixin.paginate_orphans` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_paginate_orphans`] * :attr:`~django.views.generic.list.MultipleObjectMixin.paginator_class` * :attr:`~django.views.generic.list.MultipleObjectMixin.queryset` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset`] -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.base.TemplateResponseMixin.template_name` [:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`] * :attr:`~django.views.generic.list.MultipleObjectTemplateResponseMixin.template_name_suffix` * :attr:`~django.views.generic.dates.YearMixin.year` [:meth:`~django.views.generic.dates.YearMixin.get_year`] @@ -340,13 +347,13 @@ YearArchiveView * :meth:`~django.views.generic.base.View.as_view` * :meth:`~django.views.generic.base.View.dispatch` -* :meth:`~django.views.generic.dates.BaseDateListView.get` +* ``get()`` * :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data` * :meth:`~django.views.generic.dates.BaseDateListView.get_date_list` * :meth:`~django.views.generic.dates.BaseDateListView.get_dated_items` * :meth:`~django.views.generic.dates.BaseDateListView.get_dated_queryset` * :meth:`~django.views.generic.list.MultipleObjectMixin.get_paginator` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.list.MultipleObjectMixin.paginate_queryset` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` @@ -359,6 +366,7 @@ MonthArchiveView * :attr:`~django.views.generic.list.MultipleObjectMixin.allow_empty` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_allow_empty`] * :attr:`~django.views.generic.dates.DateMixin.allow_future` [:meth:`~django.views.generic.dates.DateMixin.get_allow_future`] +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.list.MultipleObjectMixin.context_object_name` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name`] * :attr:`~django.views.generic.dates.DateMixin.date_field` [:meth:`~django.views.generic.dates.DateMixin.get_date_field`] * :attr:`~django.views.generic.base.View.http_method_names` @@ -369,7 +377,7 @@ MonthArchiveView * :attr:`~django.views.generic.list.MultipleObjectMixin.paginate_orphans` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_paginate_orphans`] * :attr:`~django.views.generic.list.MultipleObjectMixin.paginator_class` * :attr:`~django.views.generic.list.MultipleObjectMixin.queryset` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset`] -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.base.TemplateResponseMixin.template_name` [:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`] * :attr:`~django.views.generic.list.MultipleObjectTemplateResponseMixin.template_name_suffix` * :attr:`~django.views.generic.dates.YearMixin.year` [:meth:`~django.views.generic.dates.YearMixin.get_year`] @@ -379,7 +387,7 @@ MonthArchiveView * :meth:`~django.views.generic.base.View.as_view` * :meth:`~django.views.generic.base.View.dispatch` -* :meth:`~django.views.generic.dates.BaseDateListView.get` +* ``get()`` * :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data` * :meth:`~django.views.generic.dates.BaseDateListView.get_date_list` * :meth:`~django.views.generic.dates.BaseDateListView.get_dated_items` @@ -387,7 +395,7 @@ MonthArchiveView * :meth:`~django.views.generic.dates.MonthMixin.get_next_month` * :meth:`~django.views.generic.list.MultipleObjectMixin.get_paginator` * :meth:`~django.views.generic.dates.MonthMixin.get_previous_month` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.list.MultipleObjectMixin.paginate_queryset` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` @@ -400,6 +408,7 @@ WeekArchiveView * :attr:`~django.views.generic.list.MultipleObjectMixin.allow_empty` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_allow_empty`] * :attr:`~django.views.generic.dates.DateMixin.allow_future` [:meth:`~django.views.generic.dates.DateMixin.get_allow_future`] +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.list.MultipleObjectMixin.context_object_name` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name`] * :attr:`~django.views.generic.dates.DateMixin.date_field` [:meth:`~django.views.generic.dates.DateMixin.get_date_field`] * :attr:`~django.views.generic.base.View.http_method_names` @@ -408,7 +417,7 @@ WeekArchiveView * :attr:`~django.views.generic.list.MultipleObjectMixin.paginate_orphans` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_paginate_orphans`] * :attr:`~django.views.generic.list.MultipleObjectMixin.paginator_class` * :attr:`~django.views.generic.list.MultipleObjectMixin.queryset` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset`] -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.base.TemplateResponseMixin.template_name` [:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`] * :attr:`~django.views.generic.list.MultipleObjectTemplateResponseMixin.template_name_suffix` * :attr:`~django.views.generic.dates.WeekMixin.week` [:meth:`~django.views.generic.dates.WeekMixin.get_week`] @@ -420,13 +429,13 @@ WeekArchiveView * :meth:`~django.views.generic.base.View.as_view` * :meth:`~django.views.generic.base.View.dispatch` -* :meth:`~django.views.generic.dates.BaseDateListView.get` +* ``get()`` * :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data` * :meth:`~django.views.generic.dates.BaseDateListView.get_date_list` * :meth:`~django.views.generic.dates.BaseDateListView.get_dated_items` * :meth:`~django.views.generic.dates.BaseDateListView.get_dated_queryset` * :meth:`~django.views.generic.list.MultipleObjectMixin.get_paginator` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.list.MultipleObjectMixin.paginate_queryset` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` @@ -439,6 +448,7 @@ DayArchiveView * :attr:`~django.views.generic.list.MultipleObjectMixin.allow_empty` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_allow_empty`] * :attr:`~django.views.generic.dates.DateMixin.allow_future` [:meth:`~django.views.generic.dates.DateMixin.get_allow_future`] +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.list.MultipleObjectMixin.context_object_name` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name`] * :attr:`~django.views.generic.dates.DateMixin.date_field` [:meth:`~django.views.generic.dates.DateMixin.get_date_field`] * :attr:`~django.views.generic.dates.DayMixin.day` [:meth:`~django.views.generic.dates.DayMixin.get_day`] @@ -451,7 +461,7 @@ DayArchiveView * :attr:`~django.views.generic.list.MultipleObjectMixin.paginate_orphans` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_paginate_orphans`] * :attr:`~django.views.generic.list.MultipleObjectMixin.paginator_class` * :attr:`~django.views.generic.list.MultipleObjectMixin.queryset` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset`] -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.base.TemplateResponseMixin.template_name` [:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`] * :attr:`~django.views.generic.list.MultipleObjectTemplateResponseMixin.template_name_suffix` * :attr:`~django.views.generic.dates.YearMixin.year` [:meth:`~django.views.generic.dates.YearMixin.get_year`] @@ -461,7 +471,7 @@ DayArchiveView * :meth:`~django.views.generic.base.View.as_view` * :meth:`~django.views.generic.base.View.dispatch` -* :meth:`~django.views.generic.dates.BaseDateListView.get` +* ``get()`` * :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data` * :meth:`~django.views.generic.dates.BaseDateListView.get_date_list` * :meth:`~django.views.generic.dates.BaseDateListView.get_dated_items` @@ -471,7 +481,7 @@ DayArchiveView * :meth:`~django.views.generic.list.MultipleObjectMixin.get_paginator` * :meth:`~django.views.generic.dates.DayMixin.get_previous_day` * :meth:`~django.views.generic.dates.MonthMixin.get_previous_month` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.list.MultipleObjectMixin.paginate_queryset` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` @@ -484,6 +494,7 @@ TodayArchiveView * :attr:`~django.views.generic.list.MultipleObjectMixin.allow_empty` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_allow_empty`] * :attr:`~django.views.generic.dates.DateMixin.allow_future` [:meth:`~django.views.generic.dates.DateMixin.get_allow_future`] +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.list.MultipleObjectMixin.context_object_name` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name`] * :attr:`~django.views.generic.dates.DateMixin.date_field` [:meth:`~django.views.generic.dates.DateMixin.get_date_field`] * :attr:`~django.views.generic.dates.DayMixin.day` [:meth:`~django.views.generic.dates.DayMixin.get_day`] @@ -496,7 +507,7 @@ TodayArchiveView * :attr:`~django.views.generic.list.MultipleObjectMixin.paginate_orphans` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_paginate_orphans`] * :attr:`~django.views.generic.list.MultipleObjectMixin.paginator_class` * :attr:`~django.views.generic.list.MultipleObjectMixin.queryset` [:meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset`] -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.base.TemplateResponseMixin.template_name` [:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`] * :attr:`~django.views.generic.list.MultipleObjectTemplateResponseMixin.template_name_suffix` * :attr:`~django.views.generic.dates.YearMixin.year` [:meth:`~django.views.generic.dates.YearMixin.get_year`] @@ -506,7 +517,7 @@ TodayArchiveView * :meth:`~django.views.generic.base.View.as_view` * :meth:`~django.views.generic.base.View.dispatch` -* :meth:`~django.views.generic.dates.BaseDateListView.get` +* ``get()`` * :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data` * :meth:`~django.views.generic.dates.BaseDateListView.get_date_list` * :meth:`~django.views.generic.dates.BaseDateListView.get_dated_items` @@ -516,7 +527,7 @@ TodayArchiveView * :meth:`~django.views.generic.list.MultipleObjectMixin.get_paginator` * :meth:`~django.views.generic.dates.DayMixin.get_previous_day` * :meth:`~django.views.generic.dates.MonthMixin.get_previous_month` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.list.MultipleObjectMixin.paginate_queryset` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` @@ -528,6 +539,7 @@ DateDetailView **Attributes** (with optional accessor): * :attr:`~django.views.generic.dates.DateMixin.allow_future` [:meth:`~django.views.generic.dates.DateMixin.get_allow_future`] +* :attr:`~django.views.generic.base.TemplateResponseMixin.content_type` * :attr:`~django.views.generic.detail.SingleObjectMixin.context_object_name` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name`] * :attr:`~django.views.generic.dates.DateMixin.date_field` [:meth:`~django.views.generic.dates.DateMixin.get_date_field`] * :attr:`~django.views.generic.dates.DayMixin.day` [:meth:`~django.views.generic.dates.DayMixin.get_day`] @@ -538,7 +550,7 @@ DateDetailView * :attr:`~django.views.generic.dates.MonthMixin.month_format` [:meth:`~django.views.generic.dates.MonthMixin.get_month_format`] * :attr:`~django.views.generic.detail.SingleObjectMixin.pk_url_kwarg` * :attr:`~django.views.generic.detail.SingleObjectMixin.queryset` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset`] -* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` +* :attr:`~django.views.generic.base.TemplateResponseMixin.response_class` [:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`] * :attr:`~django.views.generic.detail.SingleObjectMixin.slug_field` [:meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field`] * :attr:`~django.views.generic.detail.SingleObjectMixin.slug_url_kwarg` * :attr:`~django.views.generic.base.TemplateResponseMixin.template_name` [:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`] @@ -551,13 +563,13 @@ DateDetailView * :meth:`~django.views.generic.base.View.as_view` * :meth:`~django.views.generic.base.View.dispatch` -* :meth:`~django.views.generic.detail.BaseDetailView.get` +* ``get()`` * :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data` * :meth:`~django.views.generic.dates.DayMixin.get_next_day` * :meth:`~django.views.generic.dates.MonthMixin.get_next_month` * :meth:`~django.views.generic.detail.SingleObjectMixin.get_object` * :meth:`~django.views.generic.dates.DayMixin.get_previous_day` * :meth:`~django.views.generic.dates.MonthMixin.get_previous_month` -* :meth:`~django.views.generic.base.View.head` +* ``head()`` * :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` diff --git a/docs/ref/class-based-views/generic-date-based.txt b/docs/ref/class-based-views/generic-date-based.txt index 0ae0bcdf42..4144c382f8 100644 --- a/docs/ref/class-based-views/generic-date-based.txt +++ b/docs/ref/class-based-views/generic-date-based.txt @@ -42,6 +42,20 @@ ArchiveIndexView * :class:`django.views.generic.dates.DateMixin` * :class:`django.views.generic.base.View` + **Context** + + In addition to the context provided by + :class:`django.views.generic.list.MultipleObjectMixin` (via + :class:`django.views.generic.dates.BaseDateListView`), the template's + context will be: + + * ``date_list``: A + :meth:`DateQuerySet<django.db.models.query.QuerySet.dates>` object + containing all years that have objects available according to + ``queryset``, represented as + :class:`datetime.datetime<python:datetime.datetime>` objects, in + descending order. + **Notes** * Uses a default ``context_object_name`` of ``latest``. @@ -109,7 +123,6 @@ YearArchiveView Determine if an object list will be returned as part of the context. Returns :attr:`~YearArchiveView.make_object_list` by default. - **Context** In addition to the context provided by @@ -118,7 +131,7 @@ YearArchiveView context will be: * ``date_list``: A - :meth:`DateQuerySet<django.db.models.query.QuerySet.dates>` object object + :meth:`DateQuerySet<django.db.models.query.QuerySet.dates>` object containing all months that have objects available according to ``queryset``, represented as :class:`datetime.datetime<python:datetime.datetime>` objects, in @@ -580,7 +593,7 @@ DateDetailView * :class:`django.views.generic.dates.MonthMixin` * :class:`django.views.generic.dates.DayMixin` * :class:`django.views.generic.dates.DateMixin` - * :class:`django.views.generic.detail.BaseDetailView` + * ``django.views.generic.detail.BaseDetailView`` * :class:`django.views.generic.detail.SingleObjectMixin` * :class:`django.views.generic.base.View` diff --git a/docs/ref/class-based-views/generic-display.txt b/docs/ref/class-based-views/generic-display.txt index 12603ff0df..b827c0005c 100644 --- a/docs/ref/class-based-views/generic-display.txt +++ b/docs/ref/class-based-views/generic-display.txt @@ -19,22 +19,22 @@ DetailView * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin` * :class:`django.views.generic.base.TemplateResponseMixin` - * :class:`django.views.generic.detail.BaseDetailView` + * ``django.views.generic.detail.BaseDetailView`` * :class:`django.views.generic.detail.SingleObjectMixin` * :class:`django.views.generic.base.View` **Method Flowchart** - 1. :meth:`dispatch()` - 2. :meth:`http_method_not_allowed()` - 3. :meth:`get_template_names()` - 4. :meth:`get_slug_field()` - 5. :meth:`get_queryset()` - 6. :meth:`get_object()` - 7. :meth:`get_context_object_name()` - 8. :meth:`get_context_data()` - 9. :meth:`get()` - 10. :meth:`render_to_response()` + 1. :meth:`~django.views.generic.base.View.dispatch()` + 2. :meth:`~django.views.generic.base.View.http_method_not_allowed()` + 3. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()` + 4. :meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field()` + 5. :meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset()` + 6. :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()` + 7. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name()` + 8. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data()` + 9. ``get()`` + 10. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` **Example views.py**:: @@ -86,14 +86,14 @@ ListView **Method Flowchart** - 1. :meth:`dispatch()` - 2. :meth:`http_method_not_allowed()` - 3. :meth:`get_template_names()` - 4. :meth:`get_queryset()` - 5. :meth:`get_objects()` - 6. :meth:`get_context_data()` - 7. :meth:`get()` - 8. :meth:`render_to_response()` + 1. :meth:`~django.views.generic.base.View.dispatch()` + 2. :meth:`~django.views.generic.base.View.http_method_not_allowed()` + 3. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()` + 4. :meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset()` + 5. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name()` + 6. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data()` + 7. ``get()`` + 8. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` **Example views.py**:: @@ -140,7 +140,7 @@ ListView .. method:: get(request, *args, **kwargs) - Adds :attr:`object_list` to the context. If + Adds ``object_list`` to the context. If :attr:`~django.views.generic.list.MultipleObjectMixin.allow_empty` is True then display an empty list. If :attr:`~django.views.generic.list.MultipleObjectMixin.allow_empty` is diff --git a/docs/ref/class-based-views/generic-editing.txt b/docs/ref/class-based-views/generic-editing.txt index 7ce5c1d1be..1dbb427036 100644 --- a/docs/ref/class-based-views/generic-editing.txt +++ b/docs/ref/class-based-views/generic-editing.txt @@ -12,7 +12,7 @@ editing content: .. note:: - Some of the examples on this page assume that an ``Article`` model has been + Some of the examples on this page assume that an ``Author`` model has been defined as follows in ``myapp/models.py``:: from django.core.urlresolvers import reverse @@ -38,7 +38,7 @@ FormView * :class:`django.views.generic.edit.FormView` * :class:`django.views.generic.base.TemplateResponseMixin` - * :class:`django.views.generic.edit.BaseFormView` + * ``django.views.generic.edit.BaseFormView`` * :class:`django.views.generic.edit.FormMixin` * :class:`django.views.generic.edit.ProcessFormView` * :class:`django.views.generic.base.View` @@ -86,7 +86,7 @@ CreateView * :class:`django.views.generic.edit.CreateView` * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin` * :class:`django.views.generic.base.TemplateResponseMixin` - * :class:`django.views.generic.edit.BaseCreateView` + * ``django.views.generic.edit.BaseCreateView`` * :class:`django.views.generic.edit.ModelFormMixin` * :class:`django.views.generic.edit.FormMixin` * :class:`django.views.generic.detail.SingleObjectMixin` @@ -97,11 +97,11 @@ CreateView .. attribute:: template_name_suffix - The CreateView page displayed to a GET request uses a - ``template_name_suffix`` of ``'_form.html'``. For - example, changing this attribute to ``'_create_form.html'`` for a view - creating objects for the the example `Author` model would cause the the - default `template_name` to be ``'myapp/author_create_form.html'``. + The ``CreateView`` page displayed to a ``GET`` request uses a + ``template_name_suffix`` of ``'_form'``. For + example, changing this attribute to ``'_create_form'`` for a view + creating objects for the example ``Author`` model would cause the + default ``template_name`` to be ``'myapp/author_create_form.html'``. **Example views.py**:: @@ -128,7 +128,7 @@ UpdateView * :class:`django.views.generic.edit.UpdateView` * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin` * :class:`django.views.generic.base.TemplateResponseMixin` - * :class:`django.views.generic.edit.BaseUpdateView` + * ``django.views.generic.edit.BaseUpdateView`` * :class:`django.views.generic.edit.ModelFormMixin` * :class:`django.views.generic.edit.FormMixin` * :class:`django.views.generic.detail.SingleObjectMixin` @@ -139,11 +139,11 @@ UpdateView .. attribute:: template_name_suffix - The UpdateView page displayed to a GET request uses a - ``template_name_suffix`` of ``'_form.html'``. For - example, changing this attribute to ``'_update_form.html'`` for a view - updating objects for the the example `Author` model would cause the the - default `template_name` to be ``'myapp/author_update_form.html'``. + The ``UpdateView`` page displayed to a ``GET`` request uses a + ``template_name_suffix`` of ``'_form'``. For + example, changing this attribute to ``'_update_form'`` for a view + updating objects for the example ``Author`` model would cause the + default ``template_name`` to be ``'myapp/author_update_form.html'``. **Example views.py**:: @@ -170,9 +170,9 @@ DeleteView * :class:`django.views.generic.edit.DeleteView` * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin` * :class:`django.views.generic.base.TemplateResponseMixin` - * :class:`django.views.generic.edit.BaseDeleteView` + * ``django.views.generic.edit.BaseDeleteView`` * :class:`django.views.generic.edit.DeletionMixin` - * :class:`django.views.generic.detail.BaseDetailView` + * ``django.views.generic.detail.BaseDetailView`` * :class:`django.views.generic.detail.SingleObjectMixin` * :class:`django.views.generic.base.View` @@ -180,11 +180,11 @@ DeleteView .. attribute:: template_name_suffix - The DeleteView page displayed to a GET request uses a - ``template_name_suffix`` of ``'_confirm_delete.html'``. For - example, changing this attribute to ``'_check_delete.html'`` for a view - deleting objects for the the example `Author` model would cause the the - default `template_name` to be ``'myapp/author_check_delete.html'``. + The ``DeleteView`` page displayed to a ``GET`` request uses a + ``template_name_suffix`` of ``'_confirm_delete'``. For + example, changing this attribute to ``'_check_delete'`` for a view + deleting objects for the example ``Author`` model would cause the + default ``template_name`` to be ``'myapp/author_check_delete.html'``. **Example views.py**:: diff --git a/docs/ref/class-based-views/mixins-date-based.txt b/docs/ref/class-based-views/mixins-date-based.txt index 561e525e70..75f2a77615 100644 --- a/docs/ref/class-based-views/mixins-date-based.txt +++ b/docs/ref/class-based-views/mixins-date-based.txt @@ -35,8 +35,8 @@ YearMixin Tries the following sources, in order: * The value of the :attr:`YearMixin.year` attribute. - * The value of the `year` argument captured in the URL pattern. - * The value of the `year` GET query argument. + * The value of the ``year`` argument captured in the URL pattern. + * The value of the ``year`` ``GET`` query argument. Raises a 404 if no valid year specification can be found. @@ -87,8 +87,8 @@ MonthMixin Tries the following sources, in order: * The value of the :attr:`MonthMixin.month` attribute. - * The value of the `month` argument captured in the URL pattern. - * The value of the `month` GET query argument. + * The value of the ``month`` argument captured in the URL pattern. + * The value of the ``month`` ``GET`` query argument. Raises a 404 if no valid month specification can be found. @@ -100,7 +100,7 @@ MonthMixin :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. - .. method:: get_prev_month(date) + .. method:: get_previous_month(date) Returns a date object containing the first day of the month before the date provided. This function can also return ``None`` or raise an @@ -139,8 +139,8 @@ DayMixin Tries the following sources, in order: * The value of the :attr:`DayMixin.day` attribute. - * The value of the `day` argument captured in the URL pattern. - * The value of the `day` GET query argument. + * The value of the ``day`` argument captured in the URL pattern. + * The value of the ``day`` ``GET`` query argument. Raises a 404 if no valid day specification can be found. @@ -152,7 +152,7 @@ DayMixin :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. - .. method:: get_prev_day(date) + .. method:: get_previous_day(date) Returns a date object containing the previous valid day. This function can also return ``None`` or raise an :class:`~django.http.Http404` @@ -192,8 +192,8 @@ WeekMixin Tries the following sources, in order: * The value of the :attr:`WeekMixin.week` attribute. - * The value of the `week` argument captured in the URL pattern - * The value of the `week` GET query argument. + * The value of the ``week`` argument captured in the URL pattern + * The value of the ``week`` ``GET`` query argument. Raises a 404 if no valid week specification can be found. @@ -287,8 +287,9 @@ BaseDateListView available. If this is ``True`` and no objects are available, the view will display an empty page instead of raising a 404. - This is identical to :attr:`MultipleObjectMixin.allow_empty`, except - for the default value, which is ``False``. + This is identical to + :attr:`django.views.generic.list.MultipleObjectMixin.allow_empty`, + except for the default value, which is ``False``. .. attribute:: date_list_period diff --git a/docs/ref/class-based-views/mixins-editing.txt b/docs/ref/class-based-views/mixins-editing.txt index 95dd24f442..a4175369aa 100644 --- a/docs/ref/class-based-views/mixins-editing.txt +++ b/docs/ref/class-based-views/mixins-editing.txt @@ -40,11 +40,6 @@ FormMixin Retrieve initial data for the form. By default, returns a copy of :attr:`~django.views.generic.edit.FormMixin.initial`. - .. versionchanged:: 1.4 - In Django 1.3, this method was returning the - :attr:`~django.views.generic.edit.FormMixin.initial` class variable - itself. - .. method:: get_form_class() Retrieve the form class to instantiate. By default @@ -88,9 +83,8 @@ FormMixin .. note:: - Views mixing :class:`FormMixin` must provide an implementation of - :meth:`~django.views.generic.FormMixin.form_valid` and - :meth:`~django.views.generic.FormMixin.form_invalid`. + Views mixing ``FormMixin`` must provide an implementation of + :meth:`form_valid` and :meth:`form_invalid`. ModelFormMixin @@ -98,15 +92,16 @@ ModelFormMixin .. class:: django.views.generic.edit.ModelFormMixin - A form mixin that works on ModelForms, rather than a standalone form. + A form mixin that works on ``ModelForms``, rather than a standalone form. Since this is a subclass of :class:`~django.views.generic.detail.SingleObjectMixin`, instances of this - mixin have access to the :attr:`~SingleObjectMixin.model` and - :attr:`~SingleObjectMixin.queryset` attributes, describing the type of - object that the ModelForm is manipulating. The view also provides - ``self.object``, the instance being manipulated. If the instance is being - created, ``self.object`` will be ``None``. + mixin have access to the + :attr:`~django.views.generic.detail.SingleObjectMixin.model` and + :attr:`~django.views.generic.detail.SingleObjectMixin.queryset` attributes, + describing the type of object that the ``ModelForm`` is manipulating. The + view also provides ``self.object``, the instance being manipulated. If the + instance is being created, ``self.object`` will be ``None``. **Mixins** @@ -115,6 +110,12 @@ ModelFormMixin **Methods and Attributes** + .. attribute:: model + + A model class. Can be explicitly provided, otherwise will be determined + by examining ``self.object`` or + :attr:`~django.views.generic.detail.SingleObjectMixin.queryset`. + .. attribute:: success_url The URL to redirect to when the form is successfully processed. @@ -127,22 +128,25 @@ ModelFormMixin .. method:: get_form_class() Retrieve the form class to instantiate. If - :attr:`FormMixin.form_class` is provided, that class will be used. - Otherwise, a ModelForm will be instantiated using the model associated - with the :attr:`~SingleObjectMixin.queryset`, or with the - :attr:`~SingleObjectMixin.model`, depending on which attribute is - provided. + :attr:`~django.views.generic.edit.FormMixin.form_class` is provided, + that class will be used. Otherwise, a ``ModelForm`` will be + instantiated using the model associated with the + :attr:`~django.views.generic.detail.SingleObjectMixin.queryset`, or + with the :attr:`~django.views.generic.detail.SingleObjectMixin.model`, + depending on which attribute is provided. .. method:: get_form_kwargs() Add the current instance (``self.object``) to the standard - :meth:`FormMixin.get_form_kwargs`. + :meth:`~django.views.generic.edit.FormMixin.get_form_kwargs`. .. method:: get_success_url() Determine the URL to redirect to when the form is successfully - validated. Returns :attr:`ModelFormMixin.success_url` if it is provided; - otherwise, attempts to use the ``get_absolute_url()`` of the object. + validated. Returns + :attr:`django.views.generic.edit.ModelFormMixin.success_url` if it is + provided; otherwise, attempts to use the ``get_absolute_url()`` of the + object. .. method:: form_valid(form) @@ -184,7 +188,10 @@ ProcessFormView Constructs a form, checks the form for validity, and handles it accordingly. - The PUT action is also handled, as an analog of POST. + .. method:: put(*args, **kwargs) + + The ``PUT`` action is also handled and just passes all parameters + through to :meth:`post`. .. class:: django.views.generic.edit.DeletionMixin @@ -197,7 +204,14 @@ ProcessFormView The url to redirect to when the nominated object has been successfully deleted. - .. method:: get_success_url(obj) + .. versionadded:: 1.6 + + ``success_url`` may contain dictionary string formatting, which + will be interpolated against the object's field attributes. For + example, you could use ``success_url="/parent/%(parent_id)s/"`` to + redirect to a URL composed out of the ``parent_id`` field on a model. + + .. method:: get_success_url() Returns the url to redirect to when the nominated object has been successfully deleted. Returns diff --git a/docs/ref/class-based-views/mixins-multiple-object.txt b/docs/ref/class-based-views/mixins-multiple-object.txt index c85c962bce..b28bd11a71 100644 --- a/docs/ref/class-based-views/mixins-multiple-object.txt +++ b/docs/ref/class-based-views/mixins-multiple-object.txt @@ -61,14 +61,13 @@ MultipleObjectMixin .. attribute:: queryset A ``QuerySet`` that represents the objects. If provided, the value of - :attr:`MultipleObjectMixin.queryset` supersedes the value provided for - :attr:`MultipleObjectMixin.model`. + ``queryset`` supersedes the value provided for :attr:`model`. .. attribute:: paginate_by An integer specifying how many objects should be displayed per page. If this is given, the view will paginate objects with - :attr:`MultipleObjectMixin.paginate_by` objects per page. The view will + ``paginate_by`` objects per page. The view will expect either a ``page`` query string parameter (via ``request.GET``) or a ``page`` variable specified in the URLconf. @@ -77,10 +76,9 @@ MultipleObjectMixin .. versionadded:: 1.6 An integer specifying the number of "overflow" objects the last page - can contain. This extends the :attr:`MultipleObjectMixin.paginate_by` - limit on the last page by up to - :attr:`MultipleObjectMixin.paginate_orphans`, in order to keep the last - page from having a very small number of objects. + can contain. This extends the :attr:`paginate_by` limit on the last + page by up to ``paginate_orphans``, in order to keep the last page from + having a very small number of objects. .. attribute:: page_kwarg @@ -97,7 +95,7 @@ MultipleObjectMixin :class:`django.core.paginator.Paginator` is used. If the custom paginator class doesn't have the same constructor interface as :class:`django.core.paginator.Paginator`, you will also need to - provide an implementation for :meth:`MultipleObjectMixin.get_paginator`. + provide an implementation for :meth:`get_paginator`. .. attribute:: context_object_name @@ -122,20 +120,20 @@ MultipleObjectMixin Returns the number of items to paginate by, or ``None`` for no pagination. By default this simply returns the value of - :attr:`MultipleObjectMixin.paginate_by`. + :attr:`paginate_by`. .. method:: get_paginator(queryset, per_page, orphans=0, allow_empty_first_page=True) Returns an instance of the paginator to use for this view. By default, instantiates an instance of :attr:`paginator_class`. - .. method:: get_paginate_by() + .. method:: get_paginate_orphans() .. versionadded:: 1.6 An integer specifying the number of "overflow" objects the last page can contain. By default this simply returns the value of - :attr:`MultipleObjectMixin.paginate_orphans`. + :attr:`paginate_orphans`. .. method:: get_allow_empty() @@ -149,7 +147,7 @@ MultipleObjectMixin Return the context variable name that will be used to contain the list of data that this view is manipulating. If ``object_list`` is a queryset of Django objects and - :attr:`~MultipleObjectMixin.context_object_name` is not set, + :attr:`context_object_name` is not set, the context name will be the ``object_name`` of the model that the queryset is composed from, with postfix ``'_list'`` appended. For example, the model ``Article`` would have a diff --git a/docs/ref/class-based-views/mixins-simple.txt b/docs/ref/class-based-views/mixins-simple.txt index d2f0df241e..51b0386654 100644 --- a/docs/ref/class-based-views/mixins-simple.txt +++ b/docs/ref/class-based-views/mixins-simple.txt @@ -48,7 +48,7 @@ TemplateResponseMixin .. attribute:: template_name The full name of a template to use as defined by a string. Not defining - a template_name will raise a + a ``template_name`` will raise a :class:`django.core.exceptions.ImproperlyConfigured` exception. .. attribute:: response_class @@ -64,6 +64,15 @@ TemplateResponseMixin instantiation, create a ``TemplateResponse`` subclass and assign it to ``response_class``. + .. attribute:: content_type + + .. versionadded:: 1.5 + The ``content_type`` attribute was added. + + The content type to use for the response. ``content_type`` is passed + as a keyword argument to ``response_class``. Default is ``None`` -- + meaning that Django uses :setting:`DEFAULT_CONTENT_TYPE`. + **Methods** .. method:: render_to_response(context, **response_kwargs) @@ -73,15 +82,13 @@ TemplateResponseMixin If any keyword arguments are provided, they will be passed to the constructor of the response class. - Calls :meth:`~TemplateResponseMixin.get_template_names()` to obtain the - list of template names that will be searched looking for an existent - template. + Calls :meth:`get_template_names()` to obtain the list of template names + that will be searched looking for an existent template. .. method:: get_template_names() Returns a list of template names to search for when rendering the template. - If :attr:`TemplateResponseMixin.template_name` is specified, the - default implementation will return a list containing - :attr:`TemplateResponseMixin.template_name` (if it is specified). + If :attr:`template_name` is specified, the default implementation will + return a list containing :attr:`template_name` (if it is specified). diff --git a/docs/ref/class-based-views/mixins-single-object.txt b/docs/ref/class-based-views/mixins-single-object.txt index 77f52b96c6..bbe930d79e 100644 --- a/docs/ref/class-based-views/mixins-single-object.txt +++ b/docs/ref/class-based-views/mixins-single-object.txt @@ -21,8 +21,7 @@ SingleObjectMixin .. attribute:: queryset A ``QuerySet`` that represents the objects. If provided, the value of - :attr:`SingleObjectMixin.queryset` supersedes the value provided for - :attr:`SingleObjectMixin.model`. + ``queryset`` supersedes the value provided for :attr:`model`. .. attribute:: slug_field @@ -31,15 +30,11 @@ SingleObjectMixin .. attribute:: slug_url_kwarg - .. versionadded:: 1.4 - The name of the URLConf keyword argument that contains the slug. By default, ``slug_url_kwarg`` is ``'slug'``. .. attribute:: pk_url_kwarg - .. versionadded:: 1.4 - The name of the URLConf keyword argument that contains the primary key. By default, ``pk_url_kwarg`` is ``'pk'``. @@ -51,38 +46,38 @@ SingleObjectMixin Returns the single object that this view will display. If ``queryset`` is provided, that queryset will be used as the - source of objects; otherwise, - :meth:`~SingleObjectMixin.get_queryset` will be used. - ``get_object()`` looks for a - :attr:`SingleObjectMixin.pk_url_kwarg` argument in the arguments - to the view; if this argument is found, this method performs a - primary-key based lookup using that value. If this argument is not - found, it looks for a :attr:`SingleObjectMixin.slug_url_kwarg` - argument, and performs a slug lookup using the - :attr:`SingleObjectMixin.slug_field`. + source of objects; otherwise, :meth:`get_queryset` will be used. + ``get_object()`` looks for a :attr:`pk_url_kwarg` argument in the + arguments to the view; if this argument is found, this method performs + a primary-key based lookup using that value. If this argument is not + found, it looks for a :attr:`slug_url_kwarg` argument, and performs a + slug lookup using the :attr:`slug_field`. .. method:: get_queryset() Returns the queryset that will be used to retrieve the object that - this view will display. By default, - :meth:`~SingleObjectMixin.get_queryset` returns the value of the - :attr:`~SingleObjectMixin.queryset` attribute if it is set, otherwise - it constructs a :class:`QuerySet` by calling the `all()` method on the - :attr:`~SingleObjectMixin.model` attribute's default manager. + this view will display. By default, :meth:`get_queryset` returns the + value of the :attr:`queryset` attribute if it is set, otherwise + it constructs a :class:`~django.db.models.query.QuerySet` by calling + the ``all()`` method on the :attr:`model` attribute's default manager. .. method:: get_context_object_name(obj) Return the context variable name that will be used to contain the - data that this view is manipulating. If - :attr:`~SingleObjectMixin.context_object_name` is not set, the context - name will be constructed from the ``object_name`` of the model that - the queryset is composed from. For example, the model ``Article`` - would have context object named ``'article'``. + data that this view is manipulating. If :attr:`context_object_name` is + not set, the context name will be constructed from the ``object_name`` + of the model that the queryset is composed from. For example, the model + ``Article`` would have context object named ``'article'``. .. method:: get_context_data(**kwargs) Returns context data for displaying the list of objects. + .. method:: get_slug_field() + + Returns the name of a slug field to be used to look up by slug. By + default this simply returns the value of :attr:`slug_field`. + **Context** * ``object``: The object that this view is displaying. If diff --git a/docs/ref/clickjacking.txt b/docs/ref/clickjacking.txt index b70fe9f90d..ce27148ad3 100644 --- a/docs/ref/clickjacking.txt +++ b/docs/ref/clickjacking.txt @@ -10,9 +10,6 @@ against `clickjacking`_. This type of attack occurs when a malicious site tricks a user into clicking on a concealed element of another site which they have loaded in a hidden frame or iframe. -.. versionadded:: 1.4 - The clickjacking middleware and decorators were added. - .. _clickjacking: http://en.wikipedia.org/wiki/Clickjacking An example of clickjacking @@ -33,10 +30,10 @@ Preventing clickjacking Modern browsers honor the `X-Frame-Options`_ HTTP header that indicates whether or not a resource is allowed to load within a frame or iframe. If the response -contains the header with a value of SAMEORIGIN then the browser will only load -the resource in a frame if the request originated from the same site. If the -header is set to DENY then the browser will block the resource from loading in a -frame no matter which site made the request. +contains the header with a value of ``SAMEORIGIN`` then the browser will only +load the resource in a frame if the request originated from the same site. If +the header is set to ``DENY`` then the browser will block the resource from +loading in a frame no matter which site made the request. .. _X-Frame-Options: https://developer.mozilla.org/en/The_X-FRAME-OPTIONS_response_header @@ -54,7 +51,7 @@ How to use it Setting X-Frame-Options for all responses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To set the same X-Frame-Options value for all responses in your site, add +To set the same ``X-Frame-Options`` value for all responses in your site, put ``'django.middleware.clickjacking.XFrameOptionsMiddleware'`` to :setting:`MIDDLEWARE_CLASSES`:: @@ -64,15 +61,19 @@ To set the same X-Frame-Options value for all responses in your site, add ... ) -By default, the middleware will set the X-Frame-Options header to SAMEORIGIN for -every outgoing ``HttpResponse``. If you want DENY instead, set the -:setting:`X_FRAME_OPTIONS` setting:: +.. versionchanged:: 1.6 + This middleware is enabled in the settings file generated by + :djadmin:`startproject`. + +By default, the middleware will set the ``X-Frame-Options`` header to +``SAMEORIGIN`` for every outgoing ``HttpResponse``. If you want ``DENY`` +instead, set the :setting:`X_FRAME_OPTIONS` setting:: X_FRAME_OPTIONS = 'DENY' When using the middleware there may be some views where you do **not** want the -X-Frame-Options header set. For those cases, you can use a view decorator that -tells the middleware not to set the header:: +``X-Frame-Options`` header set. For those cases, you can use a view decorator +that tells the middleware not to set the header:: from django.http import HttpResponse from django.views.decorators.clickjacking import xframe_options_exempt @@ -85,7 +86,7 @@ tells the middleware not to set the header:: Setting X-Frame-Options per view ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To set the X-Frame-Options header on a per view basis, Django provides these +To set the ``X-Frame-Options`` header on a per view basis, Django provides these decorators:: from django.http import HttpResponse @@ -106,23 +107,23 @@ a decorator overrides the middleware. Limitations =========== -The `X-Frame-Options` header will only protect against clickjacking in a modern -browser. Older browsers will quietly ignore the header and need `other +The ``X-Frame-Options`` header will only protect against clickjacking in a +modern browser. Older browsers will quietly ignore the header and need `other clickjacking prevention techniques`_. Browsers that support X-Frame-Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * Internet Explorer 8+ -* Firefox 3.6.9+ -* Opera 10.5+ -* Safari 4+ -* Chrome 4.1+ +* Firefox 3.6.9+ +* Opera 10.5+ +* Safari 4+ +* Chrome 4.1+ See also ~~~~~~~~ -A `complete list`_ of browsers supporting X-Frame-Options. +A `complete list`_ of browsers supporting ``X-Frame-Options``. .. _complete list: https://developer.mozilla.org/en/The_X-FRAME-OPTIONS_response_header#Browser_compatibility .. _other clickjacking prevention techniques: http://en.wikipedia.org/wiki/Clickjacking#Prevention diff --git a/docs/ref/contrib/admin/actions.txt b/docs/ref/contrib/admin/actions.txt index d7eef623d5..c79f978850 100644 --- a/docs/ref/contrib/admin/actions.txt +++ b/docs/ref/contrib/admin/actions.txt @@ -175,7 +175,7 @@ That's easy enough to do:: make_published.short_description = "Mark selected stories as published" Notice first that we've moved ``make_published`` into a method and renamed the -`modeladmin` parameter to `self`, and second that we've now put the string +``modeladmin`` parameter to ``self``, and second that we've now put the string ``'make_published'`` in ``actions`` instead of a direct function reference. This tells the :class:`ModelAdmin` to look up the action as a method. @@ -223,7 +223,7 @@ objects as JSON:: from django.core import serializers def export_as_json(modeladmin, request, queryset): - response = HttpResponse(mimetype="text/javascript") + response = HttpResponse(content_type="application/json") serializers.serialize("json", queryset, stream=response) return response @@ -356,5 +356,3 @@ Conditionally enabling or disabling actions if 'delete_selected' in actions: del actions['delete_selected'] return actions - - diff --git a/docs/ref/contrib/admin/admindocs.txt b/docs/ref/contrib/admin/admindocs.txt index 4a50856f3d..b3e26eca48 100644 --- a/docs/ref/contrib/admin/admindocs.txt +++ b/docs/ref/contrib/admin/admindocs.txt @@ -24,7 +24,7 @@ the following: * Add :mod:`django.contrib.admindocs` to your :setting:`INSTALLED_APPS`. * Add ``(r'^admin/doc/', include('django.contrib.admindocs.urls'))`` to - your :data:`urlpatterns`. Make sure it's included *before* the + your ``urlpatterns``. Make sure it's included *before* the ``r'^admin/'`` entry, so that requests to ``/admin/doc/`` don't get handled by the latter entry. * Install the docutils Python module (http://docutils.sf.net/). diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 6f79e97a3c..c567bc1db4 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -14,7 +14,13 @@ Django's admin interface. Overview ======== -There are seven steps in activating the Django admin site: +The admin is enabled in the default project template used by +:djadmin:`startproject`. + +.. versionchanged:: 1.6 + In previous versions, the admin wasn't enabled by default. + +For reference, here are the requirements: 1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS` setting. @@ -136,6 +142,13 @@ subclass:: e.g. if all the dates are in one month, it'll show the day-level drill-down only. + .. note:: + + ``date_hierarchy`` uses :meth:`QuerySet.datetimes() + <django.db.models.query.QuerySet.datetimes>` internally. Please refer + to its documentation for some caveats when time zone support is + enabled (:setting:`USE_TZ = True <USE_TZ>`). + .. attribute:: ModelAdmin.exclude This attribute, if given, should be a list of field names to exclude from @@ -170,7 +183,7 @@ subclass:: ``fields`` option (for more complex layout needs see the :attr:`~ModelAdmin.fieldsets` option described in the next section). For example, you could define a simpler version of the admin form for the - ``django.contrib.flatpages.FlatPage`` model as follows:: + :class:`django.contrib.flatpages.models.FlatPage` model as follows:: class FlatPageAdmin(admin.ModelAdmin): fields = ('url', 'title', 'content') @@ -180,7 +193,10 @@ subclass:: values defined in :attr:`ModelAdmin.readonly_fields` to be displayed as read-only. - .. versionadded:: 1.4 + The ``fields`` option, unlike :attr:`~ModelAdmin.list_display`, may only + contain names of fields on the model or the form specified by + :attr:`~ModelAdmin.form`. It may contain callables only if they are listed + in :attr:`~ModelAdmin.readonly_fields`. To display multiple fields on the same line, wrap those fields in their own tuple. In this example, the ``url`` and ``title`` fields will display on the @@ -214,8 +230,8 @@ subclass:: a dictionary of information about the fieldset, including a list of fields to be displayed in it. - A full example, taken from the :class:`django.contrib.flatpages.FlatPage` - model:: + A full example, taken from the + :class:`django.contrib.flatpages.models.FlatPage` model:: class FlatPageAdmin(admin.ModelAdmin): fieldsets = ( @@ -249,10 +265,10 @@ subclass:: 'fields': ('first_name', 'last_name', 'address', 'city', 'state'), } - Just like with the :attr:`~ModelAdmin.fields` option, to display - multiple fields on the same line, wrap those fields in their own - tuple. In this example, the ``first_name`` and ``last_name`` fields - will display on the same line:: + As with the :attr:`~ModelAdmin.fields` option, to display multiple + fields on the same line, wrap those fields in their own tuple. In this + example, the ``first_name`` and ``last_name`` fields will display on + the same line:: { 'fields': (('first_name', 'last_name'), 'address', 'city', 'state'), @@ -261,13 +277,17 @@ subclass:: ``fields`` can contain values defined in :attr:`~ModelAdmin.readonly_fields` to be displayed as read-only. + If you add the name of a callable to ``fields``, the same rule applies + as with the :attr:`~ModelAdmin.fields` option: the callable must be + listed in :attr:`~ModelAdmin.readonly_fields`. + * ``classes`` A list containing extra CSS classes to apply to the fieldset. Example:: { - 'classes': ['wide', 'extrapretty'], + 'classes': ('wide', 'extrapretty'), } Two useful classes defined by the default admin site stylesheet are @@ -359,7 +379,7 @@ subclass:: Note that the key in the dictionary is the actual field class, *not* a string. The value is another dictionary; these arguments will be passed to - :meth:`~django.forms.Field.__init__`. See :doc:`/ref/forms/api` for + the form field's ``__init__()`` method. See :doc:`/ref/forms/api` for details. .. warning:: @@ -451,17 +471,25 @@ subclass:: * If the string given is a method of the model, ``ModelAdmin`` or a callable, Django will HTML-escape the output by default. If you'd rather not escape the output of the method, give the method an - ``allow_tags`` attribute whose value is ``True``. + ``allow_tags`` attribute whose value is ``True``. However, to avoid an + XSS vulnerability, you should use :func:`~django.utils.html.format_html` + to escape user-provided inputs. Here's a full example model:: + from django.utils.html import format_html + class Person(models.Model): first_name = models.CharField(max_length=50) last_name = models.CharField(max_length=50) color_code = models.CharField(max_length=6) def colored_name(self): - return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name) + return format_html('<span style="color: #{0};">{1} {2}</span>', + self.color_code, + self.first_name, + self.last_name) + colored_name.allow_tags = True class PersonAdmin(admin.ModelAdmin): @@ -502,12 +530,17 @@ subclass:: For example:: + from django.utils.html import format_html + class Person(models.Model): first_name = models.CharField(max_length=50) color_code = models.CharField(max_length=6) def colored_first_name(self): - return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name) + return format_html('<span style="color: #{0};">{1}</span>', + self.color_code, + self.first_name) + colored_first_name.allow_tags = True colored_first_name.admin_order_field = 'first_name' @@ -517,6 +550,13 @@ subclass:: The above will tell Django to order by the ``first_name`` field when trying to sort by ``colored_first_name`` in the admin. + * .. versionadded:: 1.6 + + The field names in ``list_display`` will also appear as CSS classes in + the HTML output, in the form of ``column-<field_name>`` on each ``<th>`` + element. This can be used to set column widths in a CSS file for example. + + .. attribute:: ModelAdmin.list_display_links Set ``list_display_links`` to control which fields in ``list_display`` @@ -586,9 +626,7 @@ subclass:: class PersonAdmin(UserAdmin): list_filter = ('company__name',) - .. versionadded:: 1.4 - - * a class inheriting from :mod:`django.contrib.admin.SimpleListFilter`, + * a class inheriting from ``django.contrib.admin.SimpleListFilter``, which you need to provide the ``title`` and ``parameter_name`` attributes to and override the ``lookups`` and ``queryset`` methods, e.g.:: @@ -665,7 +703,7 @@ subclass:: Only show the lookups if there actually is anyone born in the corresponding decades. """ - qs = model_admin.queryset(request) + qs = model_admin.get_queryset(request) if qs.filter(birthday__gte=date(1980, 1, 1), birthday__lte=date(1989, 12, 31)).exists(): yield ('80s', _('in the eighties')) @@ -673,11 +711,9 @@ subclass:: birthday__lte=date(1999, 12, 31)).exists(): yield ('90s', _('in the nineties')) - .. versionadded:: 1.4 - * a tuple, where the first element is a field name and the second element is a class inheriting from - :mod:`django.contrib.admin.FieldListFilter`, for example:: + ``django.contrib.admin.FieldListFilter``, for example:: from django.contrib.admin import BooleanFieldListFilter @@ -691,8 +727,6 @@ subclass:: The ``FieldListFilter`` API is considered internal and might be changed. - .. versionadded:: 1.4 - It is possible to specify a custom template for rendering a list filter:: class FilterWithCustomTemplate(SimpleListFilter): @@ -703,8 +737,6 @@ subclass:: .. attribute:: ModelAdmin.list_max_show_all - .. versionadded:: 1.4 - Set ``list_max_show_all`` to control how many items can appear on a "Show all" admin change list page. The admin will display a "Show all" link on the change list only if the total result count is less than or equal to this @@ -738,15 +770,9 @@ subclass:: If this isn't provided, the Django admin will use the model's default ordering. - .. versionadded:: 1.4 - If you need to specify a dynamic order (for example depending on user or language) you can implement a :meth:`~ModelAdmin.get_ordering` method. - .. versionchanged:: 1.4 - - Django honors all elements in the list/tuple; before 1.4, only the first - was respected. .. attribute:: ModelAdmin.paginator @@ -827,25 +853,33 @@ subclass:: added last after all editable fields. A read-only field can not only display data from a model's field, it can - also display the output of a a model's method or a method of the + also display the output of a model's method or a method of the ``ModelAdmin`` class itself. This is very similar to the way :attr:`ModelAdmin.list_display` behaves. This provides an easy way to use the admin interface to provide feedback on the status of the objects being edited, for example:: + from django.utils.html import format_html_join + from django.utils.safestring import mark_safe + class PersonAdmin(ModelAdmin): readonly_fields = ('address_report',) def address_report(self, instance): - return ", ".join(instance.get_full_address()) or \ - "<span class='errors'>I can't determine this address.</span>" + # assuming get_full_address() returns a list of strings + # for each line of the address and you want to separate each + # line by a linebreak + return format_html_join( + mark_safe('<br/>'), + '{0}', + ((line,) for line in instance.get_full_address()), + ) or "<span class='errors'>I can't determine this address.</span>" # short_description functions like a model field's verbose_name address_report.short_description = "Address" # in this example, we have used HTML tags in the output address_report.allow_tags = True - .. attribute:: ModelAdmin.save_as Set ``save_as`` to enable a "save as" feature on admin change forms. @@ -959,10 +993,9 @@ templates used by the :class:`ModelAdmin` views: .. attribute:: ModelAdmin.delete_selected_confirmation_template - Path to a custom template, used by the :meth:`delete_selected` - action method for displaying a confirmation page when deleting one - or more objects. See the :doc:`actions - documentation</ref/contrib/admin/actions>`. + Path to a custom template, used by the ``delete_selected`` action method + for displaying a confirmation page when deleting one or more objects. See + the :doc:`actions documentation</ref/contrib/admin/actions>`. .. attribute:: ModelAdmin.object_history_template @@ -1017,8 +1050,6 @@ templates used by the :class:`ModelAdmin` views: .. method:: ModelAdmin.get_ordering(self, request) - .. versionadded:: 1.4 - The ``get_ordering`` method takes a``request`` as parameter and is expected to return a ``list`` or ``tuple`` for ordering similar to the :attr:`ordering` attribute. For example:: @@ -1033,8 +1064,6 @@ templates used by the :class:`ModelAdmin` views: .. method:: ModelAdmin.save_related(self, request, form, formsets, change) - .. versionadded:: 1.4 - The ``save_related`` method is given the ``HttpRequest``, the parent ``ModelForm`` instance, the list of inline formsets and a boolean value based on whether the parent is being added or changed. Here you can do any @@ -1050,8 +1079,6 @@ templates used by the :class:`ModelAdmin` views: .. method:: ModelAdmin.get_prepopulated_fields(self, request, obj=None) - .. versionadded:: 1.4 - The ``get_prepopulated_fields`` method is given the ``HttpRequest`` and the ``obj`` being edited (or ``None`` on an add form) and is expected to return a ``dictionary``, as described above in the :attr:`ModelAdmin.prepopulated_fields` @@ -1059,8 +1086,6 @@ templates used by the :class:`ModelAdmin` views: .. method:: ModelAdmin.get_list_display(self, request) - .. versionadded:: 1.4 - The ``get_list_display`` method is given the ``HttpRequest`` and is expected to return a ``list`` or ``tuple`` of field names that will be displayed on the changelist view as described above in the @@ -1068,14 +1093,19 @@ templates used by the :class:`ModelAdmin` views: .. method:: ModelAdmin.get_list_display_links(self, request, list_display) - .. versionadded:: 1.4 - The ``get_list_display_links`` method is given the ``HttpRequest`` and the ``list`` or ``tuple`` returned by :meth:`ModelAdmin.get_list_display`. It is expected to return a ``list`` or ``tuple`` of field names on the changelist that will be linked to the change view, as described in the :attr:`ModelAdmin.list_display_links` section. +.. method:: ModelAdmin.get_fieldsets(self, request, obj=None) + + The ``get_fieldsets`` method is given the ``HttpRequest`` and the ``obj`` + being edited (or ``None`` on an add form) and is expected to return a list + of two-tuples, in which each two-tuple represents a ``<fieldset>`` on the + admin form page, as described above in the :attr:`ModelAdmin.fieldsets` section. + .. method:: ModelAdmin.get_list_filter(self, request) .. versionadded:: 1.5 @@ -1134,9 +1164,8 @@ templates used by the :class:`ModelAdmin` views: Since this is usually not what you want, Django provides a convenience wrapper to check permissions and mark the view as non-cacheable. This - wrapper is :meth:`AdminSite.admin_view` (i.e. - ``self.admin_site.admin_view`` inside a ``ModelAdmin`` instance); use it - like so:: + wrapper is ``AdminSite.admin_view()`` (i.e. ``self.admin_site.admin_view`` + inside a ``ModelAdmin`` instance); use it like so:: class MyModelAdmin(admin.ModelAdmin): def get_urls(self): @@ -1156,7 +1185,7 @@ templates used by the :class:`ModelAdmin` views: If the page is cacheable, but you still want the permission check to be performed, you can pass a ``cacheable=True`` argument to - :meth:`AdminSite.admin_view`:: + ``AdminSite.admin_view()``:: (r'^my_view/$', self.admin_site.admin_view(self.my_view, cacheable=True)) @@ -1297,20 +1326,23 @@ templates used by the :class:`ModelAdmin` views: be interpreted as meaning that the current user is not permitted to delete any object of this type). -.. method:: ModelAdmin.queryset(self, request) +.. method:: ModelAdmin.get_queryset(self, request) - The ``queryset`` method on a ``ModelAdmin`` returns a + The ``get_queryset`` method on a ``ModelAdmin`` returns a :class:`~django.db.models.query.QuerySet` of all model instances that can be edited by the admin site. One use case for overriding this method is to show objects owned by the logged-in user:: class MyModelAdmin(admin.ModelAdmin): - def queryset(self, request): - qs = super(MyModelAdmin, self).queryset(request) + def get_queryset(self, request): + qs = super(MyModelAdmin, self).get_queryset(request) if request.user.is_superuser: return qs return qs.filter(author=request.user) + .. versionchanged:: 1.6 + The ``get_queryset`` method was previously named ``queryset``. + .. method:: ModelAdmin.message_user(request, message, level=messages.INFO, extra_tags='', fail_silently=False) Sends a message to the user using the :mod:`django.contrib.messages` @@ -1341,10 +1373,6 @@ Other methods Django view for the model instance edition page. See note below. - .. versionchanged:: 1.4 - - The ``form_url`` parameter was added. - .. method:: ModelAdmin.changelist_view(self, request, extra_context=None) Django view for the model instances change list/actions page. See note @@ -1386,12 +1414,10 @@ provided some extra mapping data that would not otherwise be available:: return super(MyModelAdmin, self).change_view(request, object_id, form_url, extra_context=extra_context) -.. versionadded:: 1.4 - -These views now return :class:`~django.template.response.TemplateResponse` +These views return :class:`~django.template.response.TemplateResponse` instances which allow you to easily customize the response data before -rendering. For more details, see the -:doc:`TemplateResponse documentation </ref/template-response>`. +rendering. For more details, see the :doc:`TemplateResponse documentation +</ref/template-response>`. .. _modeladmin-media-definitions: @@ -1414,15 +1440,33 @@ The :doc:`staticfiles app </ref/contrib/staticfiles>` prepends ``None``) to any media paths. The same rules apply as :ref:`regular media definitions on forms <form-media-paths>`. -Django admin Javascript makes use of the `jQuery`_ library. To avoid -conflicts with user-supplied scripts or libraries, Django's jQuery is -namespaced as ``django.jQuery``. If you want to use jQuery in your own admin -JavaScript without including a second copy, you can use the ``django.jQuery`` -object on changelist and add/edit views. +jQuery +~~~~~~ + +Django admin Javascript makes use of the `jQuery`_ library. + +To avoid conflicts with user-supplied scripts or libraries, Django's jQuery +(version 1.9.1) is namespaced as ``django.jQuery``. If you want to use jQuery +in your own admin JavaScript without including a second copy, you can use the +``django.jQuery`` object on changelist and add/edit views. + +.. versionchanged:: 1.6 + The embedded jQuery has been upgraded from 1.4.2 to 1.9.1. + +The :class:`ModelAdmin` class requires jQuery by default, so there is no need +to add jQuery to your ``ModelAdmin``'s list of media resources unless you have +a specifc need. For example, if you require the jQuery library to be in the +global namespace (for example when using third-party jQuery plugins) or if you +need a newer version of jQuery, you will have to include your own copy. -If you require the jQuery library to be in the global namespace, for example -when using third-party jQuery plugins, or need a newer version of jQuery, you -will have to include your own copy of jQuery. +Django provides both uncompressed and 'minified' versions of jQuery, as +``jquery.js`` and ``jquery.min.js`` respectively. + +:class:`ModelAdmin` and :class:`InlineModelAdmin` have a ``media`` property +that returns a list of ``Media`` objects which store paths to the JavaScript +files for the forms and/or formsets. If :setting:`DEBUG` is ``True`` it will +return the uncompressed versions of the various JavaScript files, including +``jquery.js``; if not, it will return the 'minified' versions. .. _jQuery: http://jquery.com @@ -1508,15 +1552,12 @@ adds some of its own (the shared features are actually defined in the - :attr:`~ModelAdmin.filter_vertical` - :attr:`~ModelAdmin.ordering` - :attr:`~ModelAdmin.prepopulated_fields` -- :meth:`~ModelAdmin.queryset` +- :meth:`~ModelAdmin.get_queryset` - :attr:`~ModelAdmin.radio_fields` - :attr:`~ModelAdmin.readonly_fields` - :attr:`~InlineModelAdmin.raw_id_fields` - :meth:`~ModelAdmin.formfield_for_foreignkey` - :meth:`~ModelAdmin.formfield_for_manytomany` - -.. versionadded:: 1.4 - - :meth:`~ModelAdmin.has_add_permission` - :meth:`~ModelAdmin.has_change_permission` - :meth:`~ModelAdmin.has_delete_permission` @@ -1542,8 +1583,8 @@ The ``InlineModelAdmin`` class adds: .. attribute:: InlineModelAdmin.form The value for ``form`` defaults to ``ModelForm``. This is what is passed - through to ``inlineformset_factory`` when creating the formset for this - inline. + through to :func:`~django.forms.models.inlineformset_factory` when + creating the formset for this inline. .. attribute:: InlineModelAdmin.extra @@ -1825,31 +1866,32 @@ Because of the modular design of the admin templates, it is usually neither necessary nor advisable to replace an entire template. It is almost always better to override only the section of the template which you need to change. -To continue the example above, we want to add a new link next to the ``History`` -tool for the ``Page`` model. After looking at ``change_form.html`` we determine -that we only need to override the ``object-tools`` block. Therefore here is our -new ``change_form.html`` : +To continue the example above, we want to add a new link next to the +``History`` tool for the ``Page`` model. After looking at ``change_form.html`` +we determine that we only need to override the ``object-tools-items`` block. +Therefore here is our new ``change_form.html`` : .. code-block:: html+django {% extends "admin/change_form.html" %} - {% load i18n %} - {% block object-tools %} - {% if change %}{% if not is_popup %} - <ul class="object-tools"> - <li><a href="history/" class="historylink">{% trans "History" %}</a></li> - <li><a href="mylink/" class="historylink">My Link</a></li> + {% load i18n admin_urls %} + {% block object-tools-items %} + <li> + <a href="{% url opts|admin_urlname:'history' original.pk|admin_urlquote %}" class="historylink">{% trans "History" %}</a> + </li> + <li> + <a href="mylink/" class="historylink">My Link</a> + </li> {% if has_absolute_url %} - <li><a href="../../../r/{{ content_type_id }}/{{ object_id }}/" class="viewsitelink"> - {% trans "View on site" %}</a> + <li> + <a href="{% url 'admin:view_on_site' content_type_id original.pk %}" class="viewsitelink">{% trans "View on site" %}</a> </li> {% endif%} - </ul> - {% endif %}{% endif %} {% endblock %} And that's it! If we placed this file in the ``templates/admin/my_app`` -directory, our link would appear on every model's change form. +directory, our link would appear on the change form for all models within +my_app. Templates which may be overridden per app or model -------------------------------------------------- @@ -1870,7 +1912,7 @@ and 500 pages. .. note:: - Some of the admin templates, such as ``change_list_request.html`` are used + Some of the admin templates, such as ``change_list_results.html`` are used to render custom inclusion tags. These may be overridden, but in such cases you are probably better off creating your own version of the tag in question and giving it a different name. That way you can use it @@ -1952,7 +1994,7 @@ In this example, we register the default ``AdminSite`` instance ``django.contrib.admin.site`` at the URL ``/admin/`` :: # urls.py - from django.conf.urls import patterns, url, include + from django.conf.urls import patterns, include from django.contrib import admin admin.autodiscover() @@ -1968,7 +2010,7 @@ In this example, we register the ``AdminSite`` instance ``myproject.admin.admin_site`` at the URL ``/myadmin/`` :: # urls.py - from django.conf.urls import patterns, url, include + from django.conf.urls import patterns, include from myproject.admin import admin_site urlpatterns = patterns('', @@ -1992,7 +2034,7 @@ separate versions of the admin site -- using the ``AdminSite`` instances respectively:: # urls.py - from django.conf.urls import patterns, url, include + from django.conf.urls import patterns, include from myproject.admin import basic_site, advanced_site urlpatterns = patterns('', @@ -2043,8 +2085,6 @@ your URLconf. Specifically, add these four patterns: the URLs starting with ``^admin/`` before the line that includes the admin app itself). -.. versionchanged:: 1.4 - The presence of the ``admin_password_reset`` named URL will cause a "forgotten your password?" link to appear on the default admin log-in page under the password box. @@ -2108,8 +2148,6 @@ if you specifically wanted the admin view from the admin instance named For more details, see the documentation on :ref:`reversing namespaced URLs <topics-http-reversing-url-namespaces>`. -.. versionadded:: 1.4 - To allow easier reversing of the admin urls in templates, Django provides an ``admin_urlname`` filter which takes an action as argument: @@ -2121,5 +2159,5 @@ To allow easier reversing of the admin urls in templates, Django provides an The action in the examples above match the last part of the URL names for :class:`ModelAdmin` instances described above. The ``opts`` variable can be any -object which has an ``app_label`` and ``module_name`` and is usually supplied -by the admin views for the current model. +object which has an ``app_label`` and ``model_name`` attributes and is usually +supplied by the admin views for the current model. diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt index 619b38e5ac..40b3629f63 100644 --- a/docs/ref/contrib/auth.txt +++ b/docs/ref/contrib/auth.txt @@ -1,4 +1,435 @@ ``django.contrib.auth`` ======================= -See :doc:`/topics/auth`. +This document provides API reference material for the components of Django's +authentication system. For more details on the usage of these components or +how to customize authentication and authorization see the :doc:`authentication +topic guide </topics/auth/index>`. + +.. currentmodule:: django.contrib.auth + +User +==== + +Fields +------ + +.. class:: models.User + + :class:`~django.contrib.auth.models.User` objects have the following + fields: + + .. attribute:: username + + Required. 30 characters or fewer. Usernames may contain alphanumeric, + ``_``, ``@``, ``+``, ``.`` and ``-`` characters. + + .. attribute:: first_name + + Optional. 30 characters or fewer. + + .. attribute:: last_name + + Optional. 30 characters or fewer. + + .. attribute:: email + + Optional. Email address. + + .. attribute:: password + + Required. A hash of, and metadata about, the password. (Django doesn't + store the raw password.) Raw passwords can be arbitrarily long and can + contain any character. See the :doc:`password documentation + </topics/auth/passwords>`. + + .. attribute:: groups + + Many-to-many relationship to :class:`~django.contrib.auth.models.Group` + + .. attribute:: user_permissions + + Many-to-many relationship to :class:`~django.contrib.auth.models.Permission` + + .. attribute:: is_staff + + Boolean. Designates whether this user can access the admin site. + + .. attribute:: is_active + + Boolean. Designates whether this user account should be considered + active. We recommend that you set this flag to ``False`` instead of + deleting accounts; that way, if your applications have any foreign keys + to users, the foreign keys won't break. + + This doesn't necessarily control whether or not the user can log in. + Authentication backends aren't required to check for the ``is_active`` + flag, and the default backends do not. If you want to reject a login + based on ``is_active`` being ``False``, it's up to you to check that in + your own login view or a custom authentication backend. However, the + :class:`~django.contrib.auth.forms.AuthenticationForm` used by the + :func:`~django.contrib.auth.views.login` view (which is the default) + *does* perform this check, as do the permission-checking methods such + as :meth:`~django.contrib.auth.models.User.has_perm` and the + authentication in the Django admin. All of those functions/methods will + return ``False`` for inactive users. + + .. attribute:: is_superuser + + Boolean. Designates that this user has all permissions without + explicitly assigning them. + + .. attribute:: last_login + + A datetime of the user's last login. Is set to the current date/time by + default. + + .. attribute:: date_joined + + A datetime designating when the account was created. Is set to the + current date/time by default when the account is created. + +Methods +------- + +.. class:: models.User + + .. method:: get_username() + + Returns the username for the user. Since the User model can be swapped + out, you should use this method instead of referencing the username + attribute directly. + + .. method:: is_anonymous() + + Always returns ``False``. This is a way of differentiating + :class:`~django.contrib.auth.models.User` and + :class:`~django.contrib.auth.models.AnonymousUser` objects. + Generally, you should prefer using + :meth:`~django.contrib.auth.models.User.is_authenticated()` to this + method. + + .. method:: is_authenticated() + + Always returns ``True`` (as opposed to + ``AnonymousUser.is_authenticated()`` which always returns ``False``). + This is a way to tell if the user has been authenticated. This does not + imply any permissions, and doesn't check if the user is active - it + only indicates that ``request.user`` has been populated by the + :class:`~django.contrib.auth.middleware.AuthenticationMiddleware` with + a :class:`~django.contrib.auth.models.User` object representing the + currently logged-in user. + + .. method:: get_full_name() + + Returns the :attr:`~django.contrib.auth.models.User.first_name` plus + the :attr:`~django.contrib.auth.models.User.last_name`, with a space in + between. + + .. method:: set_password(raw_password) + + Sets the user's password to the given raw string, taking care of the + password hashing. Doesn't save the + :class:`~django.contrib.auth.models.User` object. + + .. method:: check_password(raw_password) + + Returns ``True`` if the given raw string is the correct password for + the user. (This takes care of the password hashing in making the + comparison.) + + .. method:: set_unusable_password() + + Marks the user as having no password set. This isn't the same as + having a blank string for a password. + :meth:`~django.contrib.auth.models.User.check_password()` for this user + will never return ``True``. Doesn't save the + :class:`~django.contrib.auth.models.User` object. + + You may need this if authentication for your application takes place + against an existing external source such as an LDAP directory. + + .. method:: has_usable_password() + + Returns ``False`` if + :meth:`~django.contrib.auth.models.User.set_unusable_password()` has + been called for this user. + + .. method:: get_group_permissions(obj=None) + + Returns a set of permission strings that the user has, through his/her + groups. + + If ``obj`` is passed in, only returns the group permissions for + this specific object. + + .. method:: get_all_permissions(obj=None) + + Returns a set of permission strings that the user has, both through + group and user permissions. + + If ``obj`` is passed in, only returns the permissions for this + specific object. + + .. method:: has_perm(perm, obj=None) + + Returns ``True`` if the user has the specified permission, where perm + is in the format ``"<app label>.<permission codename>"``. (see + documentation on :ref:`permissions <topic-authorization>`). If the user is + inactive, this method will always return ``False``. + + If ``obj`` is passed in, this method won't check for a permission for + the model, but for this specific object. + + .. method:: has_perms(perm_list, obj=None) + + Returns ``True`` if the user has each of the specified permissions, + where each perm is in the format + ``"<app label>.<permission codename>"``. If the user is inactive, + this method will always return ``False``. + + If ``obj`` is passed in, this method won't check for permissions for + the model, but for the specific object. + + .. method:: has_module_perms(package_name) + + Returns ``True`` if the user has any permissions in the given package + (the Django app label). If the user is inactive, this method will + always return ``False``. + + .. method:: email_user(subject, message, from_email=None) + + Sends an email to the user. If ``from_email`` is ``None``, Django uses + the :setting:`DEFAULT_FROM_EMAIL`. + + .. method:: get_profile() + + .. deprecated:: 1.5 + With the introduction of :ref:`custom User models <auth-custom-user>`, + the use of :setting:`AUTH_PROFILE_MODULE` to define a single profile + model is no longer supported. See the + :doc:`Django 1.5 release notes</releases/1.5>` for more information. + + Returns a site-specific profile for this user. Raises + ``django.contrib.auth.models.SiteProfileNotAvailable`` if the + current site doesn't allow profiles, or + :exc:`django.core.exceptions.ObjectDoesNotExist` if the user does not + have a profile. + +Manager methods +--------------- + +.. class:: models.UserManager + + The :class:`~django.contrib.auth.models.User` model has a custom manager + that has the following helper methods (in addition to the methods provided + by :class:`~django.contrib.auth.models.BaseUserManager`): + + .. method:: create_user(username, email=None, password=None, **extra_fields) + + Creates, saves and returns a :class:`~django.contrib.auth.models.User`. + + The :attr:`~django.contrib.auth.models.User.username` and + :attr:`~django.contrib.auth.models.User.password` are set as given. The + domain portion of :attr:`~django.contrib.auth.models.User.email` is + automatically converted to lowercase, and the returned + :class:`~django.contrib.auth.models.User` object will have + :attr:`~django.contrib.auth.models.User.is_active` set to ``True``. + + If no password is provided, + :meth:`~django.contrib.auth.models.User.set_unusable_password()` will + be called. + + The ``extra_fields`` keyword arguments are passed through to the + :class:`~django.contrib.auth.models.User`'s ``__init__`` method to + allow setting arbitrary fields on a :ref:`custom User model + <auth-custom-user>`. + + See :ref:`Creating users <topics-auth-creating-users>` for example usage. + + .. method:: create_superuser(self, username, email, password, **extra_fields) + + Same as :meth:`create_user`, but sets :attr:`~models.User.is_staff` and + :attr:`~models.User.is_superuser` to ``True``. + + +Anonymous users +=============== + +.. class:: models.AnonymousUser + + :class:`django.contrib.auth.models.AnonymousUser` is a class that + implements the :class:`django.contrib.auth.models.User` interface, with + these differences: + + * :ref:`id <automatic-primary-key-fields>` is always ``None``. + * :attr:`~django.contrib.auth.models.User.is_staff` and + :attr:`~django.contrib.auth.models.User.is_superuser` are always + ``False``. + * :attr:`~django.contrib.auth.models.User.is_active` is always ``False``. + * :attr:`~django.contrib.auth.models.User.groups` and + :attr:`~django.contrib.auth.models.User.user_permissions` are always + empty. + * :meth:`~django.contrib.auth.models.User.is_anonymous()` returns ``True`` + instead of ``False``. + * :meth:`~django.contrib.auth.models.User.is_authenticated()` returns + ``False`` instead of ``True``. + * :meth:`~django.contrib.auth.models.User.set_password()`, + :meth:`~django.contrib.auth.models.User.check_password()`, + :meth:`~django.db.models.Model.save` and + :meth:`~django.db.models.Model.delete()` raise + :exc:`~exceptions.NotImplementedError`. + +In practice, you probably won't need to use +:class:`~django.contrib.auth.models.AnonymousUser` objects on your own, but +they're used by Web requests, as explained in the next section. + +Permission +========== + +.. class:: models.Permission + +Fields +------ + +:class:`~django.contrib.auth.models.Permission` objects have the following +fields: + +.. attribute:: name + + Required. 50 characters or fewer. Example: ``'Can vote'``. + +.. attribute:: content_type + + Required. A reference to the ``django_content_type`` database table, which + contains a record for each installed Django model. + +.. attribute:: codename + + Required. 100 characters or fewer. Example: ``'can_vote'``. + +Methods +------- + +:class:`~django.contrib.auth.models.Permission` objects have the standard +data-access methods like any other :doc:`Django model </ref/models/instances>`. + +Group +===== + +.. class:: models.Group + +Fields +------ + +:class:`~django.contrib.auth.models.Group` objects have the following fields: + +.. attribute:: name + + Required. 80 characters or fewer. Any characters are permitted. Example: + ``'Awesome Users'``. + +.. attribute:: permissions + + Many-to-many field to :class:`~django.contrib.auth.models.Permission`:: + + group.permissions = [permission_list] + group.permissions.add(permission, permission, ...) + group.permissions.remove(permission, permission, ...) + group.permissions.clear() + +.. _topics-auth-signals: + +Login and logout signals +======================== + +.. module:: django.contrib.auth.signals + +The auth framework uses the following :doc:`signals </topics/signals>` that +can be used for notification when a user logs in or out. + +.. function:: user_logged_in + + Sent when a user logs in successfully. + + Arguments sent with this signal: + + ``sender`` + The class of the user that just logged in. + + ``request`` + The current :class:`~django.http.HttpRequest` instance. + + ``user`` + The user instance that just logged in. + +.. function:: user_logged_out + + Sent when the logout method is called. + + ``sender`` + As above: the class of the user that just logged out or ``None`` + if the user was not authenticated. + + ``request`` + The current :class:`~django.http.HttpRequest` instance. + + ``user`` + The user instance that just logged out or ``None`` if the + user was not authenticated. + +.. function:: user_login_failed + + .. versionadded:: 1.5 + + Sent when the user failed to login successfully + + ``sender`` + The name of the module used for authentication. + + ``credentials`` + A dictionary of keyword arguments containing the user credentials that were + passed to :func:`~django.contrib.auth.authenticate()` or your own custom + authentication backend. Credentials matching a set of 'sensitive' patterns, + (including password) will not be sent in the clear as part of the signal. + +.. _authentication-backends-reference: + +Authentication backends +======================= + +.. module:: django.contrib.auth.backends + :synopsis: Django's built-in authentication backend classes. + +This section details the authentication backends that come with Django. For +information on how to use them and how to write your own authentication +backends, see the :ref:`Other authentication sources section +<authentication-backends>` of the :doc:`User authentication guide +</topics/auth/index>`. + + +Available authentication backends +--------------------------------- + +The following backends are available in :mod:`django.contrib.auth.backends`: + +.. class:: ModelBackend + + This is the default authentication backend used by Django. It + authenticates using credentials consisting of a user identifier and + password. For Django's default user model, the user identifier is the + username, for custom user models it is the field specified by + USERNAME_FIELD (see :doc:`Customizing Users and authentication + </topics/auth/customizing>`). + + It also handles the default permissions model as defined for + :class:`~django.contrib.auth.models.User` and + :class:`~django.contrib.auth.models.PermissionsMixin`. + +.. class:: RemoteUserBackend + + Use this backend to take advantage of external-to-Django-handled + authentication. It authenticates using usernames passed in + :attr:`request.META['REMOTE_USER'] <django.http.HttpRequest.META>`. See + the :doc:`Authenticating against REMOTE_USER </howto/auth-remote-user>` + documentation. diff --git a/docs/ref/contrib/comments/custom.txt b/docs/ref/contrib/comments/custom.txt index 0ef37a9a0b..fd70a6a224 100644 --- a/docs/ref/contrib/comments/custom.txt +++ b/docs/ref/contrib/comments/custom.txt @@ -4,6 +4,18 @@ Customizing the comments framework .. currentmodule:: django.contrib.comments +.. warning:: + + Django's comment framework has been deprecated and is no longer supported. + Most users will be better served with a custom solution, or a hosted + product like Disqus__. + + The code formerly known as ``django.contrib.comments`` is `still available + in an external repository`__. + + __ https://disqus.com/ + __ https://github.com/django/django-contrib-comments + If the built-in comment framework doesn't quite fit your needs, you can extend the comment app's behavior to add custom data and logic. The comments framework lets you extend the built-in comment model, the built-in comment form, and the @@ -66,15 +78,17 @@ In the ``models.py`` we'll define a ``CommentWithTitle`` model:: class CommentWithTitle(Comment): title = models.CharField(max_length=300) -Most custom comment models will subclass the :class:`Comment` model. However, +Most custom comment models will subclass the +:class:`~django.contrib.comments.models.Comment` model. However, if you want to substantially remove or change the fields available in the -:class:`Comment` model, but don't want to rewrite the templates, you could -try subclassing from :class:`BaseCommentAbstractModel`. +:class:`~django.contrib.comments.models.Comment` model, but don't want to +rewrite the templates, you could try subclassing from +``BaseCommentAbstractModel``. Next, we'll define a custom comment form in ``forms.py``. This is a little more tricky: we have to both create a form and override -:meth:`CommentForm.get_comment_model` and -:meth:`CommentForm.get_comment_create_data` to return deal with our custom title +``CommentForm.get_comment_model()`` and +``CommentForm.get_comment_create_data()`` to return deal with our custom title field:: from django import forms @@ -139,7 +153,7 @@ however. Return the :class:`~django.db.models.Model` class to use for comments. This model should inherit from - :class:`django.contrib.comments.models.BaseCommentAbstractModel`, which + ``django.contrib.comments.models.BaseCommentAbstractModel``, which defines necessary core fields. The default implementation returns @@ -170,33 +184,33 @@ however. attribute when rendering your comment form. The default implementation returns a reverse-resolved URL pointing - to the :func:`post_comment` view. + to the ``post_comment()`` view. .. note:: If you provide a custom comment model and/or form, but you - want to use the default :func:`post_comment` view, you will + want to use the default ``post_comment()`` view, you will need to be aware that it requires the model and form to have certain additional attributes and methods: see the - :func:`post_comment` view documentation for details. + ``django.contrib.comments.views.post_comment()`` view for details. .. function:: get_flag_url() Return the URL for the "flag this comment" view. The default implementation returns a reverse-resolved URL pointing - to the :func:`django.contrib.comments.views.moderation.flag` view. + to the ``django.contrib.comments.views.moderation.flag()`` view. .. function:: get_delete_url() Return the URL for the "delete this comment" view. The default implementation returns a reverse-resolved URL pointing - to the :func:`django.contrib.comments.views.moderation.delete` view. + to the ``django.contrib.comments.views.moderation.delete()`` view. .. function:: get_approve_url() Return the URL for the "approve this comment from moderation" view. The default implementation returns a reverse-resolved URL pointing - to the :func:`django.contrib.comments.views.moderation.approve` view. + to the ``django.contrib.comments.views.moderation.approve()`` view. diff --git a/docs/ref/contrib/comments/example.txt b/docs/ref/contrib/comments/example.txt index 2bff778c2f..abf79c5f14 100644 --- a/docs/ref/contrib/comments/example.txt +++ b/docs/ref/contrib/comments/example.txt @@ -4,6 +4,18 @@ Example of using the built-in comments app =========================================== +.. warning:: + + Django's comment framework has been deprecated and is no longer supported. + Most users will be better served with a custom solution, or a hosted + product like Disqus__. + + The code formerly known as ``django.contrib.comments`` is `still available + in an external repository`__. + + __ https://disqus.com/ + __ https://github.com/django/django-contrib-comments + Follow the first three steps of the quick start guide in the :doc:`documentation </ref/contrib/comments/index>`. @@ -136,12 +148,12 @@ Feeds ===== Suppose you want to export a :doc:`feed </ref/contrib/syndication>` of the -latest comments, you can use the built-in :class:`LatestCommentFeed`. Just +latest comments, you can use the built-in ``LatestCommentFeed``. Just enable it in your project's ``urls.py``: .. code-block:: python - from django.conf.urls import patterns, url, include + from django.conf.urls import patterns from django.contrib.comments.feeds import LatestCommentFeed urlpatterns = patterns('', @@ -166,7 +178,7 @@ features (all of which or only certain can be enabled): * Close comments after a particular (user-defined) number of days. * Email new comments to the site-staff. -To enable comment moderation, we subclass the :class:`CommentModerator` and +To enable comment moderation, we subclass the ``CommentModerator`` and register it with the moderation features we want. Let's suppose we want to close comments after 7 days of posting and also send out an email to the site staff. In ``blog/models.py``, we register a comment moderator in the diff --git a/docs/ref/contrib/comments/forms.txt b/docs/ref/contrib/comments/forms.txt index c21a27bb9e..f2624ca870 100644 --- a/docs/ref/contrib/comments/forms.txt +++ b/docs/ref/contrib/comments/forms.txt @@ -5,6 +5,18 @@ Comment form classes .. module:: django.contrib.comments.forms :synopsis: Forms for dealing with the built-in comment model. +.. warning:: + + Django's comment framework has been deprecated and is no longer supported. + Most users will be better served with a custom solution, or a hosted + product like Disqus__. + + The code formerly known as ``django.contrib.comments`` is `still available + in an external repository`__. + + __ https://disqus.com/ + __ https://github.com/django/django-contrib-comments + The ``django.contrib.comments.forms`` module contains a handful of forms you'll use when writing custom views dealing with comments, or when writing :doc:`custom comment apps </ref/contrib/comments/custom>`. @@ -43,4 +55,4 @@ forms that you can subclass to reuse pieces of the form handling logic: Handles the details of the comment itself. This class contains the ``name``, ``email``, ``url``, and the ``comment`` - field itself, along with the associated validation logic.
\ No newline at end of file + field itself, along with the associated validation logic. diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt index 8275092d2f..6db69d8168 100644 --- a/docs/ref/contrib/comments/index.txt +++ b/docs/ref/contrib/comments/index.txt @@ -7,6 +7,18 @@ Django's comments framework .. highlightlang:: html+django +.. warning:: + + Django's comment framework has been deprecated and is no longer supported. + Most users will be better served with a custom solution, or a hosted + product like Disqus__. + + The code formerly known as ``django.contrib.comments`` is `still available + in an external repository`__. + + __ https://disqus.com/ + __ https://github.com/django/django-contrib-comments + Django includes a simple, yet customizable comments framework. The built-in comments framework can be used to attach comments to any model, so you can use it for comments on blog entries, photos, book chapters, or anything else. @@ -34,7 +46,8 @@ To get started using the ``comments`` app, follow these steps: #. Use the `comment template tags`_ below to embed comments in your templates. -You might also want to examine :doc:`/ref/contrib/comments/settings`. +You might also want to examine :ref:`the available settings +<settings-comments>`. Comment template tags ===================== @@ -335,6 +348,13 @@ output the CSRF token and cookie. .. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing) + +Configuration +============= + +See :ref:`comment settings <settings-comments>`. + + More information ================ @@ -342,7 +362,6 @@ More information :maxdepth: 1 models - settings signals custom forms diff --git a/docs/ref/contrib/comments/models.txt b/docs/ref/contrib/comments/models.txt index e773790d65..cae9c11971 100644 --- a/docs/ref/contrib/comments/models.txt +++ b/docs/ref/contrib/comments/models.txt @@ -5,18 +5,30 @@ The built-in comment models .. module:: django.contrib.comments.models :synopsis: The built-in comment models +.. warning:: + + Django's comment framework has been deprecated and is no longer supported. + Most users will be better served with a custom solution, or a hosted + product like Disqus__. + + The code formerly known as ``django.contrib.comments`` is `still available + in an external repository`__. + + __ https://disqus.com/ + __ https://github.com/django/django-contrib-comments + .. class:: Comment Django's built-in comment model. Has the following fields: .. attribute:: content_object - A :class:`~django.contrib.contettypes.generic.GenericForeignKey` + A :class:`~django.contrib.contenttypes.generic.GenericForeignKey` attribute pointing to the object the comment is attached to. You can use this to get at the related object (i.e. ``my_comment.content_object``). Since this field is a - :class:`~django.contrib.contettypes.generic.GenericForeignKey`, it's + :class:`~django.contrib.contenttypes.generic.GenericForeignKey`, it's actually syntactic sugar on top of two underlying attributes, described below. @@ -77,4 +89,3 @@ The built-in comment models ``True`` if the comment was removed. Used to keep track of removed comments instead of just deleting them. - diff --git a/docs/ref/contrib/comments/moderation.txt b/docs/ref/contrib/comments/moderation.txt index 39b3ea7913..796e257200 100644 --- a/docs/ref/contrib/comments/moderation.txt +++ b/docs/ref/contrib/comments/moderation.txt @@ -5,6 +5,18 @@ Generic comment moderation .. module:: django.contrib.comments.moderation :synopsis: Support for automatic comment moderation. +.. warning:: + + Django's comment framework has been deprecated and is no longer supported. + Most users will be better served with a custom solution, or a hosted + product like Disqus__. + + The code formerly known as ``django.contrib.comments`` is `still available + in an external repository`__. + + __ https://disqus.com/ + __ https://github.com/django/django-contrib-comments + Django's bundled comments application is extremely useful on its own, but the amount of comment spam circulating on the Web today essentially makes it necessary to have some sort of automatic @@ -81,8 +93,8 @@ Built-in moderation options .. attribute:: auto_close_field If this is set to the name of a - :class:`~django.db.models.fields.DateField` or - :class:`~django.db.models.fields.DateTimeField` on the model for which + :class:`~django.db.models.DateField` or + :class:`~django.db.models.DateTimeField` on the model for which comments are being moderated, new comments for objects of that model will be disallowed (immediately deleted) when a certain number of days have passed after the date specified in that field. Must be @@ -117,7 +129,7 @@ Built-in moderation options .. attribute:: enable_field If this is set to the name of a - :class:`~django.db.models.fields.BooleanField` on the model + :class:`~django.db.models.BooleanField` on the model for which comments are being moderated, new comments on objects of that model will be disallowed (immediately deleted) whenever the value of that field is ``False`` on the object @@ -185,15 +197,14 @@ via two methods: be moderated using the options defined in the ``CommentModerator`` subclass. If any of the models are already registered for moderation, the exception - :exc:`AlreadyModerated` will be raised. + ``AlreadyModerated`` will be raised. .. function:: moderator.unregister(model_or_iterable) Takes one argument: a model class or list of model classes, and removes the model or models from the set of models which are being moderated. If any of the models are not currently - being moderated, the exception - :exc:`NotModerated` will be raised. + being moderated, the exception ``NotModerated`` will be raised. Customizing the moderation system @@ -207,8 +218,8 @@ models with an instance of the subclass. .. class:: Moderator - In addition to the :meth:`Moderator.register` and - :meth:`Moderator.unregister` methods detailed above, the following methods + In addition to the :func:`moderator.register` and + :func:`moderator.unregister` methods detailed above, the following methods on :class:`Moderator` can be overridden to achieve customized behavior: .. method:: connect diff --git a/docs/ref/contrib/comments/settings.txt b/docs/ref/contrib/comments/settings.txt deleted file mode 100644 index 1f1aecafd4..0000000000 --- a/docs/ref/contrib/comments/settings.txt +++ /dev/null @@ -1,33 +0,0 @@ -================ -Comment settings -================ - -These settings configure the behavior of the comments framework: - -.. setting:: COMMENTS_HIDE_REMOVED - -COMMENTS_HIDE_REMOVED ---------------------- - -If ``True`` (default), removed comments will be excluded from comment -lists/counts (as taken from template tags). Otherwise, the template author is -responsible for some sort of a "this comment has been removed by the site staff" -message. - -.. setting:: COMMENT_MAX_LENGTH - -COMMENT_MAX_LENGTH ------------------- - -The maximum length of the comment field, in characters. Comments longer than -this will be rejected. Defaults to 3000. - -.. setting:: COMMENTS_APP - -COMMENTS_APP ------------- - -An app which provides :doc:`customization of the comments framework -</ref/contrib/comments/custom>`. Use the same dotted-string notation -as in :setting:`INSTALLED_APPS`. Your custom :setting:`COMMENTS_APP` -must also be listed in :setting:`INSTALLED_APPS`. diff --git a/docs/ref/contrib/comments/signals.txt b/docs/ref/contrib/comments/signals.txt index 8274539ed7..f9df8980d7 100644 --- a/docs/ref/contrib/comments/signals.txt +++ b/docs/ref/contrib/comments/signals.txt @@ -5,6 +5,18 @@ Signals sent by the comments app .. module:: django.contrib.comments.signals :synopsis: Signals sent by the comment module. +.. warning:: + + Django's comment framework has been deprecated and is no longer supported. + Most users will be better served with a custom solution, or a hosted + product like Disqus__. + + The code formerly known as ``django.contrib.comments`` is `still available + in an external repository`__. + + __ https://disqus.com/ + __ https://github.com/django/django-contrib-comments + The comment app sends a series of :doc:`signals </topics/signals>` to allow for comment moderation and similar activities. See :doc:`the introduction to signals </topics/signals>` for information about how to register for and receive these @@ -81,8 +93,8 @@ Arguments sent with this signal: :meth:`~django.db.models.Model.save` again. ``flag`` - The :class:`~django.contrib.comments.models.CommentFlag` that's been - attached to the comment. + The ``django.contrib.comments.models.CommentFlag`` that's been attached to + the comment. ``created`` ``True`` if this is a new flag; ``False`` if it's a duplicate flag. diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index dfbeabc302..388172c43e 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -182,7 +182,7 @@ The ``ContentTypeManager`` Clears an internal cache used by :class:`~django.contrib.contenttypes.models.ContentType` to keep track - of which models for which it has created + of models for which it has created :class:`~django.contrib.contenttypes.models.ContentType` instances. You probably won't ever need to call this method yourself; Django will call it automatically when it's needed. @@ -234,14 +234,16 @@ lookup:: .. versionadded:: 1.5 -Prior to Django 1.5 :meth:`~ContentTypeManager.get_for_model()` and -:meth:`~ContentTypeManager.get_for_models()` always returned the -:class:`~django.contrib.contenttypes.models.ContentType` associated with the -concrete model of the specified one(s). That means there was no way to retreive -the :class:`~django.contrib.contenttypes.models.ContentType` of a proxy model +Prior to Django 1.5, +:meth:`~django.contrib.contenttypes.models.ContentTypeManager.get_for_model` and +:meth:`~django.contrib.contenttypes.models.ContentTypeManager.get_for_models` +always returned the :class:`~django.contrib.contenttypes.models.ContentType` +associated with the concrete model of the specified one(s). That means there +was no way to retrieve the +:class:`~django.contrib.contenttypes.models.ContentType` of a proxy model using those methods. As of Django 1.5 you can now pass a boolean flag – -respectively ``for_concrete_model`` and ``for_concrete_models`` – to specify -wether or not you want to retreive the +``for_concrete_model`` and ``for_concrete_models`` respectively – to specify +wether or not you want to retrieve the :class:`~django.contrib.contenttypes.models.ContentType` for the concrete or direct model. @@ -275,7 +277,7 @@ A normal :class:`~django.db.models.ForeignKey` can only "point to" one other model, which means that if the ``TaggedItem`` model used a :class:`~django.db.models.ForeignKey` it would have to choose one and only one model to store tags for. The contenttypes -application provides a special field type which +application provides a special field type (``GenericForeignKey``) which works around this and allows the relationship to be with any model: @@ -285,7 +287,8 @@ model: :class:`~django.contrib.contenttypes.generic.GenericForeignKey`: 1. Give your model a :class:`~django.db.models.ForeignKey` - to :class:`~django.contrib.contenttypes.models.ContentType`. + to :class:`~django.contrib.contenttypes.models.ContentType`. The usual + name for this field is "content_type". 2. Give your model a field that can store primary key values from the models you'll be relating to. For most models, this means a @@ -450,14 +453,18 @@ need to calculate them without using the aggregation API. Generic relations in forms and admin ------------------------------------ -The :mod:`django.contrib.contenttypes.generic` module provides -:class:`~django.contrib.contenttypes.generic.BaseGenericInlineFormSet`, -:class:`~django.contrib.contenttypes.generic.GenericTabularInline` -and :class:`~django.contrib.contenttypes.generic.GenericStackedInline` -(the last two are subclasses of -:class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin`). -This enables the use of generic relations in forms and the admin. See the -:doc:`model formset </topics/forms/modelforms>` and +The :mod:`django.contrib.contenttypes.generic` module provides: + +* ``BaseGenericInlineFormSet`` +* :class:`~django.contrib.contenttypes.generic.GenericTabularInline` + and :class:`~django.contrib.contenttypes.generic.GenericStackedInline` + (subclasses of + :class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin`) +* A formset factory, :func:`generic_inlineformset_factory`, for use with + :class:`GenericForeignKey` + +These classes and functions enable the use of generic relations in forms +and the admin. See the :doc:`model formset </topics/forms/modelforms>` and :ref:`admin <using-generic-relations-as-an-inline>` documentation for more information. @@ -478,3 +485,20 @@ information. The name of the integer field that represents the ID of the related object. Defaults to ``object_id``. + +.. class:: GenericTabularInline +.. class:: GenericStackedInline + + Subclasses of :class:`GenericInlineModelAdmin` with stacked and tabular + layouts, respectively. + +.. function:: generic_inlineformset_factory(model, form=ModelForm, formset=BaseGenericInlineFormSet, ct_field="content_type", fk_field="object_id", fields=None, exclude=None, extra=3, can_order=False, can_delete=True, max_num=None, formfield_callback=None, validate_max=False) + + Returns a ``GenericInlineFormSet`` using + :func:`~django.forms.models.modelformset_factory`. + + You must provide ``ct_field`` and ``object_id`` if they different from the + defaults, ``content_type`` and ``object_id`` respectively. Other parameters + are similar to those documented in + :func:`~django.forms.models.modelformset_factory` and + :func:`~django.forms.models.inlineformset_factory`. diff --git a/docs/ref/contrib/csrf.txt b/docs/ref/contrib/csrf.txt index 32d8a705bc..968ef0b07b 100644 --- a/docs/ref/contrib/csrf.txt +++ b/docs/ref/contrib/csrf.txt @@ -181,7 +181,7 @@ protecting the CSRF token from being sent to other domains. correctly on that version. Make sure you are running at least jQuery 1.5.1. You can use `settings.crossDomain <http://api.jquery.com/jQuery.ajax>`_ in -jQuery 1.5 and newer in order to replace the `sameOrigin` logic above: +jQuery 1.5 and newer in order to replace the ``sameOrigin`` logic above: .. code-block:: javascript @@ -410,8 +410,6 @@ Utilities .. function:: ensure_csrf_cookie(view) - .. versionadded:: 1.4 - This decorator forces a view to send the CSRF cookie. Scenarios @@ -490,64 +488,11 @@ developers of other reusable apps that want the same guarantees also use the Settings ======== -A number of settings can be used to control Django's CSRF behavior. - -CSRF_COOKIE_DOMAIN ------------------- - -Default: ``None`` - -The domain to be used when setting the CSRF cookie. This can be useful for -easily allowing cross-subdomain requests to be excluded from the normal cross -site request forgery protection. It should be set to a string such as -``".example.com"`` to allow a POST request from a form on one subdomain to be -accepted by a view served from another subdomain. - -Please note that, with or without use of this setting, this CSRF protection -mechanism is not safe against cross-subdomain attacks -- see `Limitations`_. - -CSRF_COOKIE_NAME ----------------- - -Default: ``'csrftoken'`` - -The name of the cookie to use for the CSRF authentication token. This can be -whatever you want. - -CSRF_COOKIE_PATH ----------------- - -.. versionadded:: 1.4 - -Default: ``'/'`` - -The path set on the CSRF cookie. This should either match the URL path of your -Django installation or be a parent of that path. - -This is useful if you have multiple Django instances running under the same -hostname. They can use different cookie paths, and each instance will only see -its own CSRF cookie. - -CSRF_COOKIE_SECURE ------------------- - -.. versionadded:: 1.4 - -Default: ``False`` - -Whether to use a secure cookie for the CSRF cookie. If this is set to ``True``, -the cookie will be marked as "secure," which means browsers may ensure that the -cookie is only sent under an HTTPS connection. - -CSRF_FAILURE_VIEW ------------------ - -Default: ``'django.views.csrf.csrf_failure'`` - -A dotted path to the view function to be used when an incoming request -is rejected by the CSRF protection. The function should have this signature:: - - def csrf_failure(request, reason="") +A number of settings can be used to control Django's CSRF behavior: -where ``reason`` is a short message (intended for developers or logging, not for -end users) indicating the reason the request was rejected. +* :setting:`CSRF_COOKIE_DOMAIN` +* :setting:`CSRF_COOKIE_HTTPONLY` +* :setting:`CSRF_COOKIE_NAME` +* :setting:`CSRF_COOKIE_PATH` +* :setting:`CSRF_COOKIE_SECURE` +* :setting:`CSRF_FAILURE_VIEW` diff --git a/docs/ref/contrib/databrowse.txt b/docs/ref/contrib/databrowse.txt deleted file mode 100644 index 3d411bb7b4..0000000000 --- a/docs/ref/contrib/databrowse.txt +++ /dev/null @@ -1,89 +0,0 @@ -========== -Databrowse -========== - -.. module:: django.contrib.databrowse - :synopsis: Databrowse is a Django application that lets you browse your data. - -.. deprecated:: 1.4 - This module has been deprecated. - -Databrowse is a Django application that lets you browse your data. - -As the Django admin dynamically creates an admin interface by introspecting -your models, Databrowse dynamically creates a rich, browsable Web site by -introspecting your models. - -How to use Databrowse -===================== - -1. Point Django at the default Databrowse templates. There are two ways to - do this: - - * Add ``'django.contrib.databrowse'`` to your :setting:`INSTALLED_APPS` - setting. This will work if your :setting:`TEMPLATE_LOADERS` setting - includes the ``app_directories`` template loader (which is the case by - default). See the :ref:`template loader docs <template-loaders>` for - more. - - * Otherwise, determine the full filesystem path to the - :file:`django/contrib/databrowse/templates` directory, and add that - directory to your :setting:`TEMPLATE_DIRS` setting. - -2. Register a number of models with the Databrowse site:: - - from django.contrib import databrowse - from myapp.models import SomeModel, SomeOtherModel, YetAnotherModel - - databrowse.site.register(SomeModel) - databrowse.site.register(SomeOtherModel, YetAnotherModel) - - Note that you should register the model *classes*, not instances. - - .. versionchanged:: 1.4 - - Since Django 1.4, it is possible to register several models in the same - call to :func:`~databrowse.site.register`. - - It doesn't matter where you put this, as long as it gets executed at some - point. A good place for it is in your :doc:`URLconf file - </topics/http/urls>` (``urls.py``). - -3. Change your URLconf to import the :mod:`~django.contrib.databrowse` module:: - - from django.contrib import databrowse - - ...and add the following line to your URLconf:: - - (r'^databrowse/(.*)', databrowse.site.root), - - The prefix doesn't matter -- you can use ``databrowse/`` or ``db/`` or - whatever you'd like. - -4. Run the Django server and visit ``/databrowse/`` in your browser. - -Requiring user login -==================== - -You can restrict access to logged-in users with only a few extra lines of -code. Simply add the following import to your URLconf:: - - from django.contrib.auth.decorators import login_required - -Then modify the :doc:`URLconf </topics/http/urls>` so that the -:func:`databrowse.site.root` view is decorated with -:func:`django.contrib.auth.decorators.login_required`:: - - (r'^databrowse/(.*)', login_required(databrowse.site.root)), - -If you haven't already added support for user logins to your :doc:`URLconf -</topics/http/urls>`, as described in the :doc:`user authentication docs -</ref/contrib/auth>`, then you will need to do so now with the following -mapping:: - - (r'^accounts/login/$', 'django.contrib.auth.views.login'), - -The final step is to create the login form required by -:func:`django.contrib.auth.views.login`. The -:doc:`user authentication docs </ref/contrib/auth>` provide full details and a -sample template that can be used for this purpose. diff --git a/docs/ref/contrib/flatpages.txt b/docs/ref/contrib/flatpages.txt index 7ff9165642..292b304acb 100644 --- a/docs/ref/contrib/flatpages.txt +++ b/docs/ref/contrib/flatpages.txt @@ -117,17 +117,9 @@ can do all of the work. :class:`~django.template.RequestContext` in rendering the template. - .. versionchanged:: 1.4 - The middleware will only add a trailing slash and redirect (by looking - at the :setting:`APPEND_SLASH` setting) if the resulting URL refers to - a valid flatpage. Previously requesting a non-existent flatpage - would redirect to the same URL with an apppended slash first and - subsequently raise a 404. - - .. versionchanged:: 1.4 - Redirects by the middleware are permanent (301 status code) instead of - temporary (302) to match behavior of the - :class:`~django.middleware.common.CommonMiddleware`. + The middleware will only add a trailing slash and redirect (by looking + at the :setting:`APPEND_SLASH` setting) if the resulting URL refers to + a valid flatpage. Redirects are permanent (301 status code). If it doesn't find a match, the request continues to be processed as usual. @@ -194,7 +186,7 @@ Via the Python API If you add or modify flatpages via your own code, you will likely want to check for duplicate flatpage URLs within the same site. The flatpage form used in the admin performs this validation check, and can be imported from - :class:`django.contrib.flatpages.forms.FlatPageForm` and used in your own + ``django.contrib.flatpages.forms.FlatPageForm`` and used in your own views. Flatpage templates @@ -264,7 +256,7 @@ Displaying ``registration_required`` flatpages By default, the :ttag:`get_flatpages` templatetag will only show flatpages that are marked ``registration_required = False``. If you want to display registration-protected flatpages, you need to specify -an authenticated user using a``for`` clause. +an authenticated user using a ``for`` clause. For example: diff --git a/docs/ref/contrib/formtools/form-preview.txt b/docs/ref/contrib/formtools/form-preview.txt index 784213ecba..011e72c2e0 100644 --- a/docs/ref/contrib/formtools/form-preview.txt +++ b/docs/ref/contrib/formtools/form-preview.txt @@ -25,9 +25,8 @@ application takes care of the following workflow: a. If it's valid, displays a preview page. b. If it's not valid, redisplays the form with error messages. 3. When the "confirmation" form is submitted from the preview page, calls - a hook that you define -- a - :meth:`~django.contrib.formtools.preview.FormPreview.done()` method that gets - passed the valid data. + a hook that you define -- a ``done()`` method that gets passed the valid + data. The framework enforces the required preview by passing a shared-secret hash to the preview page via hidden form fields. If somebody tweaks the form parameters @@ -51,8 +50,7 @@ How to use ``FormPreview`` directory to your :setting:`TEMPLATE_DIRS` setting. 2. Create a :class:`~django.contrib.formtools.preview.FormPreview` subclass that - overrides the :meth:`~django.contrib.formtools.preview.FormPreview.done()` - method:: + overrides the ``done()`` method:: from django.contrib.formtools.preview import FormPreview from myapp.models import SomeModel @@ -92,13 +90,15 @@ How to use ``FormPreview`` A :class:`~django.contrib.formtools.preview.FormPreview` class is a simple Python class that represents the preview workflow. :class:`~django.contrib.formtools.preview.FormPreview` classes must subclass -``django.contrib.formtools.preview.FormPreview`` and override the -:meth:`~django.contrib.formtools.preview.FormPreview.done()` method. They can live -anywhere in your codebase. +``django.contrib.formtools.preview.FormPreview`` and override the ``done()`` +method. They can live anywhere in your codebase. ``FormPreview`` templates ========================= +.. attribute:: FormPreview.form_template +.. attribute:: FormPreview.preview_template + By default, the form is rendered via the template :file:`formtools/form.html`, and the preview page is rendered via the template :file:`formtools/preview.html`. These values can be overridden for a particular form preview by setting diff --git a/docs/ref/contrib/formtools/form-wizard.txt b/docs/ref/contrib/formtools/form-wizard.txt index 3edc019d05..f85ae8356d 100644 --- a/docs/ref/contrib/formtools/form-wizard.txt +++ b/docs/ref/contrib/formtools/form-wizard.txt @@ -54,7 +54,8 @@ you just have to do these things: 4. Add ``django.contrib.formtools`` to your :setting:`INSTALLED_APPS` list in your settings file. -5. Point your URLconf at your :class:`WizardView` :meth:`~WizardView.as_view` method. +5. Point your URLconf at your :class:`WizardView` :meth:`~WizardView.as_view` + method. Defining ``Form`` classes ------------------------- @@ -89,6 +90,9 @@ the message itself. Here's what the :file:`forms.py` might look like:: Creating a ``WizardView`` subclass ---------------------------------- +.. class:: SessionWizardView +.. class:: CookieWizardView + The next step is to create a :class:`django.contrib.formtools.wizard.views.WizardView` subclass. You can also use the :class:`SessionWizardView` or :class:`CookieWizardView` classes @@ -225,9 +229,11 @@ Here's a full example template: Hooking the wizard into a URLconf --------------------------------- +.. method:: WizardView.as_view + Finally, we need to specify which forms to use in the wizard, and then deploy the new :class:`WizardView` object at a URL in the ``urls.py``. The -wizard's :meth:`as_view` method takes a list of your +wizard's ``as_view()`` method takes a list of your :class:`~django.forms.Form` classes as an argument during instantiation:: from django.conf.urls import patterns @@ -239,6 +245,13 @@ wizard's :meth:`as_view` method takes a list of your (r'^contact/$', ContactWizard.as_view([ContactForm1, ContactForm2])), ) +.. versionchanged:: 1.6 + +You can also pass the form list as a class attribute named ``form_list``:: + + class ContactWizard(WizardView): + form_list = [ContactForm1, ContactForm2] + .. _wizard-template-for-each-form: Using a different template for each form @@ -289,6 +302,14 @@ The ``urls.py`` file would contain something like:: (r'^checkout/$', OrderWizard.as_view(FORMS, condition_dict={'cc': pay_by_credit_card})), ) +.. versionchanged:: 1.6 + +The ``condiction_dict`` can be passed as attribute for the ``as_view()` +method or as a class attribute named ``condition_dict``:: + + class OrderWizard(WizardView): + condition_dict = {'cc': pay_by_credit_card} + Note that the ``OrderWizard`` object is initialized with a list of pairs. The first element in the pair is a string that corresponds to the name of the step and the second is the form class. @@ -312,11 +333,16 @@ Advanced ``WizardView`` methods counter as string representing the current step of the wizard. (E.g., the first form is ``'0'`` and the second form is ``'1'``) -.. method:: WizardView.get_form_prefix(step) +.. method:: WizardView.get_form_prefix(step=None, form=None) + + Returns the prefix which will be used when calling the form for the given + step. ``step`` contains the step name, ``form`` the form class which will + be called with the returned prefix. - Given the step, returns a form prefix to use. By default, this simply uses - the step itself. For more, see the :ref:`form prefix documentation - <form-prefix>`. + If no ``step`` is given, it will be determined automatically. By default, + this simply uses the step itself and the ``form`` parameter is not used. + + For more, see the :ref:`form prefix documentation <form-prefix>`. .. method:: WizardView.get_form_initial(step) @@ -346,9 +372,9 @@ Advanced ``WizardView`` methods used as the form for step ``step``. Returns an :class:`~django.db.models.Model` object which will be passed as - the :attr:`~django.forms.ModelForm.instance` argument when instantiating the - ModelForm for step ``step``. If no instance object was provided while - initializing the form wizard, ``None`` will be returned. + the ``instance`` argument when instantiating the ``ModelForm`` for step + ``step``. If no instance object was provided while initializing the form + wizard, ``None`` will be returned. The default implementation:: @@ -443,6 +469,17 @@ Advanced ``WizardView`` methods def process_step_files(self, form): return self.get_form_step_files(form) +.. method:: WizardView.render_goto_step(step, goto_step, **kwargs) + + .. versionadded:: 1.6 + + This method is called when the step should be changed to something else + than the next step. By default, this method just stores the requested + step ``goto_step`` in the storage and then renders the new step. + + If you want to store the entered data of the current step before rendering + the next step, you can overwrite this method. + .. method:: WizardView.render_revalidation_failure(step, form, **kwargs) When the wizard thinks all steps have passed it revalidates all forms with @@ -514,10 +551,10 @@ Providing initial data for the forms .. attribute:: WizardView.initial_dict Initial data for a wizard's :class:`~django.forms.Form` objects can be - provided using the optional :attr:`~Wizard.initial_dict` keyword argument. - This argument should be a dictionary mapping the steps to dictionaries - containing the initial data for each step. The dictionary of initial data - will be passed along to the constructor of the step's + provided using the optional :attr:`~WizardView.initial_dict` keyword + argument. This argument should be a dictionary mapping the steps to + dictionaries containing the initial data for each step. The dictionary of + initial data will be passed along to the constructor of the step's :class:`~django.forms.Form`:: >>> from myapp.forms import ContactForm1, ContactForm2 @@ -526,7 +563,9 @@ Providing initial data for the forms ... '0': {'subject': 'Hello', 'sender': 'user@example.com'}, ... '1': {'message': 'Hi there!'} ... } - >>> wiz = ContactWizard.as_view([ContactForm1, ContactForm2], initial_dict=initial) + >>> # This example is illustrative only and isn't meant to be run in + >>> # the shell since it requires an HttpRequest to pass to the view. + >>> wiz = ContactWizard.as_view([ContactForm1, ContactForm2], initial_dict=initial)(request) >>> form1 = wiz.get_form('0') >>> form2 = wiz.get_form('1') >>> form1.initial @@ -537,16 +576,23 @@ Providing initial data for the forms The ``initial_dict`` can also take a list of dictionaries for a specific step if the step is a ``FormSet``. + .. versionchanged:: 1.6 + + The ``initial_dict`` can also be added as a class attribute named + ``initial_dict`` to avoid having the initial data in the ``urls.py``. + .. _wizard-files: Handling files ============== +.. attribute:: WizardView.file_storage + To handle :class:`~django.forms.FileField` within any step form of the wizard, -you have to add a :attr:`file_storage` to your :class:`WizardView` subclass. +you have to add a ``file_storage`` to your :class:`WizardView` subclass. This storage will temporarily store the uploaded files for the wizard. The -:attr:`file_storage` attribute should be a +``file_storage`` attribute should be a :class:`~django.core.files.storage.Storage` subclass. Django provides a built-in storage class (see :ref:`the built-in filesystem @@ -646,6 +692,8 @@ Usage of ``NamedUrlWizardView`` =============================== .. class:: NamedUrlWizardView +.. class:: NamedUrlSessionWizardView +.. class:: NamedUrlCookieWizardView There is a :class:`WizardView` subclass which adds named-urls support to the wizard. By doing this, you can have single urls for every step. You can also diff --git a/docs/ref/contrib/formtools/index.txt b/docs/ref/contrib/formtools/index.txt index f36470654a..e768c0e655 100644 --- a/docs/ref/contrib/formtools/index.txt +++ b/docs/ref/contrib/formtools/index.txt @@ -1,6 +1,8 @@ django.contrib.formtools ======================== +.. module:: django.contrib.formtools + A set of high-level abstractions for Django forms (:mod:`django.forms`). .. toctree:: diff --git a/docs/ref/contrib/gis/commands.txt b/docs/ref/contrib/gis/commands.txt index 3dd161ce1d..015a1f9741 100644 --- a/docs/ref/contrib/gis/commands.txt +++ b/docs/ref/contrib/gis/commands.txt @@ -47,7 +47,8 @@ of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`. The key for specifying which layer in the OGR :class:`~django.contrib.gis.gdal.DataSource` source to use. Defaults to 0 (the first layer). May be an integer or a string identifier - for the :class:`~django.contrib.gis.gdal.Layer`. + for the :class:`~django.contrib.gis.gdal.Layer`. When inspecting databases, + ``layer`` is generally the table name you want to inspect. .. django-admin-option:: --mapping diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt index 519f79f0d4..be413c9df8 100644 --- a/docs/ref/contrib/gis/db-api.txt +++ b/docs/ref/contrib/gis/db-api.txt @@ -4,20 +4,23 @@ GeoDjango Database API ====================== -.. module:: django.contrib.gis.db.models - :synopsis: GeoDjango's database API. - .. _spatial-backends: Spatial Backends ================ +.. module:: django.contrib.gis.db.backends + :synopsis: GeoDjango's spatial database backends. + GeoDjango currently provides the following spatial database backends: -* :mod:`django.contrib.gis.db.backends.postgis` -* :mod:`django.contrib.gis.db.backends.mysql` -* :mod:`django.contrib.gis.db.backends.oracle` -* :mod:`django.contrib.gis.db.backends.spatialite` +* ``django.contrib.gis.db.backends.postgis`` +* ``django.contrib.gis.db.backends.mysql`` +* ``django.contrib.gis.db.backends.oracle`` +* ``django.contrib.gis.db.backends.spatialite`` + +.. module:: django.contrib.gis.db.models + :synopsis: GeoDjango's database API. .. _mysql-spatial-limitations: diff --git a/docs/ref/contrib/gis/feeds.txt b/docs/ref/contrib/gis/feeds.txt index 7c3a2d011c..7b1b6ebccf 100644 --- a/docs/ref/contrib/gis/feeds.txt +++ b/docs/ref/contrib/gis/feeds.txt @@ -27,7 +27,7 @@ API Reference .. class:: Feed In addition to methods provided by - the :class:`django.contrib.syndication.feeds.Feed` + the :class:`django.contrib.syndication.views.Feed` base class, GeoDjango's ``Feed`` class provides the following overrides. Note that these overrides may be done in multiple ways:: @@ -71,11 +71,11 @@ API Reference can be a ``GEOSGeometry`` instance, or a tuple that represents a point coordinate or bounding box. For example:: - class ZipcodeFeed(Feed): + class ZipcodeFeed(Feed): - def item_geometry(self, obj): - # Returns the polygon. - return obj.poly + def item_geometry(self, obj): + # Returns the polygon. + return obj.poly ``SyndicationFeed`` Subclasses ------------------------------ diff --git a/docs/ref/contrib/gis/gdal.txt b/docs/ref/contrib/gis/gdal.txt index c4b29bead7..c68030673b 100644 --- a/docs/ref/contrib/gis/gdal.txt +++ b/docs/ref/contrib/gis/gdal.txt @@ -13,7 +13,7 @@ of GDAL is the `OGR`__ Simple Features Library, which specializes in reading and writing vector geographic data in a variety of standard formats. -GeoDjango provides a high-level Python interface for some of the +GeoDjango provides a high-level Python interface for some of the capabilities of OGR, including the reading and coordinate transformation of vector spatial data. @@ -22,7 +22,7 @@ of vector spatial data. Although the module is named ``gdal``, GeoDjango only supports some of the capabilities of OGR. Thus, none of GDAL's features with respect to raster (image) data are supported at this time. - + __ http://www.gdal.org/ __ http://www.gdal.org/ogr/ @@ -68,13 +68,13 @@ each feature in that layer. also supports a variety of more complex data sources, including databases, that may be accessed by passing a special name string instead of a path. For more information, see the `OGR Vector Formats`__ - documentation. The :attr:`name` property of a ``DataSource`` + documentation. The :attr:`name` property of a ``DataSource`` instance gives the OGR name of the underlying data source that it is using. - Once you've created your ``DataSource``, you can find out how many - layers of data it contains by accessing the :attr:`layer_count` property, - or (equivalently) by using the ``len()`` function. For information on + Once you've created your ``DataSource``, you can find out how many + layers of data it contains by accessing the :attr:`layer_count` property, + or (equivalently) by using the ``len()`` function. For information on accessing the layers of data themselves, see the next section:: >>> from django.contrib.gis.gdal import DataSource @@ -105,7 +105,7 @@ __ http://www.gdal.org/ogr/ogr_formats.html Python container of ``Layer`` objects. For example, you can access a specific layer by its index (e.g. ``ds[0]`` to access the first layer), or you can iterate over all the layers in the container in a - ``for`` loop. The ``Layer`` itself acts as a container for geometric + ``for`` loop. The ``Layer`` itself acts as a container for geometric features. Typically, all the features in a given layer have the same geometry type. @@ -120,7 +120,7 @@ __ http://www.gdal.org/ogr/ogr_formats.html The example output is from the cities data source, loaded above, which evidently contains one layer, called ``"cities"``, which contains three - point features. For simplicity, the examples below assume that you've + point features. For simplicity, the examples below assume that you've stored that layer in the variable ``layer``:: >>> layer = ds[0] @@ -169,7 +169,7 @@ __ http://www.gdal.org/ogr/ogr_formats.html >>> [ft.__name__ for ft in layer.field_types] ['OFTString', 'OFTReal', 'OFTReal', 'OFTDate'] - + .. attribute:: field_widths Returns a list of the maximum field widths for each of the fields in @@ -181,7 +181,7 @@ __ http://www.gdal.org/ogr/ogr_formats.html .. attribute:: field_precisions Returns a list of the numeric precisions for each of the fields in - this layer. This is meaningless (and set to zero) for non-numeric + this layer. This is meaningless (and set to zero) for non-numeric fields:: >>> layer.field_precisions @@ -189,7 +189,7 @@ __ http://www.gdal.org/ogr/ogr_formats.html .. attribute:: extent - Returns the spatial extent of this layer, as an :class:`Envelope` + Returns the spatial extent of this layer, as an :class:`Envelope` object:: >>> layer.extent.tuple @@ -214,7 +214,7 @@ __ http://www.gdal.org/ogr/ogr_formats.html Property that may be used to retrieve or set a spatial filter for this layer. A spatial filter can only be set with an :class:`OGRGeometry` - instance, a 4-tuple extent, or ``None``. When set with something + instance, a 4-tuple extent, or ``None``. When set with something other than ``None``, only features that intersect the filter will be returned when iterating over the layer:: @@ -258,9 +258,9 @@ __ http://www.gdal.org/ogr/ogr_formats.html given capability (a string). Examples of valid capability strings include: ``'RandomRead'``, ``'SequentialWrite'``, ``'RandomWrite'``, ``'FastSpatialFilter'``, ``'FastFeatureCount'``, ``'FastGetExtent'``, - ``'CreateField'``, ``'Transactions'``, ``'DeleteFeature'``, and + ``'CreateField'``, ``'Transactions'``, ``'DeleteFeature'``, and ``'FastSetNextByIndex'``. - + ``Feature`` ----------- @@ -295,14 +295,14 @@ __ http://www.gdal.org/ogr/ogr_formats.html Returns the type of geometry for this feature, as an :class:`OGRGeomType` object. This will be the same for all features in a given layer, and - is equivalent to the :attr:`Layer.geom_type` property of the - :class:`Layer`` object the feature came from. + is equivalent to the :attr:`Layer.geom_type` property of the + :class:`Layer` object the feature came from. .. attribute:: num_fields Returns the number of fields of data associated with the feature. This will be the same for all features in a given layer, and is - equivalent to the :attr:`Layer.num_fields` property of the + equivalent to the :attr:`Layer.num_fields` property of the :class:`Layer` object the feature came from. .. attribute:: fields @@ -350,7 +350,7 @@ __ http://www.gdal.org/ogr/ogr_formats.html .. attribute:: type Returns the OGR type of this field, as an integer. The - ``FIELD_CLASSES`` dictionary maps these values onto + ``FIELD_CLASSES`` dictionary maps these values onto subclasses of ``Field``:: >>> city['Density'].type @@ -365,8 +365,8 @@ __ http://www.gdal.org/ogr/ogr_formats.html .. attribute:: value - Returns the value of this field. The ``Field`` class itself - returns the value as a string, but each subclass returns the + Returns the value of this field. The ``Field`` class itself + returns the value as a string, but each subclass returns the value in the most appropriate form:: >>> city['Population'].value @@ -433,10 +433,10 @@ OGR Geometries ``OGRGeometry`` --------------- -:class:`OGRGeometry` objects share similar functionality with +:class:`OGRGeometry` objects share similar functionality with :class:`~django.contrib.gis.geos.GEOSGeometry` objects, and are thin -wrappers around OGR's internal geometry representation. Thus, -they allow for more efficient access to data when using :class:`DataSource`. +wrappers around OGR's internal geometry representation. Thus, +they allow for more efficient access to data when using :class:`DataSource`. Unlike its GEOS counterpart, :class:`OGRGeometry` supports spatial reference systems and coordinate transformation:: @@ -446,10 +446,10 @@ systems and coordinate transformation:: .. class:: OGRGeometry(geom_input[, srs=None]) This object is a wrapper for the `OGR Geometry`__ class. - These objects are instantiated directly from the given ``geom_input`` + These objects are instantiated directly from the given ``geom_input`` parameter, which may be a string containing WKT, HEX, GeoJSON, a ``buffer`` containing WKB data, or an :class:`OGRGeomType` object. These objects - are also returned from the :class:`Feature.geom` attribute, when + are also returned from the :class:`Feature.geom` attribute, when reading vector data from :class:`Layer` (which is in turn a part of a :class:`DataSource`). @@ -557,14 +557,14 @@ systems and coordinate transformation:: .. attribute:: srid - Returns or sets the spatial reference identifier corresponding to + Returns or sets the spatial reference identifier corresponding to :class:`SpatialReference` of this geometry. Returns ``None`` if there is no spatial reference information associated with this geometry, or if an SRID cannot be determined. .. attribute:: geos - Returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object + Returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object corresponding to this geometry. .. attribute:: gml @@ -634,8 +634,8 @@ systems and coordinate transformation:: or any other input accepted by :class:`SpatialReference` (including spatial reference WKT and PROJ.4 strings, or an integer SRID). By default nothing is returned and the geometry is transformed in-place. - However, if the `clone` keyword is set to ``True`` then a transformed clone - of this geometry is returned instead. + However, if the ``clone`` keyword is set to ``True`` then a transformed + clone of this geometry is returned instead. .. method:: intersects(other) @@ -762,9 +762,9 @@ systems and coordinate transformation:: .. attribute:: z - Returns a list of Z coordinates in this line, or ``None`` if the + Returns a list of Z coordinates in this line, or ``None`` if the line does not have Z coordinates:: - + >>> OGRGeometry('LINESTRING (1 2 3,4 5 6)').z [3.0, 6.0] @@ -885,7 +885,7 @@ Coordinate System Objects Spatial reference objects are initialized on the given ``srs_input``, which may be one of the following: - + * OGC Well Known Text (WKT) (a string) * EPSG code (integer or string) * PROJ.4 string @@ -912,7 +912,7 @@ Coordinate System Objects .. method:: __getitem__(target) Returns the value of the given string attribute node, ``None`` if the node - doesn't exist. Can also take a tuple as a parameter, (target, child), + doesn't exist. Can also take a tuple as a parameter, (target, child), where child is the index of the attribute in the WKT. For example:: >>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]') @@ -1011,7 +1011,7 @@ Coordinate System Objects .. attribute:: units - Returns a 2-tuple of the units value and the units name, + Returns a 2-tuple of the units value and the units name, and will automatically determines whether to return the linear or angular units. @@ -1073,7 +1073,7 @@ Coordinate System Objects .. class:: CoordTransform(source, target) -Represents a coordinate system transform. It is initialized with two +Represents a coordinate system transform. It is initialized with two :class:`SpatialReference`, representing the source and target coordinate systems, respectively. These objects should be used when performing the same coordinate transformation repeatedly on different geometries:: diff --git a/docs/ref/contrib/gis/geoip.txt b/docs/ref/contrib/gis/geoip.txt index e37c4c60b0..2444849a19 100644 --- a/docs/ref/contrib/gis/geoip.txt +++ b/docs/ref/contrib/gis/geoip.txt @@ -7,22 +7,13 @@ Geolocation with GeoIP .. module:: django.contrib.gis.geoip :synopsis: High-level Python interface for MaxMind's GeoIP C library. -.. versionchanged:: 1.4 - -.. note:: - - In Django 1.4, the :class:`GeoIP` object was moved out of - :mod:`django.contrib.gis.utils` and into its own module, - :mod:`django.contrib.gis.geoip`. A shortcut is still provided - in ``utils``, but will be removed in Django 1.6. - The :class:`GeoIP` object is a ctypes wrapper for the `MaxMind GeoIP C API`__. [#]_ This interface is a BSD-licensed alternative to the GPL-licensed `Python GeoIP`__ interface provided by MaxMind. In order to perform IP-based geolocation, the :class:`GeoIP` object requires -the GeoIP C libary and either the GeoIP `Country`__ or `City`__ -datasets in binary format (the CSV files will not work!). These datasets may be +the GeoIP C libary and either the GeoIP `Country`__ or `City`__ +datasets in binary format (the CSV files will not work!). These datasets may be `downloaded from MaxMind`__. Grab the ``GeoLiteCountry/GeoIP.dat.gz`` and ``GeoLiteCity.dat.gz`` files and unzip them in a directory corresponding to what you set :setting:`GEOIP_PATH` with in your settings. See the example and @@ -58,7 +49,7 @@ usage:: >>> g.lat_lon('salon.com') (37.789798736572266, -122.39420318603516) >>> g.lon_lat('uh.edu') - (-95.415199279785156, 29.77549934387207) + (-95.415199279785156, 29.77549934387207) >>> g.geos('24.124.1.80').wkt 'POINT (-95.2087020874023438 39.0392990112304688)' @@ -104,30 +95,30 @@ Defaults to ``'GeoLiteCity.dat'``. .. class:: GeoIP([path=None, cache=0, country=None, city=None]) -The ``GeoIP`` object does not require any parameters to use the default +The ``GeoIP`` object does not require any parameters to use the default settings. However, at the very least the :setting:`GEOIP_PATH` setting -should be set with the path of the location of your GeoIP data sets. The -following intialization keywords may be used to customize any of the -defaults. +should be set with the path of the location of your GeoIP data sets. The +following intialization keywords may be used to customize any of the +defaults. =================== ======================================================= Keyword Arguments Description =================== ======================================================= -``path`` Base directory to where GeoIP data is located or the - full path to where the city or country data files - (.dat) are located. Assumes that both the city and - country data sets are located in this directory; +``path`` Base directory to where GeoIP data is located or the + full path to where the city or country data files + (.dat) are located. Assumes that both the city and + country data sets are located in this directory; overrides the :setting:`GEOIP_PATH` settings attribute. ``cache`` The cache settings when opening up the GeoIP datasets, and may be an integer in (0, 1, 2, 4) corresponding to - the ``GEOIP_STANDARD``, ``GEOIP_MEMORY_CACHE``, - ``GEOIP_CHECK_CACHE``, and ``GEOIP_INDEX_CACHE`` - ``GeoIPOptions`` C API settings, respectively. + the ``GEOIP_STANDARD``, ``GEOIP_MEMORY_CACHE``, + ``GEOIP_CHECK_CACHE``, and ``GEOIP_INDEX_CACHE`` + ``GeoIPOptions`` C API settings, respectively. Defaults to 0 (``GEOIP_STANDARD``). - + ``country`` The name of the GeoIP country data file. Defaults - to ``GeoIP.dat``. Setting this keyword overrides the + to ``GeoIP.dat``. Setting this keyword overrides the :setting:`GEOIP_COUNTRY` settings attribute. ``city`` The name of the GeoIP city data file. Defaults to @@ -142,9 +133,9 @@ Querying -------- All the following querying routines may take either a string IP address -or a fully qualified domain name (FQDN). For example, both -``'205.186.163.125'`` and ``'djangoproject.com'`` would be valid query -parameters. +or a fully qualified domain name (FQDN). For example, both +``'205.186.163.125'`` and ``'djangoproject.com'`` would be valid query +parameters. .. method:: GeoIP.city(query) @@ -153,7 +144,7 @@ of the values in the dictionary may be undefined (``None``). .. method:: GeoIP.country(query) -Returns a dictionary with the country code and country for the given +Returns a dictionary with the country code and country for the given query. .. method:: GeoIP.country_code(query) @@ -202,7 +193,7 @@ and country), and the version of the GeoIP C library (if supported). GeoIP-Python API compatibility methods ---------------------------------------- -These methods exist to ease compatibility with any code using MaxMind's +These methods exist to ease compatibility with any code using MaxMind's existing Python API. .. classmethod:: GeoIP.open(path, cache) diff --git a/docs/ref/contrib/gis/geoquerysets.txt b/docs/ref/contrib/gis/geoquerysets.txt index 69280dc028..97217e3c38 100644 --- a/docs/ref/contrib/gis/geoquerysets.txt +++ b/docs/ref/contrib/gis/geoquerysets.txt @@ -683,7 +683,7 @@ Keyword Argument Description a method name clashes with an existing ``GeoQuerySet`` method -- if you wanted to use the ``area()`` method on model with a ``PolygonField`` - named ``area``, for example. + named ``area``, for example. ===================== ===================================================== Measurement @@ -949,6 +949,9 @@ __ http://geohash.org/ *Availability*: PostGIS, SpatiaLite +.. versionchanged:: 1.5 + ``geojson`` support for Spatialite > 3.0 has been added. + Attaches a ``geojson`` attribute to every model in the queryset that contains the `GeoJSON`__ representation of the geometry. @@ -1043,7 +1046,7 @@ Keyword Argument Description ===================== ===================================================== ``relative`` If set to ``True``, the path data will be implemented in terms of relative moves. Defaults to ``False``, - meaning that absolute moves are used instead. + meaning that absolute moves are used instead. ``precision`` This keyword may be used to specify the number of significant digits for the coordinates in the SVG diff --git a/docs/ref/contrib/gis/geos.txt b/docs/ref/contrib/gis/geos.txt index 7d7c32781c..4d44638488 100644 --- a/docs/ref/contrib/gis/geos.txt +++ b/docs/ref/contrib/gis/geos.txt @@ -142,10 +142,9 @@ Geometry Objects .. class:: GEOSGeometry(geo_input[, srid=None]) - :param geo_input: Geometry input value - :type geo_input: string or buffer + :param geo_input: Geometry input value (string or buffer) :param srid: spatial reference identifier - :type srid: integer + :type srid: int This is the base class for all GEOS geometry objects. It initializes on the given ``geo_input`` argument, and then assumes the proper geometry subclass @@ -800,7 +799,7 @@ Example:: :param string: string that contains spatial data :type string: string :param srid: spatial reference identifier - :type srid: integer + :type srid: int :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the string Example:: @@ -966,3 +965,10 @@ location (e.g., ``/home/bob/lib/libgeos_c.so``). The setting must be the *full* path to the **C** shared library; in other words you want to use ``libgeos_c.so``, not ``libgeos.so``. + +Exceptions +========== + +.. exception:: GEOSException + +The base GEOS exception, indicates a GEOS-related error. diff --git a/docs/ref/contrib/gis/install/create_template_postgis-debian.sh b/docs/ref/contrib/gis/install/create_template_postgis-debian.sh index 3e621837fa..c59834c87e 100755 --- a/docs/ref/contrib/gis/install/create_template_postgis-debian.sh +++ b/docs/ref/contrib/gis/install/create_template_postgis-debian.sh @@ -3,13 +3,6 @@ GEOGRAPHY=0 POSTGIS_SQL=postgis.sql -# For Ubuntu 8.x and 9.x releases. -if [ -d "/usr/share/postgresql-8.3-postgis" ] -then - POSTGIS_SQL_PATH=/usr/share/postgresql-8.3-postgis - POSTGIS_SQL=lwpostgis.sql -fi - # For Ubuntu 10.04 if [ -d "/usr/share/postgresql/8.4/contrib" ] then diff --git a/docs/ref/contrib/gis/install/geolibs.txt b/docs/ref/contrib/gis/install/geolibs.txt index c78f0c0e62..74ebf6a35f 100644 --- a/docs/ref/contrib/gis/install/geolibs.txt +++ b/docs/ref/contrib/gis/install/geolibs.txt @@ -88,16 +88,16 @@ internal geometry representation used by GeoDjango (it's behind the "lazy" geometries). Specifically, the C API library is called (e.g., ``libgeos_c.so``) directly from Python using ctypes. -First, download GEOS 3.3.5 from the refractions Web site and untar the source +First, download GEOS 3.3.8 from the refractions Web site and untar the source archive:: - $ wget http://download.osgeo.org/geos/geos-3.3.5.tar.bz2 - $ tar xjf geos-3.3.5.tar.bz2 + $ wget http://download.osgeo.org/geos/geos-3.3.8.tar.bz2 + $ tar xjf geos-3.3.8.tar.bz2 Next, change into the directory where GEOS was unpacked, run the configure script, compile, and install:: - $ cd geos-3.3.5 + $ cd geos-3.3.8 $ ./configure $ make $ sudo make install @@ -181,9 +181,9 @@ supports :ref:`GDAL's vector data <ref-gdal>` capabilities [#]_. First download the latest GDAL release version and untar the archive:: - $ wget http://download.osgeo.org/gdal/gdal-1.9.1.tar.gz - $ tar xzf gdal-1.9.1.tar.gz - $ cd gdal-1.9.1 + $ wget http://download.osgeo.org/gdal/gdal-1.9.2.tar.gz + $ tar xzf gdal-1.9.2.tar.gz + $ cd gdal-1.9.2 Configure, make and install:: @@ -216,7 +216,7 @@ Can't find GDAL library When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag will be false: -.. code-block:: pycon +.. code-block:: python >>> from django.contrib.gis import gdal >>> gdal.HAS_GDAL diff --git a/docs/ref/contrib/gis/install/index.txt b/docs/ref/contrib/gis/install/index.txt index 100dc2edd0..62369d8253 100644 --- a/docs/ref/contrib/gis/install/index.txt +++ b/docs/ref/contrib/gis/install/index.txt @@ -46,8 +46,8 @@ how to install. Spatial database ---------------- -PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are -the spatial databases currently supported. +PostgreSQL (with PostGIS), MySQL (mostly with MyISAM engine), Oracle, and SQLite +(with SpatiaLite) are the spatial databases currently supported. .. note:: @@ -61,8 +61,8 @@ supported versions, and any notes for each of the supported database backends: ================== ============================== ================== ========================================= Database Library Requirements Supported Versions Notes ================== ============================== ================== ========================================= -PostgreSQL GEOS, PROJ.4, PostGIS 8.2+ Requires PostGIS. -MySQL GEOS 5.x Not OGC-compliant; limited functionality. +PostgreSQL GEOS, PROJ.4, PostGIS 8.4+ Requires PostGIS. +MySQL GEOS 5.x Not OGC-compliant; :ref:`limited functionality <mysql-spatial-limitations>`. Oracle GEOS 10.2, 11 XE not supported; not tested with 9. SQLite GEOS, GDAL, PROJ.4, SpatiaLite 3.6.+ Requires SpatiaLite 2.3+, pysqlite2 2.5+ ================== ============================== ================== ========================================= @@ -330,7 +330,7 @@ described above, ``psycopg2`` may be installed using the following command:: .. note:: - If you don't have ``pip``, follow the the :ref:`installation instructions + If you don't have ``pip``, follow the :ref:`installation instructions <installing-official-release>` to install it. .. _fink: @@ -392,7 +392,7 @@ GeoDjango on Windows. .. note:: These instructions assume that you are using 32-bit versions of - all programs. While 64-bit versions of Python and PostgreSQL 9.0 + all programs. While 64-bit versions of Python and PostgreSQL 9.x are available, 64-bit versions of spatial libraries, like GEOS and GDAL, are not yet provided by the :ref:`OSGeo4W` installer. @@ -415,7 +415,7 @@ __ http://python.org/download/ PostgreSQL ^^^^^^^^^^ -First, download the latest `PostgreSQL 9.0 installer`__ from the +First, download the latest `PostgreSQL 9.x installer`__ from the `EnterpriseDB`__ Web site. After downloading, simply run the installer, follow the on-screen directions, and keep the default options unless you know the consequences of changing them. @@ -435,7 +435,7 @@ install :ref:`postgisasb`. If installed successfully, the PostgreSQL server will run in the background each time the system as started as a Windows service. - A :menuselection:`PostgreSQL 9.0` start menu group will created + A :menuselection:`PostgreSQL 9.x` start menu group will created and contains shortcuts for the ASB as well as the 'SQL Shell', which will launch a ``psql`` command window. @@ -448,10 +448,10 @@ PostGIS ^^^^^^^ From within the Application Stack Builder (to run outside of the installer, -:menuselection:`Start --> Programs --> PostgreSQL 9.0`), select -:menuselection:`PostgreSQL Database Server 9.0 on port 5432` from the drop down +:menuselection:`Start --> Programs --> PostgreSQL 9.x`), select +:menuselection:`PostgreSQL Database Server 9.x on port 5432` from the drop down menu. Next, expand the :menuselection:`Categories --> Spatial Extensions` menu -tree and select :menuselection:`PostGIS 1.5 for PostgreSQL 9.0`. +tree and select :menuselection:`PostGIS 1.5 for PostgreSQL 9.x`. After clicking next, you will be prompted to select your mirror, PostGIS will be downloaded, and the PostGIS installer will begin. Select only the @@ -530,6 +530,6 @@ Finally, :ref:`install Django <installing-official-release>` on your system. .. rubric:: Footnotes .. [#] GeoDjango uses the :func:`~ctypes.util.find_library` routine from - :mod:`ctypes.util` to locate shared libraries. + ``ctypes.util`` to locate shared libraries. .. [#] The ``psycopg2`` Windows installers are packaged and maintained by `Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_. diff --git a/docs/ref/contrib/gis/install/postgis.txt b/docs/ref/contrib/gis/install/postgis.txt index 6d7fe88203..c651fe8fca 100644 --- a/docs/ref/contrib/gis/install/postgis.txt +++ b/docs/ref/contrib/gis/install/postgis.txt @@ -28,9 +28,9 @@ Building from source First download the source archive, and extract:: - $ wget http://postgis.refractions.net/download/postgis-2.0.1.tar.gz - $ tar xzf postgis-2.0.1.tar.gz - $ cd postgis-2.0.1 + $ wget http://download.osgeo.org/postgis/source/postgis-2.0.3.tar.gz + $ tar xzf postgis-2.0.3.tar.gz + $ cd postgis-2.0.3 Next, configure, make and install PostGIS:: @@ -56,10 +56,10 @@ Post-installation .. _spatialdb_template: .. _spatialdb_template91: -Creating a spatial database with PostGIS 2.0 and PostgreSQL 9.1 ---------------------------------------------------------------- +Creating a spatial database with PostGIS 2.0 and PostgreSQL 9.1+ +---------------------------------------------------------------- -PostGIS 2 includes an extension for Postgres 9.1 that can be used to enable +PostGIS 2 includes an extension for Postgres 9.1+ that can be used to enable spatial functionality:: $ createdb <db name> @@ -166,8 +166,8 @@ Managing the database --------------------- To administer the database, you can either use the pgAdmin III program -(:menuselection:`Start --> PostgreSQL 9.0 --> pgAdmin III`) or the -SQL Shell (:menuselection:`Start --> PostgreSQL 9.0 --> SQL Shell`). +(:menuselection:`Start --> PostgreSQL 9.x --> pgAdmin III`) or the +SQL Shell (:menuselection:`Start --> PostgreSQL 9.x --> SQL Shell`). For example, to create a ``geodjango`` spatial database and user, the following may be executed from the SQL Shell as the ``postgres`` user:: diff --git a/docs/ref/contrib/gis/model-api.txt b/docs/ref/contrib/gis/model-api.txt index 8c5274e6d3..81b619e338 100644 --- a/docs/ref/contrib/gis/model-api.txt +++ b/docs/ref/contrib/gis/model-api.txt @@ -195,7 +195,7 @@ details. Geography Type ^^^^^^^^^^^^^^ -In PostGIS 1.5, the geography type was introduced -- it provides +In PostGIS 1.5, the geography type was introduced -- it provides native support for spatial features represented with geographic coordinates (e.g., WGS84 longitude/latitude). [#fngeography]_ Unlike the plane used by a geometry type, the geography type uses a spherical @@ -236,13 +236,12 @@ if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode`` model:: from django.contrib.gis.db import models - from django.contrib.localflavor.us.models import USStateField class Address(models.Model): num = models.IntegerField() street = models.CharField(max_length=100) city = models.CharField(max_length=100) - state = USStateField() + state = models.CharField(max_length=2) zipcode = models.ForeignKey(Zipcode) objects = models.GeoManager() diff --git a/docs/ref/contrib/gis/testing.txt b/docs/ref/contrib/gis/testing.txt index 86979f0308..2a6dcef46f 100644 --- a/docs/ref/contrib/gis/testing.txt +++ b/docs/ref/contrib/gis/testing.txt @@ -140,6 +140,8 @@ with the rest of :ref:`Django's unit tests <running-unit-tests>`. Run only GeoDjango tests ------------------------ +.. class:: django.contrib.gis.tests.GeoDjangoTestSuiteRunner + To run *only* the tests for GeoDjango, the :setting:`TEST_RUNNER` setting must be changed to use the :class:`~django.contrib.gis.tests.GeoDjangoTestSuiteRunner`:: diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index 5000622ad4..56d90c8593 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/docs/ref/contrib/gis/tutorial.txt @@ -115,13 +115,12 @@ In addition, modify the :setting:`INSTALLED_APPS` setting to include and ``world`` (your newly created application):: INSTALLED_APPS = ( + 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', - 'django.contrib.sites', 'django.contrib.messages', 'django.contrib.staticfiles', - 'django.contrib.admin', 'django.contrib.gis', 'world' ) @@ -226,7 +225,7 @@ model to represent this data:: class WorldBorder(models.Model): # Regular Django fields corresponding to the attributes in the - # world borders shapefile. + # world borders shapefile. name = models.CharField(max_length=50) area = models.IntegerField() pop2005 = models.IntegerField('Population 2005') @@ -236,13 +235,13 @@ model to represent this data:: un = models.IntegerField('United Nations Code') region = models.IntegerField('Region Code') subregion = models.IntegerField('Sub-Region Code') - lon = models.FloatField() - lat = models.FloatField() + lon = models.FloatField() + lat = models.FloatField() - # GeoDjango-specific: a geometry field (MultiPolygonField), and + # GeoDjango-specific: a geometry field (MultiPolygonField), and # overriding the default manager with a GeoManager instance. - mpoly = models.MultiPolygonField() - objects = models.GeoManager() + mpoly = models.MultiPolygonField() + objects = models.GeoManager() # Returns the string representation of the model. def __unicode__(self): @@ -250,7 +249,7 @@ model to represent this data:: Please note two important things: -1. The ``models`` module is imported from :mod:`django.contrib.gis.db`. +1. The ``models`` module is imported from ``django.contrib.gis.db``. 2. You must override the model's default manager with :class:`~django.contrib.gis.db.models.GeoManager` to perform spatial queries. diff --git a/docs/ref/contrib/humanize.txt b/docs/ref/contrib/humanize.txt index 57978288b1..aca6ed990d 100644 --- a/docs/ref/contrib/humanize.txt +++ b/docs/ref/contrib/humanize.txt @@ -100,10 +100,8 @@ Examples (when 'today' is 17 Feb 2007): naturaltime ----------- -.. versionadded:: 1.4 - For datetime values, returns a string representing how many seconds, -minutes or hours ago it was -- falling back to the :tfilter:`timesince` +minutes or hours ago it was -- falling back to the :tfilter:`timesince` format if the value is more than a day old. In case the datetime value is in the future the return value will automatically use an appropriate phrase. diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt index efe4393f64..e5cea01ead 100644 --- a/docs/ref/contrib/index.txt +++ b/docs/ref/contrib/index.txt @@ -27,13 +27,10 @@ those packages have. comments/index contenttypes csrf - databrowse flatpages formtools/index gis/index humanize - localflavor - markup messages redirects sitemaps @@ -56,7 +53,7 @@ auth Django's authentication framework. -See :doc:`/topics/auth`. +See :doc:`/topics/auth/index`. comments ======== @@ -123,22 +120,6 @@ A set of Django template filters useful for adding a "human touch" to data. See the :doc:`humanize documentation </ref/contrib/humanize>`. -localflavor -=========== - -A collection of various Django snippets that are useful only for a particular -country or culture. For example, ``django.contrib.localflavor.us.forms`` -contains a ``USZipCodeField`` that you can use to validate U.S. zip codes. - -See the :doc:`localflavor documentation </ref/contrib/localflavor>`. - -markup -====== - -A collection of template filters that implement common markup languages - -See the :doc:`markup documentation </ref/contrib/markup>`. - messages ======== diff --git a/docs/ref/contrib/localflavor.txt b/docs/ref/contrib/localflavor.txt deleted file mode 100644 index 9bb27e6e74..0000000000 --- a/docs/ref/contrib/localflavor.txt +++ /dev/null @@ -1,148 +0,0 @@ -========================== -The "local flavor" add-ons -========================== - -.. module:: django.contrib.localflavor - :synopsis: A collection of various Django snippets that are useful only for - a particular country or culture. - -Historically, Django has shipped with ``django.contrib.localflavor`` -- -assorted pieces of code that are useful for particular countries or cultures. -Starting with Django 1.5, we've started the process of moving the code to -outside packages (i.e., packages distributed separately from Django), for -easier maintenance and to trim the size of Django's codebase. - -The localflavor packages are named ``django-localflavor-*``, where the asterisk -is an `ISO 3166 country code`_. For example: ``django-localflavor-us`` is the -localflavor package for the U.S.A. - -Most of these ``localflavor`` add-ons are country-specific fields for the -:doc:`forms </topics/forms/index>` framework -- for example, a -``USStateField`` that knows how to validate U.S. state abbreviations and a -``FISocialSecurityNumber`` that knows how to validate Finnish social security -numbers. - -To use one of these localized components, just import the relevant subpackage. -For example, here's how you can create a form with a field representing a -French telephone number:: - - from django import forms - from django_localflavor_fr.forms import FRPhoneNumberField - - class MyForm(forms.Form): - my_french_phone_no = FRPhoneNumberField() - -For documentation on a given country's localflavor helpers, see its README -file. - -.. _ISO 3166 country code: http://www.iso.org/iso/country_codes.htm - -How to migrate -============== - -If you've used the old ``django.contrib.localflavor`` package, follow these two -easy steps to update your code: - -1. Install the appropriate third-party ``django-localflavor-*`` package(s). - Go to https://github.com/django/ and find the package for your country. - -2. Change your app's import statements to reference the new packages. - - For example, change this:: - - from django.contrib.localflavor.fr.forms import FRPhoneNumberField - - ...to this:: - - from django_localflavor_fr.forms import FRPhoneNumberField - -The code in the new packages is the same (it was copied directly from Django), -so you don't have to worry about backwards compatibility in terms of -functionality. Only the imports have changed. - -Deprecation policy -================== - -In Django 1.5, importing from ``django.contrib.localflavor`` will result in a -``DeprecationWarning``. This means your code will still work, but you should -change it as soon as possible. - -In Django 1.6, importing from ``django.contrib.localflavor`` will no longer -work. - -Supported countries -=================== - -The following countries have django-localflavor- packages. - -* Argentina: https://github.com/django/django-localflavor-ar -* Australia: https://github.com/django/django-localflavor-au -* Austria: https://github.com/django/django-localflavor-at -* Belgium: https://github.com/django/django-localflavor-be -* Brazil: https://github.com/django/django-localflavor-br -* Canada: https://github.com/django/django-localflavor-ca -* Chile: https://github.com/django/django-localflavor-cl -* China: https://github.com/django/django-localflavor-cn -* Colombia: https://github.com/django/django-localflavor-co -* Croatia: https://github.com/django/django-localflavor-cr -* Czech Republic: https://github.com/django/django-localflavor-cz -* Ecuador: https://github.com/django/django-localflavor-ec -* Finland: https://github.com/django/django-localflavor-fi -* France: https://github.com/django/django-localflavor-fr -* Germany: https://github.com/django/django-localflavor-de -* Hong Kong: https://github.com/django/django-localflavor-hk -* Iceland: https://github.com/django/django-localflavor-is -* India: https://github.com/django/django-localflavor-in -* Indonesia: https://github.com/django/django-localflavor-id -* Ireland: https://github.com/django/django-localflavor-ie -* Israel: https://github.com/django/django-localflavor-il -* Italy: https://github.com/django/django-localflavor-it -* Japan: https://github.com/django/django-localflavor-jp -* Kuwait: https://github.com/django/django-localflavor-kw -* Lithuania: https://github.com/simukis/django-localflavor-lt -* Macedonia: https://github.com/django/django-localflavor-mk -* Mexico: https://github.com/django/django-localflavor-mx -* The Netherlands: https://github.com/django/django-localflavor-nl -* Norway: https://github.com/django/django-localflavor-no -* Peru: https://github.com/django/django-localflavor-pe -* Poland: https://github.com/django/django-localflavor-pl -* Portugal: https://github.com/django/django-localflavor-pt -* Paraguay: https://github.com/django/django-localflavor-py -* Romania: https://github.com/django/django-localflavor-ro -* Russia: https://github.com/django/django-localflavor-ru -* Slovakia: https://github.com/django/django-localflavor-sk -* Slovenia: https://github.com/django/django-localflavor-si -* South Africa: https://github.com/django/django-localflavor-za -* Spain: https://github.com/django/django-localflavor-es -* Sweden: https://github.com/django/django-localflavor-se -* Switzerland: https://github.com/django/django-localflavor-ch -* Turkey: https://github.com/django/django-localflavor-tr -* United Kingdom: https://github.com/django/django-localflavor-gb -* United States of America: https://github.com/django/django-localflavor-us -* Uruguay: https://github.com/django/django-localflavor-uy - -django.contrib.localflavor.generic -================================== - -The ``django.contrib.localflavor.generic`` package, which hasn't been removed from -Django yet, contains useful code that is not specific to one particular country -or culture. Currently, it defines date, datetime and split datetime input -fields based on those from :doc:`forms </topics/forms/index>`, but with non-US -default formats. Here's an example of how to use them:: - - from django import forms - from django.contrib.localflavor import generic - - class MyForm(forms.Form): - my_date_field = generic.forms.DateField() - -Internationalization of localflavor -=================================== - -Localflavor has its own catalog of translations, in the directory -``django/contrib/localflavor/locale``, and it's not loaded automatically like -Django's general catalog in ``django/conf/locale``. If you want localflavor's -texts to be translated, like form fields error messages, you must include -:mod:`django.contrib.localflavor` in the :setting:`INSTALLED_APPS` setting, so -the internationalization system can find the catalog, as explained in -:ref:`how-django-discovers-translations`. diff --git a/docs/ref/contrib/markup.txt b/docs/ref/contrib/markup.txt deleted file mode 100644 index 9215c64f93..0000000000 --- a/docs/ref/contrib/markup.txt +++ /dev/null @@ -1,77 +0,0 @@ -===================== -django.contrib.markup -===================== - -.. module:: django.contrib.markup - :synopsis: A collection of template filters that implement common markup languages. - -.. deprecated:: 1.5 - This module has been deprecated. - -Django provides template filters that implement the following markup -languages: - -* ``textile`` -- implements `Textile`_ -- requires `PyTextile`_ -* ``markdown`` -- implements `Markdown`_ -- requires `Python-markdown`_ (>=2.1) -* ``restructuredtext`` -- implements `reST (reStructured Text)`_ - -- requires `doc-utils`_ - -In each case, the filter expects formatted markup as a string and -returns a string representing the marked-up text. For example, the -``textile`` filter converts text that is marked-up in Textile format -to HTML. - -To activate these filters, add ``'django.contrib.markup'`` to your -:setting:`INSTALLED_APPS` setting. Once you've done that, use -``{% load markup %}`` in a template, and you'll have access to these filters. -For more documentation, read the source code in -:file:`django/contrib/markup/templatetags/markup.py`. - -.. warning:: - - The output of markup filters is marked "safe" and will not be escaped when - rendered in a template. Always be careful to sanitize your inputs and make - sure you are not leaving yourself vulnerable to cross-site scripting or - other types of attacks. - -.. _Textile: http://en.wikipedia.org/wiki/Textile_%28markup_language%29 -.. _Markdown: http://en.wikipedia.org/wiki/Markdown -.. _reST (reStructured Text): http://en.wikipedia.org/wiki/ReStructuredText -.. _PyTextile: http://loopcore.com/python-textile/ -.. _Python-markdown: http://pypi.python.org/pypi/Markdown -.. _doc-utils: http://docutils.sf.net/ - -reStructured Text ------------------ - -When using the ``restructuredtext`` markup filter you can define a -:setting:`RESTRUCTUREDTEXT_FILTER_SETTINGS` in your django settings to -override the default writer settings. See the `restructuredtext writer -settings`_ for details on what these settings are. - -.. warning:: - - reStructured Text has features that allow raw HTML to be included, and that - allow arbitrary files to be included. These can lead to XSS vulnerabilities - and leaking of private information. It is your responsibility to check the - features of this library and configure appropriately to avoid this. See the - `Deploying Docutils Securely - <http://docutils.sourceforge.net/docs/howto/security.html>`_ documentation. - -.. _restructuredtext writer settings: http://docutils.sourceforge.net/docs/user/config.html#html4css1-writer - -Markdown --------- - -The Python Markdown library supports options named "safe_mode" and -"enable_attributes". Both relate to the security of the output. To enable both -options in tandem, the markdown filter supports the "safe" argument:: - - {{ markdown_content_var|markdown:"safe" }} - -.. warning:: - - Versions of the Python-Markdown library prior to 2.1 do not support the - optional disabling of attributes. This is a security flaw. Therefore, - ``django.contrib.markup`` has dropped support for versions of - Python-Markdown < 2.1 in Django 1.5. diff --git a/docs/ref/contrib/messages.txt b/docs/ref/contrib/messages.txt index 4fa733edb5..0a376bca18 100644 --- a/docs/ref/contrib/messages.txt +++ b/docs/ref/contrib/messages.txt @@ -78,8 +78,8 @@ Django provides three built-in storage classes: :class:`~django.contrib.messages.storage.fallback.FallbackStorage` is the default storage class. If it isn't suitable to your needs, you can select -another storage class by setting `MESSAGE_STORAGE`_ to its full import path, -for example:: +another storage class by setting :setting:`MESSAGE_STORAGE` to its full import +path, for example:: MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage' @@ -87,6 +87,8 @@ To write your own storage class, subclass the ``BaseStorage`` class in ``django.contrib.messages.storage.base`` and implement the ``_get`` and ``_store`` methods. +.. _message-level: + Message levels -------------- @@ -108,7 +110,7 @@ Constant Purpose ``ERROR`` An action was **not** successful or some other failure occurred =========== ======== -The `MESSAGE_LEVEL`_ setting can be used to change the minimum recorded level +The :setting:`MESSAGE_LEVEL` setting can be used to change the minimum recorded level (or it can be `changed per request`_). Attempts to add messages of a level less than this will be ignored. @@ -136,7 +138,7 @@ Level Constant Tag ============== =========== To change the default tags for a message level (either built-in or custom), -set the `MESSAGE_TAGS`_ setting to a dictionary containing the levels +set the :setting:`MESSAGE_TAGS` setting to a dictionary containing the levels you wish to change. As this extends the default tags, you only need to provide tags for the levels you wish to override:: @@ -149,6 +151,8 @@ tags for the levels you wish to override:: Using messages in views and templates ===================================== +.. function:: add_message(request, level, message, extra_tags='', fail_silently=False) + Adding a message ---------------- @@ -166,6 +170,8 @@ used tags (which are usually represented as HTML classes for the message):: messages.warning(request, 'Your account expires in three days.') messages.error(request, 'Document deleted.') +.. _message-displaying: + Displaying messages ------------------- @@ -214,7 +220,7 @@ Level Constant Value ============== ===== If you need to identify the custom levels in your HTML or CSS, you need to -provide a mapping via the `MESSAGE_TAGS`_ setting. +provide a mapping via the :setting:`MESSAGE_TAGS` setting. .. note:: If you are creating a reusable application, it is recommended to use @@ -280,6 +286,53 @@ example:: use one of the ``add_message`` family of methods. It does not hide failures that may occur for other reasons. +Adding messages in Class Based Views +------------------------------------ + +.. versionadded:: 1.6 + +.. class:: views.SuccessMessageMixin + + Adds a success message attribute to + :class:`~django.views.generic.edit.FormView` based classes + + .. method:: get_success_message(cleaned_data) + + ``cleaned_data`` is the cleaned data from the form which is used for + string formatting + +**Example views.py**:: + + from django.contrib.messages.views import SuccessMessageMixin + from django.views.generic.edit import CreateView + from myapp.models import Author + + class AuthorCreate(SuccessMessageMixin, CreateView): + model = Author + success_url = '/success/' + success_message = "%(name)s was created successfully" + +The cleaned data from the ``form`` is available for string interpolation using +the ``%(field_name)s`` syntax. For ModelForms, if you need access to fields +from the saved ``object`` override the +:meth:`~django.contrib.messages.views.SuccessMessageMixin.get_success_message` +method. + +**Example views.py for ModelForms**:: + + from django.contrib.messages.views import SuccessMessageMixin + from django.views.generic.edit import CreateView + from myapp.models import ComplicatedModel + + class ComplicatedCreate(SuccessMessageMixin, CreateView): + model = ComplicatedModel + success_url = '/success/' + success_message = "%(calculated_field)s was created successfully" + + def get_success_message(self, cleaned_data): + return self.success_message % dict(cleaned_data, + calculated_field=self.object.calculated_field) + Expiration of messages ====================== @@ -314,80 +367,10 @@ window/tab will have its own browsing context. Settings ======== -A few :doc:`Django settings </ref/settings>` give you control over message +A few :ref:`settings<settings-messages>` give you control over message behavior: -MESSAGE_LEVEL -------------- - -Default: ``messages.INFO`` - -This sets the minimum message that will be saved in the message storage. See -`Message levels`_ above for more details. - -.. admonition:: Important - - If you override ``MESSAGE_LEVEL`` in your settings file and rely on any of - the built-in constants, you must import the constants module directly to - avoid the potential for circular imports, e.g.:: - - from django.contrib.messages import constants as message_constants - MESSAGE_LEVEL = message_constants.DEBUG - - If desired, you may specify the numeric values for the constants directly - according to the values in the above :ref:`constants table - <message-level-constants>`. - -MESSAGE_STORAGE ---------------- - -Default: ``'django.contrib.messages.storage.fallback.FallbackStorage'`` - -Controls where Django stores message data. Valid values are: - -* ``'django.contrib.messages.storage.fallback.FallbackStorage'`` -* ``'django.contrib.messages.storage.session.SessionStorage'`` -* ``'django.contrib.messages.storage.cookie.CookieStorage'`` - -See `Storage backends`_ for more details. - -MESSAGE_TAGS ------------- - -Default:: - - {messages.DEBUG: 'debug', - messages.INFO: 'info', - messages.SUCCESS: 'success', - messages.WARNING: 'warning', - messages.ERROR: 'error',} - -This sets the mapping of message level to message tag, which is typically -rendered as a CSS class in HTML. If you specify a value, it will extend -the default. This means you only have to specify those values which you need -to override. See `Displaying messages`_ above for more details. - -.. admonition:: Important - - If you override ``MESSAGE_TAGS`` in your settings file and rely on any of - the built-in constants, you must import the ``constants`` module directly to - avoid the potential for circular imports, e.g.:: - - from django.contrib.messages import constants as message_constants - MESSAGE_TAGS = {message_constants.INFO: ''} - - If desired, you may specify the numeric values for the constants directly - according to the values in the above :ref:`constants table - <message-level-constants>`. - -SESSION_COOKIE_DOMAIN ---------------------- - -Default: ``None`` - -The storage backends that use cookies -- ``CookieStorage`` and -``FallbackStorage`` -- use the value of :setting:`SESSION_COOKIE_DOMAIN` in -setting their cookies. See the :doc:`settings documentation </ref/settings>` -for more information on how this works and why you might need to set it. - -.. _Django settings: ../settings/ +* :setting:`MESSAGE_LEVEL` +* :setting:`MESSAGE_STORAGE` +* :setting:`MESSAGE_TAGS` +* :ref:`SESSION_COOKIE_DOMAIN<messages-session_cookie_domain>` diff --git a/docs/ref/contrib/redirects.txt b/docs/ref/contrib/redirects.txt index e34ba405f4..0c0cb2a3c2 100644 --- a/docs/ref/contrib/redirects.txt +++ b/docs/ref/contrib/redirects.txt @@ -13,11 +13,12 @@ Installation To install the redirects app, follow these steps: -1. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` - setting. -2. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'`` +1. Ensure that the ``django.contrib.sites`` framework + :ref:`is installed <enabling-the-sites-framework>`. +2. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` setting. +3. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'`` to your :setting:`MIDDLEWARE_CLASSES` setting. -3. Run the command :djadmin:`manage.py syncdb <syncdb>`. +4. Run the command :djadmin:`manage.py syncdb <syncdb>`. How it works ============ diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index ef6c64dc61..d37ee83378 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.txt @@ -49,6 +49,8 @@ loader can find the default templates.) Initialization ============== +.. function:: views.sitemap(request, sitemaps, section=None, template_name='sitemap.xml', mimetype='application/xml') + To activate sitemap generation on your Django site, add this line to your :doc:`URLconf </topics/http/urls>`:: @@ -213,8 +215,6 @@ Sitemap class reference .. attribute:: Sitemap.protocol - .. versionadded:: 1.4 - **Optional.** This attribute defines the protocol (``'http'`` or ``'https'``) of the @@ -242,9 +242,9 @@ The sitemap framework provides a couple convenience classes for common cases: The :class:`django.contrib.sitemaps.GenericSitemap` class allows you to create a sitemap by passing it a dictionary which has to contain at least - a :data:`queryset` entry. This queryset will be used to generate the items - of the sitemap. It may also have a :data:`date_field` entry that - specifies a date field for objects retrieved from the :data:`queryset`. + a ``queryset`` entry. This queryset will be used to generate the items + of the sitemap. It may also have a ``date_field`` entry that + specifies a date field for objects retrieved from the ``queryset``. This will be used for the :attr:`~Sitemap.lastmod` attribute in the generated sitemap. You may also pass :attr:`~Sitemap.priority` and :attr:`~Sitemap.changefreq` keyword arguments to the @@ -256,7 +256,7 @@ Example Here's an example of a :doc:`URLconf </topics/http/urls>` using both:: - from django.conf.urls import patterns, url, include + from django.conf.urls import patterns from django.contrib.sitemaps import FlatPageSitemap, GenericSitemap from blog.models import Entry @@ -283,14 +283,16 @@ Here's an example of a :doc:`URLconf </topics/http/urls>` using both:: Creating a sitemap index ======================== +.. function:: views.index(request, sitemaps, template_name='sitemap_index.xml', mimetype='application/xml', sitemap_url_name='django.contrib.sitemaps.views.sitemap') + The sitemap framework also has the ability to create a sitemap index that references individual sitemap files, one per each section defined in your -:data:`sitemaps` dictionary. The only differences in usage are: +``sitemaps`` dictionary. The only differences in usage are: * You use two views in your URLconf: :func:`django.contrib.sitemaps.views.index` and :func:`django.contrib.sitemaps.views.sitemap`. * The :func:`django.contrib.sitemaps.views.sitemap` view should take a - :data:`section` keyword argument. + ``section`` keyword argument. Here's what the relevant URLconf lines would look like for the example above:: @@ -301,15 +303,13 @@ Here's what the relevant URLconf lines would look like for the example above:: This will automatically generate a :file:`sitemap.xml` file that references both :file:`sitemap-flatpages.xml` and :file:`sitemap-blog.xml`. The -:class:`~django.contrib.sitemaps.Sitemap` classes and the :data:`sitemaps` +:class:`~django.contrib.sitemaps.Sitemap` classes and the ``sitemaps`` dict don't change at all. You should create an index file if one of your sitemaps has more than 50,000 URLs. In this case, Django will automatically paginate the sitemap, and the index will reflect that. -.. versionadded:: 1.4 - If you're not using the vanilla sitemap view -- for example, if it's wrapped with a caching decorator -- you must name your sitemap view and pass ``sitemap_url_name`` to the index view:: @@ -346,29 +346,28 @@ parameter to the ``sitemap`` and ``index`` views via the URLconf:: ) -.. versionchanged:: 1.4 - In addition, these views also return - :class:`~django.template.response.TemplateResponse` - instances which allow you to easily customize the response data before - rendering. For more details, see the - :doc:`TemplateResponse documentation </ref/template-response>`. +These views return :class:`~django.template.response.TemplateResponse` +instances which allow you to easily customize the response data before +rendering. For more details, see the :doc:`TemplateResponse documentation +</ref/template-response>`. Context variables ------------------ -When customizing the templates for the :func:`~django.contrib.sitemaps.views.index` -and :func:`~django.contrib.sitemaps.views.sitemaps` views, you can rely on the +When customizing the templates for the +:func:`~django.contrib.sitemaps.views.index` and +:func:`~django.contrib.sitemaps.views.sitemap` views, you can rely on the following context variables. Index ----- -The variable :data:`sitemaps` is a list of absolute URLs to each of the sitemaps. +The variable ``sitemaps`` is a list of absolute URLs to each of the sitemaps. Sitemap ------- -The variable :data:`urlset` is a list of URLs that should appear in the +The variable ``urlset`` is a list of URLs that should appear in the sitemap. Each URL exposes attributes as defined in the :class:`~django.contrib.sitemaps.Sitemap` class: @@ -378,8 +377,6 @@ sitemap. Each URL exposes attributes as defined in the - ``location`` - ``priority`` -.. versionadded:: 1.4 - The ``item`` attribute has been added for each URL to allow more flexible customization of the templates, such as `Google news sitemaps`_. Assuming Sitemap's :attr:`~Sitemap.items()` would return a list of items with @@ -419,14 +416,14 @@ that: :func:`django.contrib.sitemaps.ping_google()`. .. function:: ping_google - :func:`ping_google` takes an optional argument, :data:`sitemap_url`, + :func:`ping_google` takes an optional argument, ``sitemap_url``, which should be the absolute path to your site's sitemap (e.g., :file:`'/sitemap.xml'`). If this argument isn't provided, :func:`ping_google` will attempt to figure out your sitemap by performing a reverse looking in your URLconf. :func:`ping_google` raises the exception - :exc:`django.contrib.sitemaps.SitemapNotFound` if it cannot determine your + ``django.contrib.sitemaps.SitemapNotFound`` if it cannot determine your sitemap URL. .. admonition:: Register with Google first! @@ -457,8 +454,8 @@ cron script, or some other scheduled task. The function makes an HTTP request to Google's servers, so you may not want to introduce that network overhead each time you call ``save()``. -Pinging Google via `manage.py` ------------------------------- +Pinging Google via ``manage.py`` +-------------------------------- .. django-admin:: ping_google diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index 7e5448b3d3..139a9b377f 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -246,14 +246,31 @@ To do this, you can use the sites framework. A simple example:: >>> 'http://%s%s' % (Site.objects.get_current().domain, obj.get_absolute_url()) 'http://example.com/mymodel/objects/3/' +.. _enabling-the-sites-framework: -Default site and ``syncdb`` -=========================== +Enabling the sites framework +============================ + +.. versionchanged:: 1.6 + In previous versions, the sites framework was enabled by default. + +To enable the sites framework, follow these steps: + +1. Add ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` + setting. + +2. Define a :setting:`SITE_ID` setting:: + + SITE_ID = 1 + +3. Run :djadmin:`syncdb`. ``django.contrib.sites`` registers a :data:`~django.db.models.signals.post_syncdb` signal handler which creates a -default site named ``example.com`` with the domain ``example.com``. For -example, this site will be created after Django creates the test database. +default site named ``example.com`` with the domain ``example.com``. This site +will also be created after Django creates the test database. To set the +correct name and domain for your project, you can use an :doc:`initial data +fixture </howto/initial-data>`. Caching the current ``Site`` object =================================== diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index 3a74797145..806d135deb 100644 --- a/docs/ref/contrib/staticfiles.txt +++ b/docs/ref/contrib/staticfiles.txt @@ -12,115 +12,22 @@ can easily be served in production. .. seealso:: For an introduction to the static files app and some usage examples, see - :doc:`/howto/static-files`. + :doc:`/howto/static-files/index`. For guidelines on deploying static files, + see :doc:`/howto/static-files/deployment`. .. _staticfiles-settings: Settings ======== -.. highlight:: python - -.. note:: - - The following settings control the behavior of the staticfiles app. - -.. setting:: STATICFILES_DIRS - -STATICFILES_DIRS ----------------- - -Default: ``[]`` - -This setting defines the additional locations the staticfiles app will traverse -if the :class:`FileSystemFinder` finder is enabled, e.g. if you use the -:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the -static file serving view. - -This should be set to a list or tuple of strings that contain full paths to -your additional files directory(ies) e.g.:: - - STATICFILES_DIRS = ( - "/home/special.polls.com/polls/static", - "/home/polls.com/polls/static", - "/opt/webfiles/common", - ) - -Prefixes (optional) -""""""""""""""""""" - -In case you want to refer to files in one of the locations with an additional -namespace, you can **optionally** provide a prefix as ``(prefix, path)`` -tuples, e.g.:: - - STATICFILES_DIRS = ( - # ... - ("downloads", "/opt/webfiles/stats"), - ) - -Example: - -Assuming you have :setting:`STATIC_URL` set ``'/static/'``, the -:djadmin:`collectstatic` management command would collect the "stats" files -in a ``'downloads'`` subdirectory of :setting:`STATIC_ROOT`. - -This would allow you to refer to the local file -``'/opt/webfiles/stats/polls_20101022.tar.gz'`` with -``'/static/downloads/polls_20101022.tar.gz'`` in your templates, e.g.: - -.. code-block:: html+django - - <a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz"> - -.. setting:: STATICFILES_STORAGE - -STATICFILES_STORAGE -------------------- - -Default: ``'django.contrib.staticfiles.storage.StaticFilesStorage'`` - -The file storage engine to use when collecting static files with the -:djadmin:`collectstatic` management command. - -.. versionadded:: 1.4 - -A ready-to-use instance of the storage backend defined in this setting -can be found at ``django.contrib.staticfiles.storage.staticfiles_storage``. - -For an example, see :ref:`staticfiles-from-cdn`. - -.. setting:: STATICFILES_FINDERS - -STATICFILES_FINDERS -------------------- - -Default:: - - ("django.contrib.staticfiles.finders.FileSystemFinder", - "django.contrib.staticfiles.finders.AppDirectoriesFinder") +See :ref:`staticfiles settings <settings-staticfiles>` for details on the +following settings: -The list of finder backends that know how to find static files in -various locations. - -The default will find files stored in the :setting:`STATICFILES_DIRS` setting -(using :class:`django.contrib.staticfiles.finders.FileSystemFinder`) and in a -``static`` subdirectory of each app (using -:class:`django.contrib.staticfiles.finders.AppDirectoriesFinder`) - -One finder is disabled by default: -:class:`django.contrib.staticfiles.finders.DefaultStorageFinder`. If added to -your :setting:`STATICFILES_FINDERS` setting, it will look for static files in -the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE` -setting. - -.. note:: - - When using the :class:`AppDirectoriesFinder` finder, make sure your apps - can be found by staticfiles. Simply add the app to the - :setting:`INSTALLED_APPS` setting of your site. - -Static file finders are currently considered a private interface, and this -interface is thus undocumented. +* :setting:`STATIC_ROOT` +* :setting:`STATIC_URL` +* :setting:`STATICFILES_DIRS` +* :setting:`STATICFILES_STORAGE` +* :setting:`STATICFILES_FINDERS` Management Commands =================== @@ -146,8 +53,6 @@ Files are searched by using the :setting:`enabled finders :setting:`STATICFILES_DIRS` and in the ``'static'`` directory of apps specified by the :setting:`INSTALLED_APPS` setting. -.. versionadded:: 1.4 - The :djadmin:`collectstatic` management command calls the :meth:`~django.contrib.staticfiles.storage.StaticFilesStorage.post_process` method of the :setting:`STATICFILES_STORAGE` after each run and passes @@ -176,8 +81,6 @@ Some commonly used options are: .. django-admin-option:: -c .. django-admin-option:: --clear - .. versionadded:: 1.4 - Clear the existing files before trying to copy or link the original file. .. django-admin-option:: -l @@ -187,8 +90,6 @@ Some commonly used options are: .. django-admin-option:: --no-post-process - .. versionadded:: 1.4 - Don't call the :meth:`~django.contrib.staticfiles.storage.StaticFilesStorage.post_process` method of the configured :setting:`STATICFILES_STORAGE` storage backend. @@ -212,19 +113,29 @@ Searches for one or more relative paths with the enabled finders. For example:: $ python manage.py findstatic css/base.css admin/js/core.js - /home/special.polls.com/core/static/css/base.css - /home/polls.com/core/static/css/base.css - /home/polls.com/src/django/contrib/admin/media/js/core.js + Found 'css/base.css' here: + /home/special.polls.com/core/static/css/base.css + /home/polls.com/core/static/css/base.css + Found 'admin/js/core.js' here: + /home/polls.com/src/django/contrib/admin/media/js/core.js By default, all matching locations are found. To only return the first match for each relative path, use the ``--first`` option:: $ python manage.py findstatic css/base.css --first - /home/special.polls.com/core/static/css/base.css + Found 'css/base.css' here: + /home/special.polls.com/core/static/css/base.css This is a debugging aid; it'll show you exactly which static file will be collected for a given path. +By setting the :djadminopt:`--verbosity` flag to 0, you can suppress the extra +output and just get the path names:: + + $ python manage.py findstatic css/base.css --verbosity 0 + /home/special.polls.com/core/static/css/base.css + /home/polls.com/core/static/css/base.css + .. _staticfiles-runserver: runserver @@ -276,8 +187,6 @@ StaticFilesStorage .. method:: post_process(paths, **options) - .. versionadded:: 1.4 - This method is called by the :djadmin:`collectstatic` management command after each run and gets passed the local storages and paths of found files as a dictionary, as well as the command line options. @@ -291,8 +200,6 @@ CachedStaticFilesStorage .. class:: storage.CachedStaticFilesStorage - .. versionadded:: 1.4 - A subclass of the :class:`~django.contrib.staticfiles.storage.StaticFilesStorage` storage backend which caches the files it saves by appending the MD5 hash of the file's content to the filename. For example, the file @@ -370,8 +277,6 @@ static .. templatetag:: staticfiles-static -.. versionadded:: 1.4 - Uses the configured :setting:`STATICFILES_STORAGE` storage to create the full URL for the given relative path, e.g.: @@ -422,9 +327,18 @@ files: Static file development view ---------------------------- +.. currentmodule:: django.contrib.staticfiles + +The static files tools are mostly designed to help with getting static files +successfully deployed into production. This usually means a separate, +dedicated static file server, which is a lot of overhead to mess with when +developing locally. Thus, the ``staticfiles`` app ships with a +**quick and dirty helper view** that you can use to serve files locally in +development. + .. highlight:: python -.. function:: django.contrib.staticfiles.views.serve(request, path) +.. function:: views.serve(request, path) This view function serves static files in development. @@ -436,6 +350,16 @@ This view function serves static files in development. **insecure**. This is only intended for local development, and should **never be used in production**. +.. note:: + + To guess the served files' content types, this view relies on the + :py:mod:`mimetypes` module from the Python standard library, which itself + relies on the underlying platform's map files. If you find that this view + doesn't return proper content types for certain files, it is most likely + that the platform's map files need to be updated. This can be achieved, for + example, by installing or updating the ``mailcap`` package on a Red Hat + distribution, or ``mime-support`` on a Debian distribution. + This view is automatically enabled by :djadmin:`runserver` (with a :setting:`DEBUG` setting set to ``True``). To use the view with a different local development server, add the following snippet to the end of your @@ -451,9 +375,10 @@ primary URL configuration:: Note, the beginning of the pattern (``r'^static/'``) should be your :setting:`STATIC_URL` setting. -Since this is a bit finicky, there's also a helper function that'll do this for you: +Since this is a bit finicky, there's also a helper function that'll do this for +you: -.. function:: django.contrib.staticfiles.urls.staticfiles_urlpatterns() +.. function:: urls.staticfiles_urlpatterns() This will return the proper URL pattern for serving static files to your already defined pattern list. Use it like this:: @@ -464,8 +389,18 @@ already defined pattern list. Use it like this:: urlpatterns += staticfiles_urlpatterns() +This will inspect your :setting:`STATIC_URL` setting and wire up the view +to serve static files accordingly. Don't forget to set the +:setting:`STATICFILES_DIRS` setting appropriately to let +``django.contrib.staticfiles`` know where to look for files in addition to +files in app directories. + .. warning:: This helper function will only work if :setting:`DEBUG` is ``True`` and your :setting:`STATIC_URL` setting is neither empty nor a full URL such as ``http://static.example.com/``. + + That's because this view is **grossly inefficient** and probably + **insecure**. This is only intended for local development, and should + **never be used in production**. diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt index 2418dba8ef..02159c415b 100644 --- a/docs/ref/contrib/syndication.txt +++ b/docs/ref/contrib/syndication.txt @@ -77,7 +77,7 @@ latest five news items:: To connect a URL to this feed, put an instance of the Feed object in your :doc:`URLconf </topics/http/urls>`. For example:: - from django.conf.urls import patterns, url, include + from django.conf.urls import patterns from myproject.feeds import LatestEntriesFeed urlpatterns = patterns('', @@ -137,6 +137,51 @@ into those elements. See `a complex example`_ below that uses a description template. + There is also a way to pass additional information to title and description + templates, if you need to supply more than the two variables mentioned + before. You can provide your implementation of ``get_context_data`` method + in your Feed subclass. For example:: + + from mysite.models import Article + from django.contrib.syndication.views import Feed + + class ArticlesFeed(Feed): + title = "My articles" + description_template = "feeds/articles.html" + + def items(self): + return Article.objects.order_by('-pub_date')[:5] + + def get_context_data(self, **kwargs): + context = super(ArticlesFeed, self).get_context_data(**kwargs) + context['foo'] = 'bar' + return context + + And the template: + + .. code-block:: html+django + + Something about {{ foo }}: {{ obj.description }} + + This method will be called once per each item in the list returned by + ``items()`` with the following keyword arguments: + + * ``item``: the current item. For backward compatibility reasons, the name + of this context variable is ``{{ obj }}``. + + * ``obj``: the object returned by ``get_object()``. By default this is not + exposed to the templates to avoid confusion with ``{{ obj }}`` (see above), + but you can use it in your implementation of ``get_context_data()``. + + * ``site``: current site as described above. + + * ``request``: current request. + + The behavior of ``get_context_data()`` mimics that of + :ref:`generic views <adding-extra-context>` - you're supposed to call + ``super()`` to retrieve context data from parent class, add your data + and return the modified dictionary. + * To specify the contents of ``<link>``, you have two options. For each item in ``items()``, Django first tries calling the ``item_link()`` method on the @@ -321,7 +366,7 @@ Here's a full example:: And the accompanying URLconf:: - from django.conf.urls import patterns, url, include + from django.conf.urls import patterns from myproject.feeds import RssSiteNewsFeed, AtomSiteNewsFeed urlpatterns = patterns('', @@ -334,7 +379,7 @@ And the accompanying URLconf:: Feed class reference -------------------- -.. class:: django.contrib.syndication.views.Feed +.. class:: views.Feed This example illustrates all possible attributes and methods for a :class:`~django.contrib.syndication.views.Feed` class:: @@ -599,6 +644,15 @@ This example illustrates all possible attributes and methods for a item_description = 'A description of the item.' # Hard-coded description. + def get_context_data(self, **kwargs): + """ + Returns a dictionary to use as extra context if either + description_template or item_template are used. + + Default implementation preserves the old behavior + of using {'obj': item, 'site': current_site} as the context. + """ + # ITEM LINK -- One of these three is required. The framework looks for # them in this order. @@ -624,6 +678,18 @@ This example illustrates all possible attributes and methods for a Takes an item, as return by items(), and returns the item's ID. """ + # ITEM_GUID_IS_PERMALINK -- The following method is optional. If + # provided, it sets the 'isPermaLink' attribute of an item's + # GUID element. This method is used only when 'item_guid' is + # specified. + + def item_guid_is_permalink(self, obj): + """ + Takes an item, as returned by items(), and returns a boolean. + """ + + item_guid_is_permalink = False # Hard coded value + # ITEM AUTHOR NAME -- One of the following three is optional. The # framework looks for them in this order. diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 352c0f4584..395abd90dd 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -11,27 +11,73 @@ This file describes some of the features that might be relevant to Django usage. Of course, it is not intended as a replacement for server-specific documentation or reference manuals. -.. _postgresql-notes: +General notes +============= -PostgreSQL notes -================ +.. _persistent-database-connections: + +Persistent connections +---------------------- + +.. versionadded:: 1.6 + +Persistent connections avoid the overhead of re-establishing a connection to +the database in each request. By default, connections are kept open for up 10 +minutes — if not specified, :setting:`CONN_MAX_AGE` defaults to 600 seconds. + +Django 1.5 and earlier didn't have persistent connections. To restore the +legacy behavior of closing the connection at the end of every request, set +:setting:`CONN_MAX_AGE` to ``0``. + +For unlimited persistent connections, set :setting:`CONN_MAX_AGE` to ``None``. + +Connection management +~~~~~~~~~~~~~~~~~~~~~ + +Django opens a connection to the database when it first makes a database +query. It keeps this connection open and reuses it in subsequent requests. +Django closes the connection once it exceeds the maximum age defined by +:setting:`CONN_MAX_AGE` or when it isn't usable any longer. -.. versionchanged:: 1.4 +In detail, Django automatically opens a connection to the database whenever it +needs one and doesn't have one already — either because this is the first +connection, or because the previous connection was closed. -Django supports PostgreSQL 8.2 and higher. +At the beginning of each request, Django closes the connection if it has +reached its maximum age. If your database terminates idle connections after +some time, you should set :setting:`CONN_MAX_AGE` to a lower value, so that +Django doesn't attempt to use a connection that has been terminated by the +database server. (This problem may only affect very low traffic sites.) -PostgreSQL 8.2 to 8.2.4 ------------------------ +At the end of each request, Django closes the connection if it has reached its +maximum age or if it is in an unrecoverable error state. If any database +errors have occurred while processing the requests, Django checks whether the +connection still works, and closes it if it doesn't. Thus, database errors +affect at most one request; if the connection becomes unusable, the next +request gets a fresh connection. -The implementation of the population statistics aggregates ``STDDEV_POP`` and -``VAR_POP`` that shipped with PostgreSQL 8.2 to 8.2.4 are `known to be -faulty`_. Users of these releases of PostgreSQL are advised to upgrade to -`Release 8.2.5`_ or later. Django will raise a ``NotImplementedError`` if you -attempt to use the ``StdDev(sample=False)`` or ``Variance(sample=False)`` -aggregate with a database backend that falls within the affected release range. +Caveats +~~~~~~~ -.. _known to be faulty: http://archives.postgresql.org/pgsql-bugs/2007-07/msg00046.php -.. _Release 8.2.5: http://www.postgresql.org/docs/devel/static/release-8-2-5.html +Since each thread maintains its own connection, your database must support at +least as many simultaneous connections as you have worker threads. + +Sometimes a database won't be accessed by the majority of your views, for +example because it's the database of an external system, or thanks to caching. +In such cases, you should set :setting:`CONN_MAX_AGE` to a lower value, or +even ``0``, because it doesn't make sense to maintain a connection that's +unlikely to be reused. This will help keep the number of simultaneous +connections to this database small. + +The development server creates a new thread for each request it handles, +negating the effect of persistent connections. + +.. _postgresql-notes: + +PostgreSQL notes +================ + +Django supports PostgreSQL 8.4 and higher. PostgreSQL connection settings ------------------------------- @@ -44,7 +90,8 @@ Optimizing PostgreSQL's configuration Django needs the following parameters for its database connections: - ``client_encoding``: ``'UTF8'``, -- ``default_transaction_isolation``: ``'read committed'``, +- ``default_transaction_isolation``: ``'read committed'`` by default, + or the value set in the connection options (see below), - ``timezone``: ``'UTC'`` when :setting:`USE_TZ` is ``True``, value of :setting:`TIME_ZONE` otherwise. @@ -58,58 +105,57 @@ will do some additional queries to set these parameters. .. _ALTER ROLE: http://www.postgresql.org/docs/current/interactive/sql-alterrole.html -Transaction handling ---------------------- - -:doc:`By default </topics/db/transactions>`, Django runs with an open -transaction which it commits automatically when any built-in, data-altering -model function is called. The PostgreSQL backends normally operate the same as -any other Django backend in this respect. - .. _postgresql-autocommit-mode: Autocommit mode -~~~~~~~~~~~~~~~ +--------------- -If your application is particularly read-heavy and doesn't make many -database writes, the overhead of a constantly open transaction can -sometimes be noticeable. For those situations, you can configure Django -to use *"autocommit"* behavior for the connection, meaning that each database -operation will normally be in its own transaction, rather than having -the transaction extend over multiple operations. In this case, you can -still manually start a transaction if you're doing something that -requires consistency across multiple database operations. The -autocommit behavior is enabled by setting the ``autocommit`` key in -the :setting:`OPTIONS` part of your database configuration in -:setting:`DATABASES`:: +.. versionchanged:: 1.6 - 'OPTIONS': { - 'autocommit': True, +In previous versions of Django, database-level autocommit could be enabled by +setting the ``autocommit`` key in the :setting:`OPTIONS` part of your database +configuration in :setting:`DATABASES`:: + + DATABASES = { + # ... + 'OPTIONS': { + 'autocommit': True, + }, } -In this configuration, Django still ensures that :ref:`delete() -<topics-db-queries-delete>` and :ref:`update() <topics-db-queries-update>` -queries run inside a single transaction, so that either all the affected -objects are changed or none of them are. +Since Django 1.6, autocommit is turned on by default. This configuration is +ignored and can be safely removed. + +Isolation level +--------------- + +.. versionadded:: 1.6 + +Like PostgreSQL itself, Django defaults to the ``READ COMMITTED`` `isolation +level <postgresql-isolation-levels>`_. If you need a higher isolation level +such as ``REPEATABLE READ`` or ``SERIALIZABLE``, set it in the +:setting:`OPTIONS` part of your database configuration in +:setting:`DATABASES`:: + + import psycopg2.extensions -.. admonition:: This is database-level autocommit + DATABASES = { + # ... + 'OPTIONS': { + 'isolation_level': psycopg2.extensions.ISOLATION_LEVEL_SERIALIZABLE, + }, + } + +.. note:: - This functionality is not the same as the :ref:`autocommit - <topics-db-transactions-autocommit>` decorator. That decorator is - a Django-level implementation that commits automatically after - data changing operations. The feature enabled using the - :setting:`OPTIONS` option provides autocommit behavior at the - database adapter level. It commits after *every* operation. + Under higher isolation levels, your application should be prepared to + handle exceptions raised on serialization failures. This option is + designed for advanced uses. -If you are using this feature and performing an operation akin to delete or -updating that requires multiple operations, you are strongly recommended to -wrap you operations in manual transaction handling to ensure data consistency. -You should also audit your existing code for any instances of this behavior -before enabling this feature. It's faster, but it provides less automatic -protection for multi-call operations. +.. _postgresql-isolation-levels: http://www.postgresql.org/docs/current/static/transaction-iso.html Indexes for ``varchar`` and ``text`` columns -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------------- When specifying ``db_index=True`` on your model fields, Django typically outputs a single ``CREATE INDEX`` statement. However, if the database type @@ -120,7 +166,7 @@ for the column. The extra index is necessary to correctly perform lookups that use the ``LIKE`` operator in their SQL, as is done with the ``contains`` and ``startswith`` lookup types. -.. _PostgreSQL operator class: http://www.postgresql.org/docs/8.4/static/indexes-opclass.html +.. _PostgreSQL operator class: http://www.postgresql.org/docs/current/static/indexes-opclass.html .. _mysql-notes: @@ -173,18 +219,6 @@ running ``syncdb``:: 1005, "Can't create table '\\db_name\\.#sql-4a8_ab' (errno: 150)" ) -.. versionchanged:: 1.4 - -In previous versions of Django, fixtures with forward references (i.e. -relations to rows that have not yet been inserted into the database) would fail -to load when using the InnoDB storage engine. This was due to the fact that InnoDB -deviates from the SQL standard by checking foreign key constraints immediately -instead of deferring the check until the transaction is committed. This -problem has been resolved in Django 1.4. Fixture data is now loaded with foreign key -checks turned off; foreign key checks are then re-enabled when the data has -finished loading, at which point the entire table is checked for invalid foreign -key references and an `IntegrityError` is raised if any are found. - .. _storage engines: http://dev.mysql.com/doc/refman/5.5/en/storage-engines.html .. _MyISAM: http://dev.mysql.com/doc/refman/5.5/en/myisam-storage-engine.html .. _InnoDB: http://dev.mysql.com/doc/refman/5.5/en/innodb.html @@ -207,6 +241,14 @@ required for full MySQL support in Django. 1.2.1p2 or newer, then delete the ``sets.py`` file in the MySQLdb directory that was left by an earlier version. +.. note:: + There are known issues with the way MySQLdb converts date strings into + datetime objects. Specifically, date strings with value 0000-00-00 are valid for + MySQL but will be converted into None by MySQLdb. + + This means you should be careful while using loaddata/dumpdata with rows + that may have 0000-00-00 values, as they will be converted to None. + .. _MySQLdb: http://sourceforge.net/projects/mysql-python Creating your database @@ -273,9 +315,9 @@ recommended solution. Should you decide to use ``utf8_bin`` collation for some of your tables with MySQLdb 1.2.1p2 or 1.2.2, you should still use ``utf8_collation_ci_swedish`` -(the default) collation for the :class:`django.contrib.sessions.models.Session` +(the default) collation for the ``django.contrib.sessions.models.Session`` table (usually called ``django_session``) and the -:class:`django.contrib.admin.models.LogEntry` table (usually called +``django.contrib.admin.models.LogEntry`` table (usually called ``django_admin_log``). Those are the two standard tables that use :class:`~django.db.models.TextField` internally. @@ -377,8 +419,7 @@ Savepoints Both the Django ORM and MySQL (when using the InnoDB :ref:`storage engine <mysql-storage-engines>`) support database :ref:`savepoints -<topics-db-transactions-savepoints>`, but this feature wasn't available in -Django until version 1.4 when such supports was added. +<topics-db-transactions-savepoints>`. If you use the MyISAM storage engine please be aware of the fact that you will receive database-generated errors if you try to use the :ref:`savepoint-related diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 306db8439e..1d3f1b8d1d 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -25,9 +25,10 @@ copy ``django-admin.py`` to a location on your existing path or edit the Environment...``) to point to its installed location. Generally, when working on a single Django project, it's easier to use -``manage.py``. Use ``django-admin.py`` with ``DJANGO_SETTINGS_MODULE``, or the -``--settings`` command line option, if you need to switch between multiple -Django settings files. +``manage.py`` than ``django-admin.py``. If you need to switch between multiple +Django settings files, use ``django-admin.py`` with +:envvar:`DJANGO_SETTINGS_MODULE` or the :djadminopt:`--settings` command line +option. The command-line examples throughout this document use ``django-admin.py`` to be consistent, but any example can use ``manage.py`` just as well. @@ -107,12 +108,21 @@ compilemessages Compiles .po files created with ``makemessages`` to .mo files for use with the builtin gettext support. See :doc:`/topics/i18n/index`. -Use the :djadminopt:`--locale` option to specify the locale to process. -If not provided, all locales are processed. +Use the :djadminopt:`--locale` option (or its shorter version ``-l``) to +specify the locale(s) to process. If not provided, all locales are processed. Example usage:: django-admin.py compilemessages --locale=pt_BR + django-admin.py compilemessages --locale=pt_BR --locale=fr + django-admin.py compilemessages -l pt_BR + django-admin.py compilemessages -l pt_BR -l fr + django-admin.py compilemessages --locale=pt_BR,fr + django-admin.py compilemessages -l pt_BR,fr + +.. versionchanged:: 1.6 + +Added the ability to specify multiple locales. createcachetable ---------------- @@ -159,8 +169,11 @@ example, the default settings don't define :setting:`ROOT_URLCONF`, so :setting:`ROOT_URLCONF` is followed by ``"###"`` in the output of ``diffsettings``. -Note that Django's default settings live in ``django/conf/global_settings.py``, -if you're ever curious to see the full list of defaults. +The :djadminopt:`--all` option may be provided to display all settings, even +if they have Django's default value. Such settings are prefixed by ``"###"``. + +.. versionadded:: 1.6 + The :djadminopt:`--all` option was added. dumpdata <appname appname appname.Model ...> -------------------------------------------- @@ -279,9 +292,24 @@ needed. ``inspectdb`` works with PostgreSQL, MySQL and SQLite. Foreign-key detection only works in PostgreSQL and with certain types of MySQL tables. +If your plan is that your Django application(s) modify data (i.e. edit, remove +records and create new ones) in the existing database tables corresponding to +any of the introspected models then one of the manual review and edit steps +you need to perform on the resulting ``models.py`` file is to change the +Python declaration of each one of these models to specify it is a +:attr:`managed <django.db.models.Options.managed>` one. + +This servers as an explicit opt-in to give your nascent Django project write +access to your precious data on a model by model basis. + The :djadminopt:`--database` option may be used to specify the database to introspect. +.. versionchanged:: 1.6 + +The behavior by which introspected models are created as unmanaged ones is new +in Django 1.6. + loaddata <fixture fixture ...> ------------------------------ @@ -292,6 +320,8 @@ Searches for and loads the contents of the named fixture into the database. The :djadminopt:`--database` option can be used to specify the database onto which the data will be loaded. +.. django-admin-option:: --ignorenonexistent + .. versionadded:: 1.5 The :djadminopt:`--ignorenonexistent` option can be used to ignore fields that @@ -420,11 +450,24 @@ Separate multiple extensions with commas or use -e or --extension multiple times django-admin.py makemessages --locale=de --extension=html,txt --extension xml -Use the :djadminopt:`--locale` option to specify the locale to process. +Use the :djadminopt:`--locale` option (or its shorter version ``-l``) to +specify the locale(s) to process. Example usage:: django-admin.py makemessages --locale=pt_BR + django-admin.py makemessages --locale=pt_BR --locale=fr + django-admin.py makemessages -l pt_BR + django-admin.py makemessages -l pt_BR -l fr + +You can also use commas to separate multiple locales:: + + django-admin.py makemessages --locale=de,fr,pt_BR + django-admin.py makemessages -l de,fr,pt_BR + +.. versionchanged:: 1.6 + +Added the ability to specify multiple locales. .. django-admin-option:: --domain @@ -466,12 +509,18 @@ several lines in language files. .. django-admin-option:: --no-location -.. versionadded:: 1.4 - Use the ``--no-location`` option to not write '``#: filename:line``' comment lines in language files. Note that using this option makes it harder for technically skilled translators to understand each message's context. +.. django-admin-option:: --keep-pot + +.. versionadded:: 1.6 + +Use the ``--keep-pot`` option to prevent django from deleting the temporary +.pot file it generates before creating the .po file. This is useful for +debugging errors which may prevent the final language files from being created. + runfcgi [options] ----------------- @@ -482,9 +531,8 @@ supports the FastCGI protocol. See the :doc:`FastCGI deployment documentation </howto/deployment/fastcgi>` for details. Requires the Python FastCGI module from `flup`_. -.. versionadded:: 1.4 - Internally, this wraps the WSGI application object specified by the - :setting:`WSGI_APPLICATION` setting. +Internally, this wraps the WSGI application object specified by the +:setting:`WSGI_APPLICATION` setting. .. _flup: http://www.saddi.com/software/flup/ @@ -610,9 +658,8 @@ If you run this script as a user with normal privileges (recommended), you might not have access to start a port on a low port number. Low port numbers are reserved for the superuser (root). -.. versionadded:: 1.4 - This server uses the WSGI application object specified by the - :setting:`WSGI_APPLICATION` setting. +This server uses the WSGI application object specified by the +:setting:`WSGI_APPLICATION` setting. DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through security audits or performance tests. (And that's how it's gonna stay. We're in @@ -658,11 +705,8 @@ Example usage:: .. django-admin-option:: --nothreading -.. versionadded:: 1.4 - -Since version 1.4, the development server is multithreaded by default. -Use the ``--nothreading`` option to disable the use of threading in the -development server. +The development server is multithreaded by default. Use the ``--nothreading`` +option to disable the use of threading in the development server. .. django-admin-option:: --ipv6, -6 @@ -718,7 +762,8 @@ Serving static files with the development server By default, the development server doesn't serve any static files for your site (such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If -you want to configure Django to serve static media, read :doc:`/howto/static-files`. +you want to configure Django to serve static media, read +:doc:`/howto/static-files/index`. shell ----- @@ -754,6 +799,18 @@ bpython:: .. _IPython: http://ipython.scipy.org/ .. _bpython: http://bpython-interpreter.org/ +When the "plain" Python interactive interpreter starts (be it because +``--plain`` was specified or because no other interactive interface is +available) it reads the script pointed to by the :envvar:`PYTHONSTARTUP` +environment variable and the ``~/.pythonrc.py`` script. If you don't wish this +behavior you can use the ``--no-startup`` option. e.g.:: + + django-admin.py shell --plain --no-startup + +.. versionadded:: 1.6 + +The ``--no-startup`` option was added in Django 1.6. + sql <appname appname ...> ------------------------- @@ -811,6 +868,18 @@ Note that the order in which the SQL files are processed is undefined. The :djadminopt:`--database` option can be used to specify the database for which to print the SQL. +sqldropindexes <appname appname ...> +------------------------------------ + +.. django-admin:: sqldropindexes + +.. versionadded:: 1.6 + +Prints the DROP INDEX SQL statements for the given app name(s). + +The :djadminopt:`--database` option can be used to specify the database for +which to print the SQL. + sqlflush -------- @@ -856,8 +925,6 @@ startapp <appname> [destination] Creates a Django app directory structure for the given app name in the current directory or the given destination. -.. versionchanged:: 1.4 - By default the directory created contains a ``models.py`` file and other app template files. (See the `source`_ for more details.) If only the app name is given, the app directory will be created in the current working @@ -871,7 +938,8 @@ For example:: django-admin.py startapp myapp /Users/jezdez/Code/myapp -.. versionadded:: 1.4 +.. _custom-app-and-project-templates: + .. django-admin-option:: --template With the ``--template`` option, you can use a custom app template by providing @@ -893,8 +961,6 @@ zip files, you can use a URL like:: django-admin.py startapp --template=https://github.com/githubuser/django-app-template/archive/master.zip myapp -.. versionadded:: 1.4 - When Django copies the app template files, it also renders certain files through the template engine: the files whose extensions match the ``--extension`` option (``py`` by default) and the files whose names are passed @@ -905,6 +971,7 @@ with the ``--name`` option. The :class:`template context options) - ``app_name`` -- the app name as passed to the command - ``app_directory`` -- the full path of the newly created app +- ``docs_version`` -- the version of the documentation: ``'dev'`` or ``'1.x'`` .. _render_warning: @@ -929,8 +996,6 @@ startproject <projectname> [destination] Creates a Django project directory structure for the given project name in the current directory or the given destination. -.. versionchanged:: 1.4 - By default, the new directory contains ``manage.py`` and a project package (containing a ``settings.py`` and other files). See the `template source`_ for details. @@ -947,8 +1012,6 @@ For example:: django-admin.py startproject myproject /Users/jezdez/Code/myproject_repo -.. versionadded:: 1.4 - As with the :djadmin:`startapp` command, the ``--template`` option lets you specify a directory, file path or URL of a custom project template. See the :djadmin:`startapp` documentation for details of supported project template @@ -974,10 +1037,12 @@ through the template engine: the files whose extensions match the with the ``--name`` option. The :class:`template context <django.template.Context>` used is: -- Any option passed to the startproject command +- Any option passed to the startapp command (among the command's supported + options) - ``project_name`` -- the project name as passed to the command - ``project_directory`` -- the full path of the newly created project - ``secret_key`` -- a random key for the :setting:`SECRET_KEY` setting +- ``docs_version`` -- the version of the documentation: ``'dev'`` or ``'1.x'`` Please also see the :ref:`rendering warning <render_warning>` as mentioned for :djadmin:`startapp`. @@ -1036,7 +1101,7 @@ test <app or test identifier> .. django-admin:: test -Runs tests for all installed models. See :doc:`/topics/testing` for more +Runs tests for all installed models. See :doc:`/topics/testing/index` for more information. .. django-admin-option:: --failfast @@ -1044,14 +1109,12 @@ information. The ``--failfast`` option can be used to stop running tests and report the failure immediately after a test fails. -.. versionadded:: 1.4 .. django-admin-option:: --testrunner The ``--testrunner`` option can be used to control the test runner class that is used to execute tests. If this value is provided, it overrides the value provided by the :setting:`TEST_RUNNER` setting. -.. versionadded:: 1.4 .. django-admin-option:: --liveserver The ``--liveserver`` option can be used to override the default address where @@ -1072,7 +1135,7 @@ For example, this command:: ...would perform the following steps: -1. Create a test database, as described in :doc:`/topics/testing`. +1. Create a test database, as described in :ref:`the-test-database`. 2. Populate the test database with fixture data from the given fixtures. (For more on fixtures, see the documentation for ``loaddata`` above.) 3. Runs the Django development server (as in ``runserver``), pointed at @@ -1080,7 +1143,7 @@ For example, this command:: This is useful in a number of ways: -* When you're writing :doc:`unit tests </topics/testing>` of how your views +* When you're writing :doc:`unit tests </topics/testing/overview>` of how your views act with certain fixture data, you can use ``testserver`` to interact with the views in a Web browser, manually. @@ -1145,15 +1208,13 @@ changepassword .. django-admin:: changepassword This command is only available if Django's :doc:`authentication system -</topics/auth>` (``django.contrib.auth``) is installed. +</topics/auth/index>` (``django.contrib.auth``) is installed. Allows changing a user's password. It prompts you to enter twice the password of the user given as parameter. If they both match, the new password will be changed immediately. If you do not supply a user, the command will attempt to change the password whose username matches the current user. -.. versionadded:: 1.4 - Use the ``--database`` option to specify the database to query for the user. If it's not supplied, Django will use the ``default`` database. @@ -1167,7 +1228,7 @@ createsuperuser .. django-admin:: createsuperuser This command is only available if Django's :doc:`authentication system -</topics/auth>` (``django.contrib.auth``) is installed. +</topics/auth/index>` (``django.contrib.auth``) is installed. Creates a superuser account (a user who has all permissions). This is useful if you need to create an initial superuser account but did not @@ -1187,8 +1248,6 @@ using the ``--username`` and ``--email`` arguments on the command line. If either of those is not supplied, ``createsuperuser`` will prompt for it when running interactively. -.. versionadded:: 1.4 - Use the ``--database`` option to specify the database into which the superuser object will be saved. @@ -1233,7 +1292,7 @@ collectstatic ~~~~~~~~~~~~~ This command is only available if the :doc:`static files application -</howto/static-files>` (``django.contrib.staticfiles``) is installed. +</howto/static-files/index>` (``django.contrib.staticfiles``) is installed. Please refer to its :djadmin:`description <collectstatic>` in the :doc:`staticfiles </ref/contrib/staticfiles>` documentation. @@ -1242,7 +1301,7 @@ findstatic ~~~~~~~~~~ This command is only available if the :doc:`static files application -</howto/static-files>` (``django.contrib.staticfiles``) is installed. +</howto/static-files/index>` (``django.contrib.staticfiles``) is installed. Please refer to its :djadmin:`description <findstatic>` in the :doc:`staticfiles </ref/contrib/staticfiles>` documentation. @@ -1289,8 +1348,13 @@ Example usage:: django-admin.py syncdb --traceback By default, ``django-admin.py`` will show a simple error message whenever an -error occurs. If you specify ``--traceback``, ``django-admin.py`` will -output a full stack trace whenever an exception is raised. +:class:`~django.core.management.CommandError` occurs, but a full stack trace +for any other exception. If you specify ``--traceback``, ``django-admin.py`` +will also output a full stack trace when a ``CommandError`` is raised. + +.. versionchanged:: 1.6 + Previously, Django didn't show a full stack trace by default for exceptions + other than ``CommandError``. .. django-admin-option:: --verbosity @@ -1324,7 +1388,7 @@ For example, to dump data from the database with the alias ``master``:: .. django-admin-option:: --exclude Exclude a specific application from the applications whose contents is -output. For example, to specifically exclude the `auth` application from +output. For example, to specifically exclude the ``auth`` application from the output of dumpdata, you would call:: django-admin.py dumpdata --exclude=auth diff --git a/docs/ref/exceptions.txt b/docs/ref/exceptions.txt index e91a5dd85e..93bb9ed251 100644 --- a/docs/ref/exceptions.txt +++ b/docs/ref/exceptions.txt @@ -119,18 +119,43 @@ NoReverseMatch Database Exceptions =================== -Django wraps the standard database exceptions :exc:`DatabaseError` and -:exc:`IntegrityError` so that your Django code has a guaranteed common -implementation of these classes. These database exceptions are -provided in :mod:`django.db`. +Django wraps the standard database exceptions so that your Django code has a +guaranteed common implementation of these classes. These database exceptions +are provided in :mod:`django.db`. +.. exception:: Error +.. exception:: InterfaceError .. exception:: DatabaseError +.. exception:: DataError +.. exception:: OperationalError .. exception:: IntegrityError +.. exception:: InternalError +.. exception:: ProgrammingError +.. exception:: NotSupportedError The Django wrappers for database exceptions behave exactly the same as the underlying database exceptions. See :pep:`249`, the Python Database API Specification v2.0, for further information. +.. versionchanged:: 1.6 + Previous version of Django only wrapped ``DatabaseError`` and + ``IntegrityError``. + +.. exception:: models.ProtectedError + +Raised to prevent deletion of referenced objects when using +:attr:`django.db.models.PROTECT`. Subclass of :exc:`IntegrityError`. + +.. currentmodule:: django.http + +Http Exceptions +=============== + +.. exception:: UnreadablePostError + + The :exc:`UnreadablePostError` is raised when a user cancels an upload. + It is available from :mod:`django.http`. + .. currentmodule:: django.db.transaction Transaction Exceptions diff --git a/docs/ref/files/file.txt b/docs/ref/files/file.txt index ada614df45..7562f9b6bf 100644 --- a/docs/ref/files/file.txt +++ b/docs/ref/files/file.txt @@ -14,7 +14,7 @@ The ``File`` Class The :class:`File` is a thin wrapper around Python's built-in file object with some Django-specific additions. Internally, Django uses this class any time it needs to represent a file. - + :class:`File` objects have the following attributes and methods: .. attribute:: name @@ -148,7 +148,7 @@ below) will also have a couple of extra methods: Note that the ``content`` argument must be an instance of either :class:`File` or of a subclass of :class:`File`, such as - :class:`ContentFile`. + :class:`~django.core.files.base.ContentFile`. .. method:: File.delete([save=True]) diff --git a/docs/ref/files/storage.txt b/docs/ref/files/storage.txt index f9bcf9b61e..b9742514ea 100644 --- a/docs/ref/files/storage.txt +++ b/docs/ref/files/storage.txt @@ -38,7 +38,7 @@ The FileSystemStorage Class .. note:: - The :class:`FileSystemStorage.delete` method will not raise + The ``FileSystemStorage.delete()`` method will not raise raise an exception if the given file name does not exist. The Storage Class @@ -66,7 +66,7 @@ The Storage Class .. method:: delete(name) Deletes the file referenced by ``name``. If deletion is not supported - on the targest storage system this will raise ``NotImplementedError`` + on the target storage system this will raise ``NotImplementedError`` instead .. method:: exists(name) diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index dffef314b7..34ed2e493e 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -2,9 +2,7 @@ The Forms API ============= -.. module:: django.forms.forms - -.. currentmodule:: django.forms +.. module:: django.forms .. admonition:: About this document @@ -150,11 +148,11 @@ it's not necessary to include every field in your form. For example:: These values are only displayed for unbound forms, and they're not used as fallback values if a particular value isn't provided. -Note that if a :class:`~django.forms.fields.Field` defines -:attr:`~Form.initial` *and* you include ``initial`` when instantiating the -``Form``, then the latter ``initial`` will have precedence. In this example, -``initial`` is provided both at the field level and at the form instance level, -and the latter gets precedence:: +Note that if a :class:`~django.forms.Field` defines :attr:`~Form.initial` *and* +you include ``initial`` when instantiating the ``Form``, then the latter +``initial`` will have precedence. In this example, ``initial`` is provided both +at the field level and at the form instance level, and the latter gets +precedence:: >>> class CommentForm(forms.Form): ... name = forms.CharField(initial='class') @@ -163,7 +161,7 @@ and the latter gets precedence:: >>> f = CommentForm(initial={'name': 'instance'}, auto_id=False) >>> print(f) <tr><th>Name:</th><td><input type="text" name="name" value="instance" /></td></tr> - <tr><th>Url:</th><td><input type="text" name="url" /></td></tr> + <tr><th>Url:</th><td><input type="url" name="url" /></td></tr> <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> Accessing "clean" data @@ -272,7 +270,7 @@ simply ``print`` it:: >>> print(f) <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr> <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr> - <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr> + <tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" /></td></tr> <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr> If the form is bound to data, the HTML output will include that data @@ -289,7 +287,7 @@ include ``checked="checked"`` if appropriate:: >>> print(f) <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" value="hello" /></td></tr> <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" value="Hi there" /></td></tr> - <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" value="foo@example.com" /></td></tr> + <tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" value="foo@example.com" /></td></tr> <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" checked="checked" /></td></tr> This default output is a two-column HTML table, with a ``<tr>`` for each field. @@ -299,8 +297,9 @@ Notice the following: ``</table>`` tags, nor does it include the ``<form>`` and ``</form>`` tags or an ``<input type="submit">`` tag. It's your job to do that. -* Each field type has a default HTML representation. ``CharField`` and - ``EmailField`` are represented by an ``<input type="text">``. +* Each field type has a default HTML representation. ``CharField`` is + represented by an ``<input type="text">`` and ``EmailField`` by an + ``<input type="email">``. ``BooleanField`` is represented by an ``<input type="checkbox">``. Note these are merely sensible defaults; you can specify which HTML to use for a given field by using widgets, which we'll explain shortly. @@ -337,7 +336,7 @@ a form object, and each rendering method returns a Unicode object. >>> print(f.as_p()) <p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></p> <p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p> - <p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></p> + <p><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" /></p> <p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p> ``as_ul()`` @@ -352,11 +351,11 @@ a form object, and each rendering method returns a Unicode object. >>> f = ContactForm() >>> f.as_ul() - u'<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></li>\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li>\n<li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></li>\n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>' + u'<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></li>\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li>\n<li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" /></li>\n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>' >>> print(f.as_ul()) <li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></li> <li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li> - <li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></li> + <li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" /></li> <li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li> ``as_table()`` @@ -370,16 +369,19 @@ a form object, and each rendering method returns a Unicode object. >>> f = ContactForm() >>> f.as_table() - u'<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr>\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>' + u'<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" /></td></tr>\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>' >>> print(f.as_table()) <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr> <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr> - <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr> + <tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" /></td></tr> <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr> Styling required or erroneous form rows ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. attribute:: Form.error_css_class +.. attribute:: Form.required_css_class + It's pretty common to style form rows and fields that are required or have errors. For example, you might want to present required form rows in bold and highlight errors in red. @@ -430,17 +432,17 @@ tags nor ``id`` attributes:: >>> print(f.as_table()) <tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /></td></tr> <tr><th>Message:</th><td><input type="text" name="message" /></td></tr> - <tr><th>Sender:</th><td><input type="text" name="sender" /></td></tr> + <tr><th>Sender:</th><td><input type="email" name="sender" /></td></tr> <tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr> >>> print(f.as_ul()) <li>Subject: <input type="text" name="subject" maxlength="100" /></li> <li>Message: <input type="text" name="message" /></li> - <li>Sender: <input type="text" name="sender" /></li> + <li>Sender: <input type="email" name="sender" /></li> <li>Cc myself: <input type="checkbox" name="cc_myself" /></li> >>> print(f.as_p()) <p>Subject: <input type="text" name="subject" maxlength="100" /></p> <p>Message: <input type="text" name="message" /></p> - <p>Sender: <input type="text" name="sender" /></p> + <p>Sender: <input type="email" name="sender" /></p> <p>Cc myself: <input type="checkbox" name="cc_myself" /></p> If ``auto_id`` is set to ``True``, then the form output *will* include @@ -451,17 +453,17 @@ field:: >>> print(f.as_table()) <tr><th><label for="subject">Subject:</label></th><td><input id="subject" type="text" name="subject" maxlength="100" /></td></tr> <tr><th><label for="message">Message:</label></th><td><input type="text" name="message" id="message" /></td></tr> - <tr><th><label for="sender">Sender:</label></th><td><input type="text" name="sender" id="sender" /></td></tr> + <tr><th><label for="sender">Sender:</label></th><td><input type="email" name="sender" id="sender" /></td></tr> <tr><th><label for="cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="cc_myself" /></td></tr> >>> print(f.as_ul()) <li><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" /></li> <li><label for="message">Message:</label> <input type="text" name="message" id="message" /></li> - <li><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></li> + <li><label for="sender">Sender:</label> <input type="email" name="sender" id="sender" /></li> <li><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></li> >>> print(f.as_p()) <p><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" /></p> <p><label for="message">Message:</label> <input type="text" name="message" id="message" /></p> - <p><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></p> + <p><label for="sender">Sender:</label> <input type="email" name="sender" id="sender" /></p> <p><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></p> If ``auto_id`` is set to a string containing the format character ``'%s'``, @@ -474,17 +476,17 @@ attributes based on the format string. For example, for a format string >>> print(f.as_table()) <tr><th><label for="id_for_subject">Subject:</label></th><td><input id="id_for_subject" type="text" name="subject" maxlength="100" /></td></tr> <tr><th><label for="id_for_message">Message:</label></th><td><input type="text" name="message" id="id_for_message" /></td></tr> - <tr><th><label for="id_for_sender">Sender:</label></th><td><input type="text" name="sender" id="id_for_sender" /></td></tr> + <tr><th><label for="id_for_sender">Sender:</label></th><td><input type="email" name="sender" id="id_for_sender" /></td></tr> <tr><th><label for="id_for_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></td></tr> >>> print(f.as_ul()) <li><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li> <li><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></li> - <li><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></li> + <li><label for="id_for_sender">Sender:</label> <input type="email" name="sender" id="id_for_sender" /></li> <li><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li> >>> print(f.as_p()) <p><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></p> <p><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></p> - <p><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></p> + <p><label for="id_for_sender">Sender:</label> <input type="email" name="sender" id="id_for_sender" /></p> <p><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></p> If ``auto_id`` is set to any other true value -- such as a string that doesn't @@ -500,13 +502,13 @@ entirely, using the ``label_suffix`` parameter:: >>> print(f.as_ul()) <li><label for="id_for_subject">Subject</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li> <li><label for="id_for_message">Message</label> <input type="text" name="message" id="id_for_message" /></li> - <li><label for="id_for_sender">Sender</label> <input type="text" name="sender" id="id_for_sender" /></li> + <li><label for="id_for_sender">Sender</label> <input type="email" name="sender" id="id_for_sender" /></li> <li><label for="id_for_cc_myself">Cc myself</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li> >>> f = ContactForm(auto_id='id_for_%s', label_suffix=' ->') >>> print(f.as_ul()) <li><label for="id_for_subject">Subject -></label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li> <li><label for="id_for_message">Message -></label> <input type="text" name="message" id="id_for_message" /></li> - <li><label for="id_for_sender">Sender -></label> <input type="text" name="sender" id="id_for_sender" /></li> + <li><label for="id_for_sender">Sender -></label> <input type="email" name="sender" id="id_for_sender" /></li> <li><label for="id_for_cc_myself">Cc myself -></label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li> Note that the label suffix is added only if the last character of the @@ -538,19 +540,19 @@ method you're using:: >>> print(f.as_table()) <tr><th>Subject:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="subject" maxlength="100" /></td></tr> <tr><th>Message:</th><td><input type="text" name="message" value="Hi there" /></td></tr> - <tr><th>Sender:</th><td><ul class="errorlist"><li>Enter a valid email address.</li></ul><input type="text" name="sender" value="invalid email address" /></td></tr> + <tr><th>Sender:</th><td><ul class="errorlist"><li>Enter a valid email address.</li></ul><input type="email" name="sender" value="invalid email address" /></td></tr> <tr><th>Cc myself:</th><td><input checked="checked" type="checkbox" name="cc_myself" /></td></tr> >>> print(f.as_ul()) <li><ul class="errorlist"><li>This field is required.</li></ul>Subject: <input type="text" name="subject" maxlength="100" /></li> <li>Message: <input type="text" name="message" value="Hi there" /></li> - <li><ul class="errorlist"><li>Enter a valid email address.</li></ul>Sender: <input type="text" name="sender" value="invalid email address" /></li> + <li><ul class="errorlist"><li>Enter a valid email address.</li></ul>Sender: <input type="email" name="sender" value="invalid email address" /></li> <li>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></li> >>> print(f.as_p()) <p><ul class="errorlist"><li>This field is required.</li></ul></p> <p>Subject: <input type="text" name="subject" maxlength="100" /></p> <p>Message: <input type="text" name="message" value="Hi there" /></p> <p><ul class="errorlist"><li>Enter a valid email address.</li></ul></p> - <p>Sender: <input type="text" name="sender" value="invalid email address" /></p> + <p>Sender: <input type="email" name="sender" value="invalid email address" /></p> <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p> Customizing the error list format @@ -573,7 +575,7 @@ pass that in at construction time:: <p>Subject: <input type="text" name="subject" maxlength="100" /></p> <p>Message: <input type="text" name="message" value="Hi there" /></p> <div class="errorlist"><div class="error">Enter a valid email address.</div></div> - <p>Sender: <input type="text" name="sender" value="invalid email address" /></p> + <p>Sender: <input type="email" name="sender" value="invalid email address" /></p> <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p> More granular output @@ -587,24 +589,24 @@ lazy developers -- they're not the only way a form object can be displayed. Used to display HTML or access attributes for a single field of a :class:`Form` instance. - The :meth:`__unicode__` and :meth:`__str__` methods of this object displays + The ``__unicode__()`` and ``__str__()`` methods of this object displays the HTML for this field. To retrieve a single ``BoundField``, use dictionary lookup syntax on your form using the field's name as the key:: - >>> form = ContactForm() - >>> print(form['subject']) - <input id="id_subject" type="text" name="subject" maxlength="100" /> + >>> form = ContactForm() + >>> print(form['subject']) + <input id="id_subject" type="text" name="subject" maxlength="100" /> To retrieve all ``BoundField`` objects, iterate the form:: - >>> form = ContactForm() - >>> for boundfield in form: print(boundfield) - <input id="id_subject" type="text" name="subject" maxlength="100" /> - <input type="text" name="message" id="id_message" /> - <input type="text" name="sender" id="id_sender" /> - <input type="checkbox" name="cc_myself" id="id_cc_myself" /> + >>> form = ContactForm() + >>> for boundfield in form: print(boundfield) + <input id="id_subject" type="text" name="subject" maxlength="100" /> + <input type="text" name="message" id="id_message" /> + <input type="email" name="sender" id="id_sender" /> + <input type="checkbox" name="cc_myself" id="id_cc_myself" /> The field-specific output honors the form object's ``auto_id`` setting:: @@ -635,7 +637,20 @@ For a field's list of errors, access the field's ``errors`` attribute. >>> print(f['subject'].errors) >>> str(f['subject'].errors) - '' + '' + +.. method:: BoundField.label_tag(contents=None, attrs=None) + +To separately render the label tag of a form field, you can call its +``label_tag`` method:: + + >>> f = ContactForm(data) + >>> print(f['message'].label_tag()) + <label for="id_message">Message</label> + +Optionally, you can provide the ``contents`` parameter which will replace the +auto-generated label tag. An optional ``attrs`` dictionary may contain +additional attributes for the ``<label>`` tag. .. method:: BoundField.css_classes() @@ -644,17 +659,17 @@ indicate required form fields or fields that contain errors. If you're manually rendering a form, you can access these CSS classes using the ``css_classes`` method:: - >>> f = ContactForm(data) - >>> f['message'].css_classes() - 'required' + >>> f = ContactForm(data) + >>> f['message'].css_classes() + 'required' If you want to provide some additional classes in addition to the error and required classes that may be required, you can provide those classes as an argument:: - >>> f = ContactForm(data) - >>> f['message'].css_classes('foo bar') - 'foo bar required' + >>> f = ContactForm(data) + >>> f['message'].css_classes('foo bar') + 'foo bar required' .. method:: BoundField.value() @@ -715,6 +730,8 @@ form data *and* file data:: Testing for multipart forms ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: Form.is_multipart + If you're writing reusable views or templates, you may not know ahead of time whether your form is a multipart form or not. The ``is_multipart()`` method tells you whether the form requires multipart encoding for submission:: @@ -753,7 +770,7 @@ fields are ordered first:: >>> print(f.as_ul()) <li>Subject: <input type="text" name="subject" maxlength="100" /></li> <li>Message: <input type="text" name="message" /></li> - <li>Sender: <input type="text" name="sender" /></li> + <li>Sender: <input type="email" name="sender" /></li> <li>Cc myself: <input type="checkbox" name="cc_myself" /></li> <li>Priority: <input type="text" name="priority" /></li> diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 75d05c6829..c8b8044d26 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -112,7 +112,7 @@ We've specified ``auto_id=False`` to simplify the output:: >>> f = CommentForm(auto_id=False) >>> print(f) <tr><th>Your name:</th><td><input type="text" name="name" /></td></tr> - <tr><th>Your Web site:</th><td><input type="text" name="url" /></td></tr> + <tr><th>Your Web site:</th><td><input type="url" name="url" /></td></tr> <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> ``initial`` @@ -135,7 +135,7 @@ field is initialized to a particular value. For example:: >>> f = CommentForm(auto_id=False) >>> print(f) <tr><th>Name:</th><td><input type="text" name="name" value="Your name" /></td></tr> - <tr><th>Url:</th><td><input type="text" name="url" value="http://" /></td></tr> + <tr><th>Url:</th><td><input type="url" name="url" value="http://" /></td></tr> <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> You may be thinking, why not just pass a dictionary of the initial values as @@ -150,7 +150,7 @@ and the HTML output will include any validation errors:: >>> f = CommentForm(default_data, auto_id=False) >>> print(f) <tr><th>Name:</th><td><input type="text" name="name" value="Your name" /></td></tr> - <tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="text" name="url" value="http://" /></td></tr> + <tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="url" name="url" value="http://" /></td></tr> <tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" /></td></tr> This is why ``initial`` values are only displayed for unbound forms. For bound @@ -212,17 +212,17 @@ fields. We've specified ``auto_id=False`` to simplify the output:: >>> print(f.as_table()) <tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /><br /><span class="helptext">100 characters max.</span></td></tr> <tr><th>Message:</th><td><input type="text" name="message" /></td></tr> - <tr><th>Sender:</th><td><input type="text" name="sender" /><br />A valid email address, please.</td></tr> + <tr><th>Sender:</th><td><input type="email" name="sender" /><br />A valid email address, please.</td></tr> <tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr> >>> print(f.as_ul())) <li>Subject: <input type="text" name="subject" maxlength="100" /> <span class="helptext">100 characters max.</span></li> <li>Message: <input type="text" name="message" /></li> - <li>Sender: <input type="text" name="sender" /> A valid email address, please.</li> + <li>Sender: <input type="email" name="sender" /> A valid email address, please.</li> <li>Cc myself: <input type="checkbox" name="cc_myself" /></li> >>> print(f.as_p()) <p>Subject: <input type="text" name="subject" maxlength="100" /> <span class="helptext">100 characters max.</span></p> <p>Message: <input type="text" name="message" /></p> - <p>Sender: <input type="text" name="sender" /> A valid email address, please.</p> + <p>Sender: <input type="email" name="sender" /> A valid email address, please.</p> <p>Cc myself: <input type="checkbox" name="cc_myself" /></p> ``error_messages`` @@ -289,7 +289,7 @@ For each field, we describe the default widget used if you don't specify .. class:: BooleanField(**kwargs) - * Default widget: ``CheckboxInput`` + * Default widget: :class:`CheckboxInput` * Empty value: ``False`` * Normalizes to: A Python ``True`` or ``False`` value. * Validates that the value is ``True`` (e.g. the check box is checked) if @@ -309,7 +309,7 @@ For each field, we describe the default widget used if you don't specify .. class:: CharField(**kwargs) - * Default widget: ``TextInput`` + * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) * Normalizes to: A Unicode object. * Validates ``max_length`` or ``min_length``, if they are provided. @@ -329,7 +329,7 @@ For each field, we describe the default widget used if you don't specify .. class:: ChoiceField(**kwargs) - * Default widget: ``Select`` + * Default widget: :class:`Select` * Empty value: ``''`` (an empty string) * Normalizes to: A Unicode object. * Validates that the given value exists in the list of choices. @@ -355,7 +355,7 @@ For each field, we describe the default widget used if you don't specify Just like a :class:`ChoiceField`, except :class:`TypedChoiceField` takes two extra arguments, ``coerce`` and ``empty_value``. - * Default widget: ``Select`` + * Default widget: :class:`Select` * Empty value: Whatever you've given as ``empty_value`` * Normalizes to: A value of the type provided by the ``coerce`` argument. * Validates that the given value exists in the list of choices and can be @@ -382,7 +382,7 @@ For each field, we describe the default widget used if you don't specify .. class:: DateField(**kwargs) - * Default widget: ``DateInput`` + * Default widget: :class:`DateInput` * Empty value: ``None`` * Normalizes to: A Python ``datetime.date`` object. * Validates that the given value is either a ``datetime.date``, @@ -398,21 +398,21 @@ For each field, we describe the default widget used if you don't specify If no ``input_formats`` argument is provided, the default input formats are:: - '%Y-%m-%d', # '2006-10-25' + ['%Y-%m-%d', # '2006-10-25' '%m/%d/%Y', # '10/25/2006' - '%m/%d/%y', # '10/25/06' + '%m/%d/%y'] # '10/25/06' Additionally, if you specify :setting:`USE_L10N=False<USE_L10N>` in your settings, the following will also be included in the default input formats:: - '%b %d %Y', # 'Oct 25 2006' + ['%b %d %Y', # 'Oct 25 2006' '%b %d, %Y', # 'Oct 25, 2006' '%d %b %Y', # '25 Oct 2006' '%d %b, %Y', # '25 Oct, 2006' '%B %d %Y', # 'October 25 2006' '%B %d, %Y', # 'October 25, 2006' '%d %B %Y', # '25 October 2006' - '%d %B, %Y', # '25 October, 2006' + '%d %B, %Y'] # '25 October, 2006' See also :ref:`format localization <format-localization>`. @@ -421,7 +421,7 @@ For each field, we describe the default widget used if you don't specify .. class:: DateTimeField(**kwargs) - * Default widget: ``DateTimeInput`` + * Default widget: :class:`DateTimeInput` * Empty value: ``None`` * Normalizes to: A Python ``datetime.datetime`` object. * Validates that the given value is either a ``datetime.datetime``, @@ -437,7 +437,7 @@ For each field, we describe the default widget used if you don't specify If no ``input_formats`` argument is provided, the default input formats are:: - '%Y-%m-%d %H:%M:%S', # '2006-10-25 14:30:59' + ['%Y-%m-%d %H:%M:%S', # '2006-10-25 14:30:59' '%Y-%m-%d %H:%M', # '2006-10-25 14:30' '%Y-%m-%d', # '2006-10-25' '%m/%d/%Y %H:%M:%S', # '10/25/2006 14:30:59' @@ -445,7 +445,7 @@ For each field, we describe the default widget used if you don't specify '%m/%d/%Y', # '10/25/2006' '%m/%d/%y %H:%M:%S', # '10/25/06 14:30:59' '%m/%d/%y %H:%M', # '10/25/06 14:30' - '%m/%d/%y', # '10/25/06' + '%m/%d/%y'] # '10/25/06' See also :ref:`format localization <format-localization>`. @@ -454,7 +454,8 @@ For each field, we describe the default widget used if you don't specify .. class:: DecimalField(**kwargs) - * Default widget: ``TextInput`` + * Default widget: :class:`NumberInput` when :attr:`Field.localize` is + ``False``, else :class:`TextInput`. * Empty value: ``None`` * Normalizes to: A Python ``decimal``. * Validates that the given value is a decimal. Leading and trailing @@ -489,7 +490,7 @@ For each field, we describe the default widget used if you don't specify .. class:: EmailField(**kwargs) - * Default widget: ``TextInput`` + * Default widget: :class:`EmailInput` * Empty value: ``''`` (an empty string) * Normalizes to: A Unicode object. * Validates that the given value is a valid email address, using a @@ -505,7 +506,7 @@ For each field, we describe the default widget used if you don't specify .. class:: FileField(**kwargs) - * Default widget: ``ClearableFileInput`` + * Default widget: :class:`ClearableFileInput` * Empty value: ``None`` * Normalizes to: An ``UploadedFile`` object that wraps the file content and file name into a single object. @@ -533,7 +534,7 @@ For each field, we describe the default widget used if you don't specify .. class:: FilePathField(**kwargs) - * Default widget: ``Select`` + * Default widget: :class:`Select` * Empty value: ``None`` * Normalizes to: A unicode object * Validates that the selected choice exists in the list of choices. @@ -580,7 +581,8 @@ For each field, we describe the default widget used if you don't specify .. class:: FloatField(**kwargs) - * Default widget: ``TextInput`` + * Default widget: :class:`NumberInput` when :attr:`Field.localize` is + ``False``, else :class:`TextInput`. * Empty value: ``None`` * Normalizes to: A Python float. * Validates that the given value is an float. Leading and trailing @@ -596,7 +598,7 @@ For each field, we describe the default widget used if you don't specify .. class:: ImageField(**kwargs) - * Default widget: ``ClearableFileInput`` + * Default widget: :class:`ClearableFileInput` * Empty value: ``None`` * Normalizes to: An ``UploadedFile`` object that wraps the file content and file name into a single object. @@ -621,7 +623,8 @@ For each field, we describe the default widget used if you don't specify .. class:: IntegerField(**kwargs) - * Default widget: ``TextInput`` + * Default widget: :class:`NumberInput` when :attr:`Field.localize` is + ``False``, else :class:`TextInput`. * Empty value: ``None`` * Normalizes to: A Python integer or long integer. * Validates that the given value is an integer. Leading and trailing @@ -644,7 +647,7 @@ For each field, we describe the default widget used if you don't specify .. class:: IPAddressField(**kwargs) - * Default widget: ``TextInput`` + * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) * Normalizes to: A Unicode object. * Validates that the given value is a valid IPv4 address, using a regular @@ -654,13 +657,11 @@ For each field, we describe the default widget used if you don't specify ``GenericIPAddressField`` ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. versionadded:: 1.4 - .. class:: GenericIPAddressField(**kwargs) A field containing either an IPv4 or an IPv6 address. - * Default widget: ``TextInput`` + * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) * Normalizes to: A Unicode object. IPv6 addresses are normalized as described below. @@ -693,7 +694,7 @@ For each field, we describe the default widget used if you don't specify .. class:: MultipleChoiceField(**kwargs) - * Default widget: ``SelectMultiple`` + * Default widget: :class:`SelectMultiple` * Empty value: ``[]`` (an empty list) * Normalizes to: A list of Unicode objects. * Validates that every value in the given list of values exists in the list @@ -713,7 +714,7 @@ For each field, we describe the default widget used if you don't specify Just like a :class:`MultipleChoiceField`, except :class:`TypedMultipleChoiceField` takes two extra arguments, ``coerce`` and ``empty_value``. - * Default widget: ``SelectMultiple`` + * Default widget: :class:`SelectMultiple` * Empty value: Whatever you've given as ``empty_value`` * Normalizes to: A list of values of the type provided by the ``coerce`` argument. @@ -731,7 +732,7 @@ For each field, we describe the default widget used if you don't specify .. class:: NullBooleanField(**kwargs) - * Default widget: ``NullBooleanSelect`` + * Default widget: :class:`NullBooleanSelect` * Empty value: ``None`` * Normalizes to: A Python ``True``, ``False`` or ``None`` value. * Validates nothing (i.e., it never raises a ``ValidationError``). @@ -741,7 +742,7 @@ For each field, we describe the default widget used if you don't specify .. class:: RegexField(**kwargs) - * Default widget: ``TextInput`` + * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) * Normalizes to: A Unicode object. * Validates that the given value matches against a certain regular @@ -768,7 +769,7 @@ For each field, we describe the default widget used if you don't specify .. class:: SlugField(**kwargs) - * Default widget: ``TextInput`` + * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) * Normalizes to: A Unicode object. * Validates that the given value contains only letters, numbers, @@ -783,7 +784,7 @@ For each field, we describe the default widget used if you don't specify .. class:: TimeField(**kwargs) - * Default widget: ``TextInput`` + * Default widget: :class:`TextInput` * Empty value: ``None`` * Normalizes to: A Python ``datetime.time`` object. * Validates that the given value is either a ``datetime.time`` or string @@ -807,7 +808,7 @@ For each field, we describe the default widget used if you don't specify .. class:: URLField(**kwargs) - * Default widget: ``TextInput`` + * Default widget: :class:`URLInput` * Empty value: ``''`` (an empty string) * Normalizes to: A Unicode object. * Validates that the given value is a valid URL. @@ -829,7 +830,7 @@ Slightly complex built-in ``Field`` classes .. class:: ComboField(**kwargs) - * Default widget: ``TextInput`` + * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) * Normalizes to: A Unicode object. * Validates that the given value against each of the fields specified @@ -856,7 +857,7 @@ Slightly complex built-in ``Field`` classes .. class:: MultiValueField(fields=(), **kwargs) - * Default widget: ``TextInput`` + * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) * Normalizes to: the type returned by the ``compress`` method of the subclass. * Validates that the given value against each of the fields specified @@ -885,7 +886,7 @@ Slightly complex built-in ``Field`` classes .. attribute:: MultiValueField.widget Must be a subclass of :class:`django.forms.MultiWidget`. - Default value is :class:`~django.forms.widgets.TextInput`, which + Default value is :class:`~django.forms.TextInput`, which probably is not very useful in this case. .. method:: compress(data_list) @@ -902,7 +903,7 @@ Slightly complex built-in ``Field`` classes .. class:: SplitDateTimeField(**kwargs) - * Default widget: ``SplitDateTimeWidget`` + * Default widget: :class:`SplitDateTimeWidget` * Empty value: ``None`` * Normalizes to: A Python ``datetime.datetime`` object. * Validates that the given value is a ``datetime.datetime`` or string @@ -945,7 +946,7 @@ objects (in the case of ``ModelMultipleChoiceField``) into the .. class:: ModelChoiceField(**kwargs) - * Default widget: ``Select`` + * Default widget: :class:`Select` * Empty value: ``None`` * Normalizes to: A model instance. * Validates that the given id exists in the queryset. @@ -1000,7 +1001,7 @@ objects (in the case of ``ModelMultipleChoiceField``) into the .. class:: ModelMultipleChoiceField(**kwargs) - * Default widget: ``SelectMultiple`` + * Default widget: :class:`SelectMultiple` * Empty value: An empty ``QuerySet`` (self.queryset.none()) * Normalizes to: A ``QuerySet`` of model instances. * Validates that every id in the given list of values exists in the diff --git a/docs/ref/forms/formsets.txt b/docs/ref/forms/formsets.txt new file mode 100644 index 0000000000..0ab2590fce --- /dev/null +++ b/docs/ref/forms/formsets.txt @@ -0,0 +1,16 @@ +==================== +Formset Functions +==================== + +.. module:: django.forms.formsets + :synopsis: Django's functions for building formsets. + +.. function:: formset_factory(form, formset=BaseFormSet, extra=1, can_order=False, can_delete=False, max_num=None, validate_max=False) + + Returns a ``FormSet`` class for the given ``form`` class. + + See :ref:`formsets` for example usage. + + .. versionchanged:: 1.6 + + The ``validate_max`` parameter was added. diff --git a/docs/ref/forms/index.txt b/docs/ref/forms/index.txt index 866afed6dc..e6edc88ca1 100644 --- a/docs/ref/forms/index.txt +++ b/docs/ref/forms/index.txt @@ -9,5 +9,7 @@ Detailed form API reference. For introductory material, see :doc:`/topics/forms/ api fields + models + formsets widgets validation diff --git a/docs/ref/forms/models.txt b/docs/ref/forms/models.txt new file mode 100644 index 0000000000..dd0a422fd0 --- /dev/null +++ b/docs/ref/forms/models.txt @@ -0,0 +1,60 @@ +==================== +Model Form Functions +==================== + +.. module:: django.forms.models + :synopsis: Django's functions for building model forms and formsets. + +.. function:: modelform_factory(model, form=ModelForm, fields=None, exclude=None, formfield_callback=None, widgets=None) + + Returns a :class:`~django.forms.ModelForm` class for the given ``model``. + You can optionally pass a ``form`` argument to use as a starting point for + constructing the ``ModelForm``. + + ``fields`` is an optional list of field names. If provided, only the named + fields will be included in the returned fields. + + ``exclude`` is an optional list of field names. If provided, the named + fields will be excluded from the returned fields, even if they are listed + in the ``fields`` argument. + + ``widgets`` is a dictionary of model field names mapped to a widget. + + ``formfield_callback`` is a callable that takes a model field and returns + a form field. + + See :ref:`modelforms-factory` for example usage. + +.. function:: modelformset_factory(model, form=ModelForm, formfield_callback=None, formset=BaseModelFormSet, extra=1, can_delete=False, can_order=False, max_num=None, fields=None, exclude=None, widgets=None, validate_max=False) + + Returns a ``FormSet`` class for the given ``model`` class. + + Arguments ``model``, ``form``, ``fields``, ``exclude``, + ``formfield_callback`` and ``widgets`` are all passed through to + :func:`~django.forms.models.modelform_factory`. + + Arguments ``formset``, ``extra``, ``max_num``, ``can_order``, + ``can_delete`` and ``validate_max`` are passed through to + :func:`~django.forms.formsets.formset_factory`. See :ref:`formsets` for + details. + + See :ref:`model-formsets` for example usage. + + .. versionchanged:: 1.6 + + The ``widgets`` and the ``validate_max`` parameters were added. + +.. function:: inlineformset_factory(parent_model, model, form=ModelForm, formset=BaseInlineFormSet, fk_name=None, fields=None, exclude=None, extra=3, can_order=False, can_delete=True, max_num=None, formfield_callback=None, widgets=None, validate_max=False) + + Returns an ``InlineFormSet`` using :func:`modelformset_factory` with + defaults of ``formset=BaseInlineFormSet``, ``can_delete=True``, and + ``extra=3``. + + If your model has more than one :class:`~django.db.models.ForeignKey` to + the ``parent_model``, you must specify a ``fk_name``. + + See :ref:`inline-formsets` for example usage. + + .. versionchanged:: 1.6 + + The ``widgets`` and the ``validate_max`` parameters were added. diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt index e89bce748f..978c985b55 100644 --- a/docs/ref/forms/validation.txt +++ b/docs/ref/forms/validation.txt @@ -181,24 +181,20 @@ the field's ``validators`` argument, or defined on the Field class itself with the ``default_validators`` attribute. Simple validators can be used to validate values inside the field, let's have -a look at Django's ``EmailField``:: +a look at Django's ``SlugField``:: - class EmailField(CharField): - default_error_messages = { - 'invalid': _('Enter a valid email address.'), - } - default_validators = [validators.validate_email] + class SlugField(CharField): + default_validators = [validators.validate_slug] -As you can see, ``EmailField`` is just a ``CharField`` with customized error -message and a validator that validates email addresses. This can also be done -on field definition so:: +As you can see, ``SlugField`` is just a ``CharField`` with a customized +validator that validates that submitted text obeys to some character rules. +This can also be done on field definition so:: - email = forms.EmailField() + slug = forms.SlugField() is equivalent to:: - email = forms.CharField(validators=[validators.validate_email], - error_messages={'invalid': _('Enter a valid email address.')}) + slug = forms.CharField(validators=[validators.validate_slug]) Form field default cleaning diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index a0ef0731ad..514e8b3dc0 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -49,8 +49,8 @@ Setting arguments for widgets Many widgets have optional extra arguments; they can be set when defining the widget on the field. In the following example, the -:attr:`~SelectDateWidget.years` attribute is set for a -:class:`~django.forms.extras.widgets.SelectDateWidget`:: +:attr:`~django.forms.extras.widgets.SelectDateWidget.years` attribute is set +for a :class:`~django.forms.extras.widgets.SelectDateWidget`:: from django.forms.fields import DateField, ChoiceField, MultipleChoiceField from django.forms.widgets import RadioSelect, CheckboxSelectMultiple @@ -139,7 +139,7 @@ provided for each widget will be rendered exactly the same:: >>> f = CommentForm(auto_id=False) >>> f.as_table() <tr><th>Name:</th><td><input type="text" name="name" /></td></tr> - <tr><th>Url:</th><td><input type="text" name="url"/></td></tr> + <tr><th>Url:</th><td><input type="url" name="url"/></td></tr> <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> On a real Web page, you probably don't want every widget to look the same. You @@ -160,7 +160,7 @@ Django will then include the extra attributes in the rendered output: >>> f = CommentForm(auto_id=False) >>> f.as_table() <tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr> - <tr><th>Url:</th><td><input type="text" name="url"/></td></tr> + <tr><th>Url:</th><td><input type="url" name="url"/></td></tr> <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr> .. _styling-widget-classes: @@ -222,7 +222,7 @@ foundation for custom widgets. .. class:: MultiWidget(widgets, attrs=None) A widget that is composed of multiple widgets. - :class:`~django.forms.widgets.MultiWidget` works hand in hand with the + :class:`~django.forms.MultiWidget` works hand in hand with the :class:`~django.forms.MultiValueField`. :class:`MultiWidget` has one required argument: @@ -246,8 +246,8 @@ foundation for custom widgets. the combined value of the form field into the values for each widget. An example of this is how :class:`SplitDateTimeWidget` turns a - :class:`datetime` value into a list with date and time split into two - separate values:: + :class:`~datetime.datetime` value into a list with date and time split + into two separate values:: class SplitDateTimeWidget(MultiWidget): @@ -279,15 +279,10 @@ foundation for custom widgets. * A single value (e.g., a string) that is the "compressed" representation of a ``list`` of values. - If `value` is a list, output of :meth:`~MultiWidget.render` will be a - concatenation of rendered child widgets. If `value` is not a list, it - will be first processed by the method :meth:`~MultiWidget.decompress()` - to create the list and then processed as above. - - In the second case -- i.e., if the value is *not* a list -- - ``render()`` will first decompress the value into a ``list`` before - rendering it. It does so by calling the ``decompress()`` method, which - :class:`MultiWidget`'s subclasses must implement (see above). + If ``value`` is a list, the output of :meth:`~MultiWidget.render` will + be a concatenation of rendered child widgets. If ``value`` is not a + list, it will first be processed by the method + :meth:`~MultiWidget.decompress()` to create the list and then rendered. When ``render()`` executes its HTML rendering, each value in the list is rendered with the corresponding widget -- the first value is @@ -392,7 +387,38 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. .. class:: TextInput - Text input: ``<input type='text' ...>`` + Text input: ``<input type="text" ...>`` + +``NumberInput`` +~~~~~~~~~~~~~~~ + +.. class:: NumberInput + + .. versionadded:: 1.6 + + Text input: ``<input type="number" ...>`` + + Beware that not all browsers support entering localized numbers in + ``number`` input types. Django itself avoids using them for fields having + their :attr:`~django.forms.Field.localize` property to ``True``. + +``EmailInput`` +~~~~~~~~~~~~~~ + +.. class:: EmailInput + + .. versionadded:: 1.6 + + Text input: ``<input type="email" ...>`` + +``URLInput`` +~~~~~~~~~~~~ + +.. class:: URLInput + + .. versionadded:: 1.6 + + Text input: ``<input type="url" ...>`` ``PasswordInput`` ~~~~~~~~~~~~~~~~~ @@ -508,9 +534,9 @@ Selector and checkbox widgets .. attribute:: Select.choices - This attribute is optional when the field does not have a - :attr:`~Field.choices` attribute. If it does, it will override anything - you set here when the attribute is updated on the :class:`Field`. + This attribute is optional when the form field does not have a + ``choices`` attribute. If it does, it will override anything you set + here when the attribute is updated on the :class:`Field`. ``NullBooleanSelect`` ~~~~~~~~~~~~~~~~~~~~~ @@ -542,8 +568,6 @@ Selector and checkbox widgets ... </ul> - .. versionadded:: 1.4 - For more granular control over the generated markup, you can loop over the radio buttons in the template. Assuming a form ``myform`` with a field ``beatles`` that uses a ``RadioSelect`` as its widget: @@ -609,6 +633,11 @@ Selector and checkbox widgets If you decide not to loop over the radio buttons -- e.g., if your template simply includes ``{{ myform.beatles }}`` -- they'll be output in a ``<ul>`` with ``<li>`` tags, as above. +.. versionchanged:: 1.6 + +The outer ``<ul>`` container will now receive the ``id`` attribute defined on +the widget. + ``CheckboxSelectMultiple`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -624,6 +653,14 @@ Selector and checkbox widgets ... </ul> +.. versionchanged:: 1.6 + +The outer ``<ul>`` container will now receive the ``id`` attribute defined on +the widget. + +Like :class:`RadioSelect`, you can now loop over the individual checkboxes making +up the lists. See the documentation of :class:`RadioSelect` for more details. + .. _file-upload-widgets: File upload widgets @@ -662,9 +699,9 @@ Composite widgets .. attribute:: MultipleHiddenInput.choices - This attribute is optional when the field does not have a - :attr:`~Field.choices` attribute. If it does, it will override anything - you set here when the attribute is updated on the :class:`Field`. + This attribute is optional when the form field does not have a + ``choices`` attribute. If it does, it will override anything you set + here when the attribute is updated on the :class:`Field`. ``SplitDateTimeWidget`` ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/ref/index.txt b/docs/ref/index.txt index e1959d44a6..1d71b62f41 100644 --- a/docs/ref/index.txt +++ b/docs/ref/index.txt @@ -5,7 +5,6 @@ API Reference .. toctree:: :maxdepth: 1 - authbackends class-based-views/index clickjacking contrib/index @@ -26,3 +25,4 @@ API Reference urls utils validators + views diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index b542aee6e2..20bb2fb751 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -61,14 +61,16 @@ Adds a few conveniences for perfectionists: indexer would treat them as separate URLs -- so it's best practice to normalize URLs. -* Sends broken link notification emails to :setting:`MANAGERS` if - :setting:`SEND_BROKEN_LINK_EMAILS` is set to ``True``. - * Handles ETags based on the :setting:`USE_ETAGS` setting. If :setting:`USE_ETAGS` is set to ``True``, Django will calculate an ETag for each request by MD5-hashing the page content, and it'll take care of sending ``Not Modified`` responses, if appropriate. +.. class:: BrokenLinkEmailsMiddleware + +* Sends broken link notification emails to :setting:`MANAGERS` (see + :doc:`/howto/error-reporting`). + View metadata middleware ------------------------ @@ -111,7 +113,7 @@ It will NOT compress content if any of the following are true: not to be performed on certain content types. You can apply GZip compression to individual views using the -:func:`~django.views.decorators.http.gzip_page()` decorator. +:func:`~django.views.decorators.gzip.gzip_page()` decorator. Conditional GET middleware -------------------------- @@ -124,7 +126,7 @@ Conditional GET middleware Handles conditional GET operations. If the response has a ``ETag`` or ``Last-Modified`` header, and the request has ``If-None-Match`` or ``If-Modified-Since``, the response is replaced by an -:class:`~django.http.HttpNotModified`. +:class:`~django.http.HttpResponseNotModified`. Also sets the ``Date`` and ``Content-Length`` response-headers. @@ -179,8 +181,8 @@ Authentication middleware .. class:: AuthenticationMiddleware Adds the ``user`` attribute, representing the currently-logged-in user, to -every incoming ``HttpRequest`` object. See :doc:`Authentication in Web requests -</topics/auth>`. +every incoming ``HttpRequest`` object. See :ref:`Authentication in Web requests +<auth-web-requests>`. CSRF protection middleware -------------------------- @@ -203,6 +205,10 @@ Transaction middleware .. class:: TransactionMiddleware +.. versionchanged:: 1.6 + ``TransactionMiddleware`` is deprecated. The documentation of transactions + contains :ref:`upgrade instructions <transactions-upgrading-from-1.5>`. + Binds commit and rollback of the default database to the request/response phase. If a view function runs successfully, a commit is done. If it fails with an exception, a rollback is done. @@ -222,7 +228,4 @@ X-Frame-Options middleware .. class:: XFrameOptionsMiddleware -.. versionadded:: 1.4 - ``XFrameOptionsMiddleware`` was added. - Simple :doc:`clickjacking protection via the X-Frame-Options header </ref/clickjacking/>`. diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index cd1185585c..7ef251c907 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -12,8 +12,8 @@ This document contains all the gory details about all the `field options`_ and .. seealso:: - If the built-in fields don't do the trick, you can try - :mod:`django.contrib.localflavor`, which contains assorted pieces of code + If the built-in fields don't do the trick, you can try :doc:`localflavor + </topics/localflavor>`, which contains assorted pieces of code that are useful for particular countries or cultures. Also, you can easily :doc:`write your own custom model fields </howto/custom-model-fields>`. @@ -113,7 +113,7 @@ define a suitably-named constant for each value:: default=FRESHMAN) def is_upperclass(self): - return self.year_in_school in (self.JUNIOR, self.SENIOR) + return self.year_in_school in (self.JUNIOR, self.SENIOR) Though you can define a choices list outside of a model class and then refer to it, defining the choices and names for each choice inside the @@ -248,8 +248,8 @@ Alternatively you can use plain text and If ``True``, this field is the primary key for the model. -If you don't specify ``primary_key=True`` for any fields in your model, Django -will automatically add an :class:`IntegerField` to hold the primary key, so you +If you don't specify ``primary_key=True`` for any field in your model, Django +will automatically add an :class:`AutoField` to hold the primary key, so you don't need to set ``primary_key=True`` on any of your fields unless you want to override the default primary-key behavior. For more, see :ref:`automatic-primary-key-fields`. @@ -272,6 +272,9 @@ field, a :exc:`django.db.IntegrityError` will be raised by the model's This option is valid on all field types except :class:`ManyToManyField` and :class:`FileField`. +Note that when ``unique`` is ``True``, you don't need to specify +:attr:`~Field.db_index`, because ``unique`` implies the creation of an index. + ``unique_for_date`` ------------------- @@ -344,6 +347,22 @@ A 64 bit integer, much like an :class:`IntegerField` except that it is guaranteed to fit numbers from -9223372036854775808 to 9223372036854775807. The default form widget for this field is a :class:`~django.forms.TextInput`. +``BinaryField`` +------------------- + +.. class:: BinaryField([**options]) + +.. versionadded:: 1.6 + +A field to store raw binary data. It only supports ``bytes`` assignment. Be +aware that this field has limited functionality. For example, it is not possible +to filter a queryset on a ``BinaryField`` value. + +.. admonition:: Abusing ``BinaryField`` + + Although you might think about storing files in the database, consider that + it is bad design in 99% of the cases. This field is *not* a replacement for + proper :doc`static files </howto/static-files>` handling. ``BooleanField`` ---------------- @@ -358,6 +377,10 @@ The default form widget for this field is a If you need to accept :attr:`~Field.null` values then use :class:`NullBooleanField` instead. +.. versionchanged:: 1.6 + The default value of ``BooleanField`` was changed from ``False`` to + ``None`` when :attr:`Field.default` isn't defined. + ``CharField`` ------------- @@ -453,7 +476,7 @@ A fixed-precision decimal number, represented in Python by a .. attribute:: DecimalField.max_digits The maximum number of digits allowed in the number. Note that this number - must be greater than or equal to ``decimal_places``, if it exists. + must be greater than or equal to ``decimal_places``. .. attribute:: DecimalField.decimal_places @@ -509,8 +532,8 @@ Has one **required** argument: .. attribute:: FileField.upload_to A local filesystem path that will be appended to your :setting:`MEDIA_ROOT` - setting to determine the value of the :attr:`~django.core.files.File.url` - attribute. + setting to determine the value of the + :attr:`~django.db.models.fields.files.FieldFile.url` attribute. This path may contain :func:`~time.strftime` formatting, which will be replaced by the date/time of the file upload (so that uploaded files don't @@ -547,8 +570,7 @@ Also has one optional argument: Optional. A storage object, which handles the storage and retrieval of your files. See :doc:`/topics/files` for details on how to provide this object. -The default form widget for this field is a -:class:`~django.forms.widgets.FileInput`. +The default form widget for this field is a :class:`~django.forms.FileInput`. Using a :class:`FileField` or an :class:`ImageField` (see below) in a model takes a few steps: @@ -565,9 +587,9 @@ takes a few steps: 3. All that will be stored in your database is a path to the file (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the - convenience :attr:`~django.core.files.File.url` function provided by - Django. For example, if your :class:`ImageField` is called ``mug_shot``, - you can get the absolute path to your image in a template with + convenience :attr:`~django.db.models.fields.files.FieldFile.url` attribute + provided by Django. For example, if your :class:`ImageField` is called + ``mug_shot``, you can get the absolute path to your image in a template with ``{{ object.mug_shot.url }}``. For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and @@ -590,7 +612,7 @@ topic guide. saved. The uploaded file's relative URL can be obtained using the -:attr:`~django.db.models.fields.FileField.url` attribute. Internally, +:attr:`~django.db.models.fields.files.FieldFile.url` attribute. Internally, this calls the :meth:`~django.core.files.storage.Storage.url` method of the underlying :class:`~django.core.files.storage.Storage` class. @@ -615,9 +637,20 @@ can change the maximum length using the :attr:`~CharField.max_length` argument. FileField and FieldFile ~~~~~~~~~~~~~~~~~~~~~~~ -When you access a :class:`FileField` on a model, you are given an instance -of :class:`FieldFile` as a proxy for accessing the underlying file. This -class has several methods that can be used to interact with file data: +.. currentmodule:: django.db.models.fields.files + +.. class:: FieldFile + +When you access a :class:`~django.db.models.FileField` on a model, you are +given an instance of :class:`FieldFile` as a proxy for accessing the underlying +file. This class has several attributes and methods that can be used to +interact with file data: + +.. attribute:: FieldFile.url + +A read-only property to access the file's relative URL by calling the +:meth:`~django.core.files.storage.Storage.url` method of the underlying +:class:`~django.core.files.storage.Storage` class. .. method:: FieldFile.open(mode='rb') @@ -633,9 +666,9 @@ associated with this instance. This method takes a filename and file contents and passes them to the storage class for the field, then associates the stored file with the model field. -If you want to manually associate file data with :class:`FileField` -instances on your model, the ``save()`` method is used to persist that file -data. +If you want to manually associate file data with +:class:`~django.db.models.FileField` instances on your model, the ``save()`` +method is used to persist that file data. Takes two required arguments: ``name`` which is the name of the file, and ``content`` which is an object containing the file's contents. The @@ -673,6 +706,8 @@ to cleanup orphaned files, you'll need to handle it yourself (for instance, with a custom management command that can be run manually or scheduled to run periodically via e.g. cron). +.. currentmodule:: django.db.models + ``FilePathField`` ----------------- @@ -760,8 +795,7 @@ Inherits all attributes and methods from :class:`FileField`, but also validates that the uploaded object is a valid image. In addition to the special attributes that are available for :class:`FileField`, -an :class:`ImageField` also has :attr:`~django.core.files.File.height` and -:attr:`~django.core.files.File.width` attributes. +an :class:`ImageField` also has ``height`` and ``width`` attributes. To facilitate querying on those attributes, :class:`ImageField` has two extra optional arguments: @@ -805,8 +839,6 @@ for this field is a :class:`~django.forms.TextInput`. .. class:: GenericIPAddressField([protocol=both, unpack_ipv4=False, **options]) -.. versionadded:: 1.4 - An IPv4 or IPv6 address, in string format (e.g. ``192.0.2.30`` or ``2a02:42fe::4``). The default form widget for this field is a :class:`~django.forms.TextInput`. @@ -844,8 +876,8 @@ widget for this field is a :class:`~django.forms.NullBooleanSelect`. .. class:: PositiveIntegerField([**options]) -Like an :class:`IntegerField`, but must be either positive or zero (`0`). -The value `0` is accepted for backward compatibility reasons. +Like an :class:`IntegerField`, but must be either positive or zero (``0``). +The value ``0`` is accepted for backward compatibility reasons. ``PositiveSmallIntegerField`` ----------------------------- @@ -919,7 +951,7 @@ A :class:`CharField` for a URL. The default form widget for this field is a :class:`~django.forms.TextInput`. Like all :class:`CharField` subclasses, :class:`URLField` takes the optional -:attr:`~CharField.max_length`argument. If you don't specify +:attr:`~CharField.max_length` argument. If you don't specify :attr:`~CharField.max_length`, a default of 200 is used. .. versionadded:: 1.5 @@ -1039,6 +1071,21 @@ define the details of how the relation works. The field on the related object that the relation is to. By default, Django uses the primary key of the related object. +.. attribute:: ForeignKey.db_constraint + + .. versionadded:: 1.6 + + Controls whether or not a constraint should be created in the database for + this foreign key. The default is ``True``, and that's almost certainly what + you want; setting this to ``False`` can be very bad for data integrity. + That said, here are some scenarios where you might want to do this: + + * You have legacy data that is not valid. + * You're sharding your database. + + If this is set to ``False``, accessing a related object that doesn't exist + will raise its ``DoesNotExist`` exception. + .. attribute:: ForeignKey.on_delete When an object referenced by a :class:`ForeignKey` is deleted, Django by @@ -1050,26 +1097,36 @@ define the details of how the relation works. user = models.ForeignKey(User, blank=True, null=True, on_delete=models.SET_NULL) - The possible values for :attr:`on_delete` are found in - :mod:`django.db.models`: +The possible values for :attr:`~ForeignKey.on_delete` are found in +:mod:`django.db.models`: + +* .. attribute:: CASCADE + + Cascade deletes; the default. + +* .. attribute:: PROTECT + + Prevent deletion of the referenced object by raising + :exc:`~django.db.models.ProtectedError`, a subclass of + :exc:`django.db.IntegrityError`. - * :attr:`~django.db.models.CASCADE`: Cascade deletes; the default. +* .. attribute:: SET_NULL - * :attr:`~django.db.models.PROTECT`: Prevent deletion of the referenced - object by raising :exc:`django.db.models.ProtectedError`, a subclass of - :exc:`django.db.IntegrityError`. + Set the :class:`ForeignKey` null; this is only possible if + :attr:`~Field.null` is ``True``. - * :attr:`~django.db.models.SET_NULL`: Set the :class:`ForeignKey` null; - this is only possible if :attr:`null` is ``True``. +* .. attribute:: SET_DEFAULT - * :attr:`~django.db.models.SET_DEFAULT`: Set the :class:`ForeignKey` to its - default value; a default for the :class:`ForeignKey` must be set. + Set the :class:`ForeignKey` to its default value; a default for the + :class:`ForeignKey` must be set. - * :func:`~django.db.models.SET()`: Set the :class:`ForeignKey` to the value - passed to :func:`~django.db.models.SET()`, or if a callable is passed in, - the result of calling it. In most cases, passing a callable will be - necessary to avoid executing queries at the time your models.py is - imported:: +* .. function:: SET() + + Set the :class:`ForeignKey` to the value passed to + :func:`~django.db.models.SET()`, or if a callable is passed in, + the result of calling it. In most cases, passing a callable will be + necessary to avoid executing queries at the time your models.py is + imported:: def get_sentinel_user(): return User.objects.get_or_create(username='deleted')[0] @@ -1077,11 +1134,12 @@ define the details of how the relation works. class MyModel(models.Model): user = models.ForeignKey(User, on_delete=models.SET(get_sentinel_user)) - * :attr:`~django.db.models.DO_NOTHING`: Take no action. If your database - backend enforces referential integrity, this will cause an - :exc:`~django.db.IntegrityError` unless you manually add a SQL ``ON - DELETE`` constraint to the database field (perhaps using - :ref:`initial sql<initial-sql>`). +* .. attribute:: DO_NOTHING + + Take no action. If your database backend enforces referential + integrity, this will cause an :exc:`~django.db.IntegrityError` unless + you manually add a SQL ``ON DELETE`` constraint to the database field + (perhaps using :ref:`initial sql<initial-sql>`). .. _ref-manytomany: @@ -1175,6 +1233,22 @@ that control how the relationship functions. the table for the model defining the relationship and the name of the field itself. +.. attribute:: ManyToManyField.db_constraint + + .. versionadded:: 1.6 + + Controls whether or not constraints should be created in the database for + the foreign keys in the intermediary table. The default is ``True``, and + that's almost certainly what you want; setting this to ``False`` can be + very bad for data integrity. That said, here are some scenarios where you + might want to do this: + + * You have legacy data that is not valid. + * You're sharding your database. + + It is an error to pass both ``db_constraint`` and ``through``. + + .. _ref-onetoone: ``OneToOneField`` diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 6315985ba9..9f583c42ac 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -292,12 +292,13 @@ follows this algorithm: * If the object's primary key attribute is set to a value that evaluates to ``True`` (i.e., a value other than ``None`` or the empty string), Django - executes a ``SELECT`` query to determine whether a record with the given - primary key already exists. -* If the record with the given primary key does already exist, Django - executes an ``UPDATE`` query. -* If the object's primary key attribute is *not* set, or if it's set but a - record doesn't exist, Django executes an ``INSERT``. + executes an ``UPDATE``. +* If the object's primary key attribute is *not* set or if the ``UPDATE`` + didn't update anything, Django executes an ``INSERT``. + +.. versionchanged:: 1.6 + Previously Django used ``SELECT`` - if not found ``INSERT`` else ``UPDATE`` + algorithm. The old algorithm resulted in one more query in ``UPDATE`` case. The one gotcha here is that you should be careful not to specify a primary-key value explicitly when saving new objects, if you cannot guarantee the @@ -601,7 +602,7 @@ pattern, it's possible to give a name to a pattern, and then reference the name rather than the view function. A named URL pattern is defined by replacing the pattern tuple by a call to the ``url`` function):: - from django.conf.urls import patterns, url, include + from django.conf.urls import url url(r'^people/(\d+)/$', 'blog_views.generic_detail', name='people_view'), @@ -659,7 +660,7 @@ For every :class:`~django.db.models.DateField` and <django.db.models.Field.null>`, the object will have ``get_next_by_FOO()`` and ``get_previous_by_FOO()`` methods, where ``FOO`` is the name of the field. This returns the next and previous object with respect to the date field, raising -a :exc:`~django.db.DoesNotExist` exception when appropriate. +a :exc:`~django.core.exceptions.DoesNotExist` exception when appropriate. Both methods accept optional keyword arguments, which should be in the format described in :ref:`Field lookups <field-lookups>`. diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt index a577135271..5f9316bd2a 100644 --- a/docs/ref/models/options.txt +++ b/docs/ref/models/options.txt @@ -85,14 +85,15 @@ Django quotes column and table names behind the scenes. The name of an orderable field in the model, typically a :class:`DateField`, :class:`DateTimeField`, or :class:`IntegerField`. This specifies the default - field to use in your model :class:`Manager`'s :class:`~QuerySet.latest` - method. + field to use in your model :class:`Manager`'s + :meth:`~django.db.models.query.QuerySet.latest` and + :meth:`~django.db.models.query.QuerySet.earliest` methods. Example:: get_latest_by = "order_date" - See the docs for :meth:`~django.db.models.query.QuerySet.latest` for more. + See the :meth:`~django.db.models.query.QuerySet.latest` docs for more. ``managed`` ----------- @@ -100,7 +101,7 @@ Django quotes column and table names behind the scenes. .. attribute:: Options.managed Defaults to ``True``, meaning Django will create the appropriate database - tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset` + tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`flush` management command. That is, Django *manages* the database tables' lifecycles. @@ -209,10 +210,6 @@ Django quotes column and table names behind the scenes. ordering = ['-pub_date', 'author'] - .. versionchanged:: 1.4 - The Django admin honors all elements in the list/tuple; before 1.4, only - the first one was respected. - ``permissions`` --------------- @@ -262,6 +259,7 @@ Django quotes column and table names behind the scenes. an explicit :attr:`through <ManyToManyField.through>` model. ``index_together`` +------------------ .. attribute:: Options.index_together diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 40fa2d2b2f..9c1337d59f 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -378,16 +378,12 @@ query spans multiple tables, it's possible to get duplicate results when a :meth:`values()` together, be careful when ordering by fields not in the :meth:`values()` call. -.. versionadded:: 1.4 - -As of Django 1.4, you can pass positional arguments (``*fields``) in order to -specify the names of fields to which the ``DISTINCT`` should apply. This -translates to a ``SELECT DISTINCT ON`` SQL query. - -Here's the difference. For a normal ``distinct()`` call, the database compares -*each* field in each row when determining which rows are distinct. For a -``distinct()`` call with specified field names, the database will only compare -the specified field names. +You can pass positional arguments (``*fields``) in order to specify the names +of fields to which the ``DISTINCT`` should apply. This translates to a +``SELECT DISTINCT ON`` SQL query. Here's the difference. For a normal +``distinct()`` call, the database compares *each* field in each row when +determining which rows are distinct. For a ``distinct()`` call with specified +field names, the database will only compare the specified field names. .. note:: This ability to specify field names is only available in PostgreSQL. @@ -554,14 +550,19 @@ dates .. method:: dates(field, kind, order='ASC') Returns a ``DateQuerySet`` — a ``QuerySet`` that evaluates to a list of -``datetime.datetime`` objects representing all available dates of a particular -kind within the contents of the ``QuerySet``. +:class:`datetime.date` objects representing all available dates of a +particular kind within the contents of the ``QuerySet``. + +.. versionchanged:: 1.6 + ``dates`` used to return a list of :class:`datetime.datetime` objects. -``field`` should be the name of a ``DateField`` or ``DateTimeField`` of your -model. +``field`` should be the name of a ``DateField`` of your model. + +.. versionchanged:: 1.6 + ``dates`` used to accept operating on a ``DateTimeField``. ``kind`` should be either ``"year"``, ``"month"`` or ``"day"``. Each -``datetime.datetime`` object in the result list is "truncated" to the given +``datetime.date`` object in the result list is "truncated" to the given ``type``. * ``"year"`` returns a list of all distinct year values for the field. @@ -576,36 +577,77 @@ model. Examples:: >>> Entry.objects.dates('pub_date', 'year') - [datetime.datetime(2005, 1, 1)] + [datetime.date(2005, 1, 1)] >>> Entry.objects.dates('pub_date', 'month') - [datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)] + [datetime.date(2005, 2, 1), datetime.date(2005, 3, 1)] >>> Entry.objects.dates('pub_date', 'day') - [datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)] + [datetime.date(2005, 2, 20), datetime.date(2005, 3, 20)] >>> Entry.objects.dates('pub_date', 'day', order='DESC') - [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)] + [datetime.date(2005, 3, 20), datetime.date(2005, 2, 20)] >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day') - [datetime.datetime(2005, 3, 20)] + [datetime.date(2005, 3, 20)] -.. warning:: +datetimes +~~~~~~~~~ + +.. versionadded:: 1.6 + +.. method:: datetimes(field, kind, order='ASC', tzinfo=None) + +Returns a ``DateTimeQuerySet`` — a ``QuerySet`` that evaluates to a list of +:class:`datetime.datetime` objects representing all available dates of a +particular kind within the contents of the ``QuerySet``. + +``field`` should be the name of a ``DateTimeField`` of your model. + +``kind`` should be either ``"year"``, ``"month"``, ``"day"``, ``"hour"``, +``"minute"`` or ``"second"``. Each ``datetime.datetime`` object in the result +list is "truncated" to the given ``type``. + +``order``, which defaults to ``'ASC'``, should be either ``'ASC'`` or +``'DESC'``. This specifies how to order the results. + +``tzinfo`` defines the time zone to which datetimes are converted prior to +truncation. Indeed, a given datetime has different representations depending +on the time zone in use. This parameter must be a :class:`datetime.tzinfo` +object. If it's ``None``, Django uses the :ref:`current time zone +<default-current-time-zone>`. It has no effect when :setting:`USE_TZ` is +``False``. + +.. _database-time-zone-definitions: + +.. note:: + + This function performs time zone conversions directly in the database. + As a consequence, your database must be able to interpret the value of + ``tzinfo.tzname(None)``. This translates into the following requirements: + + - SQLite: install pytz_ — conversions are actually performed in Python. + - PostgreSQL: no requirements (see `Time Zones`_). + - Oracle: no requirements (see `Choosing a Time Zone File`_). + - MySQL: load the time zone tables with `mysql_tzinfo_to_sql`_. - When :doc:`time zone support </topics/i18n/timezones>` is enabled, Django - uses UTC in the database connection, which means the aggregation is - performed in UTC. This is a known limitation of the current implementation. + .. _pytz: http://pytz.sourceforge.net/ + .. _Time Zones: http://www.postgresql.org/docs/current/static/datatype-datetime.html#DATATYPE-TIMEZONES + .. _Choosing a Time Zone File: http://docs.oracle.com/cd/B19306_01/server.102/b14225/ch4datetime.htm#i1006667 + .. _mysql_tzinfo_to_sql: http://dev.mysql.com/doc/refman/5.5/en/mysql-tzinfo-to-sql.html none ~~~~ .. method:: none() -Returns an ``EmptyQuerySet`` — a ``QuerySet`` subclass that always evaluates to -an empty list. This can be used in cases where you know that you should return -an empty result set and your caller is expecting a ``QuerySet`` object (instead -of returning an empty list, for example.) +Calling none() will create a queryset that never returns any objects and no +query will be executed when accessing the results. A qs.none() queryset +is an instance of ``EmptyQuerySet``. Examples:: >>> Entry.objects.none() [] + >>> from django.db.models.query import EmptyQuerySet + >>> isinstance(Entry.objects.none(), EmptyQuerySet) + True all ~~~ @@ -740,8 +782,6 @@ prefetch_related .. method:: prefetch_related(*lookups) -.. versionadded:: 1.4 - Returns a ``QuerySet`` that will automatically retrieve, in a single batch, related objects for each of the specified lookups. @@ -1112,9 +1152,9 @@ one, doing so will result in an error. .. note:: - When calling :meth:`~Model.save()` for instances with deferred fields, - only the loaded fields will be saved. See :meth:`~Model.save()` for more - details. + When calling :meth:`~django.db.models.Model.save()` for instances with + deferred fields, only the loaded fields will be saved. See + :meth:`~django.db.models.Model.save()` for more details. only @@ -1164,9 +1204,9 @@ using :meth:`select_related` is an error as well. .. note:: - When calling :meth:`~Model.save()` for instances with deferred fields, - only the loaded fields will be saved. See :meth:`~Model.save()` for more - details. + When calling :meth:`~django.db.models.Model.save()` for instances with + deferred fields, only the loaded fields will be saved. See + :meth:`~django.db.models.Model.save()` for more details. using ~~~~~ @@ -1191,8 +1231,6 @@ select_for_update .. method:: select_for_update(nowait=False) -.. versionadded:: 1.4 - Returns a queryset that will lock rows until the end of the transaction, generating a ``SELECT ... FOR UPDATE`` SQL statement on supported databases. @@ -1211,11 +1249,6 @@ make the call non-blocking. If a conflicting lock is already acquired by another transaction, :exc:`~django.db.DatabaseError` will be raised when the queryset is evaluated. -Note that using ``select_for_update()`` will cause the current transaction to be -considered dirty, if under transaction management. This is to ensure that -Django issues a ``COMMIT`` or ``ROLLBACK``, releasing any locks held by the -``SELECT FOR UPDATE``. - Currently, the ``postgresql_psycopg2``, ``oracle``, and ``mysql`` database backends support ``select_for_update()``. However, MySQL has no support for the ``nowait`` argument. Obviously, users of external third-party backends should @@ -1248,7 +1281,7 @@ the format described in `Field lookups`_. ``get()`` raises :exc:`~django.core.exceptions.MultipleObjectsReturned` if more than one object was found. The -:exc:`~django.core.excpetions.MultipleObjectsReturned` exception is an +:exc:`~django.core.exceptions.MultipleObjectsReturned` exception is an attribute of the model class. ``get()`` raises a :exc:`~django.core.exceptions.DoesNotExist` exception if an @@ -1368,8 +1401,6 @@ bulk_create .. method:: bulk_create(objs, batch_size=None) -.. versionadded:: 1.4 - This method inserts the provided list of objects into the database in an efficient manner (generally only 1 query, no matter how many objects there are):: @@ -1485,14 +1516,25 @@ This example returns the latest ``Entry`` in the table, according to the If your model's :ref:`Meta <meta-options>` specifies :attr:`~django.db.models.Options.get_latest_by`, you can leave off the -``field_name`` argument to ``latest()``. Django will use the field specified -in :attr:`~django.db.models.Options.get_latest_by` by default. +``field_name`` argument to ``earliest()`` or ``latest()``. Django will use the +field specified in :attr:`~django.db.models.Options.get_latest_by` by default. -Like :meth:`get()`, ``latest()`` raises -:exc:`~django.core.exceptions.DoesNotExist` if there is no object with the given -parameters. +Like :meth:`get()`, ``earliest()`` and ``latest()`` raise +:exc:`~django.core.exceptions.DoesNotExist` if there is no object with the +given parameters. + +Note that ``earliest()`` and ``latest()`` exist purely for convenience and +readability. + +earliest +~~~~~~~~ + +.. method:: earliest(field_name=None) + +.. versionadded:: 1.6 -Note ``latest()`` exists purely for convenience and readability. +Works otherwise like :meth:`~django.db.models.query.QuerySet.latest` except +the direction is changed. aggregate ~~~~~~~~~ @@ -1544,32 +1586,32 @@ The most efficient method of finding whether a model with a unique field (e.g. ``primary_key``) is a member of a :class:`.QuerySet` is:: entry = Entry.objects.get(pk=123) - if some_query_set.filter(pk=entry.pk).exists(): + if some_queryset.filter(pk=entry.pk).exists(): print("Entry contained in queryset") Which will be faster than the following which requires evaluating and iterating through the entire queryset:: - if entry in some_query_set: + if entry in some_queryset: print("Entry contained in QuerySet") And to find whether a queryset contains any items:: - if some_query_set.exists(): - print("There is at least one object in some_query_set") + if some_queryset.exists(): + print("There is at least one object in some_queryset") Which will be faster than:: - if some_query_set: - print("There is at least one object in some_query_set") + if some_queryset: + print("There is at least one object in some_queryset") ... but not by a large degree (hence needing a large queryset for efficiency gains). -Additionally, if a ``some_query_set`` has not yet been evaluated, but you know -that it will be at some point, then using ``some_query_set.exists()`` will do +Additionally, if a ``some_queryset`` has not yet been evaluated, but you know +that it will be at some point, then using ``some_queryset.exists()`` will do more overall work (one query for the existence check plus an extra one to later -retrieve the results) than simply using ``bool(some_query_set)``, which +retrieve the results) than simply using ``bool(some_queryset)``, which retrieves the results and then checks if any were returned. update @@ -1637,7 +1679,7 @@ Finally, realize that ``update()`` does an update at the SQL level and, thus, does not call any ``save()`` methods on your models, nor does it emit the :attr:`~django.db.models.signals.pre_save` or :attr:`~django.db.models.signals.post_save` signals (which are a consequence of -calling :meth:`Model.save() <~django.db.models.Model.save()>`). If you want to +calling :meth:`Model.save() <django.db.models.Model.save>`). If you want to update a bunch of records for a model that has a custom :meth:`~django.db.models.Model.save()` method, loop over them and call :meth:`~django.db.models.Model.save()`, like this:: @@ -2017,7 +2059,7 @@ numbers and even characters. year ~~~~ -For date/datetime fields, exact year match. Takes a four-digit year. +For date and datetime fields, an exact year match. Takes an integer year. Example:: @@ -2029,6 +2071,9 @@ SQL equivalent:: (The exact SQL syntax varies for each database engine.) +When :setting:`USE_TZ` is ``True``, datetime fields are converted to the +current time zone before filtering. + .. fieldlookup:: month month @@ -2047,12 +2092,15 @@ SQL equivalent:: (The exact SQL syntax varies for each database engine.) +When :setting:`USE_TZ` is ``True``, datetime fields are converted to the +current time zone before filtering. + .. fieldlookup:: day day ~~~ -For date and datetime fields, an exact day match. +For date and datetime fields, an exact day match. Takes an integer day. Example:: @@ -2067,6 +2115,9 @@ SQL equivalent:: Note this will match any record with a pub_date on the third day of the month, such as January 3, July 3, etc. +When :setting:`USE_TZ` is ``True``, datetime fields are converted to the +current time zone before filtering. + .. fieldlookup:: week_day week_day @@ -2088,12 +2139,74 @@ Note this will match any record with a ``pub_date`` that falls on a Monday (day 2 of the week), regardless of the month or year in which it occurs. Week days are indexed with day 1 being Sunday and day 7 being Saturday. -.. warning:: +When :setting:`USE_TZ` is ``True``, datetime fields are converted to the +current time zone before filtering. + +.. fieldlookup:: hour + +hour +~~~~ + +.. versionadded:: 1.6 + +For datetime fields, an exact hour match. Takes an integer between 0 and 23. - When :doc:`time zone support </topics/i18n/timezones>` is enabled, Django - uses UTC in the database connection, which means the ``year``, ``month``, - ``day`` and ``week_day`` lookups are performed in UTC. This is a known - limitation of the current implementation. +Example:: + + Event.objects.filter(timestamp__hour=23) + +SQL equivalent:: + + SELECT ... WHERE EXTRACT('hour' FROM timestamp) = '23'; + +(The exact SQL syntax varies for each database engine.) + +When :setting:`USE_TZ` is ``True``, values are converted to the current time +zone before filtering. + +.. fieldlookup:: minute + +minute +~~~~~~ + +.. versionadded:: 1.6 + +For datetime fields, an exact minute match. Takes an integer between 0 and 59. + +Example:: + + Event.objects.filter(timestamp__minute=29) + +SQL equivalent:: + + SELECT ... WHERE EXTRACT('minute' FROM timestamp) = '29'; + +(The exact SQL syntax varies for each database engine.) + +When :setting:`USE_TZ` is ``True``, values are converted to the current time +zone before filtering. + +.. fieldlookup:: second + +second +~~~~~~ + +.. versionadded:: 1.6 + +For datetime fields, an exact second match. Takes an integer between 0 and 59. + +Example:: + + Event.objects.filter(timestamp__second=31) + +SQL equivalent:: + + SELECT ... WHERE EXTRACT('second' FROM timestamp) = '31'; + +(The exact SQL syntax varies for each database engine.) + +When :setting:`USE_TZ` is ``True``, values are converted to the current time +zone before filtering. .. fieldlookup:: isnull @@ -2196,6 +2309,14 @@ Django provides the following aggregation functions in the aggregate functions, see :doc:`the topic guide on aggregation </topics/db/aggregation>`. +.. warning:: + + SQLite can't handle aggregation on date/time fields out of the box. + This is because there are no native date/time fields in SQLite and Django + currently emulates these features using a text field. Attempts to use + aggregation on date/time fields in SQLite will raise + ``NotImplementedError``. + Avg ~~~ diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt index 37986ec08d..c923961a19 100644 --- a/docs/ref/models/relations.txt +++ b/docs/ref/models/relations.txt @@ -82,14 +82,13 @@ Related objects reference >>> e = Entry.objects.get(id=234) >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b. - In order to prevent database inconsistency, this method only exists on - :class:`~django.db.models.ForeignKey` objects where ``null=True``. If - the related field can't be set to ``None`` (``NULL``), then an object - can't be removed from a relation without being added to another. In the - above example, removing ``e`` from ``b.entry_set()`` is equivalent to - doing ``e.blog = None``, and because the ``blog`` - :class:`~django.db.models.ForeignKey` doesn't have ``null=True``, this - is invalid. + For :class:`~django.db.models.ForeignKey` objects, this method only + exists if ``null=True``. If the related field can't be set to ``None`` + (``NULL``), then an object can't be removed from a relation without + being added to another. In the above example, removing ``e`` from + ``b.entry_set()`` is equivalent to doing ``e.blog = None``, and because + the ``blog`` :class:`~django.db.models.ForeignKey` doesn't have + ``null=True``, this is invalid. .. method:: clear() diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index c3ba99168d..0f62741c5d 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -34,11 +34,6 @@ All attributes should be considered read-only, unless stated otherwise below. .. attribute:: HttpRequest.body - .. versionchanged:: 1.4 - - Before Django 1.4, ``HttpRequest.body`` was named - ``HttpRequest.raw_post_data``. - The raw HTTP request body as a byte string. This is useful for processing data in different ways than conventional HTML forms: binary images, XML payload etc. For processing conventional form data, use ``HttpRequest.POST``. @@ -55,12 +50,12 @@ All attributes should be considered read-only, unless stated otherwise below. .. attribute:: HttpRequest.path_info - Under some Web server configurations, the portion of the URL after the host - name is split up into a script prefix portion and a path info portion. - The ``path_info`` attribute always contains the path info portion of the - path, no matter what Web server is being used. Using this instead of - attr:`~HttpRequest.path` can make your code much easier to move between test - and deployment servers. + Under some Web server configurations, the portion of the URL after the + host name is split up into a script prefix portion and a path info + portion. The ``path_info`` attribute always contains the path info portion + of the path, no matter what Web server is being used. Using this instead + of :attr:`~HttpRequest.path` can make your code easier to move between + test and deployment servers. For example, if the ``WSGIScriptAlias`` for your application is set to ``"/minfo"``, then ``path`` might be ``"/minfo/music/bands/the_beatles/"`` @@ -181,7 +176,7 @@ All attributes should be considered read-only, unless stated otherwise below. ``user`` is only available if your Django installation has the ``AuthenticationMiddleware`` activated. For more, see - :doc:`/topics/auth`. + :doc:`/topics/auth/index`. .. attribute:: HttpRequest.session @@ -267,10 +262,8 @@ Methods .. method:: HttpRequest.get_signed_cookie(key, default=RAISE_ERROR, salt='', max_age=None) - .. versionadded:: 1.4 - Returns a cookie value for a signed cookie, or raises a - :class:`~django.core.signing.BadSignature` exception if the signature is + ``django.core.signing.BadSignature`` exception if the signature is no longer valid. If you provide the ``default`` argument the exception will be suppressed and that default value will be returned instead. @@ -478,9 +471,6 @@ In addition, ``QueryDict`` has the following methods: It's guaranteed to return a list of some sort unless the default value was no list. - .. versionchanged:: 1.4 - The ``default`` parameter was added. - .. method:: QueryDict.setlist(key, list_) Sets the given key to ``list_`` (unlike ``__setitem__()``). @@ -505,8 +495,6 @@ In addition, ``QueryDict`` has the following methods: .. method:: QueryDict.dict() - .. versionadded:: 1.4 - Returns ``dict`` representation of ``QueryDict``. For every (key, list) pair in ``QueryDict``, ``dict`` will have (key, item), where item is one element of the list, using same logic as :meth:`QueryDict.__getitem__()`:: @@ -708,9 +696,7 @@ Methods .. _HTTPOnly: https://www.owasp.org/index.php/HTTPOnly -.. method:: HttpResponse.set_signed_cookie(key, value='', salt='', max_age=None, expires=None, path='/', domain=None, secure=None, httponly=True) - - .. versionadded:: 1.4 +.. method:: HttpResponse.set_signed_cookie(key, value, salt='', max_age=None, expires=None, path='/', domain=None, secure=None, httponly=True) Like :meth:`~HttpResponse.set_cookie()`, but :doc:`cryptographic signing </topics/signing>` the cookie before setting @@ -760,6 +746,13 @@ types of HTTP responses. Like ``HttpResponse``, these subclasses live in domain (e.g. ``'/search/'``). See :class:`HttpResponse` for other optional constructor arguments. Note that this returns an HTTP status code 302. + .. attribute:: HttpResponseRedirect.url + + .. versionadded:: 1.6 + + This read-only attribute represents the URL the response will redirect + to (equivalent to the ``Location`` response header). + .. class:: HttpResponsePermanentRedirect Like :class:`HttpResponseRedirect`, but it returns a permanent redirect @@ -804,6 +797,8 @@ types of HTTP responses. Like ``HttpResponse``, these subclasses live in :class:`~django.template.response.SimpleTemplateResponse`, and the ``render`` method must itself return a valid response object. +.. _httpresponse-streaming: + StreamingHttpResponse objects ============================= @@ -819,8 +814,8 @@ generating large CSV files. .. admonition:: Performance considerations Django is designed for short-lived requests. Streaming responses will tie - a worker process and keep a database connection idle in transaction for - the entire duration of the response. This may result in poor performance. + a worker process for the entire duration of the response. This may result + in poor performance. Generally speaking, you should perform expensive tasks outside of the request-response cycle, rather than resorting to a streamed response. diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index daa4ee9a46..1fc9d2ff92 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -13,11 +13,12 @@ Settings and :setting:`TEMPLATE_CONTEXT_PROCESSORS`. Make sure you keep the components required by the features of Django you wish to use. -Available settings -================== +Core settings +============= -Here's a full list of all available settings, in alphabetical order, and their -default values. +Here's a list of settings available in Django core and their default values. +Settings provided by contrib apps are listed below, followed by a topical index +of the core settings. .. setting:: ABSOLUTE_URL_OVERRIDES @@ -38,19 +39,6 @@ a model object and return its URL. This is a way of overriding Note that the model name used in this setting should be all lower-case, regardless of the case of the actual model class name. -.. setting:: ADMIN_FOR - -ADMIN_FOR ---------- - -Default: ``()`` (Empty tuple) - -Used for admin-site settings modules, this should be a tuple of settings -modules (in the format ``'foo.bar.baz'``) for which this site is an admin. - -The admin site uses this in its automatically-introspected documentation of -models, views and template tags. - .. setting:: ADMINS ADMINS @@ -68,6 +56,42 @@ of (Full name, email address). Example:: Note that Django will email *all* of these people whenever an error happens. See :doc:`/howto/error-reporting` for more information. +.. setting:: ALLOWED_HOSTS + +ALLOWED_HOSTS +------------- + +Default: ``[]`` (Empty list) + +A list of strings representing the host/domain names that this Django site can +serve. This is a security measure to prevent an attacker from poisoning caches +and password reset emails with links to malicious hosts by submitting requests +with a fake HTTP ``Host`` header, which is possible even under many +seemingly-safe webserver configurations. + +Values in this list can be fully qualified names (e.g. ``'www.example.com'``), +in which case they will be matched against the request's ``Host`` header +exactly (case-insensitive, not including port). A value beginning with a period +can be used as a subdomain wildcard: ``'.example.com'`` will match +``example.com``, ``www.example.com``, and any other subdomain of +``example.com``. A value of ``'*'`` will match anything; in this case you are +responsible to provide your own validation of the ``Host`` header (perhaps in a +middleware; if so this middleware must be listed first in +:setting:`MIDDLEWARE_CLASSES`). + +If the ``Host`` header (or ``X-Forwarded-Host`` if +:setting:`USE_X_FORWARDED_HOST` is enabled) does not match any value in this +list, the :meth:`django.http.HttpRequest.get_host()` method will raise +:exc:`~django.core.exceptions.SuspiciousOperation`. + +When :setting:`DEBUG` is ``True`` or when running tests, host validation is +disabled; any host will be accepted. Thus it's usually only necessary to set it +in production. + +This validation only applies via :meth:`~django.http.HttpRequest.get_host()`; +if your code accesses the ``Host`` header directly from ``request.META`` you +are bypassing this security protection. + .. setting:: ALLOWED_INCLUDE_ROOTS ALLOWED_INCLUDE_ROOTS @@ -99,26 +123,6 @@ The :setting:`APPEND_SLASH` setting is only used if :class:`~django.middleware.common.CommonMiddleware` is installed (see :doc:`/topics/http/middleware`). See also :setting:`PREPEND_WWW`. -.. setting:: AUTHENTICATION_BACKENDS - -AUTHENTICATION_BACKENDS ------------------------ - -Default: ``('django.contrib.auth.backends.ModelBackend',)`` - -A tuple of authentication backend classes (as strings) to use when attempting to -authenticate a user. See the :doc:`authentication backends documentation -</ref/authbackends>` for details. - -.. setting:: AUTH_USER_MODEL - -AUTH_USER_MODEL ---------------- - -Default: 'auth.User' - -The model to use to represent a User. See :ref:`auth-custom-user`. - .. setting:: CACHES CACHES @@ -159,7 +163,7 @@ The cache backend to use. The built-in cache backends are: * ``'django.core.cache.backends.memcached.PyLibMCCache'`` You can use a cache backend that doesn't ship with Django by setting -:setting:`BACKEND <CACHE-BACKEND>` to a fully-qualified path of a cache +:setting:`BACKEND <CACHES-BACKEND>` to a fully-qualified path of a cache backend class (i.e. ``mypackage.backends.whatever.WhateverCache``). Writing a whole new cache backend from scratch is left as an exercise to the reader; see the other backends for examples. @@ -179,7 +183,8 @@ implementation is equivalent to the function:: You may use any key function you want, as long as it has the same argument signature. -See the :ref:`cache documentation <cache_key_transformation>` for more information. +See the :ref:`cache documentation <cache_key_transformation>` for more +information. .. setting:: CACHES-KEY_PREFIX @@ -293,6 +298,8 @@ The default number of seconds to cache a page when the caching middleware or See :doc:`/topics/cache`. +.. _settings-csrf: + .. setting:: CSRF_COOKIE_DOMAIN CSRF_COOKIE_DOMAIN @@ -304,12 +311,25 @@ The domain to be used when setting the CSRF cookie. This can be useful for easily allowing cross-subdomain requests to be excluded from the normal cross site request forgery protection. It should be set to a string such as ``".example.com"`` to allow a POST request from a form on one subdomain to be -accepted by accepted by a view served from another subdomain. +accepted by a view served from another subdomain. Please note that the presence of this setting does not imply that Django's CSRF protection is safe from cross-subdomain attacks by default - please see the :ref:`CSRF limitations <csrf-limitations>` section. +.. setting:: CSRF_COOKIE_HTTPONLY + +CSRF_COOKIE_HTTPONLY +-------------------- + +.. versionadded:: 1.6 + +Default: ``False`` + +Whether to use HttpOnly flag on the CSRF cookie. If this is set to ``True``, +client-side JavaScript will not to be able to access the CSRF cookie. See +:setting:`SESSION_COOKIE_HTTPONLY` for details on HttpOnly. + .. setting:: CSRF_COOKIE_NAME CSRF_COOKIE_NAME @@ -325,8 +345,6 @@ want. See :doc:`/ref/contrib/csrf`. CSRF_COOKIE_PATH ---------------- -.. versionadded:: 1.4 - Default: ``'/'`` The path set on the CSRF cookie. This should either match the URL path of your @@ -341,8 +359,6 @@ its own CSRF cookie. CSRF_COOKIE_SECURE ------------------ -.. versionadded:: 1.4 - Default: ``False`` Whether to use a secure cookie for the CSRF cookie. If this is set to ``True``, @@ -365,7 +381,6 @@ where ``reason`` is a short message (intended for developers or logging, not for end users) indicating the reason the request was rejected. See :doc:`/ref/contrib/csrf`. - .. setting:: DATABASES DATABASES @@ -393,6 +408,30 @@ SQLite. This can be configured using the following:: For other database backends, or more complex SQLite configurations, other options will be required. The following inner options are available. +.. setting:: DATABASE-ATOMIC_REQUESTS + +ATOMIC_REQUESTS +~~~~~~~~~~~~~~~ + +.. versionadded:: 1.6 + +Default: ``False`` + +Set this to ``True`` to wrap each HTTP request in a transaction on this +database. See :ref:`tying-transactions-to-http-requests`. + +.. setting:: DATABASE-AUTOCOMMIT + +AUTOCOMMIT +~~~~~~~~~~ + +.. versionadded:: 1.6 + +Default: ``True`` + +Set this to ``False`` if you want to :ref:`disable Django's transaction +management <deactivate-transaction-management>` and implement your own. + .. setting:: DATABASE-ENGINE ENGINE @@ -449,6 +488,19 @@ The name of the database to use. For SQLite, it's the full path to the database file. When specifying the path, always use forward slashes, even on Windows (e.g. ``C:/homes/user/mysite/sqlite3.db``). +.. setting:: CONN_MAX_AGE + +CONN_MAX_AGE +~~~~~~~~~~~~ + +.. versionadded:: 1.6 + +Default: ``600`` + +The lifetime of a database connection, in seconds. Use ``0`` to close database +connections at the end of each request — Django's historical behavior — and +``None`` for unlimited persistent connections. + .. setting:: OPTIONS OPTIONS @@ -505,7 +557,7 @@ backend-specific. Supported for the PostgreSQL_ (``postgresql_psycopg2``) and MySQL_ (``mysql``) backends. -.. _PostgreSQL: http://www.postgresql.org/docs/8.2/static/multibyte.html +.. _PostgreSQL: http://www.postgresql.org/docs/current/static/multibyte.html .. _MySQL: http://dev.mysql.com/doc/refman/5.0/en/charset-database.html .. setting:: TEST_COLLATION @@ -562,7 +614,7 @@ If the default value (``None``) is used with the SQLite database engine, the tests will use a memory resident database. For all other database engines the test database will use the name ``'test_' + DATABASE_NAME``. -See :doc:`/topics/testing`. +See :ref:`the-test-database`. .. setting:: TEST_CREATE @@ -670,9 +722,13 @@ DATE_INPUT_FORMATS Default:: - ('%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', '%b %d %Y', - '%b %d, %Y', '%d %b %Y', '%d %b, %Y', '%B %d %Y', - '%B %d, %Y', '%d %B %Y', '%d %B, %Y') + ( + '%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06' + '%b %d %Y', '%b %d, %Y', # 'Oct 25 2006', 'Oct 25, 2006' + '%d %b %Y', '%d %b, %Y', # '25 Oct 2006', '25 Oct, 2006' + '%B %d %Y', '%B %d, %Y', # 'October 25 2006', 'October 25, 2006' + '%d %B %Y', '%d %B, %Y', # '25 October 2006', '25 October, 2006' + ) A tuple of formats that will be accepted when inputting data on a date field. Formats will be tried in order, using the first valid one. Note that these @@ -707,9 +763,20 @@ DATETIME_INPUT_FORMATS Default:: - ('%Y-%m-%d %H:%M:%S', '%Y-%m-%d %H:%M', '%Y-%m-%d', - '%m/%d/%Y %H:%M:%S', '%m/%d/%Y %H:%M', '%m/%d/%Y', - '%m/%d/%y %H:%M:%S', '%m/%d/%y %H:%M', '%m/%d/%y') + ( + '%Y-%m-%d %H:%M:%S', # '2006-10-25 14:30:59' + '%Y-%m-%d %H:%M:%S.%f', # '2006-10-25 14:30:59.000200' + '%Y-%m-%d %H:%M', # '2006-10-25 14:30' + '%Y-%m-%d', # '2006-10-25' + '%m/%d/%Y %H:%M:%S', # '10/25/2006 14:30:59' + '%m/%d/%Y %H:%M:%S.%f', # '10/25/2006 14:30:59.000200' + '%m/%d/%Y %H:%M', # '10/25/2006 14:30' + '%m/%d/%Y', # '10/25/2006' + '%m/%d/%y %H:%M:%S', # '10/25/06 14:30:59' + '%m/%d/%y %H:%M:%S.%f', # '10/25/06 14:30:59.000200' + '%m/%d/%y %H:%M', # '10/25/06 14:30' + '%m/%d/%y', # '10/25/06' + ) A tuple of formats that will be accepted when inputting data on a datetime field. Formats will be tried in order, using the first valid one. Note that @@ -748,18 +815,13 @@ sensitive (or offensive), such as :setting:`SECRET_KEY` or :setting:`PROFANITIES_LIST`. Specifically, it will exclude any setting whose name includes any of the following: - * API - * KEY - * PASS - * PROFANITIES_LIST - * SECRET - * SIGNATURE - * TOKEN - -.. versionchanged:: 1.4 - - We changed ``'PASSWORD'`` ``'PASS'``. ``'API'``, ``'TOKEN'`` and ``'KEY'`` - were added. +* ``'API'`` +* ``'KEY'`` +* ``'PASS'`` +* ``'PROFANITIES_LIST'`` +* ``'SECRET'`` +* ``'SIGNATURE'`` +* ``'TOKEN'`` Note that these are *partial* matches. ``'PASS'`` will also match PASSWORD, just as ``'TOKEN'`` will also match TOKENIZED and so on. @@ -774,6 +836,8 @@ when you're debugging, but it'll rapidly consume memory on a production server. .. _django/views/debug.py: https://github.com/django/django/blob/master/django/views/debug.py +.. setting:: DEBUG_PROPAGATE_EXCEPTIONS + DEBUG_PROPAGATE_EXCEPTIONS -------------------------- @@ -830,7 +894,7 @@ DEFAULT_EXCEPTION_REPORTER_FILTER Default: :class:`django.views.debug.SafeExceptionReporterFilter` Default exception reporter filter class to be used if none has been assigned to -the :class:`HttpRequest` instance yet. +the :class:`~django.http.HttpRequest` instance yet. See :ref:`Filtering error reports<filtering-error-reports>`. .. setting:: DEFAULT_FILE_STORAGE @@ -1070,6 +1134,8 @@ Note that these paths should use Unix-style forward slashes, even on Windows. See :ref:`initial-data-via-fixtures` and :ref:`topics-testing-fixtures`. +.. setting:: FORCE_SCRIPT_NAME + FORCE_SCRIPT_NAME ------------------ @@ -1115,8 +1181,6 @@ Available formats are :setting:`DATE_FORMAT`, :setting:`TIME_FORMAT`, IGNORABLE_404_URLS ------------------ -.. versionadded:: 1.4 - Default: ``()`` List of compiled regular expression objects describing URLs that should be @@ -1127,8 +1191,9 @@ query string, if any). Use this if your site does not provide a commonly requested file such as ``favicon.ico`` or ``robots.txt``, or if it gets hammered by script kiddies. -This is only used if :setting:`SEND_BROKEN_LINK_EMAILS` is set to ``True`` and -``CommonMiddleware`` is installed (see :doc:`/topics/http/middleware`). +This is only used if +:class:`~django.middleware.common.BrokenLinkEmailsMiddleware` is enabled (see +:doc:`/topics/http/middleware`). .. setting:: INSTALLED_APPS @@ -1170,9 +1235,12 @@ LANGUAGE_CODE Default: ``'en-us'`` -A string representing the language code for this installation. This should be in -standard :term:`language format<language code>`. For example, U.S. English is -``"en-us"``. See :doc:`/topics/i18n/index`. +A string representing the language code for this installation. This should be +in standard :term:`language format<language code>`. For example, U.S. English +is ``"en-us"``. See also the `list of language identifiers`_ and +:doc:`/topics/i18n/index`. + +.. _list of language identifiers: http://www.i18nguy.com/unicode/language-identifiers.html .. setting:: LANGUAGE_COOKIE_NAME @@ -1197,9 +1265,9 @@ see the current list of translated languages by looking in .. _online source: https://github.com/django/django/blob/master/django/conf/global_settings.py -The list is a tuple of two-tuples in the format ``(language code, language -name)``, the ``language code`` part should be a -:term:`language name<language code>` -- for example, ``('ja', 'Japanese')``. +The list is a tuple of two-tuples in the format +(:term:`language code<language code>`, ``language name``) -- for example, +``('ja', 'Japanese')``. This specifies which languages are available for language selection. See :doc:`/topics/i18n/index`. @@ -1279,54 +1347,6 @@ configuration process will be skipped. .. _dictConfig: http://docs.python.org/library/logging.config.html#configuration-dictionary-schema -.. setting:: LOGIN_REDIRECT_URL - -LOGIN_REDIRECT_URL ------------------- - -Default: ``'/accounts/profile/'`` - -The URL where requests are redirected after login when the -``contrib.auth.login`` view gets no ``next`` parameter. - -This is used by the :func:`~django.contrib.auth.decorators.login_required` -decorator, for example. - -.. versionchanged:: 1.5 - -This setting now also accepts view function names and -:ref:`named URL patterns <naming-url-patterns>` which can be used to reduce -configuration duplication since you no longer have to define the URL in two -places (``settings`` and URLconf). -For backward compatibility reasons the default remains unchanged. - -.. setting:: LOGIN_URL - -LOGIN_URL ---------- - -Default: ``'/accounts/login/'`` - -The URL where requests are redirected for login, especially when using the -:func:`~django.contrib.auth.decorators.login_required` decorator. - -.. versionchanged:: 1.5 - -This setting now also accepts view function names and -:ref:`named URL patterns <naming-url-patterns>` which can be used to reduce -configuration duplication since you no longer have to define the URL in two -places (``settings`` and URLconf). -For backward compatibility reasons the default remains unchanged. - -.. setting:: LOGOUT_URL - -LOGOUT_URL ----------- - -Default: ``'/accounts/logout/'`` - -LOGIN_URL counterpart. - .. setting:: MANAGERS MANAGERS @@ -1335,7 +1355,8 @@ MANAGERS Default: ``()`` (Empty tuple) A tuple in the same format as :setting:`ADMINS` that specifies who should get -broken-link notifications when :setting:`SEND_BROKEN_LINK_EMAILS` is ``True``. +broken link notifications when +:class:`~django.middleware.common.BrokenLinkEmailsMiddleware` is enabled. .. setting:: MEDIA_ROOT @@ -1364,37 +1385,6 @@ to a non-empty value. Example: ``"http://media.example.com/"`` -MESSAGE_LEVEL -------------- - -Default: `messages.INFO` - -Sets the minimum message level that will be recorded by the messages -framework. See the :doc:`messages documentation </ref/contrib/messages>` for -more details. - -MESSAGE_STORAGE ---------------- - -Default: ``'django.contrib.messages.storage.fallback.FallbackStorage'`` - -Controls where Django stores message data. See the -:doc:`messages documentation </ref/contrib/messages>` for more details. - -MESSAGE_TAGS ------------- - -Default:: - - {messages.DEBUG: 'debug', - messages.INFO: 'info', - messages.SUCCESS: 'success', - messages.WARNING: 'warning', - messages.ERROR: 'error',} - -Sets the mapping of message levels to message tags. See the -:doc:`messages documentation </ref/contrib/messages>` for more details. - .. setting:: MIDDLEWARE_CLASSES MIDDLEWARE_CLASSES @@ -1450,16 +1440,6 @@ format has higher precedence and will be applied instead. See also :setting:`DECIMAL_SEPARATOR`, :setting:`THOUSAND_SEPARATOR` and :setting:`USE_THOUSAND_SEPARATOR`. -.. setting:: PASSWORD_RESET_TIMEOUT_DAYS - -PASSWORD_RESET_TIMEOUT_DAYS ---------------------------- - -Default: ``3`` - -The number of days a password reset link is valid for. Used by the -:mod:`django.contrib.auth` password reset mechanism. - .. setting:: PREPEND_WWW PREPEND_WWW @@ -1471,30 +1451,6 @@ Whether to prepend the "www." subdomain to URLs that don't have it. This is only used if :class:`~django.middleware.common.CommonMiddleware` is installed (see :doc:`/topics/http/middleware`). See also :setting:`APPEND_SLASH`. -.. setting:: PROFANITIES_LIST - -PROFANITIES_LIST ----------------- - -Default: ``()`` (Empty tuple) - -A tuple of profanities, as strings, that will be forbidden in comments when -:setting:`COMMENTS_ALLOW_PROFANITIES` is ``False``. - -.. setting:: RESTRUCTUREDTEXT_FILTER_SETTINGS - -RESTRUCTUREDTEXT_FILTER_SETTINGS --------------------------------- - -Default: ``{}`` - -A dictionary containing settings for the ``restructuredtext`` markup filter from -the :doc:`django.contrib.markup application </ref/contrib/markup>`. They override -the default writer settings. See the Docutils restructuredtext `writer settings -docs`_ for details. - -.. _writer settings docs: http://docutils.sourceforge.net/docs/user/config.html#html4css1-writer - .. setting:: ROOT_URLCONF ROOT_URLCONF @@ -1537,8 +1493,6 @@ randomly-generated ``SECRET_KEY`` to each new project. SECURE_PROXY_SSL_HEADER ----------------------- -.. versionadded:: 1.4 - Default: ``None`` A tuple representing a HTTP header/value combination that signifies a request @@ -1600,6 +1554,11 @@ available in ``request.META``.) SEND_BROKEN_LINK_EMAILS ----------------------- +.. deprecated:: 1.6 + Since :class:`~django.middleware.common.BrokenLinkEmailsMiddleware` + was split from :class:`~django.middleware.common.CommonMiddleware`, + this setting no longer serves a purpose. + Default: ``False`` Whether to send an email to the :setting:`MANAGERS` each time somebody visits @@ -1631,144 +1590,6 @@ Default: ``'root@localhost'`` The email address that error messages come from, such as those sent to :setting:`ADMINS` and :setting:`MANAGERS`. -.. setting:: SESSION_COOKIE_AGE - -SESSION_COOKIE_AGE ------------------- - -Default: ``1209600`` (2 weeks, in seconds) - -The age of session cookies, in seconds. See :doc:`/topics/http/sessions`. - -.. setting:: SESSION_COOKIE_DOMAIN - -SESSION_COOKIE_DOMAIN ---------------------- - -Default: ``None`` - -The domain to use for session cookies. Set this to a string such as -``".example.com"`` for cross-domain cookies, or use ``None`` for a standard -domain cookie. See the :doc:`/topics/http/sessions`. - -.. setting:: SESSION_COOKIE_HTTPONLY - -SESSION_COOKIE_HTTPONLY ------------------------ - -Default: ``True`` - -Whether to use HTTPOnly flag on the session cookie. If this is set to -``True``, client-side JavaScript will not to be able to access the -session cookie. - -HTTPOnly_ is a flag included in a Set-Cookie HTTP response header. It -is not part of the :rfc:`2109` standard for cookies, and it isn't honored -consistently by all browsers. However, when it is honored, it can be a -useful way to mitigate the risk of client side script accessing the -protected cookie data. - -.. _HTTPOnly: https://www.owasp.org/index.php/HTTPOnly - -.. versionchanged:: 1.4 - The default value of the setting was changed from ``False`` to ``True``. - -.. setting:: SESSION_COOKIE_NAME - -SESSION_COOKIE_NAME -------------------- - -Default: ``'sessionid'`` - -The name of the cookie to use for sessions. This can be whatever you want (but -should be different from :setting:`LANGUAGE_COOKIE_NAME`). -See the :doc:`/topics/http/sessions`. - -.. setting:: SESSION_COOKIE_PATH - -SESSION_COOKIE_PATH -------------------- - -Default: ``'/'`` - -The path set on the session cookie. This should either match the URL path of your -Django installation or be parent of that path. - -This is useful if you have multiple Django instances running under the same -hostname. They can use different cookie paths, and each instance will only see -its own session cookie. - -.. setting:: SESSION_CACHE_ALIAS - -SESSION_CACHE_ALIAS -------------------- - -Default: ``default`` - -If you're using :ref:`cache-based session storage <cached-sessions-backend>`, -this selects the cache to use. - -.. setting:: SESSION_COOKIE_SECURE - -SESSION_COOKIE_SECURE ---------------------- - -Default: ``False`` - -Whether to use a secure cookie for the session cookie. If this is set to -``True``, the cookie will be marked as "secure," which means browsers may -ensure that the cookie is only sent under an HTTPS connection. -See the :doc:`/topics/http/sessions`. - -.. setting:: SESSION_ENGINE - -SESSION_ENGINE --------------- - -Default: ``django.contrib.sessions.backends.db`` - -Controls where Django stores session data. Valid values are: - -* ``'django.contrib.sessions.backends.db'`` -* ``'django.contrib.sessions.backends.file'`` -* ``'django.contrib.sessions.backends.cache'`` -* ``'django.contrib.sessions.backends.cached_db'`` -* ``'django.contrib.sessions.backends.signed_cookies'`` - -See :doc:`/topics/http/sessions`. - -.. setting:: SESSION_EXPIRE_AT_BROWSER_CLOSE - -SESSION_EXPIRE_AT_BROWSER_CLOSE -------------------------------- - -Default: ``False`` - -Whether to expire the session when the user closes his or her browser. -See the :doc:`/topics/http/sessions`. - -.. setting:: SESSION_FILE_PATH - -SESSION_FILE_PATH ------------------ - -Default: ``None`` - -If you're using file-based session storage, this sets the directory in -which Django will store session data. See :doc:`/topics/http/sessions`. When -the default value (``None``) is used, Django will use the standard temporary -directory for the system. - -.. setting:: SESSION_SAVE_EVERY_REQUEST - -SESSION_SAVE_EVERY_REQUEST --------------------------- - -Default: ``False`` - -Whether to save the session data on every request. See -:doc:`/topics/http/sessions`. - .. setting:: SHORT_DATE_FORMAT SHORT_DATE_FORMAT @@ -1802,79 +1623,12 @@ See also :setting:`DATE_FORMAT` and :setting:`SHORT_DATE_FORMAT`. SIGNING_BACKEND --------------- -.. versionadded:: 1.4 - Default: 'django.core.signing.TimestampSigner' The backend used for signing cookies and other data. See also the :doc:`/topics/signing` documentation. -.. setting:: SITE_ID - -SITE_ID -------- - -Default: Not defined - -The ID, as an integer, of the current site in the ``django_site`` database -table. This is used so that application data can hook into specific site(s) -and a single database can manage content for multiple sites. - -See :doc:`/ref/contrib/sites`. - -.. _site framework docs: ../sites/ - -.. setting:: STATIC_ROOT - -STATIC_ROOT ------------ - -Default: ``''`` (Empty string) - -The absolute path to the directory where :djadmin:`collectstatic` will collect -static files for deployment. - -Example: ``"/var/www/example.com/static/"`` - -If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled -(default) the :djadmin:`collectstatic` management command will collect static -files into this directory. See the howto on :doc:`managing static -files</howto/static-files>` for more details about usage. - -.. warning:: - - This should be an (initially empty) destination directory for collecting - your static files from their permanent locations into one directory for - ease of deployment; it is **not** a place to store your static files - permanently. You should do that in directories that will be found by - :doc:`staticfiles</ref/contrib/staticfiles>`'s - :setting:`finders<STATICFILES_FINDERS>`, which by default, are - ``'static/'`` app sub-directories and any directories you include in - :setting:`STATICFILES_DIRS`). - -See :doc:`staticfiles reference</ref/contrib/staticfiles>` and -:setting:`STATIC_URL`. - -.. setting:: STATIC_URL - -STATIC_URL ----------- - -Default: ``None`` - -URL to use when referring to static files located in :setting:`STATIC_ROOT`. - -Example: ``"/static/"`` or ``"http://static.example.com/"`` - -If not ``None``, this will be used as the base path for -:ref:`media definitions<form-media-paths>` and the -:doc:`staticfiles app</ref/contrib/staticfiles>`. - -It must end in a slash if set to a non-empty value. - -See :setting:`STATIC_ROOT`. - .. setting:: TEMPLATE_CONTEXT_PROCESSORS TEMPLATE_CONTEXT_PROCESSORS @@ -1894,10 +1648,6 @@ A tuple of callables that are used to populate the context in ``RequestContext`` These callables take a request object as their argument and return a dictionary of items to be merged into the context. -.. versionadded:: 1.4 - The ``django.core.context_processors.tz`` context processor - was added in this release. - .. setting:: TEMPLATE_DEBUG TEMPLATE_DEBUG @@ -1963,9 +1713,7 @@ TEST_RUNNER Default: ``'django.test.simple.DjangoTestSuiteRunner'`` The name of the class to use for starting the test suite. See -:doc:`/topics/testing`. - -.. _Testing Django Applications: ../testing/ +:ref:`other-testing-frameworks`. .. setting:: THOUSAND_SEPARATOR @@ -2003,7 +1751,13 @@ See also :setting:`DATE_FORMAT` and :setting:`DATETIME_FORMAT`. TIME_INPUT_FORMATS ------------------ -Default: ``('%H:%M:%S', '%H:%M')`` +Default:: + + ( + '%H:%M:%S', # '14:30:59' + '%H:%M:%S.%f', # '14:30:59.000200' + '%H:%M', # '14:30' + ) A tuple of formats that will be accepted when inputting data on a time field. Formats will be tried in order, using the first valid one. Note that these @@ -2015,6 +1769,10 @@ precedence and will be applied instead. See also :setting:`DATE_INPUT_FORMATS` and :setting:`DATETIME_INPUT_FORMATS`. +.. versionchanged:: 1.6 + +Input format with microseconds has been added. + .. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior .. setting:: TIME_ZONE @@ -2024,15 +1782,14 @@ TIME_ZONE Default: ``'America/Chicago'`` -.. versionchanged:: 1.4 - The meaning of this setting now depends on the value of :setting:`USE_TZ`. +A string representing the time zone for this installation, or ``None``. See +the `list of time zones`_. -A string representing the time zone for this installation, or -``None``. `See available choices`_. (Note that list of available -choices lists more than one on the same line; you'll want to use just -one of the choices for a given time zone. For instance, one line says -``'Europe/London GB GB-Eire'``, but you should use the first bit of -that -- ``'Europe/London'`` -- as your :setting:`TIME_ZONE` setting.) +.. note:: + Since Django was first released with the :setting:`TIME_ZONE` set to + ``'America/Chicago'``, the global setting (used if nothing is defined in + your project's ``settings.py``) remains ``'America/Chicago'`` for backwards + compatibility. New project templates default to ``'UTC'``. Note that this isn't necessarily the time zone of the server. For example, one server may serve multiple Django-powered sites, each with a separate time zone @@ -2065,7 +1822,7 @@ to ensure your processes are running in the correct environment. If you're running Django on Windows, :setting:`TIME_ZONE` must be set to match the system time zone. -.. _See available choices: http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE +.. _list of time zones: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones .. _pytz: http://pytz.sourceforge.net/ @@ -2074,6 +1831,12 @@ to ensure your processes are running in the correct environment. TRANSACTIONS_MANAGED -------------------- +.. deprecated:: 1.6 + + This setting was deprecated because its name is very misleading. Use the + :setting:`AUTOCOMMIT <DATABASE-AUTOCOMMIT>` key in :setting:`DATABASES` + entries instead. + Default: ``False`` Set this to ``True`` if you want to :ref:`disable Django's transaction @@ -2143,8 +1906,6 @@ See also :setting:`DECIMAL_SEPARATOR`, :setting:`NUMBER_GROUPING` and USE_TZ ------ -.. versionadded:: 1.4 - Default: ``False`` A boolean that specifies if datetimes will be timezone-aware by default or not. @@ -2175,8 +1936,6 @@ which sets this header is in use. WSGI_APPLICATION ---------------- -.. versionadded:: 1.4 - Default: ``None`` The full Python path of the WSGI application object that Django's built-in @@ -2185,7 +1944,7 @@ startproject <startproject>` management command will create a simple ``wsgi.py`` file with an ``application`` callable in it, and point this setting to that ``application``. -If not set, the return value of :func:`django.core.wsgi.get_wsgi_application` +If not set, the return value of ``django.core.wsgi.get_wsgi_application()`` will be used. In this case, the behavior of :djadmin:`runserver` will be identical to previous Django versions. @@ -2220,8 +1979,41 @@ The default value for the X-Frame-Options header used by :class:`~django.middleware.clickjacking.XFrameOptionsMiddleware`. See the :doc:`clickjacking protection </ref/clickjacking/>` documentation. -Deprecated settings -=================== + +Admindocs +========= + +Settings for :mod:`django.contrib.admindocs`. + +.. setting:: ADMIN_FOR + +ADMIN_FOR +--------- + +Default: ``()`` (Empty tuple) + +Used for admin-site settings modules, this should be a tuple of settings +modules (in the format ``'foo.bar.baz'``) for which this site is an admin. + +The admin site uses this in its automatically-introspected documentation of +models, views and template tags. + + +Auth +==== + +Settings for :mod:`django.contrib.auth`. + +.. setting:: AUTHENTICATION_BACKENDS + +AUTHENTICATION_BACKENDS +----------------------- + +Default: ``('django.contrib.auth.backends.ModelBackend',)`` + +A tuple of authentication backend classes (as strings) to use when attempting to +authenticate a user. See the :ref:`authentication backends documentation +<authentication-backends>` for details. .. setting:: AUTH_PROFILE_MODULE @@ -2237,29 +2029,697 @@ AUTH_PROFILE_MODULE Default: Not defined The site-specific user profile model used by this site. See -:ref:`auth-profiles`. +:ref:`User profiles <auth-profiles>`. -.. setting:: IGNORABLE_404_ENDS +.. setting:: AUTH_USER_MODEL + +AUTH_USER_MODEL +--------------- -IGNORABLE_404_ENDS +Default: 'auth.User' + +The model to use to represent a User. See :ref:`auth-custom-user`. + +.. setting:: LOGIN_REDIRECT_URL + +LOGIN_REDIRECT_URL ------------------ -.. deprecated:: 1.4 - This setting has been superseded by :setting:`IGNORABLE_404_URLS`. +Default: ``'/accounts/profile/'`` -.. setting:: IGNORABLE_404_STARTS +The URL where requests are redirected after login when the +``contrib.auth.login`` view gets no ``next`` parameter. -IGNORABLE_404_STARTS --------------------- +This is used by the :func:`~django.contrib.auth.decorators.login_required` +decorator, for example. -.. deprecated:: 1.4 - This setting has been superseded by :setting:`IGNORABLE_404_URLS`. +.. versionchanged:: 1.5 -.. setting:: URL_VALIDATOR_USER_AGENT +This setting now also accepts view function names and +:ref:`named URL patterns <naming-url-patterns>` which can be used to reduce +configuration duplication since you no longer have to define the URL in two +places (``settings`` and URLconf). +For backward compatibility reasons the default remains unchanged. -URL_VALIDATOR_USER_AGENT ------------------------- +.. setting:: LOGIN_URL -.. deprecated:: 1.5 - This value was used as the ``User-Agent`` header when checking if a URL - exists, a feature that was removed due to security and performance issues. +LOGIN_URL +--------- + +Default: ``'/accounts/login/'`` + +The URL where requests are redirected for login, especially when using the +:func:`~django.contrib.auth.decorators.login_required` decorator. + +.. versionchanged:: 1.5 + +This setting now also accepts view function names and +:ref:`named URL patterns <naming-url-patterns>` which can be used to reduce +configuration duplication since you no longer have to define the URL in two +places (``settings`` and URLconf). +For backward compatibility reasons the default remains unchanged. + +.. setting:: LOGOUT_URL + +LOGOUT_URL +---------- + +Default: ``'/accounts/logout/'`` + +LOGIN_URL counterpart. + +.. setting:: PASSWORD_RESET_TIMEOUT_DAYS + +PASSWORD_RESET_TIMEOUT_DAYS +--------------------------- + +Default: ``3`` + +The number of days a password reset link is valid for. Used by the +:mod:`django.contrib.auth` password reset mechanism. + +.. setting:: PASSWORD_HASHERS + +PASSWORD_HASHERS +---------------- + +See :ref:`auth_password_storage`. + +Default:: + + ('django.contrib.auth.hashers.PBKDF2PasswordHasher', + 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher', + 'django.contrib.auth.hashers.BCryptPasswordHasher', + 'django.contrib.auth.hashers.SHA1PasswordHasher', + 'django.contrib.auth.hashers.MD5PasswordHasher', + 'django.contrib.auth.hashers.UnsaltedMD5PasswordHasher', + 'django.contrib.auth.hashers.CryptPasswordHasher',) + + +.. _settings-comments: + +Comments +======== + +Settings for :mod:`django.contrib.comments`. + +.. setting:: COMMENTS_HIDE_REMOVED + +COMMENTS_HIDE_REMOVED +--------------------- + +If ``True`` (default), removed comments will be excluded from comment +lists/counts (as taken from template tags). Otherwise, the template author is +responsible for some sort of a "this comment has been removed by the site staff" +message. + +.. setting:: COMMENT_MAX_LENGTH + +COMMENT_MAX_LENGTH +------------------ + +The maximum length of the comment field, in characters. Comments longer than +this will be rejected. Defaults to 3000. + +.. setting:: COMMENTS_APP + +COMMENTS_APP +------------ + +An app which provides :doc:`customization of the comments framework +</ref/contrib/comments/custom>`. Use the same dotted-string notation +as in :setting:`INSTALLED_APPS`. Your custom :setting:`COMMENTS_APP` +must also be listed in :setting:`INSTALLED_APPS`. + +.. setting:: PROFANITIES_LIST + +PROFANITIES_LIST +---------------- + +Default: ``()`` (Empty tuple) + +A tuple of profanities, as strings, that will be forbidden in comments when +``COMMENTS_ALLOW_PROFANITIES`` is ``False``. + + +.. _settings-messages: + +Messages +======== + +Settings for :mod:`django.contrib.messages`. + +.. setting:: MESSAGE_LEVEL + +MESSAGE_LEVEL +------------- + +Default: ``messages.INFO`` + +Sets the minimum message level that will be recorded by the messages +framework. See :ref:`message levels <message-level>` for more details. + +.. admonition:: Important + + If you override ``MESSAGE_LEVEL`` in your settings file and rely on any of + the built-in constants, you must import the constants module directly to + avoid the potential for circular imports, e.g.:: + + from django.contrib.messages import constants as message_constants + MESSAGE_LEVEL = message_constants.DEBUG + + If desired, you may specify the numeric values for the constants directly + according to the values in the above :ref:`constants table + <message-level-constants>`. + +.. setting:: MESSAGE_STORAGE + +MESSAGE_STORAGE +--------------- + +Default: ``'django.contrib.messages.storage.fallback.FallbackStorage'`` + +Controls where Django stores message data. Valid values are: + +* ``'django.contrib.messages.storage.fallback.FallbackStorage'`` +* ``'django.contrib.messages.storage.session.SessionStorage'`` +* ``'django.contrib.messages.storage.cookie.CookieStorage'`` + +See :ref:`message storage backends <message-storage-backends>` for more details. + +.. setting:: MESSAGE_TAGS + +MESSAGE_TAGS +------------ + +Default:: + + {messages.DEBUG: 'debug', + messages.INFO: 'info', + messages.SUCCESS: 'success', + messages.WARNING: 'warning', + messages.ERROR: 'error',} + +This sets the mapping of message level to message tag, which is typically +rendered as a CSS class in HTML. If you specify a value, it will extend +the default. This means you only have to specify those values which you need +to override. See :ref:`message-displaying` above for more details. + +.. admonition:: Important + + If you override ``MESSAGE_TAGS`` in your settings file and rely on any of + the built-in constants, you must import the ``constants`` module directly to + avoid the potential for circular imports, e.g.:: + + from django.contrib.messages import constants as message_constants + MESSAGE_TAGS = {message_constants.INFO: ''} + + If desired, you may specify the numeric values for the constants directly + according to the values in the above :ref:`constants table + <message-level-constants>`. + +.. _messages-session_cookie_domain: + +SESSION_COOKIE_DOMAIN +--------------------- + +Default: ``None`` + +The storage backends that use cookies -- ``CookieStorage`` and +``FallbackStorage`` -- use the value of :setting:`SESSION_COOKIE_DOMAIN` in +setting their cookies. + + +.. _settings-sessions: + +Sessions +======== + +Settings for :mod:`django.contrib.sessions`. + +.. setting:: SESSION_CACHE_ALIAS + +SESSION_CACHE_ALIAS +------------------- + +Default: ``default`` + +If you're using :ref:`cache-based session storage <cached-sessions-backend>`, +this selects the cache to use. + +.. setting:: SESSION_COOKIE_AGE + +SESSION_COOKIE_AGE +------------------ + +Default: ``1209600`` (2 weeks, in seconds) + +The age of session cookies, in seconds. + +.. setting:: SESSION_COOKIE_DOMAIN + +SESSION_COOKIE_DOMAIN +--------------------- + +Default: ``None`` + +The domain to use for session cookies. Set this to a string such as +``".example.com"`` (note the leading dot!) for cross-domain cookies, or use +``None`` for a standard domain cookie. + +Be cautious when updating this setting on a production site. If you update +this setting to enable cross-domain cookies on a site that previously used +standard domain cookies, existing user cookies will be set to the old +domain. This may result in them being unable to log in as long as these cookies +persist. + +.. setting:: SESSION_COOKIE_HTTPONLY + +SESSION_COOKIE_HTTPONLY +----------------------- + +Default: ``True`` + +Whether to use HTTPOnly flag on the session cookie. If this is set to +``True``, client-side JavaScript will not to be able to access the +session cookie. + +HTTPOnly_ is a flag included in a Set-Cookie HTTP response header. It +is not part of the :rfc:`2109` standard for cookies, and it isn't honored +consistently by all browsers. However, when it is honored, it can be a +useful way to mitigate the risk of client side script accessing the +protected cookie data. + +.. _HTTPOnly: https://www.owasp.org/index.php/HTTPOnly + +.. setting:: SESSION_COOKIE_NAME + +SESSION_COOKIE_NAME +------------------- + +Default: ``'sessionid'`` + +The name of the cookie to use for sessions. This can be whatever you want (but +should be different from :setting:`LANGUAGE_COOKIE_NAME`). + +.. setting:: SESSION_COOKIE_PATH + +SESSION_COOKIE_PATH +------------------- + +Default: ``'/'`` + +The path set on the session cookie. This should either match the URL path of your +Django installation or be parent of that path. + +This is useful if you have multiple Django instances running under the same +hostname. They can use different cookie paths, and each instance will only see +its own session cookie. + +.. setting:: SESSION_COOKIE_SECURE + +SESSION_COOKIE_SECURE +--------------------- + +Default: ``False`` + +Whether to use a secure cookie for the session cookie. If this is set to +``True``, the cookie will be marked as "secure," which means browsers may +ensure that the cookie is only sent under an HTTPS connection. + +.. setting:: SESSION_ENGINE + +SESSION_ENGINE +-------------- + +Default: ``django.contrib.sessions.backends.db`` + +Controls where Django stores session data. Valid values are: + +* ``'django.contrib.sessions.backends.db'`` +* ``'django.contrib.sessions.backends.file'`` +* ``'django.contrib.sessions.backends.cache'`` +* ``'django.contrib.sessions.backends.cached_db'`` +* ``'django.contrib.sessions.backends.signed_cookies'`` + +See :ref:`configuring-sessions` for more details. + +.. setting:: SESSION_EXPIRE_AT_BROWSER_CLOSE + +SESSION_EXPIRE_AT_BROWSER_CLOSE +------------------------------- + +Default: ``False`` + +Whether to expire the session when the user closes his or her browser. See +:ref:`browser-length-vs-persistent-sessions`. + +.. setting:: SESSION_FILE_PATH + +SESSION_FILE_PATH +----------------- + +Default: ``None`` + +If you're using file-based session storage, this sets the directory in +which Django will store session data. When the default value (``None``) is +used, Django will use the standard temporary directory for the system. + + +.. setting:: SESSION_SAVE_EVERY_REQUEST + +SESSION_SAVE_EVERY_REQUEST +-------------------------- + +Default: ``False`` + +Whether to save the session data on every request. If this is ``False`` +(default), then the session data will only be saved if it has been modified -- +that is, if any of its dictionary values have been assigned or deleted. + + +Sites +===== + +Settings for :mod:`django.contrib.sites`. + +.. setting:: SITE_ID + +SITE_ID +------- + +Default: Not defined + +The ID, as an integer, of the current site in the ``django_site`` database +table. This is used so that application data can hook into specific sites +and a single database can manage content for multiple sites. + + +.. _settings-staticfiles: + +Static files +============ + +Settings for :mod:`django.contrib.staticfiles`. + +.. setting:: STATIC_ROOT + +STATIC_ROOT +----------- + +Default: ``''`` (Empty string) + +The absolute path to the directory where :djadmin:`collectstatic` will collect +static files for deployment. + +Example: ``"/var/www/example.com/static/"`` + +If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled +(default) the :djadmin:`collectstatic` management command will collect static +files into this directory. See the howto on :doc:`managing static +files</howto/static-files/index>` for more details about usage. + +.. warning:: + + This should be an (initially empty) destination directory for collecting + your static files from their permanent locations into one directory for + ease of deployment; it is **not** a place to store your static files + permanently. You should do that in directories that will be found by + :doc:`staticfiles</ref/contrib/staticfiles>`'s + :setting:`finders<STATICFILES_FINDERS>`, which by default, are + ``'static/'`` app sub-directories and any directories you include in + :setting:`STATICFILES_DIRS`). + +.. setting:: STATIC_URL + +STATIC_URL +---------- + +Default: ``None`` + +URL to use when referring to static files located in :setting:`STATIC_ROOT`. + +Example: ``"/static/"`` or ``"http://static.example.com/"`` + +If not ``None``, this will be used as the base path for +:ref:`media definitions<form-media-paths>` and the +:doc:`staticfiles app</ref/contrib/staticfiles>`. + +It must end in a slash if set to a non-empty value. + +.. setting:: STATICFILES_DIRS + +STATICFILES_DIRS +---------------- + +Default: ``[]`` + +This setting defines the additional locations the staticfiles app will traverse +if the ``FileSystemFinder`` finder is enabled, e.g. if you use the +:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the +static file serving view. + +This should be set to a list or tuple of strings that contain full paths to +your additional files directory(ies) e.g.:: + + STATICFILES_DIRS = ( + "/home/special.polls.com/polls/static", + "/home/polls.com/polls/static", + "/opt/webfiles/common", + ) + +Prefixes (optional) +~~~~~~~~~~~~~~~~~~~ + +In case you want to refer to files in one of the locations with an additional +namespace, you can **optionally** provide a prefix as ``(prefix, path)`` +tuples, e.g.:: + + STATICFILES_DIRS = ( + # ... + ("downloads", "/opt/webfiles/stats"), + ) + +Example: + +Assuming you have :setting:`STATIC_URL` set ``'/static/'``, the +:djadmin:`collectstatic` management command would collect the "stats" files +in a ``'downloads'`` subdirectory of :setting:`STATIC_ROOT`. + +This would allow you to refer to the local file +``'/opt/webfiles/stats/polls_20101022.tar.gz'`` with +``'/static/downloads/polls_20101022.tar.gz'`` in your templates, e.g.: + +.. code-block:: html+django + + <a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz"> + +.. setting:: STATICFILES_STORAGE + +STATICFILES_STORAGE +------------------- + +Default: ``'django.contrib.staticfiles.storage.StaticFilesStorage'`` + +The file storage engine to use when collecting static files with the +:djadmin:`collectstatic` management command. + +A ready-to-use instance of the storage backend defined in this setting +can be found at ``django.contrib.staticfiles.storage.staticfiles_storage``. + +For an example, see :ref:`staticfiles-from-cdn`. + +.. setting:: STATICFILES_FINDERS + +STATICFILES_FINDERS +------------------- + +Default:: + + ("django.contrib.staticfiles.finders.FileSystemFinder", + "django.contrib.staticfiles.finders.AppDirectoriesFinder") + +The list of finder backends that know how to find static files in +various locations. + +The default will find files stored in the :setting:`STATICFILES_DIRS` setting +(using ``django.contrib.staticfiles.finders.FileSystemFinder``) and in a +``static`` subdirectory of each app (using +``django.contrib.staticfiles.finders.AppDirectoriesFinder``) + +One finder is disabled by default: +``django.contrib.staticfiles.finders.DefaultStorageFinder``. If added to +your :setting:`STATICFILES_FINDERS` setting, it will look for static files in +the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE` +setting. + +.. note:: + + When using the ``AppDirectoriesFinder`` finder, make sure your apps + can be found by staticfiles. Simply add the app to the + :setting:`INSTALLED_APPS` setting of your site. + +Static file finders are currently considered a private interface, and this +interface is thus undocumented. + +Core Settings Topical Index +=========================== + +Cache +----- +* :setting:`CACHES` +* :setting:`CACHE_MIDDLEWARE_ALIAS` +* :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY` +* :setting:`CACHE_MIDDLEWARE_KEY_PREFIX` +* :setting:`CACHE_MIDDLEWARE_SECONDS` + +Database +-------- +* :setting:`DATABASES` +* :setting:`DATABASE_ROUTERS` +* :setting:`DEFAULT_INDEX_TABLESPACE` +* :setting:`DEFAULT_TABLESPACE` +* :setting:`TRANSACTIONS_MANAGED` + +Debugging +--------- +* :setting:`DEBUG` +* :setting:`DEBUG_PROPAGATE_EXCEPTIONS` + +Email +----- +* :setting:`ADMINS` +* :setting:`DEFAULT_CHARSET` +* :setting:`DEFAULT_FROM_EMAIL` +* :setting:`EMAIL_BACKEND` +* :setting:`EMAIL_FILE_PATH` +* :setting:`EMAIL_HOST` +* :setting:`EMAIL_HOST_PASSWORD` +* :setting:`EMAIL_HOST_USER` +* :setting:`EMAIL_PORT` +* :setting:`EMAIL_SUBJECT_PREFIX` +* :setting:`EMAIL_USE_TLS` +* :setting:`MANAGERS` +* :setting:`SEND_BROKEN_LINK_EMAILS` +* :setting:`SERVER_EMAIL` + +Error reporting +--------------- +* :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` +* :setting:`IGNORABLE_404_URLS` +* :setting:`MANAGERS` +* :setting:`SEND_BROKEN_LINK_EMAILS` + +File uploads +------------ +* :setting:`DEFAULT_FILE_STORAGE` +* :setting:`FILE_CHARSET` +* :setting:`FILE_UPLOAD_HANDLERS` +* :setting:`FILE_UPLOAD_MAX_MEMORY_SIZE` +* :setting:`FILE_UPLOAD_PERMISSIONS` +* :setting:`FILE_UPLOAD_TEMP_DIR` +* :setting:`MEDIA_ROOT` +* :setting:`MEDIA_URL` + +Globalization (i18n/l10n) +------------------------- +* :setting:`DATE_FORMAT` +* :setting:`DATE_INPUT_FORMATS` +* :setting:`DATETIME_FORMAT` +* :setting:`DATETIME_INPUT_FORMATS` +* :setting:`DECIMAL_SEPARATOR` +* :setting:`FIRST_DAY_OF_WEEK` +* :setting:`FORMAT_MODULE_PATH` +* :setting:`LANGUAGE_CODE` +* :setting:`LANGUAGE_COOKIE_NAME` +* :setting:`LANGUAGES` +* :setting:`LOCALE_PATHS` +* :setting:`MONTH_DAY_FORMAT` +* :setting:`NUMBER_GROUPING` +* :setting:`SHORT_DATE_FORMAT` +* :setting:`SHORT_DATETIME_FORMAT` +* :setting:`THOUSAND_SEPARATOR` +* :setting:`TIME_FORMAT` +* :setting:`TIME_INPUT_FORMATS` +* :setting:`TIME_ZONE` +* :setting:`USE_I18N` +* :setting:`USE_L10N` +* :setting:`USE_THOUSAND_SEPARATOR` +* :setting:`USE_TZ` +* :setting:`YEAR_MONTH_FORMAT` + +HTTP +---- +* :setting:`DEFAULT_CHARSET` +* :setting:`DEFAULT_CONTENT_TYPE` +* :setting:`DISALLOWED_USER_AGENTS` +* :setting:`FORCE_SCRIPT_NAME` +* :setting:`INTERNAL_IPS` +* :setting:`MIDDLEWARE_CLASSES` +* :setting:`SECURE_PROXY_SSL_HEADER` +* :setting:`SIGNING_BACKEND` +* :setting:`USE_ETAGS` +* :setting:`USE_X_FORWARDED_HOST` +* :setting:`WSGI_APPLICATION` + +Logging +------- +* :setting:`LOGGING` +* :setting:`LOGGING_CONFIG` + +Models +------ +* :setting:`ABSOLUTE_URL_OVERRIDES` +* :setting:`FIXTURE_DIRS` +* :setting:`INSTALLED_APPS` + +Security +-------- +* Cross Site Request Forgery protection + + * :setting:`CSRF_COOKIE_DOMAIN` + * :setting:`CSRF_COOKIE_NAME` + * :setting:`CSRF_COOKIE_PATH` + * :setting:`CSRF_COOKIE_SECURE` + * :setting:`CSRF_FAILURE_VIEW` + +* :setting:`SECRET_KEY` +* :setting:`X_FRAME_OPTIONS` + +Serialization +------------- +* :setting:`DEFAULT_CHARSET` +* :setting:`SERIALIZATION_MODULES` + +Templates +--------- +* :setting:`ALLOWED_INCLUDE_ROOTS` +* :setting:`TEMPLATE_CONTEXT_PROCESSORS` +* :setting:`TEMPLATE_DEBUG` +* :setting:`TEMPLATE_DIRS` +* :setting:`TEMPLATE_LOADERS` +* :setting:`TEMPLATE_STRING_IF_INVALID` + +Testing +------- +* Database + + * :setting:`TEST_CHARSET` + * :setting:`TEST_COLLATION` + * :setting:`TEST_DEPENDENCIES` + * :setting:`TEST_MIRROR` + * :setting:`TEST_NAME` + * :setting:`TEST_CREATE` + * :setting:`TEST_USER` + * :setting:`TEST_USER_CREATE` + * :setting:`TEST_PASSWD` + * :setting:`TEST_TBLSPACE` + * :setting:`TEST_TBLSPACE_TMP` + +* :setting:`TEST_RUNNER` + +URLs +---- +* :setting:`APPEND_SLASH` +* :setting:`PREPEND_WWW` +* :setting:`ROOT_URLCONF` diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt index 0db540370d..ca472bd60e 100644 --- a/docs/ref/signals.txt +++ b/docs/ref/signals.txt @@ -12,7 +12,7 @@ A list of all the signals that Django sends. The :doc:`comment framework </ref/contrib/comments/index>` sends a :doc:`set of comment-related signals </ref/contrib/comments/signals>`. - The :doc:`authentication framework </topics/auth>` sends :ref:`signals when + The :doc:`authentication framework </topics/auth/index>` sends :ref:`signals when a user is logged in / out <topics-auth-signals>`. Model signals @@ -27,9 +27,8 @@ module system. .. warning:: Many of these signals are sent by various model methods like - :meth:`~django.db.models.Model.__init__` or - :meth:`~django.db.models.Model.save` that you can overwrite in your own - code. + ``__init__()`` or :meth:`~django.db.models.Model.save` that you can + override in your own code. If you override these methods on your model, you must call the parent class' methods for this signals to be sent. @@ -47,7 +46,7 @@ pre_init .. ^^^^^^^ this :module: hack keeps Sphinx from prepending the module. Whenever you instantiate a Django model, this signal is sent at the beginning -of the model's :meth:`~django.db.models.Model.__init__` method. +of the model's ``__init__()`` method. Arguments sent with this signal: @@ -55,12 +54,10 @@ Arguments sent with this signal: The model class that just had an instance created. ``args`` - A list of positional arguments passed to - :meth:`~django.db.models.Model.__init__`: + A list of positional arguments passed to ``__init__()``: ``kwargs`` - A dictionary of keyword arguments passed to - :meth:`~django.db.models.Model.__init__`:. + A dictionary of keyword arguments passed to ``__init__()``: For example, the :doc:`tutorial </intro/tutorial01>` has this line:: @@ -74,7 +71,7 @@ Argument Value ``sender`` ``Poll`` (the class itself) ``args`` ``[]`` (an empty list because there were no positional - arguments passed to ``__init__``.) + arguments passed to ``__init__()``.) ``kwargs`` ``{'question': "What's up?", 'pub_date': datetime.now()}`` ========== =============================================================== @@ -85,7 +82,7 @@ post_init .. data:: django.db.models.signals.post_init :module: -Like pre_init, but this one is sent when the :meth:`~django.db.models.Model.__init__`: method finishes. +Like pre_init, but this one is sent when the ``__init__()`` method finishes. Arguments sent with this signal: @@ -212,24 +209,24 @@ m2m_changed .. data:: django.db.models.signals.m2m_changed :module: -Sent when a :class:`ManyToManyField` is changed on a model instance. -Strictly speaking, this is not a model signal since it is sent by the -:class:`ManyToManyField`, but since it complements the +Sent when a :class:`~django.db.models.ManyToManyField` is changed on a model +instance. Strictly speaking, this is not a model signal since it is sent by the +:class:`~django.db.models.ManyToManyField`, but since it complements the :data:`pre_save`/:data:`post_save` and :data:`pre_delete`/:data:`post_delete` when it comes to tracking changes to models, it is included here. Arguments sent with this signal: ``sender`` - The intermediate model class describing the :class:`ManyToManyField`. - This class is automatically created when a many-to-many field is - defined; you can access it using the ``through`` attribute on the - many-to-many field. + The intermediate model class describing the + :class:`~django.db.models.ManyToManyField`. This class is automatically + created when a many-to-many field is defined; you can access it using the + ``through`` attribute on the many-to-many field. ``instance`` The instance whose many-to-many relation is updated. This can be an - instance of the ``sender``, or of the class the :class:`ManyToManyField` - is related to. + instance of the ``sender``, or of the class the + :class:`~django.db.models.ManyToManyField` is related to. ``action`` A string indicating the type of update that is done on the relation. @@ -303,8 +300,9 @@ Argument Value ``action`` ``"pre_add"`` (followed by a separate signal with ``"post_add"``) -``reverse`` ``False`` (``Pizza`` contains the :class:`ManyToManyField`, - so this call modifies the forward relation) +``reverse`` ``False`` (``Pizza`` contains the + :class:`~django.db.models.ManyToManyField`, so this call + modifies the forward relation) ``model`` ``Topping`` (the class of the objects added to the ``Pizza``) @@ -329,8 +327,9 @@ Argument Value ``action`` ``"pre_remove"`` (followed by a separate signal with ``"post_remove"``) -``reverse`` ``True`` (``Pizza`` contains the :class:`ManyToManyField`, - so this call modifies the reverse relation) +``reverse`` ``True`` (``Pizza`` contains the + :class:`~django.db.models.ManyToManyField`, so this call + modifies the reverse relation) ``model`` ``Pizza`` (the class of the objects removed from the ``Topping``) @@ -407,6 +406,10 @@ Arguments sent with this signal: For example, the :mod:`django.contrib.auth` app only prompts to create a superuser when ``interactive`` is ``True``. +``db`` + The database alias used for synchronization. Defaults to the ``default`` + database. + For example, ``yourapp/management/__init__.py`` could be written like:: from django.db.models.signals import post_syncdb @@ -437,9 +440,8 @@ Sent when Django begins processing an HTTP request. Arguments sent with this signal: ``sender`` - The handler class -- e.g. - :class:`django.core.handlers.wsgi.WsgiHandler` -- that handled - the request. + The handler class -- e.g. ``django.core.handlers.wsgi.WsgiHandler`` -- that + handled the request. request_finished ---------------- @@ -449,6 +451,18 @@ request_finished Sent when Django finishes processing an HTTP request. +.. note:: + + When a view returns a :ref:`streaming response <httpresponse-streaming>`, + this signal is sent only after the entire response is consumed by the + client (strictly speaking, by the WSGI gateway). + +.. versionchanged:: 1.5 + + Before Django 1.5, this signal was fired before sending the content to the + client. In order to accomodate streaming responses, it is now fired after + sending the content. + Arguments sent with this signal: ``sender`` @@ -476,18 +490,16 @@ Test signals .. module:: django.test.signals :synopsis: Signals sent during testing. -Signals only sent when :doc:`running tests </topics/testing>`. +Signals only sent when :ref:`running tests <running-tests>`. setting_changed --------------- -.. versionadded:: 1.4 - .. data:: django.test.signals.setting_changed :module: This signal is sent when the value of a setting is changed through the -:meth:`django.test.TestCase.setting` context manager or the +``django.test.TestCase.settings()`` context manager or the :func:`django.test.utils.override_settings` decorator/context manager. It's actually sent twice: when the new value is applied ("setup") and when the @@ -549,8 +561,8 @@ Arguments sent with this signal: ``sender`` The database wrapper class -- i.e. - :class:`django.db.backends.postgresql_psycopg2.DatabaseWrapper` or - :class:`django.db.backends.mysql.DatabaseWrapper`, etc. + ``django.db.backends.postgresql_psycopg2.DatabaseWrapper`` or + ``django.db.backends.mysql.DatabaseWrapper``, etc. ``connection`` The database connection that was opened. This can be used in a diff --git a/docs/ref/template-response.txt b/docs/ref/template-response.txt index d9b7130362..5c13ec7d96 100644 --- a/docs/ref/template-response.txt +++ b/docs/ref/template-response.txt @@ -56,11 +56,11 @@ Attributes Methods ------- -.. method:: SimpleTemplateResponse.__init__(template, context=None, mimetype=None, status=None, content_type=None) +.. method:: SimpleTemplateResponse.__init__(template, context=None, content_type=None, status=None) Instantiates a :class:`~django.template.response.SimpleTemplateResponse` object - with the given template, context, MIME type and HTTP status. + with the given template, context, content type, and HTTP status. ``template`` The full name of a template, or a sequence of template names. @@ -75,12 +75,15 @@ Methods The HTTP Status code for the response. ``content_type`` - An alias for ``mimetype``. Historically, this parameter was only called - ``mimetype``, but since this is actually the value included in the HTTP - ``Content-Type`` header, it can also include the character set encoding, - which makes it more than just a MIME type specification. If ``mimetype`` - is specified (not ``None``), that value is used. Otherwise, - ``content_type`` is used. If neither is given, + + .. versionchanged:: 1.5 + + Historically, this parameter was only called ``mimetype`` (now + deprecated), but since this is actually the value included in the HTTP + ``Content-Type`` header, it can also include the character set + encoding, which makes it more than just a MIME type specification. If + ``mimetype`` is specified (not ``None``), that value is used. + Otherwise, ``content_type`` is used. If neither is given, :setting:`DEFAULT_CONTENT_TYPE` is used. @@ -117,19 +120,18 @@ Methods rendered :class:`~django.template.response.SimpleTemplateResponse` instance. - If the callback returns a value that is not `None`, this will be + If the callback returns a value that is not ``None``, this will be used as the response instead of the original response object (and will be passed to the next post rendering callback etc.) -.. method:: SimpleTemplateResponse.render(): +.. method:: SimpleTemplateResponse.render() - Sets :attr:`response.content` to the result obtained by + Sets ``response.content`` to the result obtained by :attr:`SimpleTemplateResponse.rendered_content`, runs all post-rendering callbacks, and returns the resulting response object. - :meth:`~SimpleTemplateResponse.render()` will only have an effect - the first time it is called. On subsequent calls, it will return - the result obtained from the first call. + ``render()`` will only have an effect the first time it is called. On + subsequent calls, it will return the result obtained from the first call. TemplateResponse objects @@ -145,7 +147,7 @@ TemplateResponse objects Methods ------- -.. method:: TemplateResponse.__init__(request, template, context=None, mimetype=None, status=None, content_type=None, current_app=None) +.. method:: TemplateResponse.__init__(request, template, context=None, content_type=None, status=None, current_app=None) Instantiates an ``TemplateResponse`` object with the given template, context, MIME type and HTTP status. @@ -166,12 +168,15 @@ Methods The HTTP Status code for the response. ``content_type`` - An alias for ``mimetype``. Historically, this parameter was only called - ``mimetype``, but since this is actually the value included in the HTTP - ``Content-Type`` header, it can also include the character set encoding, - which makes it more than just a MIME type specification. If ``mimetype`` - is specified (not ``None``), that value is used. Otherwise, - ``content_type`` is used. If neither is given, + + .. versionchanged:: 1.5 + + Historically, this parameter was only called ``mimetype`` (now + deprecated), but since this is actually the value included in the HTTP + ``Content-Type`` header, it can also include the character set + encoding, which makes it more than just a MIME type specification. If + ``mimetype`` is specified (not ``None``), that value is used. + Otherwise, ``content_type`` is used. If neither is given, :setting:`DEFAULT_CONTENT_TYPE` is used. ``current_app`` @@ -188,24 +193,23 @@ returned to the client, it must be rendered. The rendering process takes the intermediate representation of template and context, and turns it into the final byte stream that can be served to the client. -There are three circumstances under which a TemplateResponse will be +There are three circumstances under which a ``TemplateResponse`` will be rendered: -* When the TemplateResponse instance is explicitly rendered, using +* When the ``TemplateResponse`` instance is explicitly rendered, using the :meth:`SimpleTemplateResponse.render()` method. * When the content of the response is explicitly set by assigning - :attr:`response.content`. + ``response.content``. * After passing through template response middleware, but before passing through response middleware. -A TemplateResponse can only be rendered once. The first call to -:meth:`SimpleTemplateResponse.render` sets the content of the -response; subsequent rendering calls do not change the response -content. +A ``TemplateResponse`` can only be rendered once. The first call to +:meth:`SimpleTemplateResponse.render` sets the content of the response; +subsequent rendering calls do not change the response content. -However, when :attr:`response.content` is explicitly assigned, the +However, when ``response.content`` is explicitly assigned, the change is always applied. If you want to force the content to be re-rendered, you can re-evaluate the rendered content, and assign the content of the response manually:: diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index db57d2de96..0162f78eed 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -221,13 +221,12 @@ straight lookups. Here are some things to keep in mind: self.database_record.delete() sensitive_function.alters_data = True -* .. versionadded:: 1.4 - Occasionally you may want to turn off this feature for other reasons, - and tell the template system to leave a variable un-called no matter - what. To do so, set a ``do_not_call_in_templates`` attribute on the - callable with the value ``True``. The template system then will act as - if your variable is not callable (allowing you to access attributes of - the callable, for example). +* Occasionally you may want to turn off this feature for other reasons, + and tell the template system to leave a variable un-called no matter + what. To do so, set a ``do_not_call_in_templates`` attribute on the + callable with the value ``True``. The template system then will act as + if your variable is not callable (allowing you to access attributes of + the callable, for example). .. _invalid-template-variables: @@ -558,15 +557,17 @@ Note that these paths should use Unix-style forward slashes, even on Windows. The Python API ~~~~~~~~~~~~~~ -Django has two ways to load templates from files: +.. module:: django.template.loader -.. function:: django.template.loader.get_template(template_name) +``django.template.loader`` has two functions to load templates from files: + +.. function:: get_template(template_name) ``get_template`` returns the compiled template (a ``Template`` object) for the template with the given name. If the template doesn't exist, it raises ``django.template.TemplateDoesNotExist``. -.. function:: django.template.loader.select_template(template_name_list) +.. function:: select_template(template_name_list) ``select_template`` is just like ``get_template``, except it takes a list of template names. Of the list, it returns the first template that exists. @@ -631,11 +632,19 @@ by editing your :setting:`TEMPLATE_LOADERS` setting. :setting:`TEMPLATE_LOADERS` should be a tuple of strings, where each string represents a template loader class. Here are the template loaders that come with Django: +.. currentmodule:: django.template.loaders + ``django.template.loaders.filesystem.Loader`` + +.. class:: filesystem.Loader + Loads templates from the filesystem, according to :setting:`TEMPLATE_DIRS`. This loader is enabled by default. ``django.template.loaders.app_directories.Loader`` + +.. class:: app_directories.Loader + Loads templates from Django apps on the filesystem. For each app in :setting:`INSTALLED_APPS`, the loader looks for a ``templates`` subdirectory. If the directory exists, Django looks for templates in there. @@ -670,12 +679,18 @@ class. Here are the template loaders that come with Django: This loader is enabled by default. ``django.template.loaders.eggs.Loader`` + +.. class:: eggs.Loader + Just like ``app_directories`` above, but it loads templates from Python eggs rather than from the filesystem. This loader is disabled by default. ``django.template.loaders.cached.Loader`` + +.. class:: cached.Loader + By default, the templating system will read and compile your templates every time they need to be rendered. While the Django templating system is quite fast, the overhead from reading and compiling templates can add up. diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 57ef0cfb27..123e114c4a 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -147,9 +147,8 @@ You can use any number of values in a ``{% cycle %}`` tag, separated by spaces. Values enclosed in single (``'``) or double quotes (``"``) are treated as string literals, while values without quotes are treated as template variables. -Note that the variables included in the cycle will not be escaped. -This is because template tags do not escape their content. Any HTML or -Javascript code contained in the printed variable will be rendered +Note that currently the variables included in the cycle will not be escaped. +Any HTML or Javascript code contained in the printed variable will be rendered as-is, which could potentially lead to security issues. For backwards compatibility, the ``{% cycle %}`` tag supports the much inferior @@ -172,7 +171,7 @@ just declare the cycle, but not output the first value, you can add a {% for obj in some_list %} {% cycle 'row1' 'row2' as rowcolors silent %} - <tr class="{{ rowcolors }}">{% include "subtemplate.html " %}</tr> + <tr class="{{ rowcolors }}">{% include "subtemplate.html" %}</tr> {% endfor %} This will output a list of ``<tr>`` elements with ``class`` @@ -190,6 +189,22 @@ call to ``{% cycle %}`` doesn't specify silent:: {% cycle 'row1' 'row2' as rowcolors silent %} {% cycle rowcolors %} +.. versionchanged:: 1.6 + +To improve safety, future versions of ``cycle`` will automatically escape +their output. You're encouraged to activate this behavior by loading +``cycle`` from the ``future`` template library:: + + {% load cycle from future %} + +When using the ``future`` version, you can disable auto-escaping with:: + + {% for o in some_list %} + <tr class="{% autoescape off %}{% cycle rowvalue1 rowvalue2 %}{% endautoescape %}"> + ... + </tr> + {% endfor %} + .. templatetag:: debug debug @@ -257,28 +272,44 @@ This is equivalent to:: {% if var1 %} {{ var1|safe }} - {% else %}{% if var2 %} + {% elif var2 %} {{ var2|safe }} - {% else %}{% if var3 %} + {% elif var3 %} {{ var3|safe }} - {% endif %}{% endif %}{% endif %} + {% endif %} You can also use a literal string as a fallback value in case all passed variables are False:: {% firstof var1 var2 var3 "fallback value" %} -Note that the variables included in the firstof tag will not be -escaped. This is because template tags do not escape their content. -Any HTML or Javascript code contained in the printed variable will be -rendered as-is, which could potentially lead to security issues. If you -need to escape the variables in the firstof tag, you must do so -explicitly:: +Note that currently the variables included in the firstof tag will not be +escaped. Any HTML or Javascript code contained in the printed variable will be +rendered as-is, which could potentially lead to security issues. If you need +to escape the variables in the firstof tag, you must do so explicitly:: {% filter force_escape %} {% firstof var1 var2 var3 "fallback value" %} {% endfilter %} +.. versionchanged:: 1.6 + +To improve safety, future versions of ``firstof`` will automatically escape +their output. You're encouraged to activate this behavior by loading +``firstof`` from the ``future`` template library:: + + {% load firstof from future %} + +When using the ``future`` version, you can disable auto-escaping with:: + + {% autoescape off %} + {% firstof var1 var2 var3 "<strong>fallback value</strong>" %} + {% endautoescape %} + +Or if only some variables should be escaped, you can use:: + + {% firstof var1 var2|safe var3 "<strong>fallback value</strong>"|safe %} + .. templatetag:: for for @@ -377,14 +408,10 @@ block are output:: In the above, if ``athlete_list`` is not empty, the number of athletes will be displayed by the ``{{ athlete_list|length }}`` variable. -As you can see, the ``if`` tag may take one or several `` {% elif %}`` +As you can see, the ``if`` tag may take one or several ``{% elif %}`` clauses, as well as an ``{% else %}`` clause that will be displayed if all previous conditions fail. These clauses are optional. -.. versionadded:: 1.4 - -The ``if`` tag now supports ``{% elif %}`` clauses. - Boolean operators ^^^^^^^^^^^^^^^^^ @@ -743,8 +770,6 @@ escaped, because it's not a format character:: This would display as "It is the 4th of September". -.. versionchanged:: 1.4 - .. note:: The format passed can also be one of the predefined ones @@ -864,7 +889,7 @@ an attribute "description," you could use:: {% regroup cities by country.description as country_list %} Or, if ``country`` is a field with ``choices``, it will have a -:meth:`^django.db.models.Model.get_FOO_display` method available as an +:meth:`~django.db.models.Model.get_FOO_display` method available as an attribute, allowing you to group on the display string rather than the ``choices`` key:: @@ -1079,11 +1104,11 @@ value to a maximum value, and then applies that ratio to a constant. For example:: <img src="bar.png" alt="Bar" - height="10" width="{% widthratio this_value max_value 100 %}" /> + height="10" width="{% widthratio this_value max_value max_width %}" /> -Above, if ``this_value`` is 175 and ``max_value`` is 200, the image in the -above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5 -which is rounded up to 88). +If ``this_value`` is 175, ``max_value`` is 200, and ``max_width`` is 100, the +image in the above example will be 88 pixels wide +(because 175/200 = .875; .875 * 100 = 87.5 which is rounded up to 88). .. templatetag:: with @@ -1289,10 +1314,6 @@ Z Time zone offset in seconds. The ``-43200`` to ``4320 UTC is always positive. ================ ======================================== ===================== -.. versionadded:: 1.4 - -The ``e`` and ``o`` format specification characters were added in Django 1.4. - For example:: {{ value|date:"D d M Y" }} @@ -1915,7 +1936,7 @@ slice Returns a slice of the list. Uses the same syntax as Python's list slicing. See -http://diveintopython.net/native_data_types/lists.html#odbchelper.list.slice +http://www.diveintopython3.net/native-datatypes.html#slicinglists for an introduction. Example:: @@ -2069,8 +2090,6 @@ If ``value`` is ``"my first post"``, the output will be ``"My First Post"``. truncatechars ^^^^^^^^^^^^^ -.. versionadded:: 1.4 - Truncates a string if it is longer than the specified number of characters. Truncated strings will end with a translatable ellipsis sequence ("..."). @@ -2200,11 +2219,6 @@ It also supports domain-only links ending in one of the original top level domains (``.com``, ``.edu``, ``.gov``, ``.int``, ``.mil``, ``.net``, and ``.org``). For example, ``djangoproject.com`` gets converted. -.. versionchanged:: 1.4 - -Until Django 1.4, only the ``.com``, ``.net`` and ``.org`` suffixes were -supported for domain-only links. - Links can have trailing punctuation (periods, commas, close-parens) and leading punctuation (opening parens), and ``urlize`` will still do the right thing. @@ -2334,8 +2348,6 @@ See :ref:`topic-l10n-templates`. tz ^^ -.. versionadded:: 1.4 - This library provides control over time zone conversions in templates. Like ``l10n``, you only need to load the library using ``{% load tz %}``, but you'll usually also set :setting:`USE_TZ` to ``True`` so that conversion @@ -2356,16 +2368,6 @@ django.contrib.humanize A set of Django template filters useful for adding a "human touch" to data. See :doc:`/ref/contrib/humanize`. -django.contrib.markup -^^^^^^^^^^^^^^^^^^^^^ - -A collection of template filters that implement these common markup languages: - -* Textile -* Markdown -* reST (reStructuredText) - -See the :doc:`markup documentation </ref/contrib/markup>`. django.contrib.webdesign ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2416,8 +2418,10 @@ slightly different call:: The :mod:`staticfiles<django.contrib.staticfiles>` contrib app also ships with a :ttag:`static template tag<staticfiles-static>` which uses ``staticfiles'`` :setting:`STATICFILES_STORAGE` to build the URL of the - given path. Use that instead if you have an advanced use case such as - :ref:`using a cloud service to serve static files<staticfiles-from-cdn>`:: + given path (rather than simply using :func:`urlparse.urljoin` with the + :setting:`STATIC_URL` setting and the given path). Use that instead if you + have an advanced use case such as :ref:`using a cloud service to serve + static files<staticfiles-from-cdn>`:: {% load static from staticfiles %} <img src="{% static "images/hi.jpg" %}" alt="Hi!" /> diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt index 784ff33398..bd5bdc96a9 100644 --- a/docs/ref/unicode.txt +++ b/docs/ref/unicode.txt @@ -20,14 +20,14 @@ able to store certain characters in the database, and information will be lost. * MySQL users, refer to the `MySQL manual`_ (section 9.1.3.2 for MySQL 5.1) for details on how to set or alter the database character set encoding. -* PostgreSQL users, refer to the `PostgreSQL manual`_ (section 21.2.2 in - PostgreSQL 8) for details on creating databases with the correct encoding. +* PostgreSQL users, refer to the `PostgreSQL manual`_ (section 22.3.2 in + PostgreSQL 9) for details on creating databases with the correct encoding. * SQLite users, there is nothing you need to do. SQLite always uses UTF-8 for internal encoding. .. _MySQL manual: http://dev.mysql.com/doc/refman/5.1/en/charset-database.html -.. _PostgreSQL manual: http://www.postgresql.org/docs/8.2/static/multibyte.html#AEN24104 +.. _PostgreSQL manual: http://www.postgresql.org/docs/current/static/multibyte.html All of Django's database backends automatically convert Unicode strings into the appropriate encoding for talking to the database. They also automatically @@ -68,7 +68,7 @@ Python 2 with unicode literals or Python 3:: See also :doc:`Python 3 compatibility </topics/python3>`. -.. admonition:: Warning +.. warning:: A bytestring does not carry any information with it about its encoding. For that reason, we have to make an assumption, and Django assumes that all diff --git a/docs/ref/urlresolvers.txt b/docs/ref/urlresolvers.txt index 528f172061..87c0605a11 100644 --- a/docs/ref/urlresolvers.txt +++ b/docs/ref/urlresolvers.txt @@ -71,8 +71,6 @@ You can use ``kwargs`` instead of ``args``. For example:: reverse_lazy() -------------- -.. versionadded:: 1.4 - A lazily evaluated version of `reverse()`_. .. function:: reverse_lazy(viewname, [urlconf=None, args=None, kwargs=None, current_app=None]) diff --git a/docs/ref/urls.txt b/docs/ref/urls.txt index b9a0199984..e68edc8254 100644 --- a/docs/ref/urls.txt +++ b/docs/ref/urls.txt @@ -4,14 +4,6 @@ .. module:: django.conf.urls -.. versionchanged:: 1.4 - Starting with Django 1.4 functions ``patterns``, ``url``, ``include`` plus - the ``handler*`` symbols described below live in the ``django.conf.urls`` - module. - - Until Django 1.3 they were located in ``django.conf.urls.defaults``. You - still can import them from there but it will be removed in Django 1.6. - patterns() ---------- @@ -31,12 +23,12 @@ The ``optional_dictionary`` and ``optional_name`` parameters are described in :ref:`Passing extra options to view functions <views-extra-options>`. .. note:: - Because `patterns()` is a function call, it accepts a maximum of 255 + Because ``patterns()`` is a function call, it accepts a maximum of 255 arguments (URL patterns, in this case). This is a limit for all Python function calls. This is rarely a problem in practice, because you'll - typically structure your URL patterns modularly by using `include()` + typically structure your URL patterns modularly by using ``include()`` sections. However, on the off-chance you do hit the 255-argument limit, - realize that `patterns()` returns a Python list, so you can split up the + realize that ``patterns()`` returns a Python list, so you can split up the construction of the list. :: @@ -52,6 +44,20 @@ The ``optional_dictionary`` and ``optional_name`` parameters are described in patterns you can construct. The only limit is that you can only create 254 at a time (the 255th argument is the initial prefix argument). +static() +-------- + +.. function:: static.static(prefix, view='django.views.static.serve', **kwargs) + +Helper function to return a URL pattern for serving files in debug mode:: + + from django.conf import settings + from django.conf.urls.static import static + + urlpatterns = patterns('', + # ... the rest of your URLconf goes here ... + ) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) + url() ----- @@ -94,7 +100,6 @@ include() application and instance namespaces. :arg module: URLconf module (or module name) - :type module: Module or string :arg namespace: Instance namespace for the URL entries being included :type namespace: string :arg app_name: Application namespace for the URL entries being included @@ -122,9 +127,6 @@ value should suffice. See the documentation about :ref:`the 403 (HTTP Forbidden) view <http_forbidden_view>` for more information. -.. versionadded:: 1.4 - ``handler403`` is new in Django 1.4. - handler404 ---------- @@ -153,4 +155,3 @@ value should suffice. See the documentation about :ref:`the 500 (HTTP Internal Server Error) view <http_internal_server_error_view>` for more information. - diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index 2f12c3a96c..a7d5b6690e 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -138,15 +138,13 @@ results. Instead do:: ``django.utils.dateparse`` ========================== -.. versionadded:: 1.4 - .. module:: django.utils.dateparse :synopsis: Functions to parse datetime objects. The functions defined in this module share the following properties: -- They raise :exc:`ValueError` if their input is well formatted but isn't a - valid date or time. +- They raise :exc:`~exceptions.ValueError` if their input is well formatted but + isn't a valid date or time. - They return ``None`` if it isn't well formatted at all. - They accept up to picosecond resolution in input, but they truncate it to microseconds, since that's what Python supports. @@ -192,8 +190,7 @@ The functions defined in this module share the following properties: Like ``decorator_from_middleware``, but returns a function that accepts the arguments to be passed to the middleware_class. For example, the :func:`~django.views.decorators.cache.cache_page` - decorator is created from the - :class:`~django.middleware.cache.CacheMiddleware` like this:: + decorator is created from the ``CacheMiddleware`` like this:: cache_page = decorator_from_middleware_with_args(CacheMiddleware) @@ -284,15 +281,15 @@ The functions defined in this module share the following properties: .. function:: smart_str(s, encoding='utf-8', strings_only=False, errors='strict') Alias of :func:`smart_bytes` on Python 2 and :func:`smart_text` on Python - 3. This function returns a :class:`str` or a lazy string. + 3. This function returns a ``str`` or a lazy string. - For instance, this is suitable for writing to :attr:`sys.stdout` on + For instance, this is suitable for writing to :data:`sys.stdout` on Python 2 and 3. .. function:: force_str(s, encoding='utf-8', strings_only=False, errors='strict') Alias of :func:`force_bytes` on Python 2 and :func:`force_text` on Python - 3. This function always returns a :class:`str`. + 3. This function always returns a ``str``. .. function:: iri_to_uri(iri) @@ -532,7 +529,7 @@ escaping HTML. .. code-block:: python - format_html(u"%{0} <b>{1}</b> {2}", + format_html(u"{0} <b>{1}</b> {2}", mark_safe(some_html), some_text, some_other_text) This has the advantage that you don't need to apply :func:`escape` to each @@ -544,6 +541,19 @@ escaping HTML. through :func:`conditional_escape` which (ultimately) calls :func:`~django.utils.encoding.force_text` on the values. +.. function:: format_html_join(sep, format_string, args_generator) + + A wrapper of :func:`format_html`, for the common case of a group of + arguments that need to be formatted using the same format string, and then + joined using ``sep``. ``sep`` is also passed through + :func:`conditional_escape`. + + ``args_generator`` should be an iterator that returns the sequence of + ``args`` that will be passed to :func:`format_html`. For example:: + + format_html_join('\n', "<li>{0} {1}</li>", ((u.first_name, u.last_name) + for u in users)) + .. function:: strip_tags(value) Removes anything that looks like an html tag from the string, that is @@ -558,11 +568,11 @@ escaping HTML. .. function:: remove_tags(value, tags) - Removes a list of [X]HTML tag names from the output. + Removes a space-separated list of [X]HTML tag names from the output. For example:: - remove_tags(value, ["b", "span"]) + remove_tags(value, "b span") If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"`` the return value will be ``"Joel <button>is</button> a slug"``. @@ -626,12 +636,34 @@ escaping HTML. .. function:: base36_to_int(s) Converts a base 36 string to an integer. On Python 2 the output is - guaranteed to be an :class:`int` and not a :class:`long`. + guaranteed to be an ``int`` and not a ``long``. .. function:: int_to_base36(i) Converts a positive integer to a base 36 string. On Python 2 ``i`` must be - smaller than :attr:`sys.maxint`. + smaller than :data:`sys.maxint`. + +``django.utils.module_loading`` +=============================== + +.. module:: django.utils.module_loading + :synopsis: Functions for working with Python modules. + +Functions for working with Python modules. + +.. function:: import_by_path(dotted_path, error_prefix='') + + Imports a dotted module path and returns the attribute/class designated by + the last name in the path. Raises + :exc:`~django.core.exceptions.ImproperlyConfigured` if something goes + wrong. For example:: + + from django.utils.module_loading import import_by_path + import_by_path = import_by_path('django.utils.module_loading.import_by_path') + + is equivalent to:: + + from django.utils.module_loading import import_by_path ``django.utils.safestring`` =========================== @@ -649,12 +681,12 @@ appropriate entities. .. versionadded:: 1.5 - A :class:`bytes` subclass that has been specifically marked as "safe" + A ``bytes`` subclass that has been specifically marked as "safe" (requires no further escaping) for HTML output purposes. .. class:: SafeString - A :class:`str` subclass that has been specifically marked as "safe" + A ``str`` subclass that has been specifically marked as "safe" (requires no further escaping) for HTML output purposes. This is :class:`SafeBytes` on Python 2 and :class:`SafeText` on Python 3. @@ -662,7 +694,7 @@ appropriate entities. .. versionadded:: 1.5 - A :class:`str` (in Python 3) or :class:`unicode` (in Python 2) subclass + A ``str`` (in Python 3) or ``unicode`` (in Python 2) subclass that has been specifically marked as "safe" for HTML output purposes. .. class:: SafeUnicode @@ -788,8 +820,6 @@ For a complete discussion on the usage of the following see the .. function:: override(language, deactivate=False) - .. versionadded:: 1.4 - A Python context manager that uses :func:`django.utils.translation.activate` to fetch the translation object for a given language, installing it as the translation object for the @@ -812,8 +842,6 @@ For a complete discussion on the usage of the following see the .. function:: get_language_from_request(request, check_path=False) - .. versionchanged:: 1.4 - Analyzes the request to find what language the user wants the system to show. Only languages listed in settings.LANGUAGES are taken into account. If the user requests a sublanguage where we have a main language, we send out the main @@ -838,8 +866,6 @@ For a complete discussion on the usage of the following see the ``django.utils.timezone`` ========================= -.. versionadded:: 1.4 - .. module:: django.utils.timezone :synopsis: Timezone support. diff --git a/docs/ref/validators.txt b/docs/ref/validators.txt index b68d6f2772..92e257ca85 100644 --- a/docs/ref/validators.txt +++ b/docs/ref/validators.txt @@ -96,7 +96,7 @@ to, or in lieu of custom ``field.clean()`` methods. ------------------ .. data:: validate_email - A :class:`RegexValidator` instance that ensures a value looks like an + An ``EmailValidator`` instance that ensures a value looks like an email address. ``validate_slug`` @@ -115,15 +115,13 @@ to, or in lieu of custom ``field.clean()`` methods. ``validate_ipv6_address`` ------------------------- -.. versionadded:: 1.4 .. data:: validate_ipv6_address - Uses :mod:`django.utils.ipv6` to check the validity of an IPv6 address. + Uses ``django.utils.ipv6`` to check the validity of an IPv6 address. ``validate_ipv46_address`` -------------------------- -.. versionadded:: 1.4 .. data:: validate_ipv46_address diff --git a/docs/ref/views.txt b/docs/ref/views.txt new file mode 100644 index 0000000000..3753f83f07 --- /dev/null +++ b/docs/ref/views.txt @@ -0,0 +1,48 @@ +============== +Built-in Views +============== + +.. module:: django.views + :synopsis: Django's built-in views. + +Several of Django's built-in views are documented in +:doc:`/topics/http/views` as well as elsewhere in the documentation. + +Serving files in development +---------------------------- + +.. function:: static.serve(request, path, document_root, show_indexes=False) + +There may be files other than your project's static assets that, for +convenience, you'd like to have Django serve for you in local development. +The :func:`~django.views.static.serve` view can be used to serve any directory +you give it. (This view is **not** hardened for production use and should be +used only as a development aid; you should serve these files in production +using a real front-end webserver). + +The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`. +``django.contrib.staticfiles`` is intended for static assets and has no +built-in handling for user-uploaded files, but you can have Django serve your +:setting:`MEDIA_ROOT` by appending something like this to your URLconf:: + + from django.conf import settings + + # ... the rest of your URLconf goes here ... + + if settings.DEBUG: + urlpatterns += patterns('', + url(r'^media/(?P<path>.*)$', 'django.views.static.serve', { + 'document_root': settings.MEDIA_ROOT, + }), + ) + +Note, the snippet assumes your :setting:`MEDIA_URL` has a value of +``'/media/'``. This will call the :func:`~django.views.static.serve` view, +passing in the path from the URLconf and the (required) ``document_root`` +parameter. + +Since it can become a bit cumbersome to define this URL pattern, Django +ships with a small URL helper function :func:`~django.conf.urls.static.static` +that takes as parameters the prefix such as :setting:`MEDIA_URL` and a dotted +path to a view, such as ``'django.views.static.serve'``. Any other function +parameter will be transparently passed to the view. |