Boas práticas com Jupyter Notebooks (1/6)— integração com git

Uma agenda de anotações em branco com uma lapiseira em cima, além de uma borracha e uma caneta ao lado | Foto de Mike Tinnion na Unsplash

A ideia deste artigo é propor uma visão sobre o uso de Jupyter Notebooks para desenvolvimento, em especial aqueles que vão para produção. Funciona? É o ideal? Vamos discutir!

Disclaimer: o tópico deste artigo e todos os outros citados ao final são um resumo do vídeo abaixo, o qual achei fantástico, e resolvi trazê-lo de forma compacta, simples e textual.

PyData Chicago: Running Notebooks in Production? Blessing or Curse? by Eduardo Blancas

Jupyter Notebook — o que é?

Para ler este artigo, é importante alinharmos algo antes. O que é Jupyter Notebook? Não é uma resposta tão simples quanto parece, por isso vou elucidar alguns pontos com referências para facilitar o entendimento.

Jupyter Notebook é uma expressão que tem dois significados bem distintos. Ele é tanto uma plataforma de desenvolvimento quanto um formato de arquivo.

Plataforma de desenvolvimento: Jupyter Notebook é uma plataforma de desenvolvimento web que facilita visualização do código através da execução de células isoladas. A grande vantagem no uso desta plataforma é para prototipagem rápida de experimentações de ciência de dados e análise exploratória. Site oficial da plataforma: https://jupyter.org/

Extensão de arquivo: ao mesmo tempo, Jupyter Notebook também é referente à uma extensão de arquivo. Um arquivo Jupyter Notebook tem a extensão .ipynb, no qual a letra i significa interactive, interativo, py vem de Python, e nb de NoteBook. No fundo um arquivo .ipynb armazena metadados do arquivo em formato JSON, seguindo um padrão chamado nbformat. Um exemplo pode ser encontrado abaixo, retirado da própria documentação oficial:

{
  "metadata" : {
    "kernel_info": {
        # if kernel_info is defined, its name field is required.
        "name" : "the name of the kernel"
    },
    "language_info": {
        # if language_info is defined, its name field is required.
        "name" : "the programming language of the kernel",
        "version": "the version of the language",
        "codemirror_mode": "The name of the codemirror mode to use [optional]"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0,
  "cells" : [
      # list of cell dictionaries, see below
  ],
}

E agora que sabemos o conceito, quando eu disser Jupyter Notebook, estarei me referindo à extensão de arquivo, sempre!

Jupyter Notebook e integração com git

O git, software para versionamento de código, versiona por modificações em cada linha do arquivo. Como alterações em arquivos Jupyter Notebooks são armazenados em formato JSON (metadados) conforme explicado acima, o versionamento fica mais confuso, pois não fica explícito qual linha exatamente foi alterada. Por isso é comum a conversão de arquivos Jupyter Notebooks para scripts Python para um melhor versionamento.

Só que tal conversão é trabalhosa e perde-se a principal vantagem do uso do Jupyter Notebook: divisão por células.

Não é necessário escolher entre um ou outro, pois há uma maneira bem simples de “trocar o formato” sem perder tal vantagem. Existe um pacote chamado jupytext que habilita uma pequena modificação em scripts .py para ter a vantagem de volta, e obter uma melhor integração com o versionamento usando git. E também é possível fazer uso deste método para desenvolver em IDEs como VSCode, Spyder ou Pycharm. Abaixo um exemplo bem simples, retirado da documentação oficial do VSCode:

# main.py
# %%
msg = "Hello World"
print(msg)

# %%
msg = "Hello again"
print(msg)

Quando adicionamos esses pequeno trechos comentados # %%ao nosso script, o que acontece? Vejamos:

O VSCode agora nos fornece alguns botões acima da linha comentada para simular o comportamento de células. Agora podemos rodar apenas uma parte de um script clicando em Run cell ou então debugar apenas uma parte específica do código, sem necessariamente rodar o código por completo.

Uma grande desvantagens no uso de Jupyter Notebooks que não comentei acima é a inexistência do modo debug, muito utilizada para desenvolvedores para depurar o código linha a linha e ver o que está acontecendo.

Agora temos um script main.py que tem todas as vantagens de ser um script, acrescido da vantagem de execução simulada por células.

Não é necessário mais converter o arquivo .ipynb para .py, não perdemos a vantagem de códigos em células e ainda temos o modo debug disponível em cada célula! Só vantagens, nenhuma desvantagem!

Este foi apenas um dos tópicos abordados dentre outros muitos que pretendo abordar. Os próximos serão:

• Como organizar melhor arquivos Jupyter Notebooks para projetos de ciência de dados?
• Jupyter Notebooks: operações mutáveis vs imutáveis
• Formatação automática de Jupyter Notebooks (PEP 8)
• Testes automatizados em Jupyter Notebooks
• Organizando pipelines completos com Jupyter Notebooks