Python CLI 도구 개발 실전 튜토리얼 — Click 설치부터 서브 커맨드, Rich 출력, PyPI 배포까지

argparse vs Click 코드 비교
# argparse 방식 — 명시적이지만 서브커맨드 늘어날수록 장황해진다
import argparse

def main():
    parser = argparse.ArgumentParser(description="파일 복사 도구")
    parser.add_argument("src", help="원본 경로")
    parser.add_argument("dst", help="대상 경로")
    parser.add_argument("-v", "--verbose", action="store_true")
    args = parser.parse_args()
    if args.verbose:
        print(f"{args.src} -> {args.dst} 복사 중...")


# Click 방식 — 데코레이터 하나로 동일 기능 구현
import click

@click.command()
@click.argument("src")
@click.argument("dst")
@click.option("-v", "--verbose", is_flag=True, help="자세한 출력")
def copy_file(src, dst, verbose):
    """파일 복사 도구"""
    if verbose:
        click.echo(f"{src} -> {dst} 복사 중...")

filetool/
├── filetool/
│   ├── __init__.py
│   └── cli.py       ← 진입점
├── tests/
│   └── test_cli.py
└── pyproject.toml

가상 환경 설정 + Click 그룹 구조
# 가상 환경 생성 및 활성화
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install click rich

# filetool/cli.py
import click

@click.group()
@click.version_option(version="1.0.0")
def cli():
    """파일 관리 유틸리티"""
    pass


@cli.command()
@click.argument("path", type=click.Path(exists=True))
@click.option("--count", "-n", default=10, show_default=True, help="출력할 줄 수")
@click.option("--encoding", default="utf-8", help="파일 인코딩")
def head(path, count, encoding):
    """파일의 첫 N줄을 출력합니다."""
    with open(path, encoding=encoding) as f:
        for i, line in enumerate(f):
            if i >= count:
                break
            click.echo(line, nl=False)


@cli.command()
@click.argument("path", type=click.Path(exists=True))
def wc(path):
    """파일의 줄 수, 단어 수, 바이트 수를 출력합니다."""
    with open(path, "rb") as f:
        content = f.read()
    lines = content.count(b"\n")
    words = len(content.split())
    click.echo(f"{lines:>8} {words:>8} {len(content):>8} {path}")


if __name__ == "__main__":
    cli()

Click 파라미터 타입 — 선택 목록·정수 범위·경로 검사 활용
import click
from pathlib import Path

@cli.command()
@click.argument("files", nargs=-1, type=click.Path(exists=True, path_type=Path))
@click.option(
    "--format", "output_format",
    type=click.Choice(["json", "csv", "tsv"], case_sensitive=False),
    default="json",
    help="출력 형식 (기본: json)",
)
@click.option(
    "--limit",
    type=click.IntRange(1, 1000),
    default=100,
    show_default=True,
    help="처리할 최대 행 수 (1~1000)",
)
@click.option(
    "--output", "-o",
    type=click.Path(dir_okay=False, writable=True),
    help="결과를 저장할 경로 (기본: 표준 출력)",
)
def process(files, output_format, limit, output):
    """여러 파일을 처리해 지정한 형식으로 변환합니다."""
    if not files:
        raise click.UsageError("파일을 하나 이상 지정하세요.")

    click.echo(f"파일 {len(files)}개, 형식: {output_format}, 최대 {limit}행")
    for f in files:
        click.echo(f"  처리 중: {f}")

Rich 진행 표시줄 + 테이블 출력
import click
from pathlib import Path
from rich.console import Console
from rich.progress import Progress, SpinnerColumn, BarColumn, TextColumn
from rich.table import Table

console = Console()

@cli.command()
@click.argument("directory", type=click.Path(exists=True, file_okay=False, path_type=Path))
@click.option("--top", default=20, show_default=True, help="상위 N개 파일 표시")
def stats(directory, top):
    """디렉토리 파일 통계를 테이블로 출력합니다."""
    all_files = [f for f in directory.rglob("*") if f.is_file()]

    results = []
    with Progress(
        SpinnerColumn(),
        TextColumn("[bold blue]{task.description}"),
        BarColumn(),
        TextColumn("{task.completed}/{task.total}"),
        console=console,
    ) as progress:
        task = progress.add_task("파일 분석 중...", total=len(all_files))
        for f in all_files:
            results.append((f.name, f.suffix or "-", f.stat().st_size))
            progress.advance(task)

    table = Table(title=f"{directory} — 파일 통계 (상위 {top}개)", show_header=True)
    table.add_column("파일명", style="cyan", no_wrap=True)
    table.add_column("확장자")
    table.add_column("크기 (바이트)", justify="right", style="green")

    for name, ext, size in sorted(results, key=lambda x: x[2], reverse=True)[:top]:
        table.add_row(name, ext, f"{size:,}")

    console.print(table)
    console.print(f"[dim]전체 {len(all_files)}개 파일[/dim]")

환경 변수 자동 매핑 + JSON 설정 파일 통합
import click
import json
from pathlib import Path

def load_config(ctx, param, value):
    """설정 파일을 읽어 Context default_map에 등록한다."""
    if value is None:
        default_path = Path.home() / ".filetool" / "config.json"
        value = str(default_path) if default_path.exists() else None

    if value and Path(value).exists():
        with open(value) as f:
            ctx.default_map = json.load(f)
    return value

# FILETOOL_API_KEY 환경변수가 --api-key 옵션에 자동으로 매핑됨
@click.command(context_settings={"auto_envvar_prefix": "FILETOOL"})
@click.option(
    "--config",
    type=click.Path(dir_okay=False),
    callback=load_config,
    expose_value=False,
    is_eager=True,
    help="설정 파일 경로 (기본: ~/.filetool/config.json)",
)
@click.option("--api-key", required=True, help="API 키 (FILETOOL_API_KEY 환경변수도 가능)")
@click.option("--timeout", default=30, show_default=True, help="요청 제한 시간(초)")
@click.option("--endpoint", default="https://api.example.com", help="API 엔드포인트")
def upload(api_key, timeout, endpoint):
    """파일을 원격 서버에 업로드합니다."""
    masked = api_key[:4] + "****" if len(api_key) > 4 else "****"
    click.echo(f"API 키: {masked}")
    click.echo(f"엔드포인트: {endpoint}")
    click.echo(f"제한 시간: {timeout}초")

# 사용 예시
# FILETOOL_API_KEY=secret filetool upload   <- 환경변수로 전달
# filetool --config ~/.filetool/config.json upload  <- 설정 파일

pyproject.toml 구성 + PyPI 배포 명령
# pyproject.toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "filetool"
version = "1.0.0"
description = "파일 관리 CLI 유틸리티"
readme = "README.md"
license = "MIT"
requires-python = ">=3.10"
dependencies = [
    "click>=8.1",
    "rich>=13.0",
]

[project.urls]
Homepage = "https://github.com/yourname/filetool"

# pip install 후 터미널에서 filetool 명령으로 바로 실행
[project.scripts]
filetool = "filetool.cli:cli"


# 배포 절차
# pip install build twine                           <- 빌드 도구 설치
# python -m build                                   <- dist/ 에 wheel 생성
# twine check dist/*                                <- 배포 전 유효성 검사
# twine upload --repository testpypi dist/*         <- 테스트 PyPI 먼저
# pip install --index-url https://test.pypi.org/simple/ filetool  <- 설치 확인
# twine upload dist/*                               <- 실제 PyPI 배포

CliRunner로 Click CLI 단위 테스트
from click.testing import CliRunner
from filetool.cli import cli

def test_head_command(tmp_path):
    test_file = tmp_path / "sample.txt"
    test_file.write_text("줄1\n줄2\n줄3\n줄4\n줄5\n")

    runner = CliRunner()
    result = runner.invoke(cli, ["head", str(test_file), "--count", "3"])

    assert result.exit_code == 0
    assert "줄1" in result.output
    assert "줄4" not in result.output


def test_missing_file():
    runner = CliRunner()
    result = runner.invoke(cli, ["head", "없는파일.txt"])
    assert result.exit_code != 0
    assert "Error" in result.output


def test_process_no_files():
    runner = CliRunner()
    result = runner.invoke(cli, ["process"])
    assert result.exit_code != 0
    assert "파일을 하나 이상" in result.output