PageRenderTime 160ms CodeModel.GetById 101ms app.highlight 8ms RepoModel.GetById 42ms app.codeStats 0ms

/docs/ref/class-based-views.txt

https://code.google.com/p/mango-py/
Plain Text | 1323 lines | 902 code | 421 blank | 0 comment | 0 complexity | fb26d0d6fbb2a280043650b9d46937cf MD5 | raw file
   1=========================
   2Class-based generic views
   3=========================
   4
   5.. versionadded:: 1.3
   6
   7.. note::
   8    Prior to Django 1.3, generic views were implemented as functions. The
   9    function-based implementation has been deprecated in favor of the
  10    class-based approach described here.
  11
  12    For details on the previous generic views implementation,
  13    see the :doc:`topic guide </topics/generic-views>` and
  14    :doc:`detailed reference </ref/generic-views>`.
  15
  16Writing Web applications can be monotonous, because we repeat certain patterns
  17again and again. Django tries to take away some of that monotony at the model
  18and template layers, but Web developers also experience this boredom at the view
  19level.
  20
  21A general introduction to class-based generic views can be found in the
  22:doc:`topic guide </topics/class-based-views>`.
  23
  24This reference contains details of Django's built-in generic views, along with
  25a list of the keyword arguments that each generic view expects. Remember that
  26arguments may either come from the URL pattern or from the ``extra_context``
  27additional-information dictionary.
  28
  29Most generic views require the ``queryset`` key, which is a ``QuerySet``
  30instance; see :doc:`/topics/db/queries` for more information about ``QuerySet``
  31objects.
  32
  33Mixins
  34======
  35
  36A mixin class is a way of using the inheritance capabilities of
  37classes to compose a class out of smaller pieces of behavior. Django's
  38class-based generic views are constructed by composing mixins into
  39usable generic views.
  40
  41For example, the :class:`~django.views.generic.base.detail.DetailView`
  42is composed from:
  43
  44    * :class:`~django.db.views.generic.base.View`, which provides the
  45      basic class-based behavior
  46    * :class:`~django.db.views.generic.detail.SingleObjectMixin`, which
  47      provides the utilities for retrieving and displaying a single object
  48    * :class:`~django.db.views.generic.detail.SingleObjectTemplateResponseMixin`,
  49      which provides the tools for rendering a single object into a
  50      template-based response.
  51
  52When combined, these mixins provide all the pieces necessary to
  53provide a view over a single object that renders a template to produce
  54a response.
  55
  56Django provides a range of mixins. If you want to write your own
  57generic views, you can build classes that compose these mixins in
  58interesting ways. Alternatively, you can just use the pre-mixed
  59`Generic views`_ that Django provides.
  60
  61.. note::
  62
  63    When the documentation for a view gives the list of mixins, that view
  64    inherits all the properties and methods of that mixin.
  65
  66Simple mixins
  67-------------
  68
  69.. currentmodule:: django.views.generic.base
  70
  71TemplateResponseMixin
  72~~~~~~~~~~~~~~~~~~~~~
  73.. class:: TemplateResponseMixin()
  74
  75    .. attribute:: template_name
  76
  77        The path to the template to use when rendering the view.
  78
  79    .. attribute:: response_class
  80
  81        The response class to be returned by ``render_to_response`` method.
  82        Default is
  83        :class:`TemplateResponse <django.template.response.TemplateResponse>`.
  84        The template and context of ``TemplateResponse`` instances can be
  85        altered later (e.g. in
  86        :ref:`template response middleware <template-response-middleware>`).
  87
  88        If you need custom template loading or custom context object
  89        instantiation, create a ``TemplateResponse`` subclass and assign it to
  90        ``response_class``.
  91
  92    .. method:: render_to_response(context, **response_kwargs)
  93
  94        Returns a ``self.response_class`` instance.
  95
  96        If any keyword arguments are provided, they will be
  97        passed to the constructor of the response class.
  98
  99        Calls :meth:`~TemplateResponseMixin.get_template_names()` to obtain the
 100        list of template names that will be searched looking for an existent
 101        template.
 102
 103    .. method:: get_template_names()
 104
 105        Returns a list of template names to search for when rendering the
 106        template.
 107
 108        If :attr:`TemplateResponseMixin.template_name` is specified, the
 109        default implementation will return a list containing
 110        :attr:`TemplateResponseMixin.template_name` (if it is specified).
 111
 112
 113Single object mixins
 114--------------------
 115
 116.. currentmodule:: django.views.generic.detail
 117
 118SingleObjectMixin
 119~~~~~~~~~~~~~~~~~
 120.. class:: SingleObjectMixin()
 121
 122    .. attribute:: model
 123
 124        The model that this view will display data for. Specifying ``model
 125        = Foo`` is effectively the same as specifying ``queryset =
 126        Foo.objects.all()``.
 127
 128    .. attribute:: queryset
 129
 130        A ``QuerySet`` that represents the objects. If provided, the value of
 131        :attr:`SingleObjectMixin.queryset` supersedes the value provided for
 132        :attr:`SingleObjectMixin.model`.
 133
 134    .. attribute:: slug_field
 135
 136        The name of the field on the model that contains the slug. By default,
 137        ``slug_field`` is ``'slug'``.
 138
 139    .. attribute:: context_object_name
 140
 141        Designates the name of the variable to use in the context.
 142
 143    .. method:: get_object(queryset=None)
 144
 145        Returns the single object that this view will display. If
 146        ``queryset`` is provided, that queryset will be used as the
 147        source of objects; otherwise,
 148        :meth:`~SingleObjectMixin.get_queryset` will be used.
 149        :meth:`~SingleObjectMixin.get_object` looks for a ``pk``
 150        argument in the arguments to the view; if ``pk`` is found,
 151        this method performs a primary-key based lookup using that
 152        value. If no ``pk`` argument is found, it looks for a ``slug``
 153        argument, and performs a slug lookup using the
 154        :attr:`SingleObjectMixin.slug_field`.
 155
 156    .. method:: get_queryset()
 157
 158        Returns the queryset that will be used to retrieve the object that
 159        this view will display. By default,
 160        :meth:`~SingleObjectMixin.get_queryset` returns the value of the
 161        :attr:`~SingleObjectMixin.queryset` attribute if it is set, otherwise
 162        it constructs a :class:`QuerySet` by calling the `all()` method on the
 163        :attr:`~SingleObjectMixin.model` attribute's default manager.
 164
 165    .. method:: get_context_object_name(obj)
 166
 167        Return the context variable name that will be used to contain the
 168        data that this view is manipulating. If
 169        :attr:`~SingleObjectMixin.context_object_name` is not set, the context
 170        name will be constructed from the ``object_name`` of the model that
 171        the queryset is composed from. For example, the model ``Article``
 172        would have context object named ``'article'``.
 173
 174    .. method:: get_context_data(**kwargs)
 175
 176        Returns context data for displaying the list of objects.
 177
 178    **Context**
 179
 180        * ``object``: The object that this view is displaying. If
 181          ``context_object_name`` is specified, that variable will also be
 182          set in the context, with the same value as ``object``.
 183
 184SingleObjectTemplateResponseMixin
 185~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 186
 187.. class:: SingleObjectTemplateResponseMixin()
 188
 189    A mixin class that performs template-based response rendering for views
 190    that operate upon a single object instance. Requires that the view it is
 191    mixed with provides ``self.object``, the object instance that the view is
 192    operating on. ``self.object`` will usually be, but is not required to be,
 193    an instance of a Django model. It may be ``None`` if the view is in the
 194    process of constructing a new instance.
 195
 196    **Extends**
 197
 198        * :class:`~django.views.generic.base.TemplateResponseMixin`
 199
 200    .. attribute:: template_name_field
 201
 202        The field on the current object instance that can be used to determine
 203        the name of a candidate template. If either ``template_name_field`` or
 204        the value of the ``template_name_field`` on the current object instance
 205        is ``None``, the object will not be interrogated for a candidate
 206        template name.
 207
 208    .. attribute:: template_name_suffix
 209
 210        The suffix to append to the auto-generated candidate template name.
 211        Default suffix is ``_detail``.
 212
 213    .. method:: get_template_names()
 214
 215        Returns a list of candidate template names. Returns the following list:
 216
 217          * the value of ``template_name`` on the view (if provided)
 218          * the contents of the ``template_name_field`` field on the
 219            object instance that the view is operating upon (if available)
 220          * ``<app_label>/<object_name><template_name_suffix>.html``
 221
 222Multiple object mixins
 223----------------------
 224
 225.. currentmodule:: django.views.generic.list
 226
 227MultipleObjectMixin
 228~~~~~~~~~~~~~~~~~~~
 229.. class:: MultipleObjectMixin()
 230
 231    A mixin that can be used to display a list of objects.
 232
 233    If ``paginate_by`` is specified, Django will paginate the results returned
 234    by this. You can specify the page number in the URL in one of two ways:
 235
 236        * Use the ``page`` parameter in the URLconf. For example, this is what
 237          your URLconf might look like::
 238
 239            (r'^objects/page(?P<page>[0-9]+)/$', PaginatedView.as_view())
 240
 241        * Pass the page number via the ``page`` query-string parameter. For
 242          example, a URL would look like this::
 243
 244            /objects/?page=3
 245
 246    These values and lists are 1-based, not 0-based, so the first page would be
 247    represented as page ``1``.
 248
 249    For more on pagination, read the :doc:`pagination documentation
 250    </topics/pagination>`.
 251
 252    As a special case, you are also permitted to use ``last`` as a value for
 253    ``page``::
 254
 255        /objects/?page=last
 256
 257    This allows you to access the final page of results without first having to
 258    determine how many pages there are.
 259
 260    Note that ``page`` *must* be either a valid page number or the value
 261    ``last``; any other value for ``page`` will result in a 404 error.
 262
 263    .. attribute:: allow_empty
 264
 265        A boolean specifying whether to display the page if no objects are
 266        available. If this is ``False`` and no objects are available, the view
 267        will raise a 404 instead of displaying an empty page. By default, this
 268        is ``True``.
 269
 270    .. attribute:: model
 271
 272        The model that this view will display data for. Specifying ``model
 273        = Foo`` is effectively the same as specifying ``queryset =
 274        Foo.objects.all()``.
 275
 276    .. attribute:: queryset
 277
 278        A ``QuerySet`` that represents the objects. If provided, the value of
 279        :attr:`MultipleObjectMixin.queryset` supersedes the value provided for
 280        :attr:`MultipleObjectMixin.model`.
 281
 282    .. attribute:: paginate_by
 283
 284        An integer specifying how many objects should be displayed per page. If
 285        this is given, the view will paginate objects with
 286        :attr:`MultipleObjectMixin.paginate_by` objects per page. The view will
 287        expect either a ``page`` query string parameter (via ``GET``) or a
 288        ``page`` variable specified in the URLconf.
 289
 290    .. attribute:: paginator_class
 291
 292       The paginator class to be used for pagination. By default,
 293       :class:`django.core.paginator.Paginator` is used. If the custom paginator
 294       class doesn't have the same constructor interface as
 295       :class:`django.core.paginator.Paginator`, you will also need to
 296       provide an implementation for :meth:`MultipleObjectMixin.get_paginator`.
 297
 298    .. attribute:: context_object_name
 299
 300        Designates the name of the variable to use in the context.
 301
 302    .. method:: get_queryset()
 303
 304        Returns the queryset that represents the data this view will display.
 305
 306    .. method:: paginate_queryset(queryset, page_size)
 307
 308        Returns a 4-tuple containing (``paginator``, ``page``, ``object_list``,
 309        ``is_paginated``).
 310
 311        Constructed by paginating ``queryset`` into pages of size ``page_size``.
 312        If the request contains a ``page`` argument, either as a captured URL
 313        argument or as a GET argument, ``object_list`` will correspond to the
 314        objects from that page.
 315
 316    .. method:: get_paginate_by(queryset)
 317
 318        Returns the number of items to paginate by, or ``None`` for no
 319        pagination. By default this simply returns the value of
 320        :attr:`MultipleObjectMixin.paginate_by`.
 321
 322    .. method:: get_paginator(queryset, per_page, orphans=0, allow_empty_first_page=True)
 323
 324        Returns an instance of the paginator to use for this view. By default,
 325        instantiates an instance of :attr:`paginator_class`.
 326
 327    .. method:: get_allow_empty()
 328
 329        Return a boolean specifying whether to display the page if no objects
 330        are available. If this method returns ``False`` and no objects are
 331        available, the view will raise a 404 instead of displaying an empty
 332        page. By default, this is ``True``.
 333
 334    .. method:: get_context_object_name(object_list)
 335
 336        Return the context variable name that will be used to contain
 337        the list of data that this view is manipulating. If
 338        ``object_list`` is a queryset of Django objects and
 339        :attr:`~MultipleObjectMixin.context_object_name` is not set,
 340        the context name will be the ``object_name`` of the model that
 341        the queryset is composed from, with postfix ``'_list'``
 342        appended. For example, the model ``Article`` would have a
 343        context object named ``article_list``.
 344
 345    .. method:: get_context_data(**kwargs)
 346
 347        Returns context data for displaying the list of objects.
 348
 349    **Context**
 350
 351        * ``object_list``: The list of objects that this view is displaying. If
 352          ``context_object_name`` is specified, that variable will also be set
 353          in the context, with the same value as ``object_list``.
 354
 355        * ``is_paginated``: A boolean representing whether the results are
 356          paginated. Specifically, this is set to ``False`` if no page size has
 357          been specified, or if the available objects do not span multiple
 358          pages.
 359
 360        * ``paginator``: An instance of
 361          :class:`django.core.paginator.Paginator`. If the page is not
 362          paginated, this context variable will be ``None``.
 363
 364        * ``page_obj``: An instance of
 365          :class:`django.core.paginator.Page`. If the page is not paginated,
 366          this context variable will be ``None``.
 367
 368MultipleObjectTemplateResponseMixin
 369~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 370.. class:: MultipleObjectTemplateResponseMixin()
 371
 372    A mixin class that performs template-based response rendering for views
 373    that operate upon a list of object instances. Requires that the view it is
 374    mixed with provides ``self.object_list``, the list of object instances that
 375    the view is operating on. ``self.object_list`` may be, but is not required
 376    to be, a :class:`~django.db.models.Queryset`.
 377
 378    **Extends**
 379
 380        * :class:`~django.views.generic.base.TemplateResponseMixin`
 381
 382    .. attribute:: template_name_suffix
 383
 384        The suffix to append to the auto-generated candidate template name.
 385        Default suffix is ``_list``.
 386
 387    .. method:: get_template_names()
 388
 389        Returns a list of candidate template names. Returns the following list:
 390
 391          * the value of ``template_name`` on the view (if provided)
 392          * ``<app_label>/<object_name><template_name_suffix>.html``
 393
 394Editing mixins
 395--------------
 396
 397.. currentmodule:: django.views.generic.edit
 398
 399FormMixin
 400~~~~~~~~~
 401.. class:: FormMixin()
 402
 403    A mixin class that provides facilities for creating and displaying forms.
 404
 405    .. attribute:: initial
 406
 407        A dictionary containing initial data for the form.
 408
 409    .. attribute:: form_class
 410
 411        The form class to instantiate.
 412
 413    .. attribute:: success_url
 414
 415        The URL to redirect to when the form is successfully processed.
 416
 417    .. method:: get_initial()
 418
 419        Retrieve initial data for the form. By default, returns
 420        :attr:`.initial`.
 421
 422    .. method:: get_form_class()
 423
 424        Retrieve the form class to instantiate. By default
 425        :attr:`.form_class`.
 426
 427    .. method:: get_form(form_class)
 428
 429        Instantiate an instance of ``form_class`` using
 430        :meth:`.get_form_kwargs`.
 431
 432    .. method:: get_form_kwargs()
 433
 434        Build the keyword arguments required to instantiate the form.
 435
 436        The ``initial`` argument is set to :meth:`.get_initial`. If the
 437        request is a ``POST`` or ``PUT``, the request data (``request.POST``
 438        and ``request.FILES``) will also be provided.
 439
 440    .. method:: get_success_url()
 441
 442        Determine the URL to redirect to when the form is successfully
 443        validated. Returns :attr:`.success_url` by default.
 444
 445    .. method:: form_valid(form)
 446
 447        Redirects to :meth:`.get_success_url`.
 448
 449    .. method:: form_invalid(form)
 450
 451        Renders a response, providing the invalid form as context.
 452
 453    .. method:: get_context_data(**kwargs)
 454
 455        Populates a context containing the contents of ``kwargs``.
 456
 457    **Context**
 458
 459        * ``form``: The form instance that was generated for the view.
 460
 461    .. note::
 462
 463        Views mixing :class:`FormMixin` must
 464        provide an implementation of :meth:`.form_valid` and
 465        :meth:`.form_invalid`.
 466
 467ModelFormMixin
 468~~~~~~~~~~~~~~
 469.. class:: ModelFormMixin()
 470
 471    A form mixin that works on ModelForms, rather than a standalone form.
 472
 473    Since this is a subclass of
 474    :class:`~django.views.generic.detail.SingleObjectMixin`, instances of this
 475    mixin have access to the :attr:`~SingleObjectMixin.model` and
 476    :attr:`~SingleObjectMixin.queryset` attributes, describing the type of
 477    object that the ModelForm is manipulating. The view also provides
 478    ``self.object``, the instance being manipulated. If the instance is being
 479    created, ``self.object`` will be ``None``
 480
 481    **Mixins**
 482
 483        * :class:`django.views.generic.forms.FormMixin`
 484        * :class:`django.views.generic.detail.SingleObjectMixin`
 485
 486    .. attribute:: success_url
 487
 488        The URL to redirect to when the form is successfully processed.
 489
 490        ``success_url`` may contain dictionary string formatting, which
 491        will be interpolated against the object's field attributes. For
 492        example, you could use ``success_url="/polls/%(slug)s/"`` to
 493        redirect to a URL composed out of the ``slug`` field on a model.
 494
 495    .. method:: get_form_class()
 496
 497        Retrieve the form class to instantiate. If
 498        :attr:`FormMixin.form_class` is provided, that class will be used.
 499        Otherwise, a ModelForm will be instantiated using the model associated
 500        with the :attr:`~SingleObjectMixin.queryset`, or with the
 501        :attr:`~SingleObjectMixin.model`, depending on which attribute is
 502        provided.
 503
 504    .. method:: get_form_kwargs()
 505
 506        Add the current instance (``self.object``) to the standard
 507        :meth:`FormMixin.get_form_kwargs`.
 508
 509    .. method:: get_success_url()
 510
 511        Determine the URL to redirect to when the form is successfully
 512        validated. Returns :attr:`FormMixin.success_url` if it is provided;
 513        otherwise, attempts to use the ``get_absolute_url()`` of the object.
 514
 515    .. method:: form_valid()
 516
 517        Saves the form instance, sets the current object for the view, and
 518        redirects to :meth:`.get_success_url`.
 519
 520    .. method:: form_invalid()
 521
 522        Renders a response, providing the invalid form as context.
 523
 524ProcessFormView
 525~~~~~~~~~~~~~~~
 526.. class:: ProcessFormView()
 527
 528    A mixin that provides basic HTTP GET and POST workflow.
 529
 530    .. method:: get(request, *args, **kwargs)
 531
 532        Constructs a form, then renders a response using a context that
 533        contains that form.
 534
 535    .. method:: post(request, *args, **kwargs)
 536
 537        Constructs a form, checks the form for validity, and handles it
 538        accordingly.
 539
 540    The PUT action is also handled, as an analog of POST.
 541
 542DeletionMixin
 543~~~~~~~~~~~~~
 544.. class:: DeletionMixin()
 545
 546    Enables handling of the ``DELETE`` http action.
 547
 548    .. attribute:: success_url
 549
 550        The url to redirect to when the nominated object has been
 551        successfully deleted.
 552
 553    .. method:: get_success_url(obj)
 554
 555        Returns the url to redirect to when the nominated object has been
 556        successfully deleted. Returns
 557        :attr:`~django.views.generic.edit.DeletionMixin.success_url` by
 558        default.
 559
 560Date-based mixins
 561-----------------
 562
 563.. currentmodule:: django.views.generic.dates
 564
 565YearMixin
 566~~~~~~~~~
 567.. class:: YearMixin()
 568
 569    A mixin that can be used to retrieve and provide parsing information for a
 570    year component of a date.
 571
 572    .. attribute:: year_format
 573
 574        The strftime_ format to use when parsing the year. By default, this is
 575        ``'%Y'``.
 576
 577    .. _strftime: http://docs.python.org/library/time.html#time.strftime
 578
 579    .. attribute:: year
 580
 581        **Optional** The value for the year (as a string). By default, set to
 582        ``None``, which means the year will be determined using other means.
 583
 584    .. method:: get_year_format()
 585
 586        Returns the strftime_ format to use when parsing the year. Returns
 587        :attr:`YearMixin.year_format` by default.
 588
 589    .. method:: get_year()
 590
 591        Returns the year for which this view will display data. Tries the
 592        following sources, in order:
 593
 594            * The value of the :attr:`YearMixin.year` attribute.
 595            * The value of the `year` argument captured in the URL pattern
 596            * The value of the `year` GET query argument.
 597
 598        Raises a 404 if no valid year specification can be found.
 599
 600MonthMixin
 601~~~~~~~~~~
 602.. class:: MonthMixin()
 603
 604    A mixin that can be used to retrieve and provide parsing information for a
 605    month component of a date.
 606
 607    .. attribute:: month_format
 608
 609        The strftime_ format to use when parsing the month. By default, this is
 610        ``'%b'``.
 611
 612    .. attribute:: month
 613
 614        **Optional** The value for the month (as a string). By default, set to
 615        ``None``, which means the month will be determined using other means.
 616
 617    .. method:: get_month_format()
 618
 619        Returns the strftime_ format to use when parsing the month. Returns
 620        :attr:`MonthMixin.month_format` by default.
 621
 622    .. method:: get_month()
 623
 624        Returns the month for which this view will display data. Tries the
 625        following sources, in order:
 626
 627            * The value of the :attr:`MonthMixin.month` attribute.
 628            * The value of the `month` argument captured in the URL pattern
 629            * The value of the `month` GET query argument.
 630
 631        Raises a 404 if no valid month specification can be found.
 632
 633    .. method:: get_next_month(date)
 634
 635        Returns a date object containing the first day of the month after the
 636        date provided. Returns ``None`` if mixed with a view that sets
 637        ``allow_future = False``, and the next month is in the future. If
 638        ``allow_empty = False``, returns the next month that contains data.
 639
 640    .. method:: get_prev_month(date)
 641
 642        Returns a date object containing the first day of the month before the
 643        date provided. If ``allow_empty = False``, returns the previous month
 644        that contained data.
 645
 646DayMixin
 647~~~~~~~~~
 648.. class:: DayMixin()
 649
 650    A mixin that can be used to retrieve and provide parsing information for a
 651    day component of a date.
 652
 653    .. attribute:: day_format
 654
 655        The strftime_ format to use when parsing the day. By default, this is
 656        ``'%d'``.
 657
 658    .. attribute:: day
 659
 660        **Optional** The value for the day (as a string). By default, set to
 661        ``None``, which means the day will be determined using other means.
 662
 663    .. method:: get_day_format()
 664
 665        Returns the strftime_ format to use when parsing the day. Returns
 666        :attr:`DayMixin.day_format` by default.
 667
 668    .. method:: get_day()
 669
 670        Returns the day for which this view will display data. Tries the
 671        following sources, in order:
 672
 673            * The value of the :attr:`DayMixin.day` attribute.
 674            * The value of the `day` argument captured in the URL pattern
 675            * The value of the `day` GET query argument.
 676
 677        Raises a 404 if no valid day specification can be found.
 678
 679    .. method:: get_next_day(date)
 680
 681        Returns a date object containing the next day after the date provided.
 682        Returns ``None`` if mixed with a view that sets ``allow_future = False``,
 683        and the next day is in the future. If ``allow_empty = False``, returns
 684        the next day that contains data.
 685
 686    .. method:: get_prev_day(date)
 687
 688        Returns a date object containing the previous day. If
 689        ``allow_empty = False``, returns the previous day that contained data.
 690
 691WeekMixin
 692~~~~~~~~~
 693.. class:: WeekMixin()
 694
 695    A mixin that can be used to retrieve and provide parsing information for a
 696    week component of a date.
 697
 698    .. attribute:: week_format
 699
 700        The strftime_ format to use when parsing the week. By default, this is
 701        ``'%U'``.
 702
 703    .. attribute:: week
 704
 705        **Optional** The value for the week (as a string). By default, set to
 706        ``None``, which means the week will be determined using other means.
 707
 708    .. method:: get_week_format()
 709
 710        Returns the strftime_ format to use when parsing the week. Returns
 711        :attr:`WeekMixin.week_format` by default.
 712
 713    .. method:: get_week()
 714
 715        Returns the week for which this view will display data. Tries the
 716        following sources, in order:
 717
 718            * The value of the :attr:`WeekMixin.week` attribute.
 719            * The value of the `week` argument captured in the URL pattern
 720            * The value of the `week` GET query argument.
 721
 722        Raises a 404 if no valid week specification can be found.
 723
 724
 725DateMixin
 726~~~~~~~~~
 727.. class:: DateMixin()
 728
 729    A mixin class providing common behavior for all date-based views.
 730
 731    .. attribute:: date_field
 732
 733        The name of the ``DateField`` or ``DateTimeField`` in the
 734        ``QuerySet``'s model that the date-based archive should use to
 735        determine the objects on the page.
 736
 737    .. attribute:: allow_future
 738
 739        A boolean specifying whether to include "future" objects on this page,
 740        where "future" means objects in which the field specified in
 741        ``date_field`` is greater than the current date/time. By default, this
 742        is ``False``.
 743
 744    .. method:: get_date_field()
 745
 746        Returns the name of the field that contains the date data that this
 747        view will operate on. Returns :attr:`DateMixin.date_field` by default.
 748
 749    .. method:: get_allow_future()
 750
 751        Determine whether to include "future" objects on this page, where
 752        "future" means objects in which the field specified in ``date_field``
 753        is greater than the current date/time. Returns
 754        :attr:`DateMixin.date_field` by default.
 755
 756BaseDateListView
 757~~~~~~~~~~~~~~~~
 758.. class:: BaseDateListView()
 759
 760    A base class that provides common behavior for all date-based views. There
 761    won't normally be a reason to instantiate
 762    :class:`~django.views.generic.dates.BaseDateListView`; instantiate one of
 763    the subclasses instead.
 764
 765    While this view (and it's subclasses) are executing, ``self.object_list``
 766    will contain the list of objects that the view is operating upon, and
 767    ``self.date_list`` will contain the list of dates for which data is
 768    available.
 769
 770    **Mixins**
 771
 772        * :class:`~django.views.generic.dates.DateMixin`
 773        * :class:`~django.views.generic.list.MultipleObjectMixin`
 774
 775    .. attribute:: allow_empty
 776
 777        A boolean specifying whether to display the page if no objects are
 778        available. If this is ``False`` and no objects are available, the view
 779        will raise a 404 instead of displaying an empty page. By default, this
 780        is ``True``.
 781
 782    .. method:: get_dated_items():
 783
 784        Returns a 3-tuple containing (``date_list``, ``latest``,
 785        ``extra_context``).
 786
 787        ``date_list`` is the list of dates for which data is available.
 788        ``object_list`` is the list of objects ``extra_context`` is a
 789        dictionary of context data that will be added to any context data
 790        provided by the
 791        :class:`~django.views.generic.list.MultipleObjectMixin`.
 792
 793    .. method:: get_dated_queryset(**lookup)
 794
 795        Returns a queryset, filtered using the query arguments defined by
 796        ``lookup``. Enforces any restrictions on the queryset, such as
 797        ``allow_empty`` and ``allow_future``.
 798
 799    .. method:: get_date_list(queryset, date_type)
 800
 801        Returns the list of dates of type ``date_type`` for which
 802        ``queryset`` contains entries. For example, ``get_date_list(qs,
 803        'year')`` will return the list of years for which ``qs`` has entries.
 804        See :meth:`~django.db.models.QuerySet.dates()` for the
 805        ways that the ``date_type`` argument can be used.
 806
 807
 808Generic views
 809=============
 810
 811Simple generic views
 812--------------------
 813
 814.. currentmodule:: django.views.generic.base
 815
 816View
 817~~~~
 818.. class:: View()
 819
 820    The master class-based base view. All other generic class-based views
 821    inherit from this base class.
 822
 823    Each request served by a :class:`~django.views.generic.base.View` has an
 824    independent state; therefore, it is safe to store state variables on the
 825    instance (i.e., ``self.foo = 3`` is a thread-safe operation).
 826
 827    A class-based view is deployed into a URL pattern using the
 828    :meth:`~View.as_view()` classmethod::
 829
 830        urlpatterns = patterns('',
 831                (r'^view/$', MyView.as_view(size=42)),
 832            )
 833
 834    Any argument passed into :meth:`~View.as_view()` will be assigned onto the
 835    instance that is used to service a request. Using the previous example,
 836    this means that every request on ``MyView`` is able to interrogate
 837    ``self.size``.
 838
 839    .. admonition:: Thread safety with view arguments
 840
 841        Arguments passed to a view are shared between every instance of a view.
 842        This means that you shoudn't use a list, dictionary, or any other
 843        variable object as an argument to a view. If you did, the actions of
 844        one user visiting your view could have an effect on subsequent users
 845        visiting the same view.
 846
 847    .. method:: dispatch(request, *args, **kwargs)
 848
 849        The ``view`` part of the view -- the method that accepts a ``request``
 850        argument plus arguments, and returns a HTTP response.
 851
 852        The default implementation will inspect the HTTP method and attempt to
 853        delegate to a method that matches the HTTP method; a ``GET`` will be
 854        delegated to :meth:`~View.get()`, a ``POST`` to :meth:`~View.post()`,
 855        and so on.
 856
 857        The default implementation also sets ``request``, ``args`` and
 858        ``kwargs`` as instance variables, so any method on the view can know
 859        the full details of the request that was made to invoke the view.
 860
 861    .. method:: http_method_not_allowed(request, *args, **kwargs)
 862
 863        If the view was called with HTTP method it doesn't support, this method
 864        is called instead.
 865
 866        The default implementation returns ``HttpResponseNotAllowed`` with list
 867        of allowed methods in plain text.
 868
 869TemplateView
 870~~~~~~~~~~~~
 871.. class:: TemplateView()
 872
 873    Renders a given template, passing it a ``{{ params }}`` template variable,
 874    which is a dictionary of the parameters captured in the URL.
 875
 876    **Mixins**
 877
 878        * :class:`django.views.generic.base.TemplateResponseMixin`
 879
 880    .. attribute:: template_name
 881
 882        The full name of a template to use.
 883
 884    .. method:: get_context_data(**kwargs)
 885
 886        Return a context data dictionary consisting of the contents of
 887        ``kwargs`` stored in the context variable ``params``.
 888
 889    **Context**
 890
 891        * ``params``: The dictionary of keyword arguments captured from the URL
 892          pattern that served the view.
 893
 894RedirectView
 895~~~~~~~~~~~~
 896.. class:: RedirectView()
 897
 898    Redirects to a given URL.
 899
 900    The given URL may contain dictionary-style string formatting, which will be
 901    interpolated against the parameters captured in the URL. Because keyword
 902    interpolation is *always* done (even if no arguments are passed in), any
 903    ``"%"`` characters in the URL must be written as ``"%%"`` so that Python
 904    will convert them to a single percent sign on output.
 905
 906    If the given URL is ``None``, Django will return an ``HttpResponseGone``
 907    (410).
 908
 909    .. attribute:: url
 910
 911        The URL to redirect to, as a string. Or ``None`` to raise a 410 (Gone)
 912        HTTP error.
 913
 914    .. attribute:: permanent
 915
 916        Whether the redirect should be permanent. The only difference here is
 917        the HTTP status code returned. If ``True``, then the redirect will use
 918        status code 301. If ``False``, then the redirect will use status code
 919        302. By default, ``permanent`` is ``True``.
 920
 921    .. attribute:: query_string
 922
 923        Whether to pass along the GET query string to the new location. If
 924        ``True``, then the query string is appended to the URL. If ``False``,
 925        then the query string is discarded. By default, ``query_string`` is
 926        ``False``.
 927
 928    .. method:: get_redirect_url(**kwargs)
 929
 930        Constructs the target URL for redirection.
 931
 932        The default implementation uses :attr:`~RedirectView.url` as a starting
 933        string, performs expansion of ``%`` parameters in that string, as well
 934        as the appending of query string if requested by
 935        :attr:`~RedirectView.query_string`. Subclasses may implement any
 936        behavior they wish, as long as the method returns a redirect-ready URL
 937        string.
 938
 939Detail views
 940------------
 941
 942.. currentmodule:: django.views.generic.detail
 943
 944DetailView
 945~~~~~~~~~~
 946.. class:: BaseDetailView()
 947.. class:: DetailView()
 948
 949    A page representing an individual object.
 950
 951    While this view is executing, ``self.object`` will contain the object that
 952    the view is operating upon.
 953
 954    :class:`~django.views.generic.base.BaseDetailView` implements the same
 955    behavior as :class:`~django.views.generic.base.DetailView`, but doesn't
 956    include the
 957    :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`.
 958
 959    **Mixins**
 960
 961      * :class:`django.views.generic.detail.SingleObjectMixin`
 962      * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
 963
 964List views
 965----------
 966
 967.. currentmodule:: django.views.generic.list
 968
 969ListView
 970~~~~~~~~
 971.. class:: BaseListView()
 972.. class:: ListView()
 973
 974    A page representing a list of objects.
 975
 976    While this view is executing, ``self.object_list`` will contain the list of
 977    objects (usually, but not necessarily a queryset) that the view is
 978    operating upon.
 979
 980    :class:`~django.views.generic.list.BaseListView` implements the same
 981    behavior as :class:`~django.views.generic.list.ListView`, but doesn't
 982    include the
 983    :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
 984
 985    **Mixins**
 986
 987      * :class:`django.views.generic.list.MultipleObjectMixin`
 988      * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
 989
 990
 991Editing views
 992-------------
 993
 994.. currentmodule:: django.views.generic.edit
 995
 996FormView
 997~~~~~~~~
 998.. class:: BaseFormView()
 999.. class:: FormView()
1000
1001    A view that displays a form. On error, redisplays the form with validation
1002    errors; on success, redirects to a new URL.
1003
1004    :class:`~django.views.generic.edit.BaseFormView` implements the same
1005    behavior as :class:`~django.views.generic.edit.FormView`, but doesn't
1006    include the :class:`~django.views.generic.base.TemplateResponseMixin`.
1007
1008    **Mixins**
1009
1010      * :class:`django.views.generic.edit.FormMixin`
1011      * :class:`django.views.generic.edit.ProcessFormView`
1012
1013CreateView
1014~~~~~~~~~~
1015.. class:: BaseCreateView()
1016.. class:: CreateView()
1017
1018    A view that displays a form for creating an object, redisplaying the form
1019    with validation errors (if there are any) and saving the object.
1020
1021    :class:`~django.views.generic.edit.BaseCreateView` implements the same
1022    behavior as :class:`~django.views.generic.edit.CreateView`, but doesn't
1023    include the :class:`~django.views.generic.base.TemplateResponseMixin`.
1024
1025    **Mixins**
1026
1027      * :class:`django.views.generic.edit.ModelFormMixin`
1028      * :class:`django.views.generic.edit.ProcessFormView`
1029
1030UpdateView
1031~~~~~~~~~~
1032.. class:: BaseUpdateView()
1033.. class:: UpdateView()
1034
1035    A view that displays a form for editing an existing object, redisplaying
1036    the form with validation errors (if there are any) and saving changes to
1037    the object. This uses a form automatically generated from the object's
1038    model class (unless a form class is manually specified).
1039
1040    :class:`~django.views.generic.edit.BaseUpdateView` implements the same
1041    behavior as :class:`~django.views.generic.edit.UpdateView`, but doesn't
1042    include the :class:`~django.views.generic.base.TemplateResponseMixin`.
1043
1044    **Mixins**
1045
1046      * :class:`django.views.generic.edit.ModelFormMixin`
1047      * :class:`django.views.generic.edit.ProcessFormView`
1048
1049DeleteView
1050~~~~~~~~~~
1051.. class:: BaseDeleteView()
1052.. class:: DeleteView()
1053
1054    A view that displays a confirmation page and deletes an existing object.
1055    The given object will only be deleted if the request method is ``POST``. If
1056    this view is fetched via ``GET``, it will display a confirmation page that
1057    should contain a form that POSTs to the same URL.
1058
1059    :class:`~django.views.generic.edit.BaseDeleteView` implements the same
1060    behavior as :class:`~django.views.generic.edit.DeleteView`, but doesn't
1061    include the :class:`~django.views.generic.base.TemplateResponseMixin`.
1062
1063    **Mixins**
1064
1065      * :class:`django.views.generic.edit.DeletionMixin`
1066      * :class:`django.views.generic.detail.BaseDetailView`
1067
1068    **Notes**
1069
1070       * The delete confirmation page displayed to a GET request uses a
1071         ``template_name_suffix`` of ``'_confirm_delete'``.
1072
1073Date-based views
1074----------------
1075
1076Date-based generic views (in the module :mod:`django.views.generic.dates`)
1077are views for displaying drilldown pages for date-based data.
1078
1079.. currentmodule:: django.views.generic.dates
1080
1081ArchiveIndexView
1082~~~~~~~~~~~~~~~~
1083.. class:: BaseArchiveIndexView()
1084.. class:: ArchiveIndexView()
1085
1086    A top-level index page showing the "latest" objects, by date. Objects with
1087    a date in the *future* are not included unless you set ``allow_future`` to
1088    ``True``.
1089
1090    :class:`~django.views.generic.dates.BaseArchiveIndexView` implements the
1091    same behavior as :class:`~django.views.generic.dates.ArchiveIndexView`, but
1092    doesn't include the
1093    :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
1094
1095    **Mixins**
1096
1097        * :class:`django.views.generic.dates.BaseDateListView`
1098        * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
1099
1100    **Notes**
1101
1102        * Uses a default ``context_object_name`` of ``latest``.
1103        * Uses a default ``template_name_suffix`` of ``_archive``.
1104
1105YearArchiveView
1106~~~~~~~~~~~~~~~
1107.. class:: BaseYearArchiveView()
1108.. class:: YearArchiveView()
1109
1110    A yearly archive page showing all available months in a given year. Objects
1111    with a date in the *future* are not displayed unless you set
1112    ``allow_future`` to ``True``.
1113
1114    :class:`~django.views.generic.dates.BaseYearArchiveView` implements the
1115    same behavior as :class:`~django.views.generic.dates.YearArchiveView`, but
1116    doesn't include the
1117    :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
1118
1119    **Mixins**
1120
1121        * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
1122        * :class:`django.views.generic.dates.YearMixin`
1123        * :class:`django.views.generic.dates.BaseDateListView`
1124
1125    .. attribute:: make_object_list
1126
1127        A boolean specifying whether to retrieve the full list of objects for
1128        this year and pass those to the template. If ``True``, the list of
1129        objects will be made available to the context. By default, this is
1130        ``False``.
1131
1132    .. method:: get_make_object_list()
1133
1134        Determine if an object list will be returned as part of the context. If
1135        ``False``, the ``None`` queryset will be used as the object list.
1136
1137    **Context**
1138
1139    In addition to the context provided by
1140    :class:`django.views.generic.list.MultipleObjectMixin` (via
1141    :class:`django.views.generic.dates.BaseDateListView`), the template's
1142    context will be:
1143
1144        * ``date_list``: A ``DateQuerySet`` object containing all months that
1145          have objects available according to ``queryset``, represented as
1146          ``datetime.datetime`` objects, in ascending order.
1147
1148        * ``year``: The given year, as a four-character string.
1149
1150    **Notes**
1151
1152        * Uses a default ``template_name_suffix`` of ``_archive_year``.
1153
1154MonthArchiveView
1155~~~~~~~~~~~~~~~~
1156.. class:: BaseMonthArchiveView()
1157.. class:: MonthArchiveView()
1158
1159    A monthly archive page showing all objects in a given month. Objects with a
1160    date in the *future* are not displayed unless you set ``allow_future`` to
1161    ``True``.
1162
1163    :class:`~django.views.generic.dates.BaseMonthArchiveView` implements
1164    the same behavior as
1165    :class:`~django.views.generic.dates.MonthArchiveView`, but doesn't
1166    include the
1167    :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
1168
1169    **Mixins**
1170
1171        * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
1172        * :class:`django.views.generic.dates.YearMixin`
1173        * :class:`django.views.generic.dates.MonthMixin`
1174        * :class:`django.views.generic.dates.BaseDateListView`
1175
1176    **Context**
1177
1178    In addition to the context provided by
1179    :class:`~django.views.generic.list.MultipleObjectMixin` (via
1180    :class:`~django.views.generic.dates.BaseDateListView`), the template's
1181    context will be:
1182
1183        * ``date_list``: A ``DateQuerySet`` object containing all days that
1184          have objects available in the given month, according to ``queryset``,
1185          represented as ``datetime.datetime`` objects, in ascending order.
1186
1187        * ``month``: A ``datetime.date`` object representing the given month.
1188
1189        * ``next_month``: A ``datetime.date`` object representing the first day
1190          of the next month. If the next month is in the future, this will be
1191          ``None``.
1192
1193        * ``previous_month``: A ``datetime.date`` object representing the first
1194          day of the previous month. Unlike ``next_month``, this will never be
1195          ``None``.
1196
1197    **Notes**
1198
1199        * Uses a default ``template_name_suffix`` of ``_archive_month``.
1200
1201WeekArchiveView
1202~~~~~~~~~~~~~~~
1203.. class:: BaseWeekArchiveView()
1204.. class:: WeekArchiveView()
1205
1206    A weekly archive page showing all objects in a given week. Objects with a
1207    date in the *future* are not displayed unless you set ``allow_future`` to
1208    ``True``.
1209
1210    :class:`~django.views.generic.dates.BaseWeekArchiveView` implements the
1211    same behavior as :class:`~django.views.generic.dates.WeekArchiveView`, but
1212    doesn't include the
1213    :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
1214
1215    **Mixins**
1216
1217        * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
1218        * :class:`django.views.generic.dates.YearMixin`
1219        * :class:`django.views.generic.dates.MonthMixin`
1220        * :class:`django.views.generic.dates.BaseDateListView`
1221
1222    **Context**
1223
1224    In addition to the context provided by
1225    :class:`~django.views.generic.list.MultipleObjectMixin` (via
1226    :class:`~django.views.generic.dates.BaseDateListView`), the template's
1227    context will be:
1228
1229        * ``week``: A ``datetime.date`` object representing the first day of
1230          the given week.
1231
1232    **Notes**
1233
1234        * Uses a default ``template_name_suffix`` of ``_archive_week``.
1235
1236DayArchiveView
1237~~~~~~~~~~~~~~
1238.. class:: BaseDayArchiveView()
1239.. class:: DayArchiveView()
1240
1241    A day archive page showing all objects in a given day. Days in the future
1242    throw a 404 error, regardless of whether any objects exist for future days,
1243    unless you set ``allow_future`` to ``True``.
1244
1245    :class:`~django.views.generic.dates.BaseDayArchiveView` implements the same
1246    behavior as :class:`~django.views.generic.dates.DayArchiveView`, but
1247    doesn't include the
1248    :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
1249
1250    **Mixins**
1251
1252        * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
1253        * :class:`django.views.generic.dates.YearMixin`
1254        * :class:`django.views.generic.dates.MonthMixin`
1255        * :class:`django.views.generic.dates.DayMixin`
1256        * :class:`django.views.generic.dates.BaseDateListView`
1257
1258    **Context**
1259
1260    In addition to the context provided by
1261    :class:`~django.views.generic.list.MultipleObjectMixin` (via
1262    :class:`~django.views.generic.dates.BaseDateListView`), the template's
1263    context will be:
1264
1265        * ``day``: A ``datetime.date`` object representing the given day.
1266
1267        * ``next_day``: A ``datetime.date`` object representing the next day.
1268          If the next day is in the future, this will be ``None``.
1269
1270        * ``previous_day``: A ``datetime.date`` object representing the
1271          previous day. Unlike ``next_day``, this will never be ``None``.
1272
1273        * ``next_month``: A ``datetime.date`` object representing the first day
1274          of the next month. If the next month is in the future, this will be
1275          ``None``.
1276
1277        * ``previous_month``: A ``datetime.date`` object representing the first
1278          day of the previous month. Unlike ``next_month``, this will never be
1279          ``None``.
1280
1281    **Notes**
1282
1283        * Uses a default ``template_name_suffix`` of ``_archive_day``.
1284
1285TodayArchiveView
1286~~~~~~~~~~~~~~~~
1287.. class:: BaseTodayArchiveView()
1288.. class:: TodayArchiveView()
1289
1290    A day archive page showing all objects for *today*. This is exactly the
1291    same as ``archive_day``, except the ``year``/``month``/``day`` arguments
1292    are not used,
1293
1294    :class:`~django.views.generic.dates.BaseTodayArchiveView` implements the
1295    same behavior as :class:`~django.views.generic.dates.TodayArchiveView`, but
1296    doesn't include the
1297    :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
1298
1299    **Mixins**
1300
1301        * :class:`django.views.generic.dates.DayArchiveView`
1302
1303DateDetailView
1304~~~~~~~~~~~~~~
1305.. class:: BaseDateDetailView()
1306.. class:: DateDetailView()
1307
1308    A page representing an individual object. If the object has a date value in
1309    the future, the view will throw a 404 error by default, unless you set
1310    ``allow_future`` to ``True``.
1311
1312    :class:`~django.views.generic.dates.BaseDateDetailView` implements the same
1313    behavior as :class:`~django.views.generic.dates.DateDetailView`, but
1314    doesn't include the
1315    :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`.
1316
1317    **Mixins**
1318
1319        * :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
1320        * :class:`django.views.generic.dates.YearMixin`
1321        * :class:`django.views.generic.dates.MonthMixin`
1322        * :class:`django.views.generic.dates.DayMixin`
1323        * :class:`django.views.generic.dates.BaseDateListView`