Skip to main content

Type dispatch and validation for run-time Python

Project description

alt text

Runtype is a collection of run-time type utilities for Python.

It is:

:runner: Fast! Uses an internal typesystem for maximum performance.

:brain: Smart! Supports typing, forward-references, constraints, auto-casting, and more.

:gear: Configurative! Write your own type system, and use it with dataclass and dispatch.


  • :star: validation - Provides a smarter alternative to isinstance and issubclass, with support for the typing module, and type constraints.

  • :star: dataclass - Adds run-time type validation to the built-in dataclass.

    • Improves dataclass ergonomics.
    • Supports most mypy constructs, like typing and forward-references (foo: 'Bar').
    • Supports automatic value casting, Pydantic-style. (Optional, off by default)
    • Supports types with constraints. (e.g. String(max_length=10))
    • Supports optional sampling for faster validation of big lists and dicts.
    • Twice faster than Pydantic-v1 with pure Python (read here)
  • :star: dispatch - Provides fast multiple-dispatch for functions and methods, via a decorator.

    • Dispatch on multiple arguments
    • Full specificity resolution
    • Supports mypy, by utilizing the @overload decorator
    • Inspired by Julia.
  • :star: type utilities - Provides a set of classes to implement your own type-system.

    • Supports generics, constraints, phantom types
    • Used by runtype itself, to emulate the Python type-system.


Read the docs here:


pip install runtype

No dependencies.

Requires Python 3.6 or up.



Validation (Isa & Subclass)

Use isa and issubclass as a smarter alternative to the builtin isinstance & issubclass -

from runtype import isa, issubclass

assert isa({'a': 1}, dict[str, int])        # == True
assert not isa({'a': 'b'}, dict[str, int])  # == False

assert issubclass(dict[str, int], typing.Mapping[str, int])     # == True
assert not issubclass(dict[str, int], typing.Mapping[int, str]) # == False


from runtype import dataclass

@dataclass(check_types='cast')  # Cast values to the target type, when applicable
class Person:
    name: str
    birthday: datetime = None   # Implicit optional
    interests: list[str] = []   # The list is copied for each instance

print( Person("Beetlejuice") )
#> Person(name='Beetlejuice', birthday=None, interests=[])
print( Person("Albert", "1955-04-18T00:00", ['physics']) )
#> Person(name='Albert', birthday=datetime.datetime(1955, 4, 18, 0, 0), interests=['physics'])
print( Person("Bad", interests=['a', 1]) )
# TypeError: [Person] Attribute 'interests' expected value of type list[str]. Instead got ['a', 1]
#     Failed on item: 1, expected type str

Multiple Dispatch

Runtype dispatches according to the most specific type match -

from runtype import multidispatch as md

def mul(a: list, b: list):
    return [mul(i, j) for i, j in zip(a, b, strict=True)]
def mul(a: list, b: Any):
    return [ai*b for ai in a]
def mul(a: Any, b: list):
    return [bi*b for bi in b]
def mul(a: Any, b: Any):
    return a * b

assert mul("a", 4)         == "aaaa"        # Any, Any
assert mul([1, 2, 3], 2)   == [2, 4, 6]     # list, Any
assert mul([1, 2], [3, 4]) == [3, 8]        # list, list

Dispatch can also be used for extending the dataclass builtin __init__:

class Point:
    x: int = 0
    y: int = 0
    def __init__(self, points: list | tuple):
        self.x, self.y = points

    def __init__(self, points: dict):
        self.x = points['x']
        self.y = points['y']
# Test constructors
p0 = Point()                         # Default constructor
assert p0 == Point(0, 0)             # Default constructor
assert p0 == Point([0, 0])           # User constructor
assert p0 == Point((0, 0))           # User constructor
assert p0 == Point({"x": 0, "y": 0}) # User constructor


Runtype uses the MIT license.


If you like Runtype and want to show your appreciation, you can do so at my patreon page, or ko-fi page.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

runtype-0.4.2.tar.gz (23.8 kB view hashes)

Uploaded Source

Built Distribution

runtype-0.4.2-py3-none-any.whl (24.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page