Alias

别名是字段的备用名称，用于序列化和反序列化数据时使用。

你可以通过以下方式指定别名：

@pydantic.fields.Field 上的 [ Field ]
- 必须是一个 str
@pydantic.fields.Field 上的 [ Field ]
- 可以是 str 的实例， AliasPath 或 AliasChoices
@pydantic.fields.Field 上的 [ Field ]
- 必须是一个 str
在 Config 上的 alias_generator
- 可以是可调用的对象或 AliasGenerator 的实例。

有关如何使用 alias 、 validation_alias 和 serialization_alias 的示例，请参见字段别名。

`AliasPath` and `AliasChoices`¶

AliasPath 和 AliasChoices

“API 文档”

[`pydantic.aliases.AliasPath`][pydantic.aliases.AliasPath]<br>
[`pydantic.aliases.AliasChoices`][pydantic.aliases.AliasChoices]<br>

Pydantic 为了方便在使用 validation_alias 时提供了两种特殊类型： AliasPath 和 AliasChoices 。

AliasPath 用于使用别名指定字段的路径。例如：

from pydantic import BaseModel, Field, AliasPath


class User(BaseModel):
    first_name: str = Field(validation_alias=AliasPath('names', 0))
    last_name: str = Field(validation_alias=AliasPath('names', 1))

user = User.model_validate({'names': ['John', 'Doe']})  # (1)!
print(user)
#> first_name='John' last_name='Doe'

我们正在使用 model_validate 根据字段别名验证字典。

你可以在 API 参考中了解更多关于 model_validate 的详细信息。

在 'first_name' 字段中，我们使用别名 'names' 和索引 0 指定第一个名字的路径。在 'last_name' 字段中，我们使用别名 'names' 和索引 1 指定最后一个名字的路径。

AliasChoices 用于指定别名的选择。例如：

from pydantic import BaseModel, Field, AliasChoices


class User(BaseModel):
    first_name: str = Field(validation_alias=AliasChoices('first_name', 'fname'))
    last_name: str = Field(validation_alias=AliasChoices('last_name', 'lname'))

user = User.model_validate({'fname': 'John', 'lname': 'Doe'})  # (1)!
print(user)
#> first_name='John' last_name='Doe'
user = User.model_validate({'first_name': 'John', 'lname': 'Doe'})  # (2)!
print(user)
#> first_name='John' last_name='Doe'

我们正在对这两个字段使用第二个别名选择。
我们正在使用字段 'first_name' 的第一个别名选项和字段 'last_name' 的第二个别名选项。

你也可以使用 AliasChoices 和 AliasPath ：

from pydantic import BaseModel, Field, AliasPath, AliasChoices


class User(BaseModel):
    first_name: str = Field(validation_alias=AliasChoices('first_name', AliasPath('names', 0)))
    last_name: str = Field(validation_alias=AliasChoices('last_name', AliasPath('names', 1)))


user = User.model_validate({'first_name': 'John', 'last_name': 'Doe'})
print(user)
#> first_name='John' last_name='Doe'
user = User.model_validate({'names': ['John', 'Doe']})
print(user)
#> first_name='John' last_name='Doe'
user = User.model_validate({'names': ['John'], 'last_name': 'Doe'})
print(user)
#> first_name='John' last_name='Doe'

使用别名生成器¶

你可以使用 Config 的 alias_generator 参数指定一个可调用对象（或通过 AliasGenerator 指定一组可调用对象），该对象将为模型中的所有字段生成别名。如果你希望为模型中的所有字段使用一致的命名约定，但不想为每个字段单独指定别名，这将非常有用。

注意

Pydantic 提供了三个内置的别名生成器，您可以直接使用：

to_pascal
to_camel
to_snake

使用可调用对象¶

以下是使用可调用对象的基本示例：

from pydantic import BaseModel, ConfigDict


class Tree(BaseModel):
    model_config = ConfigDict(
        alias_generator=lambda field_name: field_name.upper()
    )

    age: int
    height: float
    kind: str


t = Tree.model_validate({'AGE': 12, 'HEIGHT': 1.2, 'KIND': 'oak'})
print(t.model_dump(by_alias=True))
#> {'AGE': 12, 'HEIGHT': 1.2, 'KIND': 'oak'}

Using an `AliasGenerator`¶

使用 AliasGenerator

API Documentation

pydantic.aliases.AliasGenerator

“API 文档”

[`pydantic.aliases.AliasGenerator`][pydantic.aliases.AliasGenerator]<br>

AliasGenerator 是一个类，它允许你为模型指定多个别名生成器。你可以使用 AliasGenerator 为验证和序列化指定不同的别名生成器。

如果您需要使用不同的命名约定来加载和保存数据，但不想为每个字段单独指定验证和序列化别名，那么这将特别有用。

例如：

from pydantic import AliasGenerator, BaseModel, ConfigDict


class Tree(BaseModel):
    model_config = ConfigDict(
        alias_generator=AliasGenerator(
            validation_alias=lambda field_name: field_name.upper(),
            serialization_alias=lambda field_name: field_name.title(),
        )
    )

    age: int
    height: float
    kind: str


t = Tree.model_validate({'AGE': 12, 'HEIGHT': 1.2, 'KIND': 'oak'})
print(t.model_dump(by_alias=True))
#> {'Age': 12, 'Height': 1.2, 'Kind': 'oak'}

别名优先级¶

如果在 Field 上指定了一个 alias ，则默认情况下它将优先于生成的别名：

from pydantic import BaseModel, ConfigDict, Field


def to_camel(string: str) -> str:
    return ''.join(word.capitalize() for word in string.split('_'))


class Voice(BaseModel):
    model_config = ConfigDict(alias_generator=to_camel)

    name: str
    language_code: str = Field(alias='lang')


voice = Voice(Name='Filiz', lang='tr-TR')
print(voice.language_code)
#> tr-TR
print(voice.model_dump(by_alias=True))
#> {'Name': 'Filiz', 'lang': 'tr-TR'}

别名优先级¶

你可以在字段上设置 alias_priority 来更改此行为：

alias_priority=2 别名不会被别名生成器覆盖。
alias_priority=1 别名将被别名生成器覆盖。
未设置： alias_priority
- 别名已设置：别名不会被别名生成器覆盖。
- 未设置别名：别名将被别名生成器覆盖。

validation_alias 和 serialization_alias 也具有相同的优先级。有关不同字段别名的更多信息，请参见字段别名。

本文总阅读量次

Alias

AliasPath and AliasChoices¶

使用别名生成器¶

使用可调用对象¶

Using an AliasGenerator¶

别名优先级¶

别名优先级¶

`AliasPath` and `AliasChoices`¶

Using an `AliasGenerator`¶