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