Funções de atalho do Django

O pacote django.shortcuts agrega funções e classes auxiliares que “abrangem” múltiplos níveis do MVC. Em outras palavras, essas funções/classes introduzem uma composição controlada por uma questão de conveniência.

render()

render(request, template_name, context=None, content_type=None, status=None, using=None)[código-fonte]

Combina uma dado template com um dado dicionário de dados e retorna um objeto HttpResponse com aquele texto renderizado.

O Django não fornece um atalho de função o qual retorna uma TemplateResponse porque o construtor da TemplateResponse oferece o mesmo nível de facilidade que o render().

Argumentos requeridos

request

O objeto de requisição usado para gerar esta resposta.

template_name

O nome completo do template a ser usado ou uma sequência de nomes de templates. Se uma sequência é dada, o primeiro template que existir será usado. Veja a documentação de carga de templates para maiores informações de como os templates são encontrados.

Argumentos opcionais

context

Um dicionário de valores que são adicionados ao contexto do template. Por padrao, é um dicionário vazio. Se um valor neste dicionário é um executável, a “view” irá executá-lo logo antes de renderizar o template.

content_type

The MIME type to use for the resulting document. Defaults to 'text/html'.

status

O código de status da resposta. Padrão é 200.

using

O NAME do mecanismo de template a ser usado para a carga do template.

Exemplo

O exemplo seguinte renderiza o template myapp/index.html com o tipo MIME application/xhtml+xml:

from django.shortcuts import render


def my_view(request):
    # View code here...
    return render(
        request,
        "myapp/index.html",
        {
            "foo": "bar",
        },
        content_type="application/xhtml+xml",
    )

Este exemplo é equivalente a:

from django.http import HttpResponse
from django.template import loader


def my_view(request):
    # View code here...
    t = loader.get_template("myapp/index.html")
    c = {"foo": "bar"}
    return HttpResponse(t.render(c, request), content_type="application/xhtml+xml")

redirect()

redirect(to, *args, permanent=False, preserve_request=False, **kwargs)[código-fonte]

Retorna uma HttpResponseRedirect para a URL apropriada de acordo com os argumentos passados.

Os argumentos podem ser:

  • Um modelo: a função get_absolute_url() do modelo será chamada.

  • Um nome de uma “view”, possivelmente com argumentos: a reverse() será usada para resolver inversamente o nome

  • Uma URL absoluta ou relativa, a qual será usada como tal para o local do redirecionamento.

By default, a temporary redirect is issued with a 302 status code. If permanent=True, a permanent redirect is issued with a 301 status code.

If preserve_request=True, the response instructs the user agent to preserve the method and body of the original request when issuing the redirect. In this case, temporary redirects use a 307 status code, and permanent redirects use a 308 status code. This is better illustrated in the following table:

permanent

preserve_request

HTTP status code

True

False

301

False

False

302

False

True

307

True

True

308

Changed in Django 5.2:

The argument preserve_request was added.

Exemplos

Você pode usar a função redirect() de várias maneiras.

  1. Passando algum objeto; o método get_absolute_url() daquele objeto será chamado para descobrir a URL de redirecionamento:

    from django.shortcuts import redirect
    
    
    def my_view(request):
        ...
        obj = MyModel.objects.get(...)
        return redirect(obj)
    
  2. Passando o nome de uma “view” e opcionalmente algum argumento posicional ou nomeado; a URL será inversamente resolvida usando o método reverse()

    def my_view(request):
        ...
        return redirect("some-view-name", foo="bar")
    
  3. By passing a hardcoded URL to redirect to:

    def my_view(request):
        ...
        return redirect("/some/url/")
    

    This also works with full URLs:

    def my_view(request):
        ...
        return redirect("https://example.com/")
    

Por padrão, a redirect() retorna um redirecionamento temporário. Todas as formas acima aceitam um argumento chamado permanent; se definido como True um redirecionamento permanente será retornado:

def my_view(request):
    ...
    obj = MyModel.objects.get(...)
    return redirect(obj, permanent=True)

Additionally, the preserve_request argument can be used to preserve the original HTTP method:

def my_view(request):
    # ...
    obj = MyModel.objects.get(...)
    if request.method in ("POST", "PUT"):
        # Redirection preserves the original request method.
        return redirect(obj, preserve_request=True)
    # ...

get_object_or_404()

get_object_or_404(klass, *args, **kwargs)[código-fonte]
aget_object_or_404(klass, *args, **kwargs)

Asynchronous version: aget_object_or_404()

Chama o get() de um dado “manager” de modelo, mas emiti um Http404 no lugar de uma exceção DoesNotExist do modelo.

Argumentos

klass

Uma classe Model, um Manager, ou uma instância de QuerySet da qual pegar o objeto.

*args

Q objects.

**kwargs

Parâmetros de filtro, o quais devem estar no mesmo formato que os aceito por get() e filter().

Exemplo

O exemplo seguinte pega o objeto do modelo MyModel e com chave-primária igual a 1:

from django.shortcuts import get_object_or_404


def my_view(request):
    obj = get_object_or_404(MyModel, pk=1)

Este exemplo é equivalente a:

from django.http import Http404


def my_view(request):
    try:
        obj = MyModel.objects.get(pk=1)
    except MyModel.DoesNotExist:
        raise Http404("No MyModel matches the given query.")

O caso de uso mais comum é passar uma Model, como mostrado acima. Porém, você pode também passar uma instância de QuerySet:

queryset = Book.objects.filter(title__startswith="M")
get_object_or_404(queryset, pk=1)

O exemplo acima é um pouco exagerado já que é equivalente a fazer:

get_object_or_404(Book, title__startswith="M", pk=1)

mas pode ser útil se você estiver passando uma varável queryset vinda de algum outro lugar.

E fInalmente, você pode usar uma Manager. Isso é útil por exemplo quando você tem uma custom manager:

get_object_or_404(Book.dahl_objects, title="Matilda")

Você pode usar também uma "Manager"/s relacionados:

author = Author.objects.get(name="Roald Dahl")
get_object_or_404(author.book_set, title="Matilda")

Nota: Assimcomo o get(), uma exceção do tipo MultipleObjectsReturned será emitida se mais de um objeto for encontrado..

get_list_or_404()

get_list_or_404(klass, *args, **kwargs)[código-fonte]
aget_list_or_404(klass, *args, **kwargs)

Asynchronous version: aget_list_or_404()

Retorna o resultado de filter() de um dado “manager” de modelo como uma lista (cast), emitindo um Http404 se a lista estiver vazia.

Argumentos

klass

Uma instância Model, Manager ou de QuerySet da qual ler a lista.

*args

Q objects.

**kwargs

Parâmetros de filtro, o quais devem estar no mesmo formato que os aceito por get() e filter().

Exemplo

O exemplo seguinte pega todos os objetos publicados do MyModel:

from django.shortcuts import get_list_or_404


def my_view(request):
    my_objects = get_list_or_404(MyModel, published=True)

Este exemplo é equivalente a:

from django.http import Http404


def my_view(request):
    my_objects = list(MyModel.objects.filter(published=True))
    if not my_objects:
        raise Http404("No MyModel matches the given query.")