Skip to content

贡献指南

感谢您有意为 HTTPX 贡献代码。您可以通过多种方式参与项目：

报告缺陷或其他问题

发现 HTTPX 应该支持的功能？遇到了意外行为？

贡献通常应从讨论开始。可能的缺陷可以发起"潜在问题"讨论，功能请求可以发起"想法"讨论。然后我们会评估是否需要将讨论升级为"问题"或考虑接受 Pull Request。

请尽可能详细描述，如果是缺陷报告，请提供以下信息：

  • 操作系统平台
  • Python 版本
  • 已安装的依赖及版本 (python -m pip freeze)
  • 代码片段
  • 错误回溯

您应该始终尝试将示例缩减到能重现问题的最简单情况。

以下可能有用的排查建议：

  • 问题存在于 HTTP/1.1、HTTP/2 还是两者都有？
  • 问题存在于 Client、AsyncClient 还是两者都有？
  • 使用 AsyncClient 时，问题在使用 asyncio 或 trio 时都存在吗？

开发流程

要开始开发 HTTPX，请先在 GitHub 上Fork HTTPX 仓库。

然后克隆您的 fork（将 YOUR-USERNAME 替换为您的 GitHub 用户名）：

$ git clone https://github.com/YOUR-USERNAME/httpx

现在可以安装项目及其依赖：

$ cd httpx
$ scripts/install

测试与代码检查

我们使用自定义的 shell 脚本来自动化测试、代码检查以及文档构建工作流。

运行测试请使用：

$ scripts/test

Warning

测试套件会在 8000 和 8001 端口启动测试服务器。 请确保这些端口未被占用，以保证测试正常运行。

任何额外参数都将传递给 pytest。更多信息请参阅 pytest 文档。

例如，运行单个测试脚本：

$ scripts/test tests/test_multipart.py

运行代码自动格式化：

$ scripts/lint

最后，单独运行代码检查（这些检查也会作为 scripts/test 的一部分运行）：

$ scripts/check

文档编写

文档页面位于 docs/ 目录下。

要在本地运行文档站点（便于预览修改），请使用：

$ scripts/docs

解决构建/CI失败问题

提交 pull request 后，测试套件会自动运行，结果将显示在 GitHub 上。 如果测试失败，请点击 "Details" 链接，尝试找出失败原因。

失败的PR提交状态

以下是测试套件常见的失败情况：

检查任务失败

失败的GitHub Actions代码检查任务

此任务失败意味着存在代码格式化问题或类型注解问题。 您可以查看任务输出来确定失败原因，或者在 shell 中运行：

$ scripts/check

建议运行 $ scripts/lint 尝试自动格式化代码， 如果该任务成功，则提交修改后的代码。

文档构建失败

此任务失败意味着文档构建未成功。可能由多种原因导致，例如无效的 Markdown 语法或 mkdocs.yml 中缺少配置项。

Python 3.X 测试失败

GitHub Actions 测试任务失败

此任务失败意味着单元测试未通过或存在未被单元测试覆盖的代码路径。

若测试失败，您将在覆盖率报告下方看到如下信息：

=== 1 failed, 435 passed, 1 skipped, 1 xfailed in 11.09s ===

若测试通过但未达到当前覆盖率阈值，您将在覆盖率报告下方看到：

FAIL 未达到要求的 100% 测试覆盖率。当前总覆盖率: 99.00%

发布流程

本节内容面向 HTTPX 维护者。

在发布新版本前，请创建一个包含以下内容的拉取请求：

  • 更新变更日志：
    • 我们遵循 keepachangelog 的格式
    • 通过 对比 master 分支与最新发布版本的标签，列出所有对用户有价值的变更：
      • 必须包含在变更日志中的内容：新增、变更、废弃或移除的功能，以及错误修复
      • 不应包含在变更日志中的内容：文档、测试或工具的修改
      • 尝试按照影响/重要性降序排列条目
      • 保持简洁明了。🎯
  • 版本号更新：修改 __version__.py 文件

示例可参考 #1006。

当发布PR被合并后，创建一个新版本发布，包含：

  • 标签版本号如 0.13.3
  • 发布标题 Version 0.13.3
  • 从变更日志复制的描述内容

创建后该版本将自动上传至 PyPI。

如果 PyPI 任务出现异常，可以使用 scripts/publish 脚本来手动发布版本。

开发代理设置

要通过代理测试和调试请求，最佳方式是本地运行一个代理服务器。任何服务器都可以，但 HTTPCore 的测试套件使用了 mitmproxy，它由 Python 编写，功能全面，并提供了优秀的 UI 和工具用于请求内省。

你可以通过 pip install mitmproxy 或其他多种方式安装 mitmproxy。

mitmproxy 需要为 HTTPS 请求设置本地 TLS 证书，因为它的主要目的是让开发者能够检查通过的请求。我们可以按以下步骤设置：

  1. pip install trustme-cli
  2. trustme-cli -i example.org www.example.org（假设你想测试连接该域名），这将生成三个文件：server.pem、server.key 和 client.pem
  3. mitmproxy 需要一个包含私钥和证书的 PEM 文件，因此需要合并它们： cat server.key server.pem > server.withkey.pem
  4. 启动代理服务器 mitmproxy --certs server.withkey.pem，或使用其他 mitmproxy 命令选择不同的 UI 选项

此时服务器已准备好处理请求，你需要按照代理章节和SSL 证书章节的说明配置 HTTPX，这里会用到之前生成的 client.pem：

ctx = ssl.create_default_context(cafile="/path/to/client.pem")
client = httpx.Client(proxy="http://127.0.0.1:8080/", verify=ctx)

但请注意，HTTPS 请求仅对我们生成的 SSL/TLS 证书中指定的主机有效，对其他主机的 HTTPS 请求会引发类似错误：

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate
verify failed: Hostname mismatch, certificate is not valid for
'duckduckgo.com'. (_ssl.c:1108)

如果需要向更多主机发起请求，你需要重新生成证书并在第二步中包含所有目标主机，例如：

trustme-cli -i example.org www.example.org duckduckgo.com www.duckduckgo.com