自动化与 CLI 工具

# ① 标准库 argparse：零依赖 CLI
import argparse

def main():
    p = argparse.ArgumentParser(description="批量重命名")
    p.add_argument("src", help="源目录")
    p.add_argument("--dry-run", action="store_true", help="只预览不执行")
    p.add_argument("-v", "--verbose", action="count", default=0)
    args = p.parse_args()
    print(args.src, args.dry_run, args.verbose)

if __name__ == "__main__":
    main()

# ② Typer：类型注解驱动的现代 CLI（argparse 的 3.x）
import typer
app = typer.Typer()

@app.command()
def rename(src: str, dry_run: bool = False):
    """批量重命名文件"""
    ...

if __name__ == "__main__":
    app()

# ③ subprocess：驱动外部命令（替代 os.system）
import subprocess
r = subprocess.run(
    ["git", "status", "--porcelain"],
    capture_output=True, text=True, check=True,   # check：非零退出即抛异常
    timeout=30,
)
print(r.stdout)

uv tool install .          # 项目装成全局命令（独立隔离环境）
mytool src --dry-run
uvx mytool ...             # 免安装直接跑（一次性工具）

静态页        → httpx/requests + BeautifulSoup（或 selectolax）
需执行 JS     → Playwright（无头浏览器，现代首选）
批量并发      → asyncio + httpx.AsyncClient（kp-031）
登录/鉴权     → 会话对象、cookie 管理
尊重边界      → robots.txt、限速、目标站点条款（伦理，kp-048）

CLI 设计四原则：
  ① --dry-run 先行（破坏性操作必须可预演）
  ② 退出码语义化（0 成功；非 0 失败——供 shell/CI 判断）
  ③ stderr 放日志/进度，stdout 只放"结果数据"（可管道）
  ④ 长任务给进度与可中断（Ctrl+C 干净退出）

# 一个健壮的自动化脚本骨架
#!/usr/bin/env python3
"""备份指定目录到目标盘。"""
import argparse, logging, sys
from pathlib import Path
import shutil

def main(argv=None):
    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
    p = argparse.ArgumentParser(description=__doc__)
    p.add_argument("src", type=Path)
    p.add_argument("dst", type=Path)
    p.add_argument("--dry-run", action="store_true")
    args = p.parse_args(argv)

    if not args.src.is_dir():
        p.error(f"源目录不存在: {args.src}")
    for f in args.src.rglob("*.md"):
        target = args.dst / f.name
        if args.dry_run:
            print(f"将复制 {f} -> {target}")
        else:
            shutil.copy2(f, target)
    return 0

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