Metadata-Version: 2.4
Name: notebook-terminal
Version: 0.3.2
Summary: A cross-platform PTY/ConPTY terminal for Jupyter with bundled xterm.js
Author: Robert Zawadzki
License: MIT
Project-URL: Homepage, https://github.com/ZawadzkiR/notebook-terminal
Project-URL: Repository, https://github.com/ZawadzkiR/notebook-terminal
Project-URL: Issues, https://github.com/ZawadzkiR/notebook-terminal/issues
Project-URL: Changelog, https://github.com/ZawadzkiR/notebook-terminal/blob/main/CHANGELOG.md
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ipywidgets>=8.1
Requires-Dist: ipython>=8
Requires-Dist: traitlets>=5
Requires-Dist: jupyterlab_widgets<4,>=3.0
Requires-Dist: widgetsnbextension<5,>=4.0
Requires-Dist: pywinpty>=3.0.0; platform_system == "Windows"
Provides-Extra: flask
Requires-Dist: Flask>=2.3; extra == "flask"
Requires-Dist: flask-sock>=0.7; extra == "flask"
Provides-Extra: django
Requires-Dist: Django>=4.2; extra == "django"
Requires-Dist: channels>=4; extra == "django"
Provides-Extra: plotly
Requires-Dist: plotly>=5; extra == "plotly"
Provides-Extra: data
Requires-Dist: pandas>=1.5; extra == "data"
Requires-Dist: matplotlib>=3.6; extra == "data"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# Notebook Terminal 0.3.1

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

**Author:** Robert Zawadzki  
**GitHub:** [ZawadzkiR](https://github.com/ZawadzkiR)  
**Repository:** [github.com/ZawadzkiR/notebook-terminal](https://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

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

Restart the kernel after replacing an older version.

## Basic usage

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

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

## Python execution

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

Rich output:

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

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

## License

MIT. See `LICENSE`.

