Entrega de cuadernos de Jupyter: salidas guardadas, estado del kernel y nuevas ejecuciones

Imagina que recibes un cuaderno de Jupyter con un gráfico convincente. La celda de parámetros situada encima ha cambiado desde que se generó el gráfico. Es una entrega hipotética, pero la pregunta es práctica: ¿qué demuestra realmente el archivo?

El gráfico puede ser útil. Lo que no permite determinar es qué código fuente guardado lo produjo. Antes de pulsar Ejecutar todas las celdas, decide qué necesita saber tu colega. Quizá necesite una nueva ejecución secuencial. O quizá solo necesite el cuaderno original, con una explicación clara de que sus salidas no se han regenerado.

Esta guía utiliza la Entrega en tres estados para hacer explícita esa elección. Es una lista de comprobación editorial, no una función ni una certificación de Jupyter.

Distingue el archivo del cuaderno, el kernel activo y las pruebas de una nueva ejecución

Qué conserva un archivo .ipynb

La especificación del formato de cuaderno describe celdas de código que contienen código fuente, salidas y un execution_count cuyo valor es un entero o null. Guardar estos campos conserva un documento. No crea un registro de auditoría que vincule cada resultado visible con el código fuente actual.

Esa distinción es el punto de partida de la Entrega en tres estados de Optijara. Trata el documento guardado como un elemento de prueba. Investiga por separado el kernel en ejecución y registra después si se intentó una nueva ejecución secuencial. Mientras no sepas cómo se generó un gráfico, este aporta información sobre el documento guardado, pero no acredita una nueva ejecución verificada.

Qué pertenece al kernel en ejecución

JupyterLab documenta cómo conectar una consola de código al kernel de un cuaderno. Por tanto, la memoria del kernel puede incluir trabajo interactivo realizado fuera de la secuencia visible del cuaderno. Esas dependencias merecen atención antes de que otra persona intente ejecutar el archivo.

Cerrar la pestaña no las resuelve. La documentación del panel de procesos en ejecución de JupyterLab indica que el kernel subyacente sigue ejecutándose después de cerrar el cuaderno. Registra el kernel seleccionado y cualquier contexto interactivo relevante, en lugar de considerar que cerrar un documento equivale a reiniciarlo.

Qué puede demostrar una nueva ejecución secuencial

Una ejecución secuencial completada y revisada con un kernel recién iniciado permite hacer una afirmación acotada: las celdas de código incluidas en el alcance declarado se ejecutaron en orden, en el contexto registrado y con el resultado comunicado. Registra las omisiones en lugar de dar a entender que se ejecutaron todas las celdas. Las recomendaciones de PLOS para compartir cuadernos aconsejan reiniciar y volver a ejecutar las celdas para detectar pasos omitidos por accidente, no para certificar el análisis.

Mantén esa afirmación dentro de sus límites. Un kernel recién iniciado puede seguir utilizando el mismo entorno y los mismos archivos. Los servicios externos también quedan fuera del cuaderno. Incluso una ejecución satisfactoria deja abierta la cuestión analítica: un cálculo puede ejecutarse sin producir una respuesta correcta o significativa.

Recorre un cuaderno hipotético ejecutado fuera de orden

Un parámetro editado junto a un gráfico anterior

En este ejemplo no ejecutado, una persona que realiza el análisis ejecuta una celda de parámetros y la utiliza para preparar los datos de un gráfico. Más tarde, edita el código fuente del parámetro y guarda el cuaderno sin volver a ejecutar las celdas que dependen de él.

Quien lo recibe ve el nuevo parámetro junto al gráfico anterior. Este ejemplo no aporta valores de salida, contadores de ejecución ni errores observados. Ilustra una carencia de pruebas: el gráfico por sí solo no permite determinar si lo produjo el parámetro guardado.

Preguntas que debes resolver antes de aceptar la entrega

Empieza por identificar la versión del código fuente guardado y los datos de entrada que pueda identificar quien lo envía. Pregunta si alguna celda dependía del estado de la consola. La pregunta más directa es: ¿se regeneraron las salidas después de la última modificación relevante?

Los contadores de ejecución pueden darte motivos para investigar. No responden por sí solos a esas preguntas. Si volver a ejecutar el cuaderno está autorizado y resulta viable, documenta el intento. De lo contrario, conserva el archivo recibido e indica que sus salidas no se han regenerado.

Una nueva ejecución fallida con un registro claro es una entrega mejor que un cuaderno impecable con un historial de ejecución desconocido. Quien lo recibe necesita información suficiente para decidir en qué confiar y hasta dónde llega esa confianza.

Elige la acción adecuada de JupyterLab antes de compartir

¿Borrar las salidas, reiniciar o ejecutar todas las celdas?

El registro de comandos de JupyterLab enumera operaciones diferentes. Para borrar se utiliza notebook:clear-all-cell-outputs; para reiniciar, notebook:restart-kernel. Ejecutar todas las celdas utiliza notebook:run-all-cells, mientras que reiniciar y ejecutar utiliza notebook:restart-run-all.

Ajusta la acción a las pruebas que necesitas

El mismo registro de comandos también incluye la acción combinada de reiniciar y borrar, notebook:restart-clear-output. Un reinicio no significa automáticamente que se hayan borrado las salidas. Tampoco el nombre de un comando indica que la ejecución haya terminado correctamente.

Para realizar una comprobación secuencial con un kernel recién iniciado, elige expresamente Reiniciar el kernel y ejecutar todas las celdas. Espera a que termine la ejecución y después inspecciona las excepciones y los resultados relevantes antes de guardar. Si la ejecución falla o se detiene antes de tiempo, comunica ese resultado. Los errores guardados pueden ayudar a un colega a diagnosticar un problema; no sirven como prueba de una ejecución satisfactoria.

Aplica el procedimiento de Entrega en tres estados

Inspecciona y autoriza la nueva ejecución

Conserva el cuaderno recibido antes de editarlo. Revisa las celdas en busca de operaciones que afecten a archivos o bases de datos, y comprueba si hay solicitudes de red, datos de entrada sensibles y llamadas a servicios de pago. Las recomendaciones de seguridad de Jupyter Server dejan clara la capacidad subyacente: Jupyter permite ejecutar código arbitrario. Abrir un cuaderno no implica tener permiso para ejecutar todo lo que contiene.

Elige datos de entrada aislados y ajenos a producción, y evita los secretos activos. Si faltan dependencias o no se ha aprobado una escritura externa, mantén bloqueada la nueva ejecución y explica el motivo. No flexibilices los límites de ejecución solo para obtener un resultado satisfactorio.

Registra el contexto y ejecuta de forma deliberada

Registra la identidad del cuaderno y el kernel seleccionado. Incluye el directorio de trabajo y las versiones de las dependencias, o una especificación del entorno si está disponible. Identifica los datos de entrada y las versiones de los modelos o servicios relevantes. Marca como desconocidos los detalles que no conozcas; un nombre de archivo y un nombre de kernel son solo una pequeña parte del contexto.

Para un cuaderno que utilice Polars, la guía sobre cómo elegir entre collect y sink_parquet de Polars aborda una decisión relacionada con el archivo resultante. Un resultado en memoria y un conjunto de datos escrito son entregables distintos. Indica cuál necesita este cuaderno sin presentar la guía relacionada como una validación de su ejecución.

Las celdas que escriben en bases de datos necesitan una revisión independiente de las transacciones. La guía de DBeaver sobre Guardar frente a Confirmar explica la diferencia en un cliente de bases de datos. Lleva esa pregunta a la revisión del cuaderno: guardarlo no demuestra que una transacción de base de datos se haya confirmado o revertido de forma segura.

El siguiente flujo sirve como ayuda para planificar. No registra una ejecución observada.

Revisa, guarda por separado e indica los límites

Guarda la copia ejecutada y revisada en un destino distinto y conserva el original. Comprueba que la copia guardada sea el archivo que quieres entregar. No basta con que un comando de ejecución devuelva el control, y un fallo al guardar requiere un estado propio aunque la ejecución haya terminado.

El siguiente plan de medición registra pruebas en lugar de puntuaciones. Pregunta qué ocurrió y qué puede inspeccionar quien recibe el cuaderno, sin inventar resultados de rendimiento.

Un resumen legible por máquinas puede mantener la coherencia del registro. Este ejemplo es ilustrativo; sus marcadores de posición no son pruebas de ejecución.

{
  "framework": "three-state-handoff",
  "example_only": true,
  "source_artifact": "not-recorded",
  "execution_context": "not-recorded",
  "rerun_status": "not-recorded",
  "saved_artifact": "not-recorded",
  "limitations": ["no-execution-evidence"]
}

Sustituye un marcador de posición solo cuando tengas pruebas observadas o aportadas que lo respalden. Incluye el alcance de la nueva ejecución junto al resultado real. Si no se guardó ningún archivo ejecutado, indica expresamente esa ausencia en lugar de dejar que quien lo recibe deduzca que debe existir un archivo.

Planifica la ejecución con nbclient sin exagerar la automatización

Contexto de ejecución y política de errores

Esta sección describe un diseño de automatización basado en la documentación. No es una implementación ejecutable. Para esta guía no se ejecutó ningún cuaderno ni se instalaron dependencias. Tampoco se hicieron llamadas a API de IA.

La guía de ejecución de nbclient muestra cómo configurar NotebookClient con un kernel y un directorio de ejecución seleccionados antes de llamar a execute(). Lee sus ajustes con atención. El ejemplo timeout=600 regula la ejecución de las celdas, no la del trabajo completo. Ni kernel_name='python3' ni el directorio notebooks/ son recomendaciones universales.

La guía de gestión de errores de nbclient documenta allow_errors=False como valor predeterminado. Con allow_errors=True, la ejecución puede continuar pese a las excepciones de las celdas. Decide qué errores hacen que una entrega sea inaceptable antes de programar la automatización. Llegar a la última celda no basta, por sí solo, para dar la ejecución por válida.

Una decisión de aceptación debe distinguir entre una excepción esperada y un fallo inesperado. Si tu política permite un error, registra esa política y revisa el cuaderno resultante conforme a ella. No cambies la política de forma silenciosa después de que falle una ejecución. La entrega debe permitir que otra persona entienda la decisión sin tener que reconstruirla a partir de los registros.

Guardar la salida es una responsabilidad independiente

En el flujo de trabajo programático documentado, nbformat.write guarda el cuaderno por separado de la ejecución. Planifica un destino que conserve el original y comunica los fallos de persistencia de forma independiente. Si pretendes afirmar que la ejecución se realizó con un kernel recién iniciado, exige un kernel expresamente nuevo y bajo tu control, en lugar de darlo por supuesto.

Las recomendaciones de nbclient sobre widgets establecen otro límite útil: la ejecución no renderiza los widgets en un navegador. Por tanto, el estado almacenado de un widget no demuestra que una salida interactiva funcione en el visor previsto. Comprueba esas salidas allí o indícalas como no probadas.

Evita los errores que una nueva ejecución desde cero no puede corregir

Errores habituales en la entrega

Es fácil confundir un gráfico guardado con el resultado de una ejecución actual. Una variable de consola no documentada es más difícil de detectar, pero crea el mismo problema práctico: quien recibe el cuaderno debe adivinar cómo se produjo el resultado. Tratar Ejecutar todas las celdas como un reinicio añade otra suposición sin fundamento.

Sobrescribir el cuaderno recibido elimina el punto de comparación. Omitir las celdas fallidas oculta pruebas que necesita la siguiente persona. Conserva tanto el código fuente como un relato fiel del intento, incluso cuando el resultado sea poco ordenado.

La confianza en un cuaderno responde a otra pregunta. La documentación de JupyterLab sobre confianza trata sobre la sanitización de HTML y la visualización de salidas interactivas. Leída junto con el modelo de seguridad del servidor, explica por qué confiar en un cuaderno no aísla su código ni valida su análisis. Hacer que aparezca una salida enriquecida bloqueada no es motivo para confiar en un cuaderno desconocido sin revisarlo.

Límites de la reproducibilidad, la confianza y los servicios externos

El artículo de PLOS de 2019 Diez reglas sencillas para escribir y compartir análisis computacionales en cuadernos de Jupyter ofrece fundamentos metodológicos sobre cómo documentar dependencias, datos y pasos del análisis. Utilízalo con ese propósito. No es prueba de un lanzamiento actual del producto ni de un despliegue de Optijara.

Las referencias de investigación tienen su propio lugar en la entrega. Conservar las referencias de investigación con Zotero puede ayudar con la trazabilidad bibliográfica, mientras los cálculos y la ejecución se comprueban por separado.

Una ejecución posterior puede utilizar otras dependencias u otros datos de entrada. El estado aleatorio y los servicios externos también forman parte de la discusión sobre reproducibilidad, especialmente cuando un identificador de modelo no garantiza respuestas idénticas en el futuro. Documenta lo que sabes en lugar de prometer que el cuaderno reproducirá sus resultados en cualquier entorno.

Volver a ejecutar también tiene un coste operativo. Revisa los cargos de los servicios y la privacidad antes de ejecutar, y mantén los datos de entrada privados y las credenciales fuera del registro de entrega. Comparte el contexto restringido mediante controles de acceso aprobados. El entregable útil es un relato preciso de lo que se intentó, con contexto suficiente para evaluar el resultado y límites claros sobre lo que sigue sin probarse.