pydeps Python 导入耦合图

要解决的问题

当你准备重构一个 Python 项目，或者要把一个体量过大的包拆成几个独立模块时，最先遇到的往往不是「该怎么改」，而是「根本说不清谁依赖谁」。import 语句散落在几十个文件里，靠人工 grep 或者翻目录结构去脑补耦合关系，结果通常是漏掉间接依赖、高估某些模块的独立性，甚至拆完之后才发现运行时还有隐式的导入链。

这类判断一旦出错，代价会直接体现在拆包后的循环导入、启动顺序问题，以及 CI 里莫名其妙的失败上。

技能如何工作

这个技能围绕 pydeps 展开，核心思路是把静态扫描得到的 import 关系直接渲染成一张可视化的模块依赖图，而不是给你一堆文本清单。

• 以真实导入表为起点：它扫描本地 Python 代码库，把所有模块之间的导入关系收集起来，形成一张完整的 import map。重构方案可以拿这张图当依据，而不是凭直觉拍脑袋。
• 图形化的耦合视图：依赖关系以图的形式呈现，你能直观地看到哪些模块处在热点位置，哪条边是拆包时最容易扯断的关键连接。
• 标准库过滤粒度可控：通过 --pylib 可以把 Python 标准库模块纳入图里，用来确认某处依赖是否只是标准库而不必过度紧张；需要更完整的视图时，--pylib-all 会把全部标准库模块（包括 C 模块）一并纳入。

适用边界与注意点

• 分析对象是本地代码库，需要目标项目已经在机器上，且能被正常扫描。
• 绘图依赖 dot 命令，环境里需要装好 Graphviz 并确保 dot 在 PATH 中，否则图生成不出来。
• 依赖图反映的是静态导入关系，动态导入（运行期拼接模块名之类的写法）未必能被完整捕获，读图时要结合代码本身一起判断。
• 图上的模块边界不一定等于你打算拆分的边界，它只提供事实，不替你做架构决策。