notebook-terminal 0.4.0

A cross-platform PTY/ConPTY terminal for Jupyter with bundled xterm.js

notebook-terminal 0.4.0

Cross-platform PTY/ConPTY terminal for JupyterLab with bundled xterm.js. It works locally on Windows and Linux and can also connect to a terminal on a remote JupyterHub/Jupyter Server using its REST API and terminal WebSocket endpoint.

Repository: https://github.com/ZawadzkiR/notebook-terminal

Local terminal

from notebook_terminal import terminal

term = terminal(height=450, scrollback=10_000)
term.run("python --version")

The prompt is produced by the real shell of the current user. It is not hard-coded.

Remote JupyterHub terminal

import os
from notebook_terminal import remote_terminal

term = remote_terminal(
    hub_url="https://jupyter.example.com",
    username="robert",
    token=os.environ["JUPYTERHUB_TOKEN"],
)

term.run("hostname")
term.run("pwd")
term.run("ls -la")

You can also provide the URL of the single-user Jupyter Server directly:

term = remote_terminal(
    server_url="https://jupyter.example.com/user/robert/",
    token=os.environ["JUPYTERHUB_TOKEN"],
)

Equivalent unified API:

term = terminal(
    backend="jupyterhub",
    server_url="https://jupyter.example.com/user/robert/",
    token=os.environ["JUPYTERHUB_TOKEN"],
)

The remote backend:

1. creates a terminal with POST /api/terminals;
2. opens wss://.../terminals/websocket/<name>;
3. forwards xterm input as stdin messages;
4. forwards remote stdout messages to xterm.js;
5. synchronizes rows and columns with set_size;
6. removes the created terminal on close by default.

To attach to an existing terminal:

term = remote_terminal(
    server_url="https://jupyter.example.com/user/robert/",
    token=os.environ["JUPYTERHUB_TOKEN"],
    terminal_name="1",
    create_terminal=False,
    delete_on_close=False,
)

For a named JupyterHub server:

term = remote_terminal(
    hub_url="https://jupyter.example.com",
    username="robert",
    server_name="gpu",
    token=os.environ["JUPYTERHUB_TOKEN"],
)

TLS

Keep certificate verification enabled. For a private CA, provide its certificate bundle:

term = remote_terminal(
    server_url="https://jupyter.example.com/user/robert/",
    token=os.environ["JUPYTERHUB_TOKEN"],
    verify_ssl="/path/company-ca.pem",
)

verify_ssl=False exists for controlled testing only.

Token security

Do not put the token directly in a notebook that will be committed or shared. Use an environment variable, keyring, or another secret store. A token with terminal access can execute commands with your remote account permissions.

By default the token is sent in the Authorization: token ... header. allow_token_in_url=True is available only for unusual proxies that reject authorization headers on WebSocket upgrades, because query-string tokens are easier to leak.

Remote limitations

• The remote user server must already be running and reachable over HTTPS/WSS.
• The token must be allowed to access the single-user server.
• The administrator or reverse proxy may disable terminals or WebSockets.
• run_python_file() interprets its path as a path on the remote server.
• Rich-output capture is currently local-only. Use normal terminal output remotely.

Python file arguments

term.run_python_file(
    "train.py",
    args=["dataset.csv"],
    kwargs={"epochs": 20, "verbose": True},
)

This runs:

python train.py dataset.csv --epochs 20 --verbose

Installation

python -m pip install notebook_terminal-0.4.0-py3-none-any.whl

Restart the kernel and refresh JupyterLab after replacing an earlier version.

Optional integrations

pip install "notebook-terminal[flask]"
pip install "notebook-terminal[django]"
pip install "notebook-terminal[data,plotly]"

License

MIT