notebook-terminal 0.3.2

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

Notebook Terminal 0.3.1

A cross-platform PTY/ConPTY terminal embedded directly in Jupyter with bundled xterm.js.

Author: Robert Zawadzki
GitHub: ZawadzkiR
Repository: github.com/ZawadzkiR/notebook-terminal

Key features

• real Bash/Zsh/CMD/PowerShell prompt from the current user account;
• Linux PTY and Windows ConPTY support;
• bundled xterm.js, FitAddon and WebLinksAddon;
• no anywidget, custom JupyterLab extension, administrator installation, CDN, HTTP server, iframe or WebSocket required in Jupyter;
• offline operation after wheel installation;
• ordered and batched byte transport preserving ANSI sequences and split UTF-8 characters;
• automatic repair after scrolling away from the terminal, switching tabs, resizing panels or restoring the browser window;
• standard ipywidgets transport compatible with JupyterLab environments where ordinary widgets already work;
• optional rich tabs for DataFrames, HTML, images, Matplotlib and Plotly;
• Flask and Django adapters.

Installation

python -m pip install notebook\_terminal-0.3.1-py3-none-any.whl

Restart the kernel after replacing an older version.

Basic usage

from notebook\_terminal import terminal

term = terminal(
    height=450,
    interactive=True,
    scrollback=10000,
)

The prompt, username, host and working directory are produced by the actual shell process. No account name or path is hardcoded.

term.run("ls -la")                 # Linux/macOS
term.run("Get-ChildItem")          # PowerShell
term.run("python --version")
term.interrupt()
term.clear()
term.focus()

Python execution

term.run\_python("print('hello from Python')")
term.run\_python\_file("script.py", args=\["--verbose"])

Rich output:

term.run\_python("""
import pandas as pd
import matplotlib.pyplot as plt

df = pd.DataFrame({"x": \[1, 2, 3], "y": \[2, 4, 8]})
display(df)
plt.plot(df\["x"], df\["y"])
plt.show()
""", rich\_output=True)

Terminal resizing and notebook scrolling

Version 0.3.1 protects xterm.js from fitting while its notebook output is hidden or temporarily measured at a near-zero width. It observes:

• container size changes;
• return to the browser viewport;
• Jupyter panel and tab visibility changes;
• browser resize, page restore and visibility changes;
• notebook scrolling.

When the terminal becomes visible again, it performs a debounced multi-pass refit, refreshes the renderer, restores the viewport width and sends the corrected rows and columns to PTY/ConPTY. This prevents the terminal from collapsing into a narrow strip after scrolling away and returning.

Linux newlines

convertEol is enabled so output containing LF (\\n) starts from the first column of the next line rather than drifting to the right.

Requirements

• Python 3.9 or newer;
• IPython 8 or newer;
• ipywidgets 8.1 or newer;
• a trusted notebook that permits JavaScript output;
• on Windows: pywinpty>=3.0.0.

Compatibility target

• JupyterLab 4.x with working standard ipywidgets;
• classic Notebook environments supporting ipywidgets;
• Linux PTY;
• Windows ConPTY through pywinpty.

Development

python -m pip install -e ".\[dev]"
pytest
python -m build
python -m twine check dist/\*

License

MIT. See LICENSE.