djangodocs

Django 1.11
Português (Brasil)
Documentation contents

Escrevendo seu primeiro app Django, parte 1

Vamos aprender por um exemplo.

Através deste tutorial, nós vamos caminhar através da criação de uma aplicação básica de enquetes.

Ela irá consistir de duas partes:

  • Uma página pública que permitirá que pessoas vejam as enquetes e votem nelas.

  • Um site de administração que permite adicionar, alterar e deletar enquetes.

We’ll assume you have Django installed already. You can tell Django is installed and which version by running the following command in a shell prompt (indicated by the $ prefix):

Shell
$ python -m django --version

Se o Django estiver instalado, você verá a versão de suas instalçaõ. Se não estiver, você receberá uma mensagem de erro dizendo “No module named django”.

Este tutorial é escrito para Django 1.11 e Python 3.4 ou superior. Se a versão do Django não é a mesma, você referenciar o tutorial par sua versão de Django usando o alterador de versão no canto inferior direito desta página, ou atualizar o Django para a versão mais nova. Se ainda estiver usando python 2.7, é necessário fazer pequenos ajustes nos exemplos de código, como descrito nos comentários.

Veja Como instalar o Django para recomendação sobre como remover versões antigas do Django e instar uma mais recente.

Criando um projeto

Se esta é a primeira vez em que você está utilizando o Django, você terá que preocupar-se com algumas configurações iniciais. Isto é, você precisará auto-gerar um código para iniciar um projeto Django – uma coleção de configurações para uma instância do Django, incluindo configuração do banco de dados, opções específicas do Django e configurações específicas da aplicação.

A partir da linha de comando, cd para o diretório onde você gostaria de armazenar seu código, então execute o seguinte comando:

Shell
$ django-admin startproject mysite

This will create a mysite directory in your current directory. If it didn’t work, see Problemas ao rodar o django-admin.

Vamos ver o que o startproject criou:

Code
mysite/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        wsgi.py

Esses arquivos são:

  • O arquivo mysite/ exterior é apenas um contêiner para o seu projeto. Seu nome não importa para Django; você pode renomeá-lo para qualquer nome que você quiser.

  • manage.py: Um utilitário de linha de comando que permite a você interagir com esse projeto Django de várias maneiras. Você pode ler todos os detalhes sobre o manage.py em django-admin and manage.py.

  • O arquivo mysite/ interior é o pacote Python para o seu projeto. Seu nome é o nome do pacote Python que você vai precisar usar para importar coisas do seu interior (por exemplo, mysite.urls).

  • mysite/__init__.py: Um arquivo vazio que diz ao Python que este diretório deve ser considerado um pacote Python. Se você é um iniciante Python, leia mais sobre pacotes na documentação oficial do Python.

  • mysite/settings.py: Configurações para este projeto Django. Configurações do Django Irá revelar para você tudo sobre o funcionamento do settings.

  • mysite/urls.py: As declarações de URLs para este projeto Django; um “índice” de seu site movido a Django. Você pode ler mais sobre URLs em Despachante de URL.

  • mysite/wsgi.py: Um ponto de integração para servidores WEB compatíveis com WSGI usado para servir seu projeto. Veja Como implementar com WSGI para mais detalhes.

O servidor de desenvolvimento

Vamos verificar se ele funciona. Vá para o diretório mysite, se você ainda não estiver nele, e rode os seguintes comando:

Shell
$ python manage.py runserver

Você vera a seguinte saída na sua linha de comando:

Performing system checks...

System check identified no issues (0 silenced).

You have unapplied migrations; your app may not work properly until they are applied.
Run 'python manage.py migrate' to apply them.

09 ago. 2026 - 15:50:53
Django version 1.11, using settings 'mysite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Você iniciou o servidor de desenvolvimento do Django, um servidor Web leve escrito puramente em Python. Nós incluímos ele com o Django, então você pode desenvolver coisas rapidamente, sem ter que lidar com a configuração de um servidor Web de produção – como o Apache – até que você esteja pronto para a produção.

Agora é uma boa hora para notar: não use esse servidor em nada relacionado a um ambiente de produção. Seu objetivo é ser utilizado apenas durante o desenvolvimento. (Nós estamos na atividade de criação de frameworks Web, não de servidores Web.)

Agora que o servidor está rodando, visite http://127.0.0.1:8000/ com seu navegador Web. Você irá ver a página “Welcome to Django”, em agradáveis tons de azul claro pastel. Funcionou!

Criando um aplicativo de votação

Agora que seu ambiente – um “projeto” – está configurado, você está pronto para começar o trabalho.

Cada aplicação que você escreve no Django consiste de um pacote Python que segue uma certa convenção. O Django vem com um utilitário que gera automaticamente a estrutura básica de diretório de uma aplicação, então você pode se concentrar apenas em escrever código em vez de ficar criando diretórios.

Seus “apps” podem ficar em qualquer lugar dentro do seu Python path. Neste tutorial, iremos criar nossa “app” de enquete bem ao lado do arquivo manage.py para que possa ser importado como um módulo de nível superior dentro do projeto, ao invés de ser um sub-módulo de mysite.

Para criar sua aplicação, certifique-se de que esteja no mesmo diretório que manage.py e digite o seguinte comando:

Shell
$ python manage.py startapp polls

Que irá criar o diretório polls com a seguinte estrutura:

Code
polls/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    views.py

Esta estrutura de diretório irá abrigar a aplicação de enquete.

Escreva sua primeira view

Hora de criar a primeira view. Abra o arquivo polls/views.py e ponha o seguinte código em Python dentro dele:

polls/views.py
Code
from django.http import HttpResponse


def index(request):
    return HttpResponse("Hello, world. You're at the polls index.")

Esta é a view mais simples possível no Django. Para chamar a view, nós temos que mapear a URL - e por isto nós precisamos da URLconf;

Para criar uma URLconf no diretório polls, Crie uma aquivo chamado urls.py. Agora seu diretório da aplicação deve ficar como:

Code
polls/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    urls.py
    views.py

No aquivo polls/urls.py inclua o seguinte código:

polls/urls.py
Code
from django.conf.urls import url

from . import views

urlpatterns = [
    url(r'^$', views.index, name='index'),
]

O próximo passo, é apontar

mysite/urls.py
Code
from django.conf.urls import include, url
from django.contrib import admin

urlpatterns = [
    url(r'^polls/', include('polls.urls')),
    url(r'^admin/', admin.site.urls),
]

A função include() permite referenciar outros URLconfs. Note que a expressão regular para a função include() não tem um $ (caracter que indica fim de linha) mas ao invés disso uma barra à direita. Sempre que Django encontra a include(), ele corta toda parte da URL combinada até aquele ponto e envia a parte remanescente da string para que o processamento continue no URLconf incluído.

A idéia por trás do include() é criar facilmente URLs plug-and-play. Agora que as polls possuem sua própria URLconf (polls/urls.py), elas podem ser colocadas abaixo de "/polls/", ou abaixo de "/fun_polls/", ou abaixo de "/content_polls/", ou qualquer outra raiz de URL, que a aplicação irá continuar funcionando.

Você agora tem uma view index no URLconf. Vamos verificar se está funcionando, execute o comando:

Shell
$ python manage.py runserver

Acesse http://localhost:8000/polls/ no seu browser, e deverá ver o texto “Hello, world. You’re at the polls index.”, o qual foi definido na “view” ìndex`.

São passados 4 argumentos para url(), dois obrigatórios: regex e view, e dois opcional: kwargs, e name. Neste ponto, vale a pela rever para que servem estes argumentos.

Argumento url(): regex

O termo “regex” é uma forma abreviada utilizada que significa “expressão regular”, que é uma sintaxe para procurar por padrões correspondentes em strings, ou neste caso, padrões de URL. O Django começa pela primeira expressão regular e percorre para baixo na lista, comparando a URL requisitada contra cada expressão regular até encontrar um que corresponda.

Note que estas expressões regulares não buscam parâmetros do GET e POST , ou nomoe de domínio. Por exemplo, no request de https://www.example.com/myapp/, o URLconf irá procurar por myapp/. Em um request para https://www.example.com/myapp/?page=3, o URLconf irá procurar também por myapp/.

Se precisar de ajuda com expressões regulares, veja Wikipedia’s entry e da documentação do módulo re. Além disso, o livro da O’Reilly “Mastering Regular Expressions”, do Jeffrey Friedl é fantástico. Na prática, no entanto, você não precisa ser um especialista em expressões regulares, como você realmente só precisa saber como capturar padrões simples. Na verdade, expressões regulares complexas pode ter mau desempenho de pesquisa, então você provavelmente não deve contar com o pleno poder de expressões regulares.

Finalmente, uma nota de performance: essas expressões regulares são compiladas na primeira vez que o módulo URLconf é carregado. Elas são super rápidas(contanto que as pesquisas não sejam demasiadamente complexas como notado acima).

Argunmento url(): view

Quando o Django encontra uma expressão regular correspondente, o Django executa a função view especificada, com um objeto HttpRequest como o primeiro argumento e qualquer outro valor “capturados” da expressão regular como argumentos. Se a regex usa captura simples, os valores são passados ​​como argumentos posicionais; se ele usa capturas nomeadas, os valores são passados ​​como argumentos nomeados. Vamos dar um exemplo já já.

Argumento url(): kwargs

Argumentos nomeados arbitrários podem ser passadas em um dicionário para a view de destino. Nós não vamos usar este recurso do Django neste tutorial.

Argumento url(): name

Nomear sua URL permite que você referencie ela de forma inequívoca de qualquer lugar no Django especialmente nos templates. Este poderoso recurso permite que você faça alterações globais nos padrões de URL de seu projeto enquanto modifica um único arquivo.

Quando estiver confortável com o básico da sequência de request e response, leia part 2 of this tutorial para começar a trabalhar com banco de dados.

This page as Markdown JSON

Edit this page on GitHub Official version