<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/Andarius/piou/raw/master/docs/static/piou-dark.png">
<source media="(prefers-color-scheme: light)" srcset="https://github.com/Andarius/piou/raw/master/docs/static/piou.jpg">
<img alt="Piou logo"
src="https://github.com/Andarius/piou/raw/master/docs/static/piou.jpg"
width="250"/>
</picture>
Piou
Python versions
Latest PyPI version
CI
Latest conda-forge version
타입 유효성 검사를 통해 아름다운 명령줄 인터페이스(CLI)를 구축하는 도구입니다.
빠른 예제 (Quick Example)
from piou import Cli, Option
cli = Cli(description="A CLI tool")
...
example
설치 방법 (Installation)
또는 uv:
또는 conda:
conda install piou -c conda-forge
기본적으로 Piou는 아름다운 터미널 출력을 위해 Rich를 사용합니다. 일반 텍스트 출력을 선호하는 경우, raw formatter를 사용할 수 있습니다:
PIOU_FORMATTER=raw python your_cli.py --help
문서화 (Documentation)
전체 문서는 **andarius.github.io/piou**에서 확인할 수 있습니다.
기능 (Features)
- 타입 힌트가 적용된 FastAPI와 유사한 개발자 경험
- 사용자 지정 포매터 (기본값은 Rich 기반)
- 중첩된 명령어 그룹 / 하위 명령어
- 재사용 가능한 인자 패턴을 위한 파생 옵션(Derived options)
- 비동기 명령어 지원 (Async command support)
- 타입 유효성 검사 및 캐스팅
- 대화형 TUI 모드: 명령어 제안 및 히스토리 기능 제공
- 구조화된 JSON 도움말 (
--help-json): 도구 및 프로그램적 CLI 검색용
- bash, zsh, fish를 위한 쉘 자동 완성(Shell completion) (
--completions)
Piou를 사용해야 하는 이유 (Why Piou?)
저는 다음 기능을 제공하는 라이브러리를 찾지 못했습니다:
- FastAPI와 동일한 개발자 경험
- 인터페이스 사용자 정의(Poetry와 유사한 CLI 구축 가능)
- 타입 검증/캐스팅
Typer가 가장 근접한 대안이지만, 외부 라이브러리(예: Rich)를 사용하여 출력을 사용자 정의 방식으로 포맷할 수 있는 기능이 부족합니다.
Piou는 이러한 모든 가능성을 제공하며, 자체 포매터(Formatter)를 정의할 수 있게 해줍니다.
비동기 명령어 (Async Commands)
명령어는 async 함수가 될 수 있습니다—piou는 코루틴을 감지하고 자동으로 실행하므로, 수동으로 asyncio.run()을 호출할 필요가 없습니다:
from piou import Cli, Option
cli = Cli(description="Async example")
...
이 방식은 명령 그룹 내의 명령어에도 동일하게 적용됩니다.
셸 완성 (Shell Completion)
모든 piou CLI는 bash, zsh 및 fish에서 명령어, 옵션 및 Literal/정적 선택지를 완성할 수 있으며, 도움말 텍스트는 zsh와 fish에서는 설명으로 표시됩니다. 셸 설정에 한 줄을 추가하십시오 (my-cli가 설치된 스크립트 이름이라고 가정):
source <(my-cli --completions bash)
source <(my-cli --completions zsh)
my-cli --completions fish | source
완성 기능은 동적입니다: <TAB> 키를 누르면 셸이 _PIOU_COMPLETE=<shell>을 사용하여 CLI를 다시 실행하며, 이는 명령어를 실행하는 대신 후보 목록을 출력합니다. 명령어 본문은 절대 실행되지 않습니다. 스크립트는 실행 중인 스크립트 이름으로 등록됩니다; 래퍼(wrapper), 별칭(alias) 또는 python -m을 통해 호출할 때는 다른 이름을 전달하십시오 (my-cli --completions zsh my-alias). Python에서는, cli.completion_script("zsh", prog="my-cli")가 동일한 스크립트를 반환합니다.
호출 가능한 choices는 매번 <TAB> 키를 누를 때 실행되므로, 기본적으로 비활성화되어 있습니다. 비용이 적게 드는 경우에는 Cli(complete_dynamic_choices=True)로 활성화하거나, 사용자별로 export PIOU_COMPLETE_DYNAMIC=1을 사용하십시오 (명시적인 complete_dynamic_choices=가 환경 변수보다 우선합니다). 실패하는 choices 함수는 후보 목록을 제공하지 않습니다.
대화형 TUI 모드 (Interactive TUI Mode)
Piou는 Textual을 기반으로 하는 선택적 대화형 TUI (Text User Interface) 모드를 포함합니다. 이는 명령어 제안, 기록(history), 인라인 자동 완성 기능을 갖춘 풍부한 터미널 경험을 제공합니다.
설치 (Installation)
pip install piou[tui]
...
사용법 (Usage)
CLI를 생성할 때 tui=True로 설정하여 TUI 모드를 활성화합니다:
from piou import Cli, Option
cli = Cli(description="My Interactive CLI", tui=True)
...
또는 --tui 플래그를 통해:
또는 PIOU_TUI=1 환경 변수를 통해:
PIOU_TUI=1 python my_cli.py
TUI 기능 (TUI Features)
- 명령어 제안:
/를 입력하여 사용 가능한 명령어와 설명을 확인하세요.
- 하위 명령어 탐색:
:를 사용하여 하위 명령어를 탐색합니다 (예: /stats:uploads).
- 인라인 자동 완성: 타이핑하는 동안 인수 자리 표시자(argument placeholders)가 표시됩니다.
- 명령어 기록: 위/아래 화살표를 사용하여 이전 명령어들을 탐색할 수 있습니다 (세션 간 유지됨).
- 풍부한 출력: ANSI 색상 및 서식이 출력에 보존됩니다.
- 키보드 단축키:
Tab: 선택된 제안을 확정합니다.Up/Down: 제안 또는 기록을 탐색합니다.Ctrl+C: 입력을 지웁니다 (종료하려면 두 번 누르세요).Escape: 종료합니다.
- 개발자 모드(Dev mode): 소스 파일이 변경될 때 명령어를 자동 재로드합니다 (아래 참조)
<img alt="TUI Demo" src="https://github.com/Andarius/piou/raw/master/docs/static/tui-demo.gif" width="600"/>
자동 재로드를 포함한 개발자 모드 (Dev Mode with Auto-Reload)
더 빠른 개발 반복(development iteration)을 위해, 소스 파일이 변경될 때 명령어를 자동으로 재로드하도록 개발자 모드를 활성화합니다:
pip install piou[tui-reload]
그런 다음 --tui-reload 플래그를 사용합니다:
python my_cli.py --tui-reload
또는 환경 변수를 통해:
PIOU_TUI_DEV=1 python my_cli.py --tui
활성화되면, Piou는 명령어 소스 파일을 감시하고 저장 시 핫 리로드(hot-reloads)합니다. 또한 /tui-reload 명령을 사용하여 런타임에 재로드 모드를 전환할 수 있습니다.
재로드(reload) 후마다 사용자 정의 코드를 실행하려면 예를 들어 캐시된 데이터를 새로고침하는 경우, @cli.tui_on_reload 데코레이터를 사용하세요:
@cli.tui_on_reload
def on_reload():
print("Code reloaded!")
고급 예제: HTTP 벤치마크 (HTTP Benchmark)
TUI 모드는 풍부한 대화형 표시를 위해 사용자 정의 Textual 위젯을 마운트(mounting)하는 것을 지원합니다. 이 예제는 실시간 진행률 그리드와 함께 HTTP 라이브러리를 벤치마킹합니다:
<img alt="HTTP Benchmark TUI" src="https://github.com/Andarius/piou/raw/master/docs/static/bench_1000.gif" width="700"/>
TuiContext 및 사용자 정의 위젯을 사용하는 전체 구현은 examples/http_bench_tui.py를 참조하세요.
개발 (Development)
설정, 검사(checks), 그리고 풀 리퀘스트(pull request) 규칙은 CONTRIBUTING.md를 참조하세요.
테스트 실행 (Running Tests)
문서 생성 (Generating Documentation)
uv run --group docs mkdocs build
...
스크린샷 및 GIF 생성 (Generating Screenshots and GIFs)
터미널 녹화는 VHS를 사용하여 생성됩니다. 먼저 설치하세요:
sudo apt install vhs ttyd
...
그런 다음 테이프 파일에서 녹화를 생성합니다:
vhs docs/static/tui-demo.tape
테이프 파일은 docs/static/에 위치하며, GIF를 생성하는 스크립트화된 터미널 세션을 정의합니다.
