Jupytexto

¿Siempre has deseado que los cuadernos Jupyter fueran documentos de texto sin formato? ¿Deseabas poder editarlos en tu IDE favorito? ¿Y obtener diferencias claras y significativas al realizar el control de versiones? Entonces, ¡Jupytext puede ser la herramienta que estás buscando!

Cuadernos de texto

Un cuaderno de Python codificado en formato py:percent tiene una extensión .py y se ve así:

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

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

Solo se incluyen las entradas del cuaderno (y, opcionalmente, los metadatos). Los cuadernos de texto son muy adecuados para el control de versiones. También puedes editarlos o refactorizarlos en un IDE: el cuaderno .py de arriba es un archivo Python normal.

Recomendamos el formato percent para cuadernos que contienen principalmente código. El formato percent está disponible para Julia, Python, R y muchos otros lenguajes.

Si su cuaderno está orientado a la documentación, un formato basado en Markdown (cuadernos de texto con extensión .md ) podría ser más apropiado. Dependiendo de lo que planee hacer con su computadora portátil, es posible que prefiera el formato Myst Markdown, que interopera muy bien con Jupyter Book, Quarto Markdown o incluso Pandoc Markdown.

Instalación

Instale Jupytext en el entorno Python que utiliza para Jupyter. Utilice cualquiera de los dos

 pip install jupytext

o

 conda install jupytext -c conda-forge

Luego, reinicie su servidor de Jupyter Lab y asegúrese de que Jupytext esté activado en Jupyter: los archivos .py y .md tienen un ícono de Notebook y puede abrirlos como Notebooks con un clic derecho en Jupyter Lab.

Cuadernos emparejados

Los cuadernos de texto con extensión .py o .md son muy adecuados para el control de versiones. Se pueden editar o crear cómodamente en un IDE. Puede abrirlos y ejecutarlos como cuadernos en Jupyter Lab con un clic derecho. Sin embargo, las salidas del cuaderno se pierden cuando se cierra el cuaderno, ya que solo las entradas del cuaderno se guardan en los cuadernos de texto.

Una alternativa conveniente a los cuadernos de texto son los cuadernos emparejados. Se trata de un conjunto de dos archivos, digamos .ipynb y .py , que contienen el mismo cuaderno, pero en diferentes formatos.

Puede editar la versión .py del cuaderno emparejado y recuperar las ediciones en Jupyter seleccionando recargar cuaderno desde el disco . Las salidas se recargarán desde el archivo .ipynb , si existe. La versión .ipynb se actualizará o volverá a crear la próxima vez que guarde el cuaderno en Jupyter.

Para emparejar un cuaderno en Jupyter Lab, use el comando Pair Notebook with percent Script de la paleta de comandos:

Para emparejar todos los portátiles en un directorio determinado, cree un archivo de configuración con este contenido:

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

línea de comando

Jupytext también está disponible en la línea de comando. Puede

emparejar un cuaderno con jupytext --set-formats ipynb,py:percent notebook.ipynb
sincronizar los archivos emparejados con jupytext --sync notebook.py (las entradas se cargan desde el archivo emparejado más reciente)
convierta un cuaderno de un formato a otro con jupytext --to ipynb notebook.py (use -o si desea un archivo de salida específico)
conecte un cuaderno a un linter con, por ejemplo jupytext --pipe black notebook.ipynb

Casos de uso de muestra

Cuadernos bajo control de versiones

Este es un rápido procedimiento:

Abra su cuaderno .ipynb en Jupyter y emparéjelo con un cuaderno .py , usando el comando pair en Jupyter Lab o un archivo de configuración global.
Guarde el cuaderno: esto crea un cuaderno .py
Agregue este cuaderno .py al control de versiones

Puede excluir los archivos .ipynb del control de versiones (¡a menos que desee ver los resultados versionados!). Jupytext recreará los archivos .ipynb localmente cuando los usuarios abran y guarden los cuadernos .py .

Colaborando en cuadernos con Git

Colaborar en cuadernos Jupyter a través de Git se vuelve tan fácil como colaborar en archivos de texto.

Supongamos que tiene sus cuadernos .py bajo control de versiones (ver arriba). Entonces,

Tu colaborador saca el cuaderno .py
Lo abren como un cuaderno en Jupyter (haga clic derecho en Jupyter Lab)
En esa etapa el portátil no tiene salidas. Ejecutan el cuaderno y lo guardan. Las salidas se regeneran y se crea un archivo .ipynb local.
Editan el cuaderno y envían el archivo notebook.py actualizado. La diferencia no es más que una diferencia estándar en un script de Python.
Extrae el script notebook.py actualizado y actualiza su navegador. Las celdas de entrada se actualizan según el nuevo contenido de notebook.py . Las salidas se recargan desde su archivo .ipynb local. Finalmente, las variables del kernel no se modifican, por lo que tiene la opción de ejecutar solo las celdas modificadas para obtener los nuevos resultados.

Editar o refactorizar un cuaderno en un IDE

Una vez que su computadora portátil esté emparejada con un archivo .py , puede editar o refactorizar fácilmente la representación .py de la computadora portátil en un IDE.

Una vez que haya terminado de editar el cuaderno .py , solo tendrá que volver a cargar el cuaderno en Jupyter para obtener las últimas ediciones allí.

Nota: Es más sencillo cerrar el cuaderno .ipynb en Jupyter cuando edita el archivo .py emparejado. No hay obligación de hacerlo; sin embargo, si no lo hace, debe estar preparado para leer atentamente los mensajes emergentes. Si Jupyter intenta guardar el cuaderno mientras el archivo .py emparejado también se ha editado en el disco desde la última recarga, se detectará un conflicto y se le pedirá que decida qué versión del cuaderno (en la memoria o en el disco) es la uno apropiado.