# documentação Django 3.1.9.dev

# Escrevendo “views”

A view function, or view for short, is a Python function that takes a Web request and returns a Web response. This response can be the HTML contents of a Web page, or a redirect, or a 404 error, or an XML document, or an image . . . or anything, really. The view itself contains whatever arbitrary logic is necessary to return that response. This code can live anywhere you want, as long as it’s on your Python path. There’s no other requirement–no “magic,” so to speak. For the sake of putting the code somewhere, the convention is to put views in a file called `views.py`, placed in your project or application directory.

## Uma “view” simples.

Aqui uma “view” que retorna a data e hora corrente, como um documento HTML:

    from django.http import HttpResponse
    import datetime

    def current_datetime(request):
        now = datetime.datetime.now()
        html = "<html><body>It is now %s.</body></html>" % now
        return HttpResponse(html)

Vamos passar por este código linha por linha:

- Primeiro, importamos a classe `HttpResponse` do módulo `django.http`, juntamente com a biblioteca `datetime` do Python.

- Próximo, definimos a função chamada `current_datetime`. Esta a função da “view”. Cada função “view” recebe um objeto `HttpRequest` como seu primeiro argumento, o qual é tipicamente chamado `request`.

  Note que o nome da função “view” não importa, essa não tem que ser nominada de uma certa maniera para que o Django as reconheça. Chamaremos aqui de `current_time`, porque este nome claramente indica o que ela faz.

- A “view” retorna um objeto `HttpResponse` que contém a resposta gerada. Cada função “view” é responsável por retornar um objeto da `HttpResponse`. (existem exceções, mas chegaremos lá mais tarde.)

Fuso Horário do Django

O Django inclui uma definição `TIME_ZONE` cujo padrão é `America/Chicago`. Este provavelmente não é onde você mora, então talvez queira mudar isso no seus arquivo de definições.

## Mapiando URLs para “views”

Então, para recaptular, essa função “view” retorna uma página HTML que inclui a data e hora corrente. Para mostrar esta “view” em uma URL em particular, é necessário criar um URLconf; veja Despachante de URL para instruções.

## Retornando erros

Django provides help for returning HTTP error codes. There are subclasses of `HttpResponse` for a number of common HTTP status codes other than 200 (which means “OK”). You can find the full list of available subclasses in the request/response documentation. Return an instance of one of those subclasses instead of a normal `HttpResponse` in order to signify an error. For example:

    from django.http import HttpResponse, HttpResponseNotFound

    def my_view(request):
        # ...
        if foo:
            return HttpResponseNotFound('<h1>Page not found</h1>')
        else:
            return HttpResponse('<h1>Page was found</h1>')

Não existe uma subclasse especializada para código de resposta HTTP possível, já que muitos deles não são muito comuns. Contudo, como documentado na documentação do `HttpResponse`, você pode também passar o código de status HTTP dentro do construtor para a `HttpResponse` para que crie a classe de retorno para qualquer código de estatus que queira. Por exemplo:

    from django.http import HttpResponse

    def my_view(request):
        # ...

        # Return a "created" (201) response code.
        return HttpResponse(status=201)

Como os erros 404 são de longe o erro HTTP mais comum, existe uma maneira mais fácil de lidar com estes erros.

### A exceção `Http404`

class `django.http.``Http404`

Quando retornar um erro como o `HttpResponseNotFound`, você é responsável por definir o HTML da página de erro resultante:

    return HttpResponseNotFound('<h1>Page not found</h1>')

Por conveniência, e porque é uma boa idéia ter uma página de erro 404 consistente para todo o seu site, o Django fornece uma exceção `Http404`. Se você emitir um `Http404` em qualquer ponto em uma função “view”, o Django irá capturá-la e retornar a página de erro padrão para sua aplicação, juntamente com um código de erro HTTP 404.

Exemplo de uso:

    from django.http import Http404
    from django.shortcuts import render
    from polls.models import Poll

    def detail(request, poll_id):
        try:
            p = Poll.objects.get(pk=poll_id)
        except Poll.DoesNotExist:
            raise Http404("Poll does not exist")
        return render(request, 'polls/detail.html', {'poll': p})

Para que seja mostrado um HTML personalizado quando o Django retornar um 404, você pode criar um “template” HTML chamado `404.htm` e colocá-lo no nível superior da sua árvore de “templates”. Este “template” irá então ser servido quando `DEBUG` está definido como `False`.

Quando `DEBUG` for `True`, você pode fornecer uma mensagem para `Http404` e ela irá aparecer em depuração no “template” 404 padrão. Use estas mensagens para propósitos de depuração; elas geralmente não são adequadas para serem usadas em um template 404 em producão.

## Personalizando “views” de erro

The default error views in Django should suffice for most Web applications, but can easily be overridden if you need any custom behavior. Specify the handlers as seen below in your URLconf (setting them anywhere else will have no effect).

A “view” `page_not_found()` é substituída por `handler404`:

    handler404 = 'mysite.views.my_custom_page_not_found_view'

A “view” `server_error()` é substituída pelo `handler500`:

    handler500 = 'mysite.views.my_custom_error_view'

A “view” `permission_denied()` é substituída pelo `handler403`:

    handler403 = 'mysite.views.my_custom_permission_denied_view'

A “view” `bad_request()` é substituída pelo `handler400`:

    handler400 = 'mysite.views.my_custom_bad_request_view'

Ver também

Use the `CSRF_FAILURE_VIEW` setting to override the CSRF error view.

### Testing custom error views

To test the response of a custom error handler, raise the appropriate exception in a test view. For example:

    from django.core.exceptions import PermissionDenied
    from django.http import HttpResponse
    from django.test import SimpleTestCase, override_settings
    from django.urls import path

    def response_error_handler(request, exception=None):
        return HttpResponse('Error handler content', status=403)

    def permission_denied_view(request):
        raise PermissionDenied

    urlpatterns = [
        path('403/', permission_denied_view),
    ]

    handler403 = response_error_handler

    # ROOT_URLCONF must specify the module that contains handler403 = ...
    @override_settings(ROOT_URLCONF=__name__)
    class CustomErrorHandlerTests(SimpleTestCase):

        def test_handler_renders_template_response(self):
            response = self.client.get('/403/')
            # Make assertions on the response here. For example:
            self.assertContains(response, 'Error handler content', status_code=403)

## Async views

New in Django 3.1.

As well as being synchronous functions, views can also be asynchronous (“async”) functions, normally defined using Python’s `async def` syntax. Django will automatically detect these and run them in an async context. However, you will need to use an async server based on ASGI to get their performance benefits.

Here’s an example of an async view:

    import datetime
    from django.http import HttpResponse

    async def current_datetime(request):
        now = datetime.datetime.now()
        html = '<html><body>It is now %s.</body></html>' % now
        return HttpResponse(html)

You can read more about Django’s async support, and how to best use async views, in Suporte assíncrono.