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.
# 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.
# 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.pyAmbiente 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.
# 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.txtEstrutura 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.
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 handlersPadrã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.
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_appAnatomia 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.
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!"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.
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.
@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 codeURLs ú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.
@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 FoundVerbos 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.
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.
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/bobMú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.
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.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.
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).
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.
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.
@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", 418Respostas 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.
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.
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 respObjeto 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.
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.
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.
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.
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 dataHeaders 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.
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 '?'.
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(),
}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.
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.
# 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.
{# 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.
{# 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.
{{ 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.
{# 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>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.
# 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.
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.jsPasta 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.
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.cssFavicon
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.
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.
# 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 }}">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.
# 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.
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.
# 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.
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.
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"), 403Blueprints 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.
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/infoContexto (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.
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.
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.
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.
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.
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.
# 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)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.
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.
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.
# 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.
# 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.
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 userMigraçõ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.
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 revisionWTForms (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.
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.
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.
{# 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.
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 POSTValidadores 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.
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.
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)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.
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.
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.
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.
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 decoratorLogout
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.
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 cookiesRemember 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.
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 %}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.
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 ErrorPá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.
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"), 500Error 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.
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.
@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"), 500Registrando 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.
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", 500Tratamento 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.
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", 404JSON 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.
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 escapingRetornando 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.
# 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.
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"]}), 201Blueprint 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.
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 '*'.
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.
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}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.
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.
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.
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.
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.
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"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.
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 requestafter_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.
@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 objectteardown_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.
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 raisedbefore_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 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.
@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.
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]}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.
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 --adminflask 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.
# 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.pemContexto 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.
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ê.
# 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.
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 dropVariá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 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.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.
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.dataFazendo 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.
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.
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.
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 == 0Banco 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.
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() == 1Mocking
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.
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!")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.
# 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.
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.
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.iniProxy 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.
# /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.
# 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 myappConfiguraçã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.
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()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.
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.
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.
# 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/instanceConfig 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.
# 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.
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.
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.LoggerSnippets de Flask relacionados
Copy-paste ready code for common tasks.
Routing
Define routes with methods and dynamic parameters.
Request and Response
Access request data and build custom responses.
Jinja2 Templates
Render templates with context and template inheritance.
Blueprints
Organize an app into modular blueprints.
Session
Store per-user data in signed session cookies.
Error Handling
Register custom error handlers for HTTP exceptions.
Flask-SQLAlchemy
Define models and query them with Flask-SQLAlchemy.
Custom Decorators
Build decorators to gate or augment view functions.
Was this helpful?