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,136 @@
+---
+name: jupyter_kernel
+kind: function
+lang: py
+domain: notebook
+version: "1.0.0"
+purity: impure
+signature: "def jupyter_kernel_list(server_url: str = \"http://localhost:8888\", token: str = \"\") -> list[dict]"
+description: "CRUD completo de kernels Jupyter via REST API. Expone seis operaciones: list, start, restart, interrupt, shutdown y sessions. Usa solo stdlib (urllib, json), sin dependencias externas."
+tags: [jupyter, notebook, kernel, api, http, rest, sessions, crud]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: [json, urllib.error, urllib.request]
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/notebook/jupyter_kernel.py"
+---
+
+## Funciones expuestas
+
+| Funcion | Endpoint | Descripcion |
+|---------|----------|-------------|
+| `jupyter_kernel_list(server_url, token)` | `GET /api/kernels` | Lista kernels activos |
+| `jupyter_kernel_start(server_url, token, name)` | `POST /api/kernels` | Inicia un kernel nuevo |
+| `jupyter_kernel_restart(server_url, token, kernel_id)` | `POST /api/kernels/{id}/restart` | Reinicia un kernel |
+| `jupyter_kernel_interrupt(server_url, token, kernel_id)` | `POST /api/kernels/{id}/interrupt` | Interrumpe ejecucion |
+| `jupyter_kernel_shutdown(server_url, token, kernel_id)` | `DELETE /api/kernels/{id}` | Apaga y elimina un kernel |
+| `jupyter_kernel_sessions(server_url, token)` | `GET /api/sessions` | Lista sesiones activas |
+
+## Ejemplo
+
+```python
+from notebook.jupyter_kernel import (
+    jupyter_kernel_list,
+    jupyter_kernel_start,
+    jupyter_kernel_restart,
+    jupyter_kernel_interrupt,
+    jupyter_kernel_shutdown,
+    jupyter_kernel_sessions,
+)
+
+# Listar kernels activos
+kernels = jupyter_kernel_list("http://localhost:8888", token="mi_token")
+# [{"id": "abc123", "name": "python3", "execution_state": "idle",
+#   "last_activity": "2026-04-01T10:00:00.000Z", "connections": 1}]
+
+# Iniciar un kernel nuevo
+kernel = jupyter_kernel_start("http://localhost:8888", token="mi_token", name="python3")
+# {"id": "def456", "name": "python3", "execution_state": "starting"}
+
+# Reiniciar
+jupyter_kernel_restart("http://localhost:8888", "mi_token", kernel["id"])
+
+# Interrumpir ejecucion en curso
+jupyter_kernel_interrupt("http://localhost:8888", "mi_token", kernel["id"])
+
+# Apagar
+jupyter_kernel_shutdown("http://localhost:8888", "mi_token", kernel["id"])
+
+# Listar sesiones (mapeo notebook <-> kernel)
+sessions = jupyter_kernel_sessions("http://localhost:8888", token="mi_token")
+# [{"id": "s1", "notebook": "notebooks/01_analisis.ipynb",
+#   "kernel_id": "abc123", "kernel_state": "idle", "type": "notebook", "name": "01_analisis"}]
+```
+
+## CLI
+
+```bash
+# Listar kernels
+python python/functions/notebook/jupyter_kernel.py list --server http://localhost:8888 --token TK
+
+# Iniciar kernel (por defecto python3)
+python python/functions/notebook/jupyter_kernel.py start --name python3
+
+# Reiniciar
+python python/functions/notebook/jupyter_kernel.py restart abc123-...
+
+# Interrumpir
+python python/functions/notebook/jupyter_kernel.py interrupt abc123-...
+
+# Apagar
+python python/functions/notebook/jupyter_kernel.py shutdown abc123-...
+
+# Listar sesiones
+python python/functions/notebook/jupyter_kernel.py sessions
+```
+
+Todos los subcomandos aceptan `--server` y `--token`. El output es siempre JSON.
+
+## Estructura de los dicts retornados
+
+**`jupyter_kernel_list`** — cada elemento:
+```python
+{
+    "id": "abc123-...",
+    "name": "python3",
+    "execution_state": "idle",   # idle | busy | starting
+    "last_activity": "2026-04-01T10:00:00.000Z",
+    "connections": 1
+}
+```
+
+**`jupyter_kernel_start`** — elemento retornado:
+```python
+{
+    "id": "def456-...",
+    "name": "python3",
+    "execution_state": "starting"
+}
+```
+
+**`jupyter_kernel_sessions`** — cada elemento:
+```python
+{
+    "id": "session-id",
+    "notebook": "notebooks/01_analisis.ipynb",  # path relativo al root del servidor
+    "kernel_id": "abc123-...",
+    "kernel_state": "idle",
+    "type": "notebook",
+    "name": "01_analisis"
+}
+```
+
+## Notas
+
+Solo usa stdlib: `urllib.request`, `urllib.error`, `json`. No requiere `requests`, `jupyter_client` ni ningun paquete externo.
+
+La funcion interna `_make_request` centraliza la construccion de headers y serializacion JSON. El header `Authorization: token {token}` se omite si `token` esta vacio, permitiendo conectar a servidores sin autenticacion.
+
+`jupyter_kernel_interrupt` y `jupyter_kernel_shutdown` retornan `None` porque la API de Jupyter devuelve 204 No Content en esos casos.
+
+Compatible con Jupyter Lab 3.x, 4.x y Jupyter Notebook 6.x/7.x — todos exponen la misma REST API en `/api/kernels` y `/api/sessions`.