Standard Library Types

Pydantic supports many common types from the Python standard library. If you need stricter processing see Strict types, including if you need to constrain the values allowed (e.g. to require a positive int).

Type	Description
`None`, `type(None)`, or `Literal[None]`	Equivalent according to PEP 484. Allows only `None` value.
`bool`	See Booleans for details on how bools are validated and what values are permitted.
`int`	Pydantic uses `int(v)` to coerce types to an `int`. See Number Types for more details. See the Data Conversion warning on loss of information during data conversion.
`float`	`float(v)` is used to coerce values to floats. See Number Types for more details.
`str`	Strings are accepted as-is. `int`, `float`, and `Decimal` are coerced using `str(v)`. `bytes` and `bytearray` are converted using `v.decode()`. `Enum`s inheriting from `str` are converted using `v.value`. All other types cause an error. See String Types for more details.
`bytes`	`bytes` are accepted as-is. `bytearray` is converted using `bytes(v)`. `str` are converted using `v.encode()`. `int`, `float`, and `Decimal` are coerced using `str(v).encode()`. See ByteSize for more details.
`list`	Allows `list`, `tuple`, `set`, `frozenset`, `deque`, or generators and casts to a list. See `typing.List` for sub-type constraints.
`tuple`	Allows `list`, `tuple`, `set`, `frozenset`, `deque`, or generators and casts to a tuple. See `typing.Tuple` for sub-type constraints.
`dict`	`dict(v)` is used to attempt to convert a dictionary. See `typing.Dict` for sub-type constraints.
`set`	Allows `list`, `tuple`, `set`, `frozenset`, `deque`, or generators and casts to a set. See `typing.Set` for sub-type constraints.
`frozenset`	Allows `list`, `tuple`, `set`, `frozenset`, `deque`, or generators and casts to a frozen set. See `typing.FrozenSet` for sub-type constraints.
`deque`	Allows `list`, `tuple`, `set`, `frozenset`, `deque`, or generators and casts to a deque. See `typing.Deque` for sub-type constraints.
`datetime.date`	See Datetime Types for more detail on parsing and validation.
`datetime.time`	See Datetime Types for more detail on parsing and validation.
`datetime.datetime`	See Datetime Types for more detail on parsing and validation.
`datetime.timedelta`	See Datetime Types for more detail on parsing and validation.
`typing.Any`	Allows any value including `None`, thus an `Any` field is optional.
`typing.Annotated`	Allows wrapping another type with arbitrary metadata, as per PEP-593. The `Annotated` hint may contain a single call to the `Field` function, but otherwise the additional metadata is ignored and the root type is used.
`typing.TypeVar`	Constrains the values allowed based on `constraints` or `bound`, see TypeVar.
`typing.Union`	See Unions for more detail on parsing and validation.
`typing.Optional`	`Optional[x]` is simply short hand for `Union[x, None]`. See Unions for more detail on parsing and validation and Required Fields for details about required fields that can receive `None` as a value.
`typing.List`	See Lists and Tuples for more detail on parsing and validation.
`typing.Tuple`	See Lists and Tuples for more detail on parsing and validation.
Subclass of `typing.NamedTuple`	Same as `tuple`, but instantiates with the given `namedtuple` and validates fields since they are annotated. See Lists and Tuples for more detail.
Subclass of `collections.namedtuple`	Same as subclass of `typing.NamedTuple`, but all fields will have type `Any` since they are not annotated. See Lists and Tuples for more detail.
`typing.Dict`	See Dicts and mapping for more detail on parsing and validation.
Subclass of `typing.TypedDict`	Same as `dict`, but Pydantic will validate the dictionary since keys are annotated.
`typing.Set`	See Sets and frozenset for more detail on parsing and validation.
`typing.FrozenSet`	See Sets and frozenset for more detail on parsing and validation.
`typing.Deque`	See Sequence, Iterable & Iterator for more detail on parsing and validation.
`typing.Sequence`	See Sequence, Iterable & Iterator for more detail on parsing and validation.
`typing.Iterable`	This is reserved for iterables that shouldn't be consumed. See Sequence, Iterable & Iterator for more detail on parsing and validation.
`typing.Type`	See Type and Typevars for more detail on parsing and validation.
`typing.Callable`	See Callables for more detail on parsing and validation.
`typing.Pattern`	Will cause the input value to be passed to `re.compile(v)` to create a regular expression pattern.
`ipaddress.IPv4Address`	Simply uses the type itself for validation by passing the value to `IPv4Address(v)`. See URLs for other custom IP address types.
`ipaddress.IPv4Interface`	Simply uses the type itself for validation by passing the value to `IPv4Address(v)`. See URLs for other custom IP address types.
`ipaddress.IPv4Network`	Simply uses the type itself for validation by passing the value to `IPv4Network(v)`. See URLs for other custom IP address types.
`ipaddress.IPv6Address`	Simply uses the type itself for validation by passing the value to `IPv6Address(v)`. See URLs for other custom IP address types.
`ipaddress.IPv6Interface`	Simply uses the type itself for validation by passing the value to `IPv6Interface(v)`. See URLs for other custom IP address types.
`ipaddress.IPv6Network`	Simply uses the type itself for validation by passing the value to `IPv6Network(v)`. See URLs for other custom IP address types.
`enum.Enum`	Checks that the value is a valid `Enum` instance. See Enums and Choices for more details.
Subclass of `enum.Enum`	Checks that the value is a valid member of the `enum`. See Enums and Choices for more details.
`enum.IntEnum`	Checks that the value is a valid `IntEnum` instance. See Enums and Choices for more details.
Subclass of `enum.IntEnum`	Checks that the value is a valid member of the integer `enum`. See Enums and Choices for more details.
`decimal.Decimal`	Pydantic attempts to convert the value to a string, then passes the string to `Decimal(v)`. See Number Types for more details.
`pathlib.Path`	Simply uses the type itself for validation by passing the value to `Path(v)`. See File Types for other, more strict path types.
`uuid.UUID`	Strings and bytes (converted to strings) are passed to `UUID(v)`, with a fallback to `UUID(bytes=v)` for `bytes` and `bytearray`. See UUIDs for other, more strict UUID types.
`ByteSize`	Converts a bytes string with units to bytes. See ByteSize for more details.

Type conversion¶

During validation, Pydantic can coerce data into expected types.

There are two modes of coercion: strict and lax. See Conversion Table for more details on how Pydantic converts data in both strict and lax modes.

See Strict mode and Strict Types for details on enabling strict coercion.

Literal type¶

Note

This is a new feature of the Python standard library as of Python 3.8; prior to Python 3.8, it requires the typing-extensions package.

Pydantic supports the use of typing.Literal (or typing_extensions.Literal prior to Python 3.8) as a lightweight way to specify that a field may accept only specific literal values:

from typing import Literal

from pydantic import BaseModel, ValidationError


class Pie(BaseModel):
    flavor: Literal['apple', 'pumpkin']


Pie(flavor='apple')
Pie(flavor='pumpkin')
try:
    Pie(flavor='cherry')
except ValidationError as e:
    print(str(e))
    """
    1 validation error for Pie
    flavor
      Input should be 'apple' or 'pumpkin' [type=literal_error, input_value='cherry', input_type=str]
    """

One benefit of this field type is that it can be used to check for equality with one or more specific values without needing to declare custom validators:

from typing import ClassVar, List, Literal, Union

from pydantic import BaseModel, ValidationError


class Cake(BaseModel):
    kind: Literal['cake']
    required_utensils: ClassVar[List[str]] = ['fork', 'knife']


class IceCream(BaseModel):
    kind: Literal['icecream']
    required_utensils: ClassVar[List[str]] = ['spoon']


class Meal(BaseModel):
    dessert: Union[Cake, IceCream]


print(type(Meal(dessert={'kind': 'cake'}).dessert).__name__)
#> Cake
print(type(Meal(dessert={'kind': 'icecream'}).dessert).__name__)
#> IceCream
try:
    Meal(dessert={'kind': 'pie'})
except ValidationError as e:
    print(str(e))
    """
    2 validation errors for Meal
    dessert.Cake.kind
      Input should be 'cake' [type=literal_error, input_value='pie', input_type=str]
    dessert.IceCream.kind
      Input should be 'icecream' [type=literal_error, input_value='pie', input_type=str]
    """

With proper ordering in an annotated Union, you can use this to parse types of decreasing specificity:

from typing import Literal, Optional, Union

from pydantic import BaseModel


class Dessert(BaseModel):
    kind: str


class Pie(Dessert):
    kind: Literal['pie']
    flavor: Optional[str]


class ApplePie(Pie):
    flavor: Literal['apple']


class PumpkinPie(Pie):
    flavor: Literal['pumpkin']


class Meal(BaseModel):
    dessert: Union[ApplePie, PumpkinPie, Pie, Dessert]


print(type(Meal(dessert={'kind': 'pie', 'flavor': 'apple'}).dessert).__name__)
#> ApplePie
print(type(Meal(dessert={'kind': 'pie', 'flavor': 'pumpkin'}).dessert).__name__)
#> PumpkinPie
print(type(Meal(dessert={'kind': 'pie'}).dessert).__name__)
#> Dessert
print(type(Meal(dessert={'kind': 'cake'}).dessert).__name__)
#> Dessert