Alias

エイリアスはフィールドの別名で、データのシリアライズおよびデシリアライズ時に使用されます。

エイリアスは次の方法で指定できます。

• Fieldのalias
  • strでなければなりません。

• Fieldの*validation_alias
  • strのインスタンスで、AliasPath、またはAliasChoicesとなります。

• Fieldの*serialization_alias
  • strでなければなりません

• alias_generatorをConfig
  • 、AliasGeneratorの呼び出し可能オブジェクトまたはインスタンスです。

alias、validation_alias、およびserialization_aliasの使用例については、Field aliasesを参照してください。

AliasPath and AliasChoices

API Documentation

pydantic.aliases.AliasPath
pydantic.aliases.AliasChoices

Pydanticはvalidation_aliasを使用する際の利便性のために、AliasPathとAliasChoicesという2つの特別な型を提供しています。

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'

1. フィールドエイリアスを使用して辞書を検証するためにmodel_validateを使用しています。 model_validateの詳細については、APIリファレンスを参照してください。

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

1. 両方のフィールドに2番目のエイリアスを使用しています。

1. フィールド'first_name'に最初のエイリアス選択を使用し、フィールド'last_name'に2番目のエイリアス選択を使用しています。

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'

Using alias generators

Configのalias_generatorパラメータを使用して、モデル内のすべてのフィールドのエイリアスを生成する呼び出し可能オブジェクト(またはAliasGeneratorによる呼び出し可能オブジェクトのグループ)を指定できます。 これは、モデル内のすべてのフィールドに対して一貫した命名規則を使用し、各フィールドに個別にエイリアスを指定しない場合に便利です。

Note

Pydanticには、すぐに使用できる3つの組み込みエイリアスジェネレータが用意されています。

to_pascal
to_camel
to_snake

Using a callable

次に、callableを使用した基本的な例を示します。

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

API Documentation

pydantic.aliases.AliasGenerator

AliasGeneratorは、1つのモデルに複数のエイリアスジェネレータを指定できるクラスです。 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'}

Alias Precedence

If you specify an alias on the Field, it will take precedence over the generated alias by default:

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を設定します。

• alias_priority=2エイリアスはエイリアスジェネレータによって上書きされません。

• alias_priority=1エイリアスはエイリアスジェネレータによって上書きされます。

• alias_priorityが設定されない:
  • aliasの設定: エイリアスはエイリアスジェネレータによって上書きされません。
  • aliasの未設定: エイリアスはエイリアスジェネレータによってオーバーライドされます。

同じ優先順位がvalidation_aliasとserialization_aliasにも適用されます。 さまざまなフィールドエイリアスの詳細については、field aliasesを参照してください。