Aller au contenu

Champs

??? API "Documentation API" pydantic.fields.Field

La fonction Field est utilisée pour personnaliser et ajouter des métadonnées aux champs des modèles.

Valeurs par défaut

Le paramètre default est utilisé pour définir une valeur par défaut pour un champ.

from pydantic import BaseModel, Field


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


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

Vous pouvez également utiliser default_factory pour définir un appelable qui sera appelé pour générer une valeur par défaut.

from uuid import uuid4

from pydantic import BaseModel, Field


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

!!! info Les paramètres default et default_factory s'excluent mutuellement.

!!! note Si vous utilisez typing.Optional , cela ne signifie pas que le champ a une valeur par défaut de None !

Utilisation Annotated

La fonction Field peut également être utilisée avec 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 Les valeurs par défaut peuvent être définies en dehors Annotated comme valeur attribuée ou avec Field.default_factory à l'intérieur Annotated . L'argument Field.default n'est pas pris en charge dans Annotated .

Alias de champ

Pour la validation et la sérialisation, vous pouvez définir un alias pour un champ.

Il existe trois manières de définir un alias:

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

Le paramètre alias est utilisé à la fois pour la validation et la sérialisation. Si vous souhaitez utiliser différents alias pour la validation et la sérialisation respectivement, vous pouvez utiliser les paramètres validation_alias et serialization_alias , qui s'appliqueront uniquement dans leurs cas d'utilisation respectifs.

Voici un exemple d'utilisation du paramètre 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'}
  1. L'alias 'username' est utilisé pour la création et la validation des instances.
  2. Nous utilisons model_dump pour convertir le modèle dans un format sérialisable.

Vous pouvez voir plus de détails sur model_dump dans la référence de l'API.

Notez que l'argument du mot clé by_alias est par défaut False et doit être spécifié explicitement pour vider les modèles à l'aide des alias de champ (sérialisation).

Lorsque by_alias=True , l'alias 'username' est également utilisé lors de la sérialisation.

Si vous souhaitez utiliser un alias uniquement pour la validation, vous pouvez utiliser le paramètre 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'}
  1. L'alias de validation 'username' est utilisé lors de la validation.
  2. Le nom du champ 'name' est utilisé lors de la sérialisation.

Si vous souhaitez uniquement définir un alias pour la sérialisation , vous pouvez utiliser le paramètre 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'}
  1. Le nom du champ 'name' est utilisé pour la validation.
  2. L'alias de sérialisation 'username' est utilisé pour la sérialisation.

!!! note "Précédence et priorité de l'alias" Si vous utilisez alias avec validation_alias ou serialization_alias en même temps, validation_alias aura la priorité sur alias pour la validation, et serialization_alias aura la priorité sur alias pour la sérialisation.

If you use an `alias_generator` in the [Model Config][pydantic.config.ConfigDict.alias_generator], you can control
the order of precedence for specified field vs generated aliases via the `alias_priority` setting. You can read more about alias precedence [here](../concepts/alias.md#alias-precedence).

??? tip "Utilisateurs de VSCode et Pyright" Dans VSCode, si vous utilisez l'extension Pylance , vous ne verrez pas d'avertissement lors de l'instanciation d'un modèle à l'aide de l'alias d'un champ:

```py
from pydantic import BaseModel, Field


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


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

1. VSCode will NOT show a warning here.

When the `'alias'` keyword argument is specified, even if you set `populate_by_name` to `True` in the
[Model Config][pydantic.config.ConfigDict.populate_by_name], VSCode will show a warning when instantiating
a model using the field name (though it will work at runtime) — in this case, `'name'`:

```py
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 will show a warning here.

To "trick" VSCode into preferring the field name, you can use the `str` function to wrap the alias value.
With this approach, though, a warning is shown when instantiating a model using the alias for the field:

```py
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. Now VSCode will NOT show a warning
2. VSCode will show a warning here, though

This is discussed in more detail in [this issue](https://github.com/pydantic/pydantic/issues/5893).

### Validation Alias

Even though Pydantic treats `alias` and `validation_alias` the same when creating model instances, VSCode will not
use the `validation_alias` in the class initializer signature. If you want VSCode to use the `validation_alias`
in the class initializer, you can instead specify both an `alias` and `serialization_alias`, as the
`serialization_alias` will override the `alias` during serialization:

```py
from pydantic import BaseModel, Field


class MyModel(BaseModel):
    my_field: int = Field(..., validation_alias='myValidationAlias')
```
with:
```py
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}
```

All of the above will likely also apply to other tools that respect the
[`@typing.dataclass_transform`](https://docs.python.org/3/library/typing.html#typing.dataclass_transform)
decorator, such as Pyright.

Pour plus d'informations sur l'utilisation des alias, consultez la page Concepts d'alias .

Contraintes numériques

Certains arguments de mots clés peuvent être utilisés pour contraindre les valeurs numériques:

  • gt - supérieur à
  • lt - moins de
  • ge - supérieur ou égal à
  • le - inférieur ou égal à
  • multiple_of - un multiple du nombre donné
  • allow_inf_nan - autorise les valeurs 'inf' , '-inf' , 'nan'

Voici un exemple:

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

??? info "Schéma JSON" Dans le schéma JSON généré:

- `gt` and `lt` constraints will be translated to `exclusiveMinimum` and `exclusiveMaximum`.
- `ge` and `le` constraints will be translated to `minimum` and `maximum`.
- `multiple_of` constraint will be translated to `multipleOf`.

The above snippet will generate the following JSON Schema:

```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"
  ]
}
```

See the [JSON Schema Draft 2020-12] for more details.

!!! avertissement "Contraintes sur les types composés" Si vous utilisez des contraintes de champ avec des types composés, une erreur peut survenir dans certains cas. Pour éviter des problèmes potentiels, vous pouvez utiliser Annotated:

```py
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)
```

Contraintes de chaîne

??? API "Documentation API" pydantic.types.StringConstraints

Certains champs peuvent être utilisés pour contraindre des chaînes:

  • min_length : Longueur minimale de la chaîne.
  • max_length : Longueur maximale de la chaîne.
  • pattern: Une expression régulière à laquelle la chaîne doit correspondre.

Voici un exemple:

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

1. Only digits are allowed.

??? info "JSON Schema"
    In the generated JSON schema:

    - `min_length` constraint will be translated to `minLength`.
    - `max_length` constraint will be translated to `maxLength`.
    - `pattern` constraint will be translated to `pattern`.

    The above snippet will generate the following JSON Schema:

    ```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`: Maximum number of digits within the `Decimal`. It does not include a zero before the decimal point or
  trailing decimal zeroes.
* `decimal_places`: Maximum number of decimal places allowed. It does not include trailing decimal zeroes.

Here's an example:

```py
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')

Contraintes de classe de données

Certains champs peuvent être utilisés pour contraindre les classes de données:

  • init : Indique si le champ doit être inclus dans le __init__ de la classe de données.
  • init_var : indique si le champ doit être considéré comme un champ init uniquement dans la classe de données.
  • kw_only : indique si le champ doit être un argument de mot-clé uniquement dans le constructeur de la classe de données.

Voici un exemple:

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'}}
  1. Le champ baz n'est pas inclus dans la sortie model_dump() , puisqu'il s'agit d'un champ d'initialisation uniquement.

Valider les valeurs par défaut

Le paramètre validate_default peut être utilisé pour contrôler si la valeur par défaut du champ doit être validée.

Par défaut, la valeur par défaut du champ n'est pas validée.

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

Représentation sur le terrain

Le paramètre repr peut être utilisé pour contrôler si le champ doit être inclus dans la représentation sous forme de chaîne du modèle.

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'
  1. Il s'agit de la valeur par défaut.

Discriminateur

Le discriminator de paramètres peut être utilisé pour contrôler le champ qui sera utilisé pour discriminer les différents modèles dans une union. Il prend soit le nom d'un champ, soit une instance Discriminator . L'approche Discriminator peut être utile lorsque les champs du discriminateur ne sont pas les mêmes pour tous les modèles de l' Union .

L'exemple suivant montre comment utiliser discriminator avec un nom de champ:

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)
  1. Pour en savoir plus sur les fonctions d'assistance, consultez la page Modèles .

L'exemple suivant montre comment utiliser l'argument de mot-clé discriminator avec une instance 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))

Vous pouvez également profiter d' Annotated pour définir vos unions discriminées. Voir la documentation sur les syndicats discriminés pour plus de détails.

Mode strict

Le paramètre strict sur un Field précise si le champ doit être validé en "mode strict". En mode strict, Pydantic génère une erreur lors de la validation au lieu de forcer les données sur le champ où 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
  1. Il s'agit de la valeur par défaut.
  2. Le champ age n'est pas validé en mode strict. Par conséquent, une chaîne peut lui être attribuée.

Voir Mode strict pour plus de détails.

Voir Tableau de conversion pour plus de détails sur la façon dont Pydantic convertit les données en modes strict et laxiste.

Immutabilité

Le paramètre frozen est utilisé pour émuler le comportement de la classe de données gelée. Il est utilisé pour empêcher que le champ reçoive une nouvelle valeur après la création du modèle (immuabilité).

Consultez la documentation de la classe de données gelée pour plus de détails.

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]
    """
  1. Le champ name étant gelé, l’affectation n’est pas autorisée.

Exclure

Le paramètre exclude peut être utilisé pour contrôler quels champs doivent être exclus du modèle lors de l'exportation du modèle.

Voir l'exemple suivant:

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'}
  1. Le champ age n'est pas inclus dans la sortie model_dump() , car il est exclu.

Voir la section Sérialisation pour plus de détails.

Champs obsolètes

Le paramètre deprecated peut être utilisé pour marquer un champ comme étant obsolète. Cela entraînera:

  • un avertissement de dépréciation d'exécution émis lors de l'accès au champ.
  • "deprecated": true étant défini dans le schéma JSON généré.

Vous pouvez définir le paramètre deprecated comme l'un des suivants:

  • Une chaîne qui sera utilisée comme message de dépréciation.
  • Une instance du décorateur warnings.deprecated (ou du backport typing_extensions ).
  • Un booléen, qui sera utilisé pour marquer le champ comme obsolète avec un message de dépréciation 'deprecated' par défaut.

deprecated en tant que chaîne

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 le décorateur warnings.deprecated

!!! note Vous ne pouvez utiliser le décorateur deprecated de cette manière que si typing_extensions >= 4.9.0 est installé.

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 en tant que booléen

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

!!! note " Prise en charge de category et stacklevel " L'implémentation actuelle de cette fonctionnalité ne prend pas en compte les arguments category et stacklevel du décorateur deprecated . Cela pourrait atterrir dans une future version de Pydantic.

!!! avertissement "Accès à un champ obsolète dans les validateurs" Lors de l'accès à un champ obsolète à l'intérieur d'un validateur, l'avertissement de dépréciation sera émis. Vous pouvez utiliser catch_warnings pour l'ignorer explicitement:

```py
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
```

Personnalisation du schéma JSON

Certains paramètres de champ sont utilisés exclusivement pour personnaliser le schéma JSON généré. Les paramètres en question sont :

  • title
  • description
  • examples
  • json_schema_extra

En savoir plus sur la personnalisation/modification du schéma JSON avec des champs dans la section Personnalisation du schéma JSON de la documentation sur le schéma JSON.

Le décorateur computed_field

??? API "Documentation API" pydantic.fields.computed_field

Le décorateur computed_field peut être utilisé pour inclure des attributs property ou cached_property lors de la sérialisation d'un modèle ou d'une classe de données. Cela peut être utile pour les champs calculés à partir d'autres champs, ou pour les champs dont le calcul est coûteux (et qui sont donc mis en cache).

Voici un exemple:

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}

Comme pour les champs normaux, les champs calculés peuvent être marqués comme obsolètes:

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
本文总阅读量次