跳转到内容

贡献

我们非常欢迎您为 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 上的“help wanted”标签。

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

提示

tl;dr：使用 make format 修复格式，使用 make 运行测试和代码检查，使用 make docs 构建文档。

先决条件

您将需要以下先决条件

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

安装和设置

在 GitHub 上 fork 存储库，并在本地克隆您的 fork。

# Clone your fork and cd into the repo directory
git clone [email protected]:<your username>/pydantic.git
cd pydantic

# Install UV and pre-commit
# We use pipx here, for other options see:
# https://docs.astral.ac.cn/uv/getting-started/installation/
# https://pre-commit.git-scm.cn/#install
# To get pipx itself:
# https://pypa.github.io/pipx/
pipx install uv
pipx install pre-commit

# Install pydantic, dependencies, test dependencies and doc dependencies
make install

检出新分支并进行更改

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

# Checkout a new branch and make your changes
git checkout -b my-new-feature-branch
# Make your changes...

运行测试和代码检查

在本地运行测试和代码检查，以确保一切按预期工作。

# Run automated code formatting and linting
make format
# Pydantic uses ruff, an awesome Python linter written in rust
# https://github.com/astral-sh/ruff

# Run tests and linting
make
# There are a few sub-commands in Makefile like `test`, `testcov` and `lint`
# which you might want to use, but generally just `make` should be all you need.
# You can run `make help` to see more options.

构建文档

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

我们使用 mkdocs-material[imaging] 来支持社交预览（请参阅插件文档）。

# Build documentation
make docs
# If you have changed the documentation, make sure it builds successfully.
# You can also use `uv run mkdocs serve` to serve the documentation at localhost:8000

如果由于成像插件的问题导致此功能无法正常工作，请尝试注释掉 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 合并后，将构建并部署新文档。

注意

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

提交并推送更改

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

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

当您的拉取请求准备好进行审查时，添加一条带有“please review”消息的评论，我们将尽快查看。

文档风格

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

代码文档

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

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

Pydantic 使用根据 PEP 257 准则格式化的Google 风格 docstring。（有关更多示例，请参阅Google 风格 Python Docstring 示例。）

使用 pydocstyle 进行 docstring 检查。您可以运行 make format 来检查您的 docstring。

如果 Google 风格 docstring 和 pydocstyle 检查之间存在冲突，请遵循 pydocstyle 检查提示。

类属性和函数参数应以“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 中进行文档。

实例属性应在 __init__ docstring 中作为“Args”进行文档。

文档风格

通常，文档应以友好、易于理解的风格编写。它应该易于阅读和理解，并且在保持完整性的同时尽可能简洁。

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

Pydantic 的单元测试将测试文档中的所有代码示例，因此它们必须正确且完整。添加新代码示例时，请使用以下方法测试示例并更新其格式和输出

# Run tests and update code examples
pytest tests/test_docs.py --update-examples

调试 Python 和 Rust

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

徽章

Pydantic v1 Pydantic v2

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

使用 Markdown

[![Pydantic v1](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json)](https://pydantic.org.cn)

[![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json)](https://pydantic.org.cn)

使用 reStructuredText

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json
    :target: https://pydantic.org.cn
    :alt: Pydantic

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json
    :target: https://pydantic.org.cn
    :alt: Pydantic

使用 HTML

<a href="https://pydantic.org.cn"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json" alt="Pydantic Version 1" style="max-width:100%;"></a>

<a href="https://pydantic.org.cn"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json" alt="Pydantic Version 2" style="max-width:100%;"></a>

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

为了能够在开发早期发现回归，Pydantic 对使用 Pydantic 的各种第三方项目运行测试。如果您的项目符合以下某些标准，我们考虑添加对测试依赖 Pydantic 的新开源项目的支持

  • 该项目正在积极维护中。
  • 该项目使用了 Pydantic 内部组件（例如，依赖于BaseModel元类、类型实用程序）。
  • 该项目足够流行（尽管小型项目仍然可以根据 Pydantic 的使用方式而包含在内）。
  • 该项目的 CI 足够简单，可以移植到 Pydantic 的测试工作流程中。

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