Metadata-Version: 2.4
Name: griphtui
Version: 0.2.0
Summary: Clack-style terminal UI primitives for prompt-first Python TUIs.
Project-URL: Homepage, https://github.com/bhark/griphTUI
Project-URL: Repository, https://github.com/bhark/griphTUI
Project-URL: Issues, https://github.com/bhark/griphTUI/issues
Author-email: "Adrian E. Bratlann" <adrian@forn.dk>
License-Expression: MIT
License-File: LICENSE
Keywords: clack,cli,interactive,prompt,rich,terminal,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Terminals
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: rich>=15.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=1.3; extra == 'dev'
Requires-Dist: pytest>=9.0; extra == 'dev'
Description-Content-Type: text/markdown

# griphTUI

Minimal and ergonomic Clack-style terminal UI primitives for Python CLIs/TUIs.

![PyPI - Version](https://img.shields.io/pypi/v/griphtui) ![PyPI - Downloads](https://img.shields.io/pypi/dm/griphtui)


## Install

```bash
uv add griphtui
```

## The basics

GriphTUI is heavily inspired by [Clack](https://github.com/bombshell-dev/clack/tree/main/packages/prompts), and follows many of the same basic principles.

You'll probably want to begin with an intro:

```python
import griphtui as gtui

gtui.intro("The grand survey")
```

...after which you can employ a range of primitives to prompt the user:

```python
# section header
gtui.section("Let's talk about trains")

# text input
gtui.text("What's your favorite train?")

# select
gtui.select(
    "Can this train drift?",
    [("Probably", "probably"), ("Definitely", "definitely")]
)

# multiselect
gtui.multiselect(
    "Which of the following applies to your favorite train?",
    [
        ("I wish it could drift", "wish", True), # toggled on by default
        ("I'm sad that it can't drift", "sadness", False),
        ("It's really nice that it can drift", "happiness", False)
    ]
)

# multiselect with rules
gtui.multiselect(
    "Pick your stack",
    [
        gtui.Option("Core", "core"),
        gtui.Option("Analytics", "analytics", requires={"core"}),
        gtui.Option("Legacy mode", "legacy", excludes={"core"}),
    ]
)

# spinners
with gtui.spinner("Preparing for ethical dilemmas...") as s:
    time.sleep(1)
    s.update("Installing drift capabilities...")
    time.sleep(1)
    s.update("Updating Terms of Use...")
    time.sleep(1)
    s.done("Drift ready")  # leaves a [+] success line on exit
    # on exception, s.fail("message") leaves a [!] error line instead

# status messages
gtui.warn("Aristoteles disliked this") # info, step, success, warn or error
```

Finally, wrap up with an outro:

```python
gtui.outro("That's all, folks!")
```

There's a bit more available, eg. input validation. See the [example](/examples/tour.py) if you want to dive deeper.

## API

| Function | Purpose |
| --- | --- |
| `intro(title)` / `outro(msg)` / `section(title)` | frames |
| `note(message, title=...)` | multi-line block (e.g. a confirmation summary) |
| `text(label, default="")` | single-line input |
| `password(label, mask="·")` | masked input; `mask=""` hides length entirely |
| `confirm(label, default=True)` | y/n prompt |
| `select(label, options)` | single-choice picker; `Option(..., disabled=True)` skips navigation |
| `multiselect(label, options)` | multi-choice picker with optional `requires` / `excludes` rules; `Option(..., disabled=True)` is un-toggleable |
| `spinner(label)` | threaded spinner context manager; `.done()` / `.fail()` leave a final status line |
| `info` / `step` / `success` / `warn` / `error` | prefixed status lines |

All prompts accept an optional `console=` kwarg if you want to inject your own Rich `Console`.

When `multiselect()` rules are used, referenced option values must be unique.

## Platforms

Linux, macOS, and Windows (uses `msvcrt` for raw input on Windows, `termios`/`tty` elsewhere).
