Jupytext

Você sempre desejou que os cadernos Jupyter fossem documentos de texto simples? Gostaria de poder editá-los em seu IDE favorito? E obter diferenças claras e significativas ao fazer o controle de versão? Então, Jupytext pode muito bem ser a ferramenta que você procura!

Cadernos de texto

Um notebook Python codificado no formato py:percent tem uma extensão .py e se parece com isto:

 # %% [markdown]
# This is a markdown cell

# %%
def f(x):
  return 3*x+1

Somente as entradas do notebook (e opcionalmente, os metadados) estão incluídas. Os blocos de notas de texto são adequados para controle de versão. Você também pode editá-los ou refatorá-los em um IDE - o notebook .py acima é um arquivo Python normal.

Recomendamos o formato percent para notebooks que contêm principalmente código. O formato percent está disponível para Julia, Python, R e muitas outras linguagens.

Se o seu bloco de notas for orientado para documentação, um formato baseado em Markdown (cadernos de texto com extensão .md ) pode ser mais apropriado. Dependendo do que você planeja fazer com seu notebook, você pode preferir o formato Myst Markdown, que interopera muito bem com Jupyter Book, ou Quarto Markdown, ou mesmo Pandoc Markdown.

Instalação

Instale o Jupytext no ambiente Python que você usa para o Jupyter. Use qualquer um

 pip install jupytext

ou

 conda install jupytext -c conda-forge

Em seguida, reinicie o servidor Jupyter Lab e certifique-se de que o Jupytext esteja ativado no Jupyter: os arquivos .py e .md têm um ícone de Notebook e você pode abri-los como Notebooks com um clique com o botão direito no Jupyter Lab.

Cadernos emparelhados

Blocos de anotações de texto com extensão .py ou .md são adequados para controle de versão. Eles podem ser editados ou criados convenientemente em um IDE. Você pode abri-los e executá-los como notebooks no Jupyter Lab com um clique com o botão direito. Porém, as saídas do notebook são perdidas quando o notebook é fechado, pois apenas as entradas do notebook são salvas nos notebooks de texto.

Uma alternativa conveniente aos cadernos de texto são os cadernos emparelhados. Trata-se de um conjunto de dois arquivos, digamos .ipynb e .py , que contêm o mesmo notebook, mas em formatos diferentes.

Você pode editar a versão .py do notebook emparelhado e recuperar as edições no Jupyter selecionando reload notebook from disk . As saídas serão recarregadas do arquivo .ipynb , se existir. A versão .ipynb será atualizada ou recriada na próxima vez que você salvar o notebook no Jupyter.

Para emparelhar um notebook no Jupyter Lab, use o comando Pair Notebook with percent Script da paleta de comandos:

Para emparelhar todos os notebooks em um determinado diretório, crie um arquivo de configuração com este conteúdo:

 # jupytext.toml at the root of your notebook directory
formats = "ipynb,py:percent"

Linha de comando

Jupytext também está disponível na linha de comando. Você pode

emparelhar um notebook com jupytext --set-formats ipynb,py:percent notebook.ipynb
sincronize os arquivos emparelhados com jupytext --sync notebook.py (as entradas são carregadas do arquivo emparelhado mais recente)
converta um notebook de um formato para outro com jupytext --to ipynb notebook.py (use -o se desejar um arquivo de saída específico)
canalize um notebook para um linter com, por exemplo jupytext --pipe black notebook.ipynb

Exemplos de casos de uso

Notebooks sob controle de versão

Este é um tutorial rápido:

Abra seu notebook .ipynb no Jupyter e emparelhe-o com um notebook .py , usando o comando pair no Jupyter Lab ou um arquivo de configuração global
Salve o notebook - isso cria um notebook .py
Adicione este notebook .py ao controle de versão

Você pode excluir arquivos .ipynb do controle de versão (a menos que queira ver as saídas versionadas!). O Jupytext recriará os arquivos .ipynb localmente quando os usuários abrirem e salvarem os notebooks .py .

Colaborando em notebooks com Git

Colaborar em notebooks Jupyter por meio do Git torna-se tão fácil quanto colaborar em arquivos de texto.

Suponha que você tenha seus notebooks .py sob controle de versão (veja acima). Então,

Seu colaborador puxa o notebook .py
Eles o abrem como um notebook no Jupyter (clique com o botão direito no Jupyter Lab)
Nesse estágio, o notebook não possui saídas. Eles executam o notebook e o salvam. As saídas são regeneradas e um arquivo .ipynb local é criado
Eles editam o notebook e enviam o arquivo notebook.py atualizado. O diff nada mais é do que um diff padrão em um script Python.
Você extrai o script notebook.py atualizado e atualiza seu navegador. As células de entrada são atualizadas com base no novo conteúdo de notebook.py . As saídas são recarregadas do arquivo .ipynb local. Finalmente, as variáveis do kernel permanecem intactas, então você tem a opção de executar apenas as células modificadas para obter as novas saídas.

Editando ou refatorando um notebook em um IDE

Depois que seu notebook estiver emparelhado com um arquivo .py , você poderá editar ou refatorar facilmente a representação .py do notebook em um IDE.

Quando terminar de editar o notebook .py , você só terá que recarregar o notebook no Jupyter para obter as edições mais recentes.

Nota: É mais simples fechar o bloco de notas .ipynb no Jupyter quando você edita o arquivo .py emparelhado. Não há obrigação de fazê-lo; entretanto, se não o fizer, você deve estar preparado para ler atentamente as mensagens pop-up. Se o Jupyter tentar salvar o notebook enquanto o arquivo .py emparelhado também tiver sido editado no disco desde a última recarga, um conflito será detectado e você será solicitado a decidir qual versão do notebook (na memória ou no disco) é a apropriado.