别名

别名是字段的替代名称，用于序列化和反序列化数据。

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

Field 上的 alias
- 必须是 str 类型
Field 上的 validation_alias
- 可以是 str、AliasPath 或 AliasChoices 的实例
Field 上的 serialization_alias
- 必须是 str 类型
Config 上的 alias_generator
- 可以是可调用对象或 AliasGenerator 的实例

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

`AliasPath` 和 `AliasChoices`¶

API 文档

pydantic.aliases.AliasPath
pydantic.aliases.AliasChoices

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'}

使用 `AliasGenerator`¶

API 文档

pydantic.aliases.AliasGenerator

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。有关不同字段别名的更多信息，请参阅字段别名。

别名配置¶

你可以使用 ConfigDict 设置或运行时验证/序列化设置来控制是否使用别名。

`ConfigDict` 设置¶

你可以使用配置设置在模型级别控制是否对验证和序列化使用别名。如果你想控制嵌套模型/超越配置模型边界的这种行为，请使用运行时设置。

验证¶

验证数据时，你可以启用通过属性名称、别名或两者来填充属性。 默认情况下，Pydantic 使用别名进行验证。更多配置可通过以下方式获得

ConfigDict.validate_by_alias：默认 True
ConfigDict.validate_by_name：默认 False

validate_by_aliasvalidate_by_namevalidate_by_alias 和 validate_by_name

from pydantic import BaseModel, ConfigDict, Field


class Model(BaseModel):
    my_field: str = Field(validation_alias='my_alias')

    model_config = ConfigDict(validate_by_alias=True, validate_by_name=False)


print(repr(Model(my_alias='foo')))  # (1)!
#> Model(my_field='foo')

别名 my_alias 用于验证。

from pydantic import BaseModel, ConfigDict, Field


class Model(BaseModel):
    my_field: str = Field(validation_alias='my_alias')

    model_config = ConfigDict(validate_by_alias=False, validate_by_name=True)


print(repr(Model(my_field='foo')))  # (1)!
#> Model(my_field='foo')

属性标识符 my_field 用于验证。

from pydantic import BaseModel, ConfigDict, Field


class Model(BaseModel):
    my_field: str = Field(validation_alias='my_alias')

    model_config = ConfigDict(validate_by_alias=True, validate_by_name=True)


print(repr(Model(my_alias='foo')))  # (1)!
#> Model(my_field='foo')

print(repr(Model(my_field='foo')))  # (2)!
#> Model(my_field='foo')

别名 my_alias 用于验证。
属性标识符 my_field 用于验证。

警告

你不能将 validate_by_alias 和 validate_by_name 都设置为 False。在这种情况下会引发用户错误。

序列化¶

序列化数据时，你可以启用按别名序列化，默认情况下禁用此功能。有关更多详细信息，请参阅 ConfigDict.serialize_by_alias API 文档。

from pydantic import BaseModel, ConfigDict, Field


class Model(BaseModel):
    my_field: str = Field(serialization_alias='my_alias')

    model_config = ConfigDict(serialize_by_alias=True)


m = Model(my_field='foo')
print(m.model_dump())  # (1)!
#> {'my_alias': 'foo'}

别名 my_alias 用于序列化。

注意

默认情况下禁用按别名序列化这一事实与验证的默认设置（默认情况下使用别名）明显不一致。我们预计将在 V3 中更改此默认设置。

运行时设置¶

你可以使用运行时别名标志来控制每次调用时验证和序列化中别名的使用。如果你想在模型级别控制这种行为，请使用ConfigDict 设置。

验证¶

验证数据时，你可以启用通过属性名称、别名或两者来填充属性。

by_alias 和 by_name 标志在 model_validate()、model_validate_json() 和 model_validate_strings() 方法以及 TypeAdapter 验证方法中可用。

默认情况下

by_alias 为 True
by_name 为 False

by_aliasby_namevalidate_by_alias 和 validate_by_name

from pydantic import BaseModel, Field


class Model(BaseModel):
    my_field: str = Field(validation_alias='my_alias')


m = Model.model_validate(
    {'my_alias': 'foo'},  # (1)!
    by_alias=True,
    by_name=False,
)
print(repr(m))
#> Model(my_field='foo')

别名 my_alias 用于验证。

from pydantic import BaseModel, Field


class Model(BaseModel):
    my_field: str = Field(validation_alias='my_alias')


m = Model.model_validate(
    {'my_field': 'foo'}, by_alias=False, by_name=True  # (1)!
)
print(repr(m))
#> Model(my_field='foo')

属性名称 my_field 用于验证。

from pydantic import BaseModel, Field


class Model(BaseModel):
    my_field: str = Field(validation_alias='my_alias')


m = Model.model_validate(
    {'my_alias': 'foo'}, by_alias=True, by_name=True  # (1)!
)
print(repr(m))
#> Model(my_field='foo')

m = Model.model_validate(
    {'my_field': 'foo'}, by_alias=True, by_name=True  # (2)!
)
print(repr(m))
#> Model(my_field='foo')

别名 my_alias 用于验证。
属性名称 my_field 用于验证。

警告

你不能将 by_alias 和 by_name 都设置为 False。在这种情况下会引发用户错误。

序列化¶

序列化数据时，你可以通过 by_alias 标志启用按别名序列化，该标志在 model_dump() 和 model_dump_json() 方法以及 TypeAdapter 方法中可用。

默认情况下，by_alias 为 False。

from pydantic import BaseModel, Field


class Model(BaseModel):
    my_field: str = Field(serialization_alias='my_alias')


m = Model(my_field='foo')
print(m.model_dump(by_alias=True))  # (1)!
#> {'my_alias': 'foo'}

别名 my_alias 用于序列化。

注意

默认情况下禁用按别名序列化这一事实与验证的默认设置（默认情况下使用别名）明显不一致。我们预计将在 V3 中更改此默认设置。

别名

AliasPath 和 AliasChoices¶

使用别名生成器¶

使用可调用对象¶

使用 AliasGenerator¶

别名优先级¶

别名优先级¶

别名配置¶

ConfigDict 设置¶

验证¶

序列化¶

运行时设置¶

验证¶

序列化¶

`AliasPath` 和 `AliasChoices`¶

使用 `AliasGenerator`¶

`ConfigDict` 设置¶