{"id":8611,"library":"runtype","title":"Runtype: Runtime Type Validation and Multiple Dispatch","description":"Runtype is a Python library providing utilities for fast run-time type validation and multiple dispatch. It enhances Python's built-in `dataclasses` with runtime type validation and automatic casting, offers smart alternatives to `isinstance` and `issubclass` for complex types, and implements a performant multiple-dispatch decorator. The library is currently at version 0.5.3, with a regular release cadence addressing bug fixes and performance improvements.","status":"active","version":"0.5.3","language":"en","source_language":"en","source_url":"https://github.com/erezsh/runtype","tags":["type checking","validation","dataclasses","multiple dispatch","runtime"],"install":[{"cmd":"pip install runtype","lang":"bash","label":"Install latest stable version"}],"dependencies":[],"imports":[{"note":"Used for runtime type checking, a smarter alternative to `isinstance`.","symbol":"isa","correct":"from runtype import isa"},{"note":"A drop-in replacement for Python's `dataclasses.dataclass` with added runtime type validation and casting capabilities.","symbol":"dataclass","correct":"from runtype.dataclass import dataclass"},{"note":"Decorator for fast multiple-dispatch functions, supporting dispatch on multiple arguments and full specificity resolution.","symbol":"multidispatch","correct":"from runtype.dispatch import multidispatch"}],"quickstart":{"code":"from runtype import isa\nfrom runtype.dataclass import dataclass\n\n# Example 1: Runtime type validation\nassert isa({'a': 1, 'b': 2}, dict[str, int]) == True\nassert isa([1, 'a', 3], list[int | str]) == True\nassert not isa({'a': 'b'}, dict[str, int]) == True\n\n# Example 2: Type-safe dataclass\n@dataclass\nclass User:\n    name: str\n    age: int\n    email: str\n\ntry:\n    user = User(name='Alice', age=30, email='alice@example.com')\n    print(f\"Valid user: {user.name}\")\nexcept TypeError as e:\n    print(f\"Validation error: {e}\")\n\ntry:\n    # This will raise a TypeError due to 'age' being a string\n    invalid_user = User(name='Bob', age='twenty', email='bob@example.com')\n    print(f\"Invalid user: {invalid_user.name}\")\nexcept TypeError as e:\n    print(f\"Validation error for invalid user: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Avoid iterating directly over `runtype.dataclass` instances. Use explicit methods like `asdict()` or `astuple()` if available, or access attributes directly.","message":"The behavior of `iter(dataclass_instance)` was deprecated in version 0.4.0 and formally removed/changed in 0.5.0.","severity":"deprecated","affected_versions":">=0.4.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"0.5.0"},{"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.","message":"Prior to 0.3.5, dispatching on `dataclass.__init__` would override the built-in implementation. In 0.3.5+, it adds to it.","severity":"gotcha","affected_versions":"<0.3.5"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Instead of `for item in my_dataclass_instance:`, use `my_dataclass_instance.asdict().items()` or access specific attributes: `my_dataclass_instance.field_name`.","cause":"Attempting to iterate directly over an instance of a `runtype.dataclass` after version 0.4.0/0.5.0.","error":"TypeError: argument of type 'str' is not iterable"},{"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')`.","cause":"A `runtype.dataclass` received a value for a field that does not match its annotated type, and casting was not enabled or possible.","error":"TypeError: Value '...' of type <class 'str'> is not an instance of type <class 'int'>"},{"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.","cause":"`runtype.dispatch` does not support dispatching functions based on Python `Literal` types directly.","error":"TypeError: Can't dispatch on literal"}]}