Visual Studio Code

Pydantic 基于标准的 Python 类型注解构建，因此它与任何编辑器或 IDE 都能很好地兼容。

当使用 Visual Studio Code (VS Code) 时，有一些 额外的编辑器功能 支持，类似于 PyCharm 插件提供。

这意味着即使在创建新的 Pydantic 模型实例时，您也将获得 自动补全（或“IntelliSense”）以及针对类型和必需参数的 错误检查。

pydantic autocompletion in VS Code

配置 VS Code¶

要利用这些功能，您需要确保使用推荐的设置正确配置 VS Code。

如果您有不同的配置，这里有一个简短的步骤概述。

安装 Pylance¶

您应该使用 VS Code 的 Pylance 扩展。它是推荐的、下一代、官方的 Python 版 VS Code 插件。

Pylance 默认作为 VS Code 的 Python 扩展的一部分安装，因此它应该可以直接使用。否则，您可以双重检查它是否已在您的编辑器中安装并启用。

配置您的环境¶

然后，您需要确保您的编辑器知道您的 Python 项目的 Python 环境（可能是一个虚拟环境）。

这将是您安装 Pydantic 的环境。

配置 Pylance¶

使用默认配置，您将获得自动补全支持，但 Pylance 可能不会检查类型错误。

您可以按照以下步骤从 Pylance 启用类型错误检查：

打开“用户设置”
搜索 Type Checking Mode
您将在 Python › Analysis: Type Checking Mode 下找到一个选项
将其设置为 basic 或 strict（默认值为 off）

Type Checking Mode set to strict in VS Code

现在，当您创建新的 Pydantic 模型实例时，您不仅会获得自动补全，还会获得 必需参数 的错误检查。

Required arguments error checks in VS Code

您还将获得 无效数据类型 的错误检查。

Invalid data types error checks in VS Code

技术细节

Pylance 是 VS Code 扩展，它是闭源的，但免费使用。Pylance 在底层使用一个开源工具（也来自微软），名为 Pyright，它完成了所有的繁重工作。

您可以在 Pylance 常见问题中阅读更多内容。

配置 mypy¶

您可能还希望在 VS Code 中配置 mypy，以在编辑器中获取 mypy 错误检查（替代/附加于 Pylance）。

如果您配置了 Pydantic mypy 插件，这将包括它检测到的错误。

要在 VS Code 中启用 mypy，请执行以下操作：

打开“用户设置”
搜索 Mypy Enabled
您将在 Python › Linting: Mypy Enabled 下找到一个选项
勾选该框（默认情况下未勾选）

mypy enabled in VS Code

提示与技巧¶

以下是一些额外的提示和技巧，可以改善您在使用 VS Code 与 Pydantic 时的开发体验。

严格错误¶

这种额外的编辑器支持的工作方式是 Pylance 会将您的 Pydantic 模型视为纯 Python 的 dataclasses。

在创建新的 Pydantic 模型实例时，它将显示有关作为参数传入的数据类型的 严格类型错误检查。

在这个例子中，您可以看到它显示了 '23' 字符串对于参数 age 来说不是有效的 int。

VS Code strict type errors

它期望 age=23 而不是 age='23'。

然而，Pydantic 的设计以及主要特点之一是它对 数据类型非常宽容。

它实际上会接受值为 '23' 的 str，并将其转换为值为 23 的 int。

这些严格的错误检查在大多数情况下都 非常有用，可以帮助您 及早发现许多错误。但也有一些情况，例如 age='23'，它们可能会报告“误报”错误，从而带来不便。

上面 age='23' 的例子是故意简单的，旨在显示错误和类型差异。

但更常见的情况是，当使用更复杂的数据类型时，例如 datetime 字段的 int 值，或 Pydantic 子模型的 dict 值，这些严格错误会带来不便。

例如，这对于 Pydantic 是有效的：

from pydantic import BaseModel


class Knight(BaseModel):
    title: str
    age: int
    color: str = 'blue'


class Quest(BaseModel):
    title: str
    knight: Knight


quest = Quest(
    title='To seek the Holy Grail', knight={'title': 'Sir Lancelot', 'age': 23}
)

字段 knight 的类型使用类 Knight（一个 Pydantic 模型）声明，而代码传入的是一个字面量 dict。这对于 Pydantic 仍然是有效的，dict 将自动转换为 Knight 实例。

然而，它将被检测为类型错误：

VS Code strict type errors with model

在这些情况下，有几种方法可以在非常特定的位置禁用或忽略严格错误，同时在代码的其余部分保留它们。

下面是实现它的几种技术。

禁用行内类型检查¶

您可以使用以下注释禁用特定行的错误：

# type: ignore

或者（针对 Pylance/Pyright 特定）：

# pyright: ignore

（pyright 是 Pylance 使用的语言服务器。）

回到 age='23' 的例子，它会是：

from pydantic import BaseModel


class Knight(BaseModel):
    title: str
    age: int
    color: str = 'blue'


lancelot = Knight(title='Sir Lancelot', age='23')  # pyright: ignore

这样 Pylance 和 mypy 将忽略该行中的错误。

优点：只需对该行进行简单更改即可消除错误。

缺点：该行中的任何其他错误也将被忽略，包括类型检查、拼写错误的参数、未提供的必需参数等。

覆盖变量类型¶

您还可以创建一个变量，其中包含您想要使用的值，并使用 Any 明确声明其类型。

from typing import Any

from pydantic import BaseModel


class Knight(BaseModel):
    title: str
    age: int
    color: str = 'blue'


age_str: Any = '23'
lancelot = Knight(title='Sir Lancelot', age=age_str)

这样，Pylance 和 mypy 会将变量 age_str 解释为它们不知道其类型，而不是知道它具有 str 类型而预期为 int（然后显示相应的错误）。

优点：错误将仅针对特定值被忽略，您仍然会看到其他参数的任何附加错误。

缺点：它需要为每个需要忽略错误的参数导入 Any 并在新行中定义新变量。

使用 `cast` 覆盖值的类型¶

上一个示例中的相同想法可以借助 cast() 放在同一行。

这样，值的类型声明可以在行内被覆盖，而无需另一个变量。

from typing import Any, cast

from pydantic import BaseModel


class Knight(BaseModel):
    title: str
    age: int
    color: str = 'blue'


lancelot = Knight(title='Sir Lancelot', age=cast(Any, '23'))

cast(Any, '23') 不影响值，它仍然只是 '23'，但现在 Pylance 和 mypy 将假定它是 Any 类型，这意味着它们将表现得好像它们不知道值的类型一样。

因此，这与上一个示例等效，只是没有额外的变量。

优点：错误将仅针对特定值被忽略，您仍然会看到其他参数的任何附加错误。无需额外的变量。

缺点：它需要导入 Any 和 cast，如果您不习惯使用 cast()，一开始可能会觉得奇怪。

类参数中的配置¶

Pydantic 提供了丰富的模型配置。

这些配置可以在每个模型的内部 class Config 中设置：

from pydantic import BaseModel


class Knight(BaseModel):
    model_config = dict(frozen=True)
    title: str
    age: int
    color: str = 'blue'

或在定义模型类时作为关键字参数传入：

from pydantic import BaseModel


class Knight(BaseModel, frozen=True):
    title: str
    age: int
    color: str = 'blue'

特定配置 frozen（测试版）具有特殊含义。

它阻止其他代码在模型实例创建后更改它，使其保持 “冻结” 状态。

当使用第二种方式声明 frozen=True（在类定义中带有 关键字参数）时，Pylance 可以用它来帮助您在代码中检查并 检测错误，当某些东西试图在一个“冻结”的模型中设置值时。

VS Code strict type errors with model

使用 `Field` 添加默认值¶

Pylance/pyright 要求 default 成为 Field 的关键字参数，以便推断该字段是可选的。

from pydantic import BaseModel, Field


class Knight(BaseModel):
    title: str = Field(default='Sir Lancelot')  # this is okay
    age: int = Field(
        23
    )  # this works fine at runtime but will case an error for pyright


lance = Knight()  # error: Argument missing for parameter "age"

这是数据类转换的一个限制，无法在 Pydantic 中修复。

技术细节¶

警告

作为 Pydantic 用户，您不需要以下详细信息。请随意跳过本节的其余部分。

这些细节仅对其他库作者等有用。

这种额外的编辑器支持通过利用 @dataclass_transform 装饰器（由 PEP 681 引入）来实现。

该标准提供了一种方法，让 Pydantic 等库告诉编辑器和工具，它们（编辑器）应该将这些库（例如 Pydantic）视为数据类，从而提供自动补全、类型检查等功能。