# python_ast_parser2

**Repository Path**: enzoism/python_ast_parser2

## Basic Information

- **Project Name**: python_ast_parser2
- **Description**: 使用AST和Ripgrep开发的源码分析工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AST Reader - Python 项目代码分析工具

## 📖 项目简介

AST Reader 是一个强大的 Python 项目静态代码分析工具,通过解析抽象语法树(AST)和集成 ripgrep 搜索引擎,提供代码结构可视化、符号索引、调用关系分析和全局搜索等功能。它帮助开发者快速理解大型 Python 项目的代码结构和依赖关系。

## ✨ 核心功能

### 1. **项目结构抽取与可视化**
- 🌲 递归扫描 Python 项目目录,自动提取所有 `.py` 文件
- 📊 解析 AST 生成项目结构树,展示文件、类、方法和函数的层级关系
- 💾 将分析结果保存为 `.ast/structure.json` 索引文件,支持快速加载

### 2. **AST 语义分析**
- 🔍 **类与方法分析**:提取类名、继承关系、方法定义、参数列表、装饰器等信息
- 📝 **函数分析**:识别顶层函数、异步函数、默认参数等
- 📦 **导入分析**:记录 `import` 和 `from...import` 语句
- 🎯 **文档字符串**:自动提取类和函数的 docstring

### 3. **调用关系图谱**
- ➡️ **调用目标 (Calls To)**:分析方法/函数内部调用的其他符号
- ⬅️ **被调用方 (Called By)**:追踪哪些地方调用了当前符号
- 🔗 **全局索引**:构建完整的符号表和调用图,支持跨文件追踪

### 4. **双引擎全局搜索**
- ⚡ **ripgrep 文本搜索**:利用 ripgrep 实现毫秒级全文本匹配,支持正则表达式
- 🎯 **AST 符号搜索**:基于语义的精确符号匹配,区分类、方法、函数类型
- 🔦 **上下文预览**:显示匹配行的前后文代码片段

### 5. **代码浏览与定位**
- 🖥️ **语法高亮**:集成 highlight.js,提供深色主题代码高亮
- 📍 **行号导航**:点击符号直接跳转到定义位置,自动高亮对应行
- 📄 **源码查看**:实时读取并展示原始 Python 源代码

### 6. **交互式 Web 界面**
- 🎨 **现代化 UI**:采用 GitHub 风格的深色主题设计
- 📱 **响应式布局**:侧边栏树形结构 + 代码编辑器 + 详情面板三栏布局
- ⌨️ **快捷键支持**:支持 Enter 键快速搜索等操作

## 🏗️ 技术架构

### 后端技术栈
- **Flask**:轻量级 Web 框架,提供 RESTful API
- **Python ast 模块**:标准库 AST 解析器,无需额外依赖
- **ripgrep**:高性能正则表达式搜索工具(可选)
- **flask-cors**:跨域资源共享支持

### 前端技术栈
- **原生 HTML/CSS/JavaScript**:零框架依赖,轻量高效
- **highlight.js**:代码语法高亮
- **Fetch API**:异步数据请求

### 数据存储
- **JSON 格式**:`.ast/structure.json` 存储项目索引
- **本地持久化**:浏览器 localStorage 记住上次打开的项目路径

## 🚀 快速开始

### 环境要求
- Python >= 3.11.4
- ripgrep(可选,用于增强搜索功能)

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd ast-reader
```

2. **安装依赖**
```bash
uv sync
```

3. **启动服务**
```bash
cd src/ast-reader/backend
python app.py
```

4. **访问界面**
打开浏览器访问:`http://localhost:5000`

### (可选)安装 ripgrep

macOS:
```bash
brew install ripgrep
```

Linux:
```bash
sudo apt-get install ripgrep
```

Windows:
```bash
winget install BurntSushi.ripgrep.MSVC
```

## 📋 使用指南

### 基本工作流程

1. **项目抽取**
   - 在顶部输入框输入 Python 项目的绝对路径
   - 点击"项目抽取"按钮
   - 等待分析完成,系统会生成 `.ast/structure.json` 文件

2. **浏览代码结构**
   - 左侧边栏显示项目树形结构
   - 点击文件夹展开/折叠
   - 点击文件查看源码,同时显示该文件包含的类和方法

3. **查看符号详情**
   - 点击类名或方法名(带有 🅒/🅜/ƒ 图标)
   - 代码区域自动跳转到定义位置并高亮
   - 底部面板显示:
     - 元数据(类型、行号、参数、装饰器、是否异步)
     - 调用目标列表
     - 被调用方列表

4. **全局搜索**
   - 点击"全局搜索"按钮或按快捷键
   - 选择搜索模式:
     - **文本 (rg)**:全文本匹配,速度快
     - **符号 (AST)**:精确符号匹配,语义准确
   - 输入关键词,点击搜索结果可直接跳转

5. **加载已有项目**
   - 如果项目已抽取过,点击"加载已有"可快速恢复
   - 无需重新分析,直接读取缓存的索引文件

### API 接口说明

| 端点 | 方法 | 功能 |
|------|------|------|
| `/api/extract` | POST | 抽取项目 AST 结构 |
| `/api/load` | GET | 加载已有的 AST 索引 |
| `/api/search` | POST | 双引擎全局搜索 |
| `/api/method_detail` | POST | 获取符号详细信息和调用关系 |
| `/api/file_source` | GET | 获取文件源码 |

## 📁 项目结构

```
ast-reader/
├── src/ast-reader/
│   ├── backend/
│   │   ├── app.py              # Flask 主应用,API 路由
│   │   ├── analyzer.py         # AST 分析引擎
│   │   └── rg_client.py        # ripgrep 客户端封装
│   ├── frontend/
│   │   └── index.html          # 单页 Web 应用
│   └── main.py                 # 主程序入口
├── pyproject.toml              # 项目配置和依赖
└── README.md                   # 项目文档
```

## 🔧 开发说明

### 添加新的 AST 节点处理

在 `StructureExtractor` 类中添加对应的 `visit_*` 方法:

```python
def visit_XXX(self, node):
    # 提取信息
    self.generic_visit(node)
```

### 扩展 API 功能

在 `app.py` 中添加新的路由:

```python
@app.route("/api/your_endpoint", methods=["POST"])
def api_your_endpoint():
    data = request.get_json() or {}
    # 处理逻辑
    return jsonify({"success": True, "data": ...})
```

## 🎯 应用场景

- 📚 **代码阅读**:快速理解陌生项目的结构和关键逻辑
- 🔍 **重构辅助**:查找符号的所有引用位置,评估修改影响范围
- 🐛 **调试支持**:追踪函数调用链,定位问题根源
- 📊 **技术审计**:分析项目依赖关系和代码复杂度
- 🎓 **教学演示**:可视化展示 Python 代码的 AST 结构

## ⚠️ 注意事项

- 首次抽取大型项目可能需要几秒到几分钟,取决于项目规模
- `.ast` 目录会被自动排除在分析范围之外
- 语法错误的 Python 文件会被标记但不会中断整体分析
- ripgrep 未安装时,文本搜索功能不可用,但不影响 AST 分析

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request!

## 📄 许可证

MIT License
---

**享受代码探索的乐趣!** 🚀