Visual Studio Code

Pydantic 在开箱即用的任何编辑器或 IDE 中都能很好地工作，因为它是在标准 Python 类型注释之上构建的。

使用 Visual Studio Code（VS Code）时，还支持一些其他的编辑器功能，这些功能可与 PyCharm 插件提供的功能相媲美。

这意味着，即使在创建新的 Pydantic 模型实例时，您也将获得自动完成（或“智能感知”）和对类型和必需参数的错误检查。

pydantic autocompletion in VS Code

配置 VS 代码¶

要利用这些功能，您需要确保正确配置 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 代码扩展，它是闭源的，但可以免费使用。在其内部，Pylance 使用了一个开源工具（也来自微软），名为 Pyright，它承担了所有繁重的工作。

You can read more about it in the Pylance Frequently Asked Questions.

配置 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 模型实例时，它将对传入的参数的数据类型进行严格的类型错误检查。

在这个示例中，您可以看到，对于参数 age ， str 的 '23' 不是有效的 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 ，就好像它们不知道它的类型一样，而不是在期望 int 时知道它的类型为 str （然后显示相应的错误）。

优点：只会忽略特定值的错误，对于其他参数仍然会看到任何其他错误。

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

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

借助 cast() ，可以将上一个示例中的相同思路放在同一行中。

这样，就可以在-inline 中覆盖该值的类型声明，而无需使用其他变量。

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 用户，您不需要以下详细信息。请随意跳过本节的其余部分。

These details are only useful for other library authors, etc.

此额外的编辑器支持通过实现提议的数据类转换草案标准（PEP 681）来工作。

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

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

该草案标准还包括一个备选形式，供早期采用者（如 Pydantic）使用，以便在新草案标准完成和批准之前立即添加对其的支持。

此新的草案标准，连同备用形式，已经得到 Pyright 的支持，因此可以通过 VS Code 中的 Pylance 使用。

随着它被提议作为 Python 的官方标准，其他编辑器也可以很容易地添加对它的支持。

其他类似 Pydantic 的库的作者也可以很容易地采用这种标准（使用“备选形式”），并获得这些额外的编辑器功能的好处。

本文总阅读量次