跳到内容

版本策略

首先，我们认识到从 Pydantic V1 到 V2 的过渡对于一些用户来说已经并将会是痛苦的。对于由此带来的不便，我们深感抱歉 🙏，这是为了纠正 V1 的设计错误而采取的一个不幸但必要的步骤。

不会再有如此大规模的破坏性更改！

Pydantic V1

V1 的活跃开发已经停止，但是，在 Pydantic V3 发布之前，V1 中仍会修复关键错误和安全漏洞。

Pydantic V2

我们不会在 V2 的小版本发布中故意进行破坏性更改。

标记为已弃用的功能在下一个 V3 主要版本发布之前不会被移除。

当然，一些看似安全的更改和错误修复不可避免地会破坏一些用户的代码——此处必须链接到 xkcd。

以下更改将不被视为破坏性更改，并可能在小版本发布中发生

  • 更改 JSON Schema 引用的格式。
  • 更改 ValidationError 异常的 msg、ctx 和 loc 字段。type 不会更改——如果您以编程方式解析错误消息，则应使用 type。
  • 向 ValidationError 异常添加新键——例如，我们计划在迁移到新的 JSON 解析器后，在验证 JSON 时向错误添加 line_number 和 column_number。
  • 添加新的 ValidationError 错误。
  • 更改 __repr__ 的行为方式，即使是公共类也是如此。

在所有情况下，我们都将致力于最大限度地减少变动，并且仅在为了提高 Pydantic 对用户的质量而有必要时才这样做。

Pydantic V3 及更高版本

我们预计未来每年大约发布一次新的主要版本，尽管如上所述，与 V1 到 V2 的过渡相比，任何相关的破坏性更改都应该很容易修复。

实验性功能

在 Pydantic，我们喜欢快速行动和创新！为此，我们可能会在小版本发布中引入实验性功能。

使用文档

要了解有关我们当前实验性功能的更多信息，请参阅实验性功能文档。

请记住，实验性功能是正在进行中的工作。如果这些功能成功，它们最终将成为 Pydantic 的一部分。如果失败，这些功能将在几乎没有通知的情况下被删除。在实验阶段，功能的 API 和行为可能不稳定，并且对功能所做的更改很可能不向后兼容。

命名约定

我们使用以下命名约定之一来指示某个功能是实验性的

  1. 该功能位于 experimental 模块中。在这种情况下，您可以像这样访问该功能

    from pydantic.experimental import feature_name

  2. 该功能位于主模块中，但以 experimental_ 为前缀。当我们向主 pydantic 模块中已有的现有数据结构添加新字段、参数或方法时，就会发生这种情况。

具有这些命名约定的新功能可能会被更改或删除，并且在我们将其永久纳入 Pydantic 之前，我们正在寻求反馈和建议。有关更多信息，请参阅反馈部分。

导入实验性功能

当您从 experimental 模块导入实验性功能时，您将看到一条警告消息，指出该功能是实验性的。您可以使用以下方法禁用此警告

import warnings

from pydantic import PydanticExperimentalWarning

warnings.filterwarnings('ignore', category=PydanticExperimentalWarning)

实验性功能的生命周期

  1. 添加了一个新功能，无论是在 experimental 模块中还是带有 experimental_ 前缀。
  2. 行为通常在补丁/小版本发布期间进行修改，可能会发生 API/行为更改。

  3. 如果该功能成功，我们将通过以下步骤将其升级到 Pydantic

    a. 如果它在 experimental 模块中，则该功能将被克隆到 Pydantic 的主模块中。原始实验性功能仍然保留在 experimental 模块中，但使用时会显示警告。如果该功能已在主 Pydantic 模块中，我们将创建该功能的副本，但不带 experimental_ 前缀，因此该功能将同时存在官方名称和实验性名称。弃用警告将附加到实验性版本。

    b. 在某个时候，实验性功能的代码将被删除，但仍将保留该功能的存根，其中提供带有适当说明的错误消息。

    c. 作为最后一步，该功能的实验性版本将完全从代码库中删除。

如果该功能不成功或不受欢迎，则会在几乎没有通知的情况下将其删除。存根将保留在已弃用功能的位置，并带有错误消息。

感谢 streamlit 为我们新的实验性功能模式的生命周期和命名约定提供的灵感。

Python 版本支持

当满足以下条件时，Pydantic 将停止支持某个 Python 版本