用 CodeMap 快速分析你的 Python 项目结构

一行命令生成依赖图、调用链、复杂度热力图
接手一个陌生的 Python 项目时，你最想做的是什么？
我猜是：快速搞清楚模块之间怎么依赖的、函数调用链条是怎样的、哪些文件最复杂。

今天介绍一个开源小工具 CodeMap，它能帮你把 Python 项目的内部结构“可视化”出来。

什么是 CodeMap？

CodeMap 是一个 Python 代码可视化工具，提供五个独立功能：

• 📦 依赖图谱 – 模块间 import 关系（交互式 HTML）
• 📞 函数调用图 – 从入口函数递归追踪调用链（Mermaid/JSON）
• 🔥 代码热力图 – 圈复杂度/代码行数/Git 提交次数（彩色网格）
• 🧵 运行时追踪 – 类与类之间的方法调用时序图
• 🌳 调用树 – 思维导图式展开用户函数调用

项目地址：https://github.com/kirito-chen/CodeMap

安装

git clone https://github.com/yourname/codemap
cd codemap
pip install -e .

快速上手

我们用一个简单的示例项目来演示。项目结构如下：

test_project/
├── main.py
├── helper.py
└── utils.py

• main.py 调用 helper.greet() 和 utils.multiply()
• 三个文件相互独立

1. 生成依赖图（Dependency Graph）

codemap deps ./test_project --output deps.html

用浏览器打开 deps.html，可以看到交互式依赖图：

节点是模块，箭头表示 import。可以拖拽、缩放、查看详情。

2. 生成函数调用图（Call Graph）

codemap calls ./test_project/main.py --entry start --format mermaid

输出 Mermaid 代码：

graph TD
    start --> print
    start --> multiply
    start --> greet

可以直接粘贴到 Markdown 或 Mermaid 在线编辑器渲染。

3. 生成热力图（Heatmap）

codemap heatmap ./test_project --metric complexity --output heat.html

打开 heat.html，每个格子代表一个文件，颜色越深圈复杂度越高：

你也可以统计代码行数：

codemap heatmap ./test_project --metric lines --output lines.html

进阶用法：Python API

CodeMap 不仅可以命令行使用，还能作为库被其他程序引用：

from codemap import build_heatmap

# 生成复杂度热力图并保存为 PNG
hm = build_heatmap(".", metric="complexity")
hm.save("output.png", format="png", title="My Project Complexity")

总结

CodeMap 的目标是零配置、一键生成，帮助开发者快速理解陌生代码库。如果你经常需要接手别人的项目，或者想给你的开源项目配上结构图，不妨试试它。

优点

• 安装简单，依赖少
• 输出格式丰富（HTML、Mermaid、JSON、PNG、CSV）
• 可交互，可嵌入文档
• 被其他工具集成友好