Primeiro Projeto Django: Guia Completo | Python Brasil

Introdução

Django é o framework web mais popular do Python. Usado por empresas como Instagram, Pinterest e Disqus, ele segue a filosofia “baterias incluídas” — oferecendo ORM, sistema de autenticação, painel administrativo e muito mais prontos para uso.

Neste guia, vamos criar um projeto Django completo do zero: uma aplicação simples de lista de tarefas. Ao final, você terá um projeto funcional rodando no seu computador.

Pré-requisitos

Antes de começar, certifique-se de ter:

Python 3.10 ou superior instalado
Conhecimento básico de terminal/linha de comando
Um editor de código (VS Code, PyCharm ou outro de sua preferência)

Criando o ambiente virtual

Sempre crie um ambiente virtual para projetos Django. Isso isola as dependências do projeto:

mkdir lista-tarefas
cd lista-tarefas
python3 -m venv venv

Ative o ambiente virtual:

# Linux e macOS
source venv/bin/activate

# Windows
venv\Scripts\activate

Você verá (venv) no início da linha do terminal, indicando que o ambiente está ativo.

Instalando o Django

Com o ambiente virtual ativo, instale o Django:

pip install django

Verifique a instalação:

python -c "import django; print(django.get_version())"

Criando o projeto

O Django separa a estrutura em projeto (configurações globais) e aplicações (módulos funcionais). Crie o projeto:

django-admin startproject config .

O ponto (.) no final cria o projeto na pasta atual, evitando uma pasta aninhada desnecessária. A estrutura gerada é:

lista-tarefas/
    config/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py
    manage.py
    venv/

Teste se tudo funciona:

python manage.py runserver

Acesse http://127.0.0.1:8000/ no navegador. Se você vir a página de boas-vindas do Django, está tudo certo.

Criando a aplicação

Agora vamos criar a aplicação de tarefas:

python manage.py startapp tarefas

Registre a aplicação no arquivo config/settings.py:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'tarefas',  # Nossa aplicação
]

Criando o modelo

Modelos definem a estrutura dos dados. Edite tarefas/models.py:

from django.db import models


class Tarefa(models.Model):
    titulo = models.CharField(max_length=200)
    descricao = models.TextField(blank=True)
    concluida = models.BooleanField(default=False)
    criada_em = models.DateTimeField(auto_now_add=True)
    atualizada_em = models.DateTimeField(auto_now=True)

    class Meta:
        ordering = ['-criada_em']

    def __str__(self):
        return self.titulo

Crie e aplique a migração para gerar a tabela no banco de dados:

python manage.py makemigrations
python manage.py migrate

Configurando o painel administrativo

O Django vem com um painel admin pronto. Registre o modelo em tarefas/admin.py:

from django.contrib import admin
from .models import Tarefa


@admin.register(Tarefa)
class TarefaAdmin(admin.ModelAdmin):
    list_display = ['titulo', 'concluida', 'criada_em']
    list_filter = ['concluida']
    search_fields = ['titulo', 'descricao']

Crie um superusuário para acessar o admin:

python manage.py createsuperuser

Acesse http://127.0.0.1:8000/admin/ e faça login. Você já pode criar, editar e excluir tarefas pelo painel.

Criando as views

Views processam requisições e retornam respostas. Edite tarefas/views.py:

from django.shortcuts import render, redirect, get_object_or_404
from .models import Tarefa


def lista_tarefas(request):
    tarefas = Tarefa.objects.all()
    return render(request, 'tarefas/lista.html', {'tarefas': tarefas})


def criar_tarefa(request):
    if request.method == 'POST':
        titulo = request.POST.get('titulo')
        descricao = request.POST.get('descricao', '')
        if titulo:
            Tarefa.objects.create(titulo=titulo, descricao=descricao)
        return redirect('lista_tarefas')
    return render(request, 'tarefas/criar.html')


def alternar_tarefa(request, pk):
    tarefa = get_object_or_404(Tarefa, pk=pk)
    tarefa.concluida = not tarefa.concluida
    tarefa.save()
    return redirect('lista_tarefas')


def excluir_tarefa(request, pk):
    tarefa = get_object_or_404(Tarefa, pk=pk)
    tarefa.delete()
    return redirect('lista_tarefas')

Configurando as URLs

Crie o arquivo tarefas/urls.py:

from django.urls import path
from . import views

urlpatterns = [
    path('', views.lista_tarefas, name='lista_tarefas'),
    path('criar/', views.criar_tarefa, name='criar_tarefa'),
    path('alternar/<int:pk>/', views.alternar_tarefa, name='alternar_tarefa'),
    path('excluir/<int:pk>/', views.excluir_tarefa, name='excluir_tarefa'),
]

Inclua as URLs da aplicação no arquivo principal config/urls.py:

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('tarefas.urls')),
]

Criando os templates

Crie a pasta de templates: tarefas/templates/tarefas/. Primeiro, o template base. Crie tarefas/templates/tarefas/base.html:

<!DOCTYPE html>
<html lang="pt-br">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Lista de Tarefas</title>
    <style>
        body { font-family: Arial, sans-serif; max-width: 600px; margin: 50px auto; padding: 0 20px; }
        .tarefa { padding: 10px; border-bottom: 1px solid #ddd; display: flex; align-items: center; justify-content: space-between; }
        .concluida { text-decoration: line-through; color: #888; }
        input[type="text"] { padding: 8px; width: 100%; margin-bottom: 10px; }
        button, .btn { padding: 8px 16px; cursor: pointer; }
    </style>
</head>
<body>
    {% block content %}{% endblock %}
</body>
</html>

Agora, tarefas/templates/tarefas/lista.html:

{% extends "tarefas/base.html" %}

{% block content %}
<h1>Minhas Tarefas</h1>
<a href="{% url 'criar_tarefa' %}">Nova Tarefa</a>

{% for tarefa in tarefas %}
<div class="tarefa">
    <span class="{% if tarefa.concluida %}concluida{% endif %}">
        {{ tarefa.titulo }}
    </span>
    <div>
        <a href="{% url 'alternar_tarefa' tarefa.pk %}">
            {% if tarefa.concluida %}Reabrir{% else %}Concluir{% endif %}
        </a>
        <a href="{% url 'excluir_tarefa' tarefa.pk %}">Excluir</a>
    </div>
</div>
{% empty %}
<p>Nenhuma tarefa cadastrada.</p>
{% endfor %}
{% endblock %}

E tarefas/templates/tarefas/criar.html:

{% extends "tarefas/base.html" %}

{% block content %}
<h1>Nova Tarefa</h1>
<form method="post">
    {% csrf_token %}
    <input type="text" name="titulo" placeholder="Titulo da tarefa" required>
    <textarea name="descricao" placeholder="Descricao (opcional)"></textarea>
    <button type="submit">Criar</button>
</form>
<a href="{% url 'lista_tarefas' %}">Voltar</a>
{% endblock %}

Testando a aplicação

Rode o servidor e teste todas as funcionalidades:

python manage.py runserver

Acesse http://127.0.0.1:8000/ e experimente criar, concluir e excluir tarefas. Tudo deve funcionar com os dados sendo salvos no banco SQLite padrão do Django.

Configuração de idioma e fuso horário

Atualize o config/settings.py para português do Brasil:

LANGUAGE_CODE = 'pt-br'
TIME_ZONE = 'America/Sao_Paulo'
USE_I18N = True
USE_TZ = True

Isso afeta o painel administrativo e mensagens de erro do Django.

Próximos passos

Com o projeto básico funcionando, você pode evoluir adicionando:

Autenticação de usuários com django.contrib.auth
Formulários com a classe ModelForm do Django
Testes automatizados com pytest-django
CSS com frameworks como Tailwind ou Bootstrap
Deploy em um servidor real usando Gunicorn e Nginx

Conclusão

O Django é um framework robusto que permite criar aplicações web completas rapidamente. Neste guia, você aprendeu a criar um projeto, definir modelos, views, templates e URLs. O painel administrativo gratuito é um diferencial enorme que economiza horas de desenvolvimento. A partir daqui, explore a documentação oficial do Django para aprofundar seus conhecimentos.