Visual Studio Code

Pydantic 可以与任何编辑器或 IDE 良好配合，因为它基于标准的 Python 类型注解构建。

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

这意味着即使在创建新的 Pydantic 模型实例时，您也将拥有自动完成（或“IntelliSense”）和类型及必需参数的错误检查。

pydantic autocompletion in VS Code

配置 VS Code¶

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

如果您有不同的配置，这里是步骤的简要概述。

安装 Pylance¶

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

Pylance 默认作为 Python Extension for VS Code 的一部分安装，因此它可能应该可以直接工作。否则，您可以仔细检查它是否已安装并在您的编辑器中启用。

配置您的环境¶

然后您需要确保您的编辑器知道您的 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 使用一个开源工具（也来自 Microsoft），称为 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' 的 str 对于参数 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()，则一开始可能会觉得很奇怪。

类参数中的 Config¶

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（在 beta 版中）具有特殊含义。

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

当使用第二个版本声明 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 用户，您不需要以下细节。请随意跳过本节的其余部分。

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

这种额外的编辑器支持通过实现数据类转换 (PEP 681) 的拟议草案标准来实现。

拟议的草案标准由 Microsoft 团队的 Eric Traut 撰写，他也是开源软件包 Pyright（Pylance 在 VS Code 中提供 Python 支持时使用）的作者。

该标准的目的是为 Pydantic 等库提供一种方式，告诉编辑器和工具，他们（编辑器）应该将这些库（例如 Pydantic）视为 dataclasses，提供自动完成、类型检查等。

草案标准还包括一个备用形式，供像 Pydantic 这样的早期采用者立即添加对其的支持，即使在新的草案标准完成和批准之前。

Pyright 已经支持这个新的草案标准及其备用形式，因此可以通过 VS Code 中的 Pylance 使用它。

由于它正在作为 Python 的官方标准提出，因此其他编辑器也可以轻松地添加对其的支持。

与 Pydantic 类似的库的作者也可以轻松地立即采用该标准（使用“备用形式”），并获得这些额外的编辑器功能的好处。