Filtros em Templates no Django


Django, Templates e Filtros

Já vimos em Templates do Django que os templates são modelos usados na arquitetura MTV para renderizar as requisições do cliente e gerar texto com marcação HTML. Dentro desses modelos podemos receber variáveis enviadas no contexto, com a marcação {{ var }}. Um contexto é um conjunto de valores, em um objeto tipo dicionário (um conjunto de chaves:valores), passado pelas views para o template. Os nomes das variáveis são passados como strings.

# se temos a variável    
» contexto = {"n1": "um"; "n2":"dois";}
# e o template
⎀ Temos no contexto {{ n1 }} e {{ n2 }}.
# será renderizado como
↳ Temos no contexto um e dois.

Filtros são formas de modificar as saídas de variáveis. Por ex.:

» contexto = {'django': 'o framework web para perfecionistas com prazos'}
⎀ {{ django|title }}
↳ O Framework Web Para Perfecionistas Com Prazos
# ou
» contexto = {'data': '2022-07-04'}
⎀ {{ data|date:"d/m/Y" }}
↳ 04/07/2022

Muitos outros filtros são predefinidos e outros mais podem ser definidos pelo programador.

Filtros do Django

add soma valor ao argumento. Tenta forçar a conversão de strings para numéricos.

» valor = 6
⎀ {{ valor|add:"2" }}
↳ 8

» lista1 = [2,3,4]; lista2 = [7,8,9]
⎀ {{ lista1|add:lista2 }}
↳ [2,3,4,7,8,9]

addslashes, insere “\” em aspas.

» valor = "Einstein disse: 'Não existe mais espaço e tempo'."
⎀ {{ valor|addslashes }}
↳ Einstein disse: \'Não existe mais espaço e tempo\'.

capfirst, capitaliza primeira letra de uma string.

» valor = "não existe mais espaço e tempo"
⎀ {{ valor|capfirst }}
↳ Não existe mais espaço e tempo

center, centraliza texto dentro do espaço dado.

» valor = "tempo"
⎀ {{ valor|center:"20" }}
↳ "       tempo        "

cut, remove valores do argumento do string dado.

» valor = "não existe mais espaço e tempo"
⎀ {{ valor|cut:" " }}
↳ nãoexistemaisespaçoetempo

cut, formata uma data (e hora) de acordo com especificação dada.

» data = "2022-02-30"
⎀ {{ data|date:"d/m/y" }}
↳ 30/02/22
⎀ {{ data|date:"d-m-Y" }}
↳ 30-02-2022

Alguns formatos são pre-definidos. Veja a lista completa em Django docs.

Caracter Descrição Exemplo
Dia
d dia do mes com dois dígitos ’01’ até ’31’
j dia do mes sem zeros. ‘1’ até ’31’
D dia da semana em texto, 3 letras. ‘Fri’
l dia da semana em texto completo. ‘Friday’
w dia da semana, numérico. ‘0’ (Domingo) até ‘6’ (Sábado)
z dia do ano. 1 to 366
Semana
W número da semana no ano. 1, 53
Mês
m mês, 2 dígitos. ’01’ até ’12’
n mês sem zeros. ‘1’ até ’12’
M mês, texto, 3 letras. ‘Jan’, ‘Dec’
b mês, texto, 3 letras, ninúsculas. ‘jan’, ‘dec’
F mês, texto, extenso. ‘January’
t quantos dias no mês. 28 to 31
Ano
y ano, 2 dígitos. ’00’ até ’99’
Y ano, 4 dígitos. ‘0001’, …, ‘1999’, …, ‘9999’
L Booleano, se ano é bissexto. True ou False
Hora
g hora, formato 12-hora sem zeros. ‘1’ até ’12’
G hora, formato 24-hora sem zeros. ‘0’ até ’23’
h hora, formato 12-hora. ’01’ até ’12’
H hora, formato 24-hora. ’00’ até ’23’
i minutos. ’00’ até ’59’
s segundos, 2 dígitos. ’00’ até ’59’
u microssegundos. 000000 até 999999
a ‘a.m.’ ou ‘p.m.’
A ‘AM’ ou ‘PM’.
f hora, format 12-horas e minutos ‘1:30’
P hora, formato 12-hora horas, minutos ‘a.m.’/’p.m.’
Timezone
e nome da timezone ‘GMT’, ‘-500’, ‘US/Eastern’, etc.

O formato pode ser um dos predefinidos como DATE_FORMAT, DATETIME_FORMAT, SHORT_DATE_FORMAT ou SHORT_DATETIME_FORMAT ou um formato construído com os especificadores acima. Formatos predefinidos podem depender do ajuste local.

# se data_valor é um objeto datetime, como o resultante de datetime.datetime.now() 
# com hora 23:45, dia 01/11/2021
⎀ {{ data_valor|date:"D d M Y" }} {{ data_valor|time:"H:i" }}
↳ Mon 01 Nov 2021 23:45

# se o locale for pt-BR
⎀ {{ data_valor|date:"SHORT_DATE_FORMAT" }}
↳ 01/11/2021

default, fornece valor default se argumento for False.

»  valor = ""   
⎀ {{ valor|defalt:"nada aqui" }} 
↳ nada aqui

default_if_none, fornece valor default se argumento for None.

» valor = None
⎀ {{ valor|defalt_if_none:"recebemos None" }} 
↳ recebemos None

dictsort recebe uma lista de dicionários e ordena a lista por alguma das chaves do docionário.

# considerando o dicionário:    
» dicio = [
»     {'nome': 'Zuenir', 'idade': 9},
»     {'nome': 'Antônia', 'idade': 12},
»     {'nome': 'Jaime', 'idade': 3},
» ]

⎀ {{ dicio|dictsort:"nome" }}
# resulta em
↳ dicio = [
↳     {'nome': 'Antônia', 'idade': 12},
↳     {'nome': 'Jaime', 'idade': 3},
↳     {'nome': 'Zuenir', 'idade': 9},
↳ ]

Exemplos mais complexos podem ser obtidos:

# se livros é    
» livros = [
»     {'titulo': '1984', 'autor': {'nome': 'George', 'idade': 45}},
»     {'titulo': 'Timequake', 'autor': {'nome': 'Kurt', 'idade': 75}},
»     {'titulo': 'Alice', 'autor': {'nome': 'Lewis', 'idade': 33}},
» ]

# o código em template
⎀ {% for livro in livros|dictsort:"autor.idade" %}
⎀     * {{ livro.titulo }} ({{ livro.autor.nome }})
⎀ {% endfor %}

# resultaria em
↳ * Alice (Lewis)
↳ * 1984 (George)
↳ * Timequake (Kurt)

dictsortreversed tem o mesmo efeito que dictsort, mas ordenando em ordem invertida.

divisibleby returna True se o valor é divisível pelo argumento.

» valor = 171
⎀ {{ value|divisibleby:"3" }}
↳ True

escape promove remoção de tags html.

# esse exemplo mostra a exibição final no navegador
» string_html = "<b>Negrito<b>"
⎀ {{ string_html }}
↳ <b>Negrito<b>

⎀ {{ string_html|scape }}
↳ <b>Negrito</b>

escape converte:

  • < em &lt;
  • > em &gt;
  • ' (aspas simples) em &#x27;
  • " (aspas duplas) em &quot;
  • & em &amp;

first retorna o 1º elemento de uma lista.

» lista = ["casa","da","sogra"]
⎀ {{ lista|first }}
↳ casa

floatformat promove o arredondamento de números flutuantes.

» valor = 34.23234
⎀ {{ valor|floatformat }}
↳ 34.2

» valor = 34.0000
⎀ {{ valor|floatformat }}
↳ 34

» valor = 34.26000
⎀ {{ valor|floatformat }}
↳ 34.3

O número de casas pode ser definido em valor|floatformat:n. Passando “0” como argumento o arredondamento será para o inteiro mais próximo. O sufixo g introduz separador de milhar, definido em THOUSAND_SEPARATOR.

valor template output
34.23234 {{ valor|floatformat:2 }} 34.23
34.00000 {{ valor|floatformat:2 }} 34.00
34.26000 {{ valor|floatformat:2 }} 34.26
34.23234 {{ valor|floatformat:”0″ }} 34
31.00000 {{ valor|floatformat:”0″ }} 31
39.56000 {{ valor|floatformat:”0″ }} 40
34232.34 {{ valor|floatformat:”2g” }} 34,232.34
34232.06 {{ valor|floatformat:”g” }} 34,232.1

get_digit retorna um inteiro na posição especificada, contando do final para o início. Se não for possível encontar esse dígito, retorna o valor original.

» valor = 9512845
⎀ {{ valor|get_digit:"4" }}
↳ 2

⎀ {{ valor|get_digit:"9" }}
↳ 9512845

join faz a união de elementos em uma lista em uma string (como em str.join(lista)).

» lista = ["casa", "da", "mãe", "Joana"]
⎀ {{ lista|join:" - " }}
↳ casa - da - mãe - Joana

last retorna o último elemento de uma lista.

»  lista = ["casa", "da", "mãe", "Joana"]
⎀ {{ lista|last}}
↳ Joana

len retorna o comprimento de uma lista.

»  lista = ["casa", "da", "mãe", "Joana"]
⎀ {{ lista|len}}
↳ 4

length_is retorna booleano, se o comprimento de uma lista é o dado em parâmetro.

»  lista = ["casa", "da", "mãe", "Joana"]
⎀ {{ lista|length_is:"4"}}
↳ True

linebreaks substitui quebras de linha em texto puro por uma quebra de linha html (<br>) e insere anova linha entre tags de parágrafo (<p> … </p>).

» texto_puro = "Essa é a linha 1\nEssa é a linha 2"
⎀ {{ texto_puro|linebreaks}}
↳ <p>Essa é a linha 1<br>Essa é a linha 2</p>

linebreaksbr faz a mesma coisa, sem inserir a linha em parágrafo.

linenumbers quebra texto em linhas e as numera.

» lista_compras = '''Leite
» Açucar
» Café
» Pão'''

⎀ {{ lista_compras|linenumbers }}
# resulta em
↳ 1. Leita
↳ 2. Açucar
↳ 3. Café
↳ 4. Pão

Observe que lista_compras = “Leite\nAçucar\nCafé\nPão”.

ljust alinha texto à esquerda dentro de espaço de n caracteres dado.

» comprar = "Pão"
⎀ {{ comprar|ljust:"9" }}
↳ "Pão      "

lower converte todas os caracters de uma string para caixa baixa (minúsculas).

» texto = "Pão COM Manteiga"
⎀ {{ texto|lower }}
↳ pão com manteiga

make_list retorna valor string ou inteiro em uma lista.

» texto = "Pão de Queijo"
⎀ {{ texto|make_list }}
↳ ["P", "ã", "o", " ", "d", "e", " ", "Q", "u", "e", "i", "j", "o"]

» numero = 1957
⎀ {{ numero|make_list }}
↳ ["1", "9", "5", "7"]

pluralize retorna sufixo para plurais se valor do parâmetro for maior que 1. Esse valor pode ser o comprimento do objeto. O sufixo default é s, mas isso pode ser alterado.

» itens_compra = 1
⎀ Você tem que comprar {{ itens_compra }} objeto{{ itens_compra|pluralize }}.
↳ Você tem que comprar 1 objeto.

» itens_compra = 23
⎀ Você tem que comprar {{ itens_compra }} objeto{{ itens_compra|pluralize }}.
↳ Você tem que comprar 23 objetos.

Sufixos alternativos podem ser inseridos como parâmetros:

» quantos = 1
⎀ Você fez o pedido de {{ quantos }} paste{{ quantos|pluralize:"l,is" }}.
↳ Você fez o pedido de 1 pastel.

» quantos = 45
⎀ Você fez o pedido de {{ quantos }} paste{{ quantos|pluralize:"l,is" }}.
↳ Você fez o pedido de 45 pasteis.

random retorna um elemento aleatório de uma lista.

»  lista = ["casa", "da", "mãe", "Joana"]
⎀ {{ lista|random }}
# um possível resultado é
↳ mãe

rjust alinha texto à direita dentro de espaço de n caracteres dado.

» comprar = "Pão"
⎀ {{ comprar|rjust:"9" }}
↳ "      Pão"

safe marca texto como não necessitando escapes.

escape promove remoção de tags html.

» string_html = "<b>Negrito<b>"
⎀ {{ string_html|escape }}
↳ <b>Negrito<b>

Se existirem tags html elas serão renderizadas no navegador.

slice retorna uma fatia (slice) de uma lista. Usa a mesma sintaxe de slicing de listas do python:

» lista = ["casa","da","sogra", "no", "domingo"]
⎀ {{ lista|slice:":3" }}
↳ ["casa","da","sogra"]

slugify converte texto em ASCII puro, convertendo espaços em hífens. Remove caracteres que não são alfanuméricos, sublinhados (underscores) ou hífens. Converte tudo para minúsculas eliminando espaços nas bordas.

» texto = " Artigo 31 das Notas "
⎀ {{ texto|slugfy }}
↳ artigo-31-das-notas

stringformat formata variável de acordo com o parâmetro especificador.

» valor = 10
⎀ {{ valor|stringformat:"E" }}
↳ 1.000000E+01

Mais caracteres de formatação em printf-style String Formatting.

striptags remove tags [X]Html sempre que possível.

» valor = "<b>Um texto pode ter</b> <button>várias tags</button> <span>(x)html</span>!"
⎀ {{ valor|striptags }}
↳ Um texto pode ter várias tags (x)html!

Observação: striptags não garante que o texto seja seguro. Não aplique a filtro safe sobre o resultado de striptags.

time formata variável tipo time de acordo com formato especificado.

» hora = datetime.datetime.now()
⎀ {{ hora|time:"H:i" }}
↳ 18:49

⎀ {{ hora|time:"H\h i\m" }}
↳ 01h 23m

No exemplo caracteres literais foram escapados (\h, \m).

timesince formata uma diferença de datas entre now (agora) e data fornecida em parâmetro.

# se artigo_gravado contem uma data e
» hora = datetime.datetime.now()
⎀ {{ artigo_gravado|timesince:hora }}
↳ 14 days, 18 hours

timeuntil é análoga à timesince mas retornando a diferença entre uma data data e data futura.

title formata string como título de artigos e livros, colocando em maiúsculas as primeiras letras de cada palavra.

» titulo = "análise auxiliar de enrolação científica"
⎀ {{ titulo|title }}
↳ Análise Auxiliar De Enrolação Científica

truncatechars realiza o truncamento de um texto em um número especificado de caracteres. O texto truncado é seguido de elipses .

» texto = "Esta é uma nota grande."
⎀ {{ texto|truncatechars:15 }}
↳ Esta é uma nota...
# nada é feito de o texto for menor que o parâmetro de truncamento
⎀ {{ texto|truncatechars:35 }}
↳ Esta é uma nota grande.

truncatechars_html é similar à truncatechars mas evitando o descarte de tags html.

» texto = "

Esta é uma nota grande.

" ⎀ {{ texto|truncatechars_html:15 }} ↳ <p>Esta é uma not...</p>

truncatewords trunca uma string após um número dado de palavras. O texto truncado é seguido de elipses . Quebras de linha são removidas.

» texto = "Um texto com\n muitas palavras pode ser cortado"
⎀ {{ texto|truncatewords:4 }}
↳ Um texto com muitas...

truncatewords_html é similar à truncatewords, mas evitando eliminar tags html. Quebras de linha são mantidas.

» texto = "<p>Um texto com\n muitas palavras pode ser cortado</p>"
⎀ {{ texto|truncatewords:4 }}
↳ <p>Um texto coman muitas...</p>

unordered_list constroi uma lista html à partir de listas e listas aninhadas, inserindo recursivamente sublistas quando necessário.

» lista = ['Estados', ['Minas Gerais', ['Juiz de Fora', 'Belo Horizonte'], 'Paraná']]
⎀ {{ lista|unordered_list }}
↳
<li>Estados
<ul>
        <li>Minas Gerais
        <ul>
                <li>Juiz de Fora</li>
                <li>Belo Horizonte</li>
        </ul>
        </li>
        <li>Paraná</li>
</ul>
</li>

Observe que as tags de abertura e fechamento da lista externa (<ul></ul>) não são incluídas.

upper converte todos os caracteres de uma string em maiúsculas.

» texto = "Um texto com algumas palavras."
⎀ {{ texto|upper }}
↳ UM TEXTO COM ALGUMAS PALAVRAS.

urlencode transforma uma string para uso como url.

» url = "https://phylos.net/foo?a=b"
⎀ {{ url|urlencode }}
↳ https%3A//phylos.net/foo%3Fa%3Db

urlize converte uma URL ou endereço de email em links clicáveis.

» url = "Visite minha página em phylos.net"
⎀ {{ url|urlize }}
↳ Visite minha página em phylos.net

# emails também são convertidos
» email = "Mande sua mensagem para usuario@exemplo.com"
⎀ {{ email|urlize }}
↳ Mande sua mensagem para usuario@exemplo.com

O atributo rel=”nofollow” é acrescentado.

urlizetrunc age como urlize mas truncando urls longas para a exibição>

{{ url|urlizetrunc:15 }}

wordcount retorna número de palavras no parâmetro.

» texto = "Um texto com algumas palavras."
⎀ {{ texto|wordcount }}
↳ 5

wordwrap quebra o texto em comprimento especificado, inserindo quebra de linhas. wordwrap:n não quebra palavras mas sim a linha em valores inferiores a n dado como comprimento.

Implements word wrapping by inserting a newline character every n characters. Useful for plain text, but not typically for HTML.

» texto = "Um texto com algumas palavras."
⎀ {{ texto|wordwrap:17 }}
↳ Um texto com
↳ algumas palavras.

yesno retorna uma string especificada para o valor do parâmetro True, False ou None (opcional).

» condicao = False
⎀ {{ condicao|"Sim, Não, Talvez" }}
↳ Não

» condicao = True
⎀ Você respondeu: {{ condicao|"Afirmativo, Negativo" }}
↳ Você respondeu: Afirmativo

Bibliografia

Livros

  • Newman, Scott: Django 1.0 Template Development, 2008 Packt, 2008.

Sites

todos acessados em julho de 2022.

Django, incrementando o Projeto

Sofisticando o modelo com chaves externas e datas

Vamos aprimorar o aplicativo classificando nossas notas por categorias, permitindo diversos cadernos separados. Para efeito didático usaremos apenas um nível de categoria. Idealmente essas poderiam ser subdivididas em subcategorias de vários níveis.

Para isso criaremos modelos para as seguintes tabelas:

Caderno
id pk, automatico
caderno texto
Categoria
id pk, automatico
categoria texto
Notas
id pk, automatico
caderno fk –> caderno
categoria fk –> categoria
titulo texto
texto texto
slug texto

Vamos fazer alterações nos modelos, que serão aplicadas no banco de dados com migrations.
app_notas/notas/models.py

from django.db import models
from django.utils.text import slugify

class Caderno(models.Model):
    titulo = models.CharField(default='', max_length=150)
    def __str__(self):
        return self.titulo

class Categoria(models.Model):
    categoria = models.CharField(default='', max_length=150)
    def __str__(self):
        return self.categoria

class Nota(models.Model):
    titulo = models.CharField(default='', max_length=150, help_text="Título da Nota")
    texto = models.TextField(default='', blank=True)
    slug = models.SlugField(default='', blank=True, max_length=255)
    data_criada = models.DateField(auto_now_add=True, help_text="Data de Criação")
    data_editada = models.DateField(auto_now=True, help_text="Data de Edição")
    caderno = models.ForeignKey(Caderno, on_delete=models.CASCADE)
    categoria = models.ForeignKey(Categoria, on_delete=models.CASCADE)

    def __str__(self):
        return self.titulo

    def save(self,*args,**kwargs):
        self.slug = slugify(self.titulo)
        super().save(*args,**kwargs)

As partes alteradas estão em negrito. Inserimos duas novas tabelas: Caderno e Categoria. Cada uma delas tem seu id criado automaticamente pelo django. Na tabela Nota acrescentamos caderno e categoria. Definidos como ForeignKey eles ficam associados às novas tabelas da seguinte forma:

nota.caderno (fk) ⟼ caderno.id
nota.categoria (fk) ⟼ categoria.id

O argumento help_text permite a especificação de texto descritivo que será exibido juntos com forms, como veremos.

Os campos do tipo DateField armazenam datas. (DateTimeField armazenam datas e horas). O argumento auto_now_add=True ajusta a campo para a hora do momento de criação do valor do campo enquanto
auto_now=True ajusta a campo na hora da última edição, quando o objeto é gravado.

A chave externa (fk) define uma relação de muitos-para-um. Por ex., cada nota tem apenas uma categoria mas podem haver diversas outras notas na mesma categoria.

O argumento on_delete informa como registros ligados por chaves externas devem ser tratados em caso de apagamento do registro principal. Ele pode receber diversos valores:

CASCADE força o apagamento de dados conectados pela chave externa.
PROTECT impede o apagamento de dados conectados pela chave externa. Levanta exceção ProtectedError.
RESTRICT similar à PROTECT, mas levanta erro RestrictedError.
SET_NULL mantém dados conectados pela chave externa, substituindo seu valor por NULL. O parâmetro deve ser ajustado na definição do modelo.
SET_DEFAULT similar à SET_NULL mas substitui o valor da chave por seu valor default. O parâmetro deve ser ajustado na definição do modelo.
SET( ) permite a construção de funções customizadas para atribuir valores ao campo fk apagado.
DO_NOTHING nenhuma atitude é tomada e os dados ligados por fk permanecem inalterados.
Uma descrição mais detalhadas por ser vista em Zerotobyte: On delete explained.

Além disso inserimos dois campos de data, data_criada e data_editada, que são preenchidas por default com a data do momento da operação.

Com essas alterações o banco de dados atual fica inconsistente, pois existem campos que demandariam fk e que estão vazios. Como estamos em desenvolvimento e os dados que temos são apenas experimentais, uma boa tática é a de resetar o banco de dados. Essa é também uma boa oportunidade para mencionar como isso é feito.

Resetando o banco de dados

Podemos ver todas as migrations feitas até agora com o comando:

$ python manage.py showmigrations

Para remover as alterações no BD e as migrations do django, removemos o conteudo do BD. No nosso caso, como estamos usando o SQLite, basta apagar o arquivo db.sqlite3 que fica na pasta do projeto app_notas/app_notas. Em seguido removemos todo o conteúdo da pasta migrations, na pasta de cada aplicativo (app_notas/notas no caso), exceto o arquivo __init__.py.

Podemos agora reconstruir o BD e refazer a conta de superuser:

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


Observações: Se você está usando outro BD, como PostGRE ou MySQL você deve apagar os bancos usando a sintaxe própria de seu gerenciador. Outras informações podem ser encontradas em Techiediaries: Resetting Django Migrations, inclusive sobre como zerar as migrations em produção, manualmente ou usando um app para isso.

Usando o app ampliado

Depois de termos ampliado as definições de nossos modelos, devemos incluir nos novos modelos em admin.py para que eles possam ser gerenciados pelo admin.
app-notas/notas/admin.py

from django.contrib import admin
from notas.models import Caderno, Categoria, Nota

admin.site.register(Caderno)
admin.site.register(Categoria)
admin.site.register(Nota)

Agora é possível entrar dados visitando o site de administração do django. Notamos que, se definirmos antes categorias e cadernos o admin apresenta uma caixa dropdown contendo as escolhas possíveis desses dados sempre que inserimos ou editamos notas.

Para finalizar essa etapa vamos exibir os novos campos na página inicial e nos detalhes exibidos. Ajustamos o arquivo inicial de templates para receber os dados adicionais.
app_notas/templates/home.html

{% extends "base.html" %}
{% block title %}
  <h1>Aplicativo de Notas</h1>
{% endblock %}
{% block content %}
  <h1>Página inicial</h1>
  <p>Essas são as minhas notas (clique para visualizar).</p>
  <table class="dados_notas">
    <tr><th>Caderno</th><th>Categoria</th>
    <th>Nota</th><th>Criada em</th><th>Editada em</th>
    <th>clique para editar</th></tr>
    {% for nota in notas %}
      <tr>
        <td>{{ nota.caderno }}</td><td>{{ nota.categoria }}</td>
        <td>{{ nota }}</td>
        <td>{{ nota.data_criada|date:"d/m/Y" }}</td><td>
        {{ nota.data_editada|date:"d/m/Y" }}</td>
        <td><a href="/nota/{{ nota.pk }}/">{{ nota.pk }}</a></td>
      </tr>
    {%endfor%}
  </table>
{% endblock %}

E acrescentamos formatação css para essa tabela, definida sob a classe dados_notas (mostrando só os acréscimos):
app_notas/static/css/estilo.css

.dados_notas {text-align:left; border-collapse:collapse;}
.dados_notas tr, th, td {border:1px solid #aaa; padding:10px 30px;}    

Visitando a página incial veremos, no navegador:

Para visualizar detalhes da nota alteramos:
app_notas/templates/detalhe.html

{% extends "base.html" %}
{% block title %}
  <h1>Aplicativo de Notas: Detalhes</h1>
{% endblock %}

{% block content %}
  {% if secao == "erro" %}
    <h1>Nenhuma nota foi encontrada!</h1>
    <h2>Nota: {{ nota }}</h2>
  {% else %}
    <h1>Detalhe de uma nota</h1>
    <p><b>Caderno:</b> {{ nota.caderno }}</p>
    <p><b>Categoria:</b> {{ nota.categoria }}</p>
    <h2>Nota: {{ nota.titulo }}</h2>
    <p>{{ nota.texto|safe }}</p>
    <p>Postada em: {{nota.data_criada|date:"d/m/Y"}}</p>
    <p>Editada em: {{nota.data_editada|date:"d/m/Y"}}</p>
    <p><small>Id: {{ nota.pk }} Slug: {{ nota.slug }}</small></p>
  {% endif %}
{% endblock %}

Visitando uma página de detalhes (por exemplo clicando no link da página home) veremos:

Django Admin

A página de administração do django funciona como um app pre-desenvolvido. Ela é voltada para administradores e não deve ser usada para a interação de usuários com o site. Mesmo assim vale considerar algumas formas possíveis de aprimorar esse uso.

A referência para todo o controle do admin está em settings.py do aplicativo notas, enquanto a url que direciona para esse aplicativo está em urls.py do projeto:

# Em notas/settings.py:
INSTALLED_APPS = ['django.contrib.admin',  ... ]

# Em app_notas/urls.py
urlpatterns = [path('admin/', admin.site.urls), ...]

Para acessar o admin precisamos criar um usuário com poderes de administrador, (superuser)

$ python manage.py createsuperuser

Já vimos que, ao listar objetos de qualquer tabela, o admin usa a representação de string, definida com o modelo. Foi o que fizemos em, por ex. em models.py:
app_notas/notas/models.py

class Nota(models.Model):
    titulo = models.CharField(default='', max_length=150)
    ...
    def __str__(self):
        return self.titulo

Para customizar o texto exibido na página do admin acrescentamos as linhas à urls.py:
apps_notas/urls.py

urlpatterns = [ ... ]
admin.site.site_header  =  "Admin: Anotações"
admin.site.index_title  =  "Controle de Tabelas:  Anotações"

Vimos também quem nossos modelos são registrados em notas/admin.py. Podemos também ajustar a forma de exibição dos campos, acrescentar um campo de pesquisa sobre campos escolhidos da tabela e inserir filtros que limitam a exibição dos dados. Para isso criamos classes que herdam de admin.ModelAdmin e as registramos junto com os modelos.
apps_notas/notas/admin.py

from django.contrib import admin
from notas.models import Caderno, Categoria, Nota
 
class CadernoAdmin(admin.ModelAdmin):
    search_fields = ('titulo',)

class CategoriaAdmin(admin.ModelAdmin):
    list_filter = ('categoria',)
    search_fields = ('categoria',)

class NotaAdmin(admin.ModelAdmin):
    list_display = ('titulo', 'caderno', 'categoria', 'data_criada', 'data_editada',)
    list_filter = ('categoria', 'data_criada',)
    search_fields = ('titulo',)

admin.site.register(Caderno, CadernoAdmin)
admin.site.register(Categoria, CategoriaAdmin)
admin.site.register(Nota, NotaAdmin)

Feito isso visitamos a página ao admin e clicamos em Notas. A seguinte página é exibida:

O registro em admin.site disponibiliza o modelo para o app admin. Caso não se queira exibir um dos modelos no admin basta omitir esse registro.

Duas outras possibilidades são as de excluir um campo na página de edição das tabelas do admin e agrupar a exibição de dados sob um campo tal como datas.
apps_notas/notas/admin.py

class NotaAdmin(admin.ModelAdmin):
    ....
    date_hierarchy = 'data_criada'
    exclude = ( 'data_criada', 'data_editada',)

O primeiro filtro cria uma seleção acima da lista, por data de edição. O segundo exclue, no formulário do admin para edição de notas, os campos data_criada e data_editada. Isso é possível uma vez que ambas as datas são inseridas automaticamente com o parâmetro auto_now=True.

Formulários html no Django

Um formulário HTML é uma página construída com marcação html usada para o preenchimento de dados no navegador e habilitada para enviar esses dados para o servidor. Ela é formada por widgets que são campos de textos, caixas de seleção, botões, botões de rádio e checkboxes.


Formulários são uma das formas mais comuns de interação entre usuários e uma aplicação na Web. O django traz mecanismos para facilitar a criação de formulários e integrá-los com o aplicativo. Para experimentar com os formulários vamos criar um formulário de inserção e outro de edição de notas existente.

Inserindo uma nota: Primeiro inserir uma url para requisitar uma páginas de inserção de dados. Podemos fazer isso como (mostrando só alterações):
notas/urls.py

urlpatterns = [
    ...
    path('inserir/', views.inserir, name='inserir'),
]

Claro que temos que criar uma view para receber essa solicitação. Mas antes criaremos uma classe derivada de django.forms.ModelForm, responsável pela geração de um formulário. Gravamos o seguinte arquivo em
app_notas/notas/forms.py

from django.forms import ModelForm
from .models import Nota

class NotaForm(ModelForm):
    class Meta:
        model=Nota
        fields=['titulo', 'texto', 'caderno', 'categoria']    

A classe ModelForm descreve um formulário. Ela pode acessar as informações sobre os campos do modelo e os representar em um formulário. A class Meta é usada para modificar as propriedades da classe externa onde foi definida. Dentro dela fazemos a associação com o modelo sendo exibido e os campos que se pretende editar.

Os campos data_criada, data_editada e slug são criados automaticamente e não precisam estar no formulário de inserção de notas. Para inserir todos os campos, caso isso seja o desejado, podemos usar fields = ‘__all__’. A ordem dos campos declarados será respeitada na exibição do formulário.

Inserimos uma view para processar a requisição:
app_notas/notas/views.py

from django.shortcuts import render, get_object_or_404, redirect
from .models import Nota
from .forms import NotaForm
...

def inserir(request):
    form=NotaForm()
    if request.method=='POST':
        form=NotaForm(request.POST)
        if form.is_valid():
            nota=form.save(commit=False)
            nota.save()
            return detalhePK(request, nota.pk)

    contexto = {'section':'inserir','form': form,}    
    return render(request, 'inserir.html', contexto)    

O parâmetro request recebe os dados inseridos na requisição. Se um formulário foi preenchido e enviado o método de requisição foi POST. Um objeto form é carregado com esses dados. Se os dados estão inseridos corretamente eles são gravados. Se não for válida (se algum campo necessário não foi preenchido, ou um email está em formato incorreto, por ex.) um formulário vazio é reexibido.

O uso de nota=form.save(commit=False) armazena na variável um objeto ainda não gravado. Neste intervalo uma validação ou manipulação manual de dados pode ser feita. Se considerado correto o objeto é gravado com nota.save(). Se a nota for gravada corretamente a função view detalhePK() é chamada para exibir a nota recém gravada. O template inserir.html deve conter os comandos para a exibição do formulário.
app_notas/templates/inserir.html

{% extends "base.html" %}
{% block title %}<h1>Inserindo uma nota</h1>{% endblock %}
{% block content %}
<form action="{% url 'inserir' %}" method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <button class="button" type="submit">Inserir</button>
</form>
{% endblock %}

A ação disparada pelo clique no botão de inserir está descrita na tag action = {% url 'inserir' %}, um acesso à view descrita acima, com método POST. O token {% csrf_token %} acrescenta uma proteção contra ataques do tipo CSRF (Cross Site Request Forgeries), e {{ form.as_p }} faz a listagem HTML dos campos definidos em notas/forms.py, dispostos em parágrafos sucessivos. Também podemos dispor as campos do formulário como {{ form.as_ul }}, dispostos em uma lista não ordenada, ou {{ form.as_table }}, com os campos dentro de uma tabela.

Para acessar a página de inserção sem necessidade de escrever a URL completa, vamos colocar no cabeçalho de base.html um link com esse endereço. Alterando o código logo abaixo de <body> em (exibindo só trecho modificado):
app_notas/templates/base.htlm

<ul class="menu">
    <li><a class="{% if secao == 'home' %}
    active {% endif %}" href="{% url 'index' %}">Início</a></li>
    <li><a href="{% url 'inserir' %}">Inserir Nova Nota</a></li>
    <li><a href="/admin/">Admin</a></li>
  </ul>

Ao clicar em Inserir Nova Nota o seguinte formulário é exibido. Quando preenchido, se clicamos no botão Inserir a nota é gravada e exibida. Resta-nos agora escrever o código para editar ou apagar uma nota já inserida.

Editando uma nota: de forma similar, vamos alterar o projeto para que possamos editar notas existente e apagá-las. A url será recebida por:
app_notas/notas/urls.py

urlpatterns = [
    ...
    path('inserir/', views.inserir, name='inserir'),
    ...
    path('editar/<int:pk>/', views.editar, name='editar'),
]

Podemos usar o mesmo objeto NotaForm já criado, desde que aceitemos que os campos data_criada, data_editada e slug continuem sendo geridos automaticamente.

Uma nova view será incluída para a edição:
notas/views.py

...

def editar(request, pk):
    nota = get_object_or_404(Nota, pk=pk)
    form=NotaForm()
    if request.method=='POST':
        form=NotaForm(request.POST, instance=nota)
        if form.is_valid():
            nota=form.save(commit=False)
            nota.save()
            return detalhePK(request, nota.pk)

    contexto = {'section':'editar','form': form,}
    return render(request, 'editar.html', contexto)    

Como antes, um formulário preenchido corretamente é gravado e a nota editada é exibida. O template editar.html deve conter os comandos para a exibição do formulário.

app_notas/templates/editar.html

{% extends "base.html" %}
{% block title %}<h1>Editando uma nota</h1>{% endblock %}
{% block content %}
<form action="{% url 'editar' %}" method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <button class="button" type="submit">Gravar</button>
</form>
{% endblock %}

Para dar acesso à página de edição, tendo escolhido uma nota, inserimos uma coluna na página que lista todas as notas em home.html (exibindo só a tabela que contém a lista de notas):
app_notas/templates/home.html

<table class="dados_notas">
    <tr><th>Caderno</th><th>Categoria</th><th>Nota</th>
    <th>Criada em</th><th>Editada em</th><th>visualizar</th>
    <th>editar</th></tr>
    {% for nota in notas %}
      <tr>
        <td>{{ nota.caderno }}</td>
        <td>{{ nota.categoria }}</td>
        <td>{{ nota }}</td>
        <td>{{ nota.data_criada|date:"d/m/Y" }}</td>
        <td>{{ nota.data_editada|date:"d/m/Y" }}</td>
        <td><a href="/nota/{{ nota.pk }}/">Índice = <b>{{ nota.pk }}</b></a></td>
        <td><a href="/editar/{{ nota.pk }}/">Editar: <b>{{ nota.pk }}</b></a></td>
      </tr>
    {%endfor%}
  </table>

Ao clicar em Editar um formulário idêntico ao formulário de edição aparece com os campos já preenchidos, permitindo sua edição. Novamente, ao serem gravados a tela de exibição de notas é mostrada.

Em app_notas/notas/views.py, na função editar(), uma nota específica é carregada e usada para instanciar um objeto NotaForm. Uma NotaForm(instance=nota) é exibida para edição no primeiro carregamento do formulário. Se o botão de Gravar foi clicado a view é acionada com request.method=='POST'. Isso faz com que os dados do formulário sejam gravados, se o formulário é válido.

Apagar uma nota já inserida: Para apagar uma nota já inserida, em urls.py inserimos
app_notas/notas/urls.py

urlpatterns = [
    ...
    path('apagar//', views.apagar, name='apagar'),
]

Em forms.py inserimos a definição de um formulário sem a exibição de campos:
notas/forms.py

class ApagarNotaForm(ModelForm):
    class Meta:
        model=Nota
        fields=[]

O próximo passo é acrescentar uma view para o apagamento em views.py
notas/views.py

...
from .forms import NotaForm, ApagarNotaForm
...
def apagar(request, pk=None):
    nota=get_object_or_404(Nota, pk=pk)
    if request.method=="POST":
        form=ApagarNotaForm(request.POST, instance=nota)
        if form.is_valid():
            nota.delete()
            return redirect('home')
    else:
        form=ApagarNotaForm(instance=nota)
        contexto={'section':'apagar', 'form': form, 'nota': nota,}
        return render(request,'blog/delete.html', contexto)

Um template para confirmar a escolha do usuário em apagar uma nota pode ter o seguinte conteúdo:
app_notas/templates/apagar.html

{% extends "base.html" %}
{% block title %}<h1>Apagando uma Nota</h1>{% endblock %}
{% block content %}
<form action="{% url 'apagar' nota.pk%}" method="post">
    {% csrf_token %}
    {{ form }}
    <h2>Título da Nota: {{ nota.titulo }}</h2>
    <p style="margin-left:10em;">{{ nota.texto | safe }}</p>
    <p>Tem certeza de que deseja apagar essa nota:? <button class="button" type="submit">Apagar</button>
    Cancelar</p>
</form>
{%endblock%}

Agora, na lista geral de notas, ao clicar Apagar somos levados à página com a opção de apagamento, que lista título e conteúdo da nota. Confirmando o apagamento a view.apagar é acionada com method=="POST". Clicando Cancelar a página inicial, com a lista de notas é exibida.

É claro que muitas otimizações podem ser feitas nesse código. Por exemplo, poderíamos ter apenas uma view para inserir | editar | apagar, passando parâmetros que executem cada uma das opções. Também podemos fazer muitos aperfeiçoamentos na interface visível para o usuário, melhorando os templates e usando CSS. Para ilustrar alguns possíveis aprimoramentos vamos melhorar a aparência da página inicial, que contém uma lista de notas, com as várias possibilidades de edição.

Primeiro alteramos views.py (mostrando só alterações):
app_notas/notas/views.py

from . import funcoes

def index(request):
    #notas = Nota.objects.all() (removemos essa linha)
    notas = Nota.objects.order_by('caderno','categoria', 'data_editada')
    notas = funcoes.transforma_notas(notas)
    contexto = {'secao':'home', 'mensagem':'Item de Menu', 'notas': notas,}
    return render(request, 'home.html', contexto )

Fazendo notas = Nota.objects.order_by('caderno','categoria', 'data_editada') o objeto notas será uma coleção de notas, agora ordenadas por ‘caderno’,’categoria’, ‘data_editada’, nessa ordem de prioridade.

Suponha agora que queremos montar uma lista onde nomes de cadernos e categorias repetidas não apareçam, na lista. Isto é: em cada linha cadernos e categorias, agora ordenados nessa ordem, não são exibidos repetidamente. Para isso acrescentamos um arquivo funcoes.py:
app_notas/notas/funcoes.py

def transforma_notas(notas):
    cat = ""
    cad = ""
    for nota in notas:
        if cat == nota.categoria.categoria:
            nota.categoria.categoria = ""
        else:
            cat = nota.categoria.categoria

        if cad == nota.caderno.titulo:
            nota.caderno.titulo = ""
        else:
            cad = nota.caderno.titulo
    return notas    

Essa função transforma em strings vazias os cadernos e categorias repetidos, de forma a que a lista só contenha essa informação quando ela é alterada. Por fim alteramos home.html:
templates/home.html

{% extends "base.html" %}
{% block title %}<h1 style="margin-top:80px;" >Aplicativo de Notas</h1>{% endblock %}

{% block content %}
<table class="dados_notas">
  <tr><th>Caderno</th><th>Categoria</th><th>Nota</th><th>Criada</th><th>Editada</th><th>Ver</th><th>Editar</th><th>Apagar</th></tr>
  <tr><td colspan="8" style="border-bottom: 1px solid #999;"></td></tr>
  <tr><td colspan="8"></td></tr>
  {% for nota in notas %}
  <tr>
    <td style="font-size:2em; font-weight: bold;">{{ nota.caderno }}</td>
    <td style="font-size:1.5em; font-weight: bold;">{{ nota.categoria }}</td>
    <td>{{ nota.titulo }}</td>
    <td>{{ nota.data_criada|date:"d/m/Y" }}</td>
    <td>{{ nota.data_editada|date:"d/m/Y" }}</td>
    <td><a href="/nota/{{ nota.pk }}/">📖</a></td>
    <td><a href="/editar/{{ nota.pk }}/">📝</a></td>
    <td><a href="/apagar/{{ nota.pk }}/">🚮</a></td>
  </tr>
  {%endfor%}
{% endblock %}

Os caracteres 📖, 📝 e 🚮 podem ser copiados e colados diretamente nos templates (ou qualquer outra página html). Alteramos ainda o arquivo estilo.css (mostrando só as alterações):
app_notas/static/estilo.css

.menu > li > a {
    background-color: rgb(21, 59, 141);
    border: 1px solid rgb(6, 6, 39);
    color: #fff;
    padding: 10px 20px;
    text-align: center;
    font-size: 16px;
    margin: 4px 2px;
    cursor: pointer;
}
.menu > li > a.ativa { font-weight:bold; }

Acessando nossa homepage temos agora:

Na imagem acima supomos que temos notas inseridas com esses cadernos, categorias, e títulos.

Muitos outras aperfeiçoamentos podem ser pensados para esse aplicativo de notas. Podemos, por exemplo, fazer as categorias serem dependentes dos cadernos, abrir um conjunto novo de notas para cada usuário, permitir a entrada de sub-categorias em vários níveis, criar um conjunto de tags para aplicar a cada nota, criando uma estrutura de relacionamentos entre tags de modo que o usuário possa navegar entre notas associadas a uma mesma ideia ou conceito.

Importante lembrar que, como estamos dentro de uma estrutura de programação do python, qualquer módulo importado para finalidades diversas pode ser facilmente incorporados no site ou aplicativo. Isso inclue pacotes de análise de texto, tratamento e exibição de dados, recursos de geo-referência, etc.

Artigos Django

1- Django, Websites com Python
2- Django, um Projeto
3- Django, incrementando o Projeto (esse artigo)

Bibliografia

Consulte a bibliografia no artigo inicial.

Um projeto Django


Desenhando um projeto

Para efeito de nosso aprendizado vamos desenvolver um aplicativo para a tomada de anotações. Começaremos com uma tabela simples de notas, com os seguintes campos:

Notas
id titulo texto slug
0 Introdução ao Python Texto da nota sobre python introducao-ao-python
1 Django Texto da nota sobre django django
2 Python para Web Texto da nota sobre python para web python-para-web

Os valores na tabela são ilustrativos. O slug, como veremos, é um tipo de atalho representativo da nota, criado automaticamente e usado na url de acesso à informação. Depois introduziremos aperfeiçoamentos à essa estrutura de dados.

Criando o projeto do django

Uma vez instalados os módulos necessários, com o ambiente virtual ativado, usamos um comando para criar um projeto do django. No primeiro uso do django algum ajuste deve ser providenciado. De dentro do diretório onde será construído o aplicativo executamos, no prompt de comando:

(env) $ django-admin startproject app_notas


Esse comando cria uma estrutura básica de um site. Observe que, diferente de aplicativos em PHP e outros, o aplicativo django não fica no diretório raiz de um servidor web, o que é uma boa coisa considerados os riscos de segurança.

Esses arquivos são:

app_notas diretório raiz do projeto, pode ser renomeado. Nós o chamaremos de app_notas.
manage.py utilitário de comando de linha para interação com o projeto Django.
app_notas subdiretório, é o módulo Python do aplicativo. Esse nome será usado nas importações futuras.
app_notas/__init__.py arquivo vazio para marcar esse diretório como um módulo.
app_notas/settings.py Configurações para esse projeto.
app_notas/urls.py as declarações de URLs para o projeto.
app_notas/asgi.py ponto de entrada para ASGI web servers.
app_notas/wsgi.py ponto de entrada para WSGI web servers.

O arquivo __init__.py (que pode ser vazio) serve para marcar seu diretório como um módulo do python. Dentro desse módulo podem existir classes que podem ser importadas em outras partes do projeto.

Se você usar controle de versão coloque o diretório projeto_django sob o controle do git. Um arquivo README.md deve ser colocado no diretório raiz, com especificações sobre o projeto.

manage.py

Mais informações em: Django Docs: Manage.py

Dentro do arquivo manage.py é estabelecida uma variável global que indica onde estão, para esse projeto, as configurações.
A variável global DJANGO_SETTINGS_MODULE aponta para o arquivo settings.py, onde se encontram diversas variáveis de controle do sistema.
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'app_notas.settings')
Em settings.py existem diversas variáveis. Entre elas vamos listar apenas algumas:

# Caminho para projeto
BASE_DIR = Path(__file__).resolve().parent.parent

# Debug, booleano. True durante o desenvolvimento. Deve ser tornada False na produção
DEBUG = True

INSTALLED_APPS = [...]             # um dicionário com aplicatyivos instalados

ROOT_URLCONF = 'app_notas.urls'    # onde estão os encaminhamentos de URLs padrão

TEMPLATES = [ ... ]                # referências para os templates instalados

DATABASES                          # referência para o banco de dados usados. Por default SQLite

# varáveis de internationalização
LANGUAGE_CODE = 'pt-br'            # código de língua   (alterado para pt-br, português do Brasil)
TIME_ZONE = 'BRT'                  # faixa horária      (alterado para BRT, hora de Brasília)
USE_TZ = True                      # use time-zone

# onde estão arquivos estáticos (CSS, JavaScript, Images)
STATIC_URL = 'static/'

Feito isso temos um site (ou uma aplicação) montada e pronta a ser rodada. O Django fornece um servidor de desenvolvimento (que só pode ser executado se DEBUG = True).
Observação importante: Em nenhuma hipótese se deve rodar o servidor de desenvolvimento durante a produção, por motivo de segurança.

O servidor de desenvolvimento é iniciado com

$ python manage.py runserver
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Observação: nessas notas vamos representar o prompt simplesmente por $, lembrando que estamos trabalhando em um ambiente virtual.

Se digitarmos na barra de endereço do browser a url http://127.0.0.1:8000/ poderemos ver a tela de boas vindas do django.

Outros comandos ficam disponíveis com manage.py, entre eles:

runserver inicia o servidor de desenvolvimento.
startapp cria um app no Django.
shell inicia uma shell no interpretador com o projeto Django carregado.
dbshell inicia uma shell conectada ao banco de dados em uso, onde se pode rodar queries manualmente.
makemigrations generate alterações no banco de dados definidas pelos modelo.
migrate aplica as alterações geradas por makemigrations.
test roda testes automatizados.

Mais informações no site do Django: Admin e manage.py.

Criando Apps

No Django um projeto pode ter diversos Apps. Um app é um módulo contendo uma parte da funcionalidade do projeto. Por exemplo, nosso projeto de notas pode conter um app para a acesso e modificação das notas, um outro para registrar notas que são agendamentos e calendário, e ainda um terceiro para gerenciar a acesso de vários usuários cadastrados para uso do app.

Para criar um app usamos a comando de linha:

$ python manage.py startapp <nome_do_app>
# no nosso caso
$ python manage.py startapp notas

A seguinte estrutura de diretórios é gerada:

admin.py permite ajuste da página de administração, automaticamente crada pelo django.
apps.py configuração específica do app.
models.py deve conter os modelos geradores das tabelas do banco de dados.
tests.py armazena os testes para debugging.
views.py definição das visualizações.
migrations pasta que armazena as alterações em banco de dados, para sincronização.

O arquivo db.sqlite3, o arquivo do SQlite, é gerado e modificado com as migrações.

Como inserimos um novo app ao projeto, temos que informar isso no arquivo settings.py, na lista INSTALLED_APPS. Fazemos a seguinte modificação:
notas/settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    ... linhas omitidas
    'notas',
]

Inserimos a linha em negrito, com referência para o app notas. As demais linhas foram criadas pelo django.

Quando uma requisição é feita ao navegador, por meio de uma URL, o django passa essa requisição pelo arquivo urls.py. Se nenhuma das linhas de url forem satisfeitas uma mensagem de erro é emitida. O erro é bastante detalhado em modo de desenvolvimento, com DEBG = True, e exposto no navegador.

Vamos portanto criar uma url que pode ser reconhecida pelo aplicativo. Inicialmente vamos receber a url sem parâmetro e retornar uma página de Boas Vindas. Para isso inserimos no arquivo:
notas/urls.py

import notas.views
from django.contrib import admin
from django.urls import path

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', notas.views.index),
]

A próxima etapa é a criação de uma view. Para isso editamos o arquivo notas.views e inserimos uma função denominada index. Vamos fazer isso em etapas, para compreender o funcionamento de views.
notas/views.py

from django.http import HttpResponse

def index(request):
    return HttpResponse("Meu primeiro site!")

Se você executar python manage.py runserver e abrir o navegador (em http://127.0.0.1:8000/) veremos, na página do navegador, a frase:

Tags html podem ser passadas, por exemplo para enviar esse texto como um título nível 1, como em return HttpResponse("<h1>Meu primeiro site!</h1>")

Alternativamente podemos retornar uma página pronta de html. Mudamos o conteúdo de views para:
notas/views.py

from django.shortcuts import render

def home(request):
    return render(request,'home.html')

Observação: Os objetos (no caso funções) HttpResponse e render são importadas de seus respectivos módulos de origem. No segundo caso a função render chama um “template” (um modelo de página html) passando para ele o conteúdo de render, como veremos.

Para criar o template vamos gerar nova pasta e um novo arquivo html: Arquivo home.html, lembrando que app_notas é a pasta raiz do projeto:
app_notas/templates/home.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
</head>
<body>
    <h1>Página inicial do aplicativo de Notas</h1>
    <p>Essas são as minhas notas.</p>
</body>
</html>    

Finalmente informamos em settings.py que usaremos um diretório em os.path.join(BASE_DIR,'templates'), lembrando que BASE_DIR é a pasta raiz do projeto. Não podemos esquecer de importar o módulo os.
app_notas/settings.py

import os

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        ': [os.path.join(BASE_DIR,'templates')],
        'APP_DIRS': True,
        ...
    },
]

Agora, quando executamos o servidor e abrimos a página no navegador veremos, devidamente renderizado:


Observação: No arquivo settings.py temos a variável TEMPLATES que é uma lista de dicionários. Nela estão definidas DIRS e APP_DIRS. DIRS define uma lista de diretórios onde o código deve procurar por arquivos de template, em ordem de prioridade. APP_DIRS é booleana. Se True o código deve procurar por templates dentro dos diretórios de aplicativos instalados.

Vimos, até agora, que aplicativos são usados para adicionar recursos ao projeto. O aplicativo é conectado ao projeto com a adição de sua classe de configuração à lista INSTALLED_APPS do arquivo settings.py. O reconhecimento das URLs recebidas pela navegador é feito no arquivo urls.py, que associa a requisição à visualização em views.py que retorna um conteúdo para um template.

Templates

Um template é um arquivo de texto com conteúdo em html e marcação adicional de tags do django que permitem a inserção dinâmica de conteúdo no template. Essas tags podem conter variáveis e determinar fluxo de código, bem similar à própria sintaxe do python. Por exemplo, suponha que enviamos para um template (já veremos como fazer isso) uma lista (ou qualquer objeto iterável) em um variável notas = ["nota1", "nota2","nota3"]. O seguinte template seria traduzido e enviado para o navegador na forma mostrada à direita:

  <ul>
  {% for nota in notas %}
    <li>{{ nota }}</li>
  {%endfor%}
  </ul>  
<ul>
<li>nota1</li>
<li>nota2</li>
<li>nota3</li>
</ul>
Todas as tags, classes e ids html podem ser formatados com CSS, da maneira usual. Observe que estamos chamando de tags dois objetos diferentes: tags html são as usuais p, h1, ul, .... Tags do django são marcações para inserir conteúdos em templates.

Tags do django são adicionadas com a sintaxe: {% tag %} enquanto variáveis são avaliadas e expostas para o código html com {{ variavel }}. Exemplos disso são:{% for %} conteúdo {% endfor %}. Objetos podem ter seus atributos consultados com a notação de ponto, {{ objeto.atributo }}. Filtros podem ser usados para modificar valores de variáveis, usando-se uma barra vertical (|). Por ex.: {{ nota|truncatechars:5 }} trunca a string em 5 caracteres.

Herança de templates

Supondo que a maior parte (ou todas) das páginas de nosso site têm a mesma estrutura, o que costuma ocorrer, podemos criar um template base importado e extendido pelas páginas.

No diretório da aplicação templates criamos o arquivo base.html:
template/base.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Notas</title>
</head>
<body>
  <ul class="menu">
    <li><a href="{% url 'index' %}">Home</a></li>
  </ul>
  {% block title %}
  {% endblock %}
  {% block content %}
    Esse é meu site de Notas
  {% endblock %}
</body>
</htmlglt;

O arquivo home.html fica modificado assim:
template/home.html

{% extends "base.html" %}
{% block title %}
  <h1>Aplicativo de Notas</h1>
{% endblock %}

{% block content %}
  <h1>Página inicial</h1>
  <p>Essas são as minhas notas.</p>
{% endblock %}

Esse arquivo home.html herda a estrutura de base.html, substituindo nele o conteúdo dos blocos de mesmo nome. Um bloco pode ser omitido no arquivo filho e, nesse caso o conteúdo original de base.html é exibido.

Antes de executar esse site vamos fazer mais algumas alterações: o arquivo urls.py fica da seguinte forma:
app_notas/urls.py

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

urlpatterns = [
    ...
    path('', include('notas.urls')),
]

Após importar include, indicamos que o padrão de url vazio (ou outro que não for casado com as urls atuais) será redirecionado para notas.urls que criaremos a seguir. Na pasta do aplicativo gravamos urls.py:
notas/urls.py

from django.urls import path
from . import views

urlpatterns = [
    path('', views.index, name='index'),
]

Esse arquivo importa views que está na mesma pasta (.) e remete chamadas para views.index. Quando executamos python manage.py runserver e abrimos o navegador vemos a página:

O link <a href="{% url 'index' %}">Home</a> no topo do arquivo base.html será exibido em todas as páginas que herdam esse código. Ele contém um referência ativada pela função url do django, com o parâmetro index. Esta é uma forma de evitar que façamos referências com urls fixas nas páginas do aplicativo.

Arquivos Estáticos e CSS


Claro que páginas html sem nenhuma formatação não satisfazem a demanda de nenhum usuário moderno. Para que as páginas html tenham acesso aos arquivos de formatação CSS precisamos indicar para o django onde encontrar esses arquivos, além imagens e outros arquivos estáticos.

Vamos começar criando os diretórios static e static/css dentro do diretório raiz do projeto. Dentro criamos o arquivo estilo.css (usando aqui apenas algumas poucas configurações, apenas para demonstrar o funcionamento).
static/css/estilo.css

body { width:80%; margin: 5% 10%; }
h1 { color:navy; }    
.menu { list-style:none; padding-left:0; }
.menu > li { display:inline-block; }
.menu > li > a { text-decoration:none; color:#000; margin:00.3em; }
.menu > li > a.active { padding-bottom:0.3em; border-bottom:2px solid #528DEA; }

Temos que informar ao django onde estão os arquivos estáticos, modificando settings.py:
app_notas/settings.py

STATIC_URL='/static/'

STATICFILES_DIRS = [os.path.join(BASE_DIR,'static'),]

INSTALLED_APPS = [
    ...
    'django.contrib.staticfiles',
    'notas',
]

Lembrando que já temos, como mostrado acima, o dicionário
INSTALLED_APPS = [ …, ‘django.contrib.staticfiles’,…]
com a indicação para acessar arquivos estáticos. Toda essa configuração só deve ser usada com projetos na fase de desenvolvimento. Veremos depois qual deverá ser o ajuste na produção.

No template base.html fazemos as alterações (apenas as modificações são mostradas):
templates/base.html

<!DOCTYPE html>
{% load static %}
<html lang="en">
<head>
    <meta charset="UTF-8">
    <link rel="stylesheet" href="{% static'css/estilo.css' %}">
    ...
</head>
...

A tag {% load %} torna disponíveis tags e filtros para esse template. Aqui usamos staticpara dar acesso à URL do arquivo CSS. Alteramos agora
app_notas/notas/views.py

from django.shortcuts import render

def index(request):
    contexto = {'secao':'home', 'mensagem':'Vou colocar outro link aqui!'}
    return render(request,'home.html', contexto)

O dicionário contexto contém variáveis que podem ser usadas dentro de home.html. O nome da variável é passado como string. Alteramos o template base para receber essas variáveis:
templates/base.html

<body>
  <ul class="menu">
    <li><a class="{% if secao=='home' %} active {% endif %}
    "href=" {% url 'index' %}">Início</a></li>
    <li>{{ mensagem }}</li>
  </ul>
  {% block title %}

Esse código faz o seguinte: se secao == 'home' o primeiro ítem da lista terá classe active com formatação definida no arquivo CSS. A variável mensagem = 'Vou colocar...' foi usada para demonstração e se torna o segundo ítem da lista. O conteúdo da variável mensagem é servido para o html com a sintaxe {{ mensagem }}. O resultado será uma exibição formatada na navegador.

Se o link sublinhado for clicado a mesma página será carregada. Claro que o link pode se referir a qualquer outra página.

Você pode ver o que foi carregado olhando page source (CTRL-U, no firefox). Nessa página um clique em estilo.css deverá exibir os estilos.

Pode ocorrer que você faça alterações no arquivo css e elas não se reflitam na renderização do navegador, mesmo após um recarregamento. Isso provavelmente ocorre porque o navegador coloca em cache parte das informações recebidas pelo servidor. Isso pode ser resolvido forçando o navegador a ver o arquivo de estilo como um novo arquivo. Para isso colocamos um parâmetro após o nome do estilo:
<link rel="stylesheet" href="{% static 'css/estilo.css' %}?v=1">.

Modelos

Até agora não mencionamos como o django lida com o gerenciamento dos dados a serem servidos nos aplicativos. Essa é a parte de construção, gerenciamento e leitura em bancos de dados. Continuaremos com nosso banco de dados do SQlite, que não exige uma instalação específica de servidor de dados.

Modelos estão definidos no django em django.db.models. Para usá-los criamos subclasses desse classe. Editamos o arquivo de modelos:
notas/model.py

from django.db import models

class Nota(models.Model):
    titulo = models.CharField(default='', max_length=150)
    texto = models.TextField(default='', blank=True)
    slug = models.SlugField(default='', blank=True, max_length=255)

    def __str__(self):
        return self.titulo

O django tem código pré-definido para transformar essas definições em modificações no banco de dados. Isso é feito com os comandos manage.py makemigrations e manage.py migrate, que já utilizaremos. Quase sempre cada modelo representa uma tabela no BD. No nosso caso definimos um campo titulo, de texto com comprimento máximo de 150 caracteres, e um campo texto, de texto sem comprimento definido e que pode ser gravada vazia. O campo slug será destinados a armazenar partes das URLs de acesso a cada nota. Todos eles tem uma string vazia como valor default e pode conter apenas caracteres, números, hífens e sublinhados.

O método __str__ define o que será usado como representação da classe. Por exemplo print(Nota) imprimirá o título da nota. Ids são definidos automaticamente.

Vamos primeiro registrar esse modelo para ser usado com o app admin.py, pre-definido pelo django e ainda não usado por nós.

notas/admin.py
notas/admin.py

from django.contrib import admin
from blog.models import Nota

admin.site.register(Nota)

Feito isso podemos aplicar as alterações no bando de dados.

$ python manage.py makemigrations
$ python manage.py migrate
$ python manage.py createsuperuser
# caso se necessite trocar a senha usamos:
$ python manage.py changepassword <nome_do_usuário>

O comando makemigrations interpreta as modificações feitas em código e as armazena na pasta notas/migrations. Elas serão usadas mais tarde para aplicar as mesmas modificações na fase de produção. Quando usamos o comando migrate as alterações são aplicadas no SQlite. Se o arquivo app_notas/db.sqlite3 for inspecionado (por exemplo com o DB Browser for SQLite) veremos que estão armazenadas as estrutura da tabela notas, como mostra a figura.

Com createsuperuser se abre um diálogo para inserirmos nome, email e password de um superuser que gerenciará o admin, com todas as permissões, por default.

Se você carregar o servidor com python manage.py runserver e abrir a navegador em http://127.0.0.1:8000/admin/ verá uma página de administração do site, com possibilidade de gerenciar grupos e usuários, tudo predefinido pelo django. Além disso temos acesso para operações de CRUD da tabela Notas.

Nesse ponto, como um exercício, abra o gerenciador e faça inserções de notas no aplicativo. Observe que alguma validação é feita, por exemplo impedindo que gravemos uma nota sem título.

Link para Admin

Para acessar a página do admin sem necessitar escrever uma url completa para isso vamos alterar o arquivo base.hmtl e inserir nele esse link.
app_notas/templates/base.hmtl

<body>
  <ul class="menu">
    <li><a class="{% if secao == 'home' %} active {% endif %}"
    href=" {% url 'index' %}">Início</a></li>
    <li><a href="/admin/">Admin</a></li>
  </ul>
  ...

Exibimos aqui apenas a lista não ordenada que representa o nosso menu. Agora basta clicar no link Admin no cabeçalho para acessar o gerenciador.

Exibindo dados

Se você entrou dados no banco de dados usando a página de admin agora você pode exibí-las em seu site. Para isso modificamos views.py.
app_notas/notas/views.py

from django.shortcuts import render
from .models import Nota

def index(request):
    notas = Nota.objects.all()
    contexto = {'secao':'home', 'mensagem':'Item de Menu', 'notas': notas,}
    return render(request, 'home.html', contexto)

O método Nota.objects.all() faz o acesso ao banco de dados e retorna uma QuerySet com todos os campos nele registrados. Esse código é internamente transformados em consultas sql que são submetidas ao banco de dados. Outros tipos de consulta são possíveis, com filtros e ordenamentos. O resultado da consulta, armazenado em notas, é passado em contexto para o template.

Prosseguindo, home.html deve ser modificado para receber e exibir as notas passadas em contexto.
app_notas/templates/home.html

{% extends "base.html" %}
{% block title %}
  <h1>Aplicativo de Notas</h1>
{% endblock %}

{% block content %}
  <h1>Página inicial</h1>
  <p>Essas são as minhas notas.</p>
  <ul>
  {%for nota in notas %}
    <li>{{ nota.pk }}: {{ nota }}</li>
  {%endfor%}
  </ul>
{% endblock %}

Observe que {{ nota }} exibirá a representação default do objeto, que é seu título. {{ nota.pk }} é o id (uma primary key, que poderá ser usada para identificar uma nota individual.

O navegador agora exibe, além do cabeçalho anterior, a lista contendo ids e títulos de notas (que digitei na página do admin):

Exibindo dados do Banco de Dados

Um passo adicional para melhorar nosso aplicativo consiste em exibir detalhes de uma nota selecionada pelo usuário. Para fazer isso vamos começar alterando notas/models.py.
app_notas/notas/models.py

from django.db import models
from django.urls import reverse
from django.utils.text import slugify

class Nota(models.Model):
    titulo = models.CharField(default='', max_length=150)
    texto = models.TextField(default='', blank=True)
    slug = models.SlugField(default='', blank=True, max_length=255)
    
    def __str__(self):
        return self.titulo

    def save(self,*args,**kwargs):
        self.slug = slugify(self.title)
        super().save(*args,**kwargs)
        
    def get_absolute_url(self):
        return reverse('blog:detail', args=[str(self.slug)])

Nas partes inseridas (em negrito) sobreescrevemos o método save para executar código customizado antes que o objeto seja armazenado em banco de dados. O método super().save() se refere ao método de gravação definido na classe mãe.

A função slugify converte strings para uma forma de slug. Por exemplo: A string “Um Curso sobre Django” será transformado em “um-curso-sobre-django” e esse slug será usado nas URLs.

O método get_absolute_url() retorna a URL padrão para um objeto, usando reverse que considera a view usada e a slug.

Antes de executar o código de acesso ao detalhe das notas verifique se todas as slugs estão preenchidas, usando a página de Admin.

Vamos criar duas entradas de URLs em urls.py, para encontrar uma nota através de sua slug ou por meio de seu id (aqui chamado de pk, ou primary key).
notas/urls.py

from django.urls import path
from . import views

urlpatterns = [
    path('', views.index, name='index'),
    path('index', views.index, name='index2'),
    path('slug/<slug:slug>/', views.detalhe, name='detalhe'),
    path('nota/<int:pk>/', views.detalhePK, name='detalhe2'),
]

Agora, se digitarmos http://127.0.0.1:8000/slug/django/ o slug (a palavra django, nesse caso) será capturado e enviado para a views.detalheSLUG. Digitando, por ex., http://127.0.0.1:8000/nota/1/, o pk=1 será enviando para views.detalhePK. Precisamos criar então essas views:
app_notas/notas/views.py

from django.shortcuts import render, get_object_or_404
from .models import Nota

def index(request):
    notas = Nota.objects.all()
    contexto = {'secao':'home', 'mensagem':'Item de Menu', 'notas': notas,}
    return render(request, 'home.html', contexto )

def detalheSLUG(request, slug):
    nota = get_object_or_404(Nota, slug=slug)
    contexto = {'secao':'detalhe', "nota": nota,}
    return render(request, "detalhe.html", contexto)

def detalhePK(request, pk):
    nota = get_object_or_404(Nota, pk=pk)
    contexto = {'secao':'detalhe', "nota": nota,}
    return render(request, "detalhe.html", contexto)    

O método get_object_or_404() é um atalho que executa as operações de get(), fazendo a busca e retornando o objeto procurado ou levantando uma exceção Http404 se o objeto não existir.

Finalmente gravamos template detalhe.html que receberá e exibirá esses dados:
app_notas/templates/detalhe.html

{% extends "base.html" %}
{% block title %}
  <h1>Aplicativo de Notas: Detalhes</h1>
{% endblock %}

{% block content %}
  <h1>Detalhe de uma nota</h1>
  <h2>Nota: {{ nota.titulo }}</h2>
  <p>{{ nota.texto }}</p>
  <p><small>Id: {{ nota.pk }} Slug: {{ nota.slug }}</small></p>
{% endblock %}

Agora, digitando http://127.0.0.1:8000/django/ na barra de endereços do navegador temos:

Digitando http://127.0.0.1:8000/nota/1/ temos:

Essas exibições no navegador assumem que existem notas com os títulos, ids e slugs mostrados, além do texto da nota. Observe que as tags html não estão renderizadas como tal, ou seja, as quebras de linhas são representados como <br>, e não como quebras de fato. Isso ocorre porque o django faz escape de tags, por motivo de segurança. Para que tags sejam passadas e exibidas podemos inserir o filtro {{ variavel|safe }}.

Modifique detalhe.hmtl (exibindo somente o bloco de conteúdo):
app_notas/templates/detalhe.html

{% block content %}
  <h1>Detalhe de uma nota</h1>
  <h2>Nota: {{ nota.titulo }}</h2>
  <p>{{ nota.texto|safe }}</p>
  <p><small>Id: {{ nota.pk }} Slug: {{ nota.slug }}</small></p>
{% endblock %}

Agora visitando a url http://127.0.0.1:8000/nota/1/ veremos:

Claro que não se pode esperar que usuários conheçam as slugs ou ids de uma nota. Esse dado deve ser obtido dentro do próprio aplicativo. Vamos fazer isso alterando home.html. Abaixo está exibido apenas o código dentro de block content:
app_notas/templates/home.html

{% block content %}
  <h1>Página inicial</h1>
  <p>Essas são as minhas notas (clique para visualizar).</p>
  <ul>
  {%for nota in notas %}
    <li><a href="/nota/{{ nota.pk }}/">{{ nota }}</a></li>
  {%endfor%}
  </ul>
{% endblock %}

Aqui foi feita a alteração, na listagem das notas apresentadas: ao invés de apenas listar os ids ele é usado para construir a url href="/nota/{{ nota.pk }}/.
Por motivo didático construimos duas views para receber slugs ou ids. Poderíamos ter construido uma única view que separe parâmetros inteiros (pk) de strings (slugs).

Se uma URL for inserida em busca de um id ou slug não existente uma tela de erros aparece, indicando onde está o erro. Podemos, e devemos, capturar esse erro indicando ao usuário que a busca não foi bem sucedida. Para isso alteramos o arquivo
app_notas/notas/views.py

def detalheSLUG (request, slug):
    try:
        nota = get_object_or_404(Nota, slug=slug)
        contexto = {'secao':'detalhe', 'nota': nota,}
    except:
        contexto = {'secao':'erro', 'nota': 'Nota não encontrada!',}
    return render(request, "detalhe.html", contexto)

def detalhePK (request, pk):
    try:
        nota = get_object_or_404(Nota, pk=pk)
        contexto = {'secao':'detalhe', "nota": nota,}
    except:
        contexto = {'secao':'erro', 'nota': 'Nota não encontrada!',}
    return render(request, "detalhe.html", contexto)    

O template recebe as variáveis de contexto, com um teste para a variável seção:
app_notas/templates/home.html

{% block content %}
  {% if secao == "erro" %}
    <h1>Nenhuma nota foi encontrada!</h1>
    <h2>Nota: {{ nota }}</h2>
  {% else %}
    <h1>Detalhe de uma nota</h1>
    <h2>Nota: {{ nota.titulo }}</h2>
    <p>{{ nota.texto|safe }}</p>
    <p><small>Id: {{ nota.pk }} Slug: {{ nota.slug }}</small></p>
  {% endif %}
{% endblock %}

Agora, se um slug não existente for digitado, a mensagem é exibida:

Observe que os espaços em torno do comparador “==” devem ser mantidos em {% if secao == "erro" %}, ou um erro será lançado.

Artigos Django

1- Django, Websites com Python
2- Django, um Projeto (esse artigo)
3- Django, incrementando o Projeto

Bibliografia

Consulte a bibliografia no artigo inicial.

Django, websites com Python

O que é Django

Django foi desenvolvido como um projeto interno no jornal Lawrence Journal-World em 2003 para atender à necessidade de implementar novos recursos com muito pouco prazo, e tornado disponível publicamente em julho de 2005. Ele é mantido pela Django Software Foundation (DSF), uma organização independente estabelecida nos EUA como uma organização sem fins lucrativos. Alguns sites conhecidos que usam Django incluem Instagram, Spotify, YouTube, Mozilla, Disqus, The Washington Post, Dropbox e muitos outros.

Django é um framework web gratuito, de código aberto e baseado em Python. Seu principal objetivo é a construção de sites complexos baseados em banco de dados, de forma rápida e de fácil manutenção. Sua estrutura prioriza a reutilização de componentes, usando menos código e o princípio DRY (não se repita). O Python é usado extensivamente na configuração, no acesso aos bancos de dados e na camada de exibição.

Como framework o Django é completo (diferente do Flask), podendo ser usado sem a adição de pacotes adicionais, embora possa receber plugins para incrementar sua funcionalidade. O Django fornece uma interface de administração (um painel do usuário) opcional gerada dinamicamente por introspecção que possibilita as operações de CRUD no banco de dados e tem suporte para bancos de dados SQLite, PostgresSQL e MySQL (e outros).

Arquitetura MTV

Django segue o padrão da arquitetura MTV, modelo–template–visualização (model–template–views).

  • Model: os dados a serem apresentados pelo aplicativo. Geralmente lidos em um banco de dados.
  • View: um gerenciador de requisições que seleciona o template apropriado.
  • Template: um arquivo básico (com estrutura HTML) contendo o layout da página web com marcadores para preenchimento dos dados requisitados.

Um quadro pode ajudar a esclarecer o modelo.


Descrição do modelo MVT
(Leia esse quadro e retorne a ele mais tarde, depois de ter lidos sobre as várias camadas do django.

  • O navegador envia uma requisição para o servidor rodando django (1),
  • a URL é recebida por urls.py que atribui uma view para tratamento da requisição,
  • a camada view consulta Model (2) para receber os dados requisitados e recebe dela esses dados (3),
  • depois de obter os dados View consulta a camada Template (4) para formatar a apresentação final (5) e
  • envia páginas html formatadas para o navegador cliente (6).

Sobre aprender Django

Para se obter um entendimento razoável do Django é necessário ter alguns pre-requisitos, que não são cobertos nessas notas. Primeiro é necessário entender como as páginas na web são formadas com html e formatadas com css. Um conhecimento do Python também é essencial, em particular sobre estruturas de dados: uso de listas e tuplas, dicionários e, principalmente, o uso de programação orientada a objetos.

Esses artigos adotam a abordagem de cobrir os aspectos básicos do django para dar uma visão geral do processo de criação e manutenção de sites e aplicativos web. Após uma leitura desse texto e a experimentação com o código proposto a consulta à documentação oficial do django deverá ser compreensível para o leitor.

Instalações

Para usar essas instruções o ideal seria ter uma instalação das últimas versões do Python e do Django. Usaremos o banco de dados SQlite que não necessita nenunha instalação especial. Também poderiam ser usados o MySQL, o PostgreeSQL ou vários outros bancos de dados.

Embora não obrigatório é sempre bom trabalhar em uma área isolada usando um ambiente virtual. Instruções sobre ambientes virtuais podem ser lidas aqui: Ambientes Virtuais, pip e conda. Para isso crie um diretório destinado a conter o projeto do django, e um ambiente virtual:

$ mkdir ~/Projetos/django
$ cd  ~/Projetos/django
$ python3.10 -m venv env
# para usar o ambiente virtual
$ source env/bin/activate
# o prompt de comando muda para
(env) $
# para desativar o ambiente virtual (quando for o caso)
(env)$ deactivate

As linhas de código acima criam o diretório ~/Projetos/django (lembrando que no linux ~ representa a pasta do usuário). No Windows os comandos devem ser alterados de acordo com a sintaxe do sistema. Criando um ambiente virtual alguns diretórios específicos (bin, include, lib) são gravados com uma cópia da instalação do Python, e algumas variáveis de ambiente são redefinidas. Pacotes instalados com o pip (ou outro gerenciador) serão colocados nesse ambiente.

Estando dentro do ambiente virtual, instalamos a última versão do django (que era a 4.0.5 em junho de 2022) usamos:

(env) $ pip install Django==4.0.5
# para verificar a instalação
(env) $ python -m django --version
4.0.5

Prosseguiremos com a construção de um projeto em django no artigo 2- Django, um Projeto.

Artigos Django

1. Django, Websites com Python (esse artigo): Introdução, instalação.

2. Um Projeto no Django: Criação e gerenciamento de projetos, criação de apps, templates, herança de templates, arquivos Estáticos e CSS, Modelos de dados, admin, exibição de dados.

3. Incrementando o Projeto Django: chaves externas e datas, Resetando o banco de dados, personalizando o Admin, formulários.

Bibliografia

Livros:

  • Ashley, David: Foundation Dynamic Web Pages with Python, Apress, 2020.
  • Bendoraitis, Aidas; Kronika, Jake: Django 3 Web Development Cookbook, 4th. Ed., Packt, Mumbai, 2020.
  • Feldroy, D.; Feldroy, A.: Two Scoops of Django 3.x, 5ª Ed., Two Scoops Press, 2021.
  • Shaw, B., Badhwar, S., Bird, A, Chandra, Guest C.: Web Development with Django, Packt, 2011.
  • Vincent, William S.: Django for Professionals, Production websites with Python & Django, disponível para aquisição em Leanpub.com, 2020.

Sites:

todos eles acessados em junho de 2022.

Flask, parte 2


Templates do Jinja2


Um aplicativo web (ou outro qualquer) deve ser escrito de forma clara, para facilitar sua expansão e manutenção. Uma das formas usadas pelo Flask para implementar esse estratégia é a de colocar código python e html separados. Os templates, como vimos, são modelos ou estruturas básicas que podem ser preenchidas dinamicamente, de acordo com as requisições. Esse é o chamado de modelo de separação entre lógica de negócio e lógica de exibição (business and presentation logic). Templates são tratados por um dos módulos que compõem o Flask: o módulo Jinja2.

Um exemplo básico de template para a exibição de um artigo poderia ser o seguinte:

# template.html
<h1>{{ titulo }} </h1>
<p>{{ autor }}, {{ data }} </p>
<p>{{ texto_do_artigo }} </p>
<p>{{ pe_de_pagina }} </p>

Os campos {{ variavel }} são chamados de localizadores (placeholders) para os valores que serão passados pelas funções view. Em muitos casos as informações usadas para popular essas variáveis são lidas em um banco de dados.

Já vimos o exemplo:

@app.route(“/frutas/<nome_da_fruta>”)
def frutas(nome_da_fruta):
return render_template(“frutas.html”, nome_da_fruta = nome_da_fruta)

onde /frutas/<nome_da_fruta>, fornece o valor da varíavel passada para o parâmetro da função (em vermelho). Dentro do corpo da função a variável de mesmo nome (em verde) recebe esse valor. Esses nomes não precisam ser os mesmo, embora esse seja uma prática comum entre programadores do python.

O método render_template() é parte do Jinja2 para integrar templates e lógica do aplicativo.

Filtros


Variáveis e objetos do python podem ser integrados nos templates de algumas formas. Por meio do módulo Jinja temos diversos filtros para manipular campos em templates. Já vimos como inserir uma variável em um template. Um exemplo de filtro é title(), que torna a string no formado de título, com a primeira letra de cada palavra em maísculo.

# suponha que temos a variável titulo = "a casa da mãe joana"
# essa string pode ser exibida dentro de uma tag <h1>
<h1> {{ titulo }} </h1>
↳ a casa da mãe joana

# para maísculas na primeira letra de cada palavra
<h1> {{ titulo | title() }} </h1>
↳ A Casa Da Mãe Joana

Uma descrição dos filtros para texto está na tabela abaixo.

Filtro Descrição
capitalize Converte 1º caracter em maiúsculo, os demais em minúsculo
lower Converte todos os caracteres minúsculo
upper Converte todos os caracteres maiúsculo
title Converte 1º caracter de cada palavra em maiúsculo
trim Remove espaços em branco no início e no fim
safe Renderiza o valor sem aplicar escape (inclui tags)
striptags Remove todas as tags HTML do valor

safe: O filtro safe informa ao Flask que a tag html pode ser renderizada com segurança. Mais exemplos abaixo.
striptags: remove as tags <tag> e </tag> e retorna o texto puro.

Exemplos de Filtros em Strings

Suponha que temos uma variável de nome titulo. Nos templates ela pode ser exibida diretamente, como uma string, ou passando por algum dos vários filtros. Nos quadros seguintes os comentários são iniciados por # enquanto outputs são identificados pelo sinal .

# suponha que a variável titulo2 não está definida
# default fornece um valor default (se titulo2 não está definido).
<h1> {{titulo2 | default ("Título Não Encontrado")}} </h1>
↳ Título Não Encontrado

# torna maiúscula a primeira letra
<h1> {{"mercado" | capitalize()}} </h1>
↳ Mercado

# em linha anterior ao uso podemos definir um valor
# capitalize torna maiúscula a 1ª letra de cada palavra
{% set titulo2 = "um título para a página" %}
<h1> {{ titulo2 | capitalize()}} </h1>
↳ Um título para a página

# title() torna maiúscula a 1ª letra de cada palavra
<h1> {{titulo2 | title()}} </h1>
↳ Um Título Para A Página

# substituir um trecho em uma string
{{ "Bom dia galera!" | replace("Bom dia", "Boa noite") }}
↳ Boa noite galera!

# inverter a ordem dos elementos
{{ "Olá galera!" | reverse() }}
↳ !arelag álO

Conversores

Por default os valores passados em uma url e capturados como valores do python são strings. Alguns conversores podem transformar essas strings em caminhos (que usam barras / ), inteiros ou decimais.

@app.route("/usuario/<int:id>")
def exibir_id(id):
    # esta função recebe id como um inteiro e o exibe
    return f"O id digitado é {id}"

@app.route("/path/")
def exibir_caminho(caminho):
    # recebe e retorna o caminho passado
    return f"Caminho {caminho}"

Os seguintes conversores estão disponívies:

string (default) qualquer string sem barras / ou \
int converte em inteiros positivos
float converte em números decimais
path strings contendo barras de caminho
uuid strings UUID†

† Uma string UUID (Universally Unique IDentifier), também chamada de GUID (Globally Unique IDentifier) é um número de 128-bits usado na troca de informações em computação.

Valores numéricos podem ser convertidos entre inteiros e decimais, e um valor default ser fornecido.

# números inteiros podem ser convertidos em decimais, ou decimais em inteiros
{{ 10 | float() }}
↳ 10.0 ou 0.0      # 0.0 se a conversão não for possível
{{ 10.0 | int() }}
↳ 10

# um valor default, em caso de erro
{{ "qualquer" | float (default = "Erro: texto não pode ser convertido em decimal") }}
↳ Erro: texto não pode ser convertido em decimal

Manipulação de Listas

Diversas operações são disponíveis em listas.

# join: junta elementos de uma lista
{{ [1, 2, 3] | join() }}
↳ 123
{{ ["Um", "Dois", "Tres"] | join() }}
↳ UmDoisTres

# inserindo um separador
{{ [1, 2, 3] | join ("|") }}
↳ 1|2|3
{{ ["Um", "Dois", "Tres"] | join("-") }}
↳ Um-Dois-Tres

# o filtro list() retorna uma lista
{{ "Guilherme" | list()}}
↳ ["G","u","i","l","h","e","r","m","e"]

# random() seleciona um item aleatorio da lista
{{ ["Mercúrio", "Venus", "Terra"] | random() }}
↳ Venus

{% set pe_pagina = ["citacao 1", "citacao 2", "citacao 3", "citacao 4", "citacao 5"] %}
{{ pe_pagina | random() }}
↳ citacao 4

# replace (visto acima para strings) também pode ser usado em listas
{% set lista = ["Nada", "a", "dizer"] %}
{{ lista | replace ("Nada", "Tudo") }}
↳ ["Tudo", "a", "dizer"]

# o filtro reverse() também pode inverter uma lista
# mas seu resultado é um objeto iterador
{% set lista = ["unidade", "dezena", "centena"] %}
{{ list | reverse() }}
↳ <list_reverseiterator object at 0x7fc0b6262518>

# para usar o objeto lista sem usar iterações temos que usar o método list()
{{ list | reverse() | list() }}
↳ ["centena", "dezena", "unidade"]

O filtro random() pode ser útil para exibir um artigo aleatório do site na homepage, para escolher uma imagem ou um pé de página, etc.

Outros exemplos de manipulação de listas incluem o uso de first(), last(), uso de índices e de laços para percorrer toda a lista.

# first() é 1º elemento da lista, last() é o último elemento
{% set nomes = ["João", "Pedro", "da", "Silva"]  %}
<p> Nome: {{ nomes | first() }} </p>
<p> Segundo Nome: {{ nomes [1] }} </p>
<p> Sobrenome: {{ nomes | last() }} </p>
↳ Nome: João
↳ Segundo Nome: Pedro
↳ Sobrenome: Silva

# o tamanho de uma lista é retornado com {{ lista | length }}
# laços for são usados para percorrer os elementos
{% set comentarios = ["Comenta 1", "Comenta 2", "Comenta 3", "Comenta 4"]%}
<p>Temos ({{comentarios | length}}): comentários</p>
{% for comentario in comentarios %}
    <p> {{ comentario }} </p>
{% endfor%}
# resulta em
↳ Temos 4: comentários
↳ Comenta 1
↳ Comenta 2
↳ Comenta 3
↳ Comenta 4

O filtro safe

O filtro safe serve para passar para o interpretador do Flask a informação de que as tags html devem ser renderizadas. Sem ele a string "<texto>" é exibida literalmente, inclusive com os delimitadores "<>".

Os códigos &lt; (<) e &gt; (>) são entidades html, descritas nesse site.

Por motivo de segurança o Jinja2 remove as tags html. Por exemplo: uma variável com valor "<li> TEXTO </li>" será renderizada como "&lt;li&gt; TEXTO &lt;/li&gt;" por extenso e sem provocar a renderização do navegador. Com o filtro safe o TEXTO é exibido como um ítem de lista.

# exibição literal de uma string
{{ "<b>Texto a exibir!</b>" }}
↳ <b>Texto a exibir!</b>

# para forçar a renderização da tag <b> (negrito)
{{ "<b>Texto a exibir!</b>" | safe }}
↳ Texto a exibir!

# define uma lista
{% set lista = ["<li>Um elefante</li>", "<li>Dois elefantes</li>", "<li>Três elefantes</li>"] %}
<ul>
{% for item in list %}
    {{ item | safe }}
{% endfor %}
</ul>
# será renderizado como
↳
⏺ Um elefante
⏺ Dois elefantes
⏺ Três elefantes

# alternativamente
{% set lista = ["Um elefante", "Dois elefantes", "Três elefantes"] %}
<ul>
{% for item in list %}
    <li> {{ item }} </li>
{% endfor %}
</ul>
# será renderizado da mesma forma.
# Nesse caso não existem tags na lista e safe é desnecessário.

Observação importante: Qualquer input digitado por usuários deve passar pelo filtro safe para evitar que alguma instrução danosa seja processada pelo navegador.

Laços e bifurcações


Vimos que um template recebe variáveis do python e pode processá-las com código. Por exemplo, modificamos o template frutas.html da seguinte forma:

# frutas.html
<body>
    {% if nome_da_fruta == None %}
        <p>Você não escolheu uma fruta!</p>
    {% elif nome_da_fruta == "laranja" %}
        <p>Você escolheu laranja, a melhor fruta!</p>
    {% else %}
        <p>Você escolheu a fruta: {{ nome_da_fruta }}</p>
    {% endif %}
</body>

No código de meu_site.py modificamos a função frutas para que por default ela receba None (caso nada seja escrito após o nome do diretório /frutas/:

# meu_site.py (apenas trecho)
@app.route("/frutas/")
@app.route("/frutas/<nome_da_fruta>")
def frutas(nome_da_fruta=None):
    return render_template("frutas.html", nome_da_fruta=nome_da_fruta)

Agora temos as respostas:

url resposta no navegador
http://127.0.0.1:5000/frutas/ Você não escolheu uma fruta!
http://127.0.0.1:5000/frutas/laranja Você escolheu laranja, a melhor fruta!
http://127.0.0.1:5000/frutas/goiaba Você escolheu a fruta: goiaba

No template, os trechos entre chaves não são parte do html e sim do Python, gerenciado pelo Flask. Dessa forma podemos integrar as páginas da web com as inúmeras bibliotecas do Python.

Quatro tipos de marcações estão disponíveis para para inserção do código nos templates.

sintaxe usadas para
{% ... %} linhas de instruções
{{ ... }} expressões
{# ... #} comentários
# ... ## instruções inline

Variáveis

Variáveis a serem usadas nos templates podem ser de qualquer tipo. Por exemplo:

{% set nomes = ["João", "Pedro", "da", "Silva"]  %}
<p>O segundo nome da lista: {{ nomes[1] }}.</p>
↳ O segundo nome da lista: Pedro.

{% set id = 3 %}
<p>Quem? {{ nomes[id] }}!</p>
↳  Quem: Silva!

# uso de um dicionário
{% set dicionario = {"Nome":"Paul"; "Sobrenome":"Dirac"; "Profissão":"Físico"}  %}
<p>Estes são os dados do: {{ dicionario["Nome"] }}.</p>
{% for chave, valor in dicionario.items() %}
    <p>{{ chave }} : {{ valor }}</p>
{% end for %}
↳ Estes são os dados do: Paul.
↳ Nome: Paul
↳ Sobrenome: Dirac
↳ Profissão :Físico

# no caso geral, se um objeto é passado para o template e tem um método, podemos usar:
<p>Obtendo um valor com um método de objeto disponível: {{ objeto.metodo() }}.</p>

Incluindo trechos com include

Se uma parte do template é repetida várias vezes ela pode ser colocada à parte, em arquivo separado, e incluída na template principal. Por ex., se temos um pé de página que aparece em diversas de nossas páginas ele pode ser gravado à parte.

# arquivo pe_de_pagina.html
<div class="pe_pagina">
<p>Esté é o meu pé de página</p>
</div>

Esse código assume que existe a definição de uma classe css chamada pe_pagina.
Em todos os arquivos que devem exibir o pé de página inserimos:

# todo o texto da página
# pé de página
{% include 'pe_de_pagina.html' %}

Macros

Macros são formas de implementar o princípio DRY (Don’t Repeat Yourself ), uma prática de desenvolvimento de software que visa reduzir a repetição do linhas semelhantes ou com mesma função no código. Ele torna o código mais legível e de fácil manutenção, uma vez que alterações devem ser feitas em um único bloco. Templates, macros, inclusão de conteúdo externo (como em include()) e heranças de modelos são todos instrumentos utilizados para isso.

Outra forma de gerar código reutilizável é através da criação de macros, um recurso similar às funções usuais do Python. Macros podem ser gravadas em arquivos separados e importadas dentro de todos os templates que fazem uso delas, facilitando a modularização do código.

Uma macro pode executar tarefas simples como simplesmente montar as linhas da lista. Suponha que temos uma lista de linhas e queremos montar uma lista não ordenada em html:

 {% macro montar_lista(linha) %}
     <li>{{ linha }}</li>
 {% endmacro %}
 <ul>
 {% for linha in linhas %}
     {{ montar_lista(linha) }}
 {% endfor %}
 </ul>

Outra possibilidade importante para a modularização consiste em gravar um arquivo macros.html que contém a macro vermelho(texto, marcas). Ele retorna linhas de uma lista coloridas de vermelho se texto == marcas, de azul caso contrário.

# arquivo macros.html
{% macro vermelho(texto, marcar) %}
{% if texto == marcar %}
    <li style="color:red;">{{ texto }}</li>
{% else %}
    <li style="color:blue;">{{ texto }}</li>
{% endif %}
{% endmacro %}

O arquivo mostrar_frutas.html importa a arquivo anterior, com a sua macro, e faz uso dela para exibir a lista ordenada.

# arquivo mostrar_frutas.html
{% from "macros.html" import vermelho %}
{% set frutas = ["Abacate", "Abacaxi", "Laranja", "Uva"]  %}
{% set selecionado = "Abacaxi"  %}
<ol>
 {% for fruta in frutas %}
     {{ vermelho(fruta, selecionado) }}
 {% endfor %}
</ol>

O resultado no navegador é o seguinte:

Assim como é válido no Python, podemos fazer a importação de forma alternativa (mostrando só linhas diferentes):

# arquivo mostrar_frutas.html
{% import "macros.html" as macros %}
{% for fruta in frutas %}
    {{ macros.vermelho(fruta, selecionado) }}
{% endfor %}

Herança de Templates

Similar à herança de classes no modelo POO do python, podemos criar um template base e derivar dele outros templates que herdam a sua estrutura. Os templates base definem blocos que podem ser sobrescritos nos templates filhos. Um template base pode ter a seguinte estrutura:

# arquivo base.html    
<html>
<head>
 {% block head %}
 <title> Artigo {% block title %}{% endblock %} </title>
 {% endblock %}
</head>
<body>
 {% block body %}
 {% endblock %}
 {% block final %}
 <p>Site construído com Python-Flask!</p>
 {% endblock %} 
</body>
</html>

A instrução {% block nome_do_bloco %}{% endblock %} pode ser substituída por conteúdo nos templates filhos (ou derivados). Para herdar desse template usamos extends e redefinimos os blocos da base:

# arquivo derivado.html    
{% extends "base.html" %}
{% block title %}Nome do Artigo{% endblock %}
{% block head %}
<style>
# estilos css ficam aqui
</style>
{% endblock %}
{% block body %}
<h1>Nome do Artigo</h1>
<p>Texto do artigo</p>
{% endblock %}
{% block final %}
 {{ super() }}
{% endblock %}

O bloco final, {% block final %}{{ super() }}{% endblock %}, usa super() para simplesmente importar o conteúdo do arquivo base. Se a base e o derivado contém texto o conteúdo da base é sobreposto.

Solicitações e Respostas do Servidor (Request, Response)

† O que é uma thread?

Ao receber uma solicitação de um cliente o Flask responde passando para as funções de visualização (view functions) os objetos que serão usados para a construção da página web. Um exemplo é o objeto request, que contém a solicitação HTTP enviada pelo cliente. Temos que nos lembrar que o aplicativo pode receber um grande volume de solicitações em múltiplas threads. Para evitar que todas as funções de visualização recebam essas informações como parâmetros, o que pode tornar o código complexo e gerar conflitos o Flask usa contextos para que esses objetos fiquem temporariamente acessíveis dentro desses contextos.

Para os exemplos que se seguem vamos trabalhar usando o python no terminal. Para isso ativamos o ambiente virtual e o próprio python:

$ cd ~/caminho_para_o_projeto
$ source ./bin/activate
# o prompt muda para indicar ativação de venv
$ (venv) $ python
Python 3.9.10 (main, Jan 17 2022, 00:00:00)

Graças aos contextos, funções de visualização como a seguinte podem ser escritas:

from flask import request
@app.route('/')
def index():
    navegador = request.headers.get('User-Agent')
    return f'<p>Verificamos que seu navegador é o {navegador} </p>'

Que retorna no navegador (no meu caso):

Contextos: Note que request não foi passado explicitamente para index(), agindo como se fosse uma variável global. Isso é obtido pelo Flask com os contextos ou ambientes reservados. Dois ambientes são usados: o contexto de aplicativo e o contexto de requisição.

As seguintes variáveis existem nesses contextos:

nome da variável Contexto Descrição
current_app Aplicativo A instância do aplicativo ativo.
g Aplicativo Objeto usado pelo aplicativo para armazenamento de dados durante uma requisição. Resetada a cada requisição.
request Requisição Objeto que encapsula o conteúdo da requisição HTTP enviada pelo cliente.
session Requisição Representa a sessão do usuário, um dicionário que o aplicativo usa para armazenar valores entre requisições.

Esses contextos só estão disponíveis quando o aplicativo recebe uma requisição (por meio de uma url digitada no navegador). O Flask ativa o contexto de aplicativo disponibilizando current_app e g, e o contexto de requisição disponibilizando request e session, para a thread, e em seguida os remove. Um exemplo desse comportamento pode ser visto no código, executado dentro do python:

from meu_site import app
from flask import current_app
current_app.name                     # um mensagem de erro é exibida
                                     # pois o contexto não está ativo
RuntimeError: working outside of application context

app_contexto = app.app_context()
app_contexto.push()                 # o flask ativa o contexto
current_app.name                    # o nome do app é impresso
'meu_site'
app_contexto.pop()

Flask usa os métodos objeto.push() e objeto.pop() para iniciar e terminar um contexto. A variável current_app.name só existe enquanto o contexto está ativado.

Preparando uma resposta

Para responder a uma solicitação o Flask armazena um mapa que associa URLs (e suas partes) à função resposta que deve ser executada. Esse mapa está armazendo em app.url_map.

from meu_site import app
app.url_map
Map([<Rule '/contatos/' (HEAD, OPTIONS, GET) -> contatos>,
 <Rule '/frutas/' (HEAD, OPTIONS, GET) -> frutas>,
 <Rule '/' (HEAD, OPTIONS, GET) -> index>,
 <Rule '/frutas/<nome_da_fruta>' (HEAD, OPTIONS, GET) -> frutas>,
 <Rule '/static/<filename>' (HEAD, OPTIONS, GET) -> static>])

A lista mostra o mapeamento das funções view que criamos e mais um, denominado /static, acrescentado automaticamente para acessar arquivos estáticos como arquivos de estilo (cascading style sheets, *.css) e imagens. Os elementos (HEAD, OPTIONS, GET) são passados dentro da URL. Os dois primeiros são gerenciados internamento pelo Flask.

Objeto request

O objeto request, armazenado na variável request, contém toda a informação passada na requisição pela URL. Os atributos e métodos mais comuns desse objeto são listados a seguir.

Atributo/Método Descrição
form Dicionário com todos os campos de form submetidos na requisição.
args Dicionário com todos os argumentos passados na string de pesquisa da URL.
values Dicionário com valores combinados de form e args.
cookies Dicionário com todos os cookies incluídos na requisição.
headers Dicionário com todos os cabeçalhos HTTP incluídos na requisição.
files Dicionário com todos os arquivos de upload incluídos na requisição.
get_data() Retorna dados em buffer na requisição.
get_json() Retorna dicionário com dados JSON incluído na requisição.
blueprint Nome do blueprint que está processando a requisição.
endpoint Nome do endpoint processando a requisição. Flask usa a função view como nome do endpoint para um caminho.
method Método da requisição HTTP, (GET ou POST).
scheme Esquema da URL (http or https).
is_secure() Retorna True se a requisição veio de conexão segura (HTTPS).
host O host definido na requisição, incluindo o número da porta se fornecido pelo cliente.
path Parte da URL que define o caminho.
query_string Parte da URL que define a string de pesquisa (query), como um valor binary (raw).
full_path Parte da URL que define caminho e pesquisa (query).
url Requisição completa da URL fornecida pelo cliente.
base_url O mesmo que url, sem a parte de pesquisa (query).
remote_addr Endereço de IP do cliente.
environ Dicionário com o ambiente de WSGI da requisição.
(†) Blueprints serão vistos mais tarde.

Hooks de Solicitação (request hooks)

Com o Flask podemos registrar funções que devem ser chamadas antes ou depois de uma solicitação. Essas funções podem ser usadas para executar tarefas úteis, tais como autenticar um usuário, abrir e fechar a conexão com um banco de dados, etc. Quatro ganchos (hooks) são disponibilizados:

before_first_request Registra função para execução antes da primeira requisição. Útil para tarefas de inicialização do servidor.
before_request Registra função a ser executada antes de cada requisição.
after_request Registra função a ser executada após cada requisição, caso não ocorram exceções não tratadas.
teardown_request Registra função a ser executada após cada requisição, mesmo que ocorram exceções não tratadas.

Um exemplo de uso desses hooks seria o de usar before_request para coletar dados que serão usados ao longo do ciclo de vida do aplicativo para um usuário e os armazenar na variável g para uso posterior.

Como vimos, uma requisição resulta em uma resposta por meio de uma das funções view enviada ao cliente. Ela pode ser uma página simples de html construída com auxílio dos templates ou algo mais complexo. Junto com a resposta, de acordo com o protocolo HTTP, é enviado um código de status (status code) indicando o sucesso da solicitação. Por default o Flask retorna o status_code = 200 para solicitação bem sucedida. Podemos usar uma função view para retornar outro código.

@app.route('/')
def index():
    return 'Ocorreu um erro!', 400
42 é a resposta do Guia do Mochileiro das Galaxias!

A função acima retorna uma tupla com uma string e um inteiro. É possível e útil fazer com que essas funções retornem um objeto response no lugar da tupla.

from flask import make_response
@app.route('/')
def index():
   response = make_response('Resposta Final sobre o Universo!')
   response.set_cookie('resposta', '42') return response

Dessa forma response passa a conter um cookie (que é gerenciado pelo navegador que o recebe). A tabela seguinte mostra métodos e atributos mais usados no objeto response.

Métodos e atributos do objeto response

Atributo/Método Descrição
status_code Código numérico de status do HTTP
headers Objeto tipo dicionário com todos os cabeçalhos a serem eviados em response
set_cookie() Acrescenta um cookie no objeto response
delete_cookie() Remove um cookie
content_length Comprimento do corpo da response
content_type Tipo de midia do corpo da response
set_data() Define o corpo da response como string ou bytes
get_data() Retorna o corpo da response


Dois tipos de resposta especiais para casos que ocorrem com frequência são fornecidos como funções auxiliares. Uma delas é uma forma de lidar com erros, eviando um código por meio do método abort(). No exemplo abaixo usamos essa função para enviar uma mensagem 404 (página não encontrada) caso a id de um usuário não seja encontrada com load_user(id).

from flask import abort
@app.route('/usuario/<id>')
def usuario(id):
    usuario = load_user(id)
    if not usuario:
        abort(404)
    return f'<div class="usuario">Bem vindo {usuario.name}</div>'

Esse exemplo supõe que exista um template para usuario e que ele carrega instruções css para a classe usuario.

Se load_user(id) retornar None é executada abort(404) que retorna a mensagem de erro. Uma exceção é levantada e a função usuario() é abandonada antes de atingir a instrução return.

O outro tipo de resposta é o redirect que não retorna uma página mas sim uma nova URL redirecionando o navegador. redirect retorna status_code = 302 e a nova URL (dada no código).

from flask import redirect
@app.route('/')
def index():
    return redirect('https://phylos.com/programacao')

Bibliografia

Veja a bibliografia na Parte 1.


Flask, Parte 3 está em preparação!

Flask, parte 1


Web Frameworks

Para a construção de páginas e aplicativos web é essencial algum conhecimento de html e css, não cobertos nesse artigo.

Um aplicativo web web application ou simplesmente web app) é um aplicativo executado através de um servidor web, diferente de um aplicativo executado na máquina local, e geralmente rodados e visualizados por meio de um browser ou navegador. Eles podem ser um conjunto de páginas de texto dinâmicas contendo, por exemplo, pesquisas em uma biblioteca, um gerenciador de arquivos na nuvem, um gerenciador de contas bancárias ou emails, um servidor de músicas ou filmes, etc. Com frequência esses aplicativos estão conectados a um banco de dados, podendo fazer neles consultas e modificações.

Um framework para a web é um conjunto de softwares destinados a oferecer suporte ao desenvolvimento de aplicativos na Web. Eles buscam automatizar a construção dos web apps e seu gerenciamento durante o funcionamento, após sua publicação na web. Alguns frameworks web incluem bibliotecas para acesso a banco de dados, templates para a construção dinâmica das páginas e auxílio à reutilização de código. Eles podem facilitar o desenvolvimento de sites dinâmicos ou, em alguns casos, de sites estáticos.

Framework Flask

O Flask é um micro-framework em Python usado para desenvolvimento e gerenciamento de web apps. Ele é considerado micro porque possui poucas dependências para seu funcionamento e pode ser usado com uma estrutura inicial bem básica, voltada para aplicações simples. Apenas duas bibliotecas são instaladas junto com o Flask. Ele não contém, por ex., um gerenciador de banco de dados ou um servidor de email. No entanto esses serviços podem ser acrescentados para ampliar as funcionalidades do aplicativo.

Em particular, o Flask não inclui uma camada de abstração com banco de dados. Em vez disso é possível instalar extensões, escolhendo o banco de dados específico que se quer usar. Essas extensões também podem auxiliar a validação de formulário, manipulação de upload, tecnologias de autenticação aberta, entre outras.

Flask foi desenvolvido por Armin Ronacher e lançado em 2010. Algumas vantagens citadas em seu uso são: (a) projetos escrito com a Flask são simples (comparados àqueles gerados por frameworks maiores, como o Django) e tendem a ser mais rápidos. (b) Ele é ágil e modular: o desenvolvedor se concentra apenas nos aspectos utilizados de seu aplicativo, podendo ampliar sob demanda. (c) Os projetos são pequenos mas robustos. (d) Existe uma vasta comunidade de desenvolvedores contribuindo com seu desenvolvimento, apresentando bibliotecas que ampliam sua funcionalidade.

Criando um aplicativo básico

Nessa primeira parte vamos criar um aplicativo bem básico mas funcional. Depois entraremos em outros detalhes do Flask.

Para criar um projeto usando o Flask (ou, na verdade, outro projeto qualquer) é aconselhável criar antes um ambiente virtual para que os pacotes instalados não conflituem com outros em projetos diferentes. A criação e manutenção de ambientes virtuais está descrita na página Ambientes Virtuais, PIP e Conda. Alguns IDEs, como o Pycharm realizam automaticamente esse processo. No meu caso ele ficará abrigado em ~/Projetos/flask/venv. Para simplificar denotarei esse ambiente simplesmente pelo nome flask, que é também o nome da pasta que abriga esse projeto.

Nesse ambiente instalamos o Flask com pip install flask. Uma estrutura básica de ambiente já estará montada após esse passo. Em seguida criamos um arquivo do python, de nome meu_site.py.

# meu_site.py
from flask import Flask
app = Flask(__name__)

@app.route("/")
def homepage():
    return "Esta é a minha homepage"

if __name__ == "__main__":
    app.run()

# é exibido no console do python
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

Esse arquivo não deve se chamar flask.py para evitar conflito de nomes.

A variável __name__, passada para o construtor do Flask contém o nome do módulo principal e é usada para determinar a localização do aplicativo no app. Outros diretórios e arquivos, como pastas de templates, arquivo de estilo e imagens, serão localizadas à partir dessa raiz.

Aplicativos do Flask incluem um servidor de desenvolvimento que pode ser iniciado com o comando run. Esse comando busca pelo nome do aplicativo na variável de ambiente FLASK_APP. Se queremos rodar o aplicativo meu_site.py executamos na linha de comando:

# Linux ou macOS
(venv) $ export FLASK_APP=meu_site.py
(venv) $ flask run
 * Serving Flask app "hello"
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

# Microsoft Windows
(venv) $ set FLASK_APP=meu_site.py
(venv) $ flask run
 * Serving Flask app "hello"
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 
 # alternativamente se pode iniciar o servidor com
 app.run()

No Pycharm, ou outros IDES, você pode executar diretamente esse código.

Da biblioteca flask importamos apenas (por enquanto) a classe Flask. Uma instância da classe é criada com app = Flask(__name__) onde a variável __name__ contém o nome do projeto. A linha @app.route("/") é um decorador que informa que a função seguinte será rodada na raiz / do site. Quando esse arquivo .py é executado dentro de uma IDE ou usando python meu_site.py, na linha de comando, é exibido no console várias mensagens, entre elas a url http://127.0.0.1:5000/, que pode ser clicada ou copiada para a linha de endereço do navegador. Isso resulta na exibição, dentro do navegador, da página:


Clientes e Servidores: O navegador age como o cliente que envia ao servidor uma solicitação, através de uma URL digitada na barra de endereços. O servidor da web transforma essa solicitação em ações a serem realizadas do lado do servidor e retorna uma página com conteúdo de texto e multimídia, renderizados pelo navegador. O Flask fica do lado do servidor, construindo a resposta. Entre outras coisas ele possui um mapeamento entre as URLs e as funções route() que serão executadas no código *.py.

O endereço e a porta 127.0.0.1:5000 são padrões para o Flask. app.run() cria um servidor que atende à requisição HTTP do navegador, exibindo a página html. Qualquer texto retornado pela função homepage() é renderizado no formato html e exibido no navegador. Por exemplo, se fizermos as alterações, colocando o texto entre tags h1:

@app.route("/")
def homepage():
    return "<h1>Esta é a minha homepage</h1>"

if __name__ == "__main__":
    app.run(debug=True)

o texto agora é renderizado como um título de nível 1:

o mesmo texto será exibido mas agora com formatação de título, a tag h1. Todas as demais tags podem ser utilizadas. O parâmetro debug=True faz com que alterações no código sejam imediatamente repassadas para as requisições ao servidor, sem a necessidade de rodar todo o projeto novamente. Com isso basta recarregar a página do navegador para que alterações sejam exibidas, clicando no ícone de atualização ou pressionando F5. No mode debug os módulos dois módulos chamados reloader e debugger estão ativados por default. Com o debugger ativado as mensagens de erro são direcionadas para a página exibida. O mode debug nunca deve ser ativado em um servidor em produção pois isso fragiliza a segurança do site.

Também podemos ativar o módulo no código que executa o aplicativo:

(venv) $ export FLASK_APP=meu_site.py
(venv) $ export FLASK_DEBUG=1
(venv) $ flask run

O decorador @app.route("/") registra a função homepage() junto com a página raiz do site. Outras páginas vão executar outras funções. Por exemplo, uma página de contatos pode ser inserida por meio da inserção de nova função no código. Nesse caso criaremos a função contatos().

# meu_site.py

from flask import Flask
app = Flask(__name__)

@app.route("/")
def homepage():
    return "<h1>Esta é a minha homepage</h1>"

@app.route("/contatos")
def contatos():
    txt = (
    "<h1>Página de Contatos</h1>"
    "<ul>"
    "<li>Contato 1</li>"
    "<li>Contato 2</li>"
    "</ul>"
    )
    return txt

if __name__ == "__main__":
    app.run(debug=True)

Usamos acima a concatenação de string com parênteses: (str1 str2 ... strn).
Agora, além da homepage temos a página de contatos em 127.0.0.1:5000/contatos, com a seguinte aparência.

A funções contatos() e homegage() são chamadas funções de visualização (view functions).

Html e templates: Notamos agora que o código em meu_site.py contém sintaxe misturada de Python e html e pode ficar bem complexo em uma página real exibida na web. Para evitar isso o Flask permite a criação de templates. Fazemos isso da seguinte forma: no diretório raiz onde está o projeto (o mesmo onde foi gravado meu_site.py) criamos o diretório template (o nome default do Flask). Dentro dele colocamos nossos templates. Por exemplo, criamos os arquivos homepage.html,

# homepage.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Homepage: teste Flask</title>
</head>
<body>
    <h1>Este é o título da Homepage</h1>
    <p>Com os devidos parágrafos...</p>
</body>
</html>

e contatos.html:

# contatos.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Contatos</title>
</head>
<body>
    <h1>Página de Contatos</h1>
    <ul>
    <li>Contato 1</li>
    <li>Contato 2</li>
    </ul>
    </body>
</html>

Vários IDEs podem auxiliar na criação desses arquivos html, fornecendo um esqueleto básico a ser preenchido pelo programador.

Além disso modificamos nosso código python para usar a renderização dos templates, importando render_template.

# meu_site.py
from flask import Flask, render_template
app = Flask(__name__)

@app.route("/")
def homepage():
    return render_template("homepage.html")

@app.route("/contatos")
def contatos():
    return render_template("contatos.html")

if __name__ == "__main__":
    app.run(debug=True)

Quando esse código é executado temos a referência ao link que, se aberto, mostra as páginas criadas: digitando 127.0.0.1:5000 abrimos nossa homepage:

Mas, se digitarmos 127.0.0.1:5000/contatos a outra página é exibida:

Uma página pode receber parâmetros do código em python. Por exemplo, digamos que queremos exibir uma página para cada produto existente em uma loja virtual que vende frutas. Nesse caso acrescentamos no código de meu_site.py:

@app.route("/frutas/<nome_da_fruta>")
def frutas(nome_da_fruta):
    return render_template("frutas.html")

Para receber esse parâmetro temos que gravar a página frutas.html na pasta templates, com um conteúdo que receba essa variável.

# frutas.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Frutas disponíveis</title>
</head>
<body>
    <h1>Frutas</h1>
    <p>Você escolheu a fruta: {{nome_da_fruta}}</p>
</body>
</html>

Se for digitado no campo de endereços do navegador, ou passado por meio de um link na tag <a href="http://127.0.0.1:5000/frutas/laranja">Laranja</a> a parte do endereço <nome_da_fruta> = laranja é passado como valor de parâmetro na função frutas("laranja") que é disponibilizado dentro do código html como {{nome_da_fruta}}.

Resumindo: @app.route("/frutas/<nome_da_fruta>") envia uma string na variável nome_da_fruta para a função frutas que, por sua vez repassa ao código html. Dentro do html a variável fica disponível como {{nome_da_fruta}} (dentro de uma dupla chave).

Por exemplo, se digitamos na barra de endereços do navegador http://127.0.0.1:5000/frutas/laranja teremos a exibição de

Essa técnica pode ser usada, por ex., para criar páginas para diversos usuários usando um único template usuario.html.

@app.route('/usuario/<nome>')
def usuario(nome):
    return render_template("usuario.html")
# ou
@app.route('/usuario/<int:id>')
    return render_template("usuario.html")

A parte do código <int:id> é um filtro que transforma a entrada digitada em inteiro, quando possível e será melhor explicada adiante.

Formatando com CSS

O texto dentro de uma página html (HyperText Markup Language) pode ser formatado de algumas formas diferentes, usando css (Cascading Style Sheets). Quando se trata do uso de um framework a forma preferida consiste em apontar no cabeçalho para um arquivo externo css. No Flask isso é feito da seguinte forma: um arquivo css é gravado na pasta static da pasta do projeto. Digamos que gravamos o arquivo /static/styles.css com um conteúdo mínimo, apenas para demonstração, tornando vermelhas as letras do título e azuis as letras dos parágrafos:

# arquivo /static/styles.css
h1 { color:red; }
p { color:blue; }

No cabeçalho das páginas html, dentro da tag <head> colocamos um link para o arquivo de estilos:

# homepage.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <link rel="stylesheet" type="text/css" href="static/styles.css">
    <title>Homepage: teste Flask</title>
</head>

Agora, ao acessar a homepage veremos:


Com todas essas alterações o projeto tem agora a estrutura de pastas mostrada. Na figura à esquerda todas as pastas, inclusive aquelas criadas pelo gerenciador de ambientes virtuais são mostradas. No meu caso elas foram criadas automaticamente pelo IDE Pycharm, mas podem ser criadas pelo programador sem dificuldade. Na figura à direita são mostradas apenas as pastas criadas pela programador diretamente. Um projeto com esse formato roda perfeitamente, apesar de não contar com as vantagens do ambiente virtual (veja artigo).

Outras estruturas de código podem ser inseridas nos templates, como veremos.

Opções de comando de linha

Quando se roda o flask diretamente no terminal podemos ver uma mensagem de ajuda com (venv) $ flask --help, verificar os caminhos definidos no app ou entrar em uma shell interativa.

# Exibir ajuda do flask    
(venv) $ flask --help
  Usage: flask [OPTIONS] COMMAND [ARGS]...
  
    A general utility script for Flask applications.
  
    Provides commands from Flask, extensions, and the application. Loads the
    application defined in the FLASK_APP environment variable, or from a wsgi.py
    file. Setting the FLASK_ENV environment variable to 'development' will
    enable debug mode.
  
      $ export FLASK_APP=hello.py
      $ export FLASK_ENV=development
      $ flask run
  
  Options:
    --version  Show the flask version
    --help     Show this message and exit.
  
  Commands:
    routes  Show the routes for the app.
    run     Run a development server.
    shell   Run a shell in the app context.
  
# exibe os caminhos ativos no aplicativo
  (venv) $ flask routes
  Endpoint  Methods  Rule
  --------  -------  -----------------------
  contatos  GET      /contatos/
  frutas    GET      /frutas/
  frutas    GET      /frutas/
  homepage  GET      /
  static    GET      /static/
  
# entra em uma shell interativa    
  (venv) $ flask shell

A shell do flask inicia uma sessão python no contexto do atual aplicativo onde podemos executar testes ou tarefas de manutenção. O comando flask run admite vários parâmetros:

(venv) $ flask run --help
  Usage: flask run [OPTIONS]
  
    Run a local development server.
  
    This server is for development purposes only. It does not provide the
    stability, security, or performance of production WSGI servers.
  
    The reloader and debugger are enabled by default if FLASK_ENV=development or
    FLASK_DEBUG=1.
  
  Options:
    -h, --host TEXT                 The interface to bind to.
    -p, --port INTEGER              The port to bind to.
    --cert PATH                     Specify a certificate file to use HTTPS.
    --key FILE                      The key file to use when specifying a
                                    certificate.
    --reload / --no-reload          Enable or disable the reloader. By default
                                    the reloader is active if debug is enabled.
    --debugger / --no-debugger      Enable or disable the debugger. By default
                                    the debugger is active if debug is enabled.
    --eager-loading / --lazy-loading
                                    Enable or disable eager loading. By default
                                    eager loading is enabled if the reloader is
                                    disabled.
    --with-threads / --without-threads
                                    Enable or disable multithreading.
    --extra-files PATH              Extra files that trigger a reload on change.
                                    Multiple paths are separated by ':'.
    --help                          Show this message and exit.  

O argumento --host informa ao servido qual é o ambiente web que pode acessar nosso servidor de desenvolvimento. Por default o servidor de desenvovimento do Flask só aceita chamadas do computador local, em localhost. Mas é possível configurá-lo para receber chamadas da rede local ou de ambientes mais amplos. Por exemplo, como o código

(venv) $ flask run --host 0.0.0.0
 * Serving Flask app "hello"
 * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit)

todos os computadores conectados pelo mesmo ip terão acesso ao aplicativo.

Implantação de um aplicativo Flask

O processo de implantação (ou deploy) de um aplicativo consiste nas etapas necessários para colocá-lo acessível para seus usuários. No caso de um aplicativo web a implantação significa estabelecer um servidor ou usar servidores já disponíveis, que os usuários possam acessar, e colocar seu aplicativo como um de seus serviços.

O desenvolvimento do aplicativo se dá em um ambiente de desenvolvimento onde podem existir condições próprias para o debug e nem todas as medidas de segurança estão implementadas. Depois ele passa para a etapa de uso, no ambiente de produção. Uma conta no Heroku pode ser criada, e um site com poucos acessos pode ser mantido sem custos. Se o site for escalonado e crescer a conta deve ser atualizada e paga. A lista abaixo contém links para o Heroku e outros provedores.

Bibliografia

Livros sobre Flask

  • Aggarwal, Shalabh: Flask Framework Cookbook, 2.Ed., Packt, Birmingham-Mumbai, 2019.
  • Ashley, David: Foundation Dynamic Web Pages with Python Create Dynamic Web Pages with Django and Flask, Apress, 2020.
  • Gaspar, D.;StoufferHaider, J.: Mastering Flask Web Development, 2.Ed., Packt, Birmingham-Mumbai, 2018.
  • Grinberg, Miguel: The Flask Mega-Tutorial, Edição do autor, 2020.
  • Grinberg, Miguel: Flask Web Development, Developing Web Applications with Python, O’Reilly, Sebastopol, 2018.
  • Haider, Rehan: Web API Development With Python, CloudBytes, 2020.
  • Maia, Italo: Building Web Applications with Flask, 2.Ed., Packt, Birmingham-Mumbai, 2015.
  • Relan, Kunal: Building REST APIs with Flask, 2.Ed., Apress, 2019.

Referências na Web

Sobre HTML e CSS

todos acessados em fevereiro de 2022.