Velden

??? api "API-documentatie" pydantic.fields.Field

De functie Field wordt gebruikt om metagegevens aan te passen en toe te voegen aan velden van modellen.

Standaardwaarden¶

De default wordt gebruikt om een standaardwaarde voor een veld te definiëren.

from pydantic import BaseModel, Field


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


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

U kunt ook default_factory gebruiken om een opvraagbare waarde te definiëren die wordt aangeroepen om een standaardwaarde te genereren.

from uuid import uuid4

from pydantic import BaseModel, Field


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

!!! info De parameters default en default_factory sluiten elkaar uit.

!!! note Als u typing.Optional gebruikt, betekent dit niet dat het veld de standaardwaarde None heeft!

`Annotated` gebruiken¶

De functie Field kan ook samen met Annotated worden gebruikt.

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 Standaardwaarden kunnen buiten Annotated worden ingesteld als de toegewezen waarde of met Field.default_factory binnen Annotated . Het argument Field.default wordt niet ondersteund in Annotated .

Veldaliassen¶

Voor validatie en serialisatie kunt u een alias voor een veld definiëren.

Er zijn drie manieren om een alias te definiëren:

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

De alias wordt gebruikt voor zowel validatie als serialisatie. Als u verschillende aliassen wilt gebruiken voor respectievelijk validatie en serialisatie, kunt u de parameters validation_alias en serialization_alias gebruiken, die alleen van toepassing zijn in hun respectievelijke gebruiksscenario's.

Hier is een voorbeeld van het gebruik van de 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'}

De alias 'username' wordt gebruikt voor bijvoorbeeld het aanmaken en valideren.
We gebruiken model_dump om het model naar een serialiseerbaar formaat te converteren.

U kunt meer details over model_dump bekijken in de API-referentie.

Houd er rekening mee dat het trefwoordargument by_alias standaard ingesteld is op False en expliciet moet worden opgegeven om modellen te dumpen met behulp van de veldaliassen (serialisatie).

Wanneer by_alias=True wordt de alias 'username' ook gebruikt tijdens de serialisatie.

Als u een alias alleen voor validatie wilt gebruiken, kunt u de parameter validation_alias gebruiken:

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

Tijdens de validatie wordt de validatiealias 'username' gebruikt.
Bij serialisatie wordt de veldnaam 'name' gebruikt.

Als u alleen een alias voor serialisatie wilt definiëren, kunt u de parameter serialization_alias gebruiken:

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

Ter validatie wordt de veldnaam 'name' gebruikt.
Voor serialisatie wordt de serialisatiealias 'username' gebruikt.

!!! opmerking "Voorrang en prioriteit van alias" Als u alias tegelijkertijd gebruikt met validation_alias of serialization_alias , zal de validation_alias prioriteit hebben boven alias voor validatie, en serialization_alias zal prioriteit hebben boven alias voor serialisatie.

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 "VSCode- en Pyright-gebruikers" Als u in VSCode de Pylance- extensie gebruikt, ziet u geen waarschuwing bij het instantiëren van een model met behulp van de alias van een veld:

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

Zie de pagina Aliasconcepten voor meer informatie over aliasgebruik.

Numerieke beperkingen¶

Er zijn enkele trefwoordargumenten die kunnen worden gebruikt om numerieke waarden te beperken:

gt - groter dan
lt is minder dan
ge - groter dan of gelijk aan
le - kleiner dan of gelijk aan
multiple_of - een veelvoud van het opgegeven getal
allow_inf_nan - sta 'inf' , '-inf' , 'nan' waarden toe

Hier is een voorbeeld:

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 "JSON Schema" In het gegenereerde JSON-schema:

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

!!! waarschuwing "Beperkingen op samengestelde typen" Als u veldbeperkingen gebruikt bij samengestelde typen, kan er in sommige gevallen een fout optreden. Om mogelijke problemen te voorkomen, kunt u Annotated gebruiken:

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

Tekenreeksbeperkingen¶

??? api "API-documentatie" pydantic.types.StringConstraints

Er zijn velden die kunnen worden gebruikt om tekenreeksen te beperken:

min_length : Minimale lengte van de tekenreeks.
max_length : Maximale lengte van de tekenreeks.
pattern : Een reguliere expressie waaraan de tekenreeks moet voldoen.

Hier is een voorbeeld:

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

Beperkingen voor gegevensklassen¶

Er zijn velden die kunnen worden gebruikt om dataklassen te beperken:

init : Of het veld moet worden opgenomen in de __init__ van de dataklasse.
init_var : Of het veld moet worden gezien als een alleen-init-veld in de dataklasse.
kw_only : Of het veld alleen een trefwoordargument moet zijn in de constructor van de dataklasse.

Hier is een voorbeeld:

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

Het baz -veld is niet opgenomen in de uitvoer model_dump() , omdat het alleen een init-veld is.

Valideer standaardwaarden¶

De parameter validate_default kan worden gebruikt om te bepalen of de standaardwaarde van het veld moet worden gevalideerd.

Standaard wordt de standaardwaarde van het veld niet gevalideerd.

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

Veldvertegenwoordiging¶

De parameter repr kan worden gebruikt om te bepalen of het veld moet worden opgenomen in de stringrepresentatie van het model.

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'

Dit is de standaardwaarde.

Discriminator¶

De discriminator kan worden gebruikt om het veld te besturen dat zal worden gebruikt om onderscheid te maken tussen verschillende modellen in een unie. Er is de naam van een veld of een Discriminator -instantie voor nodig. De Discriminator -aanpak kan nuttig zijn als de discriminatorvelden niet voor alle modellen in de Union hetzelfde zijn.

In het volgende voorbeeld ziet u hoe u discriminator gebruikt met een veldnaam:

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)

Zie meer over Helperfuncties op de pagina Modellen .

In het volgende voorbeeld ziet u hoe u het trefwoordargument discriminator gebruikt met een Discriminator -instantie:

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

U kunt ook profiteren van Annotated om uw gediscrimineerde vakbonden te definiëren. Zie de documenten van Discriminated Unions voor meer details.

Strenge modus¶

De strict parameter op een Field specificeert of het veld gevalideerd moet worden in de "strikte modus". In de strikte modus genereert Pydantic een fout tijdens de validatie in plaats van gegevens op het veld af te dwingen waar 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

Dit is de standaardwaarde.
Het age wordt niet gevalideerd in de strikte modus. Daarom kan er een string aan worden toegewezen.

Zie Strikte modus voor meer details.

Zie Conversietabel voor meer details over hoe Pydantic gegevens converteert in zowel strikte als lakse modi.

Onveranderlijkheid¶

De parameter frozen wordt gebruikt om het gedrag van de bevroren dataklasse te emuleren. Het wordt gebruikt om te voorkomen dat het veld een nieuwe waarde krijgt nadat het model is gemaakt (onveranderlijkheid).

Zie de bevroren dataclass-documentatie voor meer details.

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

Omdat name bevroren is, is de toewijzing niet toegestaan.

Uitsluiten¶

De parameter exclude kan worden gebruikt om te bepalen welke velden moeten worden uitgesloten van het model bij het exporteren van het model.

Zie het volgende voorbeeld:

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

Het age is niet opgenomen in de uitvoer model_dump() , omdat het is uitgesloten.

Zie de sectie Serialisatie voor meer details.

Verouderde velden¶

De deprecated parameter kan worden gebruikt om een veld als verouderd te markeren. Als u dit wel doet, resulteert dit in:

er wordt een runtime-beëindigingswaarschuwing afgegeven bij toegang tot het veld.
"deprecated": true wordt ingesteld in het gegenereerde JSON-schema.

U kunt de deprecated parameter instellen als een van:

Een tekenreeks die wordt gebruikt als beëindigingsbericht.
Een exemplaar van de warnings.deprecated decorateur (of de backport typing_extensions ).
Een booleaanse waarde, die wordt gebruikt om het veld als verouderd te markeren met een standaard 'deprecated' beëindigingsbericht.

`deprecated` als een tekenreeks¶

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 de `warnings.deprecated` decorateur¶

!!! note Je kunt de deprecated decorateur alleen op deze manier gebruiken als je typing_extensions >= 4.9.0 hebt geïnstalleerd.

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` als een booleaanse waarde¶

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

!!! opmerking "Ondersteuning voor category en stacklevel " De huidige implementatie van deze functie houdt geen rekening met de argumenten voor category en stacklevel voor de deprecated decorateur. Dit zou in een toekomstige versie van Pydantic kunnen terechtkomen.

!!! waarschuwing "Toegang tot een verouderd veld in validators" Wanneer u toegang krijgt tot een verouderd veld in een validator, wordt de verouderde waarschuwing afgegeven. Je kunt catch_warnings gebruiken om het expliciet te negeren:

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

JSON-schema aanpassen¶

Sommige veldparameters worden uitsluitend gebruikt om het gegenereerde JSON-schema aan te passen. De betreffende parameters zijn:

title
description
examples
json_schema_extra

Lees meer over het aanpassen/wijzigen van JSON-schema's met velden in de sectie JSON-schema aanpassen van de JSON-schemadocumentatie.

De `computed_field` decorateur¶

??? api "API-documentatie" pydantic.fields.computed_field

De computed_field decorateur kan worden gebruikt om property of cached_property -attributen op te nemen bij het serialiseren van een model of dataklasse. Dit kan handig zijn voor velden die worden berekend op basis van andere velden, of voor velden die duur zijn om te berekenen (en dus in de cache worden opgeslagen).

Hier is een voorbeeld:

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}

Net als bij gewone velden kunnen berekende velden als verouderd worden gemarkeerd:

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

本文总阅读量次

Velden

Standaardwaarden¶

Annotated gebruiken¶

Veldaliassen¶

Numerieke beperkingen¶

Tekenreeksbeperkingen¶

Beperkingen voor gegevensklassen¶

Valideer standaardwaarden¶

Veldvertegenwoordiging¶

Discriminator¶

Strenge modus¶

Onveranderlijkheid¶

Uitsluiten¶

Verouderde velden¶

deprecated als een tekenreeks¶

deprecated via de warnings.deprecated decorateur¶

deprecated als een booleaanse waarde¶

JSON-schema aanpassen¶

De computed_field decorateur¶

`Annotated` gebruiken¶

`deprecated` als een tekenreeks¶

`deprecated` via de `warnings.deprecated` decorateur¶

`deprecated` als een booleaanse waarde¶

De `computed_field` decorateur¶