Fields

API Documentation

pydantic.fields.Field

Field関数は、モデルのフィールドをカスタマイズし、メタデータを追加するために使用されます。

Default values¶

defaultパラメータは、フィールドのデフォルト値を定義するために使用されます。

from pydantic import BaseModel, Field


class User(BaseModel):
    name: str = Field(default='John Doe')


user = User()
print(user)
#> name='John Doe'

default_factoryを使用して、デフォルト値を生成するために呼び出される呼び出し可能オブジェクトを定義することもできます。

from uuid import uuid4

from pydantic import BaseModel, Field


class User(BaseModel):
    id: str = Field(default_factory=lambda: uuid4().hex)

Info

defaultパラメータとdefault_factoryパラメータは互いに排他的です。

Note

typing.Optionalを使用しても、フィールドのデフォルト値がNoneになるわけではありません。

Using `Annotated`¶

Field関数は、Annotatedと一緒に使用することもできます。

from uuid import uuid4

from typing_extensions import Annotated

from pydantic import BaseModel, Field


class User(BaseModel):
    id: Annotated[str, Field(default_factory=lambda: uuid4().hex)]

Note

デフォルトは、割り当てられた値としてAnnotatedの外に設定するか、Annotated内のField.default_factoryで設定できます。Field.default引数はAnnotated内ではサポートされていません。

Field aliases¶

検証とシリアライゼーションのために、フィールドのエイリアスを定義できます。

エイリアスを定義するには、次の3つの方法があります。

Field(..., alias='foo')
Field(..., validation_alias='foo')
Field(..., serialization_alias='foo')

aliasパラメータは、validation_と_serializationの両方に使用されます。検証とシリアライゼーションにそれぞれ_different_aliasesを使用する場合は、それぞれのユースケースにのみ適用されるvalidation_aliasパラメータとserialization_aliasパラメータを使用できます。

以下にaliasパラメータの使用例を示します。

from pydantic import BaseModel, Field


class User(BaseModel):
    name: str = Field(..., alias='username')


user = User(username='johndoe')  # (1)!
print(user)
#> name='johndoe'
print(user.model_dump(by_alias=True))  # (2)!
#> {'username': 'johndoe'}

エイリアス"username"`は、インスタンスの作成と検証に使用されます。

モデルをシリアライズ可能なフォーマットに変換するためにmodel_dumpを使用しています。

model_dumpの詳細については、APIリファレンスを参照してください。

by_aliasキーワード引数のデフォルトはFalseであり、フィールド(シリアライゼーション)エイリアスを使用してモデルをダンプするには明示的に指定する必要があることに注意してください。

by_alias=Trueの場合、シリアル化の際にエイリアス'username'も使用されます。

検証にalias_only_を使用する場合は、validation_aliasパラメータを使用します。

from pydantic import BaseModel, Field


class User(BaseModel):
    name: str = Field(..., validation_alias='username')


user = User(username='johndoe')  # (1)!
print(user)
#> name='johndoe'
print(user.model_dump(by_alias=True))  # (2)!
#> {'name': 'johndoe'}

検証エイリアス'username'は、検証中に使用されます。

フィールド名'name'はシリアル化の際に使用されます。

_serialization_のエイリアスのみを定義する場合は、serialization_aliasパラメータを使用できます。

from pydantic import BaseModel, Field


class User(BaseModel):
    name: str = Field(..., serialization_alias='username')


user = User(name='johndoe')  # (1)!
print(user)
#> name='johndoe'
print(user.model_dump(by_alias=True))  # (2)!
#> {'username': 'johndoe'}

The field name 'name' is used for validation.

シリアル化には、シリアル化エイリアス'username'が使用されます。

エイリアスの優先順位

aliasをvalidation_aliasまたはserialization_aliasと同時に使用した場合、検証ではvalidation_aliasがaliasより優先され、シリアライズではserialization_aliasがaliasより優先されます。

Model Configでalias_generatorを使用する場合、alias_priority設定を使用して、指定されたフィールドと生成されたエイリアスの優先順位を制御できます。エイリアスの優先順位の詳細については、ここを参照してください。

VSCodeとPyrightのユーザ

VSCodeでは、Pylance拡張を使用すると、フィールドのエイリアスを使用してモデルをインスタンス化するときに警告が表示されません。

from pydantic import BaseModel, Field


class User(BaseModel):
    name: str = Field(..., alias='username')


user = User(username='johndoe')  # (1)!

1. VSCodeはここでは警告を表示しません。

'alias'キーワード引数が指定されている場合、Model Configでpopulate_by_nameをTrueに設定しても、VSCodeはフィールド名を使用してモデルをインスタンス化するときに警告を表示します(ただし、実行時には機能します)。この場合は'name':

from pydantic import BaseModel, ConfigDict, Field


class User(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    name: str = Field(..., alias='username')


user = User(name='johndoe')  # (1)!

1. VSCodeはここに警告を表示します。

VSCodeを"だまして"フィールド名を優先させるには、str関数を使用してエイリアス値をラップします。ただし、この方法では、フィールドのエイリアスを使用してモデルをインスタンス化するときに警告が表示されます。

from pydantic import BaseModel, ConfigDict, Field


class User(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    name: str = Field(..., alias=str('username'))  # noqa: UP018


user = User(name='johndoe')  # (1)!
user = User(username='johndoe')  # (2)!

1. VSCodeは警告を表示しません。 2. VSCodeはここで警告を表示します。

この問題については、ここでより詳細に議論されています。

Validation Alias¶

Pydanticはモデルインスタンスを作成するときにaliasとvalidation_aliasを同じように扱いますが、VSCodeはクラスイニシャライザシグネチャでvalidation_aliasを使用しません。VSCodeがクラスイニシャライザでvalidation_aliasを使用するようにしたい場合は、代わりにaliasとserialization_aliasの両方を指定できます。これは、serialization_aliasがシリアライゼーション中にaliasをオーバーライドするためです。

from pydantic import BaseModel, Field


class MyModel(BaseModel):
    my_field: int = Field(..., validation_alias='myValidationAlias')

ここで:

from pydantic import BaseModel, Field


class MyModel(BaseModel):
    my_field: int = Field(
        ...,
        alias='myValidationAlias',
        serialization_alias='my_serialization_alias',
    )


m = MyModel(myValidationAlias=1)
print(m.model_dump(by_alias=True))
#> {'my_serialization_alias': 1}

上記のすべては、Pyrightなど、@typing.dataclass_transformデコレータを尊重する他のツールにも適用される可能性があります。

エイリアスの使用方法の詳細については、Aliasconceptsページを参照してください。

Numeric Constraints¶

数値の制約に使用できるキーワード引数がいくつかあります。

gt - より大きい
lt - より小さい
ge - より大きいか等しい
le - より小さいか等しい
multiple_of - 与えられた数の倍数
allow_inf_nan - 'inf'、'-inf'、'nan'の値を許可します。

次に例を示します。

from pydantic import BaseModel, Field


class Foo(BaseModel):
    positive: int = Field(gt=0)
    non_negative: int = Field(ge=0)
    negative: int = Field(lt=0)
    non_positive: int = Field(le=0)
    even: int = Field(multiple_of=2)
    love_for_pydantic: float = Field(allow_inf_nan=True)


foo = Foo(
    positive=1,
    non_negative=0,
    negative=-1,
    non_positive=0,
    even=2,
    love_for_pydantic=float('inf'),
)
print(foo)
"""
positive=1 non_negative=0 negative=-1 non_positive=0 even=2 love_for_pydantic=inf
"""

JSON Schema

生成されたJSONスキーマでは、次のようになります。

- gtとltの制約はexclusiveMinimumとexclusiveMaximumに変換されます。 - geとleの制約はminimumとmaximumに変換されます。 - multiple_of制約はmultipleOfに変換されます。

上記のスニペットは、次のJSONスキーマを生成します。

{
  "title": "Foo",
  "type": "object",
  "properties": {
    "positive": {
      "title": "Positive",
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "non_negative": {
      "title": "Non Negative",
      "type": "integer",
      "minimum": 0
    },
    "negative": {
      "title": "Negative",
      "type": "integer",
      "exclusiveMaximum": 0
    },
    "non_positive": {
      "title": "Non Positive",
      "type": "integer",
      "maximum": 0
    },
    "even": {
      "title": "Even",
      "type": "integer",
      "multipleOf": 2
    },
    "love_for_pydantic": {
      "title": "Love For Pydantic",
      "type": "number"
    }
  },
  "required": [
    "positive",
    "non_negative",
    "negative",
    "non_positive",
    "even",
    "love_for_pydantic"
  ]
}

詳細については、JSON Schema Draft 2020-12を参照してください。

Constraints on compound types

複合型でフィールド制約を使用すると、場合によってはエラーが発生することがあります。潜在的な問題を避けるために、Annotatedを使用することができます。

from typing import Optional

from typing_extensions import Annotated

from pydantic import BaseModel, Field


class Foo(BaseModel):
    positive: Optional[Annotated[int, Field(gt=0)]]
    # Can error in some cases, not recommended:
    non_negative: Optional[int] = Field(ge=0)

String Constraints¶

API Documentation

pydantic.types.StringConstraints

文字列の制約に使用できるフィールドは次のとおりです。

min_length: 文字列の最小の長さ。
max_length: 文字列の最大長。
pattern: 文字列が一致しなければならない正規表現。

次に例を示します。

from pydantic import BaseModel, Field


class Foo(BaseModel):
    short: str = Field(min_length=3)
    long: str = Field(max_length=10)
    regex: str = Field(pattern=r'^\d*$')  # (1)!


foo = Foo(short='foo', long='foobarbaz', regex='123')
print(foo)
#> short='foo' long='foobarbaz' regex='123'

数字のみを使用できます。

JSON Schema

生成されたJSONスキーマでは、次のようになります。

- min_length制約はminLengthに変換されます。 - max_length制約はmaxLengthに変換されます。 - pattern制約はpatternに変換されます。

上記のスニペットは、次のJSONスキーマを生成します。

{
  "title": "Foo",
  "type": "object",
  "properties": {
    "short": {
      "title": "Short",
      "type": "string",
      "minLength": 3
    },
    "long": {
      "title": "Long",
      "type": "string",
      "maxLength": 10
    },
    "regex": {
      "title": "Regex",
      "type": "string",
      "pattern": "^\\d*$"
    }
  },
  "required": [
    "short",
    "long",
    "regex"
  ]
}

Decimal Constraints¶

There are fields that can be used to constrain decimals: 小数点以下の桁数を制限するために使用できるフィールドがあります。

max_digits: Decimal内の最大桁数。小数点の前のゼロや小数点以下のゼロは含まれません。
decimal_places: 小数点以下の最大桁数です。小数点以下のゼロは含まれません。

次に例を示します。

from decimal import Decimal

from pydantic import BaseModel, Field


class Foo(BaseModel):
    precise: Decimal = Field(max_digits=5, decimal_places=2)


foo = Foo(precise=Decimal('123.45'))
print(foo)
#> precise=Decimal('123.45')

Dataclass Constraints¶

データクラスの制約に使用できるフィールドは次のとおりです。

init: フィールドをデータクラスの__init__に含めるかどうか。
init_var: そのフィールドをデータクラスの[init-onlyフィールド]として見るかどうか。
kw_only: フィールドがデータクラスのコンストラクタでキーワードのみの引数であるべきかどうか。

次に例を示します。

from pydantic import BaseModel, Field
from pydantic.dataclasses import dataclass


@dataclass
class Foo:
    bar: str
    baz: str = Field(init_var=True)
    qux: str = Field(kw_only=True)


class Model(BaseModel):
    foo: Foo


model = Model(foo=Foo('bar', baz='baz', qux='qux'))
print(model.model_dump())  # (1)!
#> {'foo': {'bar': 'bar', 'qux': 'qux'}}

bazフィールドはinit-onlyフィールドなので、model_dump()の出力には含まれません。

Validate Default Values¶

パラメータvalidate_defaultを使用して、フィールドのデフォルト値を検証するかどうかを制御できます。

デフォルトでは、フィールドのデフォルト値は検証されません。

from pydantic import BaseModel, Field, ValidationError


class User(BaseModel):
    age: int = Field(default='twelve', validate_default=True)


try:
    user = User()
except ValidationError as e:
    print(e)
    """
    1 validation error for User
    age
      Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='twelve', input_type=str]
    """

Field Representation¶

パラメータreprを使用して、フィールドをモデルの文字列表現に含めるかどうかを制御できます。

from pydantic import BaseModel, Field


class User(BaseModel):
    name: str = Field(repr=True)  # (1)!
    age: int = Field(repr=False)


user = User(name='John', age=42)
print(user)
#> name='John'

これがデフォルト値です。

Discriminator¶

パラメータdiscriminatorを使用して、共用体の異なるモデルを区別するために使用されるフィールドを制御できます。これは、フィールドの名前またはDiscriminatorインスタンスのいずれかを取ります。Discriminatorアプローチは、Union内のすべてのモデルに対して識別子フィールドが同じでない場合に便利です。

次の例は、フィールド名と共にdiscriminatorを使用する方法を示しています。

from typing import Literal, Union

from pydantic import BaseModel, Field


class Cat(BaseModel):
    pet_type: Literal['cat']
    age: int


class Dog(BaseModel):
    pet_type: Literal['dog']
    age: int


class Model(BaseModel):
    pet: Union[Cat, Dog] = Field(discriminator='pet_type')


print(Model.model_validate({'pet': {'pet_type': 'cat', 'age': 12}}))  # (1)!
#> pet=Cat(pet_type='cat', age=12)

Helper Functionsの詳細については、Modelsページを参照してください。

次の例は、Discriminatorインスタンスでdiscriminatorキーワード引数を使用する方法を示しています。

from typing import Literal, Union

from typing_extensions import Annotated

from pydantic import BaseModel, Discriminator, Field, Tag


class Cat(BaseModel):
    pet_type: Literal['cat']
    age: int


class Dog(BaseModel):
    pet_kind: Literal['dog']
    age: int


def pet_discriminator(v):
    if isinstance(v, dict):
        return v.get('pet_type', v.get('pet_kind'))
    return getattr(v, 'pet_type', getattr(v, 'pet_kind', None))


class Model(BaseModel):
    pet: Union[Annotated[Cat, Tag('cat')], Annotated[Dog, Tag('dog')]] = Field(
        discriminator=Discriminator(pet_discriminator)
    )


print(repr(Model.model_validate({'pet': {'pet_type': 'cat', 'age': 12}})))
#> Model(pet=Cat(pet_type='cat', age=12))

print(repr(Model.model_validate({'pet': {'pet_kind': 'dog', 'age': 12}})))
#> Model(pet=Dog(pet_kind='dog', age=12))

Annotatedを利用して、区別された共用体を定義することもできます。詳細については、Discriminated Unionsドキュメントを参照してください。

Strict Mode¶

Fieldのstrictパラメータは、そのフィールドを"strictモード"で検証するかどうかを指定します。 strictモードでは、Pydanticは検証中にstrict=Trueのフィールドにデータを強制するのではなく、エラーをスローします。

from pydantic import BaseModel, Field


class User(BaseModel):
    name: str = Field(strict=True)  # (1)!
    age: int = Field(strict=False)


user = User(name='John', age='42')  # (2)!
print(user)
#> name='John' age=42

これがデフォルト値です。

ageフィールドはstrictモードでは検証されません。したがって、文字列を割り当てることができます。

See Strict Mode for more details. 詳細については、Strict Modeを参照してください。

Pydanticがstrictモードとlaxモードの両方でデータを変換する方法の詳細については、Conversion Tableを参照してください。

Immutability¶

パラメータfrozenは、凍結されたデータクラスの動作をエミュレートするために使用されます。これは、モデルが作成された後にフィールドに新しい値が割り当てられないようにするために使用されます(不変性)。

詳細については、frozen dataclass documentationを参照してください。

from pydantic import BaseModel, Field, ValidationError


class User(BaseModel):
    name: str = Field(frozen=True)
    age: int


user = User(name='John', age=42)

try:
    user.name = 'Jane'  # (1)!
except ValidationError as e:
    print(e)
    """
    1 validation error for User
    name
      Field is frozen [type=frozen_field, input_value='Jane', input_type=str]
    """

nameフィールドが凍結されているため、割り当ては許可されません。

Exclude¶

excludeパラメータを使用して、モデルをエクスポートするときにモデルから除外するフィールドを制御できます。

次の例を参照してください。

from pydantic import BaseModel, Field


class User(BaseModel):
    name: str
    age: int = Field(exclude=True)


user = User(name='John', age=42)
print(user.model_dump())  # (1)!
#> {'name': 'John'}

ageフィールドは除外されているので、model_dump()の出力には含まれません。詳細については、Serializationセクションを参照してください。

Deprecated fields¶

deprecatedパラメータは、フィールドを非推奨としてマークするために使用できます。これにより、次のような結果になります。

フィールドへのアクセス時に発行される実行時の非推奨警告。
"deprecated": trueが生成されたJSONスキーマに設定されます。

deprecatedパラメータは以下のいずれかに設定できます。

非推奨メッセージとして使用される文字列。
warnings.deprecatedデコレータ(またはtyping_extensionsバックポート)のインスタンス。
ブール値。デフォルトの'deprecated'非推奨メッセージでフィールドを非推奨としてマークするために使用されます。

`deprecated` as a string¶

from typing_extensions import Annotated

from pydantic import BaseModel, Field


class Model(BaseModel):
    deprecated_field: Annotated[int, Field(deprecated='This is deprecated')]


print(Model.model_json_schema()['properties']['deprecated_field'])
#> {'deprecated': True, 'title': 'Deprecated Field', 'type': 'integer'}

`deprecated` via the `warnings.deprecated` decorator¶

Note

この方法でdeprecatedデコレータを使用できるのは、typing_extensions>=4.9.0がインストールされている場合だけです。

import importlib.metadata

from packaging.version import Version
from typing_extensions import Annotated, deprecated

from pydantic import BaseModel, Field

if Version(importlib.metadata.version('typing_extensions')) >= Version('4.9'):

    class Model(BaseModel):
        deprecated_field: Annotated[int, deprecated('This is deprecated')]

        # Or explicitly using `Field`:
        alt_form: Annotated[
            int, Field(deprecated=deprecated('This is deprecated'))
        ]

`deprecated` as a boolean¶

from typing_extensions import Annotated

from pydantic import BaseModel, Field


class Model(BaseModel):
    deprecated_field: Annotated[int, Field(deprecated=True)]


print(Model.model_json_schema()['properties']['deprecated_field'])
#> {'deprecated': True, 'title': 'Deprecated Field', 'type': 'integer'}

Support for category and stacklevel

この機能の現在の実装では、deprecatedデコレータのcategory引数とstacklevel引数は考慮されていません。これは将来のバージョンのPydanticに導入される可能性があります。

Accessing a deprecated field in validators

バリデータ内の非推奨フィールドにアクセスすると、非推奨警告が表示されます。catch_warningsを使用して、明示的に無視することができます。

import warnings

from typing_extensions import Self

from pydantic import BaseModel, Field, model_validator


class Model(BaseModel):
    deprecated_field: int = Field(deprecated='This is deprecated')

    @model_validator(mode='after')
    def validate_model(self) -> Self:
        with warnings.catch_warnings():
            warnings.simplefilter('ignore', DeprecationWarning)
            self.deprecated_field = self.deprecated_field * 2

Customizing JSON Schema¶

一部のフィールド・パラメータは、生成されたJSONスキーマをカスタマイズするために排他的に使用されます。問題のパラメータは次のとおりです。

title
description
examples
json_schema_extra

JSON schema docsのCustomizing JSON Schemaセクションに記載されている、フィールドを使用したJSONスキーマのカスタマイズ/変更の詳細を読んでください。

The `computed_field` decorator¶

API Documentation

pydantic.fields.computed_field

computed_fieldデコレータは、モデルまたはデータクラスをシリアライズするときに、propertyまたはcached_property属性を含めるために使用できます。これは、他のフィールドから計算されるフィールドや、計算にコストがかかる(したがってキャッシュされる)フィールドに便利です。

次に例を示します。

from pydantic import BaseModel, computed_field


class Box(BaseModel):
    width: float
    height: float
    depth: float

    @computed_field
    def volume(self) -> float:
        return self.width * self.height * self.depth


b = Box(width=1, height=2, depth=3)
print(b.model_dump())
#> {'width': 1.0, 'height': 2.0, 'depth': 3.0, 'volume': 6.0}

通常のフィールドと同様に、計算フィールドは非推奨としてマークできます。

from typing_extensions import deprecated

from pydantic import BaseModel, computed_field


class Box(BaseModel):
    width: float
    height: float
    depth: float

    @computed_field
    @deprecated("'volume' is deprecated")
    def volume(self) -> float:
        return self.width * self.height * self.depth

Fields

Default values¶

Using Annotated¶

Field aliases¶

Validation Alias¶

Numeric Constraints¶

String Constraints¶

Decimal Constraints¶

Dataclass Constraints¶

Validate Default Values¶

Field Representation¶

Discriminator¶

Strict Mode¶

Immutability¶

Exclude¶

Deprecated fields¶

deprecated as a string¶

deprecated via the warnings.deprecated decorator¶

deprecated as a boolean¶

Customizing JSON Schema¶

The computed_field decorator¶

Using `Annotated`¶

`deprecated` as a string¶

`deprecated` via the `warnings.deprecated` decorator¶

`deprecated` as a boolean¶

The `computed_field` decorator¶