跳转到内容

版本策略

首先，我们认识到从 Pydantic V1 到 V2 的过渡已经并将会给一些用户带来痛苦。我们对这种痛苦深表歉意 🙏，但这是纠正 V1 设计错误所必需且不幸的一步。

未来不会再有如此大规模的破坏性变更！

Pydantic V1

V1 的积极开发已经停止，但关键的错误修复和安全漏洞将在 V1 中得到修复，直到 Pydantic V3 发布。

Pydantic V2

我们不会在 V2 的次要版本中故意引入破坏性变更。

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

当然，一些看似安全的变更和错误修复将不可避免地破坏某些用户的代码——这里必须链接到 xkcd。

以下变更将不被视为破坏性变更，并可能在次要版本中出现：

  • 可能导致现有代码中断的错误修复，前提是这些代码依赖于未文档化的功能/构造。
  • 更改 JSON Schema 引用的格式。
  • 更改 ValidationError 异常的 msg、ctx 和 loc 字段。type 字段不会改变——如果您需要以编程方式解析错误消息，您应该使用 type。
  • 向 ValidationError 异常中添加新的键——例如，我们打算在迁移到新的 JSON 解析器后，为验证 JSON 时的错误添加 line_number 和 column_number。
  • 添加新的 ValidationError 错误类型。
  • 更改 __repr__ 的行为，即使是公共类的 __repr__。
  • 核心模式的内容（对于 Pydantic 模型，通常在

__pydantic_core_schema__ 属性下可用；对于 类型适配器，则在 core_schema 下可用）可能会在不同版本之间发生变化（这是 Pydantic 用于规划如何执行验证和序列化的底层格式）。

在所有情况下，我们都会尽量减少变动，并且只有在能够为用户显著提升 Pydantic 质量时才会这样做。

Pydantic V3 及更高版本

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

实验性功能

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

使用文档

要了解我们当前的实验性功能，请参阅实验性功能文档。

请记住，实验性功能是正在积极开发中的工作。如果这些功能成功，它们最终将成为 Pydantic 的一部分。如果不成功，这些功能将被移除，且几乎不会提前通知。在实验阶段，一个功能的 API 和行为可能不稳定，并且对该功能所做的更改很可能不向后兼容。

命名约定

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

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

    from pydantic.experimental import feature_name

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

具有这些命名约定的新功能可能会发生变化或被移除，我们希望在将其永久纳入 Pydantic 之前收集反馈和建议。更多信息请参见反馈部分。

实验性功能的生命周期

  1. 一个新功能被添加，要么在 experimental 模块中，要么带有 experimental_ 前缀。
  2. 其行为通常在补丁/次要版本中被修改，可能会有 API/行为的变更。

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

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

    b. 在某个时候，实验性功能部分的代码会被移除，但仍然会保留一个该功能的存根（stub），它会提供一个包含适当说明的错误消息。

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

如果该功能不成功或不受欢迎，它将被移除，且几乎不会提前通知。在已弃用功能的位置会保留一个存根，并提供一条错误消息。

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

对 Python 版本的支持

Pydantic 将在满足以下条件时放弃对某个 Python 版本的支持：