Felder

??? API „API-Dokumentation“ pydantic.fields.Field

Die Funktion Field wird zum Anpassen und Hinzufügen von Metadaten zu Feldern von Modellen verwendet.

Standardwerte¶

Der default wird verwendet, um einen Standardwert für ein Feld zu definieren.

from pydantic import BaseModel, Field


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


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

Sie können default_factory auch verwenden, um ein Callable zu definieren, das aufgerufen wird, um einen Standardwert zu generieren.

from uuid import uuid4

from pydantic import BaseModel, Field


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

!!! info Die Parameter default und default_factory schließen sich gegenseitig aus.

!!! Hinweis Wenn Sie typing.Optional verwenden, bedeutet dies nicht, dass das Feld den Standardwert None hat!

Verwendung von `Annotated`¶

Die Funktion Field kann auch zusammen mit Annotated verwendet werden.

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

!!! Hinweis Standardwerte können außerhalb von Annotated als zugewiesener Wert oder mit Field.default_factory innerhalb von Annotated festgelegt werden. Das Field.default Argument wird in Annotated nicht unterstützt.

Feldaliase¶

Zur Validierung und Serialisierung können Sie einen Alias für ein Feld definieren.

Es gibt drei Möglichkeiten, einen Alias zu definieren:

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

Der alias -Parameter wird sowohl für die Validierung als auch für die Serialisierung verwendet. Wenn Sie unterschiedliche Aliase für die Validierung bzw. Serialisierung verwenden möchten, können Sie die Parameter validation_alias und serialization_alias verwenden, die nur in ihren jeweiligen Anwendungsfällen gelten.

Hier ist ein Beispiel für die Verwendung des alias -Parameters:

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

Der Alias 'username' wird für die Instanzerstellung und -validierung verwendet.
Wir verwenden model_dump , um das Modell in ein serialisierbares Format zu konvertieren.

Weitere Details zu model_dump finden Sie in der API-Referenz.

Beachten Sie, dass das Schlüsselwortargument by_alias standardmäßig False ist und explizit angegeben werden muss, um Modelle mithilfe der Feldaliase (Serialisierung) zu sichern.

Wenn by_alias=True , wird der Alias 'username' auch während der Serialisierung verwendet.

Wenn Sie einen Alias nur zur Validierung verwenden möchten, können Sie den Parameter validation_alias verwenden:

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

Der Validierungsalias 'username' wird während der Validierung verwendet.
Der Feldname 'name' wird bei der Serialisierung verwendet.

Wenn Sie nur einen Alias für die Serialisierung definieren möchten, können Sie den Parameter serialization_alias verwenden:

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

Zur Validierung wird der Feldname 'name' verwendet.
Für die Serialisierung wird der Serialisierungsalias 'username' verwendet.

!!! Hinweis „Alias-Vorrang und Priorität“ Falls Sie alias zusammen mit validation_alias oder serialization_alias gleichzeitig verwenden, hat validation_alias für die Validierung Vorrang vor alias und serialization_alias hat für die Serialisierung Vorrang vor alias .

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

??? Tipp „VSCode- und Pyright-Benutzer“ Wenn Sie in VSCode die Pylance- Erweiterung verwenden, wird beim Instanziieren eines Modells unter Verwendung des Alias eines Felds keine Warnung angezeigt:

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

Weitere Informationen zur Alias-Verwendung finden Sie auf der Seite Alias -Konzepte.

Numerische Einschränkungen¶

Es gibt einige Schlüsselwortargumente, die zum Einschränken numerischer Werte verwendet werden können:

gt – größer als
lt - weniger als
ge – größer oder gleich
le – kleiner oder gleich
multiple_of – ein Vielfaches der angegebenen Zahl
allow_inf_nan – erlaubt die Werte 'inf' , '-inf' , 'nan' .

Hier ist ein Beispiel:

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 the generated 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.

!!! Warnung „Einschränkungen für zusammengesetzte Typen“ Wenn Sie Feldeinschränkungen mit zusammengesetzten Typen verwenden, kann es in einigen Fällen zu einem Fehler kommen. Um potenzielle Probleme zu vermeiden, können Sie Annotated verwenden:

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

String-Einschränkungen¶

??? API „API-Dokumentation“ pydantic.types.StringConstraints

Es gibt Felder, die zum Einschränken von Zeichenfolgen verwendet werden können:

min_length : Mindestlänge der Zeichenfolge.
max_length : Maximale Länge der Zeichenfolge.
pattern : Ein regulärer Ausdruck, mit dem die Zeichenfolge übereinstimmen muss.

Hier ist ein Beispiel:

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

Datenklassenbeschränkungen¶

Es gibt Felder, die zum Einschränken von Datenklassen verwendet werden können:

init : Ob das Feld in __init__ der Datenklasse enthalten sein soll.
init_var : Ob das Feld als reines Init-Feld in der Datenklasse angesehen werden soll.
kw_only : Ob das Feld ein Nur-Schlüsselwort-Argument im Konstruktor der Datenklasse sein soll.

Hier ist ein Beispiel:

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

Das Feld baz ist nicht in der Ausgabe model_dump() enthalten, da es sich um ein Nur-Init-Feld handelt.

Standardwerte validieren¶

Mit dem Parameter validate_default kann gesteuert werden, ob der Standardwert des Feldes validiert werden soll.

Standardmäßig wird der Standardwert des Felds nicht validiert.

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

Felddarstellung¶

Mit dem Parameter repr kann gesteuert werden, ob das Feld in die String-Darstellung des Modells einbezogen werden soll.

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'

Dies ist der Standardwert.

Diskriminator¶

Der discriminator kann zur Steuerung des Feldes verwendet werden, das zur Unterscheidung zwischen verschiedenen Modellen in einer Union verwendet wird. Es nimmt entweder den Namen eines Feldes oder einer Discriminator -Instanz an. Der Discriminator -Ansatz kann nützlich sein, wenn die Diskriminatorfelder nicht für alle Modelle in der Union gleich sind.

Das folgende Beispiel zeigt, wie Sie discriminator mit einem Feldnamen verwenden:

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)

Weitere Informationen zu Hilfsfunktionen finden Sie auf der Seite „Modelle“ .

Das folgende Beispiel zeigt, wie das Schlüsselwortargument discriminator mit einer Discriminator -Instanz verwendet wird:

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

Sie können Annotated auch nutzen, um Ihre diskriminierten Gewerkschaften zu definieren. Weitere Einzelheiten finden Sie in den Dokumenten zu Discriminated Unions .

Strenger Modus¶

Der strict Parameter für ein Field gibt an, ob das Feld im „strikten Modus“ validiert werden soll. Im strikten Modus gibt Pydantic während der Validierung einen Fehler aus, anstatt Daten für das Feld zu erzwingen, in dem strict=True ist.

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

Dies ist der Standardwert.
Das age wird im strengen Modus nicht validiert. Daher kann ihm eine Zeichenfolge zugewiesen werden.

Weitere Einzelheiten finden Sie unter Strikter Modus .

Weitere Informationen dazu, wie Pydantic Daten sowohl im strengen als auch im laxen Modus konvertiert, finden Sie in der Konvertierungstabelle .

Unveränderlichkeit¶

Der Parameter frozen wird verwendet, um das Verhalten der eingefrorenen Datenklasse zu emulieren. Es wird verwendet, um zu verhindern, dass dem Feld nach der Erstellung des Modells ein neuer Wert zugewiesen wird (Unveränderlichkeit).

Weitere Einzelheiten finden Sie in der Dokumentation zu eingefrorenen Datenklassen .

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

Da name eingefroren ist, ist die Zuordnung nicht zulässig.

Ausschließen¶

Mit dem exclude -Parameter kann gesteuert werden, welche Felder beim Exportieren des Modells aus dem Modell ausgeschlossen werden sollen.

Sehen Sie sich das folgende Beispiel an:

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

Das age ist nicht in der Ausgabe model_dump() enthalten, da es ausgeschlossen ist.

Weitere Informationen finden Sie im Abschnitt Serialisierung .

Veraltete Felder¶

Der deprecated -Parameter kann verwendet werden, um ein Feld als veraltet zu markieren. Dies führt zu Folgendem:

Beim Zugriff auf das Feld wird eine Laufzeitwarnung ausgegeben.
"deprecated": true wird im generierten JSON-Schema festgelegt.

Sie können den deprecated Parameter als einen der folgenden festlegen:

Eine Zeichenfolge, die als veraltete Nachricht verwendet wird.
Eine Instanz des warnings.deprecated -Dekorators (oder des typing_extensions Backports).
Ein boolescher Wert, der verwendet wird, um das Feld mit der Standardmeldung 'deprecated' als veraltet zu markieren.

als String `deprecated`¶

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

über den `warnings.deprecated` Dekorator `deprecated`¶

!!! Hinweis Sie können den deprecated Decorator nur dann auf diese Weise verwenden, wenn Sie typing_extensions >= 4.9.0 installiert haben.

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

als boolescher `deprecated`¶

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

!!! Hinweis „Unterstützung für category und stacklevel “ Die aktuelle Implementierung dieser Funktion berücksichtigt nicht die Argumente category und stacklevel des deprecated Dekorators. Dies könnte in einer zukünftigen Version von Pydantic landen.

!!! Warnung „Zugriff auf ein veraltetes Feld in Validatoren“ Beim Zugriff auf ein veraltetes Feld in einem Validator wird die veraltete Warnung ausgegeben. Sie können [catch_warnings][Warnings.catch_warnings] verwenden, um es explizit zu ignorieren:

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

Anpassen des JSON-Schemas¶

Einige Feldparameter werden ausschließlich zum Anpassen des generierten JSON-Schemas verwendet. Die betreffenden Parameter sind:

title
description
examples
json_schema_extra

Weitere Informationen zur Anpassung/Änderung des JSON-Schemas mit Feldern finden Sie im Abschnitt „Anpassen des JSON-Schemas“ der JSON-Schema-Dokumentation.

Der `computed_field` Dekorator¶

??? API „API-Dokumentation“ pydantic.fields.computed_field

Der computed_field Dekorator kann verwendet werden, um bei der Serialisierung eines Modells oder einer Datenklasse property oder cached_property -Attribute einzuschließen. Dies kann für Felder nützlich sein, die aus anderen Feldern berechnet werden, oder für Felder, deren Berechnung aufwändig ist (und daher zwischengespeichert wird).

Hier ist ein Beispiel:

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}

Wie bei regulären Feldern können berechnete Felder als veraltet markiert werden:

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

本文总阅读量次

Felder

Standardwerte¶

Verwendung von Annotated¶

Feldaliase¶

Numerische Einschränkungen¶

String-Einschränkungen¶

Datenklassenbeschränkungen¶

Standardwerte validieren¶

Felddarstellung¶

Diskriminator¶

Strenger Modus¶

Unveränderlichkeit¶

Ausschließen¶

Veraltete Felder¶

als String deprecated¶

über den warnings.deprecated Dekorator deprecated¶

als boolescher deprecated¶

Anpassen des JSON-Schemas¶

Der computed_field Dekorator¶

Verwendung von `Annotated`¶

als String `deprecated`¶

über den `warnings.deprecated` Dekorator `deprecated`¶

als boolescher `deprecated`¶

Der `computed_field` Dekorator¶