Trogon

0.6.0 · active · verified Thu Apr 16

Trogon is a Python library that automatically generates a Textual User Interface (TUI) for your Click Command Line Interface (CLI) applications. It inspects the Click app's schema to build an interactive TUI, offering an intuitive way to interact with complex CLIs. It also has experimental support for Typer. The project is actively developed by Textualize, and the current version is 0.6.0. While there isn't a strict time-based release cadence, new versions are released to address bug fixes and introduce new features.

Common errors

```
TypeError: 'NoneType' object is not subscriptable (often traced to detect_run_string.py on Windows)
```
cause Trogon's internal mechanism for detecting the run string, specifically `Py_GetArgcArgv` from `ctypes`, can fail on certain Windows environments, particularly with Python 3.8.10.

fix Upgrade Python to a newer 3.x version (e.g., 3.9+) or use a Linux/WSL environment. This issue is less prevalent in later Python versions or non-Windows OS.
```
Trogon with standalone_mode of click is not working (e.g., when calling cli(standalone_mode=False))
```
cause Trogon expects Click applications to run in their default `standalone_mode=True`. Explicitly setting `standalone_mode=False` when invoking the Click command can interfere with Trogon's introspection and execution.

fix Do not explicitly set `standalone_mode=False` when Trogon is wrapping your Click application. Allow Click to run in its default `standalone_mode` when `trogon` is the entry point.
```
ImportError: cannot import name 'tui' from 'trogon.cli'
```
cause Attempting to import the `tui` decorator from an incorrect submodule path, possibly based on outdated examples or assumptions.

fix The correct import path for the `tui` decorator is directly from the `trogon` package: `from trogon import tui`.

Warnings

breaking Older versions of Trogon (pre-0.6.0) may experience layout issues or incompatibilities with Textual versions 0.54 and newer.
Fix: Upgrade Trogon to version 0.6.0 or later to ensure compatibility with Textual 0.54+. Ensure your Textual dependency is also up-to-date.
gotcha Using interactive prompts (e.g., `click.prompt()` or `rich.Prompt.ask()`) within a Click command wrapped by Trogon can lead to visual glitches and input issues, where the system command prompt interweaves with the TUI.
Fix: Avoid using interactive prompts directly within Trogon-wrapped Click commands. Instead, leverage Trogon's generated input fields for arguments and options, or provide all necessary arguments directly when launching the command from within the TUI.
gotcha Trogon has known issues with handling `click.option` of `type=bool` and can pass boolean values as strings instead of native Python booleans to the underlying Click command.
Fix: As of now, this is an open bug. A potential workaround might involve explicitly converting the string representation of boolean options (e.g., 'True', 'False') to actual `bool` types within your Click command function, or waiting for an official fix in future Trogon releases.
deprecated There is an open issue regarding `click.BaseCommand` deprecation warnings when using Trogon.
Fix: Monitor Trogon's GitHub issues for updates and official fixes. Ensure your Click library is also up to date, as newer Click versions might handle deprecations differently.

Install

pip install trogon Install latest version

Imports

tui
wrong:
```
from trogon.cli import tui
```
correct:
```
from trogon import tui
```
The `tui` decorator is directly available from the top-level `trogon` package. Older examples or common misconceptions might lead to importing from a non-existent `cli` submodule.
init_tui
```
from trogon.typer import init_tui
```
Used for integrating Trogon with Typer applications, introduced in v0.6.0. This import is specific to Typer CLIs.

Quickstart

This quickstart demonstrates how to add a Trogon TUI to a basic Click CLI. By adding the `@tui()` decorator to your Click group or command, Trogon automatically generates a TUI accessible via a new `tui` subcommand. Users can then run `python your_cli_file.py tui` to launch the interactive interface.

import click
from trogon import tui

@tui()
@click.group()
def cli():
    """A simple CLI with Trogon."""
    pass

@cli.command()
@click.option("--name", default="World", help="The name to greet.")
def hello(name):
    """Greets a name."""
    click.echo(f"Hello {name}!")

@cli.command()
@click.argument("num1", type=int)
@click.argument("num2", type=int)
def add(num1, num2):
    """Adds two numbers."""
    click.echo(f"The sum is: {num1 + num2}")

if __name__ == "__main__":
    # To run the TUI: python your_cli_file.py tui
    # To run the CLI: python your_cli_file.py hello --name Alice
    cli()

view raw JSON →