跳转至

贡献指南

我们非常希望你能为 Pydantic 做出贡献！

问题

欢迎提出问题、功能请求和错误报告，无论是作为讨论还是问题。但是，要报告安全漏洞，请参阅我们的安全策略。

为了让我们尽可能容易地帮助您，请在您的问题中包含以下调用的输出：

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

如果你在使用 Pydantic 之前的版本，请使用：

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

如果您在使用 Pydantic 时早于 v1.3（添加 version_info() 时），请手动包含 OS、Python 版本和 pydantic 版本。

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

拉取请求

开始和创建拉取请求应该极其简单。Pydantic 会定期发布，因此你应该在几天或几周内看到你的改进发布🚀。

除非你的更改是微不足道的（错别字、文档调整等），否则在创建拉取请求之前，请创建一个问题来讨论更改。

注意

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

To submit a fix to Pydantic v1, use the 1.10.X-fixes branch.

如果你正在寻找一些可以深入研究的东西，看看 github 上的“需要帮助”标签。

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

提示

太长不看：使用 make format 修复格式， make 运行测试和 linting 以及 make docs 构建文档。

Prerequisites

你需要以下先决条件：

  • Python 3.8 到 3.11 之间的任何 Python 版本

  • virtualenv 或其他虚拟环境工具

  • git
  • make
  • PDM

安装和设置

在 GitHub 上 Fork 这个仓库，然后在本地克隆你的 Fork。

# Clone your fork and cd into the repo directory
git clone git@github.com:<your username>/pydantic.git
cd pydantic

# Install PDM and pre-commit
# We use pipx here, for other options see:
# https://pdm.fming.dev/latest/#installation
# https://pre-commit.com/#install
# To get pipx itself:
# https://pypa.github.io/pipx/
pipx install pdm
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...

运行测试和 linting

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

# 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 文档中的文档字符串的更改），请确保它构建成功。

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

提交并推送你的更改

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

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

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

代码风格和要求

待办事项

文档风格

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

代码文档

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

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

Pydantic 使用符合 PEP 257 指南的 Google 风格文档字符串。（有关更多示例，请参阅示例 Google 风格 Python 文档字符串。）

pydocstyle 用于 linting 文档字符串。你可以运行 make format 来检查你的文档字符串。

如果 Google 风格的文档字符串与 pydocstyle lint 冲突，遵循 pydocstyle lint 的提示。

类属性和函数参数应以"名称：描述"的格式进行文档记录。在适用的情况下，应仅使用描述记录返回类型。类型是从签名推断出来的。

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'

你可以在文档字符串中包含示例代码。这些代码应该是完整的、自包含的并且可运行的。文档字符串示例使用 doctest 进行测试，因此请确保它们是正确和完整的。有关示例，请参见 pydantic.fields.FieldInfo.from_annotated_attribute()。

注意

“类和实例属性” 类属性应在类文档字符串中进行文档记录。

Instance attributes should be documented as "Args" in the __init__ docstring.

文档风格

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

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

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

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

调试 Python 和 Rust

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

Badges

Pydantic v1 Pydantic v2

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

With Markdown

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

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

使用 reStructuredText

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

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

With HTML

<a href="https://pydantic.com.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.com.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>
本文总阅读量次