为 pipreqs 贡献代码：从本地开发环境搭建、测试验证到提交 Pull Request 的完整指南-开发者社区

开发工具
CLI

【免费下载链接】pipreqs

pipreqs - Generate pip requirements.txt file based on imports of any project. Looking for maintainers to move this project forward.

项目地址：https://gitcode.com/gh_mirrors/pi/pipreqs

点击查看免费下载

本篇指南以仓库根目录的 CONTRIBUTING.rst 为主体，系统讲解如何为 pipreqs（一款基于项目 import 语句自动生成requirements.txt的工具）贡献代码：包括报告 Bug、实现特性、撰写文档、搭建 Poetry 本地开发环境、运行 flake8 / unittest / tox 质量检查，以及最终提交 Pull Request 的完整流程。读完本文，你将掌握在 pipreqs 仓库中安全改代码、验证改动并顺利通过评审的实战方法，同时能对照仓库源码与测试用例理解改动背后的行为约束。

一、贡献的多种方式：不止写代码

pipreqs 欢迎一切形式的贡献，且每一次贡献都会被记入功劳（credit）。根据 CONTRIBUTING.rst，你可以在五个方向上参与：

1. 报告 Bug（Report Bugs）

在项目 issue 区提交 Bug 报告时，务必附带以下信息，帮助维护者快速定位：

你的操作系统名称与版本；
本地环境中有助于排查问题的任何细节（如 Python 版本、是否使用虚拟环境、PyPI 镜像等）；
可复现 Bug 的详细操作步骤（越具体越好）。

2. 修复 Bug（Fix Bugs）

浏览 issue 列表中标记为bug的问题，任何带该标签的问题都欢迎任何人认领并实现修复。

3. 实现新特性（Implement Features）

浏览 issue 列表中标记为feature的需求，任何带该标签的需求同样对所有人开放。仓库描述中"Looking for maintainers to move this project forward"也表明项目正积极寻求长期维护者接手推进。

4. 撰写文档（Write Documentation）

pipreqs 始终需要更多文档，方向包括：

官方 pipreqs 文档（即仓库docs/目录下的 Sphinx 文档，如 docs/index.rst）；
源码 docstring（例如 pipreqs/pipreqs.py 中每个函数头部的Args/Returns说明）；
互联网上的博客文章与技术分享。

值得留意的是，文档是 Sphinx 构建体系的一部分：docs/contributing.rst 正是通过.. include:: ../CONTRIBUTING.rst将仓库根目录的 CONTRIBUTING.rst 直接包含进官方文档，因此你在根目录写的这份文档会同步出现在官方文档站中；docs/conf.py 启用了sphinx.ext.autodoc与sphinx.ext.viewcode，docstring 质量会直接影响 API 文档的可读性。

5. 提交反馈（Submit Feedback）

提出新特性建议时，请遵循三条原则：

详细说明该特性在设计中应如何工作；
尽量缩小特性范围，使其更易实现；
记住这是一个志愿者驱动的项目，贡献永远受欢迎。

二、本地开发环境搭建（Get Started）

1. Fork 并克隆仓库

先在托管平台 Forkpipreqs仓库，再将你的 fork 克隆到本地：

$ git clone <你的 fork 地址> $ cd pipreqs/

克隆完成后，仓库根目录应包含 pipreqs/pipreqs.py、pipreqs/stdlib、pipreqs/mapping、tests/test_pipreqs.py、pyproject.toml、tox.ini 等核心文件。

2. 使用 Poetry 安装开发依赖

pipreqs 使用 Poetry 管理依赖。请先参考 Poetry 官方文档在本地安装 Poetry，然后执行：

$ poetry install --with dev

--with dev会额外安装 pyproject.toml 中声明的开发依赖组，包括：

flake8>=6.1.0：代码风格检查；
tox>=4.11.3：跨 Python 版本测试矩阵；
coverage>=7.3.2：测试覆盖率；
sphinx>=7.2.6（仅 Python >= 3.9）：本地构建官方文档。

同时，项目requires-python约束为>=3.9, <3.14，运行时依赖为yarg>=0.1.9、docopt>=0.6.2、nbconvert>=7.11.0、ipython>=8.12.3（后两者用于 Jupyter Notebook 扫描，见下文）。CLI 入口在 pyproject.toml 的[project.scripts]中定义为pipreqs = "pipreqs.pipreqs:main"。

3. 创建功能分支

$ git checkout -b name-of-your-bugfix-or-feature

建议分支名体现改动意图，例如fix-notebook-encoding或add-ignore-glob。

4. 本地修改

现在可以自由修改代码。改动核心逻辑时，请先阅读 pipreqs/pipreqs.py（共 600 余行、使用docopt解析命令行参数的单文件实现），了解现有调用链：main()→init(args)→get_all_imports()（AST 解析 + 排除标准库与本地包）→get_pkg_names()（经mapping映射为 PyPI 包名）→ 本地/PyPI 版本解析 → 写出requirements.txt。

5. 通过质量检查：flake8 + 单元测试 + tox

改动完成后，依次运行以下三组命令：

$ poetry run flake8 pipreqs tests $ poetry run python -m unittest discover $ poetry run tox

flake8：对pipreqs与tests目录做风格检查。tox.ini 中配置了max-line-length = 120，并排除tests/_data/、tests/_data_clean/、tests/_data_duplicated_deps/、tests/_data_ignore/、tests/_invalid_data/等测试夹具目录（这些目录故意包含非常规代码，用于验证工具行为）。
unittest：python -m unittest discover会运行仓库根目录下的全部单元测试，实际执行的是 tests/test_pipreqs.py 中约 40 个用例（详见下文第三节）。
tox：在多个 Python 版本上重复执行单元测试。tox.ini的envlist为py39, py310, py311, py312, py313, pypy3, flake8，其中 flake8 是独立的 lint 环境。要在本地完整跑通全部版本，需要预先安装这些 Python 版本，官方推荐使用pyenv或asdf管理多版本解释器。

三、仓库源码与测试体系：改动背后的行为约束

要做出通过评审的改动，理解现有测试覆盖是前提。tests/test_pipreqs.py 用unittest.mock与真实样例目录（tests/_data/、tests/_data_clean/、tests/_data_ignore/、tests/_data_duplicated_deps/、tests/_data_notebook/、tests/_invalid_data/、tests/_data_pyw/）验证了以下关键行为：

测试用例	验证的行为
`test_get_all_imports`	从`_data/test.py`正确提取 15 个第三方 import，且排除`time`、`logging`、`curses`、`__future__`、`django`、`models`（标准库 / 本地模块不进入结果）
`test_deduplicate_dependencies`	重复依赖去重，`_data_duplicated_deps/db.py`最终只产生一个`pymongo`
`test_invalid_python`/`test_ignore_errors`	无效 Python 文件默认抛`SyntaxError`，开启`ignore_errors=True`后跳过
`test_ignored_directory`	`--ignore .ignored_dir,.ignore_second`生效，`click`、`getpass`不再进入 requirements
`test_dynamic_version_*`	`--mode=no-pin`输出裸包名、`--mode=gt`使用`>=`、`--mode=compat`使用`~=`
`test_clean`/`test_clean_with_imports_to_clean`	`--clean`删除未被 import 的模块（如`sqlalchemy`）
`test_output_requirements`	`--print`输出的内容与写入文件的内容完全一致
`test_import_notebooks`/`test_ipynb_2_py`/`test_invalid_notebook`	`--scan-notebooks`下`.ipynb`经`PythonExporter`转换后与对应`.py`提取出的 import 一致
`test_init_overwrite`	已存在的`requirements.txt`不会被静默覆盖（需`--force`）
`test_custom_pypi_server`	非法 PyPI 服务器地址（如`nonexistent`）会抛出`requests.exceptions.MissingSchema`
`test_parse_requirements`/`test_compare_modules`	按 PEP 508 分隔符解析 requirements 文件并正确求差集

对应到源码实现：

import 提取：get_all_imports()默认忽略.hg、.svn、.git、.tox、__pycache__、env、venv、.venv、.ipynb_checkpoints等目录（pipreqs/pipreqs.py 第 105–115 行），通过ast.parse遍历ast.Import/ast.ImportFrom节点收集原始 import，再以partition(".")截取包名首段，最后与pipreqs/stdlib文件中的标准库名单求差。
包名映射：get_pkg_names()读取pipreqs/mapping（形如Crypto:pycryptodome、BeautifulSoupTests:BeautifulSoup的 import 名 → PyPI 包名映射），未命中的 import 名直接作为包名使用。
文件类型：DEFAULT_EXTENSIONS = [".py", ".pyw"]；仅当开启--scan-notebooks时追加.ipynb，并延迟导入nbconvert.PythonExporter（未安装时会抛出NbconvertNotInstalled提示信息）。

如果你改动了上述任一逻辑，请务必同步更新或新增对应的测试用例——这是 PR 评审的第一条硬性要求。

四、Pull Request 提交指南

在提交 Pull Request 之前，请逐条核对以下要求（CONTRIBUTING.rst 的 Pull Request Guidelines）：

PR 必须包含测试：任何行为改动都应伴随可运行的测试用例，且测试需在本地poetry run python -m unittest discover下通过；
新功能必须更新文档：将新功能放入带 docstring 的函数中（便于 Sphinx autodoc 生成 API 文档），并把该特性加入 README.rst 的功能列表；
多版本兼容：PR 应能兼容项目当前支持的全部 Python 与 PyPy 版本。原文档要求检查 CI 中所有受支持 Python 版本的测试是否通过；就当前仓库而言，tox.ini 的测试矩阵覆盖 CPython 3.9～3.13 与 PyPy3，README.rst 顶部也挂有 GitHub Actions 测试徽章，提交前至少应保证本地poetry run tox -e py39（或你的默认版本）通过。

提交并推送分支

$ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature

提交信息建议遵循"动词 + 对象"的清晰描述风格（如Fix encoding parameter for ipynb files）。推送完成后，通过托管平台网页提交 Pull Request，并确保在 PR 描述中说明改动动机、关联 issue 以及本地验证结果。

五、仓库级开发辅助设施

除了 CONTRIBUTING 文档中的命令，仓库还提供了两套快捷工具链：

根目录 Makefile：make lint（=poetry run flake8 pipreqs tests）、make test（=poetry run python -m unittest discover）、make test-all（=poetry run tox）、make docs（调用sphinx-apidoc -o docs/ pipreqs后在docs/下构建 HTML 文档，输出到docs/_build/html/）、make build/make publish（Poetry 打包与发布）。日常开发中直接make lint与make test即可完成 CONTRIBUTING 规定的前两步检查。
Sphinx 文档构建：docs/下另有独立的 docs/Makefile（支持make html、make latexpdf、make doctest等目标），配合 docs/conf.py 的autodoc/viewcode扩展，可从 docstring 自动生成 API 文档页。

六、Tips：只运行一个子集测试

当你的改动只涉及某个功能点时，无需跑完整测试套件。使用-m unittest指定测试类即可：

$ poetry run python -m unittest tests.test_pipreqs

若只想运行单个用例，可进一步限定到类名与方法名，例如只验证动态版本模式或--clean行为。这在迭代调试时能显著缩短反馈回路。

七、小结

pipreqs 的贡献流程是一套完整可执行的质量保障体系：Poetry 负责依赖隔离与可复现安装，flake8 守住代码风格，unittest保护 import 解析、包名映射、动态版本与 Notebook 扫描等核心行为，tox 保证跨 Python 版本的兼容性，Sphinx 文档体系则让 docstring 与 README 持续反映新特性。对照 tests/test_pipreqs.py 与 pipreqs/pipreqs.py 理解每一条规则背后的行为约束，再按 CONTRIBUTING.rst 的流程提交，你的 PR 就能既安全又快速地合入这个由志愿者驱动、正在寻找新维护者的开源项目。