feat: funciones Jupyter notebook Python — discover, read, write, exec, kernel

Funciones Python para interactuar con Jupyter Lab programáticamente: descubrir instancias, leer/escribir celdas, ejecutar código y gestionar kernels. Reemplazan MCP jupyter con API REST + WebSocket directa. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-01 20:55:39 +02:00
parent dc78d8fea3
commit 268a76602a
11 changed files with 1956 additions and 0 deletions
@@ -0,0 +1,94 @@
+---
+name: jupyter_exec
+kind: function
+lang: py
+domain: notebook
+version: "1.0.0"
+purity: impure
+signature: "jupyter_append_execute(notebook_path: str, code: str, server_url: str, token: str) -> dict"
+description: "Ejecuta codigo en kernels de Jupyter via WebSocket. Tres modos: append (añade celda al notebook y la ejecuta), cell (ejecuta celda existente por indice), kernel (ejecuta en el kernel sin tocar ningun notebook)."
+tags: [jupyter, notebook, kernel, websocket, execution, cells]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: [jupyter_kernel_client, jupyter_nbmodel_client]
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/notebook/jupyter_exec.py"
+---
+
+## Funciones
+
+### `jupyter_append_execute(notebook_path, code, server_url, token)`
+
+Añade una celda de codigo al final del notebook y la ejecuta. Usa el protocolo
+colaborativo de Jupyter, por lo que tanto el agente como el usuario ven la celda
+y su output en tiempo real en JupyterLab.
+
+```python
+from notebook.jupyter_exec import jupyter_append_execute
+
+result = jupyter_append_execute(
+    "notebooks/analisis.ipynb",
+    "import pandas as pd\nprint(pd.__version__)",
+    server_url="http://localhost:8888",
+    token="",
+)
+# {"cell_index": 5, "outputs": ["2.2.1"]}
+```
+
+### `jupyter_execute_cell(notebook_path, cell_index, server_url, token)`
+
+Ejecuta una celda existente del notebook por su indice (0-based).
+
+```python
+from notebook.jupyter_exec import jupyter_execute_cell
+
+result = jupyter_execute_cell("notebooks/analisis.ipynb", 3)
+# {"cell_index": 3, "outputs": ["42"]}
+```
+
+### `jupyter_kernel_execute(code, server_url, token)`
+
+Ejecuta codigo directamente en el kernel sin modificar ningun notebook. Util para
+consultas rapidas, inspeccion de variables o verificacion de estado del kernel.
+
+```python
+from notebook.jupyter_exec import jupyter_kernel_execute
+
+result = jupyter_kernel_execute("len(df)")
+# {"outputs": ["1500"], "status": "ok"}
+```
+
+## CLI
+
+```bash
+# Añadir celda y ejecutar
+python -m notebook.jupyter_exec append notebooks/mi.ipynb "print('hola')" --server http://localhost:8888 --token mytoken
+
+# Ejecutar celda existente
+python -m notebook.jupyter_exec cell notebooks/mi.ipynb 2 --server http://localhost:8888
+
+# Ejecutar en kernel directamente
+python -m notebook.jupyter_exec kernel "x = 42; print(x)"
+```
+
+Output siempre JSON. En error retorna `{"error": "..."}` por stderr con exit code 1.
+
+## Extraccion de outputs
+
+| output_type | campo leido |
+|---|---|
+| stream | `text` |
+| display_data / execute_result | `data.text/plain` |
+| error | `traceback` (joined con `\n`) |
+
+## Notas
+
+- Las funciones `append` y `cell` son async internamente; las publicas usan `asyncio.run()`.
+- `jupyter_kernel_execute` es sincrona directamente porque `KernelClient.execute` es bloqueante.
+- El token puede ser cadena vacia si el servidor tiene autenticacion deshabilitada.
+- `NbModelClient` requiere que el servidor tenga habilitado el endpoint colaborativo (`/api/collaboration/`), disponible en JupyterLab >= 4 con `jupyter-collaboration` instalado.