==========

Base views

==========

The following three classes provide much of the functionality needed to create

Django views. You may think of them as *parent* views, which can be used by

themselves or inherited from. They may not provide all the capabilities

required for projects, in which case there are Mixins and Generic class-based

views.

Many of Django's built-in class-based views inherit from other class-based

views or various mixins. Because this inheritance chain is very important, the

ancestor classes are  documented under the section title of **Ancestors (MRO)**.

MRO is an acronym for Method Resolution Order.

``View``

========

.. class:: django.views.generic.base.View

    The base view class. All other class-based views inherit from this base

    class. It isn't strictly a generic view and thus can also be imported from

    ``django.views``.

    **Method Flowchart**

    #. :meth:`setup()`

    #. :meth:`dispatch()`

    #. :meth:`http_method_not_allowed()`

    #. :meth:`options()`

    **Example views.py**::

        from django.http import HttpResponse

        from django.views import View

        class MyView(View):

            def get(self, request, *args, **kwargs):

                return HttpResponse('Hello, World!')

    **Example urls.py**::

        from django.urls import path

        from myapp.views import MyView

        urlpatterns = [

            path('mine/', MyView.as_view(), name='my-view'),

        ]

    **Attributes**

    .. attribute:: http_method_names

        The list of HTTP method names that this view will accept.

        Default::

            ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace']

    **Methods**

    .. classmethod:: as_view(**initkwargs)

        Returns a callable view that takes a request and returns a response::

            response = MyView.as_view()(request)

        The returned view has ``view_class`` and ``view_initkwargs``

        attributes.

        When the view is called during the request/response cycle, the

        :meth:`setup` method assigns the :class:`~django.http.HttpRequest` to

        the view's ``request`` attribute, and any positional and/or keyword

        arguments :ref:`captured from the URL pattern

        <how-django-processes-a-request>` to the ``args`` and ``kwargs``

        attributes, respectively. Then :meth:`dispatch` is called.

        If a ``View`` subclass defines asynchronous (``async def``) method

        handlers, ``as_view()`` will mark the returned callable as a coroutine

        function. An ``ImproperlyConfigured`` exception will be raised if both

        asynchronous (``async def``) and synchronous (``def``) handlers are

        defined on a single view-class.

        .. versionchanged:: 4.1

            Compatibility with asynchronous (``async def``) method handlers was

            added.

    .. method:: setup(request, *args, **kwargs)

        Performs key view initialization prior to :meth:`dispatch`.

        If overriding this method, you must call ``super()``.

    .. method:: dispatch(request, *args, **kwargs)

        The ``view`` part of the view -- the method that accepts a ``request``

        argument plus arguments, and returns an HTTP response.

        The default implementation will inspect the HTTP method and attempt to

        delegate to a method that matches the HTTP method; a ``GET`` will be

        delegated to ``get()``, a ``POST`` to ``post()``, and so on.

        By default, a ``HEAD`` request will be delegated to ``get()``.

        If you need to handle ``HEAD`` requests in a different way than ``GET``,

        you can override the ``head()`` method. See

        :ref:`supporting-other-http-methods` for an example.

    .. method:: http_method_not_allowed(request, *args, **kwargs)

        If the view was called with an HTTP method it doesn't support, this

        method is called instead.

        The default implementation returns ``HttpResponseNotAllowed`` with a

        list of allowed methods in plain text.

    .. method:: options(request, *args, **kwargs)

        Handles responding to requests for the OPTIONS HTTP verb. Returns a

        response with the ``Allow`` header containing a list of the view's

        allowed HTTP method names.

        If the other HTTP methods handlers on the class are asynchronous

        (``async def``) then the response will be wrapped in a coroutine

        function for use with ``await``.

        .. versionchanged:: 4.1

            Compatibility with classes defining asynchronous (``async def``)

            method handlers was added.

``TemplateView``

================

.. class:: django.views.generic.base.TemplateView

    Renders a given template, with the context containing parameters captured

    in the URL.

    **Ancestors (MRO)**

    This view inherits methods and attributes from the following views:

    * :class:`django.views.generic.base.TemplateResponseMixin`

    * :class:`django.views.generic.base.ContextMixin`

    * :class:`django.views.generic.base.View`

    **Method Flowchart**

    #. :meth:`~django.views.generic.base.View.setup()`

    #. :meth:`~django.views.generic.base.View.dispatch()`

    #. :meth:`~django.views.generic.base.View.http_method_not_allowed()`

    #. :meth:`~django.views.generic.base.ContextMixin.get_context_data()`

    **Example views.py**::

        from django.views.generic.base import TemplateView

        from articles.models import Article

        class HomePageView(TemplateView):

            template_name = "home.html"

            def get_context_data(self, **kwargs):

                context = super().get_context_data(**kwargs)

                context['latest_articles'] = Article.objects.all()[:5]

                return context

    **Example urls.py**::

        from django.urls import path

        from myapp.views import HomePageView

        urlpatterns = [

            path('', HomePageView.as_view(), name='home'),

        ]

    **Context**

    * Populated (through :class:`~django.views.generic.base.ContextMixin`) with

      the keyword arguments captured from the URL pattern that served the view.

    * You can also add context using the

      :attr:`~django.views.generic.base.ContextMixin.extra_context` keyword

      argument for :meth:`~django.views.generic.base.View.as_view`.

``RedirectView``

================

.. class:: django.views.generic.base.RedirectView

    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).

    **Ancestors (MRO)**

    This view inherits methods and attributes from the following view:

    * :class:`django.views.generic.base.View`

    **Method Flowchart**

    #. :meth:`~django.views.generic.base.View.setup()`

    #. :meth:`~django.views.generic.base.View.dispatch()`

    #. :meth:`~django.views.generic.base.View.http_method_not_allowed()`

    #. :meth:`get_redirect_url()`

    **Example views.py**::

        from django.shortcuts import get_object_or_404

        from django.views.generic.base import RedirectView

        from articles.models import Article

        class ArticleCounterRedirectView(RedirectView):

            permanent = False

            query_string = True

            pattern_name = 'article-detail'

            def get_redirect_url(self, *args, **kwargs):

                article = get_object_or_404(Article, pk=kwargs['pk'])

                article.update_counter()

                return super().get_redirect_url(*args, **kwargs)

    **Example urls.py**::

        from django.urls import path

        from django.views.generic.base import RedirectView

        from article.views import ArticleCounterRedirectView, ArticleDetailView

        urlpatterns = [

            path('counter/<int:pk>/', ArticleCounterRedirectView.as_view(), name='article-counter'),

            path('details/<int:pk>/', ArticleDetailView.as_view(), name='article-detail'),

            path('go-to-django/', RedirectView.as_view(url='https://www.djangoproject.com/'), name='go-to-django'),

        ]

    **Attributes**

    .. attribute:: url

        The URL to redirect to, as a string. Or ``None`` to raise a 410 (Gone)

        HTTP error.

    .. attribute:: pattern_name

        The name of the URL pattern to redirect to. Reversing will be done

        using the same args and kwargs as are passed in for this view.

    .. attribute:: 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 ``False``.

    .. attribute:: query_string

        Whether to pass along the GET query string to the new location. If

        ``True``, then the query string is appended to the URL. If ``False``,

        then the query string is discarded. By default, ``query_string`` is

        ``False``.

    **Methods**

    .. method:: get_redirect_url(*args, **kwargs)

        Constructs the target URL for redirection.

        The ``args`` and ``kwargs`` arguments are positional and/or keyword

        arguments :ref:`captured from the URL pattern

        <how-django-processes-a-request>`, respectively.

        The default implementation uses :attr:`url` as a starting

        string and performs expansion of ``%`` named parameters in that string

        using the named groups captured in the URL.

        If :attr:`url` is not set, ``get_redirect_url()`` tries to reverse the

        :attr:`pattern_name` using what was captured in the URL (both named and

        unnamed groups are used).

        If requested by :attr:`query_string`, it will also append the query

        string to the generated URL.

        Subclasses may implement any behavior they wish, as long as the method

        returns a redirect-ready URL string.