Piou

タイプ検証付きで美しいコマンドラインインターフェースを構築するCLIツール。

クイック例

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

またはuvを使用して：

uv add piou

またはcondaで：

conda install piou -c conda-forge

Raw Formatter

デフォルトでは、Piouは美しいターミナル出力のためにRichを使用します。プレーンテキスト出力を好む場合は、rawフォーマッターを使用できます。

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

ドキュメント

完全なドキュメントは andarius.github.io/piou で利用可能です。

特徴

• FastAPIのような開発者体験と型ヒント
• カスタムフォーマッター（デフォルトはRichベース）
• ネストされたコマンドグループ / サブコマンド
• 再利用可能な引数パターンのための派生オプション
• 非同期コマンド対応
• 型の検証とキャスト
• コマンド提案と履歴機能付きの対話型TUIモード
• ツールやプログラム的なCLI発見のための構造化JSONヘルプ (--help-json)

なぜPiouなのか？

私は以下を提供するライブラリを見つけられませんでした：

• FastAPI と同じ開発者体験
• インターフェースのカスタマイズ（Poetryに似たCLIを構築するため）
• 型の検証 / キャスト

Typer は最も近い代替ですが、外部ライブラリ（Richなど）を使って出力をカスタムフォーマットする機能が欠けています。

Piou はこれらすべての可能性を提供し、独自のフォーマッターを定義できます。

非同期コマンド

コマンドは async 関数にでき、piouはコルーチンを検出して自動的に実行します。手動での asyncio.run() は不要です：

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()

これはコマンドグループ内のコマンドでも同様に動作します。

インタラクティブTUIモード

PiouにはTextualを利用したオプションのインタラクティブTUI（テキストユーザーインターフェース）モードが含まれています。 これにより、コマンドの候補表示、履歴、インライン補完を備えた豊富なターミナル体験が提供されます。

インストール

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

使用方法

CLIを作成するときにtui=Trueを設定してTUIモードを有効にします：

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()

または --tui フラグを使用して:

python my_cli.py --tui

または PIOU_TUI=1 環境変数を使用して：

PIOU_TUI=1 python my_cli.py

TUIの機能

• コマンドの提案: / を入力して利用可能なコマンドと説明を表示
• サブコマンドのナビゲーション: : を使ってサブコマンドを移動（例: /stats:uploads）
• インライン補完: 入力中に引数のプレースホルダーを表示
• コマンド履歴: 上下矢印で過去のコマンドを移動（セッション間で保持）
• リッチ出力: ANSIカラーとフォーマットを出力で保持
• キーボードショートカット:
• Tab - 選択中の提案を確定
• Up/Down - 提案または履歴を移動
• Ctrl+C - 入力をクリア（2回押すと終了）
• Escape - 終了
• 開発モード: ソースファイルの変更時にコマンドを自動リロード（以下参照）

自動リロード付き開発モード

より速い開発サイクルのために、開発モードを有効にするとソースファイルの変更時にコマンドが自動でリロードされます：

pip install piou[tui-reload]

次に --tui-reload フラグを使用します：

python my_cli.py --tui-reload

または環境変数を介して:

PIOU_TUI_DEV=1 python my_cli.py --tui

有効にすると、Piouはコマンドのソースファイルを監視し、保存時にホットリロードします。実行時に /tui-reload コマンドでリロードモードを切り替えることもできます。

リロード後にカスタムコードを実行するには（例：キャッシュデータの更新）、@cli.tui_on_reload デコレータを使用してください：

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

高度な例：HTTPベンチマーク

TUIモードはリッチなインタラクティブ表示のためにカスタムTextualウィジェットのマウントをサポートします。この例ではライブ進行グリッドでHTTPライブラリをベンチマークします：

TuiContextとカスタムウィジェットを使用した完全な実装はexamples/http_bench_tui.pyを参照してください。

開発

テストの実行

uv run pytest

ドキュメントの生成

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

スクリーンショットとGIFの生成

ターミナルの録画はVHSで作成されます。まずはインストールしてください：

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

次に、テープファイルから録音を生成します：

vhs docs/static/tui-demo.tape

テープファイルは docs/static/ にあり、GIFを生成するスクリプト化された端末セッションを定義しています。

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