Skip to content

贡献

正在阅读我无法读取《https://github.com/pydantic/pydantic/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22》、《https://pypa.github.io/pipx/》、《https://github.com/pydantic/pydantic/issues/new/choose》文件的内容。其他文件已阅读并为你总结如下： 我们希望您能为 Pydantic 做出贡献！

问题

问题、功能请求和错误报告都欢迎作为讨论或问题提出。 但是，要报告安全漏洞，请查看我们的安全政策。

为了尽可能简化我们帮助您的过程，请在您的问题中包含以下调用的输出：

python -c "import pydantic.version; print(pydantic.version.version_info())"

如果您使用的是 v2.0 之前的 Pydantic，请使用：

python -c "import pydantic.utils; print(pydantic.utils.version_info())"

请尽量始终包含上述内容，除非您无法安装 Pydantic 或明确知道它与您的问题或功能请求无关。

拉取请求

开始并创建拉取请求应该非常简单。 Pydantic 定期发布，所以您应该在几天或几周内看到您的改进发布 🚀。

除非您的更改很小（拼写错误、文档调整等），否则请在创建拉取请求之前创建一个问题来讨论更改。

Pydantic V1 处于维护模式

Pydantic v1 处于维护模式，意味着只会接受错误修复和安全修复。 新功能应该针对 Pydantic v2。

要向 Pydantic v1 提交修复，请使用 1.10.X-fixes 作为目标分支。

如果您正在寻找一些可以深入研究的内容，请查看 GitHub 上的 "需要帮助"标签。

为了使贡献尽可能简单和快速，您希望在本地运行测试和检查。幸运的是， Pydantic 的依赖项很少，不需要编译，测试也不需要访问数据库等。 因此，设置和运行测试应该非常简单。

Tip

简而言之：使用 make format 修复格式，使用 make 运行测试和检查，使用 make docs 构建文档。

先决条件

您需要以下先决条件：

  • 任何介于 Python 3.9 和 3.12 之间的 Python 版本
  • uv 或其他虚拟环境工具
  • git
  • make

安装和设置

在 GitHub 上 fork 仓库并本地克隆您的 fork。

# 克隆您的 fork 并进入仓库目录
git clone git@github.com:<your username>/pydantic.git
cd pydantic

# 安装 UV 和 pre-commit
# 我们在这里使用 pipx，其他选项请参见：
# 链接8
# 链接1
# 要获取 pipx 本身：
# https://pypa.github.io/pipx/
pipx install uv
pipx install pre-commit

# 安装 pydantic、依赖项、测试依赖项和文档依赖项
make install

检出新分支并进行更改

为您的更改创建一个新分支。

# 检出新分支并进行更改
git checkout -b my-new-feature-branch
# 进行更改...

运行测试和 linting

本地运行测试和 linting，确保一切按预期工作。

# 运行自动化代码格式化和 linting
make format
# Pydantic 使用 ruff，一个用 rust 编写的优秀 Python linter
# 链接5

# 运行测试和 linting
make
# Makefile 中有一些子命令，如 `test`、`testcov` 和 `lint`，
# 您可能想使用，但通常只需 `make` 就足够了。
# 您可以运行 `make help` 查看更多选项。

构建文档

如果您对文档进行了任何更改（包括对函数签名、类定义或将在 API 文档中出现的 docstring 的更改），请确保文档构建成功。

我们使用 mkdocs-material[imaging] 来支持社交预览。 您可以在此处找到如何安装所需依赖项的说明here。

# 构建文档
make docs
# 如果您更改了文档，请确保构建成功。
# 您也可以使用 `uv run mkdocs serve` 在 localhost:8000 提供文档服务

如果由于 imaging 插件的问题而无法工作，请尝试注释掉 mkdocs.yml 中的 social 插件行，然后再次运行 make docs。

更新文档

我们在每个次要版本发布时推送新版本的文档，并在每次提交到 main 时推送到 dev 路径。

如果您在次要版本周期之外更新文档，并希望您的更改反映在 latest 上， 请执行以下操作：

  1. 针对 main 打开一个包含您的文档更改的 PR
  2. PR 合并后，检出 docs-update 分支。此分支应与最新的补丁版本保持同步。 例如，如果最新版本是 v2.9.2，您应确保 docs-update 与 v2.9.2 标签保持同步。
  3. 从 docs-update 检出一个新分支，并将您的更改 cherry-pick 到此分支上。
  4. 推送您的更改并针对 docs-update 打开一个 PR。
  5. PR 合并后，新文档将被构建和部署。

Note

维护者快捷方式 - 作为维护者，您可以跳过第二个 PR，直接 cherry-pick 到 docs-update 分支。

提交并推送更改

提交您的更改，将分支推送到 GitHub，并创建拉取请求。

请遵循拉取请求模板并尽可能填写更多信息。链接到任何相关问题，并包含更改描述。

当您的拉取请求准备好审查时，添加一条消息为 "please review" 的评论，我们会尽快查看。

文档风格

文档使用 Markdown 编写，并使用 Material for MkDocs 构建。API 文档使用 mkdocstrings 从 docstring 构建。

代码文档

为 Pydantic 做贡献时，请确保所有代码都有良好的文档记录。以下内容应使用正确格式化的 docstring 进行文档记录：

  • 模块
  • 类定义
  • 函数定义
  • 模块级变量

Pydantic 使用 Google 风格 docstring，根据 PEP 257 指南格式化。（更多示例请参见 Example Google Style Python Docstrings。）

pydocstyle 用于 linting docstring。您可以运行 make format 来检查您的 docstring。

当 Google 风格 docstring 和 pydocstyle linting 存在冲突时，请遵循 pydocstyle linting 提示。

类属性和函数参数应以 "name: description." 的格式记录。适用时，返回类型应仅用描述记录。类型从签名推断。

class Foo:
    """A class docstring.

    Attributes:
        bar: A description of bar. Defaults to "bar".
    """

    bar: str = 'bar'

def bar(self, baz: int) -> str:
    """A function docstring.

    Args:
        baz: A description of `baz`.

    Returns:
        A description of the return value.
    """

    return 'bar'

您可以在 docstring 中包含示例代码。此代码应完整、自包含且可运行。Docstring 示例经过测试，因此请确保它们正确且完整。示例请参见 FieldInfo.from_annotated_attribute。

类和实例属性

类属性应在类 docstring 中记录。

实例属性应作为 "Args" 在 __init__ docstring 中记录。

文档风格

一般来说，文档应以友好、平易近人的风格编写。它应易于阅读和理解，并尽可能简洁，同时保持完整。

鼓励代码示例，但应保持简短。然而，每个代码示例都应是完整、自包含且可运行的。（如果您不确定如何操作，请寻求帮助！）我们更喜欢打印输出而不是裸断言，但如果您测试的内容没有有用的打印输出，断言也可以。

Pydantic 的单元测试将测试文档中的所有代码示例，因此它们正确且完整非常重要。添加新代码示例时，使用以下命令测试示例并更新其格式和输出：

# 运行测试并更新代码示例
pytest tests/test_docs.py --update-examples

调试 Python 和 Rust

如果您正在使用 pydantic 和 pydantic-core，您可能会发现一起调试 Python 和 Rust 代码很有帮助。 这是一个关于如何操作的快速指南。本教程在 VSCode 中完成，但您可以在其他 IDE 中使用类似的步骤。

徽章

Pydantic 有一个徽章，您可以用它来显示您的项目使用 Pydantic。您可以在 README.md 中使用此徽章：

使用 Markdown

[](链接15)

[](链接15)

使用 reStructuredText

.. image:: 链接6
    :target: 链接15
    :alt: Pydantic

.. image:: 链接16
    :target: 链接15
    :alt: Pydantic

使用 HTML

<a href="链接15"></a>

<a href="链接15"></a>

将您的库添加为 Pydantic 第三方测试套件的一部分

为了能够在开发过程中及早识别回归，Pydantic 在各种使用 Pydantic 的第三方项目上运行测试。 如果您的项目符合以下一些标准，我们会考虑添加对测试新开源项目的支持：

  • 项目积极维护。
  • 项目使用 Pydantic 内部功能（例如依赖 BaseModel 元类、类型工具）。
  • 项目足够流行（尽管小型项目仍可根据 Pydantic 的使用方式被包括在内）。
  • 项目 CI 足够简单，可以移植到 Pydantic 的测试工作流中。

如果您的项目符合其中一些标准，您可以打开功能请求 来讨论包含您的项目。