runtype

library0.5.3pypypi✓ verified 85d ago

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.

serialization testing

pip install runtype

github ↗package ↗

INSTALL

IMPORT

SIG · RUNTYPE

runtype

serializationpythonv0.5.3

Install

1.6s avg

Import

64ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.067s · 18MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.061s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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}")

Debug

Known issues

deprecatedThe 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.

affects: >=0.4.0

breakingThe 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.

affects: 0.5.0

gotchaPrior 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.

affects: <0.3.5

Errors

Common errors & fixes

TypeError: argument of type 'str' is not iterable

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'>

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

`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.

Upgrade

Version history

0.5.3latest on PyPI · released Mar 3, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/erezsh/runtype ↗

packagehttps://pypi.org/project/runtype/ ↗