Metadata-Version: 2.4
Name: pyratatui
Version: 0.3.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Terminals
Requires-Dist: pytest >=8.0 ; extra == 'dev'
Requires-Dist: ruff >=0.6 ; extra == 'dev'
Requires-Dist: mypy >=1.11 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: Python bindings for Ratatui
Keywords: ratatui,tui,terminal,bindings
Author: pyratatui contributors
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/pyratatui/pyratatui
Project-URL: Repository, https://github.com/pyratatui/pyratatui
Project-URL: Issues, https://github.com/pyratatui/pyratatui/issues

![pyratatui banner](https://raw.githubusercontent.com/pyratatui/pyratatui/main/assets/banner.svg)

# pyratatui

Python bindings for [Ratatui](https://ratatui.rs), implemented in Rust with
[PyO3](https://pyo3.rs).

Version 0.3.0 targets Ratatui 0.30.2 and supports Python 3.10+.

## Installation

```bash
pip install pyratatui
```

Building from source requires Rust 1.88 or newer and maturin:

```bash
pip install maturin
maturin develop --release
```

## Example

```python
from pyratatui import Block, Color, Paragraph, Style, run_app


def ui(frame):
    frame.render_widget(
        Paragraph.from_string("Hello! Press q to quit.")
        .block(Block().bordered().title("Hello"))
        .style(Style().fg(Color.cyan())),
        frame.area,
    )


run_app(ui, on_key=lambda ev: ev.code == "q")
```

More examples live in `examples/`. Each one is a small runnable program:

```bash
python examples/hello_world.py
python examples/dashboard.py
```

## Patterns

`term.draw` takes a callback that receives the frame. Snapshot loop state
into default arguments so each frame renders its own tick:

```python
with Terminal() as term:
    while True:
        count = state["count"]
        term.draw(lambda frame, _count=count: render(frame, _count))
        ev = term.poll_event(timeout_ms=100)
        if ev and ev.code == "q":
            break
```

Quitting is always explicit — `run_app` stops when `on_key` returns `True`,
and manual loops break on whatever key they choose.

## API

The public API is exported from the top-level package:

```python
from pyratatui import (
    Terminal,  # terminal driver (also AsyncTerminal, run_app, run_app_async)
    Frame,  # render surface handed to the draw callback
    KeyEvent,  # keyboard events from poll_event
    Layout,
    Constraint,
    Direction,
    Alignment,
    Rect,
    Style,
    Color,
    Modifier,
    Span,
    Line,
    Text,
    Block,
    Paragraph,
    List,
    Table,
    Gauge,
    BarChart,
    Sparkline,
    Scrollbar,
    Tabs,
    Clear,
    Chart,
    Canvas,
    Map,
    Monthly,
    TextPrompt,
    TextState,
    prompt_text,  # input helpers
    Buffer,  # off-screen surface (testing)
)
```

Widgets are Ratatui's built-in set plus thin `Chart`, `Canvas`, `Map`, and
calendar (`Monthly`) bindings. Types carry docstrings, and
`python/pyratatui/_pyratatui.pyi` ships full type annotations.

## Development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
maturin develop

pytest            # Python tests (includes pty-based terminal tests)
cargo test        # Rust tests
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check
ruff check . && ruff format --check .
```

See [CONTRIBUTING.md](https://github.com/pyratatui/pyratatui/blob/main/CONTRIBUTING.md) for details.

## License

MIT — see [LICENSE](https://github.com/pyratatui/pyratatui/blob/main/LICENSE).

