Jupyter pra engenharia: notebook reprodutível
⏱ 10 min·⭐ 45 XP
Pré-requisitos (0/1)0%
- ⬜🚀 FastAPI na prática: routers, DI e auth(Python para Engenheiros)
Recomendamos completar os pré-requisitos antes de seguir, mas nada te impede de continuar.
Jupyter bem usado
| Uso | Caderno serve? | Por quê |
|---|---|---|
| Explorar dado novo | Sim, é o melhor formato | Resultado imediato ao lado do código, com gráfico |
| Prototipar modelo | Sim | Iteração rápida vale mais que estrutura nesta fase |
| Relatório recorrente | Sim, se parametrizado e executado por ferramenta | Vira função: mesmos passos, entrada diferente, saída arquivada |
| Código que roda sem supervisão | Não | Estado oculto e ordem livre de execução tornam o resultado irreprodutível |
| Biblioteca compartilhada | Não | Não há importação, teste nem revisão de diferença legível |
| Tutorial executável | Sim | É exatamente o formato para isso |
UsoExplorar dado novo
Caderno serve?Sim, é o melhor formato
Por quêResultado imediato ao lado do código, com gráfico
UsoPrototipar modelo
Caderno serve?Sim
Por quêIteração rápida vale mais que estrutura nesta fase
UsoRelatório recorrente
Caderno serve?Sim, se parametrizado e executado por ferramenta
Por quêVira função: mesmos passos, entrada diferente, saída arquivada
UsoCódigo que roda sem supervisão
Caderno serve?Não
Por quêEstado oculto e ordem livre de execução tornam o resultado irreprodutível
UsoBiblioteca compartilhada
Caderno serve?Não
Por quêNão há importação, teste nem revisão de diferença legível
UsoTutorial executável
Caderno serve?Sim
Por quêÉ exatamente o formato para isso
- Exploração: dados novos, entender shape, viz rápida.
- Relatórios parametrizados: papermill executa notebook com params, gera artifact.
- Prototipagem de modelo: treinar, plotar, iterar rápido.
- Documentação executável: tutoriais.
Jupyter NÃO é: produção. Quando código estabiliza, migrar pra módulo .py + pytest.
jupytext pra git diff sadio
uv add --dev jupytext
# Parear notebook com .py
jupytext --set-formats ipynb,py:percent analysis.ipynb
# Agora analysis.py é gerado ao salvar. Commit só o .py:
# .gitignore:
*.ipynb
!notebooks-public/**/*.ipynb # exceções se precisa
# Abrir .py como notebook:
jupyter notebook analysis.py # funciona diretopapermill — notebook como função
# cells parametrizadas (tag: parameters)
# date = "2026-04-01"
# client_id = "acme"
# Execute com params
import papermill as pm
pm.execute_notebook(
"report.ipynb",
"out/report-acme-20260401.ipynb",
parameters={"date": "2026-04-01", "client_id": "acme"},
)
# Uso: relatórios mensais, experiments em grid, dashboards programáticosQuiz rápido
Por que parear o notebook com um arquivo `.py` e versionar apenas ele?
Marimo alternativa
uv tool install marimo
# Cria novo
marimo new analysis.py
# Edita (abre browser com UI reativa)
marimo edit analysis.py
# Deploy como app
marimo run analysis.py --port 8080💡
Regra: notebook pra exploração, .py+pytest pra código que vai rodar em produção. Marimo ajuda a migrar gradualmente.
Perguntas frequentes
❓ Notebook serve para código de produção?
Não como artefato de produção: estado oculto na ordem de execução torna o resultado irreprodutível. Serve para exploração, e o caminho é migrar o que ficou estável para módulo com teste. Notebook em produção é a origem clássica de "funcionava ontem".
❓ Como versionar notebook sem sofrer?
Limpando saídas antes de commitar e, quando possível, mantendo a lógica em módulos importados pelo notebook. Diferença de notebook com saída é ilegível em revisão, e é por isso que a revisão passa a ser feita por cima.
❓ Como tornar notebook reprodutível?
Executando-o de cima a baixo em ambiente limpo no fluxo de integração — se ele não roda assim, não é reprodutível. É o teste mais simples e o que mais revela dependência de estado que só existia na sessão de quem escreveu.
Fixando
Quiz rápido
O que a execução parametrizada de notebooks permite que a execução manual não permite?
Quiz rápido
Qual é a regra do módulo sobre notebook e produção?
Terminou de ler?
Marcar como concluído registra o XP, mantém sua sequência e coloca 3 cartas deste módulo na fila de revisão espaçada.
Próximos passos sugeridos
Temas deste módulo
Discussão
Carregando comentários…