--- title: "Escrevendo seu primeiro app Django, parte 1" version: 2.1 locale: pt-br source: https://docs.djangoproject.com/pt-br/2.1/intro/tutorial01/ canonical: https://djangodocs.dev/pt-br/2.1/intro/tutorial01/ --- # 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. Assumiremos que você já tem o [Django instalado](/pt-br/2.1/intro/install/) . Você pode verificar se o Django está instalado e em qual versão rodando o seguinte comando em um prompt shell (indicado pelo prefixo $): ```console $ python -m django --version ``` *Windows* ```doscon ...\> py -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”. This tutorial is written for Django 2.1, which supports Python 3.5 and later. If the Django version doesn’t match, you can refer to the tutorial for your version of Django by using the version switcher at the bottom right corner of this page, or update Django to the newest version. If you’re using an older version of Python, check [Qual versão do Python eu posso usar com Django?](/pt-br/2.1/faq/install/#faq-python-version-support) to find a compatible version of Django. Veja [Como instalar o Django](/pt-br/2.1/topics/install/) para recomendação sobre como remover versões antigas do Django e instar uma mais recente. > **Onde obter ajuda:** > > Se você estiver tendo problemas no decorrer desse tutorial, por favor envie uma mensagem para [django-users](/pt-br/2.1/internals/mailing-lists/#django-users-mailing-list) ou deixe-a em [#django-br on irc.freenode.net](irc://irc.freenode.net/django-br) para bater-papo com outros usuários Django dispostos a ajudar. ## 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](/pt-br/2.1/glossary/#term-project) 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: ```console $ django-admin startproject mysite ``` *Windows* ```doscon ...\> 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](/pt-br/2.1/faq/troubleshooting/#troubleshooting-django-admin). > **Note** > > Você precisará evitar dar nomes a projetos que remetam a componentes internos do Python ou do Django. Particularmente, isso significa que você deve evitar usar nomes como `django` (que irá conflitar com o próprio Django) ou `test` (que irá conflitar com um pacote interno do Python). > **Onde esse código deveria existir?** > > Se você tem experiência prévia em PHP (sem o uso de um framework moderno), você deve estar acostumado a colocar o código dentro do “document root” de seu servidor Web (em um lugar como `/var/www`). Com o Django você não fará isto. Não é uma boa ideia colocar qualquer código Python no document root de seu servidor Web, porque existe o risco de pessoas conseguirem ver seu código através da Web. Isso não é bom para a segurança. > > Coloque seu código em algum diretório **fora** do document root, como em `/home/mycode`. Vamos ver o que o [`startproject`](/pt-br/2.1/ref/django-admin/#django-admin-startproject) criou: ``` 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](/pt-br/2.1/ref/django-admin/). - 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](https://docs.python.org/3/tutorial/modules.html#tut-packages) na documentação oficial do Python. - `mysite/settings.py`: Configurações para este projeto Django. [Configurações do Django](/pt-br/2.1/topics/settings/) 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](/pt-br/2.1/topics/http/urls/). - `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](/pt-br/2.1/howto/deployment/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: ```console $ python manage.py runserver ``` *Windows* ```doscon ...\> py 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 2.1, using settings 'mysite.settings' Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C. ``` > **Note** > > Por hora, ignore os avisos sobre as migrações do banco de dados não aplicadas; lidaremos com o banco de dados brevemente. 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.) Now that the server’s running, visit with your Web browser. You’ll see a “Congratulations!” page, with a rocket taking off. It worked! > **Alterando a porta** > > Por padrão, o comando :djadmin:`runserver` inicia o servidor de desenvolvimento no IP interno na porta 8000. > > Se você quer mudar a porta do servidor, passe ela como um argumento na linha de comando. Por exemplo, este comando iniciará o servidor na porta 8080: > > ```console > $ python manage.py runserver 8080 > ``` > > *Windows* > > ```doscon > ...\> py manage.py runserver 8080 > ``` > > If you want to change the server’s IP, pass it along with the port. For > example, to listen on all available public IPs (which is useful if you are > running Vagrant or want to show off your work on other computers on the > network), use: > > ```console > $ python manage.py runserver 0:8000 > ``` > > *Windows* > > ```doscon > ...\> py manage.py runserver 0:8000 > ``` > > **0** is a shortcut for **0.0.0.0**. Full docs for the development server > can be found in the [`runserver`](/pt-br/2.1/ref/django-admin/#django-admin-runserver) reference. > **Releitura automática de runserver** > > O servidor de desenvolvimento recarrega o código Python para cada solicitação, conforme necessário. Você não precisa reiniciar o servidor para alterações de código tenham efeito. No entanto, algumas ações como a adição de arquivos não iniciam uma reinicialização, então você terá que reiniciar o servidor nestes casos. ## 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. > **Projetos versus aplicações** > > Qual é a diferença entre um projeto e um app? Um app é uma aplicação que faz alguma coisa, exemplo, um sistema de web blog, um banco de dados de registros públicos, ou uma simples aplicação de enquete. Um projeto é uma coleção de configurações e apps para um particular website. Um projeto pode conter múltiplos apps. Um app pode estar em múltiplos projetos. Seus “apps” podem ficar em qualquer lugar dentro do seu [Python path](https://docs.python.org/3/tutorial/modules.html#tut-searchpath). 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: ```console $ python manage.py startapp polls ``` *Windows* ```doscon ...\> py manage.py startapp polls ``` Que irá criar o diretório `polls` com a seguinte estrutura: ``` 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* ```python 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: ``` 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* ```python from django.urls import path from . import views urlpatterns = [ path('', views.index, name='index'), ] ``` O próximo passo é apontar na raiz do URLconf para o módulo `polls.urls`. No arquivo `mysite/urls.py`, adicione um importador para `django.urls.include` e insira um [`include()`](/pt-br/2.1/ref/urls/#django.urls.include) na lista de `urlpatterns` , então você tem: *mysite/urls.py* ```python from django.contrib import admin from django.urls import include, path urlpatterns = [ path('polls/', include('polls.urls')), path('admin/', admin.site.urls), ] ``` The [`include()`](/pt-br/2.1/ref/urls/#django.urls.include) function allows referencing other URLconfs. Whenever Django encounters [`include()`](/pt-br/2.1/ref/urls/#django.urls.include), it chops off whatever part of the URL matched up to that point and sends the remaining string to the included URLconf for further processing. The idea behind [`include()`](/pt-br/2.1/ref/urls/#django.urls.include) is to make it easy to plug-and-play URLs. Since polls are in their own URLconf (`polls/urls.py`), they can be placed under “/polls/”, or under “/fun\_polls/”, or under “/content/polls/”, or any other path root, and the app will still work. > **When to use include()** > > Deve-se sempre usar `include()` quando incluir outros “patterns” de URLs. `admin.site.urls` é a única excessão a isso. Você agora tem uma view `index` no URLconf. Vamos verificar se está funcionando, execute o comando: ```console $ python manage.py runserver ``` *Windows* ```doscon ...\> py manage.py runserver ``` Acesse no seu browser, e deverá ver o texto “*Hello, world. You’re at the polls index.*”, o qual foi definido na “view” ìndex\`. > **Página não encontrada?** > > If you get an error page here, check that you’re going to > and not . The [`path()`](/pt-br/2.1/ref/urls/#django.urls.path) function is passed four arguments, two required: `route` and `view`, and two optional: `kwargs`, and `name`. At this point, it’s worth reviewing what these arguments are for. ### [`path()`](/pt-br/2.1/ref/urls/#django.urls.path) argument: `route` `route` is a string that contains a URL pattern. When processing a request, Django starts at the first pattern in `urlpatterns` and makes its way down the list, comparing the requested URL against each pattern until it finds one that matches. Patterns don’t search GET and POST parameters, or the domain name. For example, in a request to `https://www.example.com/myapp/`, the URLconf will look for `myapp/`. In a request to `https://www.example.com/myapp/?page=3`, the URLconf will also look for `myapp/`. ### [`path()`](/pt-br/2.1/ref/urls/#django.urls.path) argument: `view` When Django finds a matching pattern, it calls the specified view function with an [`HttpRequest`](/pt-br/2.1/ref/request-response/#django.http.HttpRequest) object as the first argument and any “captured” values from the route as keyword arguments. We’ll give an example of this in a bit. ### [`path()`](/pt-br/2.1/ref/urls/#django.urls.path) argument: `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. ### [`path()`](/pt-br/2.1/ref/urls/#django.urls.path) argument: `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](/pt-br/2.1/intro/tutorial02/) para começar a trabalhar com banco de dados.