一个好用的Python命令行工具需正确使用argparse：从最小骨架起步，区分位置参数与选项参数，提供清晰help、类型校验和合法值限制，支持子命令与参数分组，将argparse视为用户界面来设计。
写一个好用的 Python 命令行工具，核心是把 argparse 用对、用顺——它不是堆参数，而是让命令行接口清晰、健壮、可维护。
一、从最简结构开始：别一上来就塞一堆参数
先搭骨架，再填内容。一个能跑通的最小命令行程序长这样：
- 导入
argparse - 创建
ArgumentParser实例（可带description） - 用
add_argument()添加至少一个参数（比如--input或位置参数） - 调用
parse_args()获取结果 - 用解析出的值做实际逻辑
示例：
import argparse
<p>parser = argparse.ArgumentParser(description="统计文本行数")
parser.add_argument("file", help="要读取的文件路径")
args = parser.parse_args()</p><p>with open(args.file) as f:
print(f"共 {len(f.readlines())} 行")运行：python count.py data.txt —— 这就完成了基础交互。
立即学习“Python免费学习笔记（深入）”；
二、区分“位置参数”和“选项参数”，用对语义
位置参数（如 python cp src dst 中的 src 和 dst）没有前缀，靠顺序；选项参数（如 --verbose 或 -v）带短横线，更灵活、可选、可复用。
- 位置参数：用
parser.add_argument("name")，必填，默认类型是字符串 - 选项参数：用
parser.add_argument("--name")或-n，加action="store_true"可做开关（如--dry-run） - 混用时，位置参数总在选项参数之后（argparse 自动处理）
常见组合：
A Python CLI skill for Cutout.Pro visual APIs — background removal, face cutout, and photo enhancement. Supports file upload & image URL input.
下载
调用 Cutout.Pro 视觉处理 API 进行背景移除、人像抠图和照片增强，支持文件上传与图片 URL 输入。
parser.add_argument("input", help="输入文件")
parser.add_argument("-o", "--output", help="输出文件路径")
parser.add_argument("-v", "--verbose", action="store_true", help="显示详细过程")
parser.add_argument("-n", type=int, default=10, help="处理前 N 行")三、让错误友好、帮助清晰：别让用户猜
默认报错信息干巴巴，help 也容易写得模糊。几个关键点：
- 给
add_argument()加help=字符串，用户执行--help就能看到 - 用
type=指定类型（如int、float、自定义函数），出错自动提示格式不符 - 用
choices=限定合法值（如choices=["json", "csv", "tsv"]），输错直接报错并列出可选项 - 用
default=设默认值，避免逻辑分支过多；设为argparse.SUPPRESS可让参数不出现于args对象中（适合条件性参数）
例如：
parser.add_argument("--format", choices=["json", "yaml"], default="json",
help="输出格式（默认 json）")用户输 --format xml，会看到：error: argument --format: invalid choice: 'xml' (choose from 'json', 'yaml') —— 清晰且有引导。
四、进阶但实用：子命令、参数分组、自定义动作
当工具功能变多（比如 git commit、git push），用子命令划分更自然：
subparsers = parser.add_subparsers(dest="command", help="可用子命令")
# commit 子命令
commit_parser = subparsers.add_parser("commit", help="提交更改")
commit_parser.add_argument("-m", "--message", required=True)
<h1>push 子命令</h1><p>push_parser = subparsers.add_parser("push", help="推送分支")
push_parser.add_argument("remote", nargs="?")运行：python tool.py commit -m "init" 或 python tool.py push origin。
其他实用技巧：
- 用
add_argument_group()把相关参数归组，help 输出更整洁 - 继承
argparse.Action写自定义动作（比如自动展开通配符、校验文件存在性） - 用
formatter_class=argparse.RawDescriptionHelpFormatter保留 help 字符串中的换行和缩进
不复杂但容易忽略。把 argparse 当成用户界面来设计，而不是参数搬运工，工具才真正好用。
