前言
在学习一个新的 Python 包时，我们经常想快速了解它有哪些模块和子包。本文分享一个简单实用的小工具，帮你一键生成包的模块结构树。
完整代码
#!/usr/bin/env python3""" 包结构探测器 - 快速查看任意Python包的模块结构 """importargparseimportimportlibimportpkgutilimportsysdefprobe_package(package_name,max_depth=3):""" 探测包结构并打印模块树 Args: package_name: 包名 max_depth: 最大探测深度 """# 导入包try:root=importlib.import_module(package_name)exceptModuleNotFoundError:print(f"❌ 找不到包:{package_name}")print(f" 请先安装: pip install{package_name}")returnexceptExceptionase:print(f"❌ 导入失败:{e}")return# 收集所有模块modules=[root.__name__]ifhasattr(root,"__path__"):# 是一个包，遍历子模块defwalk(pkg,depth=0):ifdepth>=max_depth:returntry:forfinder,name,ispkginpkgutil.iter_modules(pkg.__path__,pkg.__name__+"."):modules.append(name)ifispkg:try:sub=importlib.import_module(name)walk(sub,depth+1)except:passexcept:passwalk(root)# 打印结果print(f"\n📦{package_name}模块结构")print("="*40)# 构建树形结构root_name=package_nameformod_nameinsorted(modules):# 计算缩进depth=mod_name.count('.')-root_name.count('.')indent=" "*depth# 取最后一段名称short_name=mod_name.split('.')[-1]# 判断是包还是模块try:mod=importlib.import_module(mod_name)is_pkg=hasattr(mod,"__path__")icon="📁"ifis_pkgelse"📄"except:icon="📄"print(f"{indent}{icon}{short_name}")print("="*40)print(f"共{len(modules)}个模块\n")defmain():parser=argparse.ArgumentParser(description="查看Python包的模块结构")parser.add_argument("package",help="包名")parser.add_argument("-d","--depth",type=int,default=3,help="最大深度(默认3)")args=parser.parse_args()probe_package(args.package,args.depth)if__name__=="__main__":main()使用方法
基础用法
python probe_pkg.py requests输出：
📦 requests 模块结构 ======================================== 📁 requests 📄 adapters 📄 api 📄 auth 📄 certs 📄 compat 📄 cookies 📄 exceptions 📄 hooks 📄 models 📄 sessions 📄 status_codes 📄 structures 📄 utils ======================================== 共 14 个模块控制探测深度
python probe_pkg.py urllib3 -d2更多示例
# 探测 flaskpython probe_pkg.py flask# 探测 numpy（内容较多，限制深度）python probe_pkg.py numpy -d1# 探测本地开发的包python probe_pkg.py myproject代码解析
核心原理
importlib.import_module()- 动态导入指定的包pkgutil.iter_modules()- 遍历包内的所有子模块__path__属性- 判断是包（有__path__）还是普通模块
关键代码片段
# 判断是包还是模块ifhasattr(module,"__path__"):print("这是一个包，可以包含子模块")else:print("这是一个普通模块")# 遍历子模块forfinder,name,ispkginpkgutil.iter_modules(pkg.__path__):print(f"发现:{name}, 是否为包:{ispkg}")实用技巧
1. 快速了解新包
拿到一个新包，先跑一遍探测器，对整体结构有个概念：
python probe_pkg.py some_new_package2. 配合 help() 使用
找到感兴趣的模块后，用help()查看详情：
importrequests.adaptershelp(requests.adapters)3. 项目自检
检查自己项目的模块组织是否合理：
python probe_pkg.py myproject -d5总结
这个小工具虽然简单，但在日常开发中非常实用：
- ✅ 快速了解包结构
- ✅ 学习新库的起点
- ✅ 检查项目模块组织
- ✅ 代码量少，易于修改扩展
把它保存为probe_pkg.py，放到常用工具目录，随时调用！
💡扩展思路：可以加入导出 Markdown、显示模块文档、统计代码行数等功能。
