diff options
| author | Luke Plant <L.Plant.98@cantab.net> | 2011-10-14 00:12:01 +0000 |
|---|---|---|
| committer | Luke Plant <L.Plant.98@cantab.net> | 2011-10-14 00:12:01 +0000 |
| commit | d1e5c55258d624058a93c8cacdb1f25ae7857554 (patch) | |
| tree | dca859edc2229f68b7511687aa8b333378786633 /docs/ref | |
| parent | 5109ac370928a5924887424b6d6c803038fcb691 (diff) | |
Fixed many more ReST indentation errors, somehow accidentally missed from [16955]
git-svn-id: http://code.djangoproject.com/svn/django/trunk@16983 bcc190cf-cafb-0310-a4f2-bffc1f526a37
Diffstat (limited to 'docs/ref')
43 files changed, 2212 insertions, 2235 deletions
diff --git a/docs/ref/class-based-views.txt b/docs/ref/class-based-views.txt index 5f1340be50..3c7f70f77d 100644 --- a/docs/ref/class-based-views.txt +++ b/docs/ref/class-based-views.txt @@ -41,13 +41,13 @@ usable generic views. For example, the :class:`~django.views.generic.base.detail.DetailView` is composed from: - * :class:`~django.db.views.generic.base.View`, which provides the - basic class-based behavior - * :class:`~django.db.views.generic.detail.SingleObjectMixin`, which - provides the utilities for retrieving and displaying a single object - * :class:`~django.db.views.generic.detail.SingleObjectTemplateResponseMixin`, - which provides the tools for rendering a single object into a - template-based response. +* :class:`~django.db.views.generic.base.View`, which provides the + basic class-based behavior +* :class:`~django.db.views.generic.detail.SingleObjectMixin`, which + provides the utilities for retrieving and displaying a single object +* :class:`~django.db.views.generic.detail.SingleObjectTemplateResponseMixin`, + which provides the tools for rendering a single object into a + template-based response. When combined, these mixins provide all the pieces necessary to provide a view over a single object that renders a template to produce @@ -192,9 +192,9 @@ SingleObjectMixin **Context** - * ``object``: The object that this view is displaying. If - ``context_object_name`` is specified, that variable will also be - set in the context, with the same value as ``object``. + * ``object``: The object that this view is displaying. If + ``context_object_name`` is specified, that variable will also be + set in the context, with the same value as ``object``. SingleObjectTemplateResponseMixin ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -210,7 +210,7 @@ SingleObjectTemplateResponseMixin **Extends** - * :class:`~django.views.generic.base.TemplateResponseMixin` + * :class:`~django.views.generic.base.TemplateResponseMixin` .. attribute:: template_name_field @@ -229,10 +229,10 @@ SingleObjectTemplateResponseMixin Returns a list of candidate template names. Returns the following list: - * the value of ``template_name`` on the view (if provided) - * the contents of the ``template_name_field`` field on the - object instance that the view is operating upon (if available) - * ``<app_label>/<object_name><template_name_suffix>.html`` + * the value of ``template_name`` on the view (if provided) + * the contents of the ``template_name_field`` field on the + object instance that the view is operating upon (if available) + * ``<app_label>/<object_name><template_name_suffix>.html`` Multiple object mixins ---------------------- @@ -248,15 +248,15 @@ MultipleObjectMixin If ``paginate_by`` is specified, Django will paginate the results returned by this. You can specify the page number in the URL in one of two ways: - * Use the ``page`` parameter in the URLconf. For example, this is what - your URLconf might look like:: + * Use the ``page`` parameter in the URLconf. For example, this is what + your URLconf might look like:: - (r'^objects/page(?P<page>[0-9]+)/$', PaginatedView.as_view()) + (r'^objects/page(?P<page>[0-9]+)/$', PaginatedView.as_view()) - * Pass the page number via the ``page`` query-string parameter. For - example, a URL would look like this:: + * Pass the page number via the ``page`` query-string parameter. For + example, a URL would look like this:: - /objects/?page=3 + /objects/?page=3 These values and lists are 1-based, not 0-based, so the first page would be represented as page ``1``. @@ -363,22 +363,22 @@ MultipleObjectMixin **Context** - * ``object_list``: The list of objects that this view is displaying. If - ``context_object_name`` is specified, that variable will also be set - in the context, with the same value as ``object_list``. + * ``object_list``: The list of objects that this view is displaying. If + ``context_object_name`` is specified, that variable will also be set + in the context, with the same value as ``object_list``. - * ``is_paginated``: A boolean representing whether the results are - paginated. Specifically, this is set to ``False`` if no page size has - been specified, or if the available objects do not span multiple - pages. + * ``is_paginated``: A boolean representing whether the results are + paginated. Specifically, this is set to ``False`` if no page size has + been specified, or if the available objects do not span multiple + pages. - * ``paginator``: An instance of - :class:`django.core.paginator.Paginator`. If the page is not - paginated, this context variable will be ``None``. + * ``paginator``: An instance of + :class:`django.core.paginator.Paginator`. If the page is not + paginated, this context variable will be ``None``. - * ``page_obj``: An instance of - :class:`django.core.paginator.Page`. If the page is not paginated, - this context variable will be ``None``. + * ``page_obj``: An instance of + :class:`django.core.paginator.Page`. If the page is not paginated, + this context variable will be ``None``. MultipleObjectTemplateResponseMixin ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -392,7 +392,7 @@ MultipleObjectTemplateResponseMixin **Extends** - * :class:`~django.views.generic.base.TemplateResponseMixin` + * :class:`~django.views.generic.base.TemplateResponseMixin` .. attribute:: template_name_suffix @@ -403,8 +403,8 @@ MultipleObjectTemplateResponseMixin Returns a list of candidate template names. Returns the following list: - * the value of ``template_name`` on the view (if provided) - * ``<app_label>/<object_name><template_name_suffix>.html`` + * the value of ``template_name`` on the view (if provided) + * ``<app_label>/<object_name><template_name_suffix>.html`` Editing mixins -------------- @@ -471,7 +471,7 @@ FormMixin **Context** - * ``form``: The form instance that was generated for the view. + * ``form``: The form instance that was generated for the view. .. note:: @@ -495,8 +495,8 @@ ModelFormMixin **Mixins** - * :class:`django.views.generic.edit.FormMixin` - * :class:`django.views.generic.detail.SingleObjectMixin` + * :class:`django.views.generic.edit.FormMixin` + * :class:`django.views.generic.detail.SingleObjectMixin` .. attribute:: success_url @@ -604,9 +604,9 @@ YearMixin Returns the year for which this view will display data. 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 :attr:`YearMixin.year` attribute. + * 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. @@ -637,9 +637,9 @@ MonthMixin Returns the month for which this view will display data. 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 :attr:`MonthMixin.month` attribute. + * 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. @@ -683,9 +683,9 @@ DayMixin Returns the day for which this view will display data. 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 :attr:`DayMixin.day` attribute. + * 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. @@ -728,9 +728,9 @@ WeekMixin Returns the week for which this view will display data. 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 :attr:`WeekMixin.week` attribute. + * 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. @@ -782,8 +782,8 @@ BaseDateListView **Mixins** - * :class:`~django.views.generic.dates.DateMixin` - * :class:`~django.views.generic.list.MultipleObjectMixin` + * :class:`~django.views.generic.dates.DateMixin` + * :class:`~django.views.generic.list.MultipleObjectMixin` .. attribute:: allow_empty @@ -888,7 +888,7 @@ TemplateView **Mixins** - * :class:`django.views.generic.base.TemplateResponseMixin` + * :class:`django.views.generic.base.TemplateResponseMixin` .. attribute:: template_name @@ -901,8 +901,8 @@ TemplateView **Context** - * ``params``: The dictionary of keyword arguments captured from the URL - pattern that served the view. + * ``params``: The dictionary of keyword arguments captured from the URL + pattern that served the view. RedirectView ~~~~~~~~~~~~ @@ -971,8 +971,8 @@ DetailView **Mixins** - * :class:`django.views.generic.detail.SingleObjectMixin` - * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin` + * :class:`django.views.generic.detail.SingleObjectMixin` + * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin` List views ---------- @@ -997,8 +997,8 @@ ListView **Mixins** - * :class:`django.views.generic.list.MultipleObjectMixin` - * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` + * :class:`django.views.generic.list.MultipleObjectMixin` + * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` Editing views @@ -1020,8 +1020,8 @@ FormView **Mixins** - * :class:`django.views.generic.edit.FormMixin` - * :class:`django.views.generic.edit.ProcessFormView` + * :class:`django.views.generic.edit.FormMixin` + * :class:`django.views.generic.edit.ProcessFormView` CreateView ~~~~~~~~~~ @@ -1037,8 +1037,8 @@ CreateView **Mixins** - * :class:`django.views.generic.edit.ModelFormMixin` - * :class:`django.views.generic.edit.ProcessFormView` + * :class:`django.views.generic.edit.ModelFormMixin` + * :class:`django.views.generic.edit.ProcessFormView` UpdateView ~~~~~~~~~~ @@ -1056,8 +1056,8 @@ UpdateView **Mixins** - * :class:`django.views.generic.edit.ModelFormMixin` - * :class:`django.views.generic.edit.ProcessFormView` + * :class:`django.views.generic.edit.ModelFormMixin` + * :class:`django.views.generic.edit.ProcessFormView` DeleteView ~~~~~~~~~~ @@ -1075,13 +1075,13 @@ DeleteView **Mixins** - * :class:`django.views.generic.edit.DeletionMixin` - * :class:`django.views.generic.detail.BaseDetailView` + * :class:`django.views.generic.edit.DeletionMixin` + * :class:`django.views.generic.detail.BaseDetailView` **Notes** - * The delete confirmation page displayed to a GET request uses a - ``template_name_suffix`` of ``'_confirm_delete'``. + * The delete confirmation page displayed to a GET request uses a + ``template_name_suffix`` of ``'_confirm_delete'``. Date-based views ---------------- @@ -1107,13 +1107,13 @@ ArchiveIndexView **Mixins** - * :class:`django.views.generic.dates.BaseDateListView` - * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` + * :class:`django.views.generic.dates.BaseDateListView` + * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` **Notes** - * Uses a default ``context_object_name`` of ``latest``. - * Uses a default ``template_name_suffix`` of ``_archive``. + * Uses a default ``context_object_name`` of ``latest``. + * Uses a default ``template_name_suffix`` of ``_archive``. YearArchiveView ~~~~~~~~~~~~~~~ @@ -1131,9 +1131,9 @@ YearArchiveView **Mixins** - * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` - * :class:`django.views.generic.dates.YearMixin` - * :class:`django.views.generic.dates.BaseDateListView` + * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` + * :class:`django.views.generic.dates.YearMixin` + * :class:`django.views.generic.dates.BaseDateListView` .. attribute:: make_object_list @@ -1154,15 +1154,15 @@ YearArchiveView :class:`django.views.generic.dates.BaseDateListView`), the template's context will be: - * ``date_list``: A ``DateQuerySet`` object containing all months that - have objects available according to ``queryset``, represented as - ``datetime.datetime`` objects, in ascending order. + * ``date_list``: A ``DateQuerySet`` object containing all months that + have objects available according to ``queryset``, represented as + ``datetime.datetime`` objects, in ascending order. - * ``year``: The given year, as a four-character string. + * ``year``: The given year, as a four-character string. **Notes** - * Uses a default ``template_name_suffix`` of ``_archive_year``. + * Uses a default ``template_name_suffix`` of ``_archive_year``. MonthArchiveView ~~~~~~~~~~~~~~~~ @@ -1181,10 +1181,10 @@ MonthArchiveView **Mixins** - * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` - * :class:`django.views.generic.dates.YearMixin` - * :class:`django.views.generic.dates.MonthMixin` - * :class:`django.views.generic.dates.BaseDateListView` + * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` + * :class:`django.views.generic.dates.YearMixin` + * :class:`django.views.generic.dates.MonthMixin` + * :class:`django.views.generic.dates.BaseDateListView` **Context** @@ -1193,23 +1193,23 @@ MonthArchiveView :class:`~django.views.generic.dates.BaseDateListView`), the template's context will be: - * ``date_list``: A ``DateQuerySet`` object containing all days that - have objects available in the given month, according to ``queryset``, - represented as ``datetime.datetime`` objects, in ascending order. + * ``date_list``: A ``DateQuerySet`` object containing all days that + have objects available in the given month, according to ``queryset``, + represented as ``datetime.datetime`` objects, in ascending order. - * ``month``: A ``datetime.date`` object representing the given month. + * ``month``: A ``datetime.date`` object representing the given month. - * ``next_month``: A ``datetime.date`` object representing the first day - of the next month. If the next month is in the future, this will be - ``None``. + * ``next_month``: A ``datetime.date`` object representing the first day + of the next month. If the next month is in the future, this will be + ``None``. - * ``previous_month``: A ``datetime.date`` object representing the first - day of the previous month. Unlike ``next_month``, this will never be - ``None``. + * ``previous_month``: A ``datetime.date`` object representing the first + day of the previous month. Unlike ``next_month``, this will never be + ``None``. **Notes** - * Uses a default ``template_name_suffix`` of ``_archive_month``. + * Uses a default ``template_name_suffix`` of ``_archive_month``. WeekArchiveView ~~~~~~~~~~~~~~~ @@ -1227,10 +1227,10 @@ WeekArchiveView **Mixins** - * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` - * :class:`django.views.generic.dates.YearMixin` - * :class:`django.views.generic.dates.MonthMixin` - * :class:`django.views.generic.dates.BaseDateListView` + * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` + * :class:`django.views.generic.dates.YearMixin` + * :class:`django.views.generic.dates.MonthMixin` + * :class:`django.views.generic.dates.BaseDateListView` **Context** @@ -1239,12 +1239,12 @@ WeekArchiveView :class:`~django.views.generic.dates.BaseDateListView`), the template's context will be: - * ``week``: A ``datetime.date`` object representing the first day of - the given week. + * ``week``: A ``datetime.date`` object representing the first day of + the given week. **Notes** - * Uses a default ``template_name_suffix`` of ``_archive_week``. + * Uses a default ``template_name_suffix`` of ``_archive_week``. DayArchiveView ~~~~~~~~~~~~~~ @@ -1262,11 +1262,11 @@ DayArchiveView **Mixins** - * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` - * :class:`django.views.generic.dates.YearMixin` - * :class:`django.views.generic.dates.MonthMixin` - * :class:`django.views.generic.dates.DayMixin` - * :class:`django.views.generic.dates.BaseDateListView` + * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` + * :class:`django.views.generic.dates.YearMixin` + * :class:`django.views.generic.dates.MonthMixin` + * :class:`django.views.generic.dates.DayMixin` + * :class:`django.views.generic.dates.BaseDateListView` **Context** @@ -1275,25 +1275,25 @@ DayArchiveView :class:`~django.views.generic.dates.BaseDateListView`), the template's context will be: - * ``day``: A ``datetime.date`` object representing the given day. + * ``day``: A ``datetime.date`` object representing the given day. - * ``next_day``: A ``datetime.date`` object representing the next day. - If the next day is in the future, this will be ``None``. + * ``next_day``: A ``datetime.date`` object representing the next day. + If the next day is in the future, this will be ``None``. - * ``previous_day``: A ``datetime.date`` object representing the - previous day. Unlike ``next_day``, this will never be ``None``. + * ``previous_day``: A ``datetime.date`` object representing the + previous day. Unlike ``next_day``, this will never be ``None``. - * ``next_month``: A ``datetime.date`` object representing the first day - of the next month. If the next month is in the future, this will be - ``None``. + * ``next_month``: A ``datetime.date`` object representing the first day + of the next month. If the next month is in the future, this will be + ``None``. - * ``previous_month``: A ``datetime.date`` object representing the first - day of the previous month. Unlike ``next_month``, this will never be - ``None``. + * ``previous_month``: A ``datetime.date`` object representing the first + day of the previous month. Unlike ``next_month``, this will never be + ``None``. **Notes** - * Uses a default ``template_name_suffix`` of ``_archive_day``. + * Uses a default ``template_name_suffix`` of ``_archive_day``. TodayArchiveView ~~~~~~~~~~~~~~~~ @@ -1311,8 +1311,8 @@ TodayArchiveView **Mixins** - * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` - * :class:`django.views.generic.dates.BaseDayArchiveView` + * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin` + * :class:`django.views.generic.dates.BaseDayArchiveView` DateDetailView ~~~~~~~~~~~~~~ @@ -1330,9 +1330,9 @@ DateDetailView **Mixins** - * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin` - * :class:`django.views.generic.detail.BaseDetailView` - * :class:`django.views.generic.dates.DateMixin` - * :class:`django.views.generic.dates.YearMixin` - * :class:`django.views.generic.dates.MonthMixin` - * :class:`django.views.generic.dates.DayMixin` + * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin` + * :class:`django.views.generic.detail.BaseDetailView` + * :class:`django.views.generic.dates.DateMixin` + * :class:`django.views.generic.dates.YearMixin` + * :class:`django.views.generic.dates.MonthMixin` + * :class:`django.views.generic.dates.DayMixin` diff --git a/docs/ref/contrib/admin/actions.txt b/docs/ref/contrib/admin/actions.txt index a7ba4e8706..3f3b52983b 100644 --- a/docs/ref/contrib/admin/actions.txt +++ b/docs/ref/contrib/admin/actions.txt @@ -73,10 +73,10 @@ First, we'll need to write a function that gets called when the action is trigged from the admin. Action functions are just regular functions that take three arguments: - * The current :class:`ModelAdmin` - * An :class:`~django.http.HttpRequest` representing the current request, - * A :class:`~django.db.models.query.QuerySet` containing the set of - objects selected by the user. +* The current :class:`ModelAdmin` +* An :class:`~django.http.HttpRequest` representing the current request, +* A :class:`~django.db.models.query.QuerySet` containing the set of + objects selected by the user. Our publish-these-articles function won't need the :class:`ModelAdmin` or the request object, but we will use the queryset:: diff --git a/docs/ref/contrib/admin/admindocs.txt b/docs/ref/contrib/admin/admindocs.txt index f32557253c..4a50856f3d 100644 --- a/docs/ref/contrib/admin/admindocs.txt +++ b/docs/ref/contrib/admin/admindocs.txt @@ -22,16 +22,16 @@ Overview To activate the :mod:`~django.contrib.admindocs`, you will need to do 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 - ``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/). - * **Optional:** Linking to templates requires the :setting:`ADMIN_FOR` - setting to be configured. - * **Optional:** Using the admindocs bookmarklets requires the - :mod:`XViewMiddleware<django.middleware.doc>` to be installed. +* 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 + ``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/). +* **Optional:** Linking to templates requires the :setting:`ADMIN_FOR` + setting to be configured. +* **Optional:** Using the admindocs bookmarklets requires the + :mod:`XViewMiddleware<django.middleware.doc>` to be installed. Once those steps are complete, you can start browsing the documentation by going to your admin interface and clicking the "Documentation" link in the @@ -85,9 +85,9 @@ Each URL in your site has a separate entry in the ``admindocs`` page, and clicking on a given URL will show you the corresponding view. Helpful things you can document in your view function docstrings include: - * A short description of what the view does. - * The **context**, or a list of variables available in the view's template. - * The name of the template or templates that are used for that view. +* A short description of what the view does. +* The **context**, or a list of variables available in the view's template. +* The name of the template or templates that are used for that view. For example:: @@ -141,16 +141,16 @@ Included Bookmarklets Several useful bookmarklets are available from the ``admindocs`` page: - Documentation for this page - Jumps you from any page to the documentation for the view that generates - that page. +Documentation for this page + Jumps you from any page to the documentation for the view that generates + that page. - Show object ID - Shows the content-type and unique ID for pages that represent a single - object. +Show object ID + Shows the content-type and unique ID for pages that represent a single + object. - Edit this object - Jumps to the admin page for pages that represent a single object. +Edit this object + Jumps to the admin page for pages that represent a single object. Using these bookmarklets requires that you are either logged into the :mod:`Django admin <django.contrib.admin>` as a @@ -158,4 +158,4 @@ Using these bookmarklets requires that you are either logged into the :attr:`~django.contrib.auth.models.User.is_staff` set to `True`, or that the :mod:`django.middleware.doc` middleware and :mod:`XViewMiddleware <django.middleware.doc>` are installed and you -are accessing the site from an IP address listed in :setting:`INTERNAL_IPS`.
\ No newline at end of file +are accessing the site from an IP address listed in :setting:`INTERNAL_IPS`. diff --git a/docs/ref/contrib/comments/custom.txt b/docs/ref/contrib/comments/custom.txt index 5411d9ce70..5007ddff69 100644 --- a/docs/ref/contrib/comments/custom.txt +++ b/docs/ref/contrib/comments/custom.txt @@ -41,14 +41,14 @@ comment model has no field for that title. To make this kind of customization, we'll need to do three things: - #. Create a custom comment :class:`~django.db.models.Model` that adds on the - "title" field. +#. Create a custom comment :class:`~django.db.models.Model` that adds on the + "title" field. - #. Create a custom comment :class:`~django.forms.Form` that also adds this - "title" field. +#. Create a custom comment :class:`~django.forms.Form` that also adds this + "title" field. - #. Inform Django of these objects by defining a few functions in a - custom :setting:`COMMENTS_APP`. +#. Inform Django of these objects by defining a few functions in a + custom :setting:`COMMENTS_APP`. So, carrying on the example above, we're dealing with a typical app structure in the ``my_custom_app`` directory:: diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt index 7072ed14ac..61e7bd9f46 100644 --- a/docs/ref/contrib/comments/index.txt +++ b/docs/ref/contrib/comments/index.txt @@ -22,23 +22,23 @@ Quick start guide To get started using the ``comments`` app, follow these steps: - #. Install the comments framework by adding ``'django.contrib.comments'`` to - :setting:`INSTALLED_APPS`. +#. Install the comments framework by adding ``'django.contrib.comments'`` to + :setting:`INSTALLED_APPS`. - #. Run ``manage.py syncdb`` so that Django will create the comment tables. +#. Run ``manage.py syncdb`` so that Django will create the comment tables. - #. Add the comment app's URLs to your project's ``urls.py``: +#. Add the comment app's URLs to your project's ``urls.py``: - .. code-block:: python + .. code-block:: python - urlpatterns = patterns('', - ... - (r'^comments/', include('django.contrib.comments.urls')), - ... - ) + urlpatterns = patterns('', + ... + (r'^comments/', include('django.contrib.comments.urls')), + ... + ) - #. Use the `comment template tags`_ below to embed comments in your - templates. +#. Use the `comment template tags`_ below to embed comments in your + templates. You might also want to examine :doc:`/ref/contrib/comments/settings`. @@ -62,25 +62,25 @@ Django's comments are all "attached" to some parent object. This can be any instance of a Django model. Each of the tags below gives you a couple of different ways you can specify which object to attach to: - #. Refer to the object directly -- the more common method. Most of the - time, you'll have some object in the template's context you want - to attach the comment to; you can simply use that object. +#. Refer to the object directly -- the more common method. Most of the + time, you'll have some object in the template's context you want + to attach the comment to; you can simply use that object. - For example, in a blog entry page that has a variable named ``entry``, - you could use the following to load the number of comments:: + For example, in a blog entry page that has a variable named ``entry``, + you could use the following to load the number of comments:: - {% get_comment_count for entry as comment_count %}. + {% get_comment_count for entry as comment_count %}. - #. Refer to the object by content-type and object id. You'd use this method - if you, for some reason, don't actually have direct access to the object. +#. Refer to the object by content-type and object id. You'd use this method + if you, for some reason, don't actually have direct access to the object. - Following the above example, if you knew the object ID was ``14`` but - didn't have access to the actual object, you could do something like:: + Following the above example, if you knew the object ID was ``14`` but + didn't have access to the actual object, you could do something like:: - {% get_comment_count for blog.entry 14 as comment_count %} + {% get_comment_count for blog.entry 14 as comment_count %} - In the above, ``blog.entry`` is the app label and (lower-cased) model - name of the model class. + In the above, ``blog.entry`` is the app label and (lower-cased) model + name of the model class. Displaying comments ------------------- @@ -262,25 +262,25 @@ Notes on the comment form The form used by the comment system has a few important anti-spam attributes you should know about: - * It contains a number of hidden fields that contain timestamps, information - about the object the comment should be attached to, and a "security hash" - used to validate this information. If someone tampers with this data -- - something comment spammers will try -- the comment submission will fail. +* It contains a number of hidden fields that contain timestamps, information + about the object the comment should be attached to, and a "security hash" + used to validate this information. If someone tampers with this data -- + something comment spammers will try -- the comment submission will fail. - If you're rendering a custom comment form, you'll need to make sure to - pass these values through unchanged. + If you're rendering a custom comment form, you'll need to make sure to + pass these values through unchanged. - * The timestamp is used to ensure that "reply attacks" can't continue very - long. Users who wait too long between requesting the form and posting a - comment will have their submissions refused. +* The timestamp is used to ensure that "reply attacks" can't continue very + long. Users who wait too long between requesting the form and posting a + comment will have their submissions refused. - * The comment form includes a "honeypot_" field. It's a trap: if any data is - entered in that field, the comment will be considered spam (spammers often - automatically fill in all fields in an attempt to make valid submissions). +* The comment form includes a "honeypot_" field. It's a trap: if any data is + entered in that field, the comment will be considered spam (spammers often + automatically fill in all fields in an attempt to make valid submissions). - The default form hides this field with a piece of CSS and further labels - it with a warning field; if you use the comment form with a custom - template you should be sure to do the same. + The default form hides this field with a piece of CSS and further labels + it with a warning field; if you use the comment form with a custom + template you should be sure to do the same. The comments app also depends on the more general :doc:`Cross Site Request Forgery protection </ref/contrib/csrf>` that comes with Django. As described in diff --git a/docs/ref/contrib/comments/signals.txt b/docs/ref/contrib/comments/signals.txt index 7ae34a1900..9d7c435927 100644 --- a/docs/ref/contrib/comments/signals.txt +++ b/docs/ref/contrib/comments/signals.txt @@ -27,38 +27,38 @@ This signal is sent at more or less the same time (just before, actually) as the ``Comment`` object's :data:`~django.db.models.signals.pre_save` signal. Arguments sent with this signal: - - ``sender`` - The comment model. - - ``comment`` - The comment instance about to be posted. Note that it won't have been - saved into the database yet, so it won't have a primary key, and any - relations might not work correctly yet. - - ``request`` - The :class:`~django.http.HttpRequest` that posted the comment. - + +``sender`` + The comment model. + +``comment`` + The comment instance about to be posted. Note that it won't have been + saved into the database yet, so it won't have a primary key, and any + relations might not work correctly yet. + +``request`` + The :class:`~django.http.HttpRequest` that posted the comment. + comment_was_posted ================== .. data:: django.contrib.comments.signals.comment_was_posted :module: - + Sent just after the comment is saved. Arguments sent with this signal: - - ``sender`` - The comment model. - - ``comment`` - The comment instance that was posted. Note that it will have already - been saved, so if you modify it you'll need to call - :meth:`~django.db.models.Model.save` again. - - ``request`` - The :class:`~django.http.HttpRequest` that posted the comment. + +``sender`` + The comment model. + +``comment`` + The comment instance that was posted. Note that it will have already + been saved, so if you modify it you'll need to call + :meth:`~django.db.models.Model.save` again. + +``request`` + The :class:`~django.http.HttpRequest` that posted the comment. comment_was_flagged =================== @@ -71,21 +71,21 @@ was a user requesting removal of a comment, a moderator approving/removing a comment, or some other custom user flag. Arguments sent with this signal: - - ``sender`` - The comment model. - - ``comment`` - The comment instance that was posted. Note that it will have already - been saved, so if you modify it you'll need to call - :meth:`~django.db.models.Model.save` again. - - ``flag`` - The :class:`~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. - - ``request`` - The :class:`~django.http.HttpRequest` that posted the comment. + +``sender`` + The comment model. + +``comment`` + The comment instance that was posted. Note that it will have already + been saved, so if you modify it you'll need to call + :meth:`~django.db.models.Model.save` again. + +``flag`` + The :class:`~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. + +``request`` + The :class:`~django.http.HttpRequest` that posted the comment. diff --git a/docs/ref/contrib/comments/upgrade.txt b/docs/ref/contrib/comments/upgrade.txt index 3d6b5af668..dadb53f5fa 100644 --- a/docs/ref/contrib/comments/upgrade.txt +++ b/docs/ref/contrib/comments/upgrade.txt @@ -7,31 +7,31 @@ new comment system; this guide explains how. The main changes from the old system are: - * This new system is documented. - - * It uses modern Django features like :doc:`forms </topics/forms/index>` and - :doc:`modelforms </topics/forms/modelforms>`. +* This new system is documented. - * It has a single ``Comment`` model instead of separate ``FreeComment`` and - ``Comment`` models. +* It uses modern Django features like :doc:`forms </topics/forms/index>` and + :doc:`modelforms </topics/forms/modelforms>`. - * Comments have "email" and "URL" fields. +* It has a single ``Comment`` model instead of separate ``FreeComment`` and + ``Comment`` models. - * No ratings, photos and karma. This should only effect World Online. +* Comments have "email" and "URL" fields. - * The ``{% comment_form %}`` tag no longer exists. Instead, there's now two - functions: ``{% get_comment_form %}``, which returns a form for posting a - new comment, and ``{% render_comment_form %}``, which renders said form - using the ``comments/form.html`` template. - - * The way comments are include in your URLconf have changed; you'll need to - replace:: - - (r'^comments/', include('django.contrib.comments.urls.comments')), - - with:: +* No ratings, photos and karma. This should only effect World Online. + +* The ``{% comment_form %}`` tag no longer exists. Instead, there's now two + functions: ``{% get_comment_form %}``, which returns a form for posting a + new comment, and ``{% render_comment_form %}``, which renders said form + using the ``comments/form.html`` template. + +* The way comments are include in your URLconf have changed; you'll need to + replace:: + + (r'^comments/', include('django.contrib.comments.urls.comments')), + + with:: - (r'^comments/', include('django.contrib.comments.urls')), + (r'^comments/', include('django.contrib.comments.urls')), Upgrading data -------------- diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index fc685c8cd6..270ccf0c51 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -45,14 +45,14 @@ but if you've removed it or if you manually set up your It's generally a good idea to have the contenttypes framework installed; several of Django's other bundled applications require it: - * The admin application uses it to log the history of each object - added or changed through the admin interface. +* The admin application uses it to log the history of each object + added or changed through the admin interface. - * Django's :mod:`authentication framework <django.contrib.auth>` uses it - to tie user permissions to specific models. +* Django's :mod:`authentication framework <django.contrib.auth>` uses it + to tie user permissions to specific models. - * Django's comments system (:mod:`django.contrib.comments`) uses it to - "attach" comments to any installed model. +* Django's comments system (:mod:`django.contrib.comments`) uses it to + "attach" comments to any installed model. .. currentmodule:: django.contrib.contenttypes.models @@ -92,15 +92,15 @@ your database. Along with it a new instance of :class:`~django.contrib.contenttypes.models.ContentType` will be created with the following values: - * :attr:`~django.contrib.contenttypes.models.ContentType.app_label` - will be set to ``'sites'`` (the last part of the Python - path "django.contrib.sites"). +* :attr:`~django.contrib.contenttypes.models.ContentType.app_label` + will be set to ``'sites'`` (the last part of the Python + path "django.contrib.sites"). - * :attr:`~django.contrib.contenttypes.models.ContentType.model` - will be set to ``'site'``. +* :attr:`~django.contrib.contenttypes.models.ContentType.model` + will be set to ``'site'``. - * :attr:`~django.contrib.contenttypes.models.ContentType.name` - will be set to ``'site'``. +* :attr:`~django.contrib.contenttypes.models.ContentType.name` + will be set to ``'site'``. .. _the verbose_name attribute: ../model-api/#verbose_name @@ -148,17 +148,17 @@ Together, and :meth:`~django.contrib.contenttypes.models.ContentType.model_class` enable two extremely important use cases: - 1. Using these methods, you can write high-level generic code that - performs queries on any installed model -- instead of importing and - using a single specific model class, you can pass an ``app_label`` and - ``model`` into a - :class:`~django.contrib.contenttypes.models.ContentType` lookup at - runtime, and then work with the model class or retrieve objects from it. +1. Using these methods, you can write high-level generic code that + performs queries on any installed model -- instead of importing and + using a single specific model class, you can pass an ``app_label`` and + ``model`` into a + :class:`~django.contrib.contenttypes.models.ContentType` lookup at + runtime, and then work with the model class or retrieve objects from it. - 2. You can relate another model to - :class:`~django.contrib.contenttypes.models.ContentType` as a way of - tying instances of it to particular model classes, and use these methods - to get access to those model classes. +2. You can relate another model to + :class:`~django.contrib.contenttypes.models.ContentType` as a way of + tying instances of it to particular model classes, and use these methods + to get access to those model classes. Several of Django's bundled applications make use of the latter technique. For example, @@ -263,21 +263,21 @@ model: There are three parts to setting up a :class:`~django.contrib.contenttypes.generic.GenericForeignKey`: - 1. Give your model a :class:`~django.db.models.ForeignKey` - to :class:`~django.contrib.contenttypes.models.ContentType`. + 1. Give your model a :class:`~django.db.models.ForeignKey` + to :class:`~django.contrib.contenttypes.models.ContentType`. - 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 - :class:`~django.db.models.PositiveIntegerField`. The usual name - for this field is "object_id". + 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 + :class:`~django.db.models.PositiveIntegerField`. The usual name + for this field is "object_id". - 3. Give your model a - :class:`~django.contrib.contenttypes.generic.GenericForeignKey`, and - pass it the names of the two fields described above. If these fields - are named "content_type" and "object_id", you can omit this -- those - are the default field names - :class:`~django.contrib.contenttypes.generic.GenericForeignKey` will - look for. + 3. Give your model a + :class:`~django.contrib.contenttypes.generic.GenericForeignKey`, and + pass it the names of the two fields described above. If these fields + are named "content_type" and "object_id", you can omit this -- those + are the default field names + :class:`~django.contrib.contenttypes.generic.GenericForeignKey` will + look for. .. admonition:: Primary key type compatibility diff --git a/docs/ref/contrib/csrf.txt b/docs/ref/contrib/csrf.txt index a6839477e4..e1a87d495f 100644 --- a/docs/ref/contrib/csrf.txt +++ b/docs/ref/contrib/csrf.txt @@ -28,49 +28,49 @@ How to use it To enable CSRF protection for your views, follow these steps: - 1. Add the middleware - ``'django.middleware.csrf.CsrfViewMiddleware'`` to your list of - middleware classes, :setting:`MIDDLEWARE_CLASSES`. (It should come - before any view middleware that assume that CSRF attacks have - been dealt with.) +1. Add the middleware + ``'django.middleware.csrf.CsrfViewMiddleware'`` to your list of + middleware classes, :setting:`MIDDLEWARE_CLASSES`. (It should come + before any view middleware that assume that CSRF attacks have + been dealt with.) - Alternatively, you can use the decorator - :func:`~django.views.decorators.csrf.csrf_protect` on particular views - you want to protect (see below). + Alternatively, you can use the decorator + :func:`~django.views.decorators.csrf.csrf_protect` on particular views + you want to protect (see below). - 2. In any template that uses a POST form, use the :ttag:`csrf_token` tag inside - the ``<form>`` element if the form is for an internal URL, e.g.:: +2. In any template that uses a POST form, use the :ttag:`csrf_token` tag inside + the ``<form>`` element if the form is for an internal URL, e.g.:: - <form action="." method="post">{% csrf_token %} + <form action="." method="post">{% csrf_token %} - This should not be done for POST forms that target external URLs, since - that would cause the CSRF token to be leaked, leading to a vulnerability. + This should not be done for POST forms that target external URLs, since + that would cause the CSRF token to be leaked, leading to a vulnerability. - 3. In the corresponding view functions, ensure that the - ``'django.core.context_processors.csrf'`` context processor is - being used. Usually, this can be done in one of two ways: +3. In the corresponding view functions, ensure that the + ``'django.core.context_processors.csrf'`` context processor is + being used. Usually, this can be done in one of two ways: - 1. Use RequestContext, which always uses - ``'django.core.context_processors.csrf'`` (no matter what your - TEMPLATE_CONTEXT_PROCESSORS setting). If you are using - generic views or contrib apps, you are covered already, since these - apps use RequestContext throughout. + 1. Use RequestContext, which always uses + ``'django.core.context_processors.csrf'`` (no matter what your + TEMPLATE_CONTEXT_PROCESSORS setting). If you are using + generic views or contrib apps, you are covered already, since these + apps use RequestContext throughout. - 2. Manually import and use the processor to generate the CSRF token and - add it to the template context. e.g.:: + 2. Manually import and use the processor to generate the CSRF token and + add it to the template context. e.g.:: - from django.core.context_processors import csrf - from django.shortcuts import render_to_response + from django.core.context_processors import csrf + from django.shortcuts import render_to_response - def my_view(request): - c = {} - c.update(csrf(request)) - # ... view code here - return render_to_response("a_template.html", c) + def my_view(request): + c = {} + c.update(csrf(request)) + # ... view code here + return render_to_response("a_template.html", c) - You may want to write your own - :func:`~django.shortcuts.render_to_response()` wrapper that takes care - of this step for you. + You may want to write your own + :func:`~django.shortcuts.render_to_response()` wrapper that takes care + of this step for you. The utility script ``extras/csrf_migration_helper.py`` can help to automate the finding of code and templates that may need these steps. It contains full help diff --git a/docs/ref/contrib/databrowse.txt b/docs/ref/contrib/databrowse.txt index 794855877a..f8fedc4482 100644 --- a/docs/ref/contrib/databrowse.txt +++ b/docs/ref/contrib/databrowse.txt @@ -17,45 +17,45 @@ introspecting your models. How to use Databrowse ===================== - 1. Point Django at the default Databrowse templates. There are two ways to - do this: +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. + * 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. + * 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:: +2. Register a number of models with the Databrowse site:: - from django.contrib import databrowse - from myapp.models import SomeModel, SomeOtherModel + from django.contrib import databrowse + from myapp.models import SomeModel, SomeOtherModel - databrowse.site.register(SomeModel) - databrowse.site.register(SomeOtherModel) + databrowse.site.register(SomeModel) + databrowse.site.register(SomeOtherModel) - Note that you should register the model *classes*, not instances. + Note that you should register the model *classes*, not instances. - 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``). + 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:: +3. Change your URLconf to import the :mod:`~django.contrib.databrowse` module:: - from django.contrib import databrowse + from django.contrib import databrowse - ...and add the following line to your URLconf:: + ...and add the following line to your URLconf:: - (r'^databrowse/(.*)', databrowse.site.root), + (r'^databrowse/(.*)', databrowse.site.root), - The prefix doesn't matter -- you can use ``databrowse/`` or ``db/`` or - whatever you'd like. + 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. +4. Run the Django server and visit ``/databrowse/`` in your browser. Requiring user login ==================== diff --git a/docs/ref/contrib/flatpages.txt b/docs/ref/contrib/flatpages.txt index 00e2139afd..0b20eccf7e 100644 --- a/docs/ref/contrib/flatpages.txt +++ b/docs/ref/contrib/flatpages.txt @@ -22,30 +22,30 @@ content in a custom template. Here are some examples of flatpages on Django-powered sites: - * http://www.lawrence.com/about/contact/ - * http://www2.ljworld.com/site/rules/ +* http://www.lawrence.com/about/contact/ +* http://www2.ljworld.com/site/rules/ Installation ============ To install the flatpages app, follow these steps: - 1. Install the :mod:`sites framework <django.contrib.sites>` by adding - ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting, - if it's not already in there. +1. Install the :mod:`sites framework <django.contrib.sites>` by adding + ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting, + if it's not already in there. - Also make sure you've correctly set :setting:`SITE_ID` to the ID of the - site the settings file represents. This will usually be ``1`` (i.e. - ``SITE_ID = 1``, but if you're using the sites framework to manage - multiple sites, it could be the ID of a different site. + Also make sure you've correctly set :setting:`SITE_ID` to the ID of the + site the settings file represents. This will usually be ``1`` (i.e. + ``SITE_ID = 1``, but if you're using the sites framework to manage + multiple sites, it could be the ID of a different site. - 2. Add ``'django.contrib.flatpages'`` to your :setting:`INSTALLED_APPS` - setting. +2. Add ``'django.contrib.flatpages'`` to your :setting:`INSTALLED_APPS` + setting. - 3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'`` - to your :setting:`MIDDLEWARE_CLASSES` setting. +3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'`` + to your :setting:`MIDDLEWARE_CLASSES` setting. - 4. Run the command :djadmin:`manage.py syncdb <syncdb>`. +4. Run the command :djadmin:`manage.py syncdb <syncdb>`. .. currentmodule:: django.contrib.flatpages.middleware @@ -69,13 +69,13 @@ does all of the work. If it finds a match, it follows this algorithm: - * If the flatpage has a custom template, it loads that template. - Otherwise, it loads the template :file:`flatpages/default.html`. + * If the flatpage has a custom template, it loads that template. + Otherwise, it loads the template :file:`flatpages/default.html`. - * It passes that template a single context variable, ``flatpage``, - which is the flatpage object. It uses - :class:`~django.template.RequestContext` in rendering the - template. + * It passes that template a single context variable, ``flatpage``, + which is the flatpage object. It uses + :class:`~django.template.RequestContext` in rendering the + template. .. versionchanged:: 1.4 The middleware will only add a trailing slash and redirect (by looking diff --git a/docs/ref/contrib/formtools/form-preview.txt b/docs/ref/contrib/formtools/form-preview.txt index c5d8b9a8d8..f9a1feb262 100644 --- a/docs/ref/contrib/formtools/form-preview.txt +++ b/docs/ref/contrib/formtools/form-preview.txt @@ -20,14 +20,14 @@ Overview Given a :class:`django.forms.Form` subclass that you define, this application takes care of the following workflow: - 1. Displays the form as HTML on a Web page. - 2. Validates the form data when it's submitted via POST. - 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. +1. Displays the form as HTML on a Web page. +2. Validates the form data when it's submitted via POST. + 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. 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 @@ -36,53 +36,53 @@ on the preview page, the form submission will fail the hash-comparison test. How to use ``FormPreview`` ========================== - 1. Point Django at the default FormPreview templates. There are two ways to - do this: +1. Point Django at the default FormPreview templates. There are two ways to + do this: - * Add ``'django.contrib.formtools'`` 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. + * Add ``'django.contrib.formtools'`` 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/formtools/templates` directory, and add that - directory to your :setting:`TEMPLATE_DIRS` setting. + * Otherwise, determine the full filesystem path to the + :file:`django/contrib/formtools/templates` directory, and add that + 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:: +2. Create a :class:`~django.contrib.formtools.preview.FormPreview` subclass that + overrides the :meth:`~django.contrib.formtools.preview.FormPreview.done()` + method:: - from django.contrib.formtools.preview import FormPreview - from myapp.models import SomeModel + from django.contrib.formtools.preview import FormPreview + from myapp.models import SomeModel - class SomeModelFormPreview(FormPreview): + class SomeModelFormPreview(FormPreview): - def done(self, request, cleaned_data): - # Do something with the cleaned_data, then redirect - # to a "success" page. - return HttpResponseRedirect('/form/success') + def done(self, request, cleaned_data): + # Do something with the cleaned_data, then redirect + # to a "success" page. + return HttpResponseRedirect('/form/success') - This method takes an :class:`~django.http.HttpRequest` object and a - dictionary of the form data after it has been validated and cleaned. - It should return an :class:`~django.http.HttpResponseRedirect` that - is the end result of the form being submitted. + This method takes an :class:`~django.http.HttpRequest` object and a + dictionary of the form data after it has been validated and cleaned. + It should return an :class:`~django.http.HttpResponseRedirect` that + is the end result of the form being submitted. - 3. Change your URLconf to point to an instance of your - :class:`~django.contrib.formtools.preview.FormPreview` subclass:: +3. Change your URLconf to point to an instance of your + :class:`~django.contrib.formtools.preview.FormPreview` subclass:: - from myapp.preview import SomeModelFormPreview - from myapp.forms import SomeModelForm - from django import forms + from myapp.preview import SomeModelFormPreview + from myapp.forms import SomeModelForm + from django import forms - ...and add the following line to the appropriate model in your URLconf:: + ...and add the following line to the appropriate model in your URLconf:: - (r'^post/$', SomeModelFormPreview(SomeModelForm)), + (r'^post/$', SomeModelFormPreview(SomeModelForm)), - where ``SomeModelForm`` is a Form or ModelForm class for the model. + where ``SomeModelForm`` is a Form or ModelForm class for the model. - 4. Run the Django server and visit :file:`/post/` in your browser. +4. Run the Django server and visit :file:`/post/` in your browser. ``FormPreview`` classes ======================= diff --git a/docs/ref/contrib/formtools/form-wizard.txt b/docs/ref/contrib/formtools/form-wizard.txt index 00c319590e..2483ce91c6 100644 --- a/docs/ref/contrib/formtools/form-wizard.txt +++ b/docs/ref/contrib/formtools/form-wizard.txt @@ -24,15 +24,15 @@ How it works Here's the basic workflow for how a user would use a wizard: - 1. The user visits the first page of the wizard, fills in the form and - submits it. - 2. The server validates the data. If it's invalid, the form is displayed - again, with error messages. If it's valid, the server saves the current - state of the wizard in the backend and redirects to the next step. - 3. Step 1 and 2 repeat, for every subsequent form in the wizard. - 4. Once the user has submitted all the forms and all the data has been - validated, the wizard processes the data -- saving it to the database, - sending an email, or whatever the application needs to do. +1. The user visits the first page of the wizard, fills in the form and + submits it. +2. The server validates the data. If it's invalid, the form is displayed + again, with error messages. If it's valid, the server saves the current + state of the wizard in the backend and redirects to the next step. +3. Step 1 and 2 repeat, for every subsequent form in the wizard. +4. Once the user has submitted all the forms and all the data has been + validated, the wizard processes the data -- saving it to the database, + sending an email, or whatever the application needs to do. Usage ===== @@ -40,21 +40,21 @@ Usage This application handles as much machinery for you as possible. Generally, you just have to do these things: - 1. Define a number of :class:`~django.forms.Form` classes -- one per - wizard page. +1. Define a number of :class:`~django.forms.Form` classes -- one per + wizard page. - 2. Create a :class:`WizardView` subclass that specifies what to do once - all of your forms have been submitted and validated. This also lets - you override some of the wizard's behavior. +2. Create a :class:`WizardView` subclass that specifies what to do once + all of your forms have been submitted and validated. This also lets + you override some of the wizard's behavior. - 3. Create some templates that render the forms. You can define a single, - generic template to handle every one of the forms, or you can define a - specific template for each form. +3. Create some templates that render the forms. You can define a single, + generic template to handle every one of the forms, or you can define a + specific template for each form. - 4. Add ``django.contrib.formtools`` to your - :setting:`INSTALLED_APPS` list in your settings file. +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 ------------------------- @@ -160,21 +160,21 @@ latter one allows you to use a different template for each form. This template expects a ``wizard`` object that has various items attached to it: - * ``form`` -- The :class:`~django.forms.Form` instance for the current - step (either empty or with errors). +* ``form`` -- The :class:`~django.forms.Form` instance for the current + step (either empty or with errors). - * ``steps`` -- A helper object to access the various steps related data: +* ``steps`` -- A helper object to access the various steps related data: - * ``step0`` -- The current step (zero-based). - * ``step1`` -- The current step (one-based). - * ``count`` -- The total number of steps. - * ``first`` -- The first step. - * ``last`` -- The last step. - * ``current`` -- The current (or first) step. - * ``next`` -- The next step. - * ``prev`` -- The previous step. - * ``index`` -- The index of the current step. - * ``all`` -- A list of all steps of the wizard. + * ``step0`` -- The current step (zero-based). + * ``step1`` -- The current step (one-based). + * ``count`` -- The total number of steps. + * ``first`` -- The first step. + * ``last`` -- The last step. + * ``current`` -- The current (or first) step. + * ``next`` -- The next step. + * ``prev`` -- The previous step. + * ``index`` -- The index of the current step. + * ``all`` -- A list of all steps of the wizard. You can supply additional context variables by using the :meth:`~WizardView.get_context_data` method of your :class:`WizardView` @@ -582,8 +582,8 @@ Below you will see an example of a contact wizard with two steps, step 1 with Additionally you have to pass two more arguments to the :meth:`~WizardView.as_view` method: - * ``url_name`` -- the name of the url (as provided in the urls.py) - * ``done_step_name`` -- the name in the url for the done step +* ``url_name`` -- the name of the url (as provided in the urls.py) +* ``done_step_name`` -- the name in the url for the done step Example code for the changed ``urls.py`` file:: diff --git a/docs/ref/contrib/humanize.txt b/docs/ref/contrib/humanize.txt index 292d98a941..cdc3009a51 100644 --- a/docs/ref/contrib/humanize.txt +++ b/docs/ref/contrib/humanize.txt @@ -23,9 +23,9 @@ number. This follows Associated Press style. Examples: - * ``1`` becomes ``one``. - * ``2`` becomes ``two``. - * ``10`` becomes ``10``. +* ``1`` becomes ``one``. +* ``2`` becomes ``two``. +* ``10`` becomes ``10``. You can pass in either an integer or a string representation of an integer. @@ -38,16 +38,16 @@ Converts an integer to a string containing commas every three digits. Examples: - * ``4500`` becomes ``4,500``. - * ``45000`` becomes ``45,000``. - * ``450000`` becomes ``450,000``. - * ``4500000`` becomes ``4,500,000``. +* ``4500`` becomes ``4,500``. +* ``45000`` becomes ``45,000``. +* ``450000`` becomes ``450,000``. +* ``4500000`` becomes ``4,500,000``. :ref:`Format localization <format-localization>` will be respected if enabled, e.g. with the ``'de'`` language: - * ``45000`` becomes ``'45.000'``. - * ``450000`` becomes ``'450.000'``. +* ``45000`` becomes ``'45.000'``. +* ``450000`` becomes ``'450.000'``. You can pass in either an integer or a string representation of an integer. @@ -61,18 +61,18 @@ numbers over 1 million. Examples: - * ``1000000`` becomes ``1.0 million``. - * ``1200000`` becomes ``1.2 million``. - * ``1200000000`` becomes ``1.2 billion``. +* ``1000000`` becomes ``1.0 million``. +* ``1200000`` becomes ``1.2 million``. +* ``1200000000`` becomes ``1.2 billion``. Values up to 10^100 (Googol) are supported. :ref:`Format localization <format-localization>` will be respected if enabled, e.g. with the ``'de'`` language: - * ``1000000`` becomes ``'1,0 Million'``. - * ``1200000`` becomes ``'1,2 Million'``. - * ``1200000000`` becomes ``'1,2 Milliarden'``. +* ``1000000`` becomes ``'1,0 Million'``. +* ``1200000`` becomes ``'1,2 Million'``. +* ``1200000000`` becomes ``'1,2 Milliarden'``. You can pass in either an integer or a string representation of an integer. @@ -89,11 +89,11 @@ the passed in format string. Examples (when 'today' is 17 Feb 2007): - * ``16 Feb 2007`` becomes ``yesterday``. - * ``17 Feb 2007`` becomes ``today``. - * ``18 Feb 2007`` becomes ``tomorrow``. - * Any other day is formatted according to given argument or the - :setting:`DATE_FORMAT` setting if no argument is given. +* ``16 Feb 2007`` becomes ``yesterday``. +* ``17 Feb 2007`` becomes ``today``. +* ``18 Feb 2007`` becomes ``tomorrow``. +* Any other day is formatted according to given argument or the + :setting:`DATE_FORMAT` setting if no argument is given. .. templatefilter:: naturaltime @@ -109,19 +109,19 @@ the return value will automatically use an appropriate phrase. Examples (when 'now' is 17 Feb 2007 16:30:00): - * ``17 Feb 2007 16:30:00`` becomes ``now``. - * ``17 Feb 2007 16:29:31`` becomes ``29 seconds ago``. - * ``17 Feb 2007 16:29:00`` becomes ``a minute ago``. - * ``17 Feb 2007 16:25:35`` becomes ``4 minutes ago``. - * ``17 Feb 2007 15:30:29`` becomes ``an hour ago``. - * ``17 Feb 2007 13:31:29`` becomes ``2 hours ago``. - * ``16 Feb 2007 13:31:29`` becomes ``1 day ago``. - * ``17 Feb 2007 16:30:30`` becomes ``29 seconds from now``. - * ``17 Feb 2007 16:31:00`` becomes ``a minute from now``. - * ``17 Feb 2007 16:34:35`` becomes ``4 minutes from now``. - * ``17 Feb 2007 16:30:29`` becomes ``an hour from now``. - * ``17 Feb 2007 18:31:29`` becomes ``2 hours from now``. - * ``18 Feb 2007 16:31:29`` becomes ``1 day from now``. +* ``17 Feb 2007 16:30:00`` becomes ``now``. +* ``17 Feb 2007 16:29:31`` becomes ``29 seconds ago``. +* ``17 Feb 2007 16:29:00`` becomes ``a minute ago``. +* ``17 Feb 2007 16:25:35`` becomes ``4 minutes ago``. +* ``17 Feb 2007 15:30:29`` becomes ``an hour ago``. +* ``17 Feb 2007 13:31:29`` becomes ``2 hours ago``. +* ``16 Feb 2007 13:31:29`` becomes ``1 day ago``. +* ``17 Feb 2007 16:30:30`` becomes ``29 seconds from now``. +* ``17 Feb 2007 16:31:00`` becomes ``a minute from now``. +* ``17 Feb 2007 16:34:35`` becomes ``4 minutes from now``. +* ``17 Feb 2007 16:30:29`` becomes ``an hour from now``. +* ``17 Feb 2007 18:31:29`` becomes ``2 hours from now``. +* ``18 Feb 2007 16:31:29`` becomes ``1 day from now``. .. templatefilter:: ordinal @@ -132,8 +132,8 @@ Converts an integer to its ordinal as a string. Examples: - * ``1`` becomes ``1st``. - * ``2`` becomes ``2nd``. - * ``3`` becomes ``3rd``. +* ``1`` becomes ``1st``. +* ``2`` becomes ``2nd``. +* ``3`` becomes ``3rd``. You can pass in either an integer or a string representation of an integer. diff --git a/docs/ref/contrib/markup.txt b/docs/ref/contrib/markup.txt index d5f07f57ef..4b91313de4 100644 --- a/docs/ref/contrib/markup.txt +++ b/docs/ref/contrib/markup.txt @@ -8,10 +8,10 @@ django.contrib.markup Django provides template filters that implement the following markup languages: - * ``textile`` -- implements `Textile`_ -- requires `PyTextile`_ - * ``markdown`` -- implements `Markdown`_ -- requires `Python-markdown`_ - * ``restructuredtext`` -- implements `reST (reStructured Text)`_ - -- requires `doc-utils`_ +* ``textile`` -- implements `Textile`_ -- requires `PyTextile`_ +* ``markdown`` -- implements `Markdown`_ -- requires `Python-markdown`_ +* ``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 diff --git a/docs/ref/contrib/messages.txt b/docs/ref/contrib/messages.txt index 22f6bd0496..223a162830 100644 --- a/docs/ref/contrib/messages.txt +++ b/docs/ref/contrib/messages.txt @@ -23,20 +23,20 @@ class and corresponding :doc:`context processor </ref/templates/api>`. To enable message functionality, do the following: - * Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure - it contains ``'django.contrib.messages.middleware.MessageMiddleware'``. +* Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure + it contains ``'django.contrib.messages.middleware.MessageMiddleware'``. - If you are using a :ref:`storage backend <message-storage-backends>` that - relies on :doc:`sessions </topics/http/sessions>` (the default), - ``'django.contrib.sessions.middleware.SessionMiddleware'`` must be - enabled and appear before ``MessageMiddleware`` in your - :setting:`MIDDLEWARE_CLASSES`. + If you are using a :ref:`storage backend <message-storage-backends>` that + relies on :doc:`sessions </topics/http/sessions>` (the default), + ``'django.contrib.sessions.middleware.SessionMiddleware'`` must be + enabled and appear before ``MessageMiddleware`` in your + :setting:`MIDDLEWARE_CLASSES`. - * Edit the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting and make sure - it contains ``'django.contrib.messages.context_processors.messages'``. +* Edit the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting and make sure + it contains ``'django.contrib.messages.context_processors.messages'``. - * Add ``'django.contrib.messages'`` to your :setting:`INSTALLED_APPS` - setting +* Add ``'django.contrib.messages'`` to your :setting:`INSTALLED_APPS` + setting The default ``settings.py`` created by ``django-admin.py startproject`` has ``MessageMiddleware`` activated and the ``django.contrib.messages`` app @@ -349,9 +349,9 @@ Default: ``'django.contrib.messages.storage.user_messages.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'`` +* ``'django.contrib.messages.storage.fallback.FallbackStorage'`` +* ``'django.contrib.messages.storage.session.SessionStorage'`` +* ``'django.contrib.messages.storage.cookie.CookieStorage'`` See `Storage backends`_ for more details. diff --git a/docs/ref/contrib/redirects.txt b/docs/ref/contrib/redirects.txt index f1a58cb207..82e197c6e0 100644 --- a/docs/ref/contrib/redirects.txt +++ b/docs/ref/contrib/redirects.txt @@ -13,11 +13,11 @@ 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'`` - to your :setting:`MIDDLEWARE_CLASSES` setting. - 3. Run the command :djadmin:`manage.py syncdb <syncdb>`. +1. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` + setting. +2. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'`` + to your :setting:`MIDDLEWARE_CLASSES` setting. +3. Run the command :djadmin:`manage.py syncdb <syncdb>`. How it works ============ @@ -31,12 +31,12 @@ for the requested URL as a last resort. Specifically, it checks for a redirect with the given ``old_path`` with a site ID that corresponds to the :setting:`SITE_ID` setting. - * If it finds a match, and ``new_path`` is not empty, it redirects to - ``new_path``. - * If it finds a match, and ``new_path`` is empty, it sends a 410 ("Gone") - HTTP header and empty (content-less) response. - * If it doesn't find a match, the request continues to be processed as - usual. +* If it finds a match, and ``new_path`` is not empty, it redirects to + ``new_path``. +* If it finds a match, and ``new_path`` is empty, it sends a 410 ("Gone") + HTTP header and empty (content-less) response. +* If it doesn't find a match, the request continues to be processed as + usual. The middleware only gets activated for 404s -- not for 500s or responses of any other status code. diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index ecc5024877..a45312cddb 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.txt @@ -31,15 +31,15 @@ Installation To install the sitemap app, follow these steps: - 1. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS` - setting. +1. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS` + setting. - 2. Make sure ``'django.template.loaders.app_directories.Loader'`` - is in your :setting:`TEMPLATE_LOADERS` setting. It's in there by default, - so you'll only need to change this if you've changed that setting. +2. Make sure ``'django.template.loaders.app_directories.Loader'`` + is in your :setting:`TEMPLATE_LOADERS` setting. It's in there by default, + so you'll only need to change this if you've changed that setting. - 3. Make sure you've installed the - :mod:`sites framework <django.contrib.sites>`. +3. Make sure you've installed the + :mod:`sites framework <django.contrib.sites>`. (Note: The sitemap application doesn't install any database tables. The only reason it needs to go into :setting:`INSTALLED_APPS` is so that the @@ -109,20 +109,20 @@ your sitemap class might look:: Note: - * :attr:`~Sitemap.changefreq` and :attr:`~Sitemap.priority` are class - attributes corresponding to ``<changefreq>`` and ``<priority>`` elements, - respectively. They can be made callable as functions, as - :attr:`~Sitemap.lastmod` was in the example. - * :attr:`~Sitemap.items()` is simply a method that returns a list of - objects. The objects returned will get passed to any callable methods - corresponding to a sitemap property (:attr:`~Sitemap.location`, - :attr:`~Sitemap.lastmod`, :attr:`~Sitemap.changefreq`, and - :attr:`~Sitemap.priority`). - * :attr:`~Sitemap.lastmod` should return a Python ``datetime`` object. - * There is no :attr:`~Sitemap.location` method in this example, but you - can provide it in order to specify the URL for your object. By default, - :attr:`~Sitemap.location()` calls ``get_absolute_url()`` on each object - and returns the result. +* :attr:`~Sitemap.changefreq` and :attr:`~Sitemap.priority` are class + attributes corresponding to ``<changefreq>`` and ``<priority>`` elements, + respectively. They can be made callable as functions, as + :attr:`~Sitemap.lastmod` was in the example. +* :attr:`~Sitemap.items()` is simply a method that returns a list of + objects. The objects returned will get passed to any callable methods + corresponding to a sitemap property (:attr:`~Sitemap.location`, + :attr:`~Sitemap.lastmod`, :attr:`~Sitemap.changefreq`, and + :attr:`~Sitemap.priority`). +* :attr:`~Sitemap.lastmod` should return a Python ``datetime`` object. +* There is no :attr:`~Sitemap.location` method in this example, but you + can provide it in order to specify the URL for your object. By default, + :attr:`~Sitemap.location()` calls ``get_absolute_url()`` on each object + and returns the result. Sitemap class reference ======================= @@ -153,9 +153,9 @@ Sitemap class reference In both cases, "absolute path" means a URL that doesn't include the protocol or domain. Examples: - * Good: :file:`'/foo/bar/'` - * Bad: :file:`'example.com/foo/bar/'` - * Bad: :file:`'http://example.com/foo/bar/'` + * Good: :file:`'/foo/bar/'` + * Bad: :file:`'example.com/foo/bar/'` + * Bad: :file:`'http://example.com/foo/bar/'` If :attr:`~Sitemap.location` isn't provided, the framework will call the ``get_absolute_url()`` method on each object as returned by @@ -185,13 +185,13 @@ Sitemap class reference Possible values for :attr:`~Sitemap.changefreq`, whether you use a method or attribute, are: - * ``'always'`` - * ``'hourly'`` - * ``'daily'`` - * ``'weekly'`` - * ``'monthly'`` - * ``'yearly'`` - * ``'never'`` + * ``'always'`` + * ``'hourly'`` + * ``'daily'`` + * ``'weekly'`` + * ``'monthly'`` + * ``'yearly'`` + * ``'never'`` .. method:: Sitemap.priority @@ -272,10 +272,10 @@ 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: - * 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. +* 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. Here's what the relevant URLconf lines would look like for the example above:: @@ -341,11 +341,11 @@ The variable :data:`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: - - ``changefreq`` - - ``item`` - - ``lastmod`` - - ``location`` - - ``priority`` +- ``changefreq`` +- ``item`` +- ``lastmod`` +- ``location`` +- ``priority`` .. versionadded:: 1.4 diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index 58f66daf02..8fc434ba9b 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -70,24 +70,24 @@ that's represented by a :class:`~django.db.models.ManyToManyField` in the This accomplishes several things quite nicely: - * It lets the site producers edit all content -- on both sites -- in a - single interface (the Django admin). +* It lets the site producers edit all content -- on both sites -- in a + single interface (the Django admin). - * It means the same story doesn't have to be published twice in the - database; it only has a single record in the database. +* It means the same story doesn't have to be published twice in the + database; it only has a single record in the database. - * It lets the site developers use the same Django view code for both sites. - The view code that displays a given story just checks to make sure the - requested story is on the current site. It looks something like this:: +* It lets the site developers use the same Django view code for both sites. + The view code that displays a given story just checks to make sure the + requested story is on the current site. It looks something like this:: - from django.conf import settings + from django.conf import settings - def article_detail(request, article_id): - try: - a = Article.objects.get(id=article_id, sites__id__exact=settings.SITE_ID) - except Article.DoesNotExist: - raise Http404 - # ... + def article_detail(request, article_id): + try: + a = Article.objects.get(id=article_id, sites__id__exact=settings.SITE_ID) + except Article.DoesNotExist: + raise Http404 + # ... .. _ljworld.com: http://www.ljworld.com/ .. _lawrence.com: http://www.lawrence.com/ diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index 311d4f384f..dd4a92168a 100644 --- a/docs/ref/contrib/staticfiles.txt +++ b/docs/ref/contrib/staticfiles.txt @@ -385,19 +385,19 @@ There are a few other helpers outside of the :mod:`staticfiles <django.contrib.staticfiles>` app to work with static files: - - The :func:`django.core.context_processors.static` context processor - which adds :setting:`STATIC_URL` to every template context rendered - with :class:`~django.template.RequestContext` contexts. +- The :func:`django.core.context_processors.static` context processor + which adds :setting:`STATIC_URL` to every template context rendered + with :class:`~django.template.RequestContext` contexts. - - The builtin template tag :ttag:`static` which takes a path and - urljoins it with the static prefix :setting:`STATIC_URL`. +- The builtin template tag :ttag:`static` which takes a path and + urljoins it with the static prefix :setting:`STATIC_URL`. - - The builtin template tag :ttag:`get_static_prefix` which populates a - template variable with the static prefix :setting:`STATIC_URL` to be - used as a variable or directly. +- The builtin template tag :ttag:`get_static_prefix` which populates a + template variable with the static prefix :setting:`STATIC_URL` to be + used as a variable or directly. - - The similar template tag :ttag:`get_media_prefix` which works like - :ttag:`get_static_prefix` but uses :setting:`MEDIA_URL`. +- The similar template tag :ttag:`get_media_prefix` which works like + :ttag:`get_static_prefix` but uses :setting:`MEDIA_URL`. .. _staticfiles-development-view: diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt index bbc58cef55..e66bb46206 100644 --- a/docs/ref/contrib/syndication.txt +++ b/docs/ref/contrib/syndication.txt @@ -113,45 +113,45 @@ One thing is left to do. In an RSS feed, each ``<item>`` has a ``<title>``, ``<link>`` and ``<description>``. We need to tell the framework what data to put into those elements. - * For the contents of ``<title>`` and ``<description>``, Django tries - calling the methods ``item_title()`` and ``item_description()`` on - the :class:`~django.contrib.syndication.views.Feed` class. They are passed - a single parameter, ``item``, which is the object itself. These are - optional; by default, the unicode representation of the object is used for - both. +* For the contents of ``<title>`` and ``<description>``, Django tries + calling the methods ``item_title()`` and ``item_description()`` on + the :class:`~django.contrib.syndication.views.Feed` class. They are passed + a single parameter, ``item``, which is the object itself. These are + optional; by default, the unicode representation of the object is used for + both. - If you want to do any special formatting for either the title or - description, :doc:`Django templates </topics/templates>` can be used - instead. Their paths can be specified with the ``title_template`` and - ``description_template`` attributes on the - :class:`~django.contrib.syndication.views.Feed` class. The templates are - rendered for each item and are passed two template context variables: + If you want to do any special formatting for either the title or + description, :doc:`Django templates </topics/templates>` can be used + instead. Their paths can be specified with the ``title_template`` and + ``description_template`` attributes on the + :class:`~django.contrib.syndication.views.Feed` class. The templates are + rendered for each item and are passed two template context variables: - * ``{{ obj }}`` -- The current object (one of whichever objects you - returned in ``items()``). + * ``{{ obj }}`` -- The current object (one of whichever objects you + returned in ``items()``). - * ``{{ site }}`` -- A :class:`django.contrib.sites.models.Site` object - representing the current site. This is useful for ``{{ site.domain - }}`` or ``{{ site.name }}``. If you do *not* have the Django sites - framework installed, this will be set to a - :class:`django.contrib.sites.models.RequestSite` object. See the - :ref:`RequestSite section of the sites framework documentation - <requestsite-objects>` for more. + * ``{{ site }}`` -- A :class:`django.contrib.sites.models.Site` object + representing the current site. This is useful for ``{{ site.domain + }}`` or ``{{ site.name }}``. If you do *not* have the Django sites + framework installed, this will be set to a + :class:`django.contrib.sites.models.RequestSite` object. See the + :ref:`RequestSite section of the sites framework documentation + <requestsite-objects>` for more. - See `a complex example`_ below that uses a description template. + See `a complex example`_ below that uses a description template. - * 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 - :class:`~django.contrib.syndication.views.Feed` class. In a similar way to - the title and description, it is passed it a single parameter, - ``item``. If that method doesn't exist, Django tries executing a - ``get_absolute_url()`` method on that object. Both - ``get_absolute_url()`` and ``item_link()`` should return the - item's URL as a normal Python string. As with ``get_absolute_url()``, the - result of ``item_link()`` will be included directly in the URL, so you - are responsible for doing all necessary URL quoting and conversion to - ASCII inside the method itself. +* 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 + :class:`~django.contrib.syndication.views.Feed` class. In a similar way to + the title and description, it is passed it a single parameter, + ``item``. If that method doesn't exist, Django tries executing a + ``get_absolute_url()`` method on that object. Both + ``get_absolute_url()`` and ``item_link()`` should return the + item's URL as a normal Python string. As with ``get_absolute_url()``, the + result of ``item_link()`` will be included directly in the URL, so you + are responsible for doing all necessary URL quoting and conversion to + ASCII inside the method itself. .. _chicagocrime.org: http://www.chicagocrime.org/ @@ -170,8 +170,8 @@ items based on information in the feed's URL. On chicagocrime.org, the police-beat feeds are accessible via URLs like this: - * :file:`/beats/613/rss/` -- Returns recent crimes for beat 613. - * :file:`/beats/1424/rss/` -- Returns recent crimes for beat 1424. +* :file:`/beats/613/rss/` -- Returns recent crimes for beat 613. +* :file:`/beats/1424/rss/` -- Returns recent crimes for beat 1424. These can be matched with a :doc:`URLconf </topics/http/urls>` line such as:: @@ -213,12 +213,12 @@ illustrates that they can be either strings *or* methods. For each of ``title``, ``link`` and ``description``, Django follows this algorithm: - * First, it tries to call a method, passing the ``obj`` argument, where - ``obj`` is the object returned by ``get_object()``. +* First, it tries to call a method, passing the ``obj`` argument, where + ``obj`` is the object returned by ``get_object()``. - * Failing that, it tries to call a method with no arguments. +* Failing that, it tries to call a method with no arguments. - * Failing that, it uses the class attribute. +* Failing that, it uses the class attribute. Also note that ``items()`` also follows the same algorithm -- first, it tries ``items(obj)``, then ``items()``, then finally an ``items`` @@ -252,9 +252,9 @@ Note that you set ``feed_type`` to a class object, not an instance. Currently available feed types are: - * :class:`django.utils.feedgenerator.Rss201rev2Feed` (RSS 2.01. Default.) - * :class:`django.utils.feedgenerator.RssUserland091Feed` (RSS 0.91.) - * :class:`django.utils.feedgenerator.Atom1Feed` (Atom 1.0.) +* :class:`django.utils.feedgenerator.Rss201rev2Feed` (RSS 2.01. Default.) +* :class:`django.utils.feedgenerator.RssUserland091Feed` (RSS 0.91.) +* :class:`django.utils.feedgenerator.Atom1Feed` (Atom 1.0.) Enclosures ---------- @@ -788,13 +788,13 @@ also create custom feed generator subclasses for use with the ``feed_type`` The :mod:`~django.utils.feedgenerator` module contains a base class: - * :class:`django.utils.feedgenerator.SyndicationFeed` +* :class:`django.utils.feedgenerator.SyndicationFeed` and several subclasses: - * :class:`django.utils.feedgenerator.RssUserland091Feed` - * :class:`django.utils.feedgenerator.Rss201rev2Feed` - * :class:`django.utils.feedgenerator.Atom1Feed` +* :class:`django.utils.feedgenerator.RssUserland091Feed` +* :class:`django.utils.feedgenerator.Rss201rev2Feed` +* :class:`django.utils.feedgenerator.Atom1Feed` Each of these three classes knows how to render a certain type of feed as XML. They share this interface: @@ -803,22 +803,22 @@ They share this interface: Initialize the feed with the given dictionary of metadata, which applies to the entire feed. Required keyword arguments are: - * ``title`` - * ``link`` - * ``description`` + * ``title`` + * ``link`` + * ``description`` There's also a bunch of other optional keywords: - * ``language`` - * ``author_email`` - * ``author_name`` - * ``author_link`` - * ``subtitle`` - * ``categories`` - * ``feed_url`` - * ``feed_copyright`` - * ``feed_guid`` - * ``ttl`` + * ``language`` + * ``author_email`` + * ``author_name`` + * ``author_link`` + * ``subtitle`` + * ``categories`` + * ``feed_url`` + * ``feed_copyright`` + * ``feed_guid`` + * ``ttl`` Any extra keyword arguments you pass to ``__init__`` will be stored in ``self.feed`` for use with `custom feed generators`_. @@ -831,31 +831,31 @@ They share this interface: Required keyword arguments are: - * ``title`` - * ``link`` - * ``description`` + * ``title`` + * ``link`` + * ``description`` Optional keyword arguments are: - * ``author_email`` - * ``author_name`` - * ``author_link`` - * ``pubdate`` - * ``comments`` - * ``unique_id`` - * ``enclosure`` - * ``categories`` - * ``item_copyright`` - * ``ttl`` + * ``author_email`` + * ``author_name`` + * ``author_link`` + * ``pubdate`` + * ``comments`` + * ``unique_id`` + * ``enclosure`` + * ``categories`` + * ``item_copyright`` + * ``ttl`` Extra keyword arguments will be stored for `custom feed generators`_. All parameters, if given, should be Unicode objects, except: - * ``pubdate`` should be a Python :class:`~datetime.datetime` object. - * ``enclosure`` should be an instance of - :class:`django.utils.feedgenerator.Enclosure`. - * ``categories`` should be a sequence of Unicode objects. + * ``pubdate`` should be a Python :class:`~datetime.datetime` object. + * ``enclosure`` should be an instance of + :class:`django.utils.feedgenerator.Enclosure`. + * ``categories`` should be a sequence of Unicode objects. :meth:`.SyndicationFeed.write` Outputs the feed in the given encoding to outfile, which is a file-like object. diff --git a/docs/ref/contrib/webdesign.txt b/docs/ref/contrib/webdesign.txt index ded878d544..0e739484b9 100644 --- a/docs/ref/contrib/webdesign.txt +++ b/docs/ref/contrib/webdesign.txt @@ -36,21 +36,21 @@ Usage:: The ``{% lorem %}`` tag can be used with zero, one, two or three arguments. The arguments are: - =========== ============================================================= - Argument Description - =========== ============================================================= - ``count`` A number (or variable) containing the number of paragraphs or - words to generate (default is 1). - ``method`` Either ``w`` for words, ``p`` for HTML paragraphs or ``b`` - for plain-text paragraph blocks (default is ``b``). - ``random`` The word ``random``, which if given, does not use the common - paragraph ("Lorem ipsum dolor sit amet...") when generating - text. - =========== ============================================================= +=========== ============================================================= +Argument Description +=========== ============================================================= +``count`` A number (or variable) containing the number of paragraphs or + words to generate (default is 1). +``method`` Either ``w`` for words, ``p`` for HTML paragraphs or ``b`` + for plain-text paragraph blocks (default is ``b``). +``random`` The word ``random``, which if given, does not use the common + paragraph ("Lorem ipsum dolor sit amet...") when generating + text. +=========== ============================================================= Examples: - * ``{% lorem %}`` will output the common "lorem ipsum" paragraph. - * ``{% lorem 3 p %}`` will output the common "lorem ipsum" paragraph - and two random paragraphs each wrapped in HTML ``<p>`` tags. - * ``{% lorem 2 w random %}`` will output two random Latin words. +* ``{% lorem %}`` will output the common "lorem ipsum" paragraph. +* ``{% lorem 3 p %}`` will output the common "lorem ipsum" paragraph + and two random paragraphs each wrapped in HTML ``<p>`` tags. +* ``{% lorem 2 w random %}`` will output two random Latin words. diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 24f5bee0d0..0312d264cf 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -257,10 +257,10 @@ Refer to the :doc:`settings documentation </ref/settings>`. Connection settings are used in this order: - 1. :setting:`OPTIONS`. - 2. :setting:`NAME`, :setting:`USER`, :setting:`PASSWORD`, - :setting:`HOST`, :setting:`PORT` - 3. MySQL option files. +1. :setting:`OPTIONS`. +2. :setting:`NAME`, :setting:`USER`, :setting:`PASSWORD`, + :setting:`HOST`, :setting:`PORT` +3. MySQL option files. In other words, if you set the name of the database in :setting:`OPTIONS`, this will take precedence over :setting:`NAME`, which would override @@ -304,25 +304,25 @@ default storage engine to the desired engine. If you're using a hosting service and can't change your server's default storage engine, you have a couple of options. - * After the tables are created, execute an ``ALTER TABLE`` statement to - convert a table to a new storage engine (such as InnoDB):: +* After the tables are created, execute an ``ALTER TABLE`` statement to + convert a table to a new storage engine (such as InnoDB):: - ALTER TABLE <tablename> ENGINE=INNODB; + ALTER TABLE <tablename> ENGINE=INNODB; - This can be tedious if you have a lot of tables. + This can be tedious if you have a lot of tables. - * Another option is to use the ``init_command`` option for MySQLdb prior to - creating your tables:: +* Another option is to use the ``init_command`` option for MySQLdb prior to + creating your tables:: - 'OPTIONS': { - 'init_command': 'SET storage_engine=INNODB', - } + 'OPTIONS': { + 'init_command': 'SET storage_engine=INNODB', + } - This sets the default storage engine upon connecting to the database. - After your tables have been created, you should remove this option. + This sets the default storage engine upon connecting to the database. + After your tables have been created, you should remove this option. - * Another method for changing the storage engine is described in - AlterModelOnSyncDB_. +* Another method for changing the storage engine is described in + AlterModelOnSyncDB_. .. _AlterModelOnSyncDB: http://code.djangoproject.com/wiki/AlterModelOnSyncDB @@ -422,13 +422,13 @@ SQLite 3.3.6 or newer strongly recommended Versions of SQLite 3.3.5 and older contains the following bugs: - * A bug when `handling`_ ``ORDER BY`` parameters. This can cause problems when - you use the ``select`` parameter for the ``extra()`` QuerySet method. The bug - can be identified by the error message ``OperationalError: ORDER BY terms - must not be non-integer constants``. +* A bug when `handling`_ ``ORDER BY`` parameters. This can cause problems when + you use the ``select`` parameter for the ``extra()`` QuerySet method. The bug + can be identified by the error message ``OperationalError: ORDER BY terms + must not be non-integer constants``. - * A bug when handling `aggregation`_ together with DateFields and - DecimalFields. +* A bug when handling `aggregation`_ together with DateFields and + DecimalFields. .. _handling: http://www.sqlite.org/cvstrac/tktview?tn=1768 .. _aggregation: http://code.djangoproject.com/ticket/10031 @@ -507,24 +507,24 @@ is locked`` error. If you're getting this error, you can solve it by: - * Switching to another database backend. At a certain point SQLite becomes - too "lite" for real-world applications, and these sorts of concurrency - errors indicate you've reached that point. +* Switching to another database backend. At a certain point SQLite becomes + too "lite" for real-world applications, and these sorts of concurrency + errors indicate you've reached that point. - * Rewriting your code to reduce concurrency and ensure that database - transactions are short-lived. +* Rewriting your code to reduce concurrency and ensure that database + transactions are short-lived. - * Increase the default timeout value by setting the ``timeout`` database - option option:: +* Increase the default timeout value by setting the ``timeout`` database + option option:: - 'OPTIONS': { - # ... - 'timeout': 20, - # ... - } + 'OPTIONS': { + # ... + 'timeout': 20, + # ... + } - This will simply make SQLite wait a bit longer before throwing "database - is locked" errors; it won't really do anything to solve them. + This will simply make SQLite wait a bit longer before throwing "database + is locked" errors; it won't really do anything to solve them. ``QuerySet.select_for_update()`` not supported ---------------------------------------------- @@ -567,19 +567,19 @@ required. In order for the ``python manage.py syncdb`` command to work, your Oracle database user must have privileges to run the following commands: - * CREATE TABLE - * CREATE SEQUENCE - * CREATE PROCEDURE - * CREATE TRIGGER +* CREATE TABLE +* CREATE SEQUENCE +* CREATE PROCEDURE +* CREATE TRIGGER To run Django's test suite, the user needs these *additional* privileges: - * CREATE USER - * DROP USER - * CREATE TABLESPACE - * DROP TABLESPACE - * CONNECT WITH ADMIN OPTION - * RESOURCE WITH ADMIN OPTION +* CREATE USER +* DROP USER +* CREATE TABLESPACE +* DROP TABLESPACE +* CONNECT WITH ADMIN OPTION +* RESOURCE WITH ADMIN OPTION Connecting to the database -------------------------- @@ -721,16 +721,16 @@ assumption. The Oracle backend stores ``TextFields`` as ``NCLOB`` columns. Oracle imposes some limitations on the usage of such LOB columns in general: - * LOB columns may not be used as primary keys. +* LOB columns may not be used as primary keys. - * LOB columns may not be used in indexes. +* LOB columns may not be used in indexes. - * LOB columns may not be used in a ``SELECT DISTINCT`` list. This means that - attempting to use the ``QuerySet.distinct`` method on a model that - includes ``TextField`` columns will result in an error when run against - Oracle. As a workaround, use the ``QuerySet.defer`` method in conjunction - with ``distinct()`` to prevent ``TextField`` columns from being included in - the ``SELECT DISTINCT`` list. +* LOB columns may not be used in a ``SELECT DISTINCT`` list. This means that +attempting to use the ``QuerySet.distinct`` method on a model that +includes ``TextField`` columns will result in an error when run against +Oracle. As a workaround, use the ``QuerySet.defer`` method in conjunction +with ``distinct()`` to prevent ``TextField`` columns from being included in +the ``SELECT DISTINCT`` list. .. _third-party-notes: diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 88c2569607..f397b04a1f 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -9,10 +9,10 @@ In addition, ``manage.py`` is automatically created in each Django project. ``manage.py`` is a thin wrapper around ``django-admin.py`` that takes care of two things for you before delegating to ``django-admin.py``: - * It puts your project's package on ``sys.path``. +* It puts your project's package on ``sys.path``. - * It sets the :envvar:`DJANGO_SETTINGS_MODULE` environment variable so that - it points to your project's ``settings.py`` file. +* It sets the :envvar:`DJANGO_SETTINGS_MODULE` environment variable so that + it points to your project's ``settings.py`` file. The ``django-admin.py`` script should be on your system path if you installed Django via its ``setup.py`` utility. If it's not on your path, you can find it @@ -128,9 +128,9 @@ Runs the command-line client for the database engine specified in your ``ENGINE`` setting, with the connection parameters specified in your :setting:`USER`, :setting:`PASSWORD`, etc., settings. - * For PostgreSQL, this runs the ``psql`` command-line client. - * For MySQL, this runs the ``mysql`` command-line client. - * For SQLite, this runs the ``sqlite3`` command-line client. +* For PostgreSQL, this runs the ``psql`` command-line client. +* For MySQL, this runs the ``mysql`` command-line client. +* For SQLite, this runs the ``sqlite3`` command-line client. This command assumes the programs are on your ``PATH`` so that a simple call to the program name (``psql``, ``mysql``, ``sqlite3``) will find the program in @@ -257,19 +257,19 @@ As you might expect, the created models will have an attribute for every field in the table. Note that ``inspectdb`` has a few special cases in its field-name output: - * If ``inspectdb`` cannot map a column's type to a model field type, it'll - use ``TextField`` and will insert the Python comment - ``'This field type is a guess.'`` next to the field in the generated - model. +* If ``inspectdb`` cannot map a column's type to a model field type, it'll + use ``TextField`` and will insert the Python comment + ``'This field type is a guess.'`` next to the field in the generated + model. - * If the database column name is a Python reserved word (such as - ``'pass'``, ``'class'`` or ``'for'``), ``inspectdb`` will append - ``'_field'`` to the attribute name. For example, if a table has a column - ``'for'``, the generated model will have a field ``'for_field'``, with - the ``db_column`` attribute set to ``'for'``. ``inspectdb`` will insert - the Python comment - ``'Field renamed because it was a Python reserved word.'`` next to the - field. +* If the database column name is a Python reserved word (such as + ``'pass'``, ``'class'`` or ``'for'``), ``inspectdb`` will append + ``'_field'`` to the attribute name. For example, if a table has a column + ``'for'``, the generated model will have a field ``'for_field'``, with + the ``db_column`` attribute set to ``'for'``. ``inspectdb`` will insert + the Python comment + ``'Field renamed because it was a Python reserved word.'`` next to the + field. This feature is meant as a shortcut, not as definitive model generation. After you run it, you'll want to look over the generated models yourself to make @@ -309,9 +309,9 @@ fixture can be distributed over multiple directories, in multiple applications. Django will search in three locations for fixtures: - 1. In the ``fixtures`` directory of every installed application - 2. In any directory named in the :setting:`FIXTURE_DIRS` setting - 3. In the literal path named by the fixture +1. In the ``fixtures`` directory of every installed application +2. In any directory named in the :setting:`FIXTURE_DIRS` setting +3. In the literal path named by the fixture Django will load any and all fixtures it finds in these locations that match the provided fixture names. @@ -438,8 +438,8 @@ Example usage:: Use the ``--domain`` or ``-d`` option to change the domain of the messages files. Currently supported: - * ``django`` for all ``*.py``, ``*.html`` and ``*.txt`` files (default) - * ``djangojs`` for ``*.js`` files +* ``django`` for all ``*.py``, ``*.html`` and ``*.txt`` files (default) +* ``djangojs`` for ``*.js`` files .. django-admin-option:: --symlinks @@ -984,25 +984,25 @@ For example, this command:: ...would perform the following steps: - 1. Create a test database, as described in :doc:`/topics/testing`. - 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 - this newly created test database instead of your production database. +1. Create a test database, as described in :doc:`/topics/testing`. +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 + this newly created test database instead of your production database. This is useful in a number of ways: - * When you're writing :doc:`unit tests </topics/testing>` of how your views - act with certain fixture data, you can use ``testserver`` to interact with - the views in a Web browser, manually. +* When you're writing :doc:`unit tests </topics/testing>` of how your views + act with certain fixture data, you can use ``testserver`` to interact with + the views in a Web browser, manually. - * Let's say you're developing your Django application and have a "pristine" - copy of a database that you'd like to interact with. You can dump your - database to a fixture (using the ``dumpdata`` command, explained above), - then use ``testserver`` to run your Web application with that data. With - this arrangement, you have the flexibility of messing up your data - in any way, knowing that whatever data changes you're making are only - being made to a test database. +* Let's say you're developing your Django application and have a "pristine" + copy of a database that you'd like to interact with. You can dump your + database to a fixture (using the ``dumpdata`` command, explained above), + then use ``testserver`` to run your Web application with that data. With + this arrangement, you have the flexibility of messing up your data + in any way, knowing that whatever data changes you're making are only + being made to a test database. Note that this server does *not* automatically detect changes to your Python source code (as ``runserver`` does). It does, however, detect changes to @@ -1197,10 +1197,10 @@ Example usage:: Use ``--verbosity`` to specify the amount of notification and debug information that ``django-admin.py`` should print to the console. - * ``0`` means no output. - * ``1`` means normal output (default). - * ``2`` means verbose output. - * ``3`` means *very* verbose output. +* ``0`` means no output. +* ``1`` means normal output (default). +* ``2`` means verbose output. +* ``3`` means *very* verbose output. Common options ============== @@ -1259,13 +1259,13 @@ another program. The colors used for syntax highlighting can be customized. Django ships with three color palettes: - * ``dark``, suited to terminals that show white text on a black - background. This is the default palette. +* ``dark``, suited to terminals that show white text on a black + background. This is the default palette. - * ``light``, suited to terminals that show black text on a white - background. +* ``light``, suited to terminals that show black text on a white + background. - * ``nocolor``, which disables syntax highlighting. +* ``nocolor``, which disables syntax highlighting. You select a palette by setting a ``DJANGO_COLORS`` environment variable to specify the palette you want to use. For example, to @@ -1277,47 +1277,47 @@ would run the following at a command prompt:: You can also customize the colors that are used. Django specifies a number of roles in which color is used: - * ``error`` - A major error. - * ``notice`` - A minor error. - * ``sql_field`` - The name of a model field in SQL. - * ``sql_coltype`` - The type of a model field in SQL. - * ``sql_keyword`` - A SQL keyword. - * ``sql_table`` - The name of a model in SQL. - * ``http_info`` - A 1XX HTTP Informational server response. - * ``http_success`` - A 2XX HTTP Success server response. - * ``http_not_modified`` - A 304 HTTP Not Modified server response. - * ``http_redirect`` - A 3XX HTTP Redirect server response other than 304. - * ``http_not_found`` - A 404 HTTP Not Found server response. - * ``http_bad_request`` - A 4XX HTTP Bad Request server response other than 404. - * ``http_server_error`` - A 5XX HTTP Server Error response. +* ``error`` - A major error. +* ``notice`` - A minor error. +* ``sql_field`` - The name of a model field in SQL. +* ``sql_coltype`` - The type of a model field in SQL. +* ``sql_keyword`` - A SQL keyword. +* ``sql_table`` - The name of a model in SQL. +* ``http_info`` - A 1XX HTTP Informational server response. +* ``http_success`` - A 2XX HTTP Success server response. +* ``http_not_modified`` - A 304 HTTP Not Modified server response. +* ``http_redirect`` - A 3XX HTTP Redirect server response other than 304. +* ``http_not_found`` - A 404 HTTP Not Found server response. +* ``http_bad_request`` - A 4XX HTTP Bad Request server response other than 404. +* ``http_server_error`` - A 5XX HTTP Server Error response. Each of these roles can be assigned a specific foreground and background color, from the following list: - * ``black`` - * ``red`` - * ``green`` - * ``yellow`` - * ``blue`` - * ``magenta`` - * ``cyan`` - * ``white`` +* ``black`` +* ``red`` +* ``green`` +* ``yellow`` +* ``blue`` +* ``magenta`` +* ``cyan`` +* ``white`` Each of these colors can then be modified by using the following display options: - * ``bold`` - * ``underscore`` - * ``blink`` - * ``reverse`` - * ``conceal`` +* ``bold`` +* ``underscore`` +* ``blink`` +* ``reverse`` +* ``conceal`` A color specification follows one of the following patterns: - * ``role=fg`` - * ``role=fg/bg`` - * ``role=fg,option,option`` - * ``role=fg/bg,option,option`` +* ``role=fg`` +* ``role=fg/bg`` +* ``role=fg,option,option`` +* ``role=fg/bg,option,option`` where ``role`` is the name of a valid color role, ``fg`` is the foreground color, ``bg`` is the background color and each ``option`` @@ -1348,10 +1348,10 @@ script, which lives in ``extras/django_bash_completion`` in the Django distribution. It enables tab-completion of ``django-admin.py`` and ``manage.py`` commands, so you can, for instance... - * Type ``django-admin.py``. - * Press [TAB] to see all available options. - * Type ``sql``, then [TAB], to see all available options whose names start - with ``sql``. +* Type ``django-admin.py``. +* Press [TAB] to see all available options. +* Type ``sql``, then [TAB], to see all available options whose names start + with ``sql``. See :doc:`/howto/custom-management-commands` for how to add customized actions. diff --git a/docs/ref/exceptions.txt b/docs/ref/exceptions.txt index 9177cc0feb..e91a5dd85e 100644 --- a/docs/ref/exceptions.txt +++ b/docs/ref/exceptions.txt @@ -84,15 +84,15 @@ FieldError The :exc:`FieldError` exception is raised when there is a problem with a model field. This can happen for several reasons: - - A field in a model clashes with a field of the same name from an - abstract base class - - An infinite loop is caused by ordering - - A keyword cannot be parsed from the filter parameters - - A field cannot be determined from a keyword in the query - parameters - - A join is not permitted on the specified field - - A field name is invalid - - A query contains invalid order_by arguments + - A field in a model clashes with a field of the same name from an + abstract base class + - An infinite loop is caused by ordering + - A keyword cannot be parsed from the filter parameters + - A field cannot be determined from a keyword in the query + parameters + - A join is not permitted on the specified field + - A field name is invalid + - A query contains invalid order_by arguments ValidationError --------------- diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 070f9ef19a..86b6bb453e 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -19,11 +19,11 @@ Bound and unbound forms A :class:`Form` instance is either **bound** to a set of data, or **unbound**. - * If it's **bound** to a set of data, it's capable of validating that data - and rendering the form as HTML with the data displayed in the HTML. +* If it's **bound** to a set of data, it's capable of validating that data + and rendering the form as HTML with the data displayed in the HTML. - * If it's **unbound**, it cannot do validation (because there's no data to - validate!), but it can still render the blank form as HTML. +* If it's **unbound**, it cannot do validation (because there's no data to + validate!), but it can still render the blank form as HTML. .. class:: Form @@ -292,29 +292,29 @@ include ``checked="checked"`` if appropriate:: This default output is a two-column HTML table, with a ``<tr>`` for each field. Notice the following: - * For flexibility, the output does *not* include the ``<table>`` and - ``</table>`` tags, nor does it include the ``<form>`` and ``</form>`` - tags or an ``<input type="submit">`` tag. It's your job to do that. +* For flexibility, the output does *not* include the ``<table>`` and + ``</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">``. - ``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. +* Each field type has a default HTML representation. ``CharField`` and + ``EmailField`` are represented by an ``<input type="text">``. + ``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. - * The HTML ``name`` for each tag is taken directly from its attribute name - in the ``ContactForm`` class. +* The HTML ``name`` for each tag is taken directly from its attribute name + in the ``ContactForm`` class. - * The text label for each field -- e.g. ``'Subject:'``, ``'Message:'`` and - ``'Cc myself:'`` is generated from the field name by converting all - underscores to spaces and upper-casing the first letter. Again, note - these are merely sensible defaults; you can also specify labels manually. +* The text label for each field -- e.g. ``'Subject:'``, ``'Message:'`` and + ``'Cc myself:'`` is generated from the field name by converting all + underscores to spaces and upper-casing the first letter. Again, note + these are merely sensible defaults; you can also specify labels manually. - * Each text label is surrounded in an HTML ``<label>`` tag, which points - to the appropriate form field via its ``id``. Its ``id``, in turn, is - generated by prepending ``'id_'`` to the field name. The ``id`` - attributes and ``<label>`` tags are included in the output by default, to - follow best practices, but you can change that behavior. +* Each text label is surrounded in an HTML ``<label>`` tag, which points + to the appropriate form field via its ``id``. Its ``id``, in turn, is + generated by prepending ``'id_'`` to the field name. The ``id`` + attributes and ``<label>`` tags are included in the output by default, to + follow best practices, but you can change that behavior. Although ``<table>`` output is the default output style when you ``print`` a form, other output styles are available. Each style is available as a method on diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 54fdec6d38..fc8665b252 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -302,13 +302,13 @@ For each field, we describe the default widget used if you don't specify the field has ``required=True``. * Error message keys: ``required`` -.. note:: + .. note:: - Since all ``Field`` subclasses have ``required=True`` by default, the - validation condition here is important. If you want to include a boolean - in your form that can be either ``True`` or ``False`` (e.g. a checked or - unchecked checkbox), you must remember to pass in ``required=False`` when - creating the ``BooleanField``. + Since all ``Field`` subclasses have ``required=True`` by default, the + validation condition here is important. If you want to include a boolean + in your form that can be either ``True`` or ``False`` (e.g. a checked or + unchecked checkbox), you must remember to pass in ``required=False`` when + creating the ``BooleanField``. ``CharField`` ~~~~~~~~~~~~~ @@ -322,10 +322,10 @@ For each field, we describe the default widget used if you don't specify Otherwise, all inputs are valid. * Error message keys: ``required``, ``max_length``, ``min_length`` -Has two optional arguments for validation: + Has two optional arguments for validation: -.. attribute:: CharField.max_length -.. attribute:: CharField.min_length + .. attribute:: max_length + .. attribute:: min_length If provided, these arguments ensure that the string is at most or at least the given length. @@ -341,25 +341,25 @@ Has two optional arguments for validation: * Validates that the given value exists in the list of choices. * Error message keys: ``required``, ``invalid_choice`` -The ``invalid_choice`` error message may contain ``%(value)s``, which will be -replaced with the selected choice. + The ``invalid_choice`` error message may contain ``%(value)s``, which will be + replaced with the selected choice. -Takes one extra required argument: + Takes one extra required argument: -.. attribute:: ChoiceField.choices + .. attribute:: choices - An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this - field. This argument accepts the same formats as the ``choices`` argument - to a model field. See the :ref:`model field reference documentation on - choices <field-choices>` for more details. + An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this + field. This argument accepts the same formats as the ``choices`` argument + to a model field. See the :ref:`model field reference documentation on + choices <field-choices>` for more details. ``TypedChoiceField`` ~~~~~~~~~~~~~~~~~~~~ .. class:: TypedChoiceField(**kwargs) -Just like a :class:`ChoiceField`, except :class:`TypedChoiceField` takes two -extra arguments, ``coerce`` and ``empty_value``. + Just like a :class:`ChoiceField`, except :class:`TypedChoiceField` takes two + extra arguments, ``coerce`` and ``empty_value``. * Default widget: ``Select`` * Empty value: Whatever you've given as ``empty_value`` @@ -368,20 +368,20 @@ extra arguments, ``coerce`` and ``empty_value``. coerced. * Error message keys: ``required``, ``invalid_choice`` -Takes extra arguments: + Takes extra arguments: -.. attribute:: TypedChoiceField.coerce + .. attribute:: coerce - A function that takes one argument and returns a coerced value. Examples - include the built-in ``int``, ``float``, ``bool`` and other types. Defaults - to an identity function. + A function that takes one argument and returns a coerced value. Examples + include the built-in ``int``, ``float``, ``bool`` and other types. Defaults + to an identity function. -.. attribute:: TypedChoiceField.empty_value + .. attribute:: empty_value - The value to use to represent "empty." Defaults to the empty string; - ``None`` is another common choice here. Note that this value will not be - coerced by the function given in the ``coerce`` argument, so choose it - accordingly. + The value to use to represent "empty." Defaults to the empty string; + ``None`` is another common choice here. Note that this value will not be + coerced by the function given in the ``coerce`` argument, so choose it + accordingly. ``DateField`` ~~~~~~~~~~~~~ @@ -395,20 +395,20 @@ Takes extra arguments: ``datetime.datetime`` or string formatted in a particular date format. * Error message keys: ``required``, ``invalid`` -Takes one optional argument: + Takes one optional argument: -.. attribute:: DateField.input_formats + .. attribute:: input_formats - A list of formats used to attempt to convert a string to a valid - ``datetime.date`` object. + A list of formats used to attempt to convert a string to a valid + ``datetime.date`` object. -If no ``input_formats`` argument is provided, the default input formats are:: + If no ``input_formats`` argument is provided, the default input formats are:: - '%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' + '%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' ``DateTimeField`` ~~~~~~~~~~~~~~~~~ @@ -422,24 +422,24 @@ If no ``input_formats`` argument is provided, the default input formats are:: ``datetime.date`` or string formatted in a particular datetime format. * Error message keys: ``required``, ``invalid`` -Takes one optional argument: + Takes one optional argument: -.. attribute:: DateTimeField.input_formats + .. attribute:: input_formats - A list of formats used to attempt to convert a string to a valid - ``datetime.datetime`` object. + A list of formats used to attempt to convert a string to a valid + ``datetime.datetime`` object. -If no ``input_formats`` argument is provided, the default input formats are:: + 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', # '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', # '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', # '10/25/06 14:30' - '%m/%d/%y', # '10/25/06' + '%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' + '%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', # '10/25/06 14:30' + '%m/%d/%y', # '10/25/06' ``DecimalField`` ~~~~~~~~~~~~~~~~ @@ -455,26 +455,26 @@ If no ``input_formats`` argument is provided, the default input formats are:: ``min_value``, ``max_digits``, ``max_decimal_places``, ``max_whole_digits`` -The ``max_value`` and ``min_value`` error messages may contain -``%(limit_value)s``, which will be substituted by the appropriate limit. + The ``max_value`` and ``min_value`` error messages may contain + ``%(limit_value)s``, which will be substituted by the appropriate limit. -Takes four optional arguments: + Takes four optional arguments: -.. attribute:: DecimalField.max_value -.. attribute:: DecimalField.min_value + .. attribute:: max_value + .. attribute:: min_value - These control the range of values permitted in the field, and should be - given as ``decimal.Decimal`` values. + These control the range of values permitted in the field, and should be + given as ``decimal.Decimal`` values. -.. attribute:: DecimalField.max_digits + .. attribute:: max_digits - The maximum number of digits (those before the decimal point plus those - after the decimal point, with leading zeros stripped) permitted in the - value. + The maximum number of digits (those before the decimal point plus those + after the decimal point, with leading zeros stripped) permitted in the + value. -.. attribute:: DecimalField.decimal_places + .. attribute:: decimal_places - The maximum number of decimal places permitted. + The maximum number of decimal places permitted. ``EmailField`` ~~~~~~~~~~~~~~ @@ -488,9 +488,9 @@ Takes four optional arguments: moderately complex regular expression. * Error message keys: ``required``, ``invalid`` -Has two optional arguments for validation, ``max_length`` and ``min_length``. -If provided, these arguments ensure that the string is at most or at least the -given length. + Has two optional arguments for validation, ``max_length`` and ``min_length``. + If provided, these arguments ensure that the string is at most or at least the + given length. .. versionchanged:: 1.2 The EmailField previously did not recognize email addresses as valid that @@ -510,20 +510,20 @@ given length. * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``, ``max_length`` -Has two optional arguments for validation, ``max_length`` and -``allow_empty_file``. If provided, these ensure that the file name is at -most the given length, and that validation will succeed even if the file -content is empty. + Has two optional arguments for validation, ``max_length`` and + ``allow_empty_file``. If provided, these ensure that the file name is at + most the given length, and that validation will succeed even if the file + content is empty. -To learn more about the ``UploadedFile`` object, see the :doc:`file uploads -documentation </topics/http/file-uploads>`. + To learn more about the ``UploadedFile`` object, see the :doc:`file uploads + documentation </topics/http/file-uploads>`. -When you use a ``FileField`` in a form, you must also remember to -:ref:`bind the file data to the form <binding-uploaded-files>`. + When you use a ``FileField`` in a form, you must also remember to + :ref:`bind the file data to the form <binding-uploaded-files>`. -The ``max_length`` error refers to the length of the filename. In the error -message for that key, ``%(max)d`` will be replaced with the maximum filename -length and ``%(length)d`` will be replaced with the current filename length. + The ``max_length`` error refers to the length of the filename. In the error + message for that key, ``%(max)d`` will be replaced with the maximum filename + length and ``%(length)d`` will be replaced with the current filename length. ``FilePathField`` ~~~~~~~~~~~~~~~~~ @@ -536,28 +536,30 @@ length and ``%(length)d`` will be replaced with the current filename length. * Validates that the selected choice exists in the list of choices. * Error message keys: ``required``, ``invalid_choice`` -The field allows choosing from files inside a certain directory. It takes three -extra arguments; only ``path`` is required: + The field allows choosing from files inside a certain directory. It takes three + extra arguments; only ``path`` is required: -.. attribute:: FilePathField.path + .. attribute:: path - The absolute path to the directory whose contents you want listed. This - directory must exist. + The absolute path to the directory whose contents you want listed. This + directory must exist. -.. attribute:: FilePathField.recursive + .. attribute:: recursive - If ``False`` (the default) only the direct contents of ``path`` will be - offered as choices. If ``True``, the directory will be descended into - recursively and all descendants will be listed as choices. + If ``False`` (the default) only the direct contents of ``path`` will be + offered as choices. If ``True``, the directory will be descended into + recursively and all descendants will be listed as choices. -.. attribute:: FilePathField.match + .. attribute:: match - A regular expression pattern; only files with names matching this expression - will be allowed as choices. + A regular expression pattern; only files with names matching this expression + will be allowed as choices. ``FloatField`` ~~~~~~~~~~~~~~ +.. class:: FloatField(**kwargs) + * Default widget: ``TextInput`` * Empty value: ``None`` * Normalizes to: A Python float. @@ -566,8 +568,8 @@ extra arguments; only ``path`` is required: * Error message keys: ``required``, ``invalid``, ``max_value``, ``min_value`` -Takes two optional arguments for validation, ``max_value`` and ``min_value``. -These control the range of values permitted in the field. + Takes two optional arguments for validation, ``max_value`` and ``min_value``. + These control the range of values permitted in the field. ``ImageField`` ~~~~~~~~~~~~~~ @@ -583,10 +585,10 @@ These control the range of values permitted in the field. * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``, ``invalid_image`` -Using an ImageField requires that the `Python Imaging Library`_ is installed. + Using an ImageField requires that the `Python Imaging Library`_ is installed. -When you use an ``ImageField`` on a form, you must also remember to -:ref:`bind the file data to the form <binding-uploaded-files>`. + When you use an ``ImageField`` on a form, you must also remember to + :ref:`bind the file data to the form <binding-uploaded-files>`. .. _Python Imaging Library: http://www.pythonware.com/products/pil/ @@ -603,13 +605,13 @@ When you use an ``ImageField`` on a form, you must also remember to * Error message keys: ``required``, ``invalid``, ``max_value``, ``min_value`` -The ``max_value`` and ``min_value`` error messages may contain -``%(limit_value)s``, which will be substituted by the appropriate limit. + The ``max_value`` and ``min_value`` error messages may contain + ``%(limit_value)s``, which will be substituted by the appropriate limit. -Takes two optional arguments for validation: + Takes two optional arguments for validation: -.. attribute:: IntegerField.max_value -.. attribute:: IntegerField.min_value + .. attribute:: max_value + .. attribute:: min_value These control the range of values permitted in the field. @@ -628,11 +630,11 @@ Takes two optional arguments for validation: ``GenericIPAddressField`` ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. class:: GenericIPAddressField(**kwargs) - .. versionadded:: 1.4 -A field containing either an IPv4 or an IPv6 address. +.. class:: GenericIPAddressField(**kwargs) + + A field containing either an IPv4 or an IPv6 address. * Default widget: ``TextInput`` * Empty value: ``''`` (an empty string) @@ -641,26 +643,26 @@ A field containing either an IPv4 or an IPv6 address. * Validates that the given value is a valid IP address. * Error message keys: ``required``, ``invalid`` -The IPv6 address normalization follows :rfc:`4291#section-2.2` section 2.2, -including using the IPv4 format suggested in paragraph 3 of that section, like -``::ffff:192.0.2.0``. For example, ``2001:0::0:01`` would be normalized to -``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All characters -are converted to lowercase. + The IPv6 address normalization follows :rfc:`4291#section-2.2` section 2.2, + including using the IPv4 format suggested in paragraph 3 of that section, like + ``::ffff:192.0.2.0``. For example, ``2001:0::0:01`` would be normalized to + ``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All characters + are converted to lowercase. -Takes two optional arguments: + Takes two optional arguments: -.. attribute:: GenericIPAddressField.protocol + .. attribute:: protocol - Limits valid inputs to the specified protocol. - Accepted values are ``both`` (default), ``IPv4`` - or ``IPv6``. Matching is case insensitive. + Limits valid inputs to the specified protocol. + Accepted values are ``both`` (default), ``IPv4`` + or ``IPv6``. Matching is case insensitive. -.. attribute:: GenericIPAddressField.unpack_ipv4 + .. attribute:: unpack_ipv4 - Unpacks IPv4 mapped addresses like ``::ffff::192.0.2.1``. - If this option is enabled that address would be unpacked to - ``192.0.2.1``. Default is disabled. Can only be used - when ``protocol`` is set to ``'both'``. + Unpacks IPv4 mapped addresses like ``::ffff::192.0.2.1``. + If this option is enabled that address would be unpacked to + ``192.0.2.1``. Default is disabled. Can only be used + when ``protocol`` is set to ``'both'``. ``MultipleChoiceField`` ~~~~~~~~~~~~~~~~~~~~~~~ @@ -674,20 +676,20 @@ Takes two optional arguments: of choices. * Error message keys: ``required``, ``invalid_choice``, ``invalid_list`` -The ``invalid_choice`` error message may contain ``%(value)s``, which will be -replaced with the selected choice. + The ``invalid_choice`` error message may contain ``%(value)s``, which will be + replaced with the selected choice. -Takes one extra required argument, ``choices``, as for ``ChoiceField``. + Takes one extra required argument, ``choices``, as for ``ChoiceField``. ``TypedMultipleChoiceField`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. class:: TypedMultipleChoiceField(**kwargs) - .. versionadded:: 1.3 -Just like a :class:`MultipleChoiceField`, except :class:`TypedMultipleChoiceField` -takes two extra arguments, ``coerce`` and ``empty_value``. +.. class:: TypedMultipleChoiceField(**kwargs) + + Just like a :class:`MultipleChoiceField`, except :class:`TypedMultipleChoiceField` + takes two extra arguments, ``coerce`` and ``empty_value``. * Default widget: ``SelectMultiple`` * Empty value: Whatever you've given as ``empty_value`` @@ -697,10 +699,10 @@ takes two extra arguments, ``coerce`` and ``empty_value``. coerced. * Error message keys: ``required``, ``invalid_choice`` -The ``invalid_choice`` error message may contain ``%(value)s``, which will be -replaced with the selected choice. + The ``invalid_choice`` error message may contain ``%(value)s``, which will be + replaced with the selected choice. -Takes two extra arguments, ``coerce`` and ``empty_value``, as for ``TypedChoiceField``. + Takes two extra arguments, ``coerce`` and ``empty_value``, as for ``TypedChoiceField``. ``NullBooleanField`` ~~~~~~~~~~~~~~~~~~~~ @@ -724,20 +726,20 @@ Takes two extra arguments, ``coerce`` and ``empty_value``, as for ``TypedChoiceF expression. * Error message keys: ``required``, ``invalid`` -Takes one required argument: + Takes one required argument: -.. attribute:: RegexField.regex + .. attribute:: regex - A regular expression specified either as a string or a compiled regular - expression object. + A regular expression specified either as a string or a compiled regular + expression object. -Also takes ``max_length`` and ``min_length``, which work just as they do for -``CharField``. + Also takes ``max_length`` and ``min_length``, which work just as they do for + ``CharField``. -The optional argument ``error_message`` is also accepted for backwards -compatibility. The preferred way to provide an error message is to use the -``error_messages`` argument, passing a dictionary with ``'invalid'`` as a key -and the error message as the value. + The optional argument ``error_message`` is also accepted for backwards + compatibility. The preferred way to provide an error message is to use the + ``error_messages`` argument, passing a dictionary with ``'invalid'`` as a key + and the error message as the value. ``SlugField`` ~~~~~~~~~~~~~ @@ -751,8 +753,8 @@ and the error message as the value. underscores, and hyphens. * Error messages: ``required``, ``invalid`` -This field is intended for use in representing a model -:class:`~django.db.models.SlugField` in forms. + This field is intended for use in representing a model + :class:`~django.db.models.SlugField` in forms. ``TimeField`` ~~~~~~~~~~~~~ @@ -766,17 +768,17 @@ This field is intended for use in representing a model formatted in a particular time format. * Error message keys: ``required``, ``invalid`` -Takes one optional argument: + Takes one optional argument: -.. attribute:: TimeField.input_formats + .. attribute:: input_formats - A list of formats used to attempt to convert a string to a valid - ``datetime.time`` object. + A list of formats used to attempt to convert a string to a valid + ``datetime.time`` object. -If no ``input_formats`` argument is provided, the default input formats are:: + If no ``input_formats`` argument is provided, the default input formats are:: - '%H:%M:%S', # '14:30:59' - '%H:%M', # '14:30' + '%H:%M:%S', # '14:30:59' + '%H:%M', # '14:30' ``URLField`` ~~~~~~~~~~~~ @@ -789,27 +791,26 @@ If no ``input_formats`` argument is provided, the default input formats are:: * Validates that the given value is a valid URL. * Error message keys: ``required``, ``invalid``, ``invalid_link`` -Takes the following optional arguments: - -.. attribute:: URLField.max_length -.. attribute:: URLField.min_length + Takes the following optional arguments: - Same as ``CharField.max_length`` and ``CharField.min_length``. + .. attribute:: max_length + .. attribute:: min_length -.. attribute:: URLField.verify_exists + These are the same as ``CharField.max_length`` and ``CharField.min_length``. - If ``True``, the validator will attempt to load the given URL, raising - ``ValidationError`` if the page gives a 404. Defaults to ``False``. + .. attribute:: verify_exists -.. deprecated:: 1.4 + If ``True``, the validator will attempt to load the given URL, raising + ``ValidationError`` if the page gives a 404. Defaults to ``False``. - ``verify_exists`` was deprecated for security reasons and will be removed in - Django 1.5. This deprecation also removes ``validator_user_agent``. + .. deprecated:: 1.4 + ``verify_exists`` was deprecated for security reasons and will be removed in + Django 1.5. This deprecation also removes ``validator_user_agent``. -.. attribute:: URLField.validator_user_agent + .. attribute:: validator_user_agent - String used as the user-agent used when checking for a URL's existence. - Defaults to the value of the :setting:`URL_VALIDATOR_USER_AGENT` setting. + String used as the user-agent used when checking for a URL's existence. + Defaults to the value of the :setting:`URL_VALIDATOR_USER_AGENT` setting. .. versionchanged:: 1.2 The URLField previously did not recognize URLs as valid that contained an IDN @@ -832,20 +833,20 @@ Slightly complex built-in ``Field`` classes as an argument to the ``ComboField``. * Error message keys: ``required``, ``invalid`` -Takes one extra required argument: + Takes one extra required argument: -.. attribute:: ComboField.fields + .. attribute:: fields - The list of fields that should be used to validate the field's value (in - the order in which they are provided). + The list of fields that should be used to validate the field's value (in + the order in which they are provided). - >>> f = ComboField(fields=[CharField(max_length=20), EmailField()]) - >>> f.clean('test@example.com') - u'test@example.com' - >>> f.clean('longemailaddress@example.com') - Traceback (most recent call last): - ... - ValidationError: [u'Ensure this value has at most 20 characters (it has 28).'] + >>> f = ComboField(fields=[CharField(max_length=20), EmailField()]) + >>> f.clean('test@example.com') + u'test@example.com' + >>> f.clean('longemailaddress@example.com') + Traceback (most recent call last): + ... + ValidationError: [u'Ensure this value has at most 20 characters (it has 28).'] ``MultiValueField`` ~~~~~~~~~~~~~~~~~~~ @@ -866,15 +867,15 @@ Takes one extra required argument: :class:`SplitDateTimeField` is a subclass which combines a time field and a date field into a datetime object. -Takes one extra required argument: + Takes one extra required argument: -.. attribute:: MultiValueField.fields + .. attribute:: fields - A list of fields which are cleaned into a single field. Each value in - ``clean`` is cleaned by the corresponding field in ``fields`` -- the first - value is cleaned by the first field, the second value is cleaned by - the second field, etc. Once all fields are cleaned, the list of clean - values is "compressed" into a single value. + A list of fields which are cleaned into a single field. Each value in + ``clean`` is cleaned by the corresponding field in ``fields`` -- the first + value is cleaned by the first field, the second value is cleaned by + the second field, etc. Once all fields are cleaned, the list of clean + values is "compressed" into a single value. ``SplitDateTimeField`` ~~~~~~~~~~~~~~~~~~~~~~ @@ -889,23 +890,23 @@ Takes one extra required argument: * Error message keys: ``required``, ``invalid``, ``invalid_date``, ``invalid_time`` -Takes two optional arguments: + Takes two optional arguments: -.. attribute:: SplitDateTimeField.input_date_formats + .. attribute:: input_date_formats - A list of formats used to attempt to convert a string to a valid - ``datetime.date`` object. + A list of formats used to attempt to convert a string to a valid + ``datetime.date`` object. -If no ``input_date_formats`` argument is provided, the default input formats -for ``DateField`` are used. + If no ``input_date_formats`` argument is provided, the default input formats + for ``DateField`` are used. -.. attribute:: SplitDateTimeField.input_time_formats + .. attribute:: input_time_formats - A list of formats used to attempt to convert a string to a valid - ``datetime.time`` object. + A list of formats used to attempt to convert a string to a valid + ``datetime.time`` object. -If no ``input_time_formats`` argument is provided, the default input formats -for ``TimeField`` are used. + If no ``input_time_formats`` argument is provided, the default input formats + for ``TimeField`` are used. Fields which handle relationships --------------------------------- @@ -930,45 +931,45 @@ objects (in the case of ``ModelMultipleChoiceField``) into the * Validates that the given id exists in the queryset. * Error message keys: ``required``, ``invalid_choice`` -Allows the selection of a single model object, suitable for -representing a foreign key. A single argument is required: + Allows the selection of a single model object, suitable for + representing a foreign key. A single argument is required: -.. attribute:: ModelChoiceField.queryset + .. attribute:: queryset - A ``QuerySet`` of model objects from which the choices for the - field will be derived, and which will be used to validate the - user's selection. + A ``QuerySet`` of model objects from which the choices for the + field will be derived, and which will be used to validate the + user's selection. -``ModelChoiceField`` also takes one optional argument: + ``ModelChoiceField`` also takes one optional argument: -.. attribute:: ModelChoiceField.empty_label + .. attribute:: empty_label - By default the ``<select>`` widget used by ``ModelChoiceField`` will have an - empty choice at the top of the list. You can change the text of this - label (which is ``"---------"`` by default) with the ``empty_label`` - attribute, or you can disable the empty label entirely by setting - ``empty_label`` to ``None``:: + By default the ``<select>`` widget used by ``ModelChoiceField`` will have an + empty choice at the top of the list. You can change the text of this + label (which is ``"---------"`` by default) with the ``empty_label`` + attribute, or you can disable the empty label entirely by setting + ``empty_label`` to ``None``:: - # A custom empty label - field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)") + # A custom empty label + field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)") - # No empty label - field2 = forms.ModelChoiceField(queryset=..., empty_label=None) + # No empty label + field2 = forms.ModelChoiceField(queryset=..., empty_label=None) - Note that if a ``ModelChoiceField`` is required and has a default - initial value, no empty choice is created (regardless of the value - of ``empty_label``). + Note that if a ``ModelChoiceField`` is required and has a default + initial value, no empty choice is created (regardless of the value + of ``empty_label``). -The ``__unicode__`` method of the model will be called to generate -string representations of the objects for use in the field's choices; -to provide customized representations, subclass ``ModelChoiceField`` -and override ``label_from_instance``. This method will receive a model -object, and should return a string suitable for representing it. For -example:: + The ``__unicode__`` method of the model will be called to generate + string representations of the objects for use in the field's choices; + to provide customized representations, subclass ``ModelChoiceField`` + and override ``label_from_instance``. This method will receive a model + object, and should return a string suitable for representing it. For + example:: - class MyModelChoiceField(ModelChoiceField): - def label_from_instance(self, obj): - return "My Object #%i" % obj.id + class MyModelChoiceField(ModelChoiceField): + def label_from_instance(self, obj): + return "My Object #%i" % obj.id ``ModelMultipleChoiceField`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -983,16 +984,16 @@ example:: * Error message keys: ``required``, ``list``, ``invalid_choice``, ``invalid_pk_value`` -Allows the selection of one or more model objects, suitable for -representing a many-to-many relation. As with :class:`ModelChoiceField`, -you can use ``label_from_instance`` to customize the object -representations, and ``queryset`` is a required parameter: + Allows the selection of one or more model objects, suitable for + representing a many-to-many relation. As with :class:`ModelChoiceField`, + you can use ``label_from_instance`` to customize the object + representations, and ``queryset`` is a required parameter: -.. attribute:: ModelMultipleChoiceField.queryset + .. attribute:: queryset - A ``QuerySet`` of model objects from which the choices for the - field will be derived, and which will be used to validate the - user's selection. + A ``QuerySet`` of model objects from which the choices for the + field will be derived, and which will be used to validate the + user's selection. Creating custom fields ---------------------- diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt index 5264279e8e..7657353495 100644 --- a/docs/ref/forms/validation.txt +++ b/docs/ref/forms/validation.txt @@ -28,72 +28,72 @@ after the field's ``to_python`` and ``validate`` methods have been called. Validation of a Form is split into several steps, which can be customized or overridden: - * The ``to_python()`` method on a Field is the first step in every - validation. It coerces the value to correct datatype and raises - ``ValidationError`` if that is not possible. This method accepts the raw - value from the widget and returns the converted value. For example, a - FloatField will turn the data into a Python ``float`` or raise a - ``ValidationError``. +* The ``to_python()`` method on a Field is the first step in every + validation. It coerces the value to correct datatype and raises + ``ValidationError`` if that is not possible. This method accepts the raw + value from the widget and returns the converted value. For example, a + FloatField will turn the data into a Python ``float`` or raise a + ``ValidationError``. - * The ``validate()`` method on a Field handles field-specific validation - that is not suitable for a validator, It takes a value that has been - coerced to correct datatype and raises ``ValidationError`` on any error. - This method does not return anything and shouldn't alter the value. You - should override it to handle validation logic that you can't or don't - want to put in a validator. +* The ``validate()`` method on a Field handles field-specific validation + that is not suitable for a validator, It takes a value that has been + coerced to correct datatype and raises ``ValidationError`` on any error. + This method does not return anything and shouldn't alter the value. You + should override it to handle validation logic that you can't or don't + want to put in a validator. - * The ``run_validators()`` method on a Field runs all of the field's - validators and aggregates all the errors into a single - ``ValidationError``. You shouldn't need to override this method. +* The ``run_validators()`` method on a Field runs all of the field's + validators and aggregates all the errors into a single + ``ValidationError``. You shouldn't need to override this method. - * The ``clean()`` method on a Field subclass. This is responsible for - running ``to_python``, ``validate`` and ``run_validators`` in the correct - order and propagating their errors. If, at any time, any of the methods - raise ``ValidationError``, the validation stops and that error is raised. - This method returns the clean data, which is then inserted into the - ``cleaned_data`` dictionary of the form. +* The ``clean()`` method on a Field subclass. This is responsible for + running ``to_python``, ``validate`` and ``run_validators`` in the correct + order and propagating their errors. If, at any time, any of the methods + raise ``ValidationError``, the validation stops and that error is raised. + This method returns the clean data, which is then inserted into the + ``cleaned_data`` dictionary of the form. - * The ``clean_<fieldname>()`` method in a form subclass -- where - ``<fieldname>`` is replaced with the name of the form field attribute. - This method does any cleaning that is specific to that particular - attribute, unrelated to the type of field that it is. This method is not - passed any parameters. You will need to look up the value of the field - in ``self.cleaned_data`` and remember that it will be a Python object - at this point, not the original string submitted in the form (it will be - in ``cleaned_data`` because the general field ``clean()`` method, above, - has already cleaned the data once). +* The ``clean_<fieldname>()`` method in a form subclass -- where + ``<fieldname>`` is replaced with the name of the form field attribute. + This method does any cleaning that is specific to that particular + attribute, unrelated to the type of field that it is. This method is not + passed any parameters. You will need to look up the value of the field + in ``self.cleaned_data`` and remember that it will be a Python object + at this point, not the original string submitted in the form (it will be + in ``cleaned_data`` because the general field ``clean()`` method, above, + has already cleaned the data once). - For example, if you wanted to validate that the contents of a - ``CharField`` called ``serialnumber`` was unique, - ``clean_serialnumber()`` would be the right place to do this. You don't - need a specific field (it's just a ``CharField``), but you want a - formfield-specific piece of validation and, possibly, - cleaning/normalizing the data. + For example, if you wanted to validate that the contents of a + ``CharField`` called ``serialnumber`` was unique, + ``clean_serialnumber()`` would be the right place to do this. You don't + need a specific field (it's just a ``CharField``), but you want a + formfield-specific piece of validation and, possibly, + cleaning/normalizing the data. - Just like the general field ``clean()`` method, above, this method - should return the cleaned data, regardless of whether it changed - anything or not. + Just like the general field ``clean()`` method, above, this method + should return the cleaned data, regardless of whether it changed + anything or not. - * The Form subclass's ``clean()`` method. This method can perform - any validation that requires access to multiple fields from the form at - once. This is where you might put in things to check that if field ``A`` - is supplied, field ``B`` must contain a valid email address and the - like. The data that this method returns is the final ``cleaned_data`` - attribute for the form, so don't forget to return the full list of - cleaned data if you override this method (by default, ``Form.clean()`` - just returns ``self.cleaned_data``). +* The Form subclass's ``clean()`` method. This method can perform + any validation that requires access to multiple fields from the form at + once. This is where you might put in things to check that if field ``A`` + is supplied, field ``B`` must contain a valid email address and the + like. The data that this method returns is the final ``cleaned_data`` + attribute for the form, so don't forget to return the full list of + cleaned data if you override this method (by default, ``Form.clean()`` + just returns ``self.cleaned_data``). - Note that any errors raised by your ``Form.clean()`` override will not - be associated with any field in particular. They go into a special - "field" (called ``__all__``), which you can access via the - ``non_field_errors()`` method if you need to. If you want to attach - errors to a specific field in the form, you will need to access the - ``_errors`` attribute on the form, which is `described later`_. + Note that any errors raised by your ``Form.clean()`` override will not + be associated with any field in particular. They go into a special + "field" (called ``__all__``), which you can access via the + ``non_field_errors()`` method if you need to. If you want to attach + errors to a specific field in the form, you will need to access the + ``_errors`` attribute on the form, which is `described later`_. - Also note that there are special considerations when overriding - the ``clean()`` method of a ``ModelForm`` subclass. (see the - :ref:`ModelForm documentation - <overriding-modelform-clean-method>` for more information) + Also note that there are special considerations when overriding + the ``clean()`` method of a ``ModelForm`` subclass. (see the + :ref:`ModelForm documentation + <overriding-modelform-clean-method>` for more information) These methods are run in the order given above, one field at a time. That is, for each field in the form (in the order they are declared in the form diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index f0cde04c57..2b386c0864 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -21,16 +21,14 @@ which widget is used on which field, see the documentation about However, if you want to use a different widget for a field, you can just use the :attr:`~Field.widget` argument on the field definition. For -example: +example:: - .. code-block:: python + from django import forms - from django import forms - - class CommentForm(forms.Form): - name = forms.CharField() - url = forms.URLField() - comment = forms.CharField(widget=forms.Textarea) + class CommentForm(forms.Form): + name = forms.CharField() + url = forms.URLField() + comment = forms.CharField(widget=forms.Textarea) This would specify a form with a comment that uses a larger :class:`Textarea` widget, rather than the default :class:`TextInput` widget. @@ -42,25 +40,23 @@ 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`: - - .. code-block:: python +:class:`~django.forms.extras.widgets.SelectDateWidget`:: - from django.forms.fields import DateField, ChoiceField, MultipleChoiceField - from django.forms.widgets import RadioSelect, CheckboxSelectMultiple - from django.forms.extras.widgets import SelectDateWidget + from django.forms.fields import DateField, ChoiceField, MultipleChoiceField + from django.forms.widgets import RadioSelect, CheckboxSelectMultiple + from django.forms.extras.widgets import SelectDateWidget - BIRTH_YEAR_CHOICES = ('1980', '1981', '1982') - GENDER_CHOICES = (('m', 'Male'), ('f', 'Female')) - FAVORITE_COLORS_CHOICES = (('blue', 'Blue'), - ('green', 'Green'), - ('black', 'Black')) + BIRTH_YEAR_CHOICES = ('1980', '1981', '1982') + GENDER_CHOICES = (('m', 'Male'), ('f', 'Female')) + FAVORITE_COLORS_CHOICES = (('blue', 'Blue'), + ('green', 'Green'), + ('black', 'Black')) - class SimpleForm(forms.Form): - birth_year = DateField(widget=SelectDateWidget(years=BIRTH_YEAR_CHOICES)) - gender = ChoiceField(widget=RadioSelect, choices=GENDER_CHOICES) - favorite_colors = forms.MultipleChoiceField(required=False, - widget=CheckboxSelectMultiple, choices=FAVORITE_COLORS_CHOICES) + class SimpleForm(forms.Form): + birth_year = DateField(widget=SelectDateWidget(years=BIRTH_YEAR_CHOICES)) + gender = ChoiceField(widget=RadioSelect, choices=GENDER_CHOICES) + favorite_colors = forms.MultipleChoiceField(required=False, + widget=CheckboxSelectMultiple, choices=FAVORITE_COLORS_CHOICES) See the :ref:`built-in widgets` for more information about which widgets are available and which arguments they accept. @@ -78,21 +74,19 @@ buttons. :class:`Select` widgets are used by default on :class:`ChoiceField` fields. The choices displayed on the widget are inherited from the :class:`ChoiceField` and changing :attr:`ChoiceField.choices` will update :attr:`Select.choices`. For -example: - - .. code-block:: python +example:: - >>> from django import forms - >>> CHOICES = (('1', 'First',), ('2', 'Second',))) - >>> choice_field = forms.ChoiceField(widget=forms.RadioSelect, choices=CHOICES) - >>> choice_field.choices - [('1', 'First'), ('2', 'Second')] - >>> choice_field.widget.choices - [('1', 'First'), ('2', 'Second')] - >>> choice_field.widget.choices = () - >>> choice_field.choices = (('1', 'First and only',),) - >>> choice_field.widget.choices - [('1', 'First and only')] + >>> from django import forms + >>> CHOICES = (('1', 'First',), ('2', 'Second',))) + >>> choice_field = forms.ChoiceField(widget=forms.RadioSelect, choices=CHOICES) + >>> choice_field.choices + [('1', 'First'), ('2', 'Second')] + >>> choice_field.widget.choices + [('1', 'First'), ('2', 'Second')] + >>> choice_field.widget.choices = () + >>> choice_field.choices = (('1', 'First and only',),) + >>> choice_field.widget.choices + [('1', 'First and only')] Widgets which offer a :attr:`~Select.choices` attribute can however be used @@ -113,55 +107,46 @@ specify additional attributes for each widget. When you specify a widget, you can provide a list of attributes that will be added to the rendered HTML for the widget. -For example, take the following simple form: +For example, take the following simple form:: - .. code-block:: python + from django import forms - from django import forms - - class CommentForm(forms.Form): - name = forms.CharField() - url = forms.URLField() - comment = forms.CharField() + class CommentForm(forms.Form): + name = forms.CharField() + url = forms.URLField() + comment = forms.CharField() This form will include three default :class:`TextInput` widgets, with default rendering -- no CSS class, no extra attributes. This means that the input boxes -provided for each widget will be rendered exactly the same: - - .. code-block:: python - - >>> 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>Comment:</th><td><input type="text" name="comment" /></td></tr> +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>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 might want a larger input element for the comment, and you might want the 'name' widget to have some special CSS class. To do this, you use the :attr:`Widget.attrs` argument when creating the widget: -For example: - - .. code-block:: python +For example:: - class CommentForm(forms.Form): - name = forms.CharField( - widget=forms.TextInput(attrs={'class':'special'})) - url = forms.URLField() - comment = forms.CharField( - widget=forms.TextInput(attrs={'size':'40'})) + class CommentForm(forms.Form): + name = forms.CharField( + widget=forms.TextInput(attrs={'class':'special'})) + url = forms.URLField() + comment = forms.CharField( + widget=forms.TextInput(attrs={'size':'40'})) Django will then include the extra attributes in the rendered output: - .. code-block:: python - - >>> 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>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr> + >>> 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>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr> .. _built-in widgets: @@ -411,9 +396,7 @@ commonly used groups of widgets: :class:`MultiWidget`'s subclasses must implement. This method takes a single "compressed" value and returns a ``list``. An example of this is how :class:`SplitDateTimeWidget` turns a :class:`datetime` value into a list - with date and time split into two seperate values: - - .. code-block:: python + with date and time split into two seperate values:: class SplitDateTimeWidget(MultiWidget): diff --git a/docs/ref/generic-views.txt b/docs/ref/generic-views.txt index 325d808454..eb65107aaa 100644 --- a/docs/ref/generic-views.txt +++ b/docs/ref/generic-views.txt @@ -48,17 +48,17 @@ which is a dictionary of the parameters captured in the URL. **Required arguments:** - * ``template``: The full name of a template to use. +* ``template``: The full name of a template to use. **Optional arguments:** - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. +* ``extra_context``: A dictionary of values to add to the template + context. By default, this is an empty dictionary. If a value in the + dictionary is callable, the generic view will call it + just before rendering the template. - * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. +* ``mimetype``: The MIME type to use for the resulting document. Defaults + to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. **Example:** @@ -92,20 +92,20 @@ If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410). **Required arguments:** - * ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410 - (Gone) HTTP error. +* ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410 + (Gone) HTTP error. **Optional arguments:** - * ``permanent``: Whether the redirect should be permanent. The only - difference here is the HTTP status code returned. If ``True``, then the - redirect will use status code 301. If ``False``, then the redirect will - use status code 302. By default, ``permanent`` is ``True``. +* ``permanent``: Whether the redirect should be permanent. The only + difference here is the HTTP status code returned. If ``True``, then the + redirect will use status code 301. If ``False``, then the redirect will + use status code 302. By default, ``permanent`` is ``True``. - * ``query_string``: Whether to pass along the GET query string to - the new location. If ``True``, then the query string is appended - to the URL. If ``False``, then the query string is discarded. By - default, ``query_string`` is ``False``. +* ``query_string``: Whether to pass along the GET query string to + the new location. If ``True``, then the query string is appended + to the URL. If ``False``, then the query string is discarded. By + default, ``query_string`` is ``False``. .. versionadded:: 1.3 The ``query_string`` keyword argument is new in Django 1.3. @@ -167,75 +167,75 @@ a date in the *future* are not included unless you set ``allow_future`` to **Required arguments:** - * ``queryset``: A ``QuerySet`` of objects for which the archive serves. +* ``queryset``: A ``QuerySet`` of objects for which the archive serves. - * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in - the ``QuerySet``'s model that the date-based archive should use to - determine the objects on the page. +* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in + the ``QuerySet``'s model that the date-based archive should use to + determine the objects on the page. **Optional arguments:** - * ``num_latest``: The number of latest objects to send to the template - context. By default, it's 15. +* ``num_latest``: The number of latest objects to send to the template + context. By default, it's 15. - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). +* ``template_name``: The full name of a template to use in rendering the + page. This lets you override the default template name (see below). - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. +* ``template_loader``: The template loader to use when loading the + template. By default, it's ``django.template.loader``. - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. +* ``extra_context``: A dictionary of values to add to the template + context. By default, this is an empty dictionary. If a value in the + dictionary is callable, the generic view will call it + just before rendering the template. - * ``allow_empty``: A boolean specifying whether to display the page if no - objects are available. If this is ``False`` and no objects are available, - the view will raise a 404 instead of displaying an empty page. By - default, this is ``True``. +* ``allow_empty``: A boolean specifying whether to display the page if no + objects are available. If this is ``False`` and no objects are available, + the view will raise a 404 instead of displaying an empty page. By + default, this is ``True``. - * ``context_processors``: A list of template-context processors to apply to - the view's template. +* ``context_processors``: A list of template-context processors to apply to + the view's template. - * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. +* ``mimetype``: The MIME type to use for the resulting document. Defaults + to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. - * ``allow_future``: A boolean specifying whether to include "future" - objects on this page, where "future" means objects in which the field - specified in ``date_field`` is greater than the current date/time. By - default, this is ``False``. +* ``allow_future``: A boolean specifying whether to include "future" + objects on this page, where "future" means objects in which the field + specified in ``date_field`` is greater than the current date/time. By + default, this is ``False``. - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'latest'``. +* ``template_object_name``: Designates the name of the template variable + to use in the template context. By default, this is ``'latest'``. **Template name:** If ``template_name`` isn't specified, this view will use the template ``<app_label>/<model_name>_archive.html`` by default, where: - * ``<model_name>`` is your model's name in all lowercase. For a model - ``StaffMember``, that'd be ``staffmember``. +* ``<model_name>`` is your model's name in all lowercase. For a model + ``StaffMember``, that'd be ``staffmember``. - * ``<app_label>`` is the right-most part of the full Python path to - your model's app. For example, if your model lives in - ``apps/blog/models.py``, that'd be ``blog``. +* ``<app_label>`` is the right-most part of the full Python path to + your model's app. For example, if your model lives in + ``apps/blog/models.py``, that'd be ``blog``. **Template context:** In addition to ``extra_context``, the template's context will be: - * ``date_list``: A ``DateQuerySet`` object containing all years that have - have objects available according to ``queryset``, represented as - ``datetime.datetime`` objects. These are ordered in reverse. This is - equivalent to ``queryset.dates(date_field, 'year')[::-1]``. +* ``date_list``: A ``DateQuerySet`` object containing all years that have + have objects available according to ``queryset``, represented as + ``datetime.datetime`` objects. These are ordered in reverse. This is + equivalent to ``queryset.dates(date_field, 'year')[::-1]``. - * ``latest``: The ``num_latest`` objects in the system, ordered descending - by ``date_field``. For example, if ``num_latest`` is ``10``, then - ``latest`` will be a list of the latest 10 objects in ``queryset``. +* ``latest``: The ``num_latest`` objects in the system, ordered descending + by ``date_field``. For example, if ``num_latest`` is ``10``, then + ``latest`` will be a list of the latest 10 objects in ``queryset``. - This variable's name depends on the ``template_object_name`` parameter, - which is ``'latest'`` by default. If ``template_object_name`` is - ``'foo'``, this variable's name will be ``foo``. + This variable's name depends on the ``template_object_name`` parameter, + which is ``'latest'`` by default. If ``template_object_name`` is + ``'foo'``, this variable's name will be ``foo``. ``django.views.generic.date_based.archive_year`` ------------------------------------------------ @@ -248,54 +248,54 @@ to ``True``. **Required arguments:** - * ``year``: The four-digit year for which the archive serves. +* ``year``: The four-digit year for which the archive serves. - * ``queryset``: A ``QuerySet`` of objects for which the archive serves. +* ``queryset``: A ``QuerySet`` of objects for which the archive serves. - * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in - the ``QuerySet``'s model that the date-based archive should use to - determine the objects on the page. +* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in + the ``QuerySet``'s model that the date-based archive should use to + determine the objects on the page. **Optional arguments:** - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). +* ``template_name``: The full name of a template to use in rendering the + page. This lets you override the default template name (see below). - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. +* ``template_loader``: The template loader to use when loading the + template. By default, it's ``django.template.loader``. - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. +* ``extra_context``: A dictionary of values to add to the template + context. By default, this is an empty dictionary. If a value in the + dictionary is callable, the generic view will call it + just before rendering the template. - * ``allow_empty``: A boolean specifying whether to display the page if no - objects are available. If this is ``False`` and no objects are available, - the view will raise a 404 instead of displaying an empty page. By - default, this is ``False``. +* ``allow_empty``: A boolean specifying whether to display the page if no + objects are available. If this is ``False`` and no objects are available, + the view will raise a 404 instead of displaying an empty page. By + default, this is ``False``. - * ``context_processors``: A list of template-context processors to apply to - the view's template. +* ``context_processors``: A list of template-context processors to apply to + the view's template. - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. +* ``template_object_name``: Designates the name of the template variable + to use in the template context. By default, this is ``'object'``. The + view will append ``'_list'`` to the value of this parameter in + determining the variable's name. - * ``make_object_list``: A boolean specifying whether to retrieve the full - list of objects for this year and pass those to the template. If ``True``, - this list of objects will be made available to the template as - ``object_list``. (The name ``object_list`` may be different; see the docs - for ``object_list`` in the "Template context" section below.) By default, - this is ``False``. +* ``make_object_list``: A boolean specifying whether to retrieve the full + list of objects for this year and pass those to the template. If ``True``, + this list of objects will be made available to the template as + ``object_list``. (The name ``object_list`` may be different; see the docs + for ``object_list`` in the "Template context" section below.) By default, + this is ``False``. - * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. +* ``mimetype``: The MIME type to use for the resulting document. Defaults + to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. - * ``allow_future``: A boolean specifying whether to include "future" - objects on this page, where "future" means objects in which the field - specified in ``date_field`` is greater than the current date/time. By - default, this is ``False``. +* ``allow_future``: A boolean specifying whether to include "future" + objects on this page, where "future" means objects in which the field + specified in ``date_field`` is greater than the current date/time. By + default, this is ``False``. **Template name:** @@ -306,21 +306,21 @@ If ``template_name`` isn't specified, this view will use the template In addition to ``extra_context``, the template's context will be: - * ``date_list``: A ``DateQuerySet`` object containing all months that have - have objects available according to ``queryset``, represented as - ``datetime.datetime`` objects, in ascending order. +* ``date_list``: A ``DateQuerySet`` object containing all months that have + have objects available according to ``queryset``, represented as + ``datetime.datetime`` objects, in ascending order. - * ``year``: The given year, as a four-character string. +* ``year``: The given year, as a four-character string. - * ``object_list``: If the ``make_object_list`` parameter is ``True``, this - will be set to a list of objects available for the given year, ordered by - the date field. This variable's name depends on the - ``template_object_name`` parameter, which is ``'object'`` by default. If - ``template_object_name`` is ``'foo'``, this variable's name will be - ``foo_list``. +* ``object_list``: If the ``make_object_list`` parameter is ``True``, this + will be set to a list of objects available for the given year, ordered by + the date field. This variable's name depends on the + ``template_object_name`` parameter, which is ``'object'`` by default. If + ``template_object_name`` is ``'foo'``, this variable's name will be + ``foo_list``. - If ``make_object_list`` is ``False``, ``object_list`` will be passed to - the template as an empty list. + If ``make_object_list`` is ``False``, ``object_list`` will be passed to + the template as an empty list. ``django.views.generic.date_based.archive_month`` ------------------------------------------------- @@ -333,56 +333,56 @@ date in the *future* are not displayed unless you set ``allow_future`` to **Required arguments:** - * ``year``: The four-digit year for which the archive serves (a string). +* ``year``: The four-digit year for which the archive serves (a string). - * ``month``: The month for which the archive serves, formatted according to - the ``month_format`` argument. +* ``month``: The month for which the archive serves, formatted according to + the ``month_format`` argument. - * ``queryset``: A ``QuerySet`` of objects for which the archive serves. +* ``queryset``: A ``QuerySet`` of objects for which the archive serves. - * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in - the ``QuerySet``'s model that the date-based archive should use to - determine the objects on the page. +* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in + the ``QuerySet``'s model that the date-based archive should use to + determine the objects on the page. **Optional arguments:** - * ``month_format``: A format string that regulates what format the ``month`` - parameter uses. This should be in the syntax accepted by Python's - :func:`~time.strftime`. It's set to ``"%b"`` by default, which is a - three-letter month abbreviation. To change it to use numbers, use - ``"%m"``. +* ``month_format``: A format string that regulates what format the ``month`` + parameter uses. This should be in the syntax accepted by Python's + :func:`~time.strftime`. It's set to ``"%b"`` by default, which is a + three-letter month abbreviation. To change it to use numbers, use + ``"%m"``. - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). +* ``template_name``: The full name of a template to use in rendering the + page. This lets you override the default template name (see below). - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. +* ``template_loader``: The template loader to use when loading the + template. By default, it's ``django.template.loader``. - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. +* ``extra_context``: A dictionary of values to add to the template + context. By default, this is an empty dictionary. If a value in the + dictionary is callable, the generic view will call it + just before rendering the template. - * ``allow_empty``: A boolean specifying whether to display the page if no - objects are available. If this is ``False`` and no objects are available, - the view will raise a 404 instead of displaying an empty page. By - default, this is ``False``. +* ``allow_empty``: A boolean specifying whether to display the page if no + objects are available. If this is ``False`` and no objects are available, + the view will raise a 404 instead of displaying an empty page. By + default, this is ``False``. - * ``context_processors``: A list of template-context processors to apply to - the view's template. +* ``context_processors``: A list of template-context processors to apply to + the view's template. - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. +* ``template_object_name``: Designates the name of the template variable + to use in the template context. By default, this is ``'object'``. The + view will append ``'_list'`` to the value of this parameter in + determining the variable's name. - * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. +* ``mimetype``: The MIME type to use for the resulting document. Defaults + to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. - * ``allow_future``: A boolean specifying whether to include "future" - objects on this page, where "future" means objects in which the field - specified in ``date_field`` is greater than the current date/time. By - default, this is ``False``. +* ``allow_future``: A boolean specifying whether to include "future" + objects on this page, where "future" means objects in which the field + specified in ``date_field`` is greater than the current date/time. By + default, this is ``False``. **Template name:** @@ -396,24 +396,24 @@ If ``template_name`` isn't specified, this view will use the template In addition to ``extra_context``, the template's context will be: - * ``date_list``: A ``DateQuerySet`` object containing all days that have - have objects available in the given month, according to ``queryset``, - represented as ``datetime.datetime`` objects, in ascending order. +* ``date_list``: A ``DateQuerySet`` object containing all days that have + have objects available in the given month, according to ``queryset``, + represented as ``datetime.datetime`` objects, in ascending order. - * ``month``: A ``datetime.date`` object representing the given month. +* ``month``: A ``datetime.date`` object representing the given month. - * ``next_month``: A ``datetime.date`` object representing the first day of - the next month. If the next month is in the future, this will be - ``None``. +* ``next_month``: A ``datetime.date`` object representing the first day of + the next month. If the next month is in the future, this will be + ``None``. - * ``previous_month``: A ``datetime.date`` object representing the first day - of the previous month. Unlike ``next_month``, this will never be - ``None``. +* ``previous_month``: A ``datetime.date`` object representing the first day + of the previous month. Unlike ``next_month``, this will never be + ``None``. - * ``object_list``: A list of objects available for the given month. This - variable's name depends on the ``template_object_name`` parameter, which - is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, - this variable's name will be ``foo_list``. +* ``object_list``: A list of objects available for the given month. This + variable's name depends on the ``template_object_name`` parameter, which + is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, + this variable's name will be ``foo_list``. ``django.views.generic.date_based.archive_week`` ------------------------------------------------ @@ -425,50 +425,50 @@ in the *future* are not displayed unless you set ``allow_future`` to ``True``. **Required arguments:** - * ``year``: The four-digit year for which the archive serves (a string). +* ``year``: The four-digit year for which the archive serves (a string). - * ``week``: The week of the year for which the archive serves (a string). - Weeks start with Sunday. +* ``week``: The week of the year for which the archive serves (a string). + Weeks start with Sunday. - * ``queryset``: A ``QuerySet`` of objects for which the archive serves. +* ``queryset``: A ``QuerySet`` of objects for which the archive serves. - * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in - the ``QuerySet``'s model that the date-based archive should use to - determine the objects on the page. +* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in + the ``QuerySet``'s model that the date-based archive should use to + determine the objects on the page. **Optional arguments:** - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). +* ``template_name``: The full name of a template to use in rendering the + page. This lets you override the default template name (see below). - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. +* ``template_loader``: The template loader to use when loading the + template. By default, it's ``django.template.loader``. - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. +* ``extra_context``: A dictionary of values to add to the template + context. By default, this is an empty dictionary. If a value in the + dictionary is callable, the generic view will call it + just before rendering the template. - * ``allow_empty``: A boolean specifying whether to display the page if no - objects are available. If this is ``False`` and no objects are available, - the view will raise a 404 instead of displaying an empty page. By - default, this is ``True``. +* ``allow_empty``: A boolean specifying whether to display the page if no + objects are available. If this is ``False`` and no objects are available, + the view will raise a 404 instead of displaying an empty page. By + default, this is ``True``. - * ``context_processors``: A list of template-context processors to apply to - the view's template. +* ``context_processors``: A list of template-context processors to apply to + the view's template. - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. +* ``template_object_name``: Designates the name of the template variable + to use in the template context. By default, this is ``'object'``. The + view will append ``'_list'`` to the value of this parameter in + determining the variable's name. - * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. +* ``mimetype``: The MIME type to use for the resulting document. Defaults + to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. - * ``allow_future``: A boolean specifying whether to include "future" - objects on this page, where "future" means objects in which the field - specified in ``date_field`` is greater than the current date/time. By - default, this is ``False``. +* ``allow_future``: A boolean specifying whether to include "future" + objects on this page, where "future" means objects in which the field + specified in ``date_field`` is greater than the current date/time. By + default, this is ``False``. **Template name:** @@ -479,13 +479,13 @@ If ``template_name`` isn't specified, this view will use the template In addition to ``extra_context``, the template's context will be: - * ``week``: A ``datetime.date`` object representing the first day of the - given week. +* ``week``: A ``datetime.date`` object representing the first day of the + given week. - * ``object_list``: A list of objects available for the given week. This - variable's name depends on the ``template_object_name`` parameter, which - is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, - this variable's name will be ``foo_list``. +* ``object_list``: A list of objects available for the given week. This + variable's name depends on the ``template_object_name`` parameter, which + is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, + this variable's name will be ``foo_list``. ``django.views.generic.date_based.archive_day`` ----------------------------------------------- @@ -498,62 +498,62 @@ you set ``allow_future`` to ``True``. **Required arguments:** - * ``year``: The four-digit year for which the archive serves (a string). +* ``year``: The four-digit year for which the archive serves (a string). - * ``month``: The month for which the archive serves, formatted according to - the ``month_format`` argument. +* ``month``: The month for which the archive serves, formatted according to + the ``month_format`` argument. - * ``day``: The day for which the archive serves, formatted according to the - ``day_format`` argument. +* ``day``: The day for which the archive serves, formatted according to the + ``day_format`` argument. - * ``queryset``: A ``QuerySet`` of objects for which the archive serves. +* ``queryset``: A ``QuerySet`` of objects for which the archive serves. - * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in - the ``QuerySet``'s model that the date-based archive should use to - determine the objects on the page. +* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in + the ``QuerySet``'s model that the date-based archive should use to + determine the objects on the page. **Optional arguments:** - * ``month_format``: A format string that regulates what format the ``month`` - parameter uses. This should be in the syntax accepted by Python's - :func:`~time.strftime`. It's set to ``"%b"`` by default, which is a - three-letter month abbreviation. To change it to use numbers, use - ``"%m"``. +* ``month_format``: A format string that regulates what format the ``month`` + parameter uses. This should be in the syntax accepted by Python's + :func:`~time.strftime`. It's set to ``"%b"`` by default, which is a + three-letter month abbreviation. To change it to use numbers, use + ``"%m"``. - * ``day_format``: Like ``month_format``, but for the ``day`` parameter. - It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). +* ``day_format``: Like ``month_format``, but for the ``day`` parameter. + It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). +* ``template_name``: The full name of a template to use in rendering the + page. This lets you override the default template name (see below). - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. +* ``template_loader``: The template loader to use when loading the + template. By default, it's ``django.template.loader``. - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. +* ``extra_context``: A dictionary of values to add to the template + context. By default, this is an empty dictionary. If a value in the + dictionary is callable, the generic view will call it + just before rendering the template. - * ``allow_empty``: A boolean specifying whether to display the page if no - objects are available. If this is ``False`` and no objects are available, - the view will raise a 404 instead of displaying an empty page. By - default, this is ``False``. +* ``allow_empty``: A boolean specifying whether to display the page if no + objects are available. If this is ``False`` and no objects are available, + the view will raise a 404 instead of displaying an empty page. By + default, this is ``False``. - * ``context_processors``: A list of template-context processors to apply to - the view's template. +* ``context_processors``: A list of template-context processors to apply to + the view's template. - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. +* ``template_object_name``: Designates the name of the template variable + to use in the template context. By default, this is ``'object'``. The + view will append ``'_list'`` to the value of this parameter in + determining the variable's name. - * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. +* ``mimetype``: The MIME type to use for the resulting document. Defaults + to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. - * ``allow_future``: A boolean specifying whether to include "future" - objects on this page, where "future" means objects in which the field - specified in ``date_field`` is greater than the current date/time. By - default, this is ``False``. +* ``allow_future``: A boolean specifying whether to include "future" + objects on this page, where "future" means objects in which the field + specified in ``date_field`` is greater than the current date/time. By + default, this is ``False``. **Template name:** @@ -564,18 +564,18 @@ If ``template_name`` isn't specified, this view will use the template In addition to ``extra_context``, the template's context will be: - * ``day``: A ``datetime.date`` object representing the given day. +* ``day``: A ``datetime.date`` object representing the given day. - * ``next_day``: A ``datetime.date`` object representing the next day. If - the next day is in the future, this will be ``None``. +* ``next_day``: A ``datetime.date`` object representing the next day. If + the next day is in the future, this will be ``None``. - * ``previous_day``: A ``datetime.date`` object representing the previous day. - Unlike ``next_day``, this will never be ``None``. +* ``previous_day``: A ``datetime.date`` object representing the previous day. + Unlike ``next_day``, this will never be ``None``. - * ``object_list``: A list of objects available for the given day. This - variable's name depends on the ``template_object_name`` parameter, which - is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, - this variable's name will be ``foo_list``. +* ``object_list``: A list of objects available for the given day. This + variable's name depends on the ``template_object_name`` parameter, which + is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, + this variable's name will be ``foo_list``. ``django.views.generic.date_based.archive_today`` ------------------------------------------------- @@ -597,73 +597,73 @@ future, the view will throw a 404 error by default, unless you set **Required arguments:** - * ``year``: The object's four-digit year (a string). +* ``year``: The object's four-digit year (a string). - * ``month``: The object's month , formatted according to the - ``month_format`` argument. +* ``month``: The object's month , formatted according to the + ``month_format`` argument. - * ``day``: The object's day , formatted according to the ``day_format`` - argument. +* ``day``: The object's day , formatted according to the ``day_format`` + argument. - * ``queryset``: A ``QuerySet`` that contains the object. +* ``queryset``: A ``QuerySet`` that contains the object. - * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in - the ``QuerySet``'s model that the generic view should use to look up the - object according to ``year``, ``month`` and ``day``. +* ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in + the ``QuerySet``'s model that the generic view should use to look up the + object according to ``year``, ``month`` and ``day``. - * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. +* Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. - If you provide ``object_id``, it should be the value of the primary-key - field for the object being displayed on this page. + If you provide ``object_id``, it should be the value of the primary-key + field for the object being displayed on this page. - Otherwise, ``slug`` should be the slug of the given object, and - ``slug_field`` should be the name of the slug field in the ``QuerySet``'s - model. By default, ``slug_field`` is ``'slug'``. + Otherwise, ``slug`` should be the slug of the given object, and + ``slug_field`` should be the name of the slug field in the ``QuerySet``'s + model. By default, ``slug_field`` is ``'slug'``. **Optional arguments:** - * ``month_format``: A format string that regulates what format the ``month`` - parameter uses. This should be in the syntax accepted by Python's - :func:`~time.strftime`. It's set to ``"%b"`` by default, which is a - three-letter month abbreviation. To change it to use numbers, use - ``"%m"``. +* ``month_format``: A format string that regulates what format the ``month`` + parameter uses. This should be in the syntax accepted by Python's + :func:`~time.strftime`. It's set to ``"%b"`` by default, which is a + three-letter month abbreviation. To change it to use numbers, use + ``"%m"``. - * ``day_format``: Like ``month_format``, but for the ``day`` parameter. - It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). +* ``day_format``: Like ``month_format``, but for the ``day`` parameter. + It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). +* ``template_name``: The full name of a template to use in rendering the + page. This lets you override the default template name (see below). - * ``template_name_field``: The name of a field on the object whose value is - the template name to use. This lets you store template names in the data. - In other words, if your object has a field ``'the_template'`` that - contains a string ``'foo.html'``, and you set ``template_name_field`` to - ``'the_template'``, then the generic view for this object will use the - template ``'foo.html'``. +* ``template_name_field``: The name of a field on the object whose value is + the template name to use. This lets you store template names in the data. + In other words, if your object has a field ``'the_template'`` that + contains a string ``'foo.html'``, and you set ``template_name_field`` to + ``'the_template'``, then the generic view for this object will use the + template ``'foo.html'``. - It's a bit of a brain-bender, but it's useful in some cases. + It's a bit of a brain-bender, but it's useful in some cases. - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. +* ``template_loader``: The template loader to use when loading the + template. By default, it's ``django.template.loader``. - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. +* ``extra_context``: A dictionary of values to add to the template + context. By default, this is an empty dictionary. If a value in the + dictionary is callable, the generic view will call it + just before rendering the template. - * ``context_processors``: A list of template-context processors to apply to - the view's template. +* ``context_processors``: A list of template-context processors to apply to + the view's template. - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. +* ``template_object_name``: Designates the name of the template variable + to use in the template context. By default, this is ``'object'``. - * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. +* ``mimetype``: The MIME type to use for the resulting document. Defaults + to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. - * ``allow_future``: A boolean specifying whether to include "future" - objects on this page, where "future" means objects in which the field - specified in ``date_field`` is greater than the current date/time. By - default, this is ``False``. +* ``allow_future``: A boolean specifying whether to include "future" + objects on this page, where "future" means objects in which the field + specified in ``date_field`` is greater than the current date/time. By + default, this is ``False``. **Template name:** @@ -674,10 +674,10 @@ If ``template_name`` isn't specified, this view will use the template In addition to ``extra_context``, the template's context will be: - * ``object``: The object. This variable's name depends on the - ``template_object_name`` parameter, which is ``'object'`` by default. If - ``template_object_name`` is ``'foo'``, this variable's name will be - ``foo``. +* ``object``: The object. This variable's name depends on the + ``template_object_name`` parameter, which is ``'object'`` by default. If + ``template_object_name`` is ``'foo'``, this variable's name will be + ``foo``. .. module:: django.views.generic.list_detail @@ -698,45 +698,45 @@ A page representing a list of objects. **Required arguments:** - * ``queryset``: A ``QuerySet`` that represents the objects. +* ``queryset``: A ``QuerySet`` that represents the objects. **Optional arguments:** - * ``paginate_by``: An integer specifying how many objects should be - displayed per page. If this is given, the view will paginate objects with - ``paginate_by`` objects per page. The view will expect either a ``page`` - query string parameter (via ``GET``) or a ``page`` variable specified in - the URLconf. See `Notes on pagination`_ below. +* ``paginate_by``: An integer specifying how many objects should be + displayed per page. If this is given, the view will paginate objects with + ``paginate_by`` objects per page. The view will expect either a ``page`` + query string parameter (via ``GET``) or a ``page`` variable specified in + the URLconf. See `Notes on pagination`_ below. - * ``page``: The current page number, as an integer, or the string - ``'last'``. This is 1-based. See `Notes on pagination`_ below. +* ``page``: The current page number, as an integer, or the string + ``'last'``. This is 1-based. See `Notes on pagination`_ below. - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). +* ``template_name``: The full name of a template to use in rendering the + page. This lets you override the default template name (see below). - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. +* ``template_loader``: The template loader to use when loading the + template. By default, it's ``django.template.loader``. - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. +* ``extra_context``: A dictionary of values to add to the template + context. By default, this is an empty dictionary. If a value in the + dictionary is callable, the generic view will call it + just before rendering the template. - * ``allow_empty``: A boolean specifying whether to display the page if no - objects are available. If this is ``False`` and no objects are available, - the view will raise a 404 instead of displaying an empty page. By - default, this is ``True``. +* ``allow_empty``: A boolean specifying whether to display the page if no + objects are available. If this is ``False`` and no objects are available, + the view will raise a 404 instead of displaying an empty page. By + default, this is ``True``. - * ``context_processors``: A list of template-context processors to apply to - the view's template. +* ``context_processors``: A list of template-context processors to apply to + the view's template. - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. +* ``template_object_name``: Designates the name of the template variable + to use in the template context. By default, this is ``'object'``. The + view will append ``'_list'`` to the value of this parameter in + determining the variable's name. - * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. +* ``mimetype``: The MIME type to use for the resulting document. Defaults + to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. **Template name:** @@ -747,20 +747,20 @@ If ``template_name`` isn't specified, this view will use the template In addition to ``extra_context``, the template's context will be: - * ``object_list``: The list of objects. This variable's name depends on the - ``template_object_name`` parameter, which is ``'object'`` by default. If - ``template_object_name`` is ``'foo'``, this variable's name will be - ``foo_list``. +* ``object_list``: The list of objects. This variable's name depends on the + ``template_object_name`` parameter, which is ``'object'`` by default. If + ``template_object_name`` is ``'foo'``, this variable's name will be + ``foo_list``. - * ``is_paginated``: A boolean representing whether the results are - paginated. Specifically, this is set to ``False`` if the number of - available objects is less than or equal to ``paginate_by``. +* ``is_paginated``: A boolean representing whether the results are + paginated. Specifically, this is set to ``False`` if the number of + available objects is less than or equal to ``paginate_by``. If the results are paginated, the context will contain these extra variables: - * ``paginator``: An instance of ``django.core.paginator.Paginator``. +* ``paginator``: An instance of ``django.core.paginator.Paginator``. - * ``page_obj``: An instance of ``django.core.paginator.Page``. +* ``page_obj``: An instance of ``django.core.paginator.Page``. Notes on pagination ~~~~~~~~~~~~~~~~~~~ @@ -768,19 +768,19 @@ Notes on pagination If ``paginate_by`` is specified, Django will paginate the results. You can specify the page number in the URL in one of two ways: - * Use the ``page`` parameter in the URLconf. For example, this is what - your URLconf might look like:: +* Use the ``page`` parameter in the URLconf. For example, this is what + your URLconf might look like:: - (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict)) + (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict)) - * Pass the page number via the ``page`` query-string parameter. For - example, a URL would look like this:: +* Pass the page number via the ``page`` query-string parameter. For + example, a URL would look like this:: - /objects/?page=3 + /objects/?page=3 - * To loop over all the available page numbers, use the ``page_range`` - variable. You can iterate over the list provided by ``page_range`` - to create a link to every page of results. +* To loop over all the available page numbers, use the ``page_range`` + variable. You can iterate over the list provided by ``page_range`` + to create a link to every page of results. These values and lists are 1-based, not 0-based, so the first page would be represented as page ``1``. @@ -810,47 +810,47 @@ A page representing an individual object. **Required arguments:** - * ``queryset``: A ``QuerySet`` that contains the object. +* ``queryset``: A ``QuerySet`` that contains the object. - * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. +* Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. - If you provide ``object_id``, it should be the value of the primary-key - field for the object being displayed on this page. + If you provide ``object_id``, it should be the value of the primary-key + field for the object being displayed on this page. - Otherwise, ``slug`` should be the slug of the given object, and - ``slug_field`` should be the name of the slug field in the ``QuerySet``'s - model. By default, ``slug_field`` is ``'slug'``. + Otherwise, ``slug`` should be the slug of the given object, and + ``slug_field`` should be the name of the slug field in the ``QuerySet``'s + model. By default, ``slug_field`` is ``'slug'``. **Optional arguments:** - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). +* ``template_name``: The full name of a template to use in rendering the + page. This lets you override the default template name (see below). - * ``template_name_field``: The name of a field on the object whose value is - the template name to use. This lets you store template names in the data. - In other words, if your object has a field ``'the_template'`` that - contains a string ``'foo.html'``, and you set ``template_name_field`` to - ``'the_template'``, then the generic view for this object will use the - template ``'foo.html'``. +* ``template_name_field``: The name of a field on the object whose value is + the template name to use. This lets you store template names in the data. + In other words, if your object has a field ``'the_template'`` that + contains a string ``'foo.html'``, and you set ``template_name_field`` to + ``'the_template'``, then the generic view for this object will use the + template ``'foo.html'``. - It's a bit of a brain-bender, but it's useful in some cases. + It's a bit of a brain-bender, but it's useful in some cases. - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. +* ``template_loader``: The template loader to use when loading the + template. By default, it's ``django.template.loader``. - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. +* ``extra_context``: A dictionary of values to add to the template + context. By default, this is an empty dictionary. If a value in the + dictionary is callable, the generic view will call it + just before rendering the template. - * ``context_processors``: A list of template-context processors to apply to - the view's template. +* ``context_processors``: A list of template-context processors to apply to + the view's template. - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. +* ``template_object_name``: Designates the name of the template variable + to use in the template context. By default, this is ``'object'``. - * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. +* ``mimetype``: The MIME type to use for the resulting document. Defaults + to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting. **Template name:** @@ -861,10 +861,10 @@ If ``template_name`` isn't specified, this view will use the template In addition to ``extra_context``, the template's context will be: - * ``object``: The object. This variable's name depends on the - ``template_object_name`` parameter, which is ``'object'`` by default. If - ``template_object_name`` is ``'foo'``, this variable's name will be - ``foo``. +* ``object``: The object. This variable's name depends on the + ``template_object_name`` parameter, which is ``'object'`` by default. If + ``template_object_name`` is ``'foo'``, this variable's name will be + ``foo``. .. module:: django.views.generic.create_update @@ -884,46 +884,46 @@ validation errors (if there are any) and saving the object. **Required arguments:** - * Either ``form_class`` or ``model`` is required. +* Either ``form_class`` or ``model`` is required. - If you provide ``form_class``, it should be a ``django.forms.ModelForm`` - subclass. Use this argument when you need to customize the model's form. - See the :doc:`ModelForm docs </topics/forms/modelforms>` for more - information. + If you provide ``form_class``, it should be a ``django.forms.ModelForm`` + subclass. Use this argument when you need to customize the model's form. + See the :doc:`ModelForm docs </topics/forms/modelforms>` for more + information. - Otherwise, ``model`` should be a Django model class and the form used - will be a standard ``ModelForm`` for ``model``. + Otherwise, ``model`` should be a Django model class and the form used + will be a standard ``ModelForm`` for ``model``. **Optional arguments:** - * ``post_save_redirect``: A URL to which the view will redirect after - saving the object. By default, it's ``object.get_absolute_url()``. +* ``post_save_redirect``: A URL to which the view will redirect after + saving the object. By default, it's ``object.get_absolute_url()``. - ``post_save_redirect`` may contain dictionary string formatting, which - will be interpolated against the object's field attributes. For example, - you could use ``post_save_redirect="/polls/%(slug)s/"``. + ``post_save_redirect`` may contain dictionary string formatting, which + will be interpolated against the object's field attributes. For example, + you could use ``post_save_redirect="/polls/%(slug)s/"``. - * ``login_required``: A boolean that designates whether a user must be - logged in, in order to see the page and save changes. This hooks into the - Django :doc:`authentication system </topics/auth>`. By default, this is - ``False``. +* ``login_required``: A boolean that designates whether a user must be + logged in, in order to see the page and save changes. This hooks into the + Django :doc:`authentication system </topics/auth>`. By default, this is + ``False``. - If this is ``True``, and a non-logged-in user attempts to visit this page - or save the form, Django will redirect the request to ``/accounts/login/``. + If this is ``True``, and a non-logged-in user attempts to visit this page + or save the form, Django will redirect the request to ``/accounts/login/``. - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). +* ``template_name``: The full name of a template to use in rendering the + page. This lets you override the default template name (see below). - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. +* ``template_loader``: The template loader to use when loading the + template. By default, it's ``django.template.loader``. - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. +* ``extra_context``: A dictionary of values to add to the template + context. By default, this is an empty dictionary. If a value in the + dictionary is callable, the generic view will call it + just before rendering the template. - * ``context_processors``: A list of template-context processors to apply to - the view's template. +* ``context_processors``: A list of template-context processors to apply to + the view's template. **Template name:** @@ -934,19 +934,19 @@ If ``template_name`` isn't specified, this view will use the template In addition to ``extra_context``, the template's context will be: - * ``form``: A ``django.forms.ModelForm`` instance representing the form - for creating the object. This lets you refer to form fields easily in the - template system. +* ``form``: A ``django.forms.ModelForm`` instance representing the form + for creating the object. This lets you refer to form fields easily in the + template system. - For example, if the model has two fields, ``name`` and ``address``:: + For example, if the model has two fields, ``name`` and ``address``:: - <form action="" method="post"> - <p>{{ form.name.label_tag }} {{ form.name }}</p> - <p>{{ form.address.label_tag }} {{ form.address }}</p> - </form> + <form action="" method="post"> + <p>{{ form.name.label_tag }} {{ form.name }}</p> + <p>{{ form.address.label_tag }} {{ form.address }}</p> + </form> - See the :doc:`forms documentation </topics/forms/index>` for more - information about using ``Form`` objects in templates. + See the :doc:`forms documentation </topics/forms/index>` for more + information about using ``Form`` objects in templates. ``django.views.generic.create_update.update_object`` ---------------------------------------------------- @@ -960,59 +960,59 @@ model class. **Required arguments:** - * Either ``form_class`` or ``model`` is required. +* Either ``form_class`` or ``model`` is required. - If you provide ``form_class``, it should be a ``django.forms.ModelForm`` - subclass. Use this argument when you need to customize the model's form. - See the :doc:`ModelForm docs </topics/forms/modelforms>` for more - information. + If you provide ``form_class``, it should be a ``django.forms.ModelForm`` + subclass. Use this argument when you need to customize the model's form. + See the :doc:`ModelForm docs </topics/forms/modelforms>` for more + information. - Otherwise, ``model`` should be a Django model class and the form used - will be a standard ``ModelForm`` for ``model``. + Otherwise, ``model`` should be a Django model class and the form used + will be a standard ``ModelForm`` for ``model``. - * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. +* Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. - If you provide ``object_id``, it should be the value of the primary-key - field for the object being displayed on this page. + If you provide ``object_id``, it should be the value of the primary-key + field for the object being displayed on this page. - Otherwise, ``slug`` should be the slug of the given object, and - ``slug_field`` should be the name of the slug field in the ``QuerySet``'s - model. By default, ``slug_field`` is ``'slug'``. + Otherwise, ``slug`` should be the slug of the given object, and + ``slug_field`` should be the name of the slug field in the ``QuerySet``'s + model. By default, ``slug_field`` is ``'slug'``. **Optional arguments:** - * ``post_save_redirect``: A URL to which the view will redirect after - saving the object. By default, it's ``object.get_absolute_url()``. +* ``post_save_redirect``: A URL to which the view will redirect after + saving the object. By default, it's ``object.get_absolute_url()``. - ``post_save_redirect`` may contain dictionary string formatting, which - will be interpolated against the object's field attributes. For example, - you could use ``post_save_redirect="/polls/%(slug)s/"``. + ``post_save_redirect`` may contain dictionary string formatting, which + will be interpolated against the object's field attributes. For example, + you could use ``post_save_redirect="/polls/%(slug)s/"``. - * ``login_required``: A boolean that designates whether a user must be - logged in, in order to see the page and save changes. This hooks into the - Django :doc:`authentication system </topics/auth>`. By default, this is - ``False``. +* ``login_required``: A boolean that designates whether a user must be + logged in, in order to see the page and save changes. This hooks into the + Django :doc:`authentication system </topics/auth>`. By default, this is + ``False``. - If this is ``True``, and a non-logged-in user attempts to visit this page - or save the form, Django will redirect to :setting:`LOGIN_URL` (which - defaults to ``/accounts/login/``). + If this is ``True``, and a non-logged-in user attempts to visit this page + or save the form, Django will redirect to :setting:`LOGIN_URL` (which + defaults to ``/accounts/login/``). - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). +* ``template_name``: The full name of a template to use in rendering the + page. This lets you override the default template name (see below). - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. +* ``template_loader``: The template loader to use when loading the + template. By default, it's ``django.template.loader``. - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. +* ``extra_context``: A dictionary of values to add to the template + context. By default, this is an empty dictionary. If a value in the + dictionary is callable, the generic view will call it + just before rendering the template. - * ``context_processors``: A list of template-context processors to apply to - the view's template. +* ``context_processors``: A list of template-context processors to apply to + the view's template. - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. +* ``template_object_name``: Designates the name of the template variable + to use in the template context. By default, this is ``'object'``. **Template name:** @@ -1023,24 +1023,24 @@ If ``template_name`` isn't specified, this view will use the template In addition to ``extra_context``, the template's context will be: - * ``form``: A ``django.forms.ModelForm`` instance representing the form - for editing the object. This lets you refer to form fields easily in the - template system. +* ``form``: A ``django.forms.ModelForm`` instance representing the form + for editing the object. This lets you refer to form fields easily in the + template system. - For example, if the model has two fields, ``name`` and ``address``:: + For example, if the model has two fields, ``name`` and ``address``:: - <form action="" method="post"> - <p>{{ form.name.label_tag }} {{ form.name }}</p> - <p>{{ form.address.label_tag }} {{ form.address }}</p> - </form> + <form action="" method="post"> + <p>{{ form.name.label_tag }} {{ form.name }}</p> + <p>{{ form.address.label_tag }} {{ form.address }}</p> + </form> - See the :doc:`forms documentation </topics/forms/index>` for more - information about using ``Form`` objects in templates. + See the :doc:`forms documentation </topics/forms/index>` for more + information about using ``Form`` objects in templates. - * ``object``: The original object being edited. This variable's name - depends on the ``template_object_name`` parameter, which is ``'object'`` - by default. If ``template_object_name`` is ``'foo'``, this variable's - name will be ``foo``. +* ``object``: The original object being edited. This variable's name + depends on the ``template_object_name`` parameter, which is ``'object'`` + by default. If ``template_object_name`` is ``'foo'``, this variable's + name will be ``foo``. ``django.views.generic.create_update.delete_object`` ---------------------------------------------------- @@ -1054,48 +1054,48 @@ contain a form that POSTs to the same URL. **Required arguments:** - * ``model``: The Django model class of the object that the form will - delete. +* ``model``: The Django model class of the object that the form will + delete. - * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. +* Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. - If you provide ``object_id``, it should be the value of the primary-key - field for the object being displayed on this page. + If you provide ``object_id``, it should be the value of the primary-key + field for the object being displayed on this page. - Otherwise, ``slug`` should be the slug of the given object, and - ``slug_field`` should be the name of the slug field in the ``QuerySet``'s - model. By default, ``slug_field`` is ``'slug'``. + Otherwise, ``slug`` should be the slug of the given object, and + ``slug_field`` should be the name of the slug field in the ``QuerySet``'s + model. By default, ``slug_field`` is ``'slug'``. - * ``post_delete_redirect``: A URL to which the view will redirect after - deleting the object. +* ``post_delete_redirect``: A URL to which the view will redirect after + deleting the object. **Optional arguments:** - * ``login_required``: A boolean that designates whether a user must be - logged in, in order to see the page and save changes. This hooks into the - Django :doc:`authentication system </topics/auth>`. By default, this is - ``False``. +* ``login_required``: A boolean that designates whether a user must be + logged in, in order to see the page and save changes. This hooks into the + Django :doc:`authentication system </topics/auth>`. By default, this is + ``False``. - If this is ``True``, and a non-logged-in user attempts to visit this page - or save the form, Django will redirect to :setting:`LOGIN_URL` (which - defaults to ``/accounts/login/``). + If this is ``True``, and a non-logged-in user attempts to visit this page + or save the form, Django will redirect to :setting:`LOGIN_URL` (which + defaults to ``/accounts/login/``). - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). +* ``template_name``: The full name of a template to use in rendering the + page. This lets you override the default template name (see below). - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. +* ``template_loader``: The template loader to use when loading the + template. By default, it's ``django.template.loader``. - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. +* ``extra_context``: A dictionary of values to add to the template + context. By default, this is an empty dictionary. If a value in the + dictionary is callable, the generic view will call it + just before rendering the template. - * ``context_processors``: A list of template-context processors to apply to - the view's template. +* ``context_processors``: A list of template-context processors to apply to + the view's template. - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. +* ``template_object_name``: Designates the name of the template variable + to use in the template context. By default, this is ``'object'``. **Template name:** @@ -1106,7 +1106,7 @@ If ``template_name`` isn't specified, this view will use the template In addition to ``extra_context``, the template's context will be: - * ``object``: The original object that's about to be deleted. This - variable's name depends on the ``template_object_name`` parameter, which - is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, - this variable's name will be ``foo``. +* ``object``: The original object that's about to be deleted. This + variable's name depends on the ``template_object_name`` parameter, which + is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, + this variable's name will be ``foo``. diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index 07873219ff..59d05cc053 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -36,38 +36,38 @@ defines. See the :doc:`cache documentation </topics/cache>`. Adds a few conveniences for perfectionists: - * Forbids access to user agents in the :setting:`DISALLOWED_USER_AGENTS` - setting, which should be a list of strings. +* Forbids access to user agents in the :setting:`DISALLOWED_USER_AGENTS` + setting, which should be a list of strings. - * Performs URL rewriting based on the :setting:`APPEND_SLASH` and - :setting:`PREPEND_WWW` settings. +* Performs URL rewriting based on the :setting:`APPEND_SLASH` and + :setting:`PREPEND_WWW` settings. - If :setting:`APPEND_SLASH` is ``True`` and the initial URL doesn't end - with a slash, and it is not found in the URLconf, then a new URL is - formed by appending a slash at the end. If this new URL is found in the - URLconf, then Django redirects the request to this new URL. Otherwise, - the initial URL is processed as usual. + If :setting:`APPEND_SLASH` is ``True`` and the initial URL doesn't end + with a slash, and it is not found in the URLconf, then a new URL is + formed by appending a slash at the end. If this new URL is found in the + URLconf, then Django redirects the request to this new URL. Otherwise, + the initial URL is processed as usual. - For example, ``foo.com/bar`` will be redirected to ``foo.com/bar/`` if - you don't have a valid URL pattern for ``foo.com/bar`` but *do* have a - valid pattern for ``foo.com/bar/``. + For example, ``foo.com/bar`` will be redirected to ``foo.com/bar/`` if + you don't have a valid URL pattern for ``foo.com/bar`` but *do* have a + valid pattern for ``foo.com/bar/``. - If :setting:`PREPEND_WWW` is ``True``, URLs that lack a leading "www." - will be redirected to the same URL with a leading "www." + If :setting:`PREPEND_WWW` is ``True``, URLs that lack a leading "www." + will be redirected to the same URL with a leading "www." - Both of these options are meant to normalize URLs. The philosophy is that - each URL should exist in one, and only one, place. Technically a URL - ``foo.com/bar`` is distinct from ``foo.com/bar/`` -- a search-engine - indexer would treat them as separate URLs -- so it's best practice to - normalize URLs. + Both of these options are meant to normalize URLs. The philosophy is that + each URL should exist in one, and only one, place. Technically a URL + ``foo.com/bar`` is distinct from ``foo.com/bar/`` -- a search-engine + 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``. +* 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. +* 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. View metadata middleware ------------------------ diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 6c9dbf5a87..3ae35f0dc2 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -510,23 +510,23 @@ Has one **required** argument: to be passed along to the storage system. The two arguments that will be passed are: - ====================== =============================================== - Argument Description - ====================== =============================================== - ``instance`` An instance of the model where the - ``FileField`` is defined. More specifically, - this is the particular instance where the - current file is being attached. + ====================== =============================================== + Argument Description + ====================== =============================================== + ``instance`` An instance of the model where the + ``FileField`` is defined. More specifically, + this is the particular instance where the + current file is being attached. - In most cases, this object will not have been - saved to the database yet, so if it uses the - default ``AutoField``, *it might not yet have a - value for its primary key field*. + In most cases, this object will not have been + saved to the database yet, so if it uses the + default ``AutoField``, *it might not yet have a + value for its primary key field*. - ``filename`` The filename that was originally given to the - file. This may or may not be taken into account - when determining the final destination path. - ====================== =============================================== + ``filename`` The filename that was originally given to the + file. This may or may not be taken into account + when determining the final destination path. + ====================== =============================================== Also has one optional argument: @@ -541,22 +541,22 @@ widget). Using a :class:`FileField` or an :class:`ImageField` (see below) in a model takes a few steps: - 1. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the - full path to a directory where you'd like Django to store uploaded files. - (For performance, these files are not stored in the database.) Define - :setting:`MEDIA_URL` as the base public URL of that directory. Make sure - that this directory is writable by the Web server's user account. +1. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the + full path to a directory where you'd like Django to store uploaded files. + (For performance, these files are not stored in the database.) Define + :setting:`MEDIA_URL` as the base public URL of that directory. Make sure + that this directory is writable by the Web server's user account. - 2. Add the :class:`FileField` or :class:`ImageField` to your model, making - sure to define the :attr:`~FileField.upload_to` option to tell Django - to which subdirectory of :setting:`MEDIA_ROOT` it should upload files. +2. Add the :class:`FileField` or :class:`ImageField` to your model, making + sure to define the :attr:`~FileField.upload_to` option to tell Django + to which subdirectory of :setting:`MEDIA_ROOT` it should upload files. - 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 - ``{{ object.mug_shot.url }}``. +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 + ``{{ object.mug_shot.url }}``. For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and :attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 4ab9dd3011..d84fb3e584 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -34,9 +34,9 @@ Validating objects There are three steps involved in validating a model: - 1. Validate the model fields - 2. Validate the model as a whole - 3. Validate the field uniqueness +1. Validate the model fields +2. Validate the model as a whole +3. Validate the field uniqueness All three steps are performed when you call a model's :meth:`~Model.full_clean()` method. @@ -211,43 +211,43 @@ What happens when you save? When you save an object, Django performs the following steps: - 1. **Emit a pre-save signal.** The :doc:`signal </ref/signals>` - :attr:`django.db.models.signals.pre_save` is sent, allowing any - functions listening for that signal to take some customized - action. +1. **Emit a pre-save signal.** The :doc:`signal </ref/signals>` + :attr:`django.db.models.signals.pre_save` is sent, allowing any + functions listening for that signal to take some customized + action. - 2. **Pre-process the data.** Each field on the object is asked to - perform any automated data modification that the field may need - to perform. +2. **Pre-process the data.** Each field on the object is asked to + perform any automated data modification that the field may need + to perform. - Most fields do *no* pre-processing — the field data is kept as-is. - Pre-processing is only used on fields that have special behavior. For - example, if your model has a :class:`~django.db.models.DateField` with - ``auto_now=True``, the pre-save phase will alter the data in the object - to ensure that the date field contains the current date stamp. (Our - documentation doesn't yet include a list of all the fields with this - "special behavior.") + Most fields do *no* pre-processing — the field data is kept as-is. + Pre-processing is only used on fields that have special behavior. For + example, if your model has a :class:`~django.db.models.DateField` with + ``auto_now=True``, the pre-save phase will alter the data in the object + to ensure that the date field contains the current date stamp. (Our + documentation doesn't yet include a list of all the fields with this + "special behavior.") - 3. **Prepare the data for the database.** Each field is asked to provide - its current value in a data type that can be written to the database. +3. **Prepare the data for the database.** Each field is asked to provide + its current value in a data type that can be written to the database. - Most fields require *no* data preparation. Simple data types, such as - integers and strings, are 'ready to write' as a Python object. However, - more complex data types often require some modification. + Most fields require *no* data preparation. Simple data types, such as + integers and strings, are 'ready to write' as a Python object. However, + more complex data types often require some modification. - For example, :class:`~django.db.models.DateField` fields use a Python - ``datetime`` object to store data. Databases don't store ``datetime`` - objects, so the field value must be converted into an ISO-compliant date - string for insertion into the database. + For example, :class:`~django.db.models.DateField` fields use a Python + ``datetime`` object to store data. Databases don't store ``datetime`` + objects, so the field value must be converted into an ISO-compliant date + string for insertion into the database. - 4. **Insert the data into the database.** The pre-processed, prepared - data is then composed into an SQL statement for insertion into the - database. +4. **Insert the data into the database.** The pre-processed, prepared + data is then composed into an SQL statement for insertion into the + database. - 5. **Emit a post-save signal.** The signal - :attr:`django.db.models.signals.post_save` is sent, allowing - any functions listening for that signal to take some customized - action. +5. **Emit a post-save signal.** The signal + :attr:`django.db.models.signals.post_save` is sent, allowing + any functions listening for that signal to take some customized + action. How Django knows to UPDATE vs. INSERT ------------------------------------- @@ -257,14 +257,14 @@ for creating and changing objects. Django abstracts the need to use ``INSERT`` or ``UPDATE`` SQL statements. Specifically, when you call ``save()``, Django 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``. +* 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``. 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 diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt index 89935cc5e0..14446b69b4 100644 --- a/docs/ref/models/options.txt +++ b/docs/ref/models/options.txt @@ -107,21 +107,21 @@ Django quotes column and table names behind the scenes. the *only* difference when ``managed=False``. All other aspects of model handling are exactly the same as normal. This includes - 1. Adding an automatic primary key field to the model if you don't - declare it. To avoid confusion for later code readers, it's - recommended to specify all the columns from the database table you - are modeling when using unmanaged models. + 1. Adding an automatic primary key field to the model if you don't + declare it. To avoid confusion for later code readers, it's + recommended to specify all the columns from the database table you + are modeling when using unmanaged models. - 2. If a model with ``managed=False`` contains a - :class:`~django.db.models.ManyToManyField` that points to another - unmanaged model, then the intermediate table for the many-to-many - join will also not be created. However, the intermediary table - between one managed and one unmanaged model *will* be created. + 2. If a model with ``managed=False`` contains a + :class:`~django.db.models.ManyToManyField` that points to another + unmanaged model, then the intermediate table for the many-to-many + join will also not be created. However, the intermediary table + between one managed and one unmanaged model *will* be created. - If you need to change this default behavior, create the intermediary - table as an explicit model (with ``managed`` set as needed) and use - the :attr:`ManyToManyField.through` attribute to make the relation - use your custom model. + If you need to change this default behavior, create the intermediary + table as an explicit model (with ``managed`` set as needed) and use + the :attr:`ManyToManyField.through` attribute to make the relation + use your custom model. For tests involving models with ``managed=False``, it's up to you to ensure the correct tables are created as part of the test setup. diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt index ee6bcdd046..37986ec08d 100644 --- a/docs/ref/models/relations.txt +++ b/docs/ref/models/relations.txt @@ -9,28 +9,28 @@ Related objects reference A "related manager" is a manager used in a one-to-many or many-to-many related context. This happens in two cases: - * The "other side" of a :class:`~django.db.models.ForeignKey` relation. - That is:: + * The "other side" of a :class:`~django.db.models.ForeignKey` relation. + That is:: - class Reporter(models.Model): - ... + class Reporter(models.Model): + ... - class Article(models.Model): - reporter = models.ForeignKey(Reporter) + class Article(models.Model): + reporter = models.ForeignKey(Reporter) - In the above example, the methods below will be available on - the manager ``reporter.article_set``. + In the above example, the methods below will be available on + the manager ``reporter.article_set``. - * Both sides of a :class:`~django.db.models.ManyToManyField` relation:: + * Both sides of a :class:`~django.db.models.ManyToManyField` relation:: - class Topping(models.Model): - ... + class Topping(models.Model): + ... - class Pizza(models.Model): - toppings = models.ManyToManyField(Topping) + class Pizza(models.Model): + toppings = models.ManyToManyField(Topping) - In this example, the methods below will be available both on - ``topping.pizza_set`` and on ``pizza.toppings``. + In this example, the methods below will be available both on + ``topping.pizza_set`` and on ``pizza.toppings``. These related managers have some extra methods: diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index fc19493132..f0ec7cf237 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -125,20 +125,20 @@ All attributes except ``session`` should be considered read-only. Available headers depend on the client and server, but here are some examples: - * ``CONTENT_LENGTH`` -- the length of the request body (as a string). - * ``CONTENT_TYPE`` -- the MIME type of the request body. - * ``HTTP_ACCEPT_ENCODING`` -- Acceptable encodings for the response. - * ``HTTP_ACCEPT_LANGUAGE`` -- Acceptable languages for the response. - * ``HTTP_HOST`` -- The HTTP Host header sent by the client. - * ``HTTP_REFERER`` -- The referring page, if any. - * ``HTTP_USER_AGENT`` -- The client's user-agent string. - * ``QUERY_STRING`` -- The query string, as a single (unparsed) string. - * ``REMOTE_ADDR`` -- The IP address of the client. - * ``REMOTE_HOST`` -- The hostname of the client. - * ``REMOTE_USER`` -- The user authenticated by the Web server, if any. - * ``REQUEST_METHOD`` -- A string such as ``"GET"`` or ``"POST"``. - * ``SERVER_NAME`` -- The hostname of the server. - * ``SERVER_PORT`` -- The port of the server (as a string). + * ``CONTENT_LENGTH`` -- the length of the request body (as a string). + * ``CONTENT_TYPE`` -- the MIME type of the request body. + * ``HTTP_ACCEPT_ENCODING`` -- Acceptable encodings for the response. + * ``HTTP_ACCEPT_LANGUAGE`` -- Acceptable languages for the response. + * ``HTTP_HOST`` -- The HTTP Host header sent by the client. + * ``HTTP_REFERER`` -- The referring page, if any. + * ``HTTP_USER_AGENT`` -- The client's user-agent string. + * ``QUERY_STRING`` -- The query string, as a single (unparsed) string. + * ``REMOTE_ADDR`` -- The IP address of the client. + * ``REMOTE_HOST`` -- The hostname of the client. + * ``REMOTE_USER`` -- The user authenticated by the Web server, if any. + * ``REQUEST_METHOD`` -- A string such as ``"GET"`` or ``"POST"``. + * ``SERVER_NAME`` -- The hostname of the server. + * ``SERVER_PORT`` -- The port of the server (as a string). With the exception of ``CONTENT_LENGTH`` and ``CONTENT_TYPE``, as given above, any HTTP headers in the request are converted to ``META`` keys by @@ -549,10 +549,10 @@ Passing iterators Finally, you can pass ``HttpResponse`` an iterator rather than passing it hard-coded strings. If you use this technique, follow these guidelines: - * The iterator should return strings. - * If an :class:`HttpResponse` has been initialized with an iterator as its - content, you can't use the :class:`HttpResponse` instance as a file-like - object. Doing so will raise ``Exception``. +* The iterator should return strings. +* If an :class:`HttpResponse` has been initialized with an iterator as its + content, you can't use the :class:`HttpResponse` instance as a file-like + object. Doing so will raise ``Exception``. Setting headers ~~~~~~~~~~~~~~~ @@ -649,27 +649,27 @@ Methods Sets a cookie. The parameters are the same as in the :class:`Cookie.Morsel` object in the Python standard library. - * ``max_age`` should be a number of seconds, or ``None`` (default) if - the cookie should last only as long as the client's browser session. - If ``expires`` is not specified, it will be calculated. - * ``expires`` should either be a string in the format - ``"Wdy, DD-Mon-YY HH:MM:SS GMT"`` or a ``datetime.datetime`` object - in UTC. If ``expires`` is a ``datetime`` object, the ``max_age`` - will be calculated. - * Use ``domain`` if you want to set a cross-domain cookie. For example, - ``domain=".lawrence.com"`` will set a cookie that is readable by - the domains www.lawrence.com, blogs.lawrence.com and - calendars.lawrence.com. Otherwise, a cookie will only be readable by - the domain that set it. - * Use ``httponly=True`` if you want to prevent client-side - JavaScript from having access to the cookie. + * ``max_age`` should be a number of seconds, or ``None`` (default) if + the cookie should last only as long as the client's browser session. + If ``expires`` is not specified, it will be calculated. + * ``expires`` should either be a string in the format + ``"Wdy, DD-Mon-YY HH:MM:SS GMT"`` or a ``datetime.datetime`` object + in UTC. If ``expires`` is a ``datetime`` object, the ``max_age`` + will be calculated. + * Use ``domain`` if you want to set a cross-domain cookie. For example, + ``domain=".lawrence.com"`` will set a cookie that is readable by + the domains www.lawrence.com, blogs.lawrence.com and + calendars.lawrence.com. Otherwise, a cookie will only be readable by + the domain that set it. + * Use ``httponly=True`` if you want to prevent client-side + JavaScript from having access to the 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_ 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: http://www.owasp.org/index.php/HTTPOnly diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 42a94c4513..0669750565 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -147,12 +147,12 @@ Default: ``''`` (Empty string) The cache backend to use. The built-in cache backends are: - * ``'django.core.cache.backends.db.DatabaseCache'`` - * ``'django.core.cache.backends.dummy.DummyCache'`` - * ``'django.core.cache.backends.filebased.FileBasedCache'`` - * ``'django.core.cache.backends.locmem.LocMemCache'`` - * ``'django.core.cache.backends.memcached.MemcachedCache'`` - * ``'django.core.cache.backends.memcached.PyLibMCCache'`` +* ``'django.core.cache.backends.db.DatabaseCache'`` +* ``'django.core.cache.backends.dummy.DummyCache'`` +* ``'django.core.cache.backends.filebased.FileBasedCache'`` +* ``'django.core.cache.backends.locmem.LocMemCache'`` +* ``'django.core.cache.backends.memcached.MemcachedCache'`` +* ``'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 @@ -412,10 +412,10 @@ Default: ``''`` (Empty string) The database backend to use. The built-in database backends are: - * ``'django.db.backends.postgresql_psycopg2'`` - * ``'django.db.backends.mysql'`` - * ``'django.db.backends.sqlite3'`` - * ``'django.db.backends.oracle'`` +* ``'django.db.backends.postgresql_psycopg2'`` +* ``'django.db.backends.mysql'`` +* ``'django.db.backends.sqlite3'`` +* ``'django.db.backends.oracle'`` You can use a database backend that doesn't ship with Django by setting ``ENGINE`` to a fully-qualified path (i.e. @@ -1165,9 +1165,9 @@ Default: ``()`` (Empty tuple) A tuple of IP addresses, as strings, that: - * See debug comments, when :setting:`DEBUG` is ``True`` - * Receive X headers if the ``XViewMiddleware`` is installed (see - :doc:`/topics/http/middleware`) +* See debug comments, when :setting:`DEBUG` is ``True`` +* Receive X headers if the ``XViewMiddleware`` is installed (see + :doc:`/topics/http/middleware`) .. setting:: LANGUAGE_CODE @@ -1389,11 +1389,11 @@ MESSAGE_TAGS Default:: - {messages.DEBUG: 'debug', - messages.INFO: 'info', - messages.SUCCESS: 'success', - messages.WARNING: 'warning', - messages.ERROR: 'error',} + {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. @@ -1649,10 +1649,10 @@ 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.db'`` +* ``'django.contrib.sessions.backends.file'`` +* ``'django.contrib.sessions.backends.cache'`` +* ``'django.contrib.sessions.backends.cached_db'`` See :doc:`/topics/http/sessions`. @@ -1989,12 +1989,12 @@ and models will automatically operate in the correct time zone. However, Django won't set the ``TZ`` environment variable under the following conditions: - * If you're using the manual configuration option as described in - :ref:`manually configuring settings - <settings-without-django-settings-module>`, or +* If you're using the manual configuration option as described in + :ref:`manually configuring settings + <settings-without-django-settings-module>`, or - * If you specify ``TIME_ZONE = None``. This will cause Django to fall - back to using the system timezone. +* If you specify ``TIME_ZONE = None``. This will cause Django to fall + back to using the system timezone. If Django doesn't set the ``TZ`` environment variable, it's up to you to ensure your processes are running in the correct environment. diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt index d6369c74c4..1f0612b6ba 100644 --- a/docs/ref/signals.txt +++ b/docs/ref/signals.txt @@ -62,24 +62,22 @@ Arguments sent with this signal: A dictionary of keyword arguments passed to :meth:`~django.db.models.Model.__init__`:. -For example, the :doc:`tutorial </intro/tutorial01>` has this line: - -.. code-block:: python +For example, the :doc:`tutorial </intro/tutorial01>` has this line:: p = Poll(question="What's up?", pub_date=datetime.now()) The arguments sent to a :data:`pre_init` handler would be: - ========== =============================================================== - Argument Value - ========== =============================================================== - ``sender`` ``Poll`` (the class itself) +========== =============================================================== +Argument Value +========== =============================================================== +``sender`` ``Poll`` (the class itself) - ``args`` ``[]`` (an empty list because there were no positional - arguments passed to ``__init__``.) +``args`` ``[]`` (an empty list because there were no positional + arguments passed to ``__init__``.) - ``kwargs`` ``{'question': "What's up?", 'pub_date': datetime.now()}`` - ========== =============================================================== +``kwargs`` ``{'question': "What's up?", 'pub_date': datetime.now()}`` +========== =============================================================== post_init --------- @@ -269,12 +267,11 @@ Arguments sent with this signal: The database alias being used. For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled -like this: - -.. code-block:: python +like this:: class Topping(models.Model): # ... + pass class Pizza(models.Model): # ... @@ -282,62 +279,58 @@ like this: If we would do something like this: -.. code-block:: python - >>> p = Pizza.object.create(...) >>> t = Topping.objects.create(...) >>> p.toppings.add(t) the arguments sent to a :data:`m2m_changed` handler would be: - ============== ============================================================ - Argument Value - ============== ============================================================ - ``sender`` ``Pizza.toppings.through`` (the intermediate m2m class) - - ``instance`` ``p`` (the ``Pizza`` instance being modified) +============== ============================================================ +Argument Value +============== ============================================================ +``sender`` ``Pizza.toppings.through`` (the intermediate m2m class) - ``action`` ``"pre_add"`` (followed by a separate signal with ``"post_add"``) +``instance`` ``p`` (the ``Pizza`` instance being modified) - ``reverse`` ``False`` (``Pizza`` contains the :class:`ManyToManyField`, - so this call modifies the forward relation) +``action`` ``"pre_add"`` (followed by a separate signal with ``"post_add"``) - ``model`` ``Topping`` (the class of the objects added to the - ``Pizza``) +``reverse`` ``False`` (``Pizza`` contains the :class:`ManyToManyField`, + so this call modifies the forward relation) - ``pk_set`` ``[t.id]`` (since only ``Topping t`` was added to the relation) +``model`` ``Topping`` (the class of the objects added to the + ``Pizza``) - ``using`` ``"default"`` (since the default router sends writes here) - ============== ============================================================ +``pk_set`` ``[t.id]`` (since only ``Topping t`` was added to the relation) -And if we would then do something like this: +``using`` ``"default"`` (since the default router sends writes here) +============== ============================================================ -.. code-block:: python +And if we would then do something like this:: >>> t.pizza_set.remove(p) the arguments sent to a :data:`m2m_changed` handler would be: - ============== ============================================================ - Argument Value - ============== ============================================================ - ``sender`` ``Pizza.toppings.through`` (the intermediate m2m class) +============== ============================================================ +Argument Value +============== ============================================================ +``sender`` ``Pizza.toppings.through`` (the intermediate m2m class) - ``instance`` ``t`` (the ``Topping`` instance being modified) +``instance`` ``t`` (the ``Topping`` instance being modified) - ``action`` ``"pre_remove"`` (followed by a separate signal with ``"post_remove"``) +``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:`ManyToManyField`, + so this call modifies the reverse relation) - ``model`` ``Pizza`` (the class of the objects removed from the - ``Topping``) +``model`` ``Pizza`` (the class of the objects removed from the + ``Topping``) - ``pk_set`` ``[p.id]`` (since only ``Pizza p`` was removed from the - relation) +``pk_set`` ``[p.id]`` (since only ``Pizza p`` was removed from the + relation) - ``using`` ``"default"`` (since the default router sends writes here) - ============== ============================================================ +``using`` ``"default"`` (since the default router sends writes here) +============== ============================================================ class_prepared -------------- diff --git a/docs/ref/template-response.txt b/docs/ref/template-response.txt index c53919f558..c21da5ef43 100644 --- a/docs/ref/template-response.txt +++ b/docs/ref/template-response.txt @@ -193,14 +193,14 @@ final byte stream that can be served to the client. There are three circumstances under which a TemplateResponse will be rendered: - * When the TemplateResponse instance is explicitly rendered, using - the :meth:`SimpleTemplateResponse.render()` method. +* 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`. +* When the content of the response is explicitly set by assigning + :attr:`response.content`. - * After passing through template response middleware, but before - passing through response middleware. +* 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 diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index 8aff949ecf..2b7d35479c 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -56,9 +56,9 @@ Using the template system Using the template system in Python is a two-step process: - * First, you compile the raw template code into a ``Template`` object. - * Then, you call the ``render()`` method of the ``Template`` object with a - given context. +* First, you compile the raw template code into a ``Template`` object. +* Then, you call the ``render()`` method of the ``Template`` object with a + given context. Compiling a string ------------------ @@ -91,11 +91,11 @@ multiple contexts -- with it. The ``Context`` class lives at :class:`django.template.Context`, and the constructor takes two (optional) arguments: - * A dictionary mapping variable names to variable values. +* A dictionary mapping variable names to variable values. - * The name of the current application. This application name is used - to help :ref:`resolve namespaced URLs<topics-http-reversing-url-namespaces>`. - If you're not using namespaced URLs, you can ignore this argument. +* The name of the current application. This application name is used + to help :ref:`resolve namespaced URLs<topics-http-reversing-url-namespaces>`. + If you're not using namespaced URLs, you can ignore this argument. Call the ``Template`` object's ``render()`` method with the context to "fill" the template:: @@ -118,9 +118,9 @@ Dots have a special meaning in template rendering. A dot in a variable name signifies a **lookup**. Specifically, when the template system encounters a dot in a variable name, it tries the following lookups, in this order: - * Dictionary lookup. Example: ``foo["bar"]`` - * Attribute lookup. Example: ``foo.bar`` - * List-index lookup. Example: ``foo[bar]`` +* Dictionary lookup. Example: ``foo["bar"]`` +* Attribute lookup. Example: ``foo.bar`` +* List-index lookup. Example: ``foo[bar]`` The template system uses the first lookup type that works. It's short-circuit logic. Here are a few examples:: @@ -161,69 +161,69 @@ it. Example:: Callable variables are slightly more complex than variables which only require straight lookups. Here are some things to keep in mind: - * If the variable raises an exception when called, the exception will be - propagated, unless the exception has an attribute - ``silent_variable_failure`` whose value is ``True``. If the exception - *does* have a ``silent_variable_failure`` attribute whose value is - ``True``, the variable will render as an empty string. Example:: +* If the variable raises an exception when called, the exception will be + propagated, unless the exception has an attribute + ``silent_variable_failure`` whose value is ``True``. If the exception + *does* have a ``silent_variable_failure`` attribute whose value is + ``True``, the variable will render as an empty string. Example:: - >>> t = Template("My name is {{ person.first_name }}.") - >>> class PersonClass3: - ... def first_name(self): - ... raise AssertionError("foo") - >>> p = PersonClass3() - >>> t.render(Context({"person": p})) - Traceback (most recent call last): - ... - AssertionError: foo + >>> t = Template("My name is {{ person.first_name }}.") + >>> class PersonClass3: + ... def first_name(self): + ... raise AssertionError("foo") + >>> p = PersonClass3() + >>> t.render(Context({"person": p})) + Traceback (most recent call last): + ... + AssertionError: foo - >>> class SilentAssertionError(Exception): - ... silent_variable_failure = True - >>> class PersonClass4: - ... def first_name(self): - ... raise SilentAssertionError - >>> p = PersonClass4() - >>> t.render(Context({"person": p})) - "My name is ." + >>> class SilentAssertionError(Exception): + ... silent_variable_failure = True + >>> class PersonClass4: + ... def first_name(self): + ... raise SilentAssertionError + >>> p = PersonClass4() + >>> t.render(Context({"person": p})) + "My name is ." - Note that :exc:`django.core.exceptions.ObjectDoesNotExist`, which is the - base class for all Django database API ``DoesNotExist`` exceptions, has - ``silent_variable_failure = True``. So if you're using Django templates - with Django model objects, any ``DoesNotExist`` exception will fail - silently. + Note that :exc:`django.core.exceptions.ObjectDoesNotExist`, which is the + base class for all Django database API ``DoesNotExist`` exceptions, has + ``silent_variable_failure = True``. So if you're using Django templates + with Django model objects, any ``DoesNotExist`` exception will fail + silently. - * A variable can only be called if it has no required arguments. Otherwise, - the system will return an empty string. +* A variable can only be called if it has no required arguments. Otherwise, + the system will return an empty string. - * Obviously, there can be side effects when calling some variables, and - it'd be either foolish or a security hole to allow the template system - to access them. +* Obviously, there can be side effects when calling some variables, and + it'd be either foolish or a security hole to allow the template system + to access them. - A good example is the :meth:`~django.db.models.Model.delete` method on - each Django model object. The template system shouldn't be allowed to do - something like this:: + A good example is the :meth:`~django.db.models.Model.delete` method on + each Django model object. The template system shouldn't be allowed to do + something like this:: - I will now delete this valuable data. {{ data.delete }} + I will now delete this valuable data. {{ data.delete }} - To prevent this, set an ``alters_data`` attribute on the callable - variable. The template system won't call a variable if it has - ``alters_data=True`` set, and will instead replace the variable with - :setting:`TEMPLATE_STRING_IF_INVALID`, unconditionally. The - dynamically-generated :meth:`~django.db.models.Model.delete` and - :meth:`~django.db.models.Model.save` methods on Django model objects get - ``alters_data=True`` automatically. Example:: + To prevent this, set an ``alters_data`` attribute on the callable + variable. The template system won't call a variable if it has + ``alters_data=True`` set, and will instead replace the variable with + :setting:`TEMPLATE_STRING_IF_INVALID`, unconditionally. The + dynamically-generated :meth:`~django.db.models.Model.delete` and + :meth:`~django.db.models.Model.save` methods on Django model objects get + ``alters_data=True`` automatically. Example:: - def sensitive_function(self): - self.database_record.delete() - sensitive_function.alters_data = True + def sensitive_function(self): + 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). +* .. 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). .. _invalid-template-variables: @@ -427,13 +427,13 @@ django.contrib.auth.context_processors.auth If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every ``RequestContext`` will contain these three variables: - * ``user`` -- An ``auth.User`` instance representing the currently - logged-in user (or an ``AnonymousUser`` instance, if the client isn't - logged in). +* ``user`` -- An ``auth.User`` instance representing the currently + logged-in user (or an ``AnonymousUser`` instance, if the client isn't + logged in). - * ``perms`` -- An instance of - ``django.contrib.auth.context_processors.PermWrapper``, representing the - permissions that the currently logged-in user has. +* ``perms`` -- An instance of + ``django.contrib.auth.context_processors.PermWrapper``, representing the + permissions that the currently logged-in user has. .. versionchanged:: 1.2 This context processor was moved in this release from @@ -452,11 +452,11 @@ If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every :setting:`DEBUG` setting is set to ``True`` and the request's IP address (``request.META['REMOTE_ADDR']``) is in the :setting:`INTERNAL_IPS` setting: - * ``debug`` -- ``True``. You can use this in templates to test whether - you're in :setting:`DEBUG` mode. - * ``sql_queries`` -- A list of ``{'sql': ..., 'time': ...}`` dictionaries, - representing every SQL query that has happened so far during the request - and how long it took. The list is in order by query. +* ``debug`` -- ``True``. You can use this in templates to test whether + you're in :setting:`DEBUG` mode. +* ``sql_queries`` -- A list of ``{'sql': ..., 'time': ...}`` dictionaries, + representing every SQL query that has happened so far during the request + and how long it took. The list is in order by query. django.core.context_processors.i18n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -464,9 +464,9 @@ django.core.context_processors.i18n If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every ``RequestContext`` will contain these two variables: - * ``LANGUAGES`` -- The value of the :setting:`LANGUAGES` setting. - * ``LANGUAGE_CODE`` -- ``request.LANGUAGE_CODE``, if it exists. Otherwise, - the value of the :setting:`LANGUAGE_CODE` setting. +* ``LANGUAGES`` -- The value of the :setting:`LANGUAGES` setting. +* ``LANGUAGE_CODE`` -- ``request.LANGUAGE_CODE``, if it exists. Otherwise, + the value of the :setting:`LANGUAGE_CODE` setting. See :doc:`/topics/i18n/index` for more. @@ -511,9 +511,9 @@ django.contrib.messages.context_processors.messages If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every ``RequestContext`` will contain a single additional variable: - * ``messages`` -- A list of messages (as strings) that have been set - via the user model (using ``user.message_set.create``) or through - the :doc:`messages framework </ref/contrib/messages>`. +* ``messages`` -- A list of messages (as strings) that have been set + via the user model (using ``user.message_set.create``) or through + the :doc:`messages framework </ref/contrib/messages>`. .. versionadded:: 1.2 This template context variable was previously supplied by the ``'auth'`` @@ -589,16 +589,16 @@ For example, if you call ``get_template('story_detail.html')`` and have the above :setting:`TEMPLATE_DIRS` setting, here are the files Django will look for, in order: - * ``/home/html/templates/lawrence.com/story_detail.html`` - * ``/home/html/templates/default/story_detail.html`` +* ``/home/html/templates/lawrence.com/story_detail.html`` +* ``/home/html/templates/default/story_detail.html`` If you call ``select_template(['story_253_detail.html', 'story_detail.html'])``, here's what Django will look for: - * ``/home/html/templates/lawrence.com/story_253_detail.html`` - * ``/home/html/templates/default/story_253_detail.html`` - * ``/home/html/templates/lawrence.com/story_detail.html`` - * ``/home/html/templates/default/story_detail.html`` +* ``/home/html/templates/lawrence.com/story_253_detail.html`` +* ``/home/html/templates/default/story_253_detail.html`` +* ``/home/html/templates/lawrence.com/story_detail.html`` +* ``/home/html/templates/default/story_detail.html`` When Django finds a template that exists, it stops looking. @@ -628,8 +628,8 @@ To load a template that's within a subdirectory, just use a slash, like so:: Using the same :setting:`TEMPLATE_DIRS` setting from above, this example ``get_template()`` call will attempt to load the following templates: - * ``/home/html/templates/lawrence.com/news/story_detail.html`` - * ``/home/html/templates/default/news/story_detail.html`` +* ``/home/html/templates/lawrence.com/news/story_detail.html`` +* ``/home/html/templates/default/news/story_detail.html`` .. _template-loaders: @@ -669,8 +669,8 @@ class. Here are the template loaders that come with Django: ...then ``get_template('foo.html')`` will look for templates in these directories, in this order: - * ``/path/to/myproject/polls/templates/foo.html`` - * ``/path/to/myproject/music/templates/foo.html`` + * ``/path/to/myproject/polls/templates/foo.html`` + * ``/path/to/myproject/music/templates/foo.html`` Note that the loader performs an optimization when it is first imported: It caches a list of which :setting:`INSTALLED_APPS` packages have a @@ -739,15 +739,15 @@ The ``render_to_string`` shortcut takes one required argument -- and render (or a list of template names, in which case Django will use the first template in the list that exists) -- and two optional arguments: - dictionary - A dictionary to be used as variables and values for the - template's context. This can also be passed as the second - positional argument. +dictionary + A dictionary to be used as variables and values for the + template's context. This can also be passed as the second + positional argument. - context_instance - An instance of ``Context`` or a subclass (e.g., an instance of - ``RequestContext``) to use as the template's context. This can - also be passed as the third positional argument. +context_instance + An instance of ``Context`` or a subclass (e.g., an instance of + ``RequestContext``) to use as the template's context. This can + also be passed as the third positional argument. See also the :func:`~django.shortcuts.render_to_response()` shortcut, which calls ``render_to_string`` and feeds the result into an :class:`~django.http.HttpResponse` diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 5b21b18766..4e5c124bd6 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -201,13 +201,13 @@ Signals that this template extends a parent template. This tag can be used in two ways: - * ``{% extends "base.html" %}`` (with quotes) uses the literal value - ``"base.html"`` as the name of the parent template to extend. +* ``{% extends "base.html" %}`` (with quotes) uses the literal value + ``"base.html"`` as the name of the parent template to extend. - * ``{% extends variable %}`` uses the value of ``variable``. If the variable - evaluates to a string, Django will use that string as the name of the - parent template. If the variable evaluates to a ``Template`` object, - Django will use that object as the parent template. +* ``{% extends variable %}`` uses the value of ``variable``. If the variable + evaluates to a string, Django will use that string as the name of the + parent template. If the variable evaluates to a ``Template`` object, + Django will use that object as the parent template. See :ref:`template-inheritance` for more information. @@ -303,20 +303,20 @@ would display the keys and values of the dictionary:: The for loop sets a number of variables available within the loop: - ========================== =============================================== - Variable Description - ========================== =============================================== - ``forloop.counter`` The current iteration of the loop (1-indexed) - ``forloop.counter0`` The current iteration of the loop (0-indexed) - ``forloop.revcounter`` The number of iterations from the end of the - loop (1-indexed) - ``forloop.revcounter0`` The number of iterations from the end of the - loop (0-indexed) - ``forloop.first`` True if this is the first time through the loop - ``forloop.last`` True if this is the last time through the loop - ``forloop.parentloop`` For nested loops, this is the loop "above" the - current one - ========================== =============================================== +========================== =============================================== +Variable Description +========================== =============================================== +``forloop.counter`` The current iteration of the loop (1-indexed) +``forloop.counter0`` The current iteration of the loop (0-indexed) +``forloop.revcounter`` The number of iterations from the end of the + loop (1-indexed) +``forloop.revcounter0`` The number of iterations from the end of the + loop (0-indexed) +``forloop.first`` True if this is the first time through the loop +``forloop.last`` True if this is the last time through the loop +``forloop.parentloop`` For nested loops, this is the loop "above" the + current one +========================== =============================================== for ... empty ^^^^^^^^^^^^^ @@ -526,11 +526,11 @@ expressions, it can be important to know how the operators are grouped when the expression is evaluated - that is, the precedence rules. The precedence of the operators, from lowest to highest, is as follows: - * ``or`` - * ``and`` - * ``not`` - * ``in`` - * ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=`` +* ``or`` +* ``and`` +* ``not`` +* ``in`` +* ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=`` (This follows Python exactly). So, for example, the following complex :ttag:`if` tag: @@ -660,14 +660,14 @@ the variable ``template_name``:: An included template is rendered with the context of the template that's including it. This example produces the output ``"Hello, John"``: - * Context: variable ``person`` is set to ``"john"``. - * Template:: +* Context: variable ``person`` is set to ``"john"``. +* Template:: - {% include "name_snippet.html" %} + {% include "name_snippet.html" %} - * The ``name_snippet.html`` template:: +* The ``name_snippet.html`` template:: - {{ greeting }}, {{ person|default:"friend" }}! + {{ greeting }}, {{ person|default:"friend" }}! .. versionchanged:: 1.3 Additional context and exclusive context. @@ -771,14 +771,14 @@ is a list of people represented by dictionaries with ``first_name``, ...and you'd like to display a hierarchical list that is ordered by gender, like this: - * Male: - * George Bush - * Bill Clinton - * Female: - * Margaret Thatcher - * Condoleezza Rice - * Unknown: - * Pat Smith +* Male: + * George Bush + * Bill Clinton +* Female: + * Margaret Thatcher + * Condoleezza Rice +* Unknown: + * Pat Smith You can use the ``{% regroup %}`` tag to group the list of people by gender. The following snippet of template code would accomplish this:: @@ -805,10 +805,10 @@ attribute and calling the result ``gender_list``. ``{% regroup %}`` produces a list (in this case, ``gender_list``) of **group objects**. Each group object has two attributes: - * ``grouper`` -- the item that was grouped by (e.g., the string "Male" or - "Female"). - * ``list`` -- a list of all items in this group (e.g., a list of all people - with gender='Male'). +* ``grouper`` -- the item that was grouped by (e.g., the string "Male" or + "Female"). +* ``list`` -- a list of all items in this group (e.g., a list of all people + with gender='Male'). Note that ``{% regroup %}`` does not order its input! Our example relies on the fact that the ``people`` list was ordered by ``gender`` in the first place. @@ -830,16 +830,16 @@ grouped together): With this input for ``people``, the example ``{% regroup %}`` template code above would result in the following output: - * Male: - * Bill Clinton - * Unknown: - * Pat Smith - * Female: - * Margaret Thatcher - * Male: - * George Bush - * Female: - * Condoleezza Rice +* Male: + * Bill Clinton +* Unknown: + * Pat Smith +* Female: + * Margaret Thatcher +* Male: + * George Bush +* Female: + * Condoleezza Rice The easiest solution to this gotcha is to make sure in your view code that the data is ordered according to how you want to display it. @@ -959,18 +959,18 @@ bits used in template tags, you must use the ``{% templatetag %}`` tag. The argument tells which template bit to output: - ================== ======= - Argument Outputs - ================== ======= - ``openblock`` ``{%`` - ``closeblock`` ``%}`` - ``openvariable`` ``{{`` - ``closevariable`` ``}}`` - ``openbrace`` ``{`` - ``closebrace`` ``}`` - ``opencomment`` ``{#`` - ``closecomment`` ``#}`` - ================== ======= +================== ======= +Argument Outputs +================== ======= +``openblock`` ``{%`` +``closeblock`` ``%}`` +``openvariable`` ``{{`` +``closevariable`` ``}}`` +``openbrace`` ``{`` +``closebrace`` ``}`` +``opencomment`` ``{#`` +``closecomment`` ``#}`` +================== ======= .. templatetag:: url @@ -1250,75 +1250,75 @@ with some custom extensions. Available format strings: - ================ ======================================== ===================== - Format character Description Example output - ================ ======================================== ===================== - a ``'a.m.'`` or ``'p.m.'`` (Note that ``'a.m.'`` - this is slightly different than PHP's - output, because this includes periods - to match Associated Press style.) - A ``'AM'`` or ``'PM'``. ``'AM'`` - b Month, textual, 3 letters, lowercase. ``'jan'`` - B Not implemented. - c ISO 8601 format. (Note: unlike others ``2008-01-02T10:30:00.000123+02:00``, - formatters, such as "Z", "O" or "r", or ``2008-01-02T10:30:00.000123`` if the datetime is naive - the "c" formatter will not add timezone - offset if value is a naive datetime - (see :class:`datetime.tzinfo`). - d Day of the month, 2 digits with ``'01'`` to ``'31'`` - leading zeros. - D Day of the week, textual, 3 letters. ``'Fri'`` - E Month, locale specific alternative - representation usually used for long - date representation. ``'listopada'`` (for Polish locale, as opposed to ``'Listopad'``) - f Time, in 12-hour hours and minutes, ``'1'``, ``'1:30'`` - with minutes left off if they're zero. - Proprietary extension. - F Month, textual, long. ``'January'`` - g Hour, 12-hour format without leading ``'1'`` to ``'12'`` - zeros. - G Hour, 24-hour format without leading ``'0'`` to ``'23'`` - zeros. - h Hour, 12-hour format. ``'01'`` to ``'12'`` - H Hour, 24-hour format. ``'00'`` to ``'23'`` - i Minutes. ``'00'`` to ``'59'`` - I Not implemented. - j Day of the month without leading ``'1'`` to ``'31'`` - zeros. - l Day of the week, textual, long. ``'Friday'`` - L Boolean for whether it's a leap year. ``True`` or ``False`` - m Month, 2 digits with leading zeros. ``'01'`` to ``'12'`` - M Month, textual, 3 letters. ``'Jan'`` - n Month without leading zeros. ``'1'`` to ``'12'`` - N Month abbreviation in Associated Press ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'`` - style. Proprietary extension. - O Difference to Greenwich time in hours. ``'+0200'`` - P Time, in 12-hour hours, minutes and ``'1 a.m.'``, ``'1:30 p.m.'``, ``'midnight'``, ``'noon'``, ``'12:30 p.m.'`` - 'a.m.'/'p.m.', with minutes left off - if they're zero and the special-case - strings 'midnight' and 'noon' if - appropriate. Proprietary extension. - r :rfc:`2822` formatted date. ``'Thu, 21 Dec 2000 16:01:07 +0200'`` - s Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'`` - S English ordinal suffix for day of the ``'st'``, ``'nd'``, ``'rd'`` or ``'th'`` - month, 2 characters. - t Number of days in the given month. ``28`` to ``31`` - T Time zone of this machine. ``'EST'``, ``'MDT'`` - u Microseconds. ``0`` to ``999999`` - U Seconds since the Unix Epoch - (January 1 1970 00:00:00 UTC). - w Day of the week, digits without ``'0'`` (Sunday) to ``'6'`` (Saturday) - leading zeros. - W ISO-8601 week number of year, with ``1``, ``53`` - weeks starting on Monday. - y Year, 2 digits. ``'99'`` - Y Year, 4 digits. ``'1999'`` - z Day of the year. ``0`` to ``365`` - Z Time zone offset in seconds. The ``-43200`` to ``43200`` - offset for timezones west of UTC is - always negative, and for those east of - UTC is always positive. - ================ ======================================== ===================== +================ ======================================== ===================== +Format character Description Example output +================ ======================================== ===================== +a ``'a.m.'`` or ``'p.m.'`` (Note that ``'a.m.'`` + this is slightly different than PHP's + output, because this includes periods + to match Associated Press style.) +A ``'AM'`` or ``'PM'``. ``'AM'`` +b Month, textual, 3 letters, lowercase. ``'jan'`` +B Not implemented. +c ISO 8601 format. (Note: unlike others ``2008-01-02T10:30:00.000123+02:00``, + formatters, such as "Z", "O" or "r", or ``2008-01-02T10:30:00.000123`` if the datetime is naive + the "c" formatter will not add timezone + offset if value is a naive datetime + (see :class:`datetime.tzinfo`). +d Day of the month, 2 digits with ``'01'`` to ``'31'`` + leading zeros. +D Day of the week, textual, 3 letters. ``'Fri'`` +E Month, locale specific alternative + representation usually used for long + date representation. ``'listopada'`` (for Polish locale, as opposed to ``'Listopad'``) +f Time, in 12-hour hours and minutes, ``'1'``, ``'1:30'`` + with minutes left off if they're zero. + Proprietary extension. +F Month, textual, long. ``'January'`` +g Hour, 12-hour format without leading ``'1'`` to ``'12'`` + zeros. +G Hour, 24-hour format without leading ``'0'`` to ``'23'`` + zeros. +h Hour, 12-hour format. ``'01'`` to ``'12'`` +H Hour, 24-hour format. ``'00'`` to ``'23'`` +i Minutes. ``'00'`` to ``'59'`` +I Not implemented. +j Day of the month without leading ``'1'`` to ``'31'`` + zeros. +l Day of the week, textual, long. ``'Friday'`` +L Boolean for whether it's a leap year. ``True`` or ``False`` +m Month, 2 digits with leading zeros. ``'01'`` to ``'12'`` +M Month, textual, 3 letters. ``'Jan'`` +n Month without leading zeros. ``'1'`` to ``'12'`` +N Month abbreviation in Associated Press ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'`` + style. Proprietary extension. +O Difference to Greenwich time in hours. ``'+0200'`` +P Time, in 12-hour hours, minutes and ``'1 a.m.'``, ``'1:30 p.m.'``, ``'midnight'``, ``'noon'``, ``'12:30 p.m.'`` + 'a.m.'/'p.m.', with minutes left off + if they're zero and the special-case + strings 'midnight' and 'noon' if + appropriate. Proprietary extension. +r :rfc:`2822` formatted date. ``'Thu, 21 Dec 2000 16:01:07 +0200'`` +s Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'`` +S English ordinal suffix for day of the ``'st'``, ``'nd'``, ``'rd'`` or ``'th'`` + month, 2 characters. +t Number of days in the given month. ``28`` to ``31`` +T Time zone of this machine. ``'EST'``, ``'MDT'`` +u Microseconds. ``0`` to ``999999`` +U Seconds since the Unix Epoch + (January 1 1970 00:00:00 UTC). +w Day of the week, digits without ``'0'`` (Sunday) to ``'6'`` (Saturday) + leading zeros. +W ISO-8601 week number of year, with ``1``, ``53`` + weeks starting on Monday. +y Year, 2 digits. ``'99'`` +Y Year, 4 digits. ``'1999'`` +z Day of the year. ``0`` to ``365`` +Z Time zone offset in seconds. The ``-43200`` to ``43200`` + offset for timezones west of UTC is + always negative, and for those east of + UTC is always positive. +================ ======================================== ===================== .. versionadded:: 1.2 @@ -1448,11 +1448,11 @@ escape Escapes a string's HTML. Specifically, it makes these replacements: - * ``<`` is converted to ``<`` - * ``>`` is converted to ``>`` - * ``'`` (single quote) is converted to ``'`` - * ``"`` (double quote) is converted to ``"`` - * ``&`` is converted to ``&`` +* ``<`` is converted to ``<`` +* ``>`` is converted to ``>`` +* ``'`` (single quote) is converted to ``'`` +* ``"`` (double quote) is converted to ``"`` +* ``&`` is converted to ``&`` The escaping is only applied when the string is output, so it does not matter where in a chained sequence of filters you put ``escape``: it will always be @@ -2320,9 +2320,9 @@ django.contrib.markup A collection of template filters that implement these common markup languages: - * Textile - * Markdown - * reST (reStructuredText) +* Textile +* Markdown +* reST (reStructuredText) See the :doc:`markup documentation </ref/contrib/markup>`. diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt index 5356af3563..08f738c879 100644 --- a/docs/ref/unicode.txt +++ b/docs/ref/unicode.txt @@ -17,14 +17,14 @@ data. Normally, this means giving it an encoding of UTF-8 or UTF-16. If you use a more restrictive encoding -- for example, latin1 (iso8859-1) -- you won't be 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. +* 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 21.2.2 in + PostgreSQL 8) 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. +* 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 @@ -106,35 +106,35 @@ Conversion functions The ``django.utils.encoding`` module contains a few functions that are handy for converting back and forth between Unicode and bytestrings. - * ``smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')`` - converts its input to a Unicode string. The ``encoding`` parameter - specifies the input encoding. (For example, Django uses this internally - when processing form input data, which might not be UTF-8 encoded.) The - ``strings_only`` parameter, if set to True, will result in Python - numbers, booleans and ``None`` not being converted to a string (they keep - their original types). The ``errors`` parameter takes any of the values - that are accepted by Python's ``unicode()`` function for its error - handling. +* ``smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')`` + converts its input to a Unicode string. The ``encoding`` parameter + specifies the input encoding. (For example, Django uses this internally + when processing form input data, which might not be UTF-8 encoded.) The + ``strings_only`` parameter, if set to True, will result in Python + numbers, booleans and ``None`` not being converted to a string (they keep + their original types). The ``errors`` parameter takes any of the values + that are accepted by Python's ``unicode()`` function for its error + handling. - If you pass ``smart_unicode()`` an object that has a ``__unicode__`` - method, it will use that method to do the conversion. + If you pass ``smart_unicode()`` an object that has a ``__unicode__`` + method, it will use that method to do the conversion. - * ``force_unicode(s, encoding='utf-8', strings_only=False, - errors='strict')`` is identical to ``smart_unicode()`` in almost all - cases. The difference is when the first argument is a :ref:`lazy - translation <lazy-translations>` instance. While ``smart_unicode()`` - preserves lazy translations, ``force_unicode()`` forces those objects to a - Unicode string (causing the translation to occur). Normally, you'll want - to use ``smart_unicode()``. However, ``force_unicode()`` is useful in - template tags and filters that absolutely *must* have a string to work - with, not just something that can be converted to a string. +* ``force_unicode(s, encoding='utf-8', strings_only=False, + errors='strict')`` is identical to ``smart_unicode()`` in almost all + cases. The difference is when the first argument is a :ref:`lazy + translation <lazy-translations>` instance. While ``smart_unicode()`` + preserves lazy translations, ``force_unicode()`` forces those objects to a + Unicode string (causing the translation to occur). Normally, you'll want + to use ``smart_unicode()``. However, ``force_unicode()`` is useful in + template tags and filters that absolutely *must* have a string to work + with, not just something that can be converted to a string. - * ``smart_str(s, encoding='utf-8', strings_only=False, errors='strict')`` - is essentially the opposite of ``smart_unicode()``. It forces the first - argument to a bytestring. The ``strings_only`` parameter has the same - behavior as for ``smart_unicode()`` and ``force_unicode()``. This is - slightly different semantics from Python's builtin ``str()`` function, - but the difference is needed in a few places within Django's internals. +* ``smart_str(s, encoding='utf-8', strings_only=False, errors='strict')`` + is essentially the opposite of ``smart_unicode()``. It forces the first + argument to a bytestring. The ``strings_only`` parameter has the same + behavior as for ``smart_unicode()`` and ``force_unicode()``. This is + slightly different semantics from Python's builtin ``str()`` function, + but the difference is needed in a few places within Django's internals. Normally, you'll only need to use ``smart_unicode()``. Call it as early as possible on any input data that might be either Unicode or a bytestring, and @@ -152,13 +152,13 @@ URL from an IRI_ -- very loosely speaking, a URI_ that can contain Unicode characters. Quoting and converting an IRI to URI can be a little tricky, so Django provides some assistance. - * The function ``django.utils.encoding.iri_to_uri()`` implements the - conversion from IRI to URI as required by the specification (:rfc:`3987`). +* The function ``django.utils.encoding.iri_to_uri()`` implements the + conversion from IRI to URI as required by the specification (:rfc:`3987`). - * The functions ``django.utils.http.urlquote()`` and - ``django.utils.http.urlquote_plus()`` are versions of Python's standard - ``urllib.quote()`` and ``urllib.quote_plus()`` that work with non-ASCII - characters. (The data is converted to UTF-8 prior to encoding.) +* The functions ``django.utils.http.urlquote()`` and + ``django.utils.http.urlquote_plus()`` are versions of Python's standard + ``urllib.quote()`` and ``urllib.quote_plus()`` that work with non-ASCII + characters. (The data is converted to UTF-8 prior to encoding.) These two groups of functions have slightly different purposes, and it's important to keep them straight. Normally, you would use ``urlquote()`` on the @@ -295,14 +295,14 @@ Template tags and filters A couple of tips to remember when writing your own template tags and filters: - * Always return Unicode strings from a template tag's ``render()`` method - and from template filters. +* Always return Unicode strings from a template tag's ``render()`` method + and from template filters. - * Use ``force_unicode()`` in preference to ``smart_unicode()`` in these - places. Tag rendering and filter calls occur as the template is being - rendered, so there is no advantage to postponing the conversion of lazy - translation objects into strings. It's easier to work solely with Unicode - strings at that point. +* Use ``force_unicode()`` in preference to ``smart_unicode()`` in these + places. Tag rendering and filter calls occur as the template is being + rendered, so there is no advantage to postponing the conversion of lazy + translation objects into strings. It's easier to work solely with Unicode + strings at that point. Email ===== diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index 1755ee77b3..e4648bd1b9 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -37,12 +37,12 @@ to distinguish caches by the ``Accept-language`` header. This function patches the ``Cache-Control`` header by adding all keyword arguments to it. The transformation is as follows: - * All keyword parameter names are turned to lowercase, and underscores - are converted to hyphens. - * If the value of a parameter is ``True`` (exactly ``True``, not just a - true value), only the parameter name is added to the header. - * All other parameters are added with their value, after applying - ``str()`` to it. + * All keyword parameter names are turned to lowercase, and underscores + are converted to hyphens. + * If the value of a parameter is ``True`` (exactly ``True``, not just a + true value), only the parameter name is added to the header. + * All other parameters are added with their value, after applying + ``str()`` to it. .. function:: get_max_age(response) @@ -53,10 +53,10 @@ to distinguish caches by the ``Accept-language`` header. Adds some useful headers to the given ``HttpResponse`` object: - * ``ETag`` - * ``Last-Modified`` - * ``Expires`` - * ``Cache-Control`` + * ``ETag`` + * ``Last-Modified`` + * ``Expires`` + * ``Cache-Control`` Each header is only added if it isn't already set. @@ -553,8 +553,8 @@ For a complete discussion on the usage of the following see the Returns selected language's BiDi layout: - * ``False`` = left-to-right layout - * ``True`` = right-to-left layout + * ``False`` = left-to-right layout + * ``True`` = right-to-left layout .. function:: get_language_from_request(request) |