Pydantic Lax Mode Type Conversions
This page provides a complete reference for how Pyrefly converts types when working with Pydantic models in lax mode (the default). For background on how lax mode works, see the main Pydantic documentation.
Note: Nested Pydantic models and standard-library dataclasses accept either an instance or a Mapping[str, Any]. Classes with a custom __get_pydantic_core_schema__ hook convert to Any, as do enums, named tuples, and standard-library classes without a conversion rule, because Pydantic's built-in schemas for them accept more than instances. Other custom class types without a conversion rule are left unchanged, except that the type arguments of a generic class convert to Any, because Pydantic validates them with an isinstance check. Unsupported forms, such as Callable, convert to Any.
Atomic Type Conversions
Named unions are used for atomic types to keep type signatures concise.
| Input Type | Named Union | Expanded Type |
|---|---|---|
int | LaxInt | int | bool | float | str | bytes | Decimal |
float | LaxFloat | int | bool | float | str | bytes | Decimal |
bool | LaxBool | bool | int | float | str | Decimal |
Decimal | LaxDecimal | Decimal | int | float | str |
str | LaxStr | str | bytes | bytearray |
bytes | LaxBytes | str | bytes | bytearray |
date | LaxDate | date | datetime | int | float | str | bytes | Decimal |
datetime | LaxDatetime | date | datetime | int | float | str | bytes | Decimal |
time | LaxTime | time | int | float | str | bytes | Decimal |
timedelta | LaxTimedelta | timedelta | int | float | str | bytes | Decimal |
Path | LaxPath | Path | str |
UUID | LaxUuid | UUID | str |
None | (no conversion) | None |
For bool conversions, Pyrefly checks inferred integer and string literals against Pydantic's accepted values. Non-literal values use the broader input types shown above.
Compositional Type Conversions
Notation:
T_convertedmeans the typeTis recursively converted using lax mode rules (e.g.,int→LaxInt)T_flattenedmeans the typeTis converted and expanded (e.g.,int→int | bool | float | str | bytes | Decimal)
| Input Type/Container | Output Type/Container |
|---|---|
type[T] | type[T_converted] |
T1 | T2 | ... | T1_flattened | T2_flattened | ... |
list[T], set[T], frozenset[T],Sequence[T], Iterable[T], deque[T],tuple[T, ...] | Iterable[T_converted] |
tuple[T1, T2, ...] | Iterable[T1_flattened | T2_flattened | ...] |
dict[K, V] | Mapping[K, V_converted] |
Examples:
- Type wrapper:
type[int]→type[LaxInt] - Union types: Each member is converted and flattened.
int | bool→int | bool | float | str | bytes | Decimal - Single-element containers and unbounded tuples: Named unions are preserved.
list[int]→Iterable[LaxInt] - Concrete tuples: Element types are expanded and flattened.
tuple[int, str]→Iterable[int | bool | float | str | bytes | bytearray | Decimal] - Dictionaries: Only values are converted; keys remain unchanged.
dict[str, int]→Mapping[str, LaxInt]