Skip to content

3. O modelo da action

Uma action precisa das informações enviadas pelo navegador: os parâmetros da URL ([?name=martin&age=42]), os campos de formulário, o corpo JSON da requisição e, às vezes, um cabeçalho de requisição HTTP. O curso original chama todas essas informações de modelo da action. Este capítulo mostra como uma action recupera essas informações, as converte no tipo correto e as valida. Esse processo se chama binding de dados.

O [Flask] é aqui muito mais minimalista que outros frameworks: ele dá acesso às informações da requisição na forma de strings e para por aí. Converter ["42"] no inteiro 42, verificar se um nome tem pelo menos dois caracteres, montar os campos em um objeto: tudo isso fica a cargo da aplicação. Faremos isso primeiro à mão (Exemplo 07) e depois com a biblioteca [Pydantic] (Exemplos 08 a 12), que descreve um modelo por meio de uma classe na qual cada campo declara seu tipo e suas restrições. No próximo capítulo, os formulários HTML serão tratados por outra biblioteca, [WTForms], concebida especificamente para eles; o [Pydantic] continua sendo a ferramenta natural para os parâmetros de uma URL e para os corpos JSON da API.

Observação sobre a terminologia: no capítulo seguinte, a palavra “modelo” designará principalmente os dados que uma action transmite à sua view. O modelo de uma action, no sentido usado neste capítulo, é o que ela recebe.

Os Exemplos 07 a 12 são executados da mesma forma que os do capítulo anterior: abra um terminal na pasta do exemplo, com o ambiente virtual ativado ([python app.py]); [Ctrl-C] interrompe o servidor. Seus arquivos [app.py] são todos parecidos: uma factory [create_app] que cria a aplicação, configura o provedor JSON (acentos preservados, chaves na ordem original; veja o Exemplo 03) e registra um blueprint. Só os comentaremos quando trouxerem algo novo.

3.1. Exemplo 07: os parâmetros da URL

Os parâmetros da URL são a parte que segue o [?]: [?name=martin&age=42]. Essa parte se chama query string (*query string*). Cada parâmetro é um par [name=value]; os pares são separados por [&]. O arquivo [controllers/parameters.py]:

# controllers/parameters.py: os parâmetros da URL (a "query string")
from flask import Blueprint, abort, request

parameters = Blueprint("parameters", __name__, url_prefix="/parameters")


# /parameters/action01?name=martin: request.args contém os parâmetros da
# URL; get retorna o valor do parâmetro, ou None se ele estiver ausente
@parameters.get("/action01")
def action01():
    name = request.args.get("name")
    return f"name = [{name}], of type {type(name).__name__}"


# /parameters/action02?age=42: type=int CONVERTE o valor (uma string) em
# inteiro; um parâmetro ausente, ou que não seja um inteiro, resulta em None
@parameters.get("/action02")
def action02():
    age = request.args.get("age", type=int)
    return f"age = [{age}], of type {type(age).__name__}"


# /parameters/action03?age=42: um parâmetro OBRIGATÓRIO; sua ausência, ou um
# valor que não seja um inteiro, interrompe a ação com uma resposta 400 (Bad Request)
@parameters.get("/action03")
def action03():
    text = request.args.get("age")
    if text is None:
        # abort lança uma exceção, que o Flask transforma em uma resposta de erro
        abort(400, "the [age] parameter is required")
    # a conversão fica por nossa conta
    try:
        age = int(text)
    except ValueError:
        abort(400, f"[{text}] is not an integer")
    return f"age = [{age}], of type {type(age).__name__}"


# /parameters/action04?page=2: um valor padrão se o parâmetro estiver ausente
@parameters.get("/action04")
def action04():
    page = request.args.get("page", default=1, type=int)
    return f"page = [{page}]"


# /parameters/action05?q=flask: o nome do parâmetro da URL não é necessariamente
# o da variável Python
@parameters.get("/action05")
def action05():
    search = request.args.get("q")
    return f"search = [{search}]"


# /parameters/action06?name=martin&age=42: todos os parâmetros de uma vez, como um dicionário
@parameters.get("/action06")
def action06():
    return request.args.to_dict()
  • linha 11: [request.args] contém os parâmetros da URL, já decodificados pelo [Werkzeug]. É um dicionárioespecial, um [MultiDict], que, como veremos no Exemplo 10, aceita vários valores por chave. Seu método [get] devolve o valor de um parâmetro, ou [None] se ele estiver ausente. Ao contrário de [request.args["name"]], que lançaria uma exceção para um parâmetro ausente, [get] nunca causa erro;
  • linha 12: a action exibe o valor e seu tipo: [type(x)] é a classe de [x], e [__name__] é o nome dessa classe. Um valor recuperado da URL é sempre uma string ([str]);
  • linha 19: o parâmetro [type] de [get] especifica uma função de conversão aplicada à string: neste caso, [int], a classe dos inteiros, cuja chamada [int("42")] devolve 42. Se a conversão falha ([int("abc")] lança uma [ValueError]), [get] devolve [None], exatamente como para um parâmetro ausente: a action não consegue distinguir os dois casos, e o erro de entrada passa despercebido;
  • Linhas 26–35: um parâmetro obrigatório e uma conversão manual que distingue os dois erros possíveis. [abort(400, message)] encerra a action com uma resposta 400 (*Bad Request* — a requisição é inválida), acompanhada da mensagem (veja o Exemplo 03). A instrução [try] / [except ValueError] captura a exceção lançada por [int];
  • linha 42: um valor padrão, usado se o parâmetro estiver ausente (ou se sua conversão falhar). É um caso típico para o número de página de uma lista;
  • linha 50: não há obrigação de dar à variável [Python] o mesmo nome do parâmetro da URL. Os mecanismos de busca costumam usar um parâmetro curto, [q] (*query*);
  • linha 57: [to_dict()] converte o [MultiDict] em um dicionário [Python] padrão (mantendo apenas o primeiro valor de cada parâmetro), que a action retorna: [Flask] o transforma em JSON (veja o Exemplo 03).

Vamos testar cada action com [curl]. Um parâmetro presente e, depois, ausente:

curl -i "http://localhost:5000/parameters/action01?name=martin"
curl http://localhost:5000/parameters/action01
1
2
3
4
5
6
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 28

name = [martin], of type str
name = [None], of type NoneType

As aspas em torno da URL são necessárias em um terminal: sem elas, o shell interpretaria [&] (que executa um comando em segundo plano no [Linux]) e [?]. Um valor que contenha espaços ou caracteres especiais deve ser codificado na URL: um espaço vira [%20], e [&] vira [%26] (caso contrário, separaria dois parâmetros). O navegador faz isso automaticamente; com [curl], é preciso escrevê-lo manualmente. [Werkzeug] decodifica o valor antes de armazená-lo em [request.args]:

curl "http://localhost:5000/parameters/action01?name=jean%20dupont%20%26%20sons"
name = [jean dupont & sons], of type str

A conversão com [type=int], que primeiro teve sucesso e depois falhou:

curl "http://localhost:5000/parameters/action02?age=42"
curl "http://localhost:5000/parameters/action02?age=abc"
age = [42], of type int
age = [None], of type NoneType

O parâmetro obrigatório da action 03, ausente e depois inválido:

curl -i http://localhost:5000/parameters/action03
curl "http://localhost:5000/parameters/action03?age=abc"
HTTP/1.1 400 BAD REQUEST
Content-Type: text/html; charset=utf-8
Content-Length: 122

<!doctype html>
<html lang=en>
<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>the [age] parameter is required</p>
<!doctype html>
<html lang=en>
<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>[abc] is not an integer</p>

O valor padrão e o parâmetro renomeado:

1
2
3
curl http://localhost:5000/parameters/action04
curl "http://localhost:5000/parameters/action04?page=3"
curl "http://localhost:5000/parameters/action05?q=flask"
1
2
3
page = [1]
page = [3]
search = [flask]

Por fim, todos os parâmetros de uma vez. O parâmetro [name] aparece duas vezes: [to_dict()] mantém apenas o primeiro valor.

curl "http://localhost:5000/parameters/action06?name=martin&age=42&name=durand"
1
2
3
4
{
  "name": "martin",
  "age": "42"
}

A idade continuou sendo uma string (["42"], entre aspas no JSON): nenhuma conversão foi solicitada. Em um navegador (aqui [Chromium]), o JSON aparece em uma única linha: [Flask] só indenta o JSON no modo de depuração, e a captura de tela foi feita sem ele; a caixa de seleção “Pretty-print” o exibiria indentado. Aliás, a barra de endereços mostra a codificação dos caracteres acentuados na URL ([é] vira [%C3%A9], com seus dois bytes em [UTF-8]):

Image

Este primeiro exemplo ilustra os limites da abordagem manual: para cada parâmetro, é preciso escrever a leitura, a conversão e o tratamento dos valores ausentes e dos erros. Com dez parâmetros, o código da action ficaria sobrecarregado por essas verificações. É melhor descrever o que se espera e deixar que uma biblioteca cuide da verificação. É o objetivo do exemplo seguinte.

3.2. Exemplo 08: um modelo de action descrito por uma classe

[Pydantic] é a biblioteca de validação de dados mais usada em [Python] (está no núcleo do framework [FastAPI]). Ela descreve os dados esperados por meio de uma classe: cada atributo tem um tipo e, opcionalmente, restrições. [Pydantic] encarrega-se de converter os dados recebidos nesses tipos e de validar as restrições. Ela está instalada no ambiente virtual do exemplo (arquivo [requirements.txt]).

3.2.1. O modelo: models/person.py

# models/person.py: o modelo da ação, uma classe Pydantic na qual cada
# campo carrega seu tipo e suas restrições
from typing import Annotated, Literal

from pydantic import BaseModel, ConfigDict, EmailStr, Field


class PersonModel(BaseModel):
    # as strings recebidas têm os espaços ao redor removidos
    model_config = ConfigDict(str_strip_whitespace=True)

    # obrigatório (sem valor padrão), de 2 a 20 caracteres
    name: Annotated[str, Field(min_length=2, max_length=20)]
    # um inteiro ("42" é convertido em 42), entre 0 e 150
    age: Annotated[int, Field(ge=0, le=150)]
    # somente um destes três valores
    title: Literal["Mr", "Mme", "Melle"]
    # opcional (None por padrão); se presente, um endereço de e-mail válido
    email: EmailStr | None = None
  • Linha 8: um modelo [Pydantic] é uma classe que herda de [BaseModel]. Seus atributos são declarados no nível da classe, junto com seus tipos, como em uma [dataclass] (Exemplo 06);
  • Linha 10: a configuração do modelo. [str_strip_whitespace=True] remove os espaços ao redor das strings recebidas: um nome digitado como [" martin "] passa a ser ["martin"] antes de ser validado. O atributo [model_config] não é um campo do modelo: [Pydantic] reconhece esse nome reservado;
  • Linha 13: o campo [name]. [Annotated[str, Field(...)]] lê-se “o tipo [str], anotado por [Field(...)]”. [Annotated], do módulo padrão [typing], permite anexar informações adicionais a um tipo — informações que [Python] ignora, mas que as bibliotecas leem: aqui, as restrições de [Pydantic], um comprimento de 2 a 20 caracteres ([min_length], [max_length]). O campo não tem valor padrão: ele é obrigatório;
  • linha 15: o tipo [int]: [Pydantic] converte a string ["42"] no inteiro 42 e rejeita ["abc"]. As restrições [ge] (*greater or equal*) e [le] (*less or equal*) limitam o valor. Também existem [gt] e [lt] para desigualdades estritas;
  • linha 17: [Literal["Mr", "Mme", "Melle"]] é o tipo dos três valores listados, e apenas desses;
  • linha 19: [EmailStr] é o tipo de um endereço de e-mail; [Pydantic] valida sua sintaxe com a biblioteca [email-validator] (que também é instalada por [requirements.txt]). [EmailStr | None]: um endereço ou [None]. O valor padrão [= None] torna o campo opcional.

Este modelo descreve os dados esperados; ele não contém nenhuma instrução de validação. Isso é chamado de estilo declarativo.

3.2.2. A action: controllers/persons.py

# controllers/persons.py: uma ação cujo modelo é uma classe Pydantic
from flask import Blueprint, request

from models.person import PersonModel

persons = Blueprint("persons", __name__, url_prefix="/persons")


# /persons/action01?name=martin&age=42&title=Mr
# model_validate: o Pydantic cria o objeto a partir do dicionário de parâmetros
# (BINDING: conversão das strings para o tipo de cada campo), depois verifica
# as restrições (VALIDAÇÃO). Um modelo inválido lança uma ValidationError,
# transformada em uma resposta 400 pelo app.py: a ação para por aí
@persons.get("/action01")
def action01():
    person = PersonModel.model_validate(request.args.to_dict())
    return {
        # model_dump: o objeto como dicionário (serializável em JSON)
        "person": person.model_dump(),
        "ageType": type(person.age).__name__,
    }
  • Linha 16: o método de classe [model_validate] cria um objeto [PersonModel] a partir de um dicionário — neste caso, o que contém os parâmetros da URL. Ele executa duas operações, nesta ordem: - binding: cada valor do dicionário é atribuído ao campo de mesmo nome, depois de ser convertido para o tipo do campo (["42"] → 42); - validação: as restrições de cada campo são verificadas (comprimento, limites, valores permitidos etc.).
  • Se uma das duas etapas falhar, [model_validate] lança uma exceção [ValidationError], que contém uma lista de todos os erros (não apenas o primeiro). A action não a trata: ela é interrompida; veremos quem cuida disso;
  • linha 19: [model_dump()] retorna o objeto como um dicionário, que o [Flask] pode converter em JSON;
  • linha 20: o tipo da idade, para mostrar que a conversão ocorreu.

3.2.3. Tratamento de erros: app.py

# app.py: a aplicação do exemplo 08
from flask import Flask
from pydantic import ValidationError

from controllers.persons import persons


def create_app():
    app = Flask(__name__)
    # JSON: acentos mantidos, chaves em sua ordem original (veja o exemplo 03)
    app.json.ensure_ascii = False
    app.json.sort_keys = False
    app.register_blueprint(persons)

    # um modelo inválido: a exceção ValidationError do Pydantic se torna,
    # para a aplicação INTEIRA, uma resposta 400 que detalha os erros
    @app.errorhandler(ValidationError)
    def invalid_model(e: ValidationError):
        errors = [{"field": ".".join(str(x) for x in err["loc"]), "message": err["msg"]}
                  for err in e.errors()]
        return {"status": 400, "errors": errors}, 400

    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Linhas 17–21: o decorador [@app.errorhandler(ValidationError)] registra um tratador de exceções: quando uma action lança uma [ValidationError] (ou uma exceção de uma classe derivada), o [Flask] chama essa função, passando a exceção como parâmetro, e usa o valor retornado por ela como resposta. Declarado no nível da aplicação, o tratador vale para todas as suas actions: toda action que valida um modelo se beneficia dele, sem precisar escrever uma única linha de código de tratamento de erros;
  • Linha 19: [e.errors()] retorna a lista de erros. Cada erro é um dicionário; mantemos duas informações: [loc] (*location*), o campo afetado, na forma de uma tupla ([("name",)]; veja o Exemplo 10 para uma tupla mais longa), e [msg], a mensagem. A expressão [[... for err in e.errors()]] é uma compreensão de lista: ela constrói uma lista aplicando a expressão da esquerda a cada elemento;
  • linha 21: uma tupla [(body, code)] (veja o Exemplo 03): um dicionário, convertido em JSON, e o código 400.

3.2.4. Execução

Um modelo válido:

curl -i "http://localhost:5000/persons/action01?name=martin&age=42&title=Mr"
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 116

{
  "person": {
    "name": "martin",
    "age": 42,
    "title": "Mr",
    "email": null
  },
  "ageType": "int"
}

A idade de fato se tornou um inteiro (sem aspas no JSON), e o endereço ausente é [None] ([null] no JSON). Um nome cercado de espaços ([%20]) e um endereço presente:

curl "http://localhost:5000/persons/action01?name=%20%20martin%20&age=42&title=Mme&email=martin@example.com"
1
2
3
4
5
6
7
8
9
{
  "person": {
    "name": "martin",
    "age": 42,
    "title": "Mme",
    "email": "martin@example.com"
  },
  "ageType": "int"
}

Nenhum parâmetro: os três campos obrigatórios estão ausentes.

curl -i http://localhost:5000/persons/action01
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
Content-Length: 248

{
  "status": 400,
  "errors": [
    {
      "field": "name",
      "message": "Field required"
    },
    {
      "field": "age",
      "message": "Field required"
    },
    {
      "field": "title",
      "message": "Field required"
    }
  ]
}

Quatro campos inválidos ao mesmo tempo:

curl "http://localhost:5000/persons/action01?name=m&age=abc&title=Mlle&email=xx"
{
  "status": 400,
  "errors": [
    {
      "field": "name",
      "message": "String should have at least 2 characters"
    },
    {
      "field": "age",
      "message": "Input should be a valid integer, unable to parse string as an integer"
    },
    {
      "field": "title",
      "message": "Input should be 'Mr', 'Mme' or 'Melle'"
    },
    {
      "field": "email",
      "message": "value is not a valid email address: An email address must have an @-sign."
    }
  ]
}

Todos os erros são relatados de uma só vez, o que permite ao usuário corrigir tudo de uma vez. As mensagens estão em inglês: [Pydantic] não é traduzido. O exemplo seguinte as substitui por mensagens próprias.

3.3. Exemplo 09: validação realizada pela action

No Exemplo 08, um formulário inválido interrompe a action, e o tratador da aplicação responde. Isso é conveniente para uma API, cujos clientes são programas que esperam uma resposta de erro padronizada. No entanto, uma página web muitas vezes prefere reexibir o formulário com as mensagens de erro: nesse caso, a action deve decidir como tratar um modelo inválido. O modelo [models/person.py] é o do Exemplo 08.

3.3.1. Mensagens personalizadas: models/messages.py

# models/messages.py: as mensagens dos erros de validação, em inglês.
# Cada erro do Pydantic é um dicionário: seu TIPO ("missing",
# "string_too_short"...), o campo envolvido (loc), uma mensagem em inglês (msg),
# e o contexto (ctx): os valores das restrições ({"min_length": 2}...)
MESSAGES = {
    "missing": "the field is required",
    "string_too_short": "{min_length} character(s) at least",
    "string_too_long": "{max_length} character(s) at most",
    "int_parsing": "an integer is expected",
    "greater_than_equal": "the value must be greater than or equal to {ge}",
    "less_than_equal": "the value must be less than or equal to {le}",
    "literal_error": "unknown value",
    "value_error": "invalid value",
    "too_short": "{min_length} item(s) at least",
}


# o nome do campo: loc é uma tupla, ("name",) ou ("color", 1) para o 2º
# item de uma lista
def field(error: dict) -> str:
    return ".".join(str(x) for x in error["loc"])


# nossa própria mensagem; um tipo de erro desconhecido mantém a mensagem do Pydantic
def message_en(error: dict) -> str:
    template = MESSAGES.get(error["type"])
    if template is None:
        return error["msg"]
    # format substitui {min_length}... pelos valores do contexto
    return template.format(**error.get("ctx", {}))
  • Linhas 5–14: cada erro do [Pydantic] tem um tipo e um identificador único (["missing"] para um campo ausente, ["string_too_short"] para uma string curta demais etc.), independente da mensagem em inglês. O dicionário [MESSAGES] associa uma mensagem própria a cada tipo. Algumas contêm marcadores como [{min_length}], [{ge}]...: a documentação do [Pydantic] fornece, para cada tipo de erro, os valores de seu contexto;
  • linhas 20–21: o nome do campo que causou o erro, extraído da tupla [loc]. [".".join(...)] reúne os elementos da tupla — convertidos em strings — separando-os por pontos;
  • linhas 25–30: nossa própria mensagem de erro. [MESSAGES.get(...)] retorna [None] para um tipo de erro que não está no dicionário; nesse caso, usa-se a mensagem em inglês do [Pydantic]. Caso contrário, [format] substitui cada ocorrência de [{name}] na mensagem pelo valor de mesmo nome do contexto: ["{min_length} character(s) at least".format(min_length=2)] produz ["2 character(s) at least"]. A notação [**dictionary] passa as entradas do dicionário como parâmetros nomeados; [error.get("ctx", {})] retorna um dicionário vazio para um erro sem contexto.

Essa técnica (traduzir com base no tipo do erro) é a usada no estudo de caso: ali, as mensagens são identificadas por chaves, que são traduzidas para o idioma do usuário.

3.3.2. A action: controllers/persons.py

# controllers/persons.py: é a ação que decide o que fazer com um modelo inválido
from flask import Blueprint, request
from markupsafe import escape
from pydantic import ValidationError

from models.messages import field, message_en
from models.person import PersonModel

persons = Blueprint("persons", __name__, url_prefix="/persons")


@persons.get("/action01")
def action01():
    try:
        person = PersonModel.model_validate(request.args.to_dict())
    except ValidationError as e:
        # os erros, campo por campo: e.errors() fornece sua lista
        items = "".join(f"<li>{field(error)}: {message_en(error)}</li>" for error in e.errors())
        return f"<p>The form contains errors:</p><ul>{items}</ul>"
    # escape: o nome digitado é inserido em HTML; seus caracteres < > & " '
    # são substituídos por &lt; &gt;... (caso contrário, uma entrada poderia injetar HTML)
    return f"<p>Welcome {person.title} {escape(person.name)} ({person.age} years old)</p>"
  • Linhas 14–19: a própria action intercepta a [ValidationError] dentro de um bloco [try] / [except] . Se ocorrer um erro, ela constrói uma lista HTML de erros ([<ul>], uma tag [<li>] por erro);
  • linha 22: em caso de sucesso, uma mensagem de boas-vindas. O nome passa pela função [escape] da biblioteca [markupsafe] (instalada com o [Flask]). [escape] substitui os caracteres que têm significado em HTML ([<], [>], [&], ["], [']) por suas entidades ([&lt;], [&gt;]...): elas serão exibidas como estão, em vez de interpretadas. Sem essa precaução, um usuário poderia digitar um “nome” contendo HTML, ou até mesmo [JavaScript], que seria executado no navegador de qualquer pessoa que visse a página. Essa é a vulnerabilidade de segurança mais comum na web: injeção de script (*XSS*, *cross-site scripting*). O título e a idade não exigem essa proteção: seus valores foram validados pelo modelo (um de três valores permitidos, um inteiro). No próximo capítulo, a engine de views [Jinja2] fará esse escape automaticamente para qualquer valor inserido em uma página.

Uma entrada válida, seguida de uma entrada com quatro erros:

Image

Image

A resposta bruta à segunda requisição e a resposta para um nome contendo HTML:

curl "http://localhost:5000/persons/action01?name=m&age=abc&title=Mx&email=xx"
curl "http://localhost:5000/persons/action01?name=%3Cb%3Emartin%3C/b%3E&age=42&title=Mr"
<p>The form contains errors:</p><ul><li>name: 2 character(s) at least</li><li>age: an integer is expected</li><li>title: unknown value</li><li>email: invalid value</li></ul>
<p>Welcome Mr &lt;b&gt;martin&lt;/b&gt; (42 years old)</p>

O nome [<b>martin</b>] (codificado como [%3Cb%3E...] na URL) é exibido como está, sem ficar em negrito: suas tags foram neutralizadas. Observe que, desta vez, a resposta tem o código de status 200: isso acontece porque a action optou por retornar uma página normal contendo os erros.

3.4. Exemplo 10: vários parâmetros

O mesmo parâmetro pode aparecer várias vezes em uma URL: [?color=red&color=green]. É o que um navegador envia para um grupo de caixas de seleção com o mesmo nome, ou para uma lista de seleção múltipla (veja o próximo capítulo). O arquivo [controllers/arrays.py]:

# controllers/arrays.py: um parâmetro que aparece várias vezes na URL
from flask import Blueprint, request
from pydantic import ValidationError

from models.choice import ChoiceModel
from models.messages import field, message_en

arrays = Blueprint("arrays", __name__, url_prefix="/arrays")


# /arrays/action01?color=red&color=green: get retorna somente o PRIMEIRO valor
@arrays.get("/action01")
def action01():
    return {"color": request.args.get("color")}


# /arrays/action02?color=red&color=green: getlist retorna TODOS os
# valores, em uma lista (vazia se o parâmetro estiver ausente)
@arrays.get("/action02")
def action02():
    colors = request.args.getlist("color")
    return {"color": colors, "count": len(colors)}


# /arrays/action03?color=red: uma lista, validada por ChoiceModel
@arrays.get("/action03")
def action03():
    colors = request.args.getlist("color")
    try:
        ChoiceModel(color=colors)
        errors = []
    except ValidationError as e:
        errors = [f"{field(error)}: {message_en(error)}" for error in e.errors()]
    return {"colors": colors, "valid": not errors, "errors": errors}
  • linha 14: [get] retorna apenas o primeiro valor do parâmetro;
  • linha 21: [getlist] retorna todos os seus valores em uma lista, que fica vazia se o parâmetro estiver ausente. Essa é a característica distintiva do [MultiDict]: ele mantém a lista de valores de cada chave;
  • linhas 27–34: a lista é validada com um modelo [Pydantic]. Desta vez, o modelo é construído por uma chamada padrão, [ChoiceModel(color=colors)], com os campos passados como parâmetros nomeados: isso equivale a [model_validate] em um dicionário. O objeto criado só serve para a validação: ele não é guardado. A expressão [not errors] equivale a [True] para uma lista vazia.

O modelo [models/choice.py]:

# models/choice.py: uma lista, e uma restrição sobre CADA item da lista
from typing import Annotated, Literal

from pydantic import BaseModel, Field


class ChoiceModel(BaseModel):
    # list[Literal[...]]: cada item deve ser "red", "green" ou "blue";
    # min_length=1: a lista deve conter pelo menos um item
    color: Annotated[list[Literal["red", "green", "blue"]], Field(min_length=1)]
  • Linha 10: o tipo [list[Literal["red", "green", "blue"]]] é o de uma lista em que cada elemento é uma de três cores. A restrição [min_length=1], aplicada a uma lista, refere-se ao número de elementos: deve haver pelo menos um.

O arquivo [models/messages.py] é o do Exemplo 09. Os resultados:

1
2
3
curl "http://localhost:5000/arrays/action01?color=red&color=green"
curl "http://localhost:5000/arrays/action02?color=red&color=green"
curl http://localhost:5000/arrays/action02
{
  "color": "red"
}
{
  "color": [
    "red",
    "green"
  ],
  "count": 2
}
{
  "color": [],
  "count": 0
}

A validação teve sucesso no início, depois falhou por causa de uma cor desconhecida e, em seguida, por causa de uma lista vazia:

1
2
3
curl "http://localhost:5000/arrays/action03?color=red&color=blue"
curl "http://localhost:5000/arrays/action03?color=red&color=yellow"
curl http://localhost:5000/arrays/action03
{
  "colors": [
    "red",
    "blue"
  ],
  "valid": true,
  "errors": []
}
{
  "colors": [
    "red",
    "yellow"
  ],
  "valid": false,
  "errors": [
    "color.1: unknown value"
  ]
}
{
  "colors": [],
  "valid": false,
  "errors": [
    "color: 1 item(s) at least"
  ]
}

O erro “unknown value” refere-se a [color.1]: a tupla de erro [loc] é [("color", 1)]; o campo e o índice do elemento problemático na lista (o segundo, já que os índices começam em 0).

3.5. Exemplo 11: os parâmetros de uma requisição POST

Os exemplos anteriores usavam requisições GET, cujos parâmetros estão contidos na URL. Uma requisição POST transporta seus dados no corpo, em duas formas principais:

  • campos de um formulário HTML: o corpo tem a mesma sintaxe de uma query string ([name=martin&age=42]), e seu tipo (cabeçalho [Content-Type]) é [application/x-www-form-urlencoded];
  • um documento JSON, enviado por um programa ([JavaScript] em uma página, cliente de uma API...): o tipo é [application/json].

O arquivo [controllers/post.py]:

# controllers/post.py: os parâmetros de uma requisição POST
from flask import Blueprint, request
from pydantic import ValidationError

from models.messages import field, message_en
from models.person import PersonModel

post = Blueprint("post", __name__, url_prefix="/post")


# os campos de um formulário HTML (corpo application/x-www-form-urlencoded):
# request.form, um dicionário "multi" (MultiDict), como request.args
@post.post("/action01")
def action01():
    return {
        "receivedType": request.content_type,
        # flat=False: cada campo -> a lista de seus valores
        "fields": request.form.to_dict(flat=False),
    }


# um corpo JSON: get_json o desserializa (dicionário, lista...); um corpo
# que não é JSON -> erro 415 (tipo não suportado) ou 400 (JSON malformado)
@post.post("/action02")
def action02():
    return {"receivedType": request.content_type, "body": request.get_json()}


# um único campo do formulário
@post.post("/action03")
def action03():
    name = request.form.get("name")
    return f"name = [{name}]"


# os campos do formulário, vinculados e validados pela classe PersonModel
@post.post("/action04")
def action04():
    try:
        person = PersonModel.model_validate(request.form.to_dict()).model_dump()
        errors = []
    except ValidationError as e:
        person = None
        errors = sorted(f"{field(error)}: {message_en(error)}" for error in e.errors())
    return {"person": person, "valid": not errors, "errors": errors}
  • linha 13: [post.post(...)]: o primeiro [post] é o blueprint, o segundo é o método que declara uma rota para o método HTTP POST (veja o Exemplo 02);
  • linha 16: [request.content_type] é o cabeçalho [Content-Type] da requisição;
  • linha 18: [request.form] contém os campos de um formulário enviado por POST. Assim como [request.args], é um [MultiDict]. [to_dict(flat=False)] cria, na verdade, um dicionário em que cada valor é a lista de valores do campo;
  • linha 26: [request.get_json()] desserializa um corpo JSON: o texto JSON se torna um objeto [Python] (um dicionário para um objeto JSON, uma lista para um array JSON...). Se o corpo não for declarado como JSON, [get_json] causa um erro 415 (*Unsupported Media Type*); se for, mas o texto estiver malformado, ocorre um erro 400;
  • linha 32: um campo, interpretado como parâmetro da URL;
  • linhas 38–45: o modelo [PersonModel] do Exemplo 08, desta vez ligado aos campos do formulário. O código é o mesmo que com os parâmetros da URL: só muda a origem do dicionário. [sorted] ordena as mensagens para garantir uma resposta consistente.

Com o [curl], a opção [-d] (*data*) envia um corpo; a requisição passa então a ser POST, do tipo [application/x-www-form-urlencoded], a menos que a opção [-H] (*header*) especifique outro tipo. A opção [-X POST] define o método explicitamente (aqui ela é opcional). Os campos de um formulário, incluindo um campo repetido:

curl -i -X POST -d "name=martin&age=42&hobby=tennis&hobby=piano" http://localhost:5000/post/action01
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 195

{
  "receivedType": "application/x-www-form-urlencoded",
  "fields": {
    "name": [
      "martin"
    ],
    "age": [
      "42"
    ],
    "hobby": [
      "tennis",
      "piano"
    ]
  }
}

Um corpo JSON, que contém um inteiro e um array:

curl -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": 42, \"children\": [\"léa\", \"tom\"]}" http://localhost:5000/post/action02
{
  "receivedType": "application/json",
  "body": {
    "name": "martin",
    "age": 42,
    "children": [
      "léa",
      "tom"
    ]
  }
}

As aspas do JSON são precedidas por uma [\] para evitar que a string do comando termine; no [Linux] e no [macOS], também é possível envolver o JSON em apóstrofos: [-d '{"name": "martin"}']. Diferentemente dos campos de formulário, o JSON carrega tipos de dados: a idade já é um inteiro. Um corpo que não é JSON, seguido de um JSON malformado:

curl -i -d "name=martin" http://localhost:5000/post/action02
curl -i -H "Content-Type: application/json" -d "{\"name\": " http://localhost:5000/post/action02
HTTP/1.1 415 UNSUPPORTED MEDIA TYPE
Content-Type: text/html; charset=utf-8
Content-Length: 215

<!doctype html>
<html lang=en>
<title>415 Unsupported Media Type</title>
<h1>Unsupported Media Type</h1>
<p>Did not attempt to load JSON data because the request Content-Type was not &#39;application/json&#39;.</p>
HTTP/1.1 400 BAD REQUEST
Content-Type: text/html; charset=utf-8
Content-Length: 163

<!doctype html>
<html lang=en>
<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>Failed to decode JSON object: Expecting value: line 1 column 10 (char 9)</p>

Um único campo e, depois, a mesma URL requisitada como GET:

curl -d "name=jean%20dupont" http://localhost:5000/post/action03
curl -i "http://localhost:5000/post/action03?name=martin"
name = [jean dupont]
HTTP/1.1 405 METHOD NOT ALLOWED
Content-Type: text/html; charset=utf-8
Allow: POST, OPTIONS
Content-Length: 153

<!doctype html>
<html lang=en>
<title>405 Method Not Allowed</title>
<h1>Method Not Allowed</h1>
<p>The method is not allowed for the requested URL.</p>

A URL existe, mas não para o método GET: [Flask] retorna um 405 (*Method Not Allowed*), e seu cabeçalho [Allow] lista os métodos aceitos ([OPTIONS] é tratado automaticamente pelo [Flask] para qualquer rota). Por fim, o modelo ligado aos campos do formulário, primeiro válido e depois inválido:

curl -d "name=martin&age=42&title=Mr" http://localhost:5000/post/action04
curl -d "name=m&age=200" http://localhost:5000/post/action04
{
  "person": {
    "name": "martin",
    "age": 42,
    "title": "Mr",
    "email": null
  },
  "valid": true,
  "errors": []
}
{
  "person": null,
  "valid": false,
  "errors": [
    "age: the value must be less than or equal to 150",
    "name: 2 character(s) at least",
    "title: the field is required"
  ]
}

3.6. Exemplo 12: binding e validação personalizados

Os tipos padrão nem sempre bastam. Este exemplo mostra três maneiras de estender o binding e a validação:

  • um conversor de caminho: uma data no formato francês, [23-09-2026], no caminho da URL;
  • um decorador que fornece à action um parâmetro que não vem da URL, mas de um cabeçalho HTTP;
  • tipos “personalizados” para o [Pydantic]: uma restrição (sem espaços) e uma conversão (uma data [dd/mm/yyyy]).
1
2
3
4
5
6
7
8
12-custom-binding/
├── app.py
├── binding/
│   ├── date_fr.py
│   ├── language.py
│   └── types.py
└── controllers/
    └── examples.py

3.6.1. Um conversor de caminho: binding/date_fr.py

No Exemplo 02, conhecemos os conversores do [Werkzeug]: [<int:id>] aceita apenas um inteiro e o converte. É possível escrever novos.

# binding/date_fr.py: uma data francesa "23-09-2026" no caminho da URL
from datetime import date, datetime

from werkzeug.routing import BaseConverter, ValidationError


# um CONVERSOR do Werkzeug (a biblioteca na qual o Flask é construído):
# ele decide se um pedaço do caminho é adequado e o transforma em um objeto Python
class DateFrConverter(BaseConverter):
    # a expressão regular do pedaço do caminho: dd-mm-yyyy
    regex = r"\d{2}-\d{2}-\d{4}"

    # texto do caminho -> objeto date
    def to_python(self, value: str) -> date:
        try:
            # strptime verifica se a data existe: "31-02-2026" é rejeitada
            return datetime.strptime(value, "%d-%m-%Y").date()
        except ValueError:
            # a rota não corresponde: o Flask procura outra rota e, se não achar, responde 404
            raise ValidationError()

    # objeto date -> texto do caminho (usado por url_for)
    def to_url(self, value: date) -> str:
        return value.strftime("%d-%m-%Y")
  • linha 9: um conversor é uma classe que herda de [BaseConverter];
  • linha 11: o atributo [regex] é uma expressão regular que descreve o formato do segmento de caminho aceito: [\d] indica um dígito, [{2}] indica a repetição do elemento anterior — neste caso, dois dígitos. O prefixo [r] na string (*raw string*) impede que o [Python] interprete [\]. O roteamento só tenta usar esse conversor em um segmento de caminho com esse formato;
  • linhas 14–20: [to_python] transforma o texto do caminho em um objeto [Python], neste caso um [date]. [datetime.strptime] (*string parse time*) analisa uma string segundo um formato específico: [%d] para o dia, [%m] para o mês e [%Y] para o ano com quatro dígitos; [.date()] mantém a data sem a hora. [strptime] verifica se a data existe: [31-02-2026] tem o formato correto, mas lança uma [ValueError]. O conversor então lança a exceção [ValidationError] do [Werkzeug] (que não deve ser confundida com a do [Pydantic]): para o roteamento, a rota não corresponde à URL, o que resultará em um erro 404 se nenhuma outra rota corresponder a ela;
  • Linhas 23–24: a operação inversa, usada por [url_for] para construir uma URL a partir de uma data. [strftime] (*string format time*) formata uma data.

O conversor é registrado em [app.py]:

# app.py: a aplicação do exemplo 12
from flask import Flask

from controllers.examples import examples
from binding.date_fr import DateFrConverter


def create_app():
    app = Flask(__name__)
    # um conversor de variável de caminho, com o nome [datefr]: as rotas
    # agora podem escrever <datefr:day>, como <int:id>
    app.url_map.converters["datefr"] = DateFrConverter
    app.register_blueprint(examples)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Linha 12: [app.url_map] é a tabela de roteamento da aplicação; seu dicionário, [converters], associa um nome a cada conversor ([int], [path]...). Adicionamos o nosso a ele, com o nome [datefr]. A entrada deve preceder a dos blueprints que a utilizam.

3.6.2. Um parâmetro fornecido por um decorador: binding/language.py

Uma action [Flask] recebe como parâmetros as variáveis de caminho e nada mais. Para fornecer a ela informações adicionais, podemos decorar a action: o decorador substitui a action por uma função que calcula a informação e depois chama a action passando-a como parâmetro.

# binding/language.py: um decorador que FORNECE um parâmetro à ação
from functools import wraps

from flask import request


# @with_language, colocado em uma ação, passa a ela o parâmetro [language], lido do
# cabeçalho "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" -> "fr"
def with_language(action):
    # wraps: a função produzida mantém o nome da ação (o Flask o usa
    # para nomear a rota)
    @wraps(action)
    def action_with_language(*args, **kwargs):
        # request.accept_languages: o cabeçalho já analisado pelo Werkzeug;
        # best_match: o idioma preferido do navegador dentre os oferecidos
        kwargs["language"] = request.accept_languages.best_match(["fr", "en"], default="fr")
        return action(*args, **kwargs)

    return action_with_language
  • Linha 9: um decorador é uma função que recebe uma função (neste caso, a action) e retorna outra função (veja o Exemplo 01). Escrever [@with_language] acima de [def hello(...)] equivale a escrever, depois da definição, [hello = with_language(hello)];
  • Linha 13: a função que substituirá a action. [*args] recebe os parâmetros posicionais em uma tupla, e [**kwargs] (*keyword arguments*) recebe os parâmetros nomeados em um dicionário. É assim que o [Flask] passa as variáveis de caminho ([id=3]): a função as recebe sem precisar conhecê-las;
  • linha 16: é adicionado um parâmetro nomeado, [language]. [request.accept_languages] é o cabeçalho de requisição [Accept-Language], já analisado pelo [Werkzeug]. O navegador especifica aqui os idiomas do usuário, em ordem de preferência: [fr-FR,fr;q=0.9,en;q=0.8] (o coeficiente [q] mede a preferência, em uma escala de 0 a 1). [best_match] seleciona, entre os idiomas oferecidos pela aplicação, o que o usuário prefere, ou o valor [default] se nenhum for adequado;
  • linha 17: a chamada à action original, com os parâmetros recebidos e o novo. As notações [*args] e [**kwargs] desempacotam a tupla e o dicionário em parâmetros desta vez;
  • linha 12: a função [action_with_language] recupera o nome ([__name__]) e a documentação da action. Isso é essencial aqui: [Flask] dá a cada rota o nome de sua função (o [hello] de [url_for("examples.hello")]), e se recusaria a registrar duas rotas com o mesmo nome, [action_with_language], caso duas actions usassem o decorador.

Veremos essa abordagem ao longo do curso: os decoradores [@login_required] e [@role_required] do capítulo sobre autenticação são construídos da mesma forma.

3.6.3. Tipos “personalizados” para o Pydantic: binding/types.py

# binding/types.py: tipos "caseiros" para os modelos Pydantic
from datetime import date, datetime
from typing import Annotated

from pydantic import AfterValidator, BeforeValidator


# uma restrição "caseira": a string não deve conter espaço.
# A função recebe o valor JÁ convertido para str; ela o retorna, ou lança
# um ValueError cuja mensagem se torna a do erro de validação
def no_space(value: str) -> str:
    if " " in value:
        raise ValueError("the field must not contain a space")
    return value


# Annotated: o tipo str, complementado por uma verificação executada DEPOIS da
# conversão. NoSpace é então usado como um tipo comum
NoSpace = Annotated[str, AfterValidator(no_space)]


# uma conversão "caseira": "23/09/2026" -> date(2026, 9, 23), executada ANTES da
# validação do tipo date
def date_fr(value):
    if isinstance(value, str):
        try:
            return datetime.strptime(value, "%d/%m/%Y").date()
        except ValueError:
            raise ValueError(f"[{value}] is not a valid dd/mm/yyyy date")
    return value


DateFr = Annotated[date, BeforeValidator(date_fr)]
  • Linhas 11–14: uma função de validação: ela recebe o valor do campo, retorna-o se for válido e, caso contrário, lança uma [ValueError]. A mensagem da exceção torna-se a mensagem do erro de validação;
  • linha 19: o tipo [NoSpace] é o tipo [str], anotado por [AfterValidator(no_space)]: o [Pydantic] chamará a função depois de verificar (e, se necessário, converter) o valor para [str]. Isso nos permite definir, uma única vez, um tipo que pode ser reutilizado em todos os modelos, como um tipo comum;
  • Linhas 24–30: uma função de conversão. O tipo ***[date] do *[Pydantic] aceita strings no formato internacional, ***[2026-09-23]; queremos o formato francês, ***[23/09/2026]. A função recebe o valor bruto : se for uma string, ela a converte em [date]. Qualquer outro valor (um [date]** já construído, por exemplo) é retornado como está;
  • linha 33: [BeforeValidator]: a função é chamada antes da validação do tipo [date], que, portanto, recebe um [date] já construído.

3.6.4. O controller: controllers/examples.py

# controllers/examples.py: binding e validação personalizados
from datetime import date

from flask import Blueprint, request, url_for
from pydantic import BaseModel, ValidationError

from binding.language import with_language
from binding.types import DateFr, NoSpace

examples = Blueprint("examples", __name__, url_prefix="/examples")


# /examples/schedule/23-09-2026: um conversor de caminho personalizado (veja app.py)
@examples.get("/schedule/<datefr:day>")
def schedule(day: date):
    # url_for usa o método to_url do conversor: date -> "23-09-2026"
    return f"schedule for the day [{day}], of type {type(day).__name__}, " \
           f"URL: {url_for('examples.schedule', day=day)}"


# /examples/hello: um parâmetro que não vem da URL, mas de um cabeçalho,
# fornecido pelo decorador @with_language
@examples.get("/hello")
@with_language
def hello(language: str):
    return "Hello!" if language == "en" else "Bonjour !"


# o modelo da busca: dois tipos "caseiros"
class SearchModel(BaseModel):
    keyword: NoSpace | None = None
    since: DateFr | None = None


# /examples/search?keyword=flask&since=01/09/2026
@examples.get("/search")
def search():
    model = SearchModel.model_validate(request.args.to_dict())
    return f"search for [{model.keyword}] since [{model.since}]"


# ——————————————————————————————— erros
# errorhandler de um BLUEPRINT: transforma uma exceção lançada por uma de SUAS
# ações em uma resposta (o mesmo decorador na aplicação vale para todas)
@examples.errorhandler(ValidationError)
def validation(e: ValidationError):
    # a mensagem do primeiro erro, sem o prefixo "Value error, " do Pydantic
    message = e.errors()[0]["msg"].removeprefix("Value error, ")
    return message, 400, {"Content-Type": "text/plain; charset=utf-8"}
  • Linhas 14–18: a variável de caminho [day] usa o conversor [datefr]: a action recebe um [date]. [url_for] constrói a URL dessa mesma action a partir da data, usando o método [to_url] do conversor. O separador [\] no fim da linha continua a instrução na linha seguinte; duas strings literais consecutivas são concatenadas;
  • Linhas 23–25: a ordem dos decoradores importa. Eles são aplicados de baixo para cima: [@with_language] primeiro transforma a action, depois [@examples.get] registra a função transformada no blueprint. Na ordem inversa, o blueprint registraria a action original, e o parâmetro [language] nunca seria fornecido;
  • linhas 30–32: um modelo que usa os dois tipos “personalizados” como se fossem tipos comuns. Os dois campos são opcionais;
  • linhas 45–49: um tratador de exceções, desta vez declarado no blueprint: ele trata apenas as exceções lançadas pelas actions desse blueprint. [removeprefix] remove o prefixo ["Value error, "] da mensagem, que o [Pydantic] acrescenta às mensagens de [ValueError]. A resposta é uma tupla de três elementos: o corpo, o código e um dicionário de cabeçalhos (veja o Exemplo 03), neste caso para uma resposta em texto simples.

3.6.5. Execução

O conversor de caminho:

curl "http://localhost:5000/examples/schedule/23-09-2026"
curl -i "http://localhost:5000/examples/schedule/31-02-2026"
1
2
3
4
5
schedule for the day [2026-09-23], of type date, URL: /examples/schedule/23-09-2026
HTTP/1.1 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 207
...

A data é exibida pelo [Python] no formato internacional (é o resultado da conversão de um [date] em string), mas a URL construída por [url_for] voltou ao formato francês. O dia 31 de fevereiro não existe: 404. Uma data no formato internacional, [2026-09-23], não corresponde ao padrão descrito pela expressão regular: também 404.

O decorador. A opção [-H] do [curl] define o cabeçalho [Accept-Language]:

1
2
3
curl -H "Accept-Language: en-US,en;q=0.9,fr;q=0.8" http://localhost:5000/examples/hello
curl -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:5000/examples/hello
curl http://localhost:5000/examples/hello
1
2
3
Hello!
Bonjour !
Bonjour !

Sem um cabeçalho [Accept-Language] ([curl] não envia nenhum), usa-se o idioma padrão. O capítulo sobre internacionalização voltará a essa questão, com o usuário escolhendo o idioma.

Tipos “personalizados”:

1
2
3
4
5
curl "http://localhost:5000/examples/search?keyword=flask&since=01/09/2026"
curl "http://localhost:5000/examples/search"
curl -i "http://localhost:5000/examples/search?keyword=flask%20mvc"
curl "http://localhost:5000/examples/search?since=2026-09-01"
curl "http://localhost:5000/examples/search?since=31/02/2026"
1
2
3
4
5
6
7
8
9
search for [flask] since [2026-09-01]
search for [None] since [None]
HTTP/1.1 400 BAD REQUEST
Content-Type: text/plain; charset=utf-8
Content-Length: 34

the field must not contain a space
[2026-09-01] is not a valid dd/mm/yyyy date
[31/02/2026] is not a valid dd/mm/yyyy date

3.6.6. Conclusão

Vamos resumir os métodos de que uma action dispõe para obter seu modelo:

Origem
Método
Variáveis de caminho
os parâmetros da action, tipados pelos conversores ([<int:id>], [<datefr:day>])
Parâmetros da URL
[request.args]: [get] (junto com [type] e [default]), [getlist], [to_dict]
Campos de um formulário POST
[request.form], um [MultiDict], e um [request.args]
Corpo JSON
[request.get_json()]
Cabeçalhos
[request.headers], e objetos já analisados, como [request.accept_languages]
Conversão e validação
um modelo [Pydantic]: [model_validate], [ValidationError], [e.errors()]
Erros comuns
[@app.errorhandler] (aplicação inteira) ou [@blueprint.errorhandler] (um blueprint)
Parâmetro calculado
Um decorador que adiciona um parâmetro nomeado à action

Os formulários HTML, por outro lado, exigem mais do que simples validação: eles precisam ser exibidos, reexibidos com os dados digitados pelo usuário e os eventuais erros, e protegidos contra requisições forjadas. Esse será o papel do [WTForms], abordado no próximo capítulo, depois que as views forem apresentadas.