python-dotenv 贡献指南：测试、代码规范与文档构建全流程

后端【免费下载链接】python-dotenvReads key-value pairs from a .env file and can set them as environment variables. It helps in developing applications following the 12-factor principles.项目地址https://gitcode.com/gh_mirrors/py/python-dotenv点击查看免费下载导读本文基于 python-dotenv 仓库的 docs/contributing.md 贡献指南展开完整覆盖从环境搭建、测试执行、代码格式化到本地文档预览的整套开发工作流。无论你是想提交第一个 Issue、发起 Pull Request还是仅仅想在本地完整跑通该项目的测试与文档体系读完本文你都能掌握基于uv与tox的两种测试方式、ruff的代码规范约束以及用mkdocs在本地实时预览官方文档的具体步骤并了解这些命令背后对应的仓库配置与源码结构。一、贡献入口欢迎一切形式的参与贡献指南开篇即明确所有形式的贡献都受到欢迎。无论是报告问题通过 GitHub Issues还是提交代码Pull Request都是项目持续演进的一部分。对初学者而言最轻量的参与方式是先阅读仓库中的 README.md 了解项目定位通过 docs/reference.md 熟悉 API 全貌再结合 tests/ 目录下的测试用例理解各模块行为——这本身就是为后续贡献做准备的最佳路径。二、开发环境搭建基于 uv 的一站式工作流当前贡献指南推荐使用 uv 作为 Python 包与虚拟环境管理工具。以下命令逐一执行即可完成从零到可测试的开发环境$ uv venv $ uv pip install -r requirements.txt $ uv pip install -e .uv venv在当前目录创建虚拟环境默认生成.venv后续所有uv命令自动在该环境中执行uv pip install -r requirements.txt安装开发依赖。查看 requirements.txt 可知其中包含pytest9.0.3、pytest-cov、ruff、tox、build、pre-commit、click、ipython以及发布辅助工具bumpversion等uv pip install -e .以可编辑模式editable安装项目自身。通过 pyproject.toml 中的package-dir { src}配置可知源码实际位于src/dotenv目录即 src/dotenv/可编辑安装确保你修改源码后无需重装即可生效同时注册dotenv命令行入口见[project.scripts]中dotenv dotenv.__main__:cli。也可以使用传统 pip如果你不使用 uv等价的做法是$ python -m venv .venv $ source .venv/bin/activate $ pip install -r requirements.txt $ pip install -e .三、执行测试两种官方推荐方式3.1 方式一uv pytest$ uv ruff check . $ uv format . $ uv run pytest其中uv run pytest是测试的主入口。pyproject.toml 的[tool.pytest.ini_options]将testpaths配置为tests因此无需额外参数即可自动发现并运行 tests/ 下的全部测试覆盖解析器test_parser.py、主库 APItest_main.py、test_lib.py、CLItest_cli.py、IPython 集成test_ipython.py、FIFO 管道读取test_fifo_dotenv.py、zip 导入场景test_zip_imports.py等模块。若要输出覆盖率报告可参考 Makefile 中的coverage目标$ coverage run --sourcedotenv --omit*tests* -m py.test tests/ -v --tbnative $ coverage report3.2 方式二tox 矩阵测试如果安装了 tox只需一条命令即可跑完整套测试矩阵$ tox查看 tox.ini 可以理解其内部逻辑[tox] envlist lint,py{310,311,312,313,314,314t},pypy3,manifest,coverage-reportpy{310,311,312,313,314,314t}分别针对 Python 3.10 至 3.14含 free-threaded 的3.14t创建独立虚拟环境执行pytest --cov --cov-reportterm-missingpypy3在 PyPy 3.11 上运行测试lint运行ruff check、ruff format --check以及针对 3.10~3.14 五个版本的mypy类型检查详见 tox.ini 的[testenv:lint]manifest通过check-manifest校验打包清单coverage-report汇总各环境覆盖率[tool.coverage.paths]中甚至把.tox/*/lib/python*/site-packages/dotenv映射回src/dotenv保证跨环境覆盖率可正确合并。tox 测试同样用于 CI。.github/workflows/test.yml 展示了 GitHub Actions 中的真实用法Ubuntu 上跑全部 Python 版本Windows 上验证最低3.10与最高3.14版本安装tox tox-gh-actions后执行tox由 tox-gh-actions 根据矩阵自动映射环境。四、代码规范ruff 检查与格式化ruff在项目中承担 lint 与 format 双重职责$ uv ruff check . # 静态检查 $ uv format . # 自动格式化ruff.toml 定义了启用规则集[lint] select [ E4, # pycodestyle逻辑错误类 E7, # pycodestyle语句类 E9, # pycodestyle运行时错误类 F, # Pyflakes未使用导入、未定义名称等 B, # flake8-bugbear易错模式 I, # isort导入排序 A, # flake8-builtins内建名称遮蔽 ]从源码结构看项目采用src 布局因此 lint 对象是src与tests两个目录见 tox.ini 的ruff check src tests与 Makefile 中的fmt: ruff format src tests保持一致。五、推荐使用 pre-commit 钩子贡献指南建议安装 pre-commit在每次提交前自动执行代码检查$ uv run precommit install注意仓库中的可执行文件名为pre-commit由 requirements.txt 中的pre-commit包提供指南中写作precommit属于笔误实际安装时应使用带连字符的命令。仓库自带的 .pre-commit-config.yaml 配置了两个钩子均来自astral-sh/ruff-pre-commit锁定v0.12.0repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.12.0 hooks: - id: ruff # 运行 linter - id: ruff-format # 运行 formatter安装后每次git commit都会先执行ruff检查与ruff-format格式化不符合规范的文件会被拦截并自动修正从而保证提交到仓库的代码始终风格统一。六、文档构建与本地预览mkdocs 全流程python-dotenv 的文档站基于 mkdocs 构建。先在本地安装文档依赖$ uv pip install -r requirements-docs.txt $ uv pip install -e . $ uv run mkdocs serverequirements-docs.txt 中的依赖包括mkdocs1.5.0与mkdocs-material9.5.0核心站点生成器与 Material 主题mkdocstrings[python]0.24.0从源码 docstring 自动生成 API 参考文档mkdocs-include-markdown-plugin7.3.0支持在 Markdown 中按片段包含其他文件mdx_truly_sane_lists1.3修正 Markdown 列表渲染行为。uv run mkdocs serve启动本地开发服务器后打开 http://127.0.0.1:8000/ 即可实时预览文档。修改docs/下的 Markdown 文件或源码 docstring 会自动触发重新构建非常适合边写文档边校对。关于站点结构mkdocs.yml 给出了完整定义主题使用 Material主色调为绿色primary: green启用了toc.follow与navigation.sections启用mkdocstrings插件其 Python handler 配置了separate_signature、show_root_heading、show_symbol_type_heading等选项使函数签名与类型标注在参考页中清晰呈现导航菜单依次为 Homedocs/index.md、Changelogdocs/changelog.md、Contributingdocs/contributing.md、Referencedocs/reference.md、Licensedocs/license.md。也就是说你正在阅读的这份贡献指南docs/contributing.md本身就是文档站点的一个独立页面。当你要为项目新增或修改文档时可先在本地启动mkdocs serve验证渲染效果再提交改动。七、本地开发辅助Makefile 常用目标除上述 uv/tox 工作流外Makefile 还封装了若干日常命令可配合使用test: # 可编辑安装 ruff 检查 pytest uv pip install -e . ruff check . pytest tests/ fmt: # 仅格式化 src 与 tests ruff format src tests sdist: # 构建源码分发包到 dist/ python -m build -o dist . clean: # 清理构建产物、缓存与 .tox八、给贡献者的检查清单综合贡献指南与仓库配置提交 Pull Request 前建议依次确认测试通过uv run pytest或tox跑完整矩阵无失败代码规范uv ruff check .无警告uv format .后 diff 干净类型检查如改动涉及公开 API运行tox -e lint验证 mypy 在 3.10~3.14 各版本下均通过提交前钩子确认pre-commit已安装uv run pre-commit install并正常工作文档同步若行为或 API 有变化更新 docs/ 下对应页面并在本地mkdocs serve预览确认无误清单校验如新增/删除文件运行check-manifesttox 的manifest环境确认打包清单一致。完成以上步骤后即可通过 Issue 或 Pull Request 将你的贡献提交给维护者。赞分享后端【免费下载链接】python-dotenvReads key-value pairs from a .env file and can set them as environment variables. It helps in developing applications following the 12-factor principles.项目地址https://gitcode.com/gh_mirrors/py/python-dotenv点击查看免费下载相关推荐seaborn开源贡献指南测试、代码规范与文档构建完整流程seaborn开源贡献指南测试、代码规范与文档构建完整流程 seaborn 是基于 matplotlib 的 Python 统计 数据可视化 库提供绘制美观数据可视化数据分析PaddleOCR 贡献指南Python 代码规范、文档写作规范与 Pull Request 全流程详解PaddleOCR 贡献指南Python 代码规范、文档写作规范与 Pull Request 全流程详解 PaddleOCR 是一个基于飞桨PaddlePa人工智能计算机视觉OCR深度学习大模型RAGPaddleOCR 社区贡献指南Python 编码规范、文档规范与 Pull Request 全流程PaddleOCR 社区贡献指南Python 编码规范、文档规范与 Pull Request 全流程 本文是 PaddleOCR 开源社区贡献者的入门手册系人工智能计算机视觉OCR深度学习大模型RAG上一篇SmartBugs 批量安全审计实战4.7 万合约的并行分析与资源调优怎么配下一篇5分钟搞定全网资源下载res-downloader全平台嗅探工具终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考