pytask.new: comparison parts/django/docs/ref/generic-views.txt

equal deleted inserted replaced

-:5ff1fc726848
+:c6bca38c1cbf
+=============
+Generic views
+=============
+Writing Web applications can be monotonous, because we repeat certain patterns
+again and again. In Django, the most common of these patterns have been
+abstracted into "generic views" that let you quickly provide common views of
+an object without actually needing to write any Python code.
+A general introduction to generic views can be found in the :doc:`topic guide
+</topics/http/generic-views>`.
+This reference contains details of Django's built-in generic views, along with
+a list of all keyword arguments that a generic view expects. Remember that
+arguments may either come from the URL pattern or from the ``extra_context``
+additional-information dictionary.
+Most generic views require the ``queryset`` key, which is a ``QuerySet``
+instance; see :doc:`/topics/db/queries` for more information about ``QuerySet``
+objects.
+"Simple" generic views
+======================
+The ``django.views.generic.simple`` module contains simple views to handle a
+couple of common cases: rendering a template when no view logic is needed,
+and issuing a redirect.
+``django.views.generic.simple.direct_to_template``
+--------------------------------------------------
+**Description:**
+Renders a given template, passing it a ``{{ params }}`` template variable,
+which is a dictionary of the parameters captured in the URL.
+**Required arguments:**
+* ``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.
+* ``mimetype``: The MIME type to use for the resulting document. Defaults
+to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+**Example:**
+Given the following URL patterns::
+urlpatterns = patterns('django.views.generic.simple',
+(r'^foo/$',             'direct_to_template', {'template': 'foo_index.html'}),
+(r'^foo/(?P<id>\d+)/$', 'direct_to_template', {'template': 'foo_detail.html'}),
+)
+... a request to ``/foo/`` would render the template ``foo_index.html``, and a
+request to ``/foo/15/`` would render the ``foo_detail.html`` with a context
+variable ``{{ params.id }}`` that is set to ``15``.
+``django.views.generic.simple.redirect_to``
+-------------------------------------------
+**Description:**
+Redirects to a given URL.
+The given URL may contain dictionary-style string formatting, which will be
+interpolated against the parameters captured in the URL. Because keyword
+interpolation is *always* done (even if no arguments are passed in), any ``"%"``
+characters in the URL must be written as ``"%%"`` so that Python will convert
+them to a single percent sign on output.
+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.
+**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``.
+.. versionadded:: 1.1
+The ``permanent`` keyword argument is new in Django 1.1.
+**Example:**
+This example issues a permanent redirect (HTTP status code 301) from
+``/foo/<id>/`` to ``/bar/<id>/``::
+urlpatterns = patterns('django.views.generic.simple',
+('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}),
+)
+This example issues a non-permanent redirect (HTTP status code 302) from
+``/foo/<id>/`` to ``/bar/<id>/``::
+urlpatterns = patterns('django.views.generic.simple',
+('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/', 'permanent': False}),
+)
+This example returns a 410 HTTP error for requests to ``/bar/``::
+urlpatterns = patterns('django.views.generic.simple',
+('^bar/$', 'redirect_to', {'url': None}),
+)
+This example shows how ``"%"`` characters must be written in the URL in order
+to avoid confusion with Python's string formatting markers. If the redirect
+string is written as ``"%7Ejacob/"`` (with only a single ``%``), an exception would be raised::
+urlpatterns = patterns('django.views.generic.simple',
+('^bar/$', 'redirect_to', {'url': '%%7Ejacob.'}),
+)
+Date-based generic views
+========================
+Date-based generic views (in the module ``django.views.generic.date_based``)
+are views for displaying drilldown pages for date-based data.
+``django.views.generic.date_based.archive_index``
+-------------------------------------------------
+**Description:**
+A top-level index page showing the "latest" objects, by date. Objects with
+a date in the *future* are not included unless you set ``allow_future`` to
+``True``.
+**Required arguments:**
+* ``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.
+**Optional arguments:**
+* ``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_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.
+* ``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.
+* ``mimetype``: The MIME type to use for the resulting document. Defaults
+to the value of the ``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``.
+.. versionadded:: 1.0
+* ``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``.
+* ``<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]``.
+.. versionchanged:: 1.0
+The behaviour depending on ``template_object_name`` is new in this version.
+* ``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``.
+``django.views.generic.date_based.archive_year``
+------------------------------------------------
+**Description:**
+A yearly archive page showing all available months in a given year. Objects
+with a date 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.
+* ``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.
+**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_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.
+* ``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.
+* ``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``.
+* ``mimetype``: The MIME type to use for the resulting document. Defaults
+to the value of the ``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``.
+**Template name:**
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_archive_year.html`` by default.
+**Template context:**
+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.
+* ``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``.
+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``
+-------------------------------------------------
+**Description:**
+A monthly archive page showing all objects in a given month. Objects with a
+date 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).
+* ``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.
+* ``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 ``time.strftime``. (See the `strftime docs`_.) 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_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.
+* ``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.
+* ``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 ``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``.
+**Template name:**
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_archive_month.html`` by default.
+**Template context:**
+.. versionadded:: 1.2
+The inclusion of ``date_list`` in the template's context is new.
+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.
+* ``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``.
+* ``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``.
+.. _strftime docs: http://docs.python.org/library/time.html#time.strftime
+``django.views.generic.date_based.archive_week``
+------------------------------------------------
+**Description:**
+A weekly archive page showing all objects in a given week. Objects with a date
+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).
+* ``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.
+* ``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_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.
+* ``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.
+* ``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 ``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``.
+**Template name:**
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_archive_week.html`` by default.
+**Template context:**
+In addition to ``extra_context``, the template's context will be:
+* ``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``.
+``django.views.generic.date_based.archive_day``
+-----------------------------------------------
+**Description:**
+A day archive page showing all objects in a given day. Days in the future throw
+a 404 error, regardless of whether any objects exist for future days, unless
+you set ``allow_future`` to ``True``.
+**Required arguments:**
+* ``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.
+* ``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.
+* ``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 ``time.strftime``. (See the `strftime docs`_.) 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).
+* ``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``.
+* ``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``.
+* ``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.
+* ``mimetype``: The MIME type to use for the resulting document. Defaults
+to the value of the ``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``.
+**Template name:**
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_archive_day.html`` by default.
+**Template context:**
+In addition to ``extra_context``, the template's context will be:
+* ``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``.
+* ``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``.
+``django.views.generic.date_based.archive_today``
+-------------------------------------------------
+**Description:**
+A day archive page showing all objects for *today*. This is exactly the same as
+``archive_day``, except the ``year``/``month``/``day`` arguments are not used,
+and today's date is used instead.
+``django.views.generic.date_based.object_detail``
+-------------------------------------------------
+**Description:**
+A page representing an individual object. If the object has a date value in the
+future, the view will throw a 404 error by default, unless you set
+``allow_future`` to ``True``.
+**Required arguments:**
+* ``year``: The object's four-digit year (a string).
+* ``month``: The object's month , formatted according to the
+``month_format`` argument.
+* ``day``: The object's day , formatted according to the ``day_format``
+argument.
+* ``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``.
+* 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.
+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 ``time.strftime``. (See the `strftime docs`_.) 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).
+* ``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'``.
+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``.
+* ``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.
+* ``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 ``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``.
+**Template name:**
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_detail.html`` by default.
+**Template context:**
+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``.
+List/detail generic views
+=========================
+The list-detail generic-view framework (in the
+``django.views.generic.list_detail`` module) is similar to the date-based one,
+except the former simply has two views: a list of objects and an individual
+object page.
+``django.views.generic.list_detail.object_list``
+------------------------------------------------
+**Description:**
+A page representing a list of objects.
+**Required arguments:**
+* ``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.
+* ``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_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.
+* ``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.
+* ``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 ``DEFAULT_CONTENT_TYPE`` setting.
+**Template name:**
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_list.html`` by default.
+**Template context:**
+.. versionadded:: 1.0
+The ``paginator`` and ``page_obj`` context variables are new.
+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``.
+* ``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``.
+* ``page_obj``: An instance of ``django.core.paginator.Page``.
+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::
+(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::
+/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.
+These values and lists are 1-based, not 0-based, so the first page would be
+represented as page ``1``.
+For more on pagination, read the :doc:`pagination documentation
+</topics/pagination>`.
+.. versionadded:: 1.0
+As a special case, you are also permitted to use ``last`` as a value for
+``page``::
+/objects/?page=last
+This allows you to access the final page of results without first having to
+determine how many pages there are.
+Note that ``page`` *must* be either a valid page number or the value ``last``;
+any other value for ``page`` will result in a 404 error.
+``django.views.generic.list_detail.object_detail``
+--------------------------------------------------
+A page representing an individual object.
+**Description:**
+A page representing an individual object.
+**Required arguments:**
+* ``queryset``: A ``QuerySet`` that contains the object.
+* 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.
+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_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.
+* ``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.
+* ``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'``.
+* ``mimetype``: The MIME type to use for the resulting document. Defaults
+to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+**Template name:**
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_detail.html`` by default.
+**Template context:**
+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``.
+Create/update/delete generic views
+==================================
+The ``django.views.generic.create_update`` module contains a set of functions
+for creating, editing and deleting objects.
+.. versionchanged:: 1.0
+``django.views.generic.create_update.create_object`` and
+``django.views.generic.create_update.update_object`` now use the new :doc:`forms
+library </topics/forms/index>` to build and display the form.
+``django.views.generic.create_update.create_object``
+----------------------------------------------------
+**Description:**
+A page that displays a form for creating an object, redisplaying the form with
+validation errors (if there are any) and saving the object.
+**Required arguments:**
+* 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.
+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`` 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``.
+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_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.
+* ``context_processors``: A list of template-context processors to apply to
+the view's template.
+**Template name:**
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_form.html`` by default.
+**Template context:**
+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.
+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>
+See the :doc:`forms documentation </topics/forms/index>` for more
+information about using ``Form`` objects in templates.
+``django.views.generic.create_update.update_object``
+----------------------------------------------------
+**Description:**
+A page that displays a form for editing an existing object, redisplaying the
+form with validation errors (if there are any) and saving changes to the
+object. This uses a form automatically generated from the object's
+model class.
+**Required arguments:**
+* 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.
+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.
+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'``.
+**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`` 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``.
+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_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.
+* ``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 name:**
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_form.html`` by default.
+**Template context:**
+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.
+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>
+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``.
+``django.views.generic.create_update.delete_object``
+----------------------------------------------------
+**Description:**
+A view that displays a confirmation page and deletes an existing object. The
+given object will only be deleted if the request method is ``POST``. If this
+view is fetched via ``GET``, it will display a confirmation page that should
+contain a form that POSTs to the same URL.
+**Required arguments:**
+* ``model``: The Django model class of the object that the form will
+create.
+* 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.
+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.
+**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``.
+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_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.
+* ``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 name:**
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_confirm_delete.html`` by default.
+**Template context:**
+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``.