查看: 56|回复: 3

Python argparse子命令实现cua打包合并检查工具

[复制链接]
发表于 半小时前 | 显示全部楼层 |阅读模式
在终端里反复敲 cd、find、tar,最烦的往往不是操作本身有多难,而是长路径写错一次就得重来。把这类重复动作收敛成一个短命令,是很自然的需求。下面这套实现来自一个叫 cua(Command Utility Assistant)的个人小工具,用 Python 写成,把打包、报告合并、服务体检固定成 pack、merge、check 三个子命令。这里按实际落地顺序拆解:argparse 的子命令分发、tarfile 的过滤打包、socket 端口探测、退出码设计,以及安装后命令找不到的排查思路。

一、先定形态:命令行、单文件、配置外置

做成命令行而不是 GUI,核心理由是可组合:命令行工具能被 shell 脚本、cron 定时任务、CI/CD 流程直接调用,比如在构建脚本里执行 cua check,靠返回码决定是否中止后续步骤,这种编程式调用能力 GUI 很难提供。另一方面,工具本身就跑在终端上下文里,不用为了一件小事切到别的窗口,分发也只是一个 Python 文件丢过去。

用 Python 而不是 Bash,关键不在功能而在参数处理。Shell 里靠 $1、$2 顺序取值或用 getopts,一旦出现“指定打包目录”“排除某类文件”“是否上传”这类组合参数,写法会迅速变得绕。标准库 argparse 处理子命令、可选参数和自动生成的 --help 帮助信息都更直接,用户敲 cua --help 就能看到每个子命令的用法。跨平台也是硬需求:macOS 自带 Bash 3.2,Linux 上常见 Bash 5.x,在关联数组和正则支持上存在差异,而 tarfile、subprocess、socket 在三个平台上行为基本一致。

整体结构参考 git、docker 的“一个主命令 + 若干子命令”形态,入口统一、子命令互相隔离。配置不写死在代码里,放在 ~/.cua/config.yaml,首次运行 cua init 生成默认内容,大致如下:
  1. projects:
  2.   blog: ~/Documents/blog
  3.   app: ~/Work/application
  4. pack:
  5.   outputs: ~/Backups
  6.   excludes:
  7.     - node_modules
  8.     - .git
  9.     - dist
  10. check:
  11.   ports: [3306, 6379, 9200]
  12.   directory_max_mb: 2048
复制代码

路径别名、端口列表这类经常变化的信息留在配置里,改配置即可,不必动代码。项目目录按职责拆成主入口 cua.py、commands 包(pack_cmd.py、merge_cmd.py、check_cmd.py)、utils 包(config.py、output.py),依赖只有 PyYAML 一个第三方库,执行 pip install pyyaml 即可;如果是 Python 3.11 以上,也可以改用 tomllib 把配置格式换成 TOML,进一步减少依赖。

二、主入口:用 add_subparsers 做参数分发
  1. import argparse
  2. from commands import pack_cmd, merge_cmd, check_cmd
  3. def main():
  4.     parser = argparse.ArgumentParser(prog="cua", description="Command Utility Assistant")
  5.     subparsers = parser.add_subparsers(dest="command", required=True)
  6.     pack_parser = subparsers.add_parser("pack", help="pack a project directory")
  7.     pack_parser.add_argument("project", help="project alias defined in config")
  8.     pack_parser.add_argument("--exclude", action="append", help="extra exclude patterns")
  9.     pack_parser.add_argument("--no-upload", action="store_true", help="skip upload step")
  10.     merge_parser = subparsers.add_parser("merge", help="merge report files")
  11.     merge_parser.add_argument("directory", help="directory to scan")
  12.     merge_parser.add_argument("--pattern", default="test-report*.md", help="glob pattern to match")
  13.     check_parser = subparsers.add_parser("check", help="check ports and disk usage")
  14.     check_parser.add_argument("--ports", action="append", type=int, help="additional ports to check")
  15.     check_parser.add_argument("--directory", help="directory to check disk usage")
  16.     args = parser.parse_args()
  17.     if args.command == "pack":
  18.         pack_cmd.run(args)
  19.     elif args.command == "merge":
  20.         merge_cmd.run(args)
  21.     elif args.command == "check":
  22.         check_cmd.run(args)
  23. if __name__ == "__main__":
  24.     main()
复制代码

两个细节值得留意:一是 dest="command",解析后直接用 args.command 判断走哪个分支,分发逻辑很干净;二是 required=True,不加这个参数时,用户只输 cua 不带子命令会静默退出,对命令行工具来说是不良体验。

三、pack 子命令:别名映射、过滤打包、清单生成

pack 分三步。第一步把命令行传入的 project 名称通过配置里的别名映射换成真实路径,同时要处理别名不存在的情况,给出可读的错误提示而不是抛异常。第二步打包,用标准库 tarfile 配合 filter 参数做排除,比在 Shell 里拼 tar 命令更灵活:
  1. import os
  2. import tarfile
  3. from datetime import datetime
  4. def create_tarball(source_dir, output_dir, branch, excludes=None):
  5.     excludes = excludes or []
  6.     timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
  7.     project_name = os.path.basename(source_dir.rstrip(os.sep))
  8.     filename = f"{project_name}-{timestamp}-{branch}.tar.gz"
  9.     output_path = os.path.join(output_dir, filename)
  10.     def should_exclude(tarinfo):
  11.         for pattern in excludes:
  12.             if pattern in tarinfo.name:
  13.                 return None
  14.         return tarinfo
  15.     with tarfile.open(output_path, "w:gz") as tar:
  16.         tar.add(source_dir, arcname=project_name, filter=should_exclude)
  17.     size_mb = os.path.getsize(output_path) / 1024 / 1024
  18.     return output_path, size_mb
复制代码

arcname=project_name 这层包装的作用是让解压后所有文件落在一个以项目名命名的目录里,而不是散在当前目录,看着不起眼,但实际解压时组织清晰很多。文件名带上时间戳和 git 分支,例如 frontend-20250615-143012-master.tar.gz,避免了 final_v2 这类无法追溯的命名。分支名通过 subprocess.check_output 执行 git branch --show-current 取得,这一步是后来补上的:一开始只有日期,等到需要回溯线上版本时,才发现缺分支信息的包根本无法快速定位代码。

第三步生成 manifest.txt 一并写入包内,记录源码目录的文件数量、总大小、Git 分支和打包时间,隔一段时间翻旧包时能快速知道内容是什么。

四、merge 子命令:排序靠文件名,拼接补标题

merge 的逻辑是扫描指定目录、按 glob 模式匹配文件、排序后依次拼接。测试报告通常按日期命名,如 test-report-20250601.md、test-report-20250602.md,字符串排序恰好等于时间顺序,因此直接用 sorted() 即可,不需要额外解析日期。拼接时在每个文件正文前插入一个二级标题,标题内容取去掉扩展名后的文件名,这样合并出来的 markdown 结构清晰,阅读者能一眼看出各段来源,文件头部再生成一份简单目录索引。

五、check 子命令:端口探测与退出码

check 覆盖两个维度:端口是否可连接、指定目录所在磁盘占用是否超过配置阈值。端口用 socket.connect_ex() 判断,比主动 connect 再捕获异常更干净,返回 0 表示可连、非 0 表示不可达:
  1. import socket
  2. def is_port_open(port, host="127.0.0.1", timeout=1):
  3.     sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
  4.     sock.settimeout(timeout)
  5.     result = sock.connect_ex((host, port))
  6.     sock.close()
  7.     return result == 0
复制代码

磁盘部分用 shutil.disk_usage() 拿到总量、已用量和剩余量,与配置里的 directory_max_mb 比较即可。结果逐行输出 status: ok 或 status: fail。真正让 check 区别于其他子命令的是退出码:只要有一项不通过,主程序就 sys.exit(1);全部通过则为 0。终端里看不出太大差别,但一旦放进定时任务或 CI,外部脚本仅凭返回码就能判断要不要继续。

性能方面,瓶颈在磁盘 IO 和网络超时而非 Python 执行效率。一个约 5MB 的源码目录,tarfile 压缩不到 2 秒;检查 10 个端口、单端口超时 1 秒,最差也在 10 秒内结束。稳定性上做了两处防御:配置缺失时提示先执行 cua init,而不是抛 traceback;打包目标目录不可写时输出普通文本错误,而不是堆栈。

六、安装成全局命令

在 cua.py 头部加 shebang,赋予执行权限后软链到 /usr/local/bin:
  1. #!/usr/bin/env python3
  2. chmod +x cua.py
  3. sudo ln -s "$(pwd)/cua.py" /usr/local/bin/cua
复制代码

重新开终端执行 cua --help,能列出全部子命令说明就算装好了。这种方式简单稳定,适合个人使用;需要多用户共享或自动升级时,再考虑用 pip 的 entry_points 打包成正式分发包。

七、常见问题与排查

1. 提示 command not found。多数情况出在软链目标或 Python 解释器上。先确认软链是否建成功,再直接运行 /usr/local/bin/cua 看真实报错;如果提示找不到 python3,检查 shebang 用的是 python3 还是绝对路径,以及当前 shell 下 which python3 指向哪里。跨机器时解释器路径不一致,是这类问题最常见的根因。

2. argparse 的三个坑。其一,子命令参数若与主命令参数重名,解析结果可能被主命令拦截,子命令收不到值,取名时加前缀(如 --no-upload)可规避。其二,action="append" 的参数默认值是 None 而不是空列表,代码里直接 for 循环 args.ports 会抛 TypeError,解析后要先补 if args.ports is None: args.ports = []。其三,子命令的帮助信息默认不显示全局参数,希望所有子命令都识别的公共参数(例如 --verbose)应定义在主 parser 上。

3. 配置文件找不到导致项目路径无效。默认配置在 ~/.cua/config.yaml,但在 Windows 的 Git Bash 里 HOME 不一定指向 C:\Users\用户名,可能被改成 /tmp 之类的路径。处理办法是代码里不直接使用 ~,改用 Path.home() 获取主目录,并用 os.path.expanduser 统一展开配置中所有含 ~ 的路径,这样各平台解析结果一致。

4. 交互式选择要限定触发条件。pack 支持第二个参数传入目录路径时,若当前位于 git 仓库内,就列出最近几个 tag 让用户选择版本,用 input() 加循环校验实现简单菜单。但交互逻辑不能混进核心流程,否则工具无法用于无人值守场景,应封装成独立函数,仅在检测到标准输入是 TTY 时触发,脚本调用时直接走默认值。

八、与现有工作流整合

单点使用之外,价值主要来自整合。在 git 的 post-commit 钩子里可以接上打包逻辑;CI 配置里在测试步骤之后加一句 cua merge ./reports && cua check,借助退出码判断流程是否继续。整合时建议从一条高频主流程开始,比如先把打包做透,再加第二个场景,一次塞进五六个功能往往会每个都做得不深,最后整个工具被闲置。

小结:这类个人效率工具不需要一开始就追求大而全。找到重复频率最高、最容易出错的那个场景,封装到足够简单,哪怕只有一个子命令,只要天天在用就比一堆半成品有价值。输出格式值得花时间打磨,正常信息、警告和错误用不同颜色区分,扫一眼终端就能判断结果是否正常;文档也要顺手写,参数说明和配置说明不仅是换机器后恢复环境的依据,也是一个月后重新读代码时理解设计意图的线索。
回复

使用道具 举报

发表于 半小时前 | 显示全部楼层

Re: Python argparse子命令实现cua打包合并检查工具

这套思路挺清晰的,先定命令行形态再拆子命令,比一上来堆功能更稳。argparse 用 add_subparsers 做分发,配合 commands 包分文件,后面加子命令也不容易乱。配置外置到 ~/.cua/config.yaml 这点很实用,路径别名和端口列表本来就会经常变,改配置比改代码舒服。依赖只留 PyYAML,对个人工具来说也合适。 落地时有几个小地方可以留意:配置里的 ~ 路径读取后最好统一做 expanduser 展开;--exclude 用 append 接收后,和配置里的 excludes 合并时注意去重和顺序,避免排除规则互相覆盖。tarfile 过滤打包时,建议按相对路径匹配排除项,别把同名但不在排除目录里的文件误伤。check 子命令做端口探测时最好加超时,不然一个端口不通可能拖慢整个体检。退出码也值得统一约定,比如成功 0、检查失败 1、参数或配置错误 2,这样在脚本和定时任务里判断更直接。 安装后命令找不到,除了看 PATH,也要确认入口脚本是不是真的装进了可执行目录,虚拟环境里装完有没有激活对应环境。整体方向很好,把 pack、merge、check 固定成短命令,确实能省掉不少重复敲长路径的麻烦。
回复 支持 反对

使用道具 举报

发表于 半小时前 | 显示全部楼层

Re: Python argparse子命令实现cua打包合并检查工具

这个思路挺实用的,把 cd/find/tar 这一串动作收敛成三个子命令,确实比每次手敲长路径靠谱。配置文件外置这点我特别认同,项目路径和端口这种经常变的东西放 YAML 里,改起来不用动代码,也不容易因为改错一个字符把脚本弄崩。选 Python 而不是 Bash 的理由也讲得很实在,参数组合一多,shell 的 $1、$2 和 getopts 很快就写成一团,argparse 的 --help 和子命令隔离能省不少事。 主入口那段用 add_subparsers 做分发的结构很清晰,dest="command" 加 required=True 能保证不带子命令时直接报错,不会静默什么都不做。不过有个小地方可以再顺手一点:三个子命令的 add_parser 里可以加 set_defaults(func=pack_cmd.run),最后统一 args.func(args),这样以后加第四个命令就不用再往 if/elif 链里补分支,主入口也不容易越写越长。 还有两个落地时容易踩的点想提一下:配置里的 ~/Documents/blog 这种路径,读出来最好统一做一次 expanduser 再用,不然 tarfile 和目录扫描拿到字面量 ~ 会找不到路径;check 子命令的 --ports 用 action="append" 收集的是命令行额外端口,后面和配置文件里的 ports 合
回复 支持 反对

使用道具 举报

发表于 半小时前 | 显示全部楼层

Re: Python argparse子命令实现cua打包合并检查工具

这个结构挺对路的,git/docker 那种“一个主命令 + 子命令”的形态确实最适合这种杂活工具,配 subparsers 加上 required=True,敲 cua 不带参数就直接报错并打印用法,比手动判断 sys.argv 长度省心多了。 几个点我比较认同:一是配置外置到 ~/.cua/config.yaml、用项目别名代替长路径,正好解决了“长路径敲错一次重来”这个原始痛点;二是用 Python 而不是 Bash 的理由说得实在,Bash 3.2 和 5.x 在关联数组上的差异我踩过,脚本一多就会到处埋兼容性坑;三是提到退出码设计,这点很关键,check 子命令能不能被 CI 当门禁用,全看端口不通、磁盘超限时返回什么值,这块如果后面能展开讲讲会很有价值。 另外正文到 main 的 if __name__ 那里就断了,后面的 tarfile 过滤打包(是给 tarfile.add 传 filter 回调还是自己 walk 一遍再 add?)、socket 端口探测的超时设置、以及最后“安装后命令找不到”的排查思路都没看到,有点意犹未尽,方便的话把剩下的贴出来。 顺便问两个实现细节:pack 的 --exclude 是 append 到参数里,那它和配置文件里的 excludes 是叠加还是覆盖?我倾向于叠加,显式传参优先级高但不清空默认值。还有 merge 的 --pat
回复 支持 反对

使用道具 举报

您需要登录后才可以回帖 登录 | 注册

本版积分规则

指导单位

江苏省公安厅

江苏省通信管理局

浙江省台州刑侦支队

DEFCON GROUP 86025

Hacking Group 021A

旗下站点

态势感知中心

应急响应中心

红盟安全

联系我们

官方QQ群:112851260

官方邮箱:security#ihonker.org(#改成@)

官方核心成员

关注微信公众号

Archiver|手机版|小黑屋| ( 沪ICP备2021026908号 )

GMT+8, 2026-11-21 04:40 , Processed in 0.024033 second(s), 17 queries , Gzip On, Redis On.

Powered by ihonker.com

Copyright © 2015-现在.

  • 返回顶部