Piou

Una herramienta CLI para construir hermosas interfaces de línea de comandos con validación de tipos.

Ejemplo rápido

from piou import Cli, Option
cli = Cli(description='A CLI tool')

@cli.command(cmd='foo', help='Run foo command')
def foo_main(
        bar: int = Option(help='Bar positional argument (required)'),
        baz: str = Option('-b', '--baz', help='Baz keyword argument (required)'),
        foo: str | None = Option(None, '--foo', help='Foo keyword argument'),
):
    """
    A longer description on what the function is doing.
    """
    pass

if __name__ == '__main__':
    cli.run()

Installation

pip install piou

O con uv:

uv add piou

O con conda:

conda install piou -c conda-forge

Formateador en Crudo

Por defecto, Piou utiliza Rich para una salida hermosa en la terminal. Si prefieres una salida en texto plano, puedes usar el formateador en crudo:

# Force raw output via environment variable
PIOU_FORMATTER=raw python your_cli.py --help

Documentación

La documentación completa está disponible en andarius.github.io/piou.

Características

• Experiencia de desarrollo similar a FastAPI con indicaciones de tipo
• Formateadores personalizados (basados en Rich por defecto)
• Grupos de comandos anidados / subcomandos
• Opciones derivadas para patrones reutilizables de argumentos
• Soporte para comandos asíncronos
• Validación y conversión de tipos
• Modo TUI interactivo con sugerencias de comandos e historial
• Ayuda JSON estructurada (--help-json) para herramientas y descubrimiento programático de CLI

¿Por qué Piou?

No pude encontrar una biblioteca que ofreciera:

• La misma experiencia de desarrollo que FastAPI
• Personalización de la interfaz (para construir una CLI similar a Poetry)
• Validación / conversión de tipos

Typer es la alternativa más cercana pero carece de la posibilidad de formatear la salida de forma personalizada usando librerías externas (como Rich).

Piou ofrece todas estas posibilidades y te permite definir tu propio Formateador.

Comandos Asíncronos

Los comandos pueden ser funciones async: piou detecta las corutinas y las ejecuta automáticamente, sin necesidad de asyncio.run() manual:

from piou import Cli, Option
cli = Cli(description='Async example')
@cli.command(cmd='fetch', help='Fetch data')
async def fetch(url: str = Option(help='URL to fetch')):
    import niquests
    async with niquests.AsyncSession() as client:
        r = await client.get(url)
        print(r.status_code)
if __name__ == '__main__':
    cli.run()

Esto funciona de la misma manera para los comandos dentro de grupos de comandos.

Modo TUI interactivo

Piou incluye un modo TUI (Interfaz de Usuario de Texto) interactivo opcional impulsado por Textual. Esto ofrece una experiencia rica en la terminal con sugerencias de comandos, historial y completaciones en línea.

Instalación

pip install piou[tui]
With auto-reload support for development
pip install piou[tui-reload]

Uso

Habilite el modo TUI configurando tui=True al crear su CLI:

from piou import Cli, Option
cli = Cli(description='My Interactive CLI', tui=True)
@cli.command(cmd='hello', help='Say hello')
def hello(name: str = Option(..., help='Name to greet')):
    print(f'Hello, {name}!')
if __name__ == '__main__':
    cli.run()

O mediante el indicador --tui:

python my_cli.py --tui

O mediante la variable de entorno PIOU_TUI=1:

PIOU_TUI=1 python my_cli.py

Características de la TUI

• Sugerencias de comandos: Escribe / para ver los comandos disponibles con descripciones
• Navegación de subcomandos: Usa : para navegar subcomandos (p. ej., /stats:uploads)
• Completaciones en línea: Ve marcadores de posición de argumentos mientras escribes
• Historial de comandos: Navega comandos previos con flechas arriba/abajo (persistente entre sesiones)
• Salida enriquecida: Colores ANSI y formato preservados en la salida
• Atajos de teclado:
• Tab - Confirmar sugerencia seleccionada
• Arriba/Abajo - Navegar sugerencias o historial
• Ctrl+C - Limpiar entrada (presionar dos veces para salir)
• Escape - Salir
• Modo desarrollador: Recarga automática de comandos cuando cambian archivos fuente (ver abajo)

Modo desarrollador con recarga automática

Para iterar más rápido en el desarrollo, activa el modo desarrollador para recargar automáticamente tus comandos cuando cambien los archivos fuente:

pip install piou[tui-reload]

Luego use la bandera --tui-reload:

python my_cli.py --tui-reload

O mediante variable de entorno:

PIOU_TUI_DEV=1 python my_cli.py --tui

Cuando está habilitado, Piou supervisa tus archivos fuente de comandos y los recarga automáticamente al guardar. También puedes alternar el modo de recarga en tiempo de ejecución con el comando /tui-reload.

Para ejecutar código personalizado después de cada recarga (por ejemplo, actualizar datos en caché), usa el decorador @cli.tui_on_reload:

@cli.tui_on_reload
def on_reload():
    print('Code reloaded!')

Ejemplo Avanzado: Benchmark HTTP

El modo TUI soporta montar widgets Textual personalizados para pantallas interactivas enriquecidas. Este ejemplo evalúa bibliotecas HTTP con tablas de progreso en vivo:

Vea examples/http_bench_tui.py para la implementación completa usando TuiContext y widgets personalizados.

Desarrollo

Ejecución de Pruebas

uv run pytest

Generación de Documentación

# Build docs
uv run --group docs mkdocs build
Serve locally
uv run --group docs mkdocs serve

Generación de capturas de pantalla y GIFs

Las grabaciones de terminal se crean con VHS. Instálalo primero:

# Ubuntu/Debian
sudo apt install vhs ttyd
macOS
brew install vhs
Or via Go
go install github.com/charmbracelet/vhs@latest

Luego genere grabaciones a partir de archivos de cinta:

vhs docs/static/tui-demo.tape

Los archivos de cinta se encuentran en docs/static/ y definen sesiones de terminal guionizadas que producen GIFs.

--- Tranlated By Open Ai Tx | Last indexed: 2026-05-31 ---