Runtype: Runtime Type Validation and Multiple Dispatch

Common errors

• TypeError: argument of type 'str' is not iterable

  cause Attempting to iterate directly over an instance of a `runtype.dataclass` after version 0.4.0/0.5.0.
  fix Instead of `for item in my_dataclass_instance:`, use `my_dataclass_instance.asdict().items()` or access specific attributes: `my_dataclass_instance.field_name`.

• TypeError: Value '...' of type <class 'str'> is not an instance of type <class 'int'>

  cause A `runtype.dataclass` received a value for a field that does not match its annotated type, and casting was not enabled or possible.
  fix Ensure that the input values strictly match the type hints in your `runtype.dataclass`. If you want `runtype` to attempt automatic type conversion, decorate your dataclass with `@dataclass(check_types='cast')`.

• TypeError: Can't dispatch on literal

  cause `runtype.dispatch` does not support dispatching functions based on Python `Literal` types directly.
  fix Refactor your dispatch logic to use concrete types or broader type unions instead of `Literal` for dispatch arguments. `Literal` types are typically for static checking, not runtime dispatch values.

Warnings

• deprecated The behavior of `iter(dataclass_instance)` was deprecated in version 0.4.0 and formally removed/changed in 0.5.0.
  Fix: Avoid iterating directly over `runtype.dataclass` instances. Use explicit methods like `asdict()` or `astuple()` if available, or access attributes directly.
• breaking The behavior of `Any` when used in type annotations was fixed in version 0.5.0 to align with `mypy`'s semantics. This might cause existing code relying on previous `Any` behavior to break.
  Fix: Review usage of `Any` in type annotations within `runtype` contexts. If `All` (a new type introduced in 0.5.0) is more appropriate for your use case, consider switching to it. Ensure your type annotations accurately reflect the desired flexibility or strictness.
• gotcha Prior to 0.3.5, dispatching on `dataclass.__init__` would override the built-in implementation. In 0.3.5+, it adds to it.
  Fix: For versions 0.3.5 and later, `multidispatch` on `__init__` will augment rather than replace the default dataclass initialization. If you relied on `runtype` completely overriding `__init__`, you might need to adjust your dispatch logic or use `__post_init__` for additional setup.

Install

• pip install runtype Install latest stable version

Imports

• isa

  from runtype import isa

  Used for runtime type checking, a smarter alternative to `isinstance`.
• dataclass

  from runtype.dataclass import dataclass

  A drop-in replacement for Python's `dataclasses.dataclass` with added runtime type validation and casting capabilities.
• multidispatch

  from runtype.dispatch import multidispatch

  Decorator for fast multiple-dispatch functions, supporting dispatch on multiple arguments and full specificity resolution.

Quickstart

This quickstart demonstrates basic runtime type validation using `isa` and shows how to define a type-safe dataclass using `runtype.dataclass`. It includes examples of both successful validation and instances where validation fails, raising a TypeError.

from runtype import isa
from runtype.dataclass import dataclass

# Example 1: Runtime type validation
assert isa({'a': 1, 'b': 2}, dict[str, int]) == True
assert isa([1, 'a', 3], list[int | str]) == True
assert not isa({'a': 'b'}, dict[str, int]) == True

# Example 2: Type-safe dataclass
@dataclass
class User:
    name: str
    age: int
    email: str

try:
    user = User(name='Alice', age=30, email='alice@example.com')
    print(f"Valid user: {user.name}")
except TypeError as e:
    print(f"Validation error: {e}")

try:
    # This will raise a TypeError due to 'age' being a string
    invalid_user = User(name='Bob', age='twenty', email='bob@example.com')
    print(f"Invalid user: {invalid_user.name}")
except TypeError as e:
    print(f"Validation error for invalid user: {e}")