Skip to content

Flask Folha de referência

Framework web Python leve (microframework).

01

Primeiros passos

Primeira aplicação

Flask é um microframework — fornece o essencial e deixa você adicionar o que precisar. debug=True habilita auto-reload e páginas de erro detalhadas.

flask
# install Flask
pip install flask

# app.py
from flask import Flask, render_template

app = Flask(__name__)

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

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

Rodando o servidor de desenvolvimento

Nunca use o servidor embutido em produção. FLASK_APP aponta para o módulo que contém a instância da app. Use --host=0.0.0.0 para torná-lo acessível na rede.

flask
# Set the entry point and enable debug mode
export FLASK_APP=app.py
export FLASK_ENV=development
flask run

# Override host and port
flask run --host=0.0.0.0 --port=5000

# Or run the module directly
python app.py

Ambiente virtual

Um ambiente virtual isola as dependências do projeto do Python do sistema. requirements.txt registra as versões exatas para que outras pessoas reproduzam o ambiente com pip install -r requirements.txt.

flask
# Create an isolated environment
python -m venv venv

# Activate (Linux/macOS)
source venv/bin/activate

# Activate (Windows PowerShell)
venv\Scripts\Activate.ps1

# Install dependencies
pip install flask
pip freeze > requirements.txt

Estrutura do projeto

O Flask não impõe um layout, mas separar arquivos estáticos, templates e configuração é a convenção. A pasta instance/ guarda segredos específicos de deploy que não devem ir ao controle de versão.

flask
myapp/
  app.py            # application factory or instance
  config.py         # configuration classes
  requirements.txt  # pinned dependencies
  instance/
    config.py       # secret instance config (not in VCS)
  static/           # CSS, JS, images
    css/style.css
  templates/        # Jinja2 templates
    base.html
    index.html
  models.py         # database models
  views.py          # route handlers

Padrão application factory

O padrão factory adia a criação da app até uma função ser chamada, o que é essencial para múltiplas instâncias, testes e extensões. A opção --app do Flask aceita um callable que retorna uma app.

flask
from flask import Flask

def create_app(config_name="default"):
    app = Flask(__name__)
    app.config.from_object(f"config.{config_name.title()}Config")

    from .views import bp as views_bp
    app.register_blueprint(views_bp)

    @app.route("/health")
    def health():
        return {"status": "ok"}

    return app

# Run with: flask --app myapp create_app run
# or export FLASK_APP=myapp:create_app

Anatomia da aplicação mínima

Passar __name__ diz ao Flask onde encontrar arquivos estáticos e templates. Você pode sobrescrever as localizações das pastas com argumentos do construtor, se seu layout diferir dos padrões.

flask
from flask import Flask

app = Flask(
    __name__,
    static_folder="static",
    template_folder="templates",
    static_url_path="/static",
)

# __name__ lets Flask locate resources relative to the module.
# Route decorators map URL patterns to view functions.
@app.route("/")
def index():
    return "Hello, Flask!"
02

Rotas

Regras com variáveis

Seções marcadas com <converter:varname> capturam segmentos da URL. Conversores embutidos: string (padrão), int, float, path (aceita barras), uuid. O valor é passado como argumento da função.

flask
from flask import Flask

app = Flask(__name__)

@app.route("/user/<username>")
def show_user(username):
    return f"User: {username}"

@app.route("/post/<int:post_id>")
def show_post(post_id):
    return f"Post #{post_id}"

@app.route("/path/<path:subpath>")
def show_path(subpath):
    return f"Path: {subpath}"

Conversores de URL

Conversores validam e fazem cast das variáveis da URL. Registre uma subclasse de BaseConverter em app.url_map.converters para impor um padrão regex, como códigos de produto.

flask
@app.route("/item/<int:item_id>")
def item_int(item_id):
    return f"Integer ID: {item_id}"

@app.route("/weight/<float:kg>")
def weight(kg):
    return f"{kg} kg"

@app.route("/uid/<uuid:token>")
def by_token(token):
    return str(token)

# Custom converter
from werkzeug.routing import BaseConverter

class RegexConverter(BaseConverter):
    def __init__(self, url_map, *items):
        super().__init__(url_map)
        self.regex = items[0]

app.url_map.converters["re"] = RegexConverter

@app.route("/code/<re:[a-z]{3}-[0-9]{4}:code>")
def code(code):
    return code

URLs únicas e redirecionamento

A barra final importa. Uma rota terminando em '/' redireciona a forma sem barra; uma rota sem '/' retorna 404 para a forma com barra. Escolha uma convenção por rota e seja consistente.

flask
@app.route("/projects/")
def projects():
    return "Projects page"

# /projects/  -> 200 OK
# /projects   -> 301 redirect to /projects/

@app.route("/about")
def about():
    return "About page"

# /about    -> 200 OK
# /about/   -> 404 Not Found

Verbos HTTP

Use o argumento methods para aceitar múltiplos verbos, ou os atalhos @app.get / @app.post (Flask 2.0+) para rotas de função único. GET é o padrão.

flask
from flask import request, render_template

@app.route("/login", methods=["GET", "POST"])
def login():
    if request.method == "POST":
        return do_login()
    return render_template("login.html")

# Method-specific shortcuts
@app.get("/profile")
def profile_get():
    return render_template("profile.html")

@app.post("/profile")
def profile_post():
    return update_profile()

Construindo URLs com url_for

url_for gera URLs a partir do nome do endpoint (o nome da função de view, por padrão). Sobrevive a mudanças de URL e produz URLs absolutas quando _external=True é passado.

flask
from flask import Flask, url_for

app = Flask(__name__)

@app.route("/")
def index():
    # builds '/user/alice' instead of hardcoding
    return f'<a href="{url_for("show_user", username="alice")}">Alice</a>'

@app.route("/user/<username>")
def show_user(username):
    return f"Hello {username}"

with app.test_request_context():
    print(url_for("show_user", username="bob"))  # /user/bob

Múltiplas regras para uma view

add_url_rule registra uma URL sem decorator. Ao dar a cada regra um endpoint distinto, mas a mesma função de view com defaults, um único handler serve múltiplas formas de URL.

flask
from flask import Flask

app = Flask(__name__)

def show(id=None, name=None):
    if id is not None:
        return f"By id: {id}"
    return f"By name: {name}"

app.add_url_rule("/by-id/<int:id>", "by_id", show, defaults={"name": None})
app.add_url_rule("/by-name/<name>", "by_name", show, defaults={"id": None})

# Two endpoints share one function with different defaults.
03

Requisição e resposta

O objeto Request

request é um proxy thread-local vinculado ao contexto da requisição atual. Expõe a URL, função, headers, corpo e informações do cliente sem ser passado explicitamente.

flask
from flask import Flask, request

app = Flask(__name__)

@app.route("/info")
def info():
    return {
        "url": request.url,
        "method": request.method,
        "remote_addr": request.remote_addr,
        "user_agent": str(request.user_agent),
        "headers": dict(request.headers),
    }

Construindo uma resposta

make_response dá controle total sobre status, headers e corpo. Para casos simples, retorne uma string, um dict (JSON) ou uma tupla de (body, status, headers).

flask
from flask import Flask, make_response

app = Flask(__name__)

@app.route("/")
def index():
    resp = make_response("Hello, World!")
    resp.status_code = 201
    resp.headers["X-Custom"] = "yes"
    resp.set_cookie("visited", "1")
    return resp

# Returning a tuple: (body, status, headers)
@app.route("/quick")
def quick():
    return "OK", 202, {"X-Quick": "1"}

Objetos Response

Use Response quando precisar de um mimetype personalizado (por exemplo, XML, CSV) ou headers. Definir Content-Disposition como attachment força um download no navegador.

flask
from flask import Response

@app.route("/xml")
def xml():
    return Response("<msg>hi</msg>", mimetype="application/xml")

@app.route("/text")
def text():
    return Response("plain text", mimetype="text/plain")

@app.route("/csv")
def csv():
    body = "a,b,c\n1,2,3\n"
    headers = {"Content-Disposition": "attachment; filename=data.csv"}
    return Response(body, mimetype="text/csv", headers=headers)

Status e headers personalizados

Retorne uma tupla (body, status, headers) para respostas personalizadas concisas. Use 204 No Content para respostas de sucesso sem corpo, e códigos de status HTTP padrão para semântica.

flask
@app.route("/created")
def created():
    return "done", 201, {"Location": "/resource/1"}

@app.route("/no-content")
def no_content():
    return "", 204

@app.route("/teapot")
def teapot():
    return "I'm a teapot", 418

Respostas em streaming

Um valor de retorno generator faz streaming dos dados para o cliente. Útil para arquivos grandes (evita carregar o arquivo inteiro na memória) e Server-Sent Events. Defina um mimetype apropriado.

flask
from flask import Response

def generate():
    yield "data: first\n\n"
    yield "data: second\n\n"
    yield "data: third\n\n"

@app.route("/stream")
def stream():
    return Response(generate(), mimetype="text/event-stream")

@app.route("/big-file")
def big_file():
    def chunks():
        with open("large.log", "rb") as f:
            while chunk := f.read(8192):
                yield chunk
    return Response(chunks(), mimetype="application/octet-stream")

Cookies na resposta

set_cookie escreve um header Set-Cookie; delete_cookie o expira. Sempre defina httponly e samesite por segurança. Cookies são parte da resposta, não do corpo da requisição.

flask
from flask import make_response

@app.route("/set-theme")
def set_theme():
    resp = make_response("theme set")
    resp.set_cookie("theme", "dark", max_age=30*86400, httponly=True, samesite="Lax")
    return resp

@app.route("/clear-theme")
def clear_theme():
    resp = make_response("cleared")
    resp.delete_cookie("theme")
    return resp
04

Objeto Request (form/args/files)

Parâmetros de query (args)

request.args é um MultiDict dos valores da query string. Use get com um padrão e conversão de tipo, e getlist para chaves repetidas. Nunca indexe diretamente — chaves ausentes levantam 400.

flask
from flask import request

@app.route("/search")
def search():
    q = request.args.get("q", "")           # default ""
    page = request.args.get("page", 1, type=int)
    tags = request.args.getlist("tag")       # /search?tag=a&tag=b -> ["a","b"]
    return {"q": q, "page": page, "tags": tags}

Dados de formulário

request.form guarda dados application/x-www-form-urlencoded ou multipart enviados via POST. Use .get() para evitar KeyError em campos opcionais. Requisições GET têm um form vazio.

flask
from flask import request, render_template

@app.route("/login", methods=["GET", "POST"])
def login():
    if request.method == "POST":
        username = request.form.get("username")
        password = request.form.get("password")
        if not username or not password:
            return "Missing fields", 400
        return f"Welcome {username}"
    return render_template("login.html")

Uploads de arquivos

request.files é um MultiDict de objetos FileStorage. Sempre passe nomes de arquivo fornecidos por usuários por secure_filename para remover separadores de caminho e caracteres perigosos antes de salvar.

flask
from flask import request
from werkzeug.utils import secure_filename
import os

@app.route("/upload", methods=["POST"])
def upload():
    file = request.files.get("file")
    if not file or file.filename == "":
        return "No file", 400
    name = secure_filename(file.filename)
    file.save(os.path.join("uploads", name))
    return "saved"

Corpo JSON

get_json() interpreta o corpo como JSON apenas quando o Content-Type é application/json. force=True ignora o header (use com cautela). silent=True suprime erros de parse.

flask
from flask import request

@app.route("/api/echo", methods=["POST"])
def echo():
    data = request.get_json()        # returns None if not JSON
    if data is None:
        return "Expected JSON", 415
    return {"you_sent": data}

# Force parsing even without the right header (risky)
@app.route("/api/force")
def force():
    data = request.get_json(force=True)
    return data

Headers e cookies

request.headers é um objeto parecido com dict do tipo EnvironHeaders; request.cookies guarda os cookies recebidos enviados pelo cliente. Ambos são somente leitura — defina headers/cookies na resposta.

flask
from flask import request

@app.route("/inspect")
def inspect():
    auth = request.headers.get("Authorization")
    accept = request.headers.get("Accept")
    session_id = request.cookies.get("session_id")
    return {
        "auth": auth,
        "accept": accept,
        "session_id": session_id,
    }

Funções e propriedades do request

request expõe metadados sobre a conexão e o corpo. is_json verifica o Content-Type, is_secure verifica HTTPS, e query_string são os bytes brutos após '?'.

flask
from flask import request

@app.route("/state")
def state():
    return {
        "method": request.method,
        "is_xhr": request.is_json,
        "content_type": request.content_type,
        "content_length": request.content_length,
        "is_secure": request.is_secure,
        "scheme": request.scheme,
        "host": request.host,
        "path": request.path,
        "query_string": request.query_string.decode(),
    }
05

Templates Jinja2

Renderizando templates

render_template carrega um arquivo Jinja2 da pasta templates/ e injeta argumentos nomeados como variáveis. A sintaxe {{ }} exibe uma expressão; o Flask escapa HTML automaticamente por segurança.

flask
from flask import render_template

@app.route("/<name>")
def hello(name):
    return render_template("hello.html", name=name, title="Welcome")

# templates/hello.html
# <!DOCTYPE html>
# <html>
#   <head><title>{{ title }}</title></head>
#   <body>
#     <h1>Hello {{ name }}!</h1>
#   </body>
# </html>

Variáveis de template

Jinja2 suporta acesso por atributo (user.name) e por item (user['age']). O filtro safe marca uma string como confiável para não ser escapada — use apenas em conteúdo que você controla totalmente.

flask
# View
@app.route("/")
def index():
    return render_template(
        "index.html",
        user={"name": "Alice", "age": 30},
        items=["apple", "banana", "cherry"],
        html_content="<b>safe?</b>",
    )

# Template
# <p>Name: {{ user.name }}</p>
# <p>Age: {{ user["age"] }}</p>
# <p>First: {{ items[0] }}</p>
# <p>Raw HTML: {{ html_content | safe }}</p>

Estruturas de controle

Jinja2 suporta {% if %}, {% for %} e {% block %}. Dentro de loops, a variável especial loop dá index, index0, first, last, length e revindex. O for-else roda quando o iterável está vazio.

flask
{# if / elif / else #}
{% if user.age >= 18 %}
  Adult
{% elif user.age >= 13 %}
  Teen
{% else %}
  Child
{% endif %}

{# for loop #}
<ul>
{% for item in items %}
  <li>{{ loop.index }}: {{ item }}</li>
{% else %}
  <li>No items</li>
{% endfor %}
</ul>

Herança de template

extends puxa um template base e templates filhos sobrescrevem blocos nomeados. Isso mantém o layout compartilhado (navegação, scripts) num único lugar. super() renderiza o conteúdo do bloco pai.

flask
{# templates/base.html #}
<!DOCTYPE html>
<html>
<head>
  <title>{% block title %}Default{% endblock %}</title>
</head>
<body>
  {% block content %}{% endblock %}
</body>
</html>

{# templates/child.html #}
{% extends "base.html" %}

{% block title %}Home{% endblock %}

{% block content %}
  <h1>Welcome home</h1>
{% endblock %}

Filtros

Filtros transformam valores via a sintaxe de pipe (|) e aceitam argumentos. Registre filtros personalizados em app.jinja_env.filters para reutilizar lógica entre templates.

flask
{{ name | capitalize }}      {# alice -> Alice #}
{{ price | round(2) }}       {# 3.14159 -> 3.14 #}
{{ items | length }}         {# count #}
{{ text | truncate(20) }}    {# shorten #}
{{ tags | join(", ") }}      {# ["a","b"] -> "a, b" #}
{{ value | default("n/a") }} {# fallback #}
{{ html | striptags }}       {# remove HTML tags #}

{# Custom filter #}
def reverse_filter(s):
    return s[::-1]

app.jinja_env.filters["reverse"] = reverse_filter
{{ "hello" | reverse }}  {# olleh #}

Macros

Macros são trechos de template reutilizáveis, como funções. Importe-os com {% from %} ou {% import %}. Mantêm HTML repetitivo (campos de formulário, cards) DRY.

flask
{# templates/macros.html #}
{% macro input(name, value="", type="text") %}
  <input type="{{ type }}" name="{{ name }}" value="{{ value }}">
{% endmacro %}

{% macro label(text, for_id) %}
  <label for="{{ for_id }}">{{ text }}</label>
{% endmacro %}

{# In another template #}
{% from "macros.html" import input, label %}

<form>
  {{ label("Username", "u") }}
  {{ input("username") }}
  {{ label("Password", "p") }}
  {{ input("password", type="password") }}
</form>
06

Arquivos estáticos

Servindo arquivos estáticos

O Flask registra automaticamente uma rota /static/<path:filename> para a pasta static. Sempre construa URLs com url_for para que os caminhos continuem corretos mesmo se static_url_path mudar.

flask
# Files in the static/ folder are served at /static/<filename>
# static/css/style.css -> http://localhost:5000/static/css/style.css

# Reference them in templates
# <link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}">
# <script src="{{ url_for('static', filename='js/app.js') }}"></script>
# <img src="{{ url_for('static', filename='img/logo.png') }}">

url_for para assets estáticos

url_for('static', filename=...) resolve um caminho de arquivo estático. Passe _external=True para uma URL absoluta (útil em e-mails ou feeds) e argumentos de query para cache busting.

flask
from flask import Flask, url_for

app = Flask(__name__)

with app.test_request_context():
    print(url_for("static", filename="css/style.css"))
    # /static/css/style.css
    print(url_for("static", filename="js/app.js", _external=True))
    # http://localhost/static/js/app.js

Pasta estática personalizada

Sobrescreva static_folder (localização no disco) e static_url_path (prefixo de URL) para casar com as convenções do seu projeto. O padrão é pasta='static' mapeada para /static.

flask
from flask import Flask

app = Flask(
    __name__,
    static_folder="assets",       # folder on disk
    static_url_path="/public",    # URL prefix
)

# Now files in assets/ are served at /public/<filename>
# Template: url_for('static', filename='css/style.css') -> /public/css/style.css

Favicon

Navegadores pedem /favicon.ico na raiz por padrão. Adicione uma rota explícita ou vincule o ícone via uma tag <link>. send_from_directory serve um arquivo de um diretório com segurança.

flask
from flask import send_from_directory
import os

@app.route("/favicon.ico")
def favicon():
    return send_from_directory(
        os.path.join(app.root_path, "static"),
        "favicon.ico",
        mimetype="image/vnd.microsoft.icon",
    )

# Or place favicon.ico in static/ and link it:
# <link rel="icon" href="{{ url_for('static', filename='favicon.ico') }}">

Cache busting

Navegadores cacheiam assets estáticos por URL. Acrescentar um hash de versão força os clientes a buscar novas cópias depois que um arquivo muda. Uma ferramenta de build (Vite, Flask-Assets) automatiza isso em projetos maiores.

flask
# Append a version query param to force reloads
# <link href="{{ url_for('static', filename='css/app.css', v='1.2') }}">

# Or compute a hash at startup
import hashlib, os

def asset_version(filename):
    path = os.path.join(app.static_folder, filename)
    with open(path, "rb") as f:
        return hashlib.md5(f.read()).hexdigest()[:8]

@app.template_filter("bust")
def bust(filename):
    v = asset_version(filename)
    return url_for("static", filename=filename) + f"?v={v}"

# Template: <link href="{{ 'css/app.css' | bust }}">
07

Blueprints

Criando um Blueprint

Um Blueprint agrupa rotas, templates e arquivos estáticos relacionados num módulo. O primeiro argumento é o nome do blueprint; url_prefix antecede um caminho a cada rota que ele define.

flask
# auth.py
from flask import Blueprint, render_template

bp = Blueprint("auth", __name__, url_prefix="/auth")

@bp.route("/login")
def login():
    return render_template("auth/login.html")

@bp.route("/register")
def register():
    return render_template("auth/register.html")

Registrando blueprints

register_blueprint anexa um blueprint à app. Você pode sobrescrever url_prefix no momento do registro, então o mesmo blueprint pode ser montado sob caminhos diferentes em apps diferentes.

flask
from flask import Flask
from auth import bp as auth_bp
from blog import bp as blog_bp

app = Flask(__name__)
app.register_blueprint(auth_bp)           # /auth/*
app.register_blueprint(blog_bp, url_prefix="/blog")  # /blog/*

# Register later, or with a name override
app.register_blueprint(auth_bp, name="alt_auth")

Blueprint com prefixo de URL

Defina url_prefix no Blueprint ou no registro. Versionar o caminho da API (/api/v1) permite introduzir /api/v2 mais tarde sem quebrar clientes existentes.

flask
# api/__init__.py
from flask import Blueprint

bp = Blueprint("api", __name__, url_prefix="/api/v1")

@bp.route("/users")
def list_users():
    return {"users": []}

@bp.route("/users/<int:uid>")
def get_user(uid):
    return {"id": uid}

# All routes become /api/v1/users...

Recursos do blueprint

Um blueprint pode carregar pastas próprias de templates e static. A resolução de templates verifica o blueprint primeiro, depois a app, então arquivos locais do blueprint sobrescrevem os globais da app com o mesmo nome.

flask
bp = Blueprint(
    "admin",
    __name__,
    url_prefix="/admin",
    template_folder="templates",   # blueprint-local templates
    static_folder="static",        # blueprint-local static
)

# Templates: blueprint lookups first, then app templates
# render_template("admin/dashboard.html")
# Static: url_for('admin.static', filename='css/admin.css')

Error handlers do blueprint

Error handlers no nível do blueprint só capturam erros lançados pelas rotas daquele blueprint, dando páginas de erro específicas por seção. Handlers no nível da app tratam o que não for capturado.

flask
from flask import Blueprint, render_template

bp = Blueprint("blog", __name__)

@bp.errorhandler(404)
def blog_not_found(e):
    return render_template("blog/404.html"), 404

@bp.errorhandler(403)
def blog_forbidden(e):
    return render_template("blog/403.html"), 403

Blueprints aninhados

Flask 2.0+ suporta aninhar blueprints. Registre um blueprint filho num pai com register_blueprint; os url_prefix deles se concatenam, permitindo compor apps grandes a partir de módulos pequenos.

flask
from flask import Blueprint

parent = Blueprint("parent", __name__, url_prefix="/parent")
child = Blueprint("child", __name__, url_prefix="/child")

@child.route("/info")
def info():
    return "nested info"

parent.register_blueprint(child)
app.register_blueprint(parent)

# Final URL: /parent/child/info
08

Contexto (g / session)

Contexto de aplicação

O contexto de aplicação torna current_app e g disponíveis fora de uma requisição (por exemplo, em comandos de CLI ou tarefas em segundo plano). Empurre-o com app.app_context() quando trabalhar fora de uma requisição.

flask
from flask import current_app, g

@app.route("/")
def index():
    app_name = current_app.name
    config_value = current_app.config["SECRET_KEY"]
    return f"Running {app_name}"

# Push a context manually (scripts, shell)
with app.app_context():
    print(current_app.config["DEBUG"])

O objeto g

g é um namespace por requisição para guardar recursos compartilhados, como conexões de banco de dados. É reiniciado a cada requisição e limpo num handler teardown_appcontext.

flask
from flask import g
import sqlite3

def get_db():
    if "db" not in g:
        g.db = sqlite3.connect("app.db")
        g.db.row_factory = sqlite3.Row
    return g.db

@app.teardown_appcontext
def close_db(exc):
    db = g.pop("db", None)
    if db is not None:
        db.close()

Contexto de requisição

O contexto de requisição vincula request, session e url_for a uma thread. Use test_request_context em testes e scripts para simular uma requisição sem um servidor HTTP.

flask
from flask import request

# Flask pushes a request context automatically during dispatch.
# Push one manually to use request/url_for outside a view:
with app.test_request_context("/?q=flask"):
    print(request.args.get("q"))   # flask
    print(request.path)            # /

# request_context for real WSGI environments
from werkzeug.test import EnvironBuilder
env = EnvironBuilder("/post/1").get_environ()
with app.request_context(env):
    print(request.path)

Proxies current_app e request

current_app, request, session e g são objetos LocalProxy que encaminham o acesso a atributos para o contexto ativo. Nunca os capture numa variável global — sempre acesse-os no momento da chamada.

flask
from flask import current_app, request, session, g

# These are LocalProxy objects, not the real thing.
# They resolve to the current context's object at access time.

@app.route("/")
def index():
    current_app.logger.info("hit /")
    g.request_start = time.time()
    session["visited"] = True
    return current_app.config["APP_NAME"]

# Avoid storing proxies in module-level variables;
# always access them inside a context.

Objeto session

session é um dict baseado em cookie assinado. Defina app.secret_key para que o Flask possa assiná-lo. Os valores ficam no cliente e são legíveis pelo usuário (mas não alteráveis), então nunca guarde segredos ali.

flask
from flask import session

@app.route("/login")
def login():
    session["user_id"] = 42
    session["role"] = "admin"
    return "logged in"

@app.route("/who")
def who():
    uid = session.get("user_id")
    return f"user {uid}" if uid else "anonymous"

@app.route("/logout")
def logout():
    session.clear()
    return "logged out"

Ciclo de vida do contexto

Entender o ciclo de vida é a chave para usar os hooks corretamente. Handlers teardown_* sempre rodam, mesmo em erros, então são o lugar certo para fechar conexões de banco e liberar recursos.

flask
# Per-request lifecycle:
# 1. Application context pushed
# 2. Request context pushed
# 3. before_request handlers run
# 4. View function runs
# 5. after_request handlers run (can modify response)
# 6. Request context popped
# 7. teardown_request handlers run
# 8. teardown_appcontext handlers run (close resources)

@app.before_request
def before():
    g.start = time.time()

@app.teardown_request
def teardown(exc):
    elapsed = time.time() - getattr(g, "start", time.time())
    app.logger.debug("request took %.3fs", elapsed)
09

Integração SQLAlchemy

Configurando Flask-SQLAlchemy

Flask-SQLAlchemy embrulha o SQLAlchemy e o integra ao contexto da app do Flask. Defina SQLALCHEMY_DATABASE_URI como a string de conexão e desabilite o rastreamento de modificações para economizar memória.

flask
pip install flask-sqlalchemy

from flask import Flask
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False

db = SQLAlchemy(app)

# In a factory, init with db.init_app(app)

Definindo models

Models herdam de db.Model; colunas são instâncias de db.Column. Tipos comuns incluem Integer, String, Text, DateTime, Boolean. Use unique=True e nullable=False para restrições.

flask
from datetime import datetime

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True)
    created_at = db.Column(db.DateTime, default=datetime.utcnow)

    def __repr__(self):
        return f"<User {self.username}>"

class Post(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(200), nullable=False)
    body = db.Column(db.Text)
    user_id = db.Column(db.Integer, db.ForeignKey("user.id"))

Consultando dados

Model.query é uma interface de consulta conveniente. filter_by(chave=valor) é simples; filter(expressão) suporta operadores como >, <, like, in_. paginate() retorna itens mais metadados de página.

flask
# Fetch all
users = User.query.all()

# Primary key lookup
user = User.query.get(1)

# Filter
admins = User.query.filter_by(role="admin").all()
active = User.query.filter(User.email.isnot(None)).first()

# Order, limit, paginate
recent = User.query.order_by(User.created_at.desc()).limit(10).all()
page = User.query.paginate(page=2, per_page=20)

# Count
total = User.query.count()

Adicionando e atualizando

Toda mudança acontece numa transação via db.session. add prepara um novo objeto; commit grava. Em erro, faça rollback com db.session.rollback() para manter a sessão utilizável.

flask
# Create
u = User(username="alice", email="[email protected]")
db.session.add(u)
db.session.commit()

# Update
u.email = "[email protected]"
db.session.commit()

# Delete
db.session.delete(u)
db.session.commit()

# Bulk insert
db.session.add_all([User(username="b"), User(username="c")])
db.session.commit()

Relacionamentos

db.relationship define o vínculo entre models. backref adiciona um atributo reverso. lazy='dynamic' retorna um objeto de consulta em vez de uma lista, útil para coleções grandes que você quer filtrar mais.

flask
class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80))
    posts = db.relationship("Post", backref="author", lazy="dynamic")

class Post(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(200))
    user_id = db.Column(db.Integer, db.ForeignKey("user.id"))

# Usage
user = User.query.get(1)
user.posts.all()              # list of posts
post = Post.query.get(5)
post.author.username          # backref to user

Migrações com Flask-Migrate

Flask-Migrate embrulha o Alembic para versionar seu schema. Rode migrate para gerar um script automaticamente a partir de mudanças nos models, depois upgrade para aplicá-lo. Sempre revise scripts gerados automaticamente antes de commitar.

flask
pip install flask-migrate

from flask_migrate import Migrate

migrate = Migrate(app, db)

# CLI commands
# flask db init          # create migrations folder
# flask db migrate -m "create users"
# flask db upgrade       # apply migrations
# flask db downgrade     # revert one step
# flask db current       # show current revision
10

WTForms (Flask-WTF)

Instalando Flask-WTF

Flask-WTF integra WTForms ao Flask e adiciona proteção CSRF automaticamente. Um SECRET_KEY é necessário para que o token CSRF possa ser assinado. Desabilite CSRF apenas em endpoints de API públicos.

flask
pip install flask-wtf

from flask import Flask
from flask_wtf import FlaskForm

app = Flask(__name__)
app.config["SECRET_KEY"] = "change-me-in-production"
app.config["WTF_CSRF_ENABLED"] = True

# CSRF protection is enabled by default
# when SECRET_KEY is set.

Definindo um formulário

Formulários herdam de FlaskForm. Cada campo recebe um label e uma lista de validators que rodam em validate(). Validadores impõem entrada obrigatória, comprimento, formato de e-mail e mais.

flask
from flask_wtf import FlaskForm
from wtforms import StringField, PasswordField, SubmitField
from wtforms.validators import DataRequired, Email, Length

class LoginForm(FlaskForm):
    email = StringField("Email", validators=[DataRequired(), Email()])
    password = PasswordField("Password", validators=[DataRequired(), Length(min=8)])
    submit = SubmitField("Log In")

class RegisterForm(FlaskForm):
    username = StringField("Username", validators=[DataRequired(), Length(min=3, max=20)])
    email = StringField("Email", validators=[DataRequired(), Email()])
    submit = SubmitField("Sign Up")

Renderizando o form no template

form.hidden_tag() renderiza o token CSRF e quaisquer campos ocultos. Cada campo pode renderizar seu label, input e erros separadamente. Para saída rápida, {{ form.field() }} renderiza o input HTML.

flask
{# templates/login.html #}
<form method="POST">
  {{ form.hidden_tag() }}  {# CSRF token #}
  <p>
    {{ form.email.label }}
    {{ form.email() }}
    {% for err in form.email.errors %}<span class="err">{{ err }}</span>{% endfor %}
  </p>
  <p>
    {{ form.password.label }}
    {{ form.password() }}
  </p>
  {{ form.submit() }}
</form>

Validando o formulário

validate_on_submit() retorna True apenas numa requisição POST em que os validadores passam. Em sucesso, leia os valores dos campos de form.field.data. Em falha, re-renderize o template para mostrar os erros.

flask
from flask import render_template, redirect, url_for, flash

@app.route("/login", methods=["GET", "POST"])
def login():
    form = LoginForm()
    if form.validate_on_submit():   # POST + valid
        email = form.email.data
        flash(f"Logged in as {email}")
        return redirect(url_for("dashboard"))
    return render_template("login.html", form=form)

# validate_on_submit() returns False on GET or invalid POST

Validadores embutidos

Validadores são callables que lançam ValidationError em falha. EqualTo é comum para confirmação de senha. Encadeie-os numa lista; rodam em ordem até um falhar.

flask
from wtforms.validators import (
    DataRequired,   # field not empty
    Email,          # valid email format
    Length,         # Length(min=3, max=20)
    NumberRange,    # NumberRange(min=0, max=100)
    URL,            # valid URL
    Regexp,         # Regexp(r"^\\w+$")
    EqualTo,        # EqualTo("password") - match another field
    Optional,       # skip validation if empty
    InputRequired,  # field submitted (even if empty string)
    NoneOf,         # NoneOf(["admin", "root"])
)

password = PasswordField("Password", validators=[DataRequired(), Length(min=8)])
confirm = PasswordField("Confirm", validators=[EqualTo("password")])

FileField

Use FileField de flask_wtf.file com FileRequired e FileAllowed para validar uploads. O arquivo enviado é um objeto FileStorage disponível em form.field.data. A tag do form deve incluir enctype=multipart/form-data.

flask
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileRequired, FileAllowed

class UploadForm(FlaskForm):
    image = FileField("Image", validators=[
        FileRequired(),
        FileAllowed(["jpg", "png", "gif"], "Images only!"),
    ])
    submit = SubmitField("Upload")

@app.route("/upload", methods=["GET", "POST"])
def upload():
    form = UploadForm()
    if form.validate_on_submit():
        f = form.image.data
        f.save("uploads/" + f.filename)
        return "uploaded"
    return render_template("upload.html", form=form)
11

Autenticação com Flask-Login

Configurando Flask-Login

Flask-Login gerencia sessões de usuário: login, logout e lembrança de usuários. Defina login_view para que usuários não autenticados sejam redirecionados para lá. login_message aparece naquele redirecionamento.

flask
pip install flask-login

from flask import Flask
from flask_login import LoginManager

app = Flask(__name__)
app.config["SECRET_KEY"] = "secret"

login_manager = LoginManager()
login_manager.init_app(app)
login_manager.login_view = "login"
login_manager.login_message = "Please log in to access this page."

Model de usuário

O model de usuário deve misturar UserMixin (que fornece is_authenticated, is_active, get_id etc.) e implementar um callback user_loader que retorna um usuário pelo ID. Nunca armazene senhas em texto puro — faça hash.

flask
from flask_login import UserMixin
from werkzeug.security import generate_password_hash, check_password_hash

class User(UserMixin, db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True)
    password_hash = db.Column(db.String(256))

    def set_password(self, pw):
        self.password_hash = generate_password_hash(pw)

    def check_password(self, pw):
        return check_password_hash(self.password_hash, pw)

@login_manager.user_loader
def load_user(user_id):
    return User.query.get(int(user_id))

View de login

login_user carrega o usuário na sessão. Passe remember=True para cookies persistentes. Sempre verifique a senha com uma checagem de hash antes de logar, e mostre um erro genérico em falha.

flask
from flask import render_template, redirect, url_for, flash
from flask_login import login_user
from forms import LoginForm

@app.route("/login", methods=["GET", "POST"])
def login():
    form = LoginForm()
    if form.validate_on_submit():
        user = User.query.filter_by(username=form.username.data).first()
        if user and user.check_password(form.password.data):
            login_user(user, remember=form.remember.data)
            return redirect(url_for("dashboard"))
        flash("Invalid username or password")
    return render_template("login.html", form=form)

Protegendo rotas

O decorator @login_required rejeita usuários anônimos e os redireciona para login_view. current_user é um proxy para o usuário logado (ou um AnonymousUserMixin) disponível em views e templates.

flask
from flask_login import login_required, current_user

@app.route("/dashboard")
@login_required
def dashboard():
    return f"Welcome {current_user.username}"

@app.route("/settings")
@login_required
def settings():
    return render_template("settings.html", user=current_user)

# Unauthenticated users redirect to login_view
# @login_required must be the innermost decorator

Logout

logout_user limpa o usuário da sessão. Proteja a rota com @login_required para que só usuários logados possam deslogar. Redirecione para uma página pública (index ou login) depois.

flask
from flask_login import logout_user, login_required
from flask import redirect, url_for, flash

@app.route("/logout")
@login_required
def logout():
    logout_user()
    flash("You have been logged out.")
    return redirect(url_for("index"))

# logout_user() clears the session and cookies

Remember me e current_user

remember=True define um cookie separado para que os usuários continuem logados após fechar o navegador. current_user funciona em views e templates, facilitando renderizar a UI condicionalmente conforme o status de autenticação.

flask
from flask_login import current_user

# In the login view
login_user(user, remember=True)

# remember=True stores a separate long-lived cookie
# so the session survives a browser restart.

# current_user is available everywhere a context exists
@app.route("/")
def index():
    if current_user.is_authenticated:
        return f"Hi {current_user.username}"
    return "Welcome, guest"

# In templates:
# {% if current_user.is_authenticated %}
#   <a href="{{ url_for('logout') }}">Logout</a>
# {% endif %}
12

Tratamento de erros

abort()

abort() interrompe imediatamente a view e retorna um erro HTTP. Passe um código de status e uma mensagem opcional. Ele lança uma HTTPException que o Flask converte na resposta de erro correspondente.

flask
from flask import abort

@app.route("/user/<int:id>")
def get_user(id):
    user = find_user(id)
    if user is None:
        abort(404)            # Not Found
    if not can_access(user):
        abort(403, "Forbidden")   # Forbidden with description
    return render_template("user.html", user=user)

# Common codes: 400 Bad Request, 401 Unauthorized,
# 403 Forbidden, 404 Not Found, 418 Teapot, 500 Server Error

Páginas de erro personalizadas

Registre handlers com @app.errorhandler(code). Retorne uma tupla de (template, status_code). Esses handlers capturam tanto chamadas abort() quanto exceções que mapeiam para aquele status.

flask
from flask import render_template

@app.errorhandler(404)
def not_found(e):
    return render_template("errors/404.html"), 404

@app.errorhandler(403)
def forbidden(e):
    return render_template("errors/403.html"), 403

@app.errorhandler(500)
def server_error(e):
    return render_template("errors/500.html"), 500

Error handlers para exceções

Você pode registrar handlers para classes de exceção personalizadas, não apenas códigos HTTP. Lançar a exceção em qualquer lugar de uma view dispara o handler, centralizando as respostas de erro para erros de domínio.

flask
from werkzeug.exceptions import HTTPException

class InvalidUsage(Exception):
    status_code = 400
    def __init__(self, message, status_code=None, payload=None):
        super().__init__()
        self.message = message
        if status_code is not None:
            self.status_code = status_code
        self.payload = payload

@app.errorhandler(InvalidUsage)
def handle_invalid_usage(e):
    return {"error": e.message}, e.status_code

@app.route("/raise")
def raise_err():
    raise InvalidUsage("Bad input", status_code=422)

Handler catch-all de 404

Um handler genérico de Exception é o último recurso para 500s. Relance HTTPException para que as páginas embutidas continuem funcionando, e registre o traceback. Cuidado para não vazar stack traces aos usuários em produção.

flask
@app.errorhandler(404)
def page_not_found(e):
    # Log the missing URL for analysis
    app.logger.info("404: %s", request.path)
    return render_template("errors/404.html", path=request.path), 404

@app.errorhandler(Exception)
def unhandled(e):
    # Catch any uncaught exception -> 500
    if isinstance(e, HTTPException):
        return e
    app.logger.exception("Unhandled error")
    return render_template("errors/500.html"), 500

Registrando erros em log

Registre erros em log com exc_info=True para capturar o traceback completo. Um RotatingFileHandler impede que os arquivos de log cresçam sem limite. Em produção, encaminhe os logs para um serviço centralizado.

flask
import logging
from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler("app.log", maxBytes=10*1024*1024, backupCount=5)
handler.setLevel(logging.ERROR)
handler.setFormatter(logging.Formatter(
    "%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]"
))
app.logger.addHandler(handler)

@app.errorhandler(500)
def server_error(e):
    app.logger.error("Server error: %s", e, exc_info=True)
    return "Internal error", 500

Tratamento de exceções HTTP

HTTPException é a classe base dos erros HTTP do Werkzeug. Um handler para HTTPException captura cada um deles de uma vez, enquanto um handler específico de subclasse (NotFound) tem precedência para aquele código.

flask
from werkzeug.exceptions import HTTPException, NotFound, BadRequest

@app.errorhandler(HTTPException)
def handle_http_exception(e):
    # All HTTP exceptions in one handler
    return render_template(
        "errors/generic.html",
        code=e.code,
        name=e.name,
        description=e.description,
    ), e.code

# Specific subclasses still work
@app.errorhandler(NotFound)
def specific_404(e):
    return "custom 404", 404
13

JSON e API

jsonify

jsonify converte dicts/lists Python numa resposta JSON com o Content-Type correto e escapamento seguro para ASCII. A partir do Flask 2.1+ você pode passar uma lista diretamente; versões antigas exigem um dict.

flask
from flask import jsonify

@app.route("/api/user")
def api_user():
    return jsonify(username="alice", age=30)

@app.route("/api/users")
def api_users():
    users = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
    return jsonify(users)

# jsonify sets Content-Type: application/json
# and dumps with proper escaping

Retornando JSON

Retornar um dict ou lista diretamente é a forma mais simples de enviar JSON. Para códigos de status ou headers personalizados, retorne uma tupla. Use Response + json.dumps só quando precisar de controle total da serialização.

flask
# Returning a dict/list is auto-converted to JSON (Flask 1.1+)
@app.route("/api/quick")
def quick():
    return {"status": "ok", "count": 42}

# With custom status and headers
@app.route("/api/created", methods=["POST"])
def created():
    return {"id": 99}, 201, {"Location": "/api/99"}

# A Response with JSON body
from flask import Response
import json

@app.route("/api/raw")
def raw():
    return Response(json.dumps({"k": "v"}), mimetype="application/json")

Recebendo JSON

get_json() interpreta o corpo como JSON quando o Content-Type é application/json. Sempre valide a estrutura interpretada antes de usar — nunca confie na entrada do cliente. Retorne 400/422 para payloads malformados.

flask
from flask import request, jsonify

@app.route("/api/echo", methods=["POST"])
def echo():
    data = request.get_json()
    if not data:
        return jsonify({"error": "Invalid JSON"}), 400
    return jsonify({"received": data})

# Validate the structure
@app.route("/api/signup", methods=["POST"])
def signup():
    data = request.get_json()
    if not data or "email" not in data:
        return jsonify({"error": "email required"}), 422
    return jsonify({"email": data["email"]}), 201

Blueprint de API

Agrupe rotas de API num blueprint com um url_prefix versionado (/api/v1). Isso separa a lógica da API das rotas de páginas e torna o versionamento explícito — migre para /api/v2 quando chegarem mudanças que quebram compatibilidade.

flask
from flask import Blueprint, jsonify, request

api = Blueprint("api", __name__, url_prefix="/api/v1")

@api.route("/health")
def health():
    return jsonify(status="ok")

@api.route("/items", methods=["GET", "POST"])
def items():
    if request.method == "POST":
        return jsonify(created=True), 201
    return jsonify(items=[])

# Register: app.register_blueprint(api)

CORS

flask-cors adiciona o header Access-Control-Allow-Origin para que os navegadores permitam requisições cross-origin. Restrinja as origens a domínios confiáveis em produção, em vez de usar o curinga '*'.

flask
pip install flask-cors

from flask import Flask
from flask_cors import CORS

app = Flask(__name__)

# Enable for all routes
CORS(app)

# Or restrict to specific origins
CORS(app, resources={r"/api/*": {"origins": ["https://example.com", "http://localhost:3000"]}})

# Per-route
@app.route("/api/public")
@cross_origin(origins="*")
def public():
    return {"data": "open"}

Respostas de erro de API

Uma função auxiliar mantém as respostas de erro uniformes entre endpoints — mesma forma, mesmos nomes de chave. Corpos de erro consistentes facilitam muito o tratamento de erros no cliente. Inclua detalhes que ajudem a depurar sem vazar segredos.

flask
from flask import jsonify, abort

def api_error(message, status=400, **extra):
    body = {"error": message}
    body.update(extra)
    return jsonify(body), status

@app.route("/api/users/<int:id>")
def get_user(id):
    user = find_user(id)
    if not user:
        return api_error("User not found", 404, user_id=id)
    return jsonify(user.serialize())

# Consistent error shape across the API:
# {"error": "User not found", "user_id": 1}
14

Upload de arquivos

Upload básico

A tag do form precisa de enctype=multipart/form-data para uploads de arquivos. Defina MAX_CONTENT_LENGTH para rejeitar uploads grandes demais com um 413 antes que o corpo seja lido por completo — isso protege o servidor.

flask
from flask import request
import os

app.config["UPLOAD_FOLDER"] = "uploads"
app.config["MAX_CONTENT_LENGTH"] = 16 * 1024 * 1024  # 16 MB

@app.route("/upload", methods=["POST"])
def upload():
    file = request.files["file"]
    file.save(os.path.join(app.config["UPLOAD_FOLDER"], file.filename))
    return "uploaded"

# HTML form must include enctype:
# <form method="POST" enctype="multipart/form-data">
#   <input type="file" name="file">
#   <button>Upload</button>
# </form>

Nome de arquivo seguro

secure_filename remove path traversal e caracteres inseguros de nomes de arquivo fornecidos por usuários. Não garante exclusividade — acrescente um UUID ou verifique colisões se sobrescrever for um risco.

flask
from werkzeug.utils import secure_filename
import os

@app.route("/upload", methods=["POST"])
def upload():
    f = request.files.get("file")
    if not f:
        return "no file", 400

    safe = secure_filename(f.filename)  # "my file!!/x.txt" -> "my_file__x.txt"
    if not safe:
        return "invalid filename", 400

    f.save(os.path.join("uploads", safe))
    return f"saved as {safe}"

Múltiplos arquivos

Use request.files.getlist('files') com um input que tenha o atributo multiple para aceitar vários arquivos de uma vez. Valide a extensão e o tamanho de cada arquivo antes de salvar.

flask
from flask import request

@app.route("/upload-many", methods=["POST"])
def upload_many():
    files = request.files.getlist("files")
    saved = []
    for f in files:
        if f and f.filename:
            name = secure_filename(f.filename)
            f.save(os.path.join("uploads", name))
            saved.append(name)
    return {"saved": saved}

# <form method="POST" enctype="multipart/form-data">
#   <input type="file" name="files" multiple>
# </form>

Upload com WTForms

O FileField do Flask-WTF valida a extensão e a presença do upload. A tag do form deve incluir enctype=multipart/form-data. O arquivo enviado fica acessível em form.photo.data.

flask
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileRequired, FileAllowed

class PhotoForm(FlaskForm):
    photo = FileField("Photo", validators=[
        FileRequired(),
        FileAllowed(["jpg", "jpeg", "png"], "Images only"),
    ])
    submit = SubmitField("Upload")

@app.route("/photo", methods=["GET", "POST"])
def photo():
    form = PhotoForm()
    if form.validate_on_submit():
        f = form.photo.data
        f.save(os.path.join("uploads", secure_filename(f.filename)))
        return "uploaded"
    return render_template("photo.html", form=form)

Validando tipo e tamanho de arquivo

Valide tanto a extensão quanto o comprimento do conteúdo antes de salvar. MAX_CONTENT_LENGTH rejeita requisições enormes cedo, mas checagens por arquivo dão controle mais fino. Para mais segurança, inspecione os magic bytes do arquivo, não apenas a extensão.

flask
import os
from flask import request

ALLOWED = {".png", ".jpg", ".jpeg", ".gif", ".pdf"}
MAX_SIZE = 5 * 1024 * 1024  # 5 MB

@app.route("/upload", methods=["POST"])
def upload():
    f = request.files.get("file")
    if not f or not f.filename:
        return "no file", 400

    ext = os.path.splitext(f.filename)[1].lower()
    if ext not in ALLOWED:
        return "file type not allowed", 415

    f.stream.seek(0, 2)        # seek to end
    size = f.stream.tell()
    f.stream.seek(0)
    if size > MAX_SIZE:
        return "file too large", 413

    f.save(os.path.join("uploads", secure_filename(f.filename)))
    return "ok"
15

Cookies e sessões

Definindo cookies

Cookies são definidos no objeto de resposta via set_cookie. Defina httponly=True para impedir que o JavaScript os leia (defesa contra XSS), secure=True para só HTTPS, e samesite='Lax' ou 'Strict' para defesa contra CSRF.

flask
from flask import make_response

@app.route("/set-cookie")
def set_cookie():
    resp = make_response("cookie set")
    resp.set_cookie("user", "alice", max_age=3600, httponly=True)
    resp.set_cookie("theme", "dark", path="/", secure=True, samesite="Lax")
    return resp

# max_age in seconds; expires sets a datetime
# httponly blocks JS access; secure requires HTTPS
# samesite: "Lax" (default), "Strict", or "None"

Lendo cookies

request.cookies é um ImmutableMultiDict somente leitura dos cookies enviados pelo navegador. Use .get() com um padrão em vez de indexar, pois um cookie pode não existir. Modificar cookies acontece na resposta.

flask
from flask import request

@app.route("/show-cookies")
def show_cookies():
    user = request.cookies.get("user", "guest")
    theme = request.cookies.get("theme", "light")
    all_cookies = request.cookies.to_dict()
    return f"user={user}, theme={theme}"

# request.cookies is a read-only dict
# use .get() with a default to avoid KeyError

Objeto session

session é um cookie assinado que armazena um dict serializado. Como é assinado com secret_key, usuários não podem alterá-lo, mas PODEM lê-lo — então nunca guarde senhas ou segredos na sessão.

flask
from flask import session

app.secret_key = "a-very-secret-string"

@app.route("/login")
def login():
    session["user_id"] = 1
    session["role"] = "admin"
    return "logged in"

@app.route("/dashboard")
def dashboard():
    if "user_id" not in session:
        return "please log in", 401
    return f"user {session['user_id']}"

@app.route("/logout")
def logout():
    session.pop("user_id", None)
    return "logged out"

Secret key

secret_key assina cookies de sessão e tokens CSRF. Use um valor longo e aleatório, e carregue-o do ambiente para que não seja commitado no controle de código. Todas as instâncias da app devem compartilhar a mesma chave.

flask
import os
from flask import Flask

app = Flask(__name__)

# Generate a strong random key
app.secret_key = os.urandom(32)

# Or load from environment (recommended for production)
app.secret_key = os.environ.get("SECRET_KEY")

# For multiple workers, all must share the same key
# so sessions survive being routed to different processes.
# A key of at least 32 random bytes is recommended.

Mensagens flash

flash guarda uma mensagem na sessão que sobrevive a um redirecionamento e é mostrada na próxima requisição. Chame get_flashed_messages no template para recuperá-las e limpá-las. with_categories permite estilizar por tipo.

flask
from flask import flash, redirect, url_for, render_template

app.secret_key = "secret"   # flash uses the session

@app.route("/save", methods=["POST"])
def save():
    flash("Saved successfully!", "success")
    return redirect(url_for("index"))

# In the template:
# {% with messages = get_flashed_messages(with_categories=true) %}
#   {% for category, message in messages %}
#     <div class="alert alert-{{ category }}">{{ message }}</div>
#   {% endfor %}
# {% endwith %}

Configuração de sessão

Por padrão, as sessões são baseadas em cookie e expiram quando o navegador fecha. Defina session.permanent=True e PERMANENT_SESSION_LIFETIME para estendê-las. Flask-Session move o armazenamento para o servidor (Redis, filesystem) para sessões maiores ou mais seguras.

flask
app.config.update(
    SECRET_KEY="secret",
    SESSION_COOKIE_NAME="sid",
    SESSION_COOKIE_HTTPONLY=True,
    SESSION_COOKIE_SECURE=True,     # HTTPS only
    SESSION_COOKIE_SAMESITE="Lax",
    PERMANENT_SESSION_LIFETIME=3600,  # seconds
    SESSION_TYPE="redis",            # needs Flask-Session
)

# Mark a session as permanent
from flask import session
from datetime import timedelta

@app.route("/remember")
def remember():
    session.permanent = True
    session["user"] = "alice"
    return "remembered for 1 hour"
16

Hooks before/after request

before_request

Handlers before_request rodam antes de cada view. Use-os para checagens de autenticação, modo de manutenção ou carregar estado compartilhado em g. Retornar um valor pula a view e usa aquela resposta diretamente.

flask
from flask import g, request

@app.before_request
def check_maintenance():
    if app.config.get("MAINTENANCE"):
        return "Site under maintenance", 503

@app.before_request
def load_user():
    token = request.headers.get("Authorization")
    if token:
        g.user = verify_token(token)

# Return a value to short-circuit the request

after_request

Handlers after_request rodam depois da view, recebendo e retornando a resposta. São perfeitos para adicionar headers, logar ou cachear. Se ocorrer uma exceção não tratada, after_request é pulado.

flask
@app.after_request
def add_security_headers(resp):
    resp.headers["X-Content-Type-Options"] = "nosniff"
    resp.headers["X-Frame-Options"] = "SAMEORIGIN"
    return resp

@app.after_request
def log_response(resp):
    app.logger.info("%s %s -> %s", request.method, request.path, resp.status_code)
    return resp

# Must take and return a Response object

teardown_request

teardown_request roda no fim de cada requisição, mesmo em erros — diferente de after_request. Recebe a exceção (ou None) e é o lugar certo para liberar recursos como conexões de DB ou handles de arquivos.

flask
import sqlite3
from flask import g

def get_db():
    if "db" not in g:
        g.db = sqlite3.connect("app.db")
    return g.db

@app.teardown_request
def close_db(exc):
    db = g.pop("db", None)
    if db is not None:
        db.close()

# teardown_request always runs, even if the view raised

before_first_request (descontinuado)

before_first_request foi removido no Flask 2.3 porque quebra com servidores assíncronos modernos e setups multiprocesso. Rode configuração única dentro de um contexto de app na importação ou num comando de CLI.

flask
# Flask 2.3+ removed before_first_request.
# Old code:
# @app.before_first_request
# def init():
#     warm_cache()

# Modern alternative: use the app context at startup
with app.app_context():
    warm_cache()

# Or a CLI command run once during deployment
@app.cli.command("init")
def init_cmd():
    warm_cache()

Modificando a resposta

Múltiplos handlers after_request se encadeiam em ordem reversa de registro. Cada um deve retornar uma resposta. São úteis para headers de segurança, diretivas de cache e IDs de tracing.

flask
@app.after_request
def no_cache(resp):
    resp.headers["Cache-Control"] = "no-store"
    resp.headers["Pragma"] = "no-cache"
    return resp

@app.after_request
def add_request_id(resp):
    rid = getattr(g, "request_id", "n/a")
    resp.headers["X-Request-ID"] = rid
    return resp

# Multiple after_request handlers run in reverse
# registration order; each receives the previous one's output.

Padrão de conexão de banco de dados

Um padrão comum: abrir uma conexão sob demanda em get_db (guardada em g) e fechá-la em teardown_appcontext. Isso dá a cada requisição sua própria conexão e garante a limpeza mesmo em erros.

flask
import sqlite3
from flask import g, current_app

def get_db():
    if "db" not in g:
        g.db = sqlite3.connect(
            current_app.config["DATABASE"],
            detect_types=sqlite3.PARSE_DECLTYPES,
        )
        g.db.row_factory = sqlite3.Row
    return g.db

@app.teardown_appcontext
def close_db(exc):
    db = g.pop("db", None)
    if db is not None:
        db.close()

@app.route("/users")
def users():
    db = get_db()
    rows = db.execute("SELECT * FROM users").fetchall()
    return {"users": [dict(r) for r in rows]}
17

Comandos de CLI

Comandos personalizados

Use @app.cli.command para registrar um comando de CLI, decorado com argumentos e opções do click. A docstring vira o texto de ajuda. Rode flask --help para listar os comandos disponíveis.

flask
import click
from flask import Flask

app = Flask(__name__)

@app.cli.command("create-user")
@click.argument("name")
@click.option("--admin", is_flag=True, default=False)
def create_user(name, admin):
    """Create a new user."""
    role = "admin" if admin else "user"
    click.echo(f"Created {name} as {role}")

# Run: flask create-user alice --admin

flask run

flask run inicia o servidor de dev do Werkzeug. --debug habilita o reloader e o depurador interativo. --app permite apontar para um módulo ou factory. Nunca use esse servidor em produção — é single-threaded e inseguro.

flask
# Basic
flask run

# Custom host/port
flask run --host=0.0.0.0 --port=8000

# Enable reloader and debugger
flask run --debug

# Specify the app explicitly
flask --app myapp run
flask --app myapp:create_app run

# With SSL (development)
flask run --cert=cert.pem --key=key.pem

Contexto do shell

shell_context_processor injeta nomes no flask shell para que você experimente sem imports. É valioso para depurar models e rodar consultas ad-hoc contra sua app.

flask
from flask import Flask
from models import db, User

app = Flask(__name__)

@app.shell_context_processor
def make_shell_context():
    return {"db": db, "User": User, "app": app}

# flask shell
# >>> User.query.all()
# >>> db.session.add(User(username="x"))

Application factory com CLI

Ao usar o padrão factory, registre os comandos de CLI dentro de create_app para que tenham acesso à app configurada. A opção --app do Flask detecta a factory e a invoca para você.

flask
# myapp/__init__.py
from flask import Flask

def create_app():
    app = Flask(__name__)
    app.config.from_object("config.Config")

    @app.cli.command("init-db")
    def init_db():
        """Initialize the database."""
        click.echo("Initialized")

    return app

# Run: flask --app myapp init-db
# The factory is detected automatically.

Grupos de CLI

Agrupe comandos relacionados sob um pai com @app.cli.group. Subcomandos são registrados no grupo, mantendo a CLI organizada: flask db init, flask db migrate etc.

flask
import click
from flask import Flask

app = Flask(__name__)

@app.cli.group("db")
def db_group():
    """Database commands."""
    pass

@db_group.command("init")
def db_init():
    click.echo("DB initialized")

@db_group.command("drop")
def db_drop():
    click.echo("DB dropped")

# flask db init
# flask db drop

Variáveis de ambiente

FLASK_APP e FLASK_DEBUG configuram a CLI. Use .flaskenv para configurações de dev compartilhadas e .env para segredos (ambos carregados automaticamente se python-dotenv estiver instalado). Mantenha segredos fora do .flaskenv, pois ele costuma ser commitado.

flask
# Flask reads these env vars:
# FLASK_APP      -> module/app to run (app.py, myapp, myapp:create_app)
# FLASK_DEBUG    -> 1/0 to toggle debug mode
# FLASK_ENV      -> development/production (deprecated, use FLASK_DEBUG)
# FLASK_RUN_PORT -> default port
# FLASK_RUN_HOST -> default host

# .env or .flaskenv files are auto-loaded by python-dotenv
# .flaskenv (committed): FLASK_APP=app.py
# .env (gitignored): SECRET_KEY=..., DATABASE_URL=...

# Prefer app.config.from_envvar or from_object for app secrets.
18

Testes

Básico do test client

test_client() retorna um client que faz requisições sem rede. Defina TESTING=True para melhores mensagens de erro e para desabilitar a captura de erros. Use uma fixture para que cada teste receba uma app nova.

flask
import pytest
from myapp import create_app

@pytest.fixture()
def client():
    app = create_app()
    app.config["TESTING"] = True
    with app.test_client() as client:
        with app.app_context():
            pass  # init DB here
        yield client

def test_home(client):
    resp = client.get("/")
    assert resp.status_code == 200
    assert b"Hello" in resp.data

Fazendo requisições em testes

O test client imita um navegador: get/post/put/delete com data (form), json, query_string e headers. Use resp.get_json() para interpretar uma resposta JSON e resp.headers para inspecioná-los.

flask
def test_get(client):
    resp = client.get("/users/1")
    assert resp.status_code == 200

def test_post_form(client):
    resp = client.post("/login", data={"username": "a", "password": "b"})
    assert resp.status_code == 302  # redirect

def test_post_json(client):
    resp = client.post("/api/echo", json={"key": "value"})
    assert resp.get_json() == {"received": {"key": "value"}}

def test_query(client):
    resp = client.get("/search?q=flask&page=2")
    assert resp.status_code == 200

def test_headers(client):
    resp = client.get("/", headers={"X-Test": "1"})

Testando API JSON

Passe json=... para enviar um corpo JSON com o Content-Type correto. Faça asserções sobre status, o corpo JSON interpretado e headers como Location. Testar caminhos de sucesso e de erro garante que a API se comporte de forma consistente.

flask
def test_create_user(client):
    resp = client.post(
        "/api/users",
        json={"username": "alice", "email": "[email protected]"},
    )
    assert resp.status_code == 201
    body = resp.get_json()
    assert body["username"] == "alice"
    assert "id" in body
    assert resp.headers["Location"].endswith(str(body["id"]))

def test_error(client):
    resp = client.post("/api/users", json={})
    assert resp.status_code == 422
    assert "error" in resp.get_json()

Fixtures com pytest

Fixtures fornecem configuração reutilizável: um banco de dados em memória, um test client e um CLI runner. Entregue o recurso com yield e limpe depois. test_cli_runner() invoca comandos de CLI em testes e verifica sua saída e código de saída.

flask
import pytest
from myapp import create_app, db

@pytest.fixture()
def app():
    app = create_app()
    app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///:memory:"
    with app.app_context():
        db.create_all()
        yield app
        db.drop_all()

@pytest.fixture()
def client(app):
    return app.test_client()

@pytest.fixture()
def runner(app):
    return app.test_cli_runner()

def test_cli(runner):
    result = runner.invoke(args=["create-user", "alice"])
    assert result.exit_code == 0

Banco de dados de teste

Use um SQLite em memória para testes rápidos e isolados. Crie tabelas e popule dados dentro da fixture, e depois apague tudo. Cada teste começa com uma página em branco, evitando contaminação entre testes.

flask
import pytest
from myapp import create_app, db
from myapp.models import User

@pytest.fixture()
def app():
    app = create_app()
    app.config["TESTING"] = True
    app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///:memory:"
    with app.app_context():
        db.create_all()
        db.session.add(User(username="alice"))
        db.session.commit()
        yield app
        db.session.remove()
        db.drop_all()

def test_user_count(app):
    with app.app_context():
        assert User.query.count() == 1

Mocking

patch substitui chamadas externas (HTTP, e-mail, filas) por mocks para que os testes continuem rápidos e determinísticos. Verifique que o mock foi chamado com os argumentos esperados. Sempre faça patch onde o nome é buscado, não onde é definido.

flask
from unittest.mock import patch, MagicMock
import myapp

def test_external_call(client):
    with patch("myapp.requests.get") as mock_get:
        mock_get.return_value = MagicMock(status_code=200, json=lambda: {"ok": True})
        resp = client.get("/proxy")
        assert resp.status_code == 200
        mock_get.assert_called_once()

def test_email(client):
    with patch("myapp.send_email") as mock_send:
        client.post("/register", data={"email": "[email protected]"})
        mock_send.assert_called_once_with("[email protected]", "Welcome!")
19

Deploy

Aviso sobre servidor de produção

O servidor de dev do Werkzeug é single-threaded e inseguro — nunca o exponha à internet. Use um servidor WSGI de produção (Gunicorn, uWSGI, Waitress) atrás de um proxy reverso. O depurador de debug é um risco de execução remota de código.

flask
# WARNING: Flask's built-in server is for development only!
# app.run() / flask run -> single-threaded, no security, not scalable

# For production use a WSGI server:
# - Gunicorn (Linux/macOS)
# - uWSGI
# - Waitress (Windows-friendly)
# Behind a reverse proxy (Nginx, Apache, Caddy)

# The dev server also enables the interactive debugger
# when debug=True, which allows arbitrary code execution.
# NEVER deploy with debug=True.

Gunicorn

Gunicorn é o servidor WSGI mais popular para Linux/macOS. A fórmula (2 × CPU + 1) workers é um bom ponto de partida. Atrás do Nginx, vincule a 127.0.0.1 e deixe o proxy tratar TLS e arquivos estáticos.

flask
pip install gunicorn

# Basic
gunicorn "app:app"

# With factory
gunicorn "myapp:create_app()"

# Workers and binding
gunicorn -w 4 -b 0.0.0.0:8000 "app:app"

# With timeout and logging
gunicorn -w 4 -b 0.0.0.0:8000 --timeout 120 --access-logfile - "app:app"

# Recommended workers: (2 * CPU) + 1
# Use --preload to share memory, or -k gevent for async.

uWSGI

uWSGI é um servidor WSGI de alto desempenho e altamente configurável. O processo master gerencia os workers; vacuum limpa na saída. Pareie com Nginx usando o protocolo uwsgi para melhor throughput.

flask
pip install uwsgi

# Command line
uwsgi --http 0.0.0.0:8000 --module app:app --processes 4 --threads 2

# INI config (uwsgi.ini)
# [uwsgi]
# module = app:app
# http = 0.0.0.0:8000
# processes = 4
# threads = 2
# master = true
# vacuum = true
# die-on-term = true

# Run: uwsgi uwsgi.ini

Proxy reverso (Nginx)

Nginx fica na frente do Gunicorn: serve arquivos estáticos diretamente (mais rápido), termina o TLS e encaminha requisições ao servidor WSGI. Os headers X-Forwarded-* permitem que o Flask veja o IP e o scheme reais do cliente — defina ProxyFix para confiar neles.

flask
# /etc/nginx/sites-available/myapp
server {
    listen 80;
    server_name example.com;

    location /static/ {
        alias /path/to/app/static/;
        expires 30d;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;
    }
}

Docker

Uma imagem base Python enxuta mantém a imagem pequena. Instale as dependências antes de copiar o código para aproveitar o cache de camadas do Docker. Passe segredos via variáveis de ambiente (--env-file), nunca os asse na imagem.

flask
# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "app:app"]

# .dockerignore
# __pycache__/
# venv/
# *.pyc
# .env

# Build and run
# docker build -t myapp .
# docker run -p 8000:8000 --env-file .env myapp

Configuração por ambiente

Camadas de configuração: defaults no código, overrides específicos de ambiente e segredos de instância vindos de variáveis de ambiente. Isso mantém segredos fora do controle de código e permite que uma base de código rode em dev, staging e produção.

flask
import os
from flask import Flask

app = Flask(__name__)
app.config.from_object("config.DefaultConfig")

# Override with environment-specific config
env = os.environ.get("FLASK_ENV", "development")
app.config.from_object(f"config.{env.title()}Config")

# Then instance-specific secrets from env vars
app.config["SECRET_KEY"] = os.environ["SECRET_KEY"]
app.config["SQLALCHEMY_DATABASE_URI"] = os.environ["DATABASE_URL"]

# Use python-dotenv for local .env files
from dotenv import load_dotenv
load_dotenv()
20

Configuração

Objeto Config

Defina a configuração como classes que herdam de um Config base. Sobrescreva apenas o que muda por ambiente. from_object copia atributos em maiúsculas para app.config, então helpers em minúsculas são ignorados.

flask
class Config:
    DEBUG = False
    TESTING = False
    SECRET_KEY = "change-me"
    SQLALCHEMY_DATABASE_URI = "sqlite:///app.db"

class DevelopmentConfig(Config):
    DEBUG = True
    SECRET_KEY = "dev-secret"

class ProductionConfig(Config):
    DEBUG = False
    SECRET_KEY = os.environ["SECRET_KEY"]

class TestingConfig(Config):
    TESTING = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"

app.config.from_object(DevelopmentConfig)

Variáveis de ambiente

Use os.environ para segredos, para que nunca vivam no código. from_envvar carrega um arquivo Python apontado por uma variável de ambiente — útil para overrides específicos de deploy. python-dotenv carrega um arquivo .env para desenvolvimento local.

flask
import os
from flask import Flask

app = Flask(__name__)

# Read individual values
app.config["SECRET_KEY"] = os.environ.get("SECRET_KEY", "dev")
app.config["DATABASE_URL"] = os.environ.get("DATABASE_URL", "sqlite:///app.db")

# Load a whole config file from an env var path
# export MYAPP_SETTINGS=/etc/myapp/prod.py
app.config.from_envvar("MYAPP_SETTINGS", silent=True)

# python-dotenv loads .env automatically if installed
from dotenv import load_dotenv
load_dotenv()

Pasta instance

A pasta instance guarda arquivos específicos de deploy (segredos, config) fora do controle de versão. Defina instance_relative_config=True e carregue com from_pyfile. Isso separa código de configuração de ambiente de forma limpa.

flask
# The instance/ folder sits outside the package, not in VCS.
# Flask searches it automatically for config files.

app = Flask(__name__, instance_relative_config=True)

# Load from instance/config.py
app.config.from_pyfile("config.py", silent=True)

# instance/config.py (deployment-specific, gitignored)
# SECRET_KEY = "real-production-key"
# SQLALCHEMY_DATABASE_URI = "postgresql://user:pass@db/app"

# Access the path
print(app.instance_path)  # /abs/path/to/instance

Config de arquivo

from_object importa um módulo ou caminho de objeto; from_pyfile carrega um arquivo absoluto; from_file (Flask 2.0+) usa uma função loader, suportando JSON, TOML ou YAML. Escolha um formato e seja consistente.

flask
# config.py
DEBUG = True
SECRET_KEY = "dev"
SQLALCHEMY_DATABASE_URI = "sqlite:///dev.db"

# Load a Python file
app.config.from_object("config")

# Load by path
app.config.from_pyfile("/etc/myapp/config.py")

# Load from a JSON file
app.config.from_file("config.json", load=json.load)

# config.json
# { "DEBUG": true, "SECRET_KEY": "dev" }

Desenvolvimento vs produção

Alterne configurações por variável de ambiente para que o mesmo código rode em toda parte. A produção deve desabilitar debug (o depurador é um furo de segurança) e usar um banco de dados real. Registre um aviso se debug estiver ligado em produção.

flask
import os
from flask import Flask

env = os.environ.get("FLASK_ENV", "development")

configs = {
    "development": DevelopmentConfig,
    "production": ProductionConfig,
    "testing": TestingConfig,
}

app = Flask(__name__)
app.config.from_object(configs[env])

# In production, never enable debug:
if app.config["DEBUG"]:
    print("WARNING: running in debug mode!")

Configuração de logging

Configure o logging apenas fora do modo debug (o Flask loga no stderr por padrão em debug). RotatingFileHandler impede crescimento ilimitado de logs. Em produção, considere logging estruturado em JSON para serviços de agregação.

flask
import logging
from logging.handlers import RotatingFileHandler

if not app.debug:
    handler = RotatingFileHandler("app.log", maxBytes=10*1024*1024, backupCount=5)
    handler.setFormatter(logging.Formatter(
        "%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]"
    ))
    handler.setLevel(logging.INFO)
    app.logger.addHandler(handler)
    app.logger.setLevel(logging.INFO)

# In a view
@app.route("/")
def index():
    app.logger.info("Index page accessed")
    return "Hello"

# Flask's logger is a standard logging.Logger

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.