fn_registry/python/functions/notebook/jupyter_kernel.md

---
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 ocho operaciones: list, start, restart, interrupt, shutdown, sessions, cleanup y shutdown-all. Usa solo stdlib (urllib, json), sin dependencias externas."
tags: [jupyter, notebook, kernel, api, http, rest, sessions, crud, cleanup]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [json, urllib.error, urllib.request]
output: "Múltiples funciones para CRUD de kernels: list, start, restart, interrupt, shutdown, sessions (retornan dicts con metadatos)"
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 |
| `jupyter_kernel_cleanup(server_url, token, idle_seconds)` | `GET + DELETE` | Apaga kernels inactivos |
| `jupyter_kernel_shutdown_all(server_url, token)` | `GET + DELETE` | Apaga todos los kernels |

## 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

# Limpiar kernels inactivos (default: 1h sin actividad)
python python/functions/notebook/jupyter_kernel.py cleanup --idle-seconds 1800

# Apagar todos los kernels
python python/functions/notebook/jupyter_kernel.py shutdown-all
```

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`.