# Documentação Django 5.2.8

# Django em um relance

Como o Django foi desenvolvido no ambiente movimentado de uma redação, ele foi desenhado para tornar as tarefas comuns do desenvolvimento web rápidas e fáceis. Aqui está uma visão informal sobre como escrever uma aplicação Web dirigida a banco de dados com Django.

O objetivo deste documento é dar a você as especificações técnicas necessárias para entender como o Django funciona, mas este texto não pretende ser um tutorial ou uma referência – mas possuímos os dois! Quando você estiver pronto para iniciar um projeto, você pode iniciar com o tutorial ou mergulhar direto em uma documentação mais detalhada.

## Projete o seu model

Embora você possa usar o Django sem um banco de dados, ele vem com um mapeador objeto-relacional no qual você descreve o layout do seu banco de dados em código Python.

A sintaxe do modelo de dados oferece muitas formas ricas de representar seus modelos – portanto, está resolvendo muitos anos de problemas com esquemas de banco de dados. Aqui está um exemplo rápido:

`news/models.py`

    from django.db import models

    class Reporter(models.Model):
        full_name = models.CharField(max_length=70)

        def __str__(self):
            return self.full_name

    class Article(models.Model):
        pub_date = models.DateField()
        headline = models.CharField(max_length=200)
        content = models.TextField()
        reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)

        def __str__(self):
            return self.headline

## Instale-o

A seguir, execute o utilitário de linha de comando do Django para criar as tabelas do banco de dados automaticamente:

/ 

    $ python manage.py makemigrations
    $ python manage.py migrate

    ...\> py manage.py makemigrations
    ...\> py manage.py migrate

O comando `makemigrations` procura por todos os seus modelos disponíveis e cria migrações para cada tabela que ainda não exista. Já o comando `migrate` executa as migrações e cria as tabelas em seu banco de dados, bem como, opcionalmente, fornece um controle muito mais rico do seu esquema de dados.

## Aproveite a API livre

Com ela você terá uma API Python livre e rica para acessar seus dados. A API é criada em tempo de execução, nenhuma geração de código é necessária:

    # Import the models we created from our "news" app
    >>> from news.models import Article, Reporter

    # No reporters are in the system yet.
    >>> Reporter.objects.all()
    <QuerySet []>

    # Create a new Reporter.
    >>> r = Reporter(full_name="John Smith")

    # Save the object into the database. You have to call save() explicitly.
    >>> r.save()

    # Now it has an ID.
    >>> r.id
    1

    # Now the new reporter is in the database.
    >>> Reporter.objects.all()
    <QuerySet [<Reporter: John Smith>]>

    # Fields are represented as attributes on the Python object.
    >>> r.full_name
    'John Smith'

    # Django provides a rich database lookup API.
    >>> Reporter.objects.get(id=1)
    <Reporter: John Smith>
    >>> Reporter.objects.get(full_name__startswith="John")
    <Reporter: John Smith>
    >>> Reporter.objects.get(full_name__contains="mith")
    <Reporter: John Smith>
    >>> Reporter.objects.get(id=2)
    Traceback (most recent call last):
        ...
    DoesNotExist: Reporter matching query does not exist.

    # Create an article.
    >>> from datetime import date
    >>> a = Article(
    ...     pub_date=date.today(), headline="Django is cool", content="Yeah.", reporter=r
    ... )
    >>> a.save()

    # Now the article is in the database.
    >>> Article.objects.all()
    <QuerySet [<Article: Django is cool>]>

    # Article objects get API access to related Reporter objects.
    >>> r = a.reporter
    >>> r.full_name
    'John Smith'

    # And vice versa: Reporter objects get API access to Article objects.
    >>> r.article_set.all()
    <QuerySet [<Article: Django is cool>]>

    # The API follows relationships as far as you need, performing efficient
    # JOINs for you behind the scenes.
    # This finds all articles by a reporter whose name starts with "John".
    >>> Article.objects.filter(reporter__full_name__startswith="John")
    <QuerySet [<Article: Django is cool>]>

    # Change an object by altering its attributes and calling save().
    >>> r.full_name = "Billy Goat"
    >>> r.save()

    # Delete an object with delete().
    >>> r.delete()

## Uma interface de administração dinâmica: não se trata apenas de andaimes - é toda a casa.

Uma vez que seus modelos estejam definidos, Django pode automaticamente criar uma interface de administração profissional pronta para produção – um website que permite a usuários autenticados adicionarem, alterarem e removerem objetos. O único passo necessário é registrar seu modelo no site de administração:

`news/models.py`

    from django.db import models

    class Article(models.Model):
        pub_date = models.DateField()
        headline = models.CharField(max_length=200)
        content = models.TextField()
        reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)

`news/admin.py`

    from django.contrib import admin

    from . import models

    admin.site.register(models.Article)

A filosofia aqui é que seu site é editado por uma equipe, ou um cliente, ou talvez apenas por você – e você não quer ter que lidar com criação de interfaces apenas para gerenciar conteúdo.

Um fluxo de trabalho típico na criação de aplicações Django é criar os modelos e ter os sites de administração rodando o mais rápido possível, assim sua equipe (ou cliente) poderá começar a inserir os dados. Em seguida, desenvolve-se a forma com que os dados serão apresentados ao público.

## Projete suas URLs

Um esquema limpo e elegante de URL’s é um detalhe importante em uma aplicação web de alta qualidade. O Django encoraja o desenho de belíssimas URLs e não coloca nenhuma sujeira nelas, como `.php` ou `.asp`.

Para projetar URLs para uma aplicação, você cria um módulo Python que chamamos de URLconf. Uma tabela de conteúdos para sua aplicação, contendo um mapeamento entre padrões de URL e funções Python. URLconfs também servem para desacoplar as URLs do código Python.

Aqui está como um URLconf se aparentaria para o exemplo `Reporter`/`Article` acima:

`news/urls.py`

    from django.urls import path

    from . import views

    urlpatterns = [
        path("articles/<int:year>/", views.year_archive),
        path("articles/<int:year>/<int:month>/", views.month_archive),
        path("articles/<int:year>/<int:month>/<int:pk>/", views.article_detail),
    ]

O código acima mapeia URLs, como simples expressões regulares, para a localização das funções Python de retorno (“views”). As strings dos caminhos usam tags (valores entre <>) de parâmetros para “capturar” valores das URLs. Quando um usuário requisita uma página, o Django percorre cada padrão, em ordem, e para no primeiro que casa com a URL requisitada. (Se nenhum deles combinar o Django executa uma view especial de exceção 404.) Isso é incrivelmente rápido, porque os caminhos são compilados em expressões regulares.

Uma vez que um dos padrões de URL corresponda, o Django chama a view fornecida, que é uma função Python. Cada view recebe um objeto request – que contém os metadados da solicitação – e os valores capturados no padrão.

Por exemplo, se um usuário solicita a URL “/articles/2005/05/39323/”, Django chamaria a função `news.views.article_detail(request, year=2005, month=5, pk=39323)`.

## Escreva suas views

Cada view é responsável por fazer uma entre duas coisas: Devolver um objeto `HttpResponse` contendo o conteúdo para a página requisitada, ou levantar uma exceção como `Http404`. O resto é com você.

Geralmente, uma view recupera dados de acordo com os parâmetros, carrega um template e renderiza o template com os dados recuperados. Aqui está uma view para o `year_archive` do exemplo acima:

`news/views.py`

    from django.shortcuts import render

    from .models import Article

    def year_archive(request, year):
        a_list = Article.objects.filter(pub_date__year=year)
        context = {"year": year, "article_list": a_list}
        return render(request, "news/year_archive.html", context)

Esse exemplo usa o sistema de template do Django, o qual possui diversos recursos poderosos mas prima por permanecer simples o suficiente para que não-programadores possam usá-lo.

## Projete seus templates

O código acima carrega o template `news / year_archive.html`.

O Django tem um caminho de pesquisa para templates, o qual permite a você minimizar a redundância entre templates. Nas configurações do Django, você especifica uma lista de diretórios para procurar por templates em `DIRS`. Se um template não existir no primeiro diretório, ele verifica o segundo e assim por diante.

Vamos dizer que o template `news/article_detail.html` foi encontrado. Aqui está como ele deve se parecer:

`news/templates/news/year_archive.html`

    {% extends "base.html" %}

    {% block title %}Articles for {{ year }}{% endblock %}

    {% block content %}
    <h1>Articles for {{ year }}</h1>

    {% for article in article_list %}
        <p>{{ article.headline }}</p>
        <p>By {{ article.reporter.full_name }}</p>
        <p>Published {{ article.pub_date|date:"F j, Y" }}</p>
    {% endfor %}
    {% endblock %}

Variáveis são cercadas por chaves duplas. `{{ article.headline }}` que significa “retorne o valor do atributo headline do artigo”, mas pontos não são usados apenas para acessar atributos: eles também podem acessar chaves de dicionários, acesar índices e chamar funções.

Note que `{{ article.pub_date|date:"F j, Y" }}` usa um “pipe” no estilo Unix (o caractere “|”). Isso é chamado de filtro de template, e é uma forma de filtrar o valor de uma variável. Nesse caso, o filtro “date” formata um objeto Python datetime para um formato dado (como o encontrado na função date do PHP).

Você pode atrelar tantos filtros quanto você quiser. Você pode escrever filtros personalizados. Você pode escrever tags de template personalizadas, que irão executar código Python personalizado por baixo dos panos.

Finalmente, o Django usa o conceito de “herança de templates”: É isso que o `{% extends "base.html" %}` faz. Isso significa “primeiro carregue o template chamado ‘base’, o qual define uma série de blocos, e preencha os blocos com os seguintes blocos”. Resumindo, isso permite a você reduzir drasticamente a redundância em seus templates: cada template tem que definir apenas aquilo que é único para aquele template.

Aqui está como o template “base.html”, incluindo o uso de arquivos estáticos, deve se parecer:

`templates/base.html`

    {% load static %}
    <html lang="en">
    <head>
        <title>{% block title %}{% endblock %}</title>
    </head>
    <body>
        <img src="{% static 'images/sitelogo.png' %}" alt="Logo">
        {% block content %}{% endblock %}
    </body>
    </html>

Simplificadamente, ele define a aparência do site (com o logo do site), e fornece “buracos” para templates filhos preencherem. Isso significa que um redesenho do site pode ser feito alterando um único arquivo - o template base.

Isto também permite criar múltiplas versões de um site, com diferentes templates bases, mas com reuso de templates filhos. Os criadores do Django usaram essa técnica para criar versões mobile do site surpreendentemente diferentes apenas criando um novo template base.

Note que você não tem que usar o sistema de templates do Django se você preferir outro. Enquanto o sistema de templates do Django é particularmente bem integrado com a camada de modelos do Django, nada força você a usá-lo. Da mesma maneira que, você não tem que usar a API de banco de dados do Django, também. Você pode usar outras camadas de abstração de banco de dados, você pode ler arquivos XML, você pode ler arquivos do disco, ou qualquer coisa que desejar. Cada parte do Django – modelos, visões e templates – é desacoplada da próxima.

## Isto é apenas a superfície

Esta foi apenas uma breve visão geral da funcionalidade do Django. Algumas características mais úteis:

- Um framework para caching que se integra com o memcached e outros backends.

- Um framework de distribuição que permite você criar feeds RSS e Atom escrevendo uma pequena classe Python.

- Recursos de administração gerados automaticamente mais atraentes – esta visão geral mal arranhou a superfície.

Os próximos passos são para você baixar o Django, ler:doc:o tutorial </intro/tutorial01> e juntar-se à comunidade. Obrigado pelo seu interesse!