跳到内容

贡献

我们欢迎您为 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.sh/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 文档中的文档字符串的更改），请确保它可以成功构建。

我们使用 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，并创建一个拉取请求。

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

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

文档风格

文档以 Markdown 编写，并使用 Material for MkDocs 构建。 API 文档从文档字符串中使用 mkdocstrings 构建。

代码文档

在为 Pydantic 做出贡献时，请确保所有代码都得到良好记录。以下内容应使用格式正确的文档字符串进行记录

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

Pydantic 使用 Google 风格的文档字符串，并根据 PEP 257 指南进行格式化。（有关更多示例，请参阅 Google 风格 Python 文档字符串示例。）

pydocstyle 用于代码检查文档字符串。您可以运行 make format 来检查您的文档字符串。

如果 Google 风格的文档字符串和 pydocstyle 代码检查之间存在冲突，请遵循 pydocstyle 代码检查提示。

类属性和函数参数应以“名称：描述”的格式记录。如果适用，则应仅使用描述来记录返回类型。类型从签名中推断出来。

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'

您可以在文档字符串中包含示例代码。此代码应完整、独立且可运行。文档字符串示例经过测试，因此请确保它们正确且完整。有关示例，请参阅 FieldInfo.from_annotated_attribute。

类和实例属性

类属性应在类文档字符串中记录。

实例属性应在 __init__ 文档字符串中记录为“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 的测试工作流程中。

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