Bidang

??? api "Dokumentasi API" pydantic.fields.Field

Fungsi Field digunakan untuk menyesuaikan dan menambahkan metadata ke bidang model.

Nilai bawaan¶

Parameter default digunakan untuk menentukan nilai default untuk suatu bidang.

from pydantic import BaseModel, Field


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


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

Anda juga dapat menggunakan default_factory untuk menentukan callable yang akan dipanggil untuk menghasilkan nilai default.

from uuid import uuid4

from pydantic import BaseModel, Field


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

!!! info Parameter default dan default_factory saling eksklusif.

!!! catatan Jika Anda menggunakan typing.Optional , itu tidak berarti bahwa bidang tersebut memiliki nilai default None !

Menggunakan `Annotated`¶

Fungsi Field juga dapat digunakan bersama dengan 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)]

!!! catatan Default dapat diatur di luar Annotated sebagai nilai yang ditetapkan atau dengan Field.default_factory di dalam Annotated . Argumen Field.default tidak didukung di dalam Annotated .

Alias lapangan¶

Untuk validasi dan serialisasi, Anda dapat menentukan alias untuk suatu bidang.

Ada tiga cara untuk mendefinisikan alias:

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

Parameter alias digunakan untuk validasi dan serialisasi. Jika Anda ingin menggunakan alias berbeda untuk validasi dan serialisasi, Anda dapat menggunakan parameter validation_alias dan serialization_alias , yang hanya akan berlaku dalam kasus penggunaannya masing-masing.

Berikut ini contoh penggunaan parameter 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'}

Alias 'username' digunakan untuk pembuatan dan validasi instance.
Kami menggunakan model_dump untuk mengubah model menjadi format serial.

Anda dapat melihat detail lebih lanjut tentang model_dump di referensi API.

Perhatikan bahwa argumen kata kunci by_alias defaultnya adalah False , dan harus ditentukan secara eksplisit untuk membuang model menggunakan alias bidang (serialisasi).

Ketika by_alias=True , alias 'username' juga digunakan selama serialisasi.

Jika Anda ingin menggunakan alias hanya untuk validasi, Anda dapat menggunakan parameter 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'}

Alias validasi 'username' digunakan selama validasi.
Nama bidang 'name' digunakan selama serialisasi.

Jika Anda hanya ingin mendefinisikan alias untuk serialization , Anda dapat menggunakan parameter 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'}

Nama bidang 'name' digunakan untuk validasi.
Alias serialisasi 'username' digunakan untuk serialisasi.

!!! catatan "Alias diutamakan dan prioritas" Jika Anda menggunakan alias bersama dengan validation_alias atau serialization_alias secara bersamaan, validation_alias akan memiliki prioritas di atas alias untuk validasi, dan serialization_alias akan memiliki prioritas di atas alias untuk serialisasi.

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 "Pengguna VSCode dan Pyright" Di VSCode, jika Anda menggunakan ekstensi Pylance , Anda tidak akan melihat peringatan saat membuat instance model menggunakan alias bidang:

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

Untuk informasi selengkapnya tentang penggunaan alias, lihat halaman Konsep Alias .

Batasan Numerik¶

Ada beberapa argumen kata kunci yang dapat digunakan untuk membatasi nilai numerik:

gt - lebih besar dari
lt - kurang dari
ge - lebih besar dari atau sama dengan
le - kurang dari atau sama dengan
multiple_of - kelipatan dari angka yang diberikan
allow_inf_nan - izinkan nilai 'inf' , '-inf' , 'nan'

Berikut ini contohnya:

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 "Skema JSON" Dalam skema JSON yang dihasilkan:

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

!!! peringatan "Batasan pada tipe gabungan" Jika Anda menggunakan batasan bidang dengan tipe gabungan, kesalahan dapat terjadi dalam beberapa kasus. Untuk menghindari potensi masalah, Anda dapat menggunakan 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)
```

Batasan String¶

??? api "Dokumentasi API" pydantic.types.StringConstraints

Ada bidang yang dapat digunakan untuk membatasi string:

min_length : Panjang minimum string.
max_length : Panjang maksimum string.
pattern : Ekspresi reguler yang stringnya harus cocok.

Berikut ini contohnya:

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

Batasan Kelas Data¶

Ada bidang yang dapat digunakan untuk membatasi kelas data:

init : Apakah bidang tersebut harus disertakan dalam __init__ kelas data.
init_var : Apakah bidang tersebut harus dilihat sebagai bidang khusus init di kelas data.
kw_only : Apakah kolom harus berupa argumen khusus kata kunci di konstruktor kelas data.

Berikut ini contohnya:

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

Bidang baz tidak disertakan dalam keluaran model_dump() , karena ini hanya bidang init.

Validasi Nilai Default¶

Parameter validate_default dapat digunakan untuk mengontrol apakah nilai default bidang harus divalidasi.

Secara default, nilai default bidang tidak divalidasi.

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

Representasi Lapangan¶

Parameter repr dapat digunakan untuk mengontrol apakah bidang tersebut harus disertakan dalam representasi string 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'

Ini adalah nilai default.

Diskriminator¶

discriminator parameter dapat digunakan untuk mengontrol bidang yang akan digunakan untuk membedakan model yang berbeda dalam suatu gabungan. Dibutuhkan nama bidang atau contoh Discriminator . Pendekatan Discriminator dapat berguna ketika bidang diskriminator tidak sama untuk semua model di Union .

Contoh berikut menunjukkan cara menggunakan discriminator dengan nama bidang:

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)

Lihat selengkapnya tentang Fungsi Pembantu di halaman Model .

Contoh berikut menunjukkan cara menggunakan argumen kata kunci discriminator dengan 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))

Anda juga dapat memanfaatkan Annotated untuk mendefinisikan serikat pekerja Anda yang didiskriminasi. Lihat dokumen Serikat Pekerja yang Didiskriminasi untuk lebih jelasnya.

Modus Ketat¶

Parameter strict pada Field menentukan apakah bidang tersebut harus divalidasi dalam "mode ketat". Dalam mode ketat, Pydantic memunculkan kesalahan selama validasi alih-alih memaksa data di bidang tempat 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

Ini adalah nilai default.
Bidang age tidak divalidasi dalam mode ketat. Oleh karena itu, dapat diberikan sebuah string.

Lihat Mode Ketat untuk lebih jelasnya.

Lihat Tabel Konversi untuk detail selengkapnya tentang cara Pydantic mengonversi data dalam mode ketat dan longgar.

Kekekalan¶

Parameter frozen digunakan untuk meniru perilaku kelas data yang dibekukan. Ini digunakan untuk mencegah bidang diberi nilai baru setelah model dibuat (kekekalan).

Lihat dokumentasi kelas data yang dibekukan untuk detail selengkapnya.

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

Karena kolom name dibekukan, penugasan tidak diperbolehkan.

Mengecualikan¶

Parameter exclude dapat digunakan untuk mengontrol bidang mana yang harus dikecualikan dari model saat mengekspor model.

Lihat contoh berikut:

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

Bidang age tidak disertakan dalam keluaran model_dump() , karena dikecualikan.

Lihat bagian Serialisasi untuk lebih jelasnya.

Bidang yang tidak digunakan lagi¶

Parameter deprecated dapat digunakan untuk menandai suatu bidang sebagai tidak digunakan lagi. Melakukan hal ini akan menghasilkan:

peringatan penghentian waktu proses yang dikeluarkan saat mengakses bidang tersebut.
"deprecated": true disetel dalam skema JSON yang dihasilkan.

Anda dapat mengatur parameter deprecated sebagai salah satu dari:

Sebuah string, yang akan digunakan sebagai pesan penghentian.
Sebuah instance dari dekorator warnings.deprecated (atau backport typing_extensions ).
Boolean, yang akan digunakan untuk menandai bidang tersebut sebagai tidak digunakan lagi dengan pesan penghentian default 'deprecated' .

`deprecated` sebagai 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` melalui dekorator `warnings.deprecated`¶

!!! catatan Anda hanya dapat menggunakan dekorator deprecated dengan cara ini jika Anda telah menginstal 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` sebagai 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'}

!!! catatan "Dukungan untuk category dan stacklevel " Implementasi fitur ini saat ini tidak memperhitungkan argumen category dan stacklevel ke dekorator deprecated . Ini mungkin akan muncul di versi Pydantic yang akan datang.

!!! peringatan "Mengakses bidang yang tidak digunakan lagi di validator" Saat mengakses bidang yang tidak digunakan lagi di dalam validator, peringatan penghentian akan dikeluarkan. Anda dapat menggunakan catch_warnings untuk mengabaikannya secara eksplisit:

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

Menyesuaikan Skema JSON¶

Beberapa parameter bidang digunakan secara eksklusif untuk menyesuaikan skema JSON yang dihasilkan. Parameter yang dimaksud adalah:

title
description
examples
json_schema_extra

Baca selengkapnya tentang kustomisasi/modifikasi skema JSON dengan kolom di bagian Menyesuaikan Skema JSON pada dokumen skema JSON.

Dekorator `computed_field`¶

??? api "Dokumentasi API" pydantic.fields.computed_field

Dekorator computed_field dapat digunakan untuk menyertakan atribut property atau cached_property saat membuat serial model atau kelas data. Hal ini dapat berguna untuk bidang yang dihitung dari bidang lain, atau untuk bidang yang mahal untuk dihitung (sehingga di-cache).

Berikut ini contohnya:

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}

Seperti bidang biasa, bidang terhitung dapat ditandai sebagai tidak digunakan lagi:

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

本文总阅读量次

Bidang

Nilai bawaan¶

Menggunakan Annotated¶

Alias lapangan¶

Batasan Numerik¶

Batasan String¶

Batasan Kelas Data¶

Validasi Nilai Default¶

Representasi Lapangan¶

Diskriminator¶

Modus Ketat¶

Kekekalan¶

Mengecualikan¶

Bidang yang tidak digunakan lagi¶

deprecated sebagai string¶

deprecated melalui dekorator warnings.deprecated¶

deprecated sebagai boolean¶

Menyesuaikan Skema JSON¶

Dekorator computed_field¶

Menggunakan `Annotated`¶

`deprecated` sebagai string¶

`deprecated` melalui dekorator `warnings.deprecated`¶

`deprecated` sebagai boolean¶

Dekorator `computed_field`¶