Python 命令行工具：argparse、Click 与 Typer

import sys

def log(msg: str) -> None:
    print(msg, file=sys.stderr)

def emit(data: str) -> None:
    print(data)  # 只有这个能被管道消费

def main() -> int:
    try:
        run()
    except KeyboardInterrupt:
        log("interrupted")
        return 130
    except UsageError as e:
        log(f"error: {e}")
        return 2
    return 0

if __name__ == "__main__":
    sys.exit(main())

import os
from dataclasses import dataclass

@dataclass
class Config:
    endpoint: str = "http://localhost:8000"
    timeout: float = 30.0
    token: str | None = None

    @classmethod
    def load(cls, cli_args, config_file: dict | None = None) -> "Config":
        cfg = cls()
        cfg.endpoint = os.environ.get("MYTOOL_ENDPOINT", cfg.endpoint)
        if config_file:
            cfg.endpoint = config_file.get("endpoint", cfg.endpoint)
        if cli_args.endpoint:
            cfg.endpoint = cli_args.endpoint   # 最高优先级
        return cfg

import argparse

def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(
        prog="mytool",
        description="示例命令行工具",
        epilog="更多文档见 https://example.com",
        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
    )
    p.add_argument("path", help="输入路径")
    p.add_argument("-o", "--output", default="-", help="输出文件，- 表示 stdout")
    p.add_argument("-v", "--verbose", action="count", default=0, help="可叠加的详细度")
    p.add_argument("--timeout", type=float, default=30.0, help="超时秒数")
    return p

def positive_int(value: str) -> int:
    ivalue = int(value)
    if ivalue <= 0:
        raise argparse.ArgumentTypeError(f"{value} 必须是正整数")
    return ivalue

p.add_argument("--workers", type=positive_int, default=4)
p.add_argument("--mode", choices=["fast", "safe", "dry-run"], default="safe")
p.add_argument("--include", action="append", default=[], help="可重复指定")
p.add_argument("--no-color", action="store_true")
p.add_argument("--tags", nargs="+", default=[], help="一次接收多个值")

def main(argv=None) -> int:
    parser = build_parser()
    sub = parser.add_subparsers(dest="command", required=True)

    add = sub.add_parser("add", help="新增条目")
    add.add_argument("name")
    add.set_defaults(func=cmd_add)

    rm = sub.add_parser("remove", help="删除条目")
    rm.add_argument("name")
    rm.add_argument("-f", "--force", action="store_true")
    rm.set_defaults(func=cmd_remove)

    args = parser.parse_args(argv)
    return args.func(args)

import click

@click.group()
@click.option("--verbose", "-v", count=True, help="详细度")
@click.version_option()
@click.pass_context
def cli(ctx: click.Context, verbose: int) -> None:
    ctx.ensure_object(dict)
    ctx.obj["verbose"] = verbose

@cli.command()
@click.argument("path", type=click.Path(exists=True))
@click.option("--output", "-o", type=click.File("w"), default="-")
@click.pass_obj
def convert(obj: dict, path: str, output) -> None:
    """把 PATH 转换为目标格式。"""
    if obj["verbose"]:
        click.echo(f"reading {path}", err=True)
    output.write("...")

if __name__ == "__main__":
    cli()

@cli.command()
@click.option("--date", type=click.DateTime(["%Y-%m-%d"]), required=True)
@click.option("--level", type=click.IntRange(1, 9), default=5)
def report(date, level) -> None:
    ...

@cli.command()
@click.confirmation_option(prompt="确定要删除全部数据吗？")
def purge() -> None:
    ...

@cli.command()
def upload() -> None:
    name = click.prompt("项目名", type=str)
    password = click.prompt("密码", hide_input=True, confirmation_prompt=True)
    with click.progressbar(range(100), label="上传中") as bar:
        for i in bar:
            ...

from click.testing import CliRunner
from mytool.cli import cli

def test_convert(tmp_path):
    src = tmp_path / "in.txt"
    src.write_text("hello")
    runner = CliRunner()
    result = runner.invoke(cli, ["convert", str(src), "-o", "-"])
    assert result.exit_code == 0
    assert "hello" in result.output

def test_missing_path():
    result = CliRunner().invoke(cli, ["convert", "/nope"])
    assert result.exit_code == 2
    assert "does not exist" in result.output

import typer
from typing import Annotated, Optional
from pathlib import Path

app = typer.Typer(help="示例工具", no_args_is_help=True)

@app.command()
def convert(
    path: Annotated[Path, typer.Argument(exists=True, dir_okay=False)],
    output: Annotated[Optional[Path], typer.Option("--output", "-o")] = None,
    workers: Annotated[int, typer.Option(min=1, max=64)] = 4,
    verbose: Annotated[bool, typer.Option("--verbose", "-v")] = False,
) -> None:
    """把 PATH 转换为目标格式。"""
    if verbose:
        typer.echo(f"workers={workers}", err=True)

if __name__ == "__main__":
    app()

@app.command()
def add(name: str, force: bool = False) -> None:
    ...

@app.command()
def remove(name: str, force: bool = False) -> None:
    ...

# 或者把子命令拆到独立模块再挂载
app.add_typer(user_app, name="user", help="用户管理")

from rich.console import Console
from rich.table import Table
from rich.progress import track

console = Console(stderr=True)   # 诊断信息走 stderr

table = Table(title="构建结果")
table.add_column("模块")
table.add_column("状态", justify="right")
table.add_row("core", "[green]ok[/green]")
table.add_row("cli", "[red]fail[/red]")
console.print(table)

for _ in track(range(50), description="处理中..."):
    ...

import os, sys

def use_color() -> bool:
    return sys.stdout.isatty() and "NO_COLOR" not in os.environ

# Bash
_mytool_completion() { eval "$(_MYTOOL_COMPLETE=bash_complete mytool)"; }
complete -F _mytool_completion mytool

# Zsh
eval "$(_MYTOOL_COMPLETE=zsh_source mytool)"

# Fish
_MYTOOL_COMPLETE=fish_source mytool | source

mytool --help
mytool convert --help
mytool --version

from importlib.metadata import version

@click.version_option(version=version("mytool"))
def cli() -> None: ...

# 从 stdin 读取，支持管道
cat data.json | mytool convert --input - --output -

# 输出 JSON 供 jq 消费
mytool list --format json | jq '.[] | select(.active)'

[project]
name = "mytool"
version = "0.4.0"
dependencies = ["click>=8.1", "rich>=13.7"]

[project.scripts]
mytool = "mytool.cli:cli"

# 隔离安装（推荐给终端用户，不污染全局环境）
uv tool install mytool
pipx install mytool

# 项目依赖方式
uv add mytool

# 开发模式
uv pip install -e ".[dev]"

pyinstaller --onefile --name mytool --strip \
    --hidden-import click \
    src/mytool/__main__.py

# src/mytool/__main__.py
from mytool.cli import cli

if __name__ == "__main__":
    cli()

FROM python:3.12-slim AS build
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN pip install uv && uv sync --frozen --no-dev

FROM python:3.12-slim
COPY --from=build /app/.venv /app/.venv
ENV PATH=/app/.venv/bin:$PATH
ENTRYPOINT ["mytool"]

import subprocess, sys

def test_e2e_version():
    r = subprocess.run([sys.executable, "-m", "mytool", "--version"],
                       capture_output=True, text=True)
    assert r.returncode == 0
    assert "0.4.0" in r.stdout