ⓘ

Python type checking tools are usually very complex. In this case, we have thrown out almost all the places where there is a lot of complexity, and left only the most obvious and necessary things for runtime.

Table of contents

• Why?
• Installation
• Usage
• Special types
• String deserialization

Why?

It's been a long time since static type checking tools like mypy for Python have been available, and they've become very complex. The typing system has also become noticeably more complicated, providing us with more and more new types of annotations, new syntax and other tools. It seems that Python devs procrastinate endlessly, postponing all the really important CPyhton improvements in order to add more garbage to typing.

A separate difficulty arises for those who try to use type annotations in runtime. Many data types make sense only in the context of static validation, and there is no way to verify these aspects in runtime. And some checks, although theoretically possible, would be extremely expensive. For example, to verify the validity of annotation List[int] in relation to a list, you would need to go through all its objects linearly to make sure that none of them violates the contract from the annotation.

So, why do we need this package? There is only one function where you can pass a type or a type annotation + a specific value, and you will find out if one corresponds to the other. That's it! You can use this feature as a support when creating runtime type checking tools, however, we do not offer these tools here. You decide for yourself whether to wrap this function in syntactic sugar like decorators with automatic type checking.

Also, we are not trying to cover the whole chasm of semantics that, for example, mypy can track. Our approach is to make type checking as stupid as possible. This is the only way to avoid the stupid typing games that complex tools impose on us.

What exactly does this library support:

• The basis of everything is the simplest type checking via isinstance. If you don't use any special types from typing, expect direct type matching.
• Union support. You can combine the two types through a logical OR.
• Checking the Optional type and None as an annotation.
• Using Any annotation.

And that's what's not here:

• Supports types with complex semantics from the typing module.
• Checking the contents of collections. In normal mode, collections are checked only for the base type (in strict mode, the contents for some base collections are also checked).
• Support for string annotations.

If you need more complex semantics, use static validation tools. If you need strange and expensive runtime checks that try to confuse static semantics by adding thousands of exceptions, use other runtime tools. Use this library if you need a MINIMUM.

Installation

You can install simtypes using pip:

pip install simtypes

You can also quickly try out this and other packages without having to install using instld.

Usage

Import the check function:

from simtypes import check

And pass there 2 arguments, a value + a type or type annotation:

print(check(1, int))
#> True
print(check(1, str))
#> False
print(check(1, Any))
#> True
print(check('kek', Any))
#> True
print(check(1, List))
#> False
print(check([1], List))
#> True
print(check([1], List[int]))
#> True
print(check(['kek'], List[int]))  # Attention! The content of the list is not checked in normal mode.
#> True
print(check(1, Optional[int]))
#> True
print(check(None, Optional[int]))
#> True
print(check(1, Optional[str]))
#> False
print(check(1, None))
#> False
print(check(None, None))
#> True

↑ As you can see, the function returns True or False, depending on whether the value matches its annotation.

In normal mode, the contents of collections are not checked. However, if strict mode is activated, the contents of lists, dicts and tuples will also start to be checked:

print(check(['kek'], List[str], strict=True))
#> True
print(check({'lol': 'kek'}, Dict[str, str], strict=True))
#> True
print(check([1, 2, 3], List[str], strict=True))
#> False
print(check({'lol': 123}, Dict[str, str], strict=True))
#> False
print(check((1, 2, 3), Tuple[int, int, int], strict=True))
#> True
print(check((1, 2, 3), Tuple[int, ...], strict=True))
#> True
print(check((1, 2, "text"), Tuple[int, ...], strict=True))
#> False

Mock objects are skipped during verification by default. If you want to disable this, use pass_mocks=False:

from unittest.mock import Mock, MagicMock

print(check(Mock(), str))
#> True
print(check(MagicMock(), int))
#> True

print(check(Mock(), str, pass_mocks=False))
#> False
print(check(MagicMock(), int, pass_mocks=False))
#> False

Special types

Some non-trivial runtime checks can be shifted to the type system. This library offers several additional types, which can be checked for membership via the check function:

• NaturalNumber — as the name implies, only objects of type int greater than zero will be checked for this type.
• NonNegativeInt — the same as NaturalNumber, but 0 is also a valid value.

Here are some usage examples:

from simtypes import NaturalNumber, NonNegativeInt

print(check(13, NaturalNumber))
#> True
print(check(0, NaturalNumber))
#> False
print(check(13, NonNegativeInt))
#> True
print(check(0, NonNegativeInt))
#> True
print(check(-11, NonNegativeInt))
#> False

In addition to other types, simtypes supports an extended type of sentinels from the denial library. In short, this is an extended None, for cases when we need to distinguish between situations where a value is undefined and situations where it is defined as undefined. Similar to None, objects of the InnerNoneType class can be used as type hints for themselves:

from denial import InnerNoneType

print(check(InnerNoneType('key'), InnerNoneType('key')))
#> True

String deserialization

The library also provides primitive deserialization. Conversion of strings into several basic types in any combinations is supported:

• str- any string can be interpreted as a str type.
• int - any integers.
• float - any floating-point numbers, including infinities and NaN.
• bool- the strings "yes", "True", and "true" are interpreted as True, while "no", "False", or "false" are interpreted as False.
• date or datetime - strings representing, respectively, dates or dates + time in ISO 8601 format.
• list - lists in json format are expected.
• tuple - lists in json format are expected.
• dict - dicts in json format are expected.

Examples:

from simtypes import from_string

# ints
print(from_string('13', int))
#> 13
print(from_string('-13', int))
#> -13

# floats
print(from_string('13', float))
#> 13.0
print(from_string('13.5', float))
#> 13.5
print(from_string('nan', float))
#> nan
print(from_string('∞', float))
#> inf
print(from_string('-∞', float))
#> -inf
print(from_string('inf', float))
#> inf
print(from_string('-inf', float))
#> -inf

# strings
print(from_string('I am the danger', str))
#> "I am the danger"
print(from_string('I am the danger', Any))  # Any is interpreted as a string.
#> "I am the danger"

# bools
print(from_string('yes', bool))
#> True
print(from_string('no', bool))
#> False
print(from_string('True', bool))
#> True

# dates and datetimes
from datetime import datetime, date

print(from_string('2026-01-27', date))
#> 2026-01-27
print(from_string('2026-01-27 01:47:29.982044', datetime))
#> 2026-01-27 01:47:29.982044

# collections
print(from_string('[1, 2, 3]', list[int]))
#> [1, 2, 3]
print(from_string('[1, 2, 3]', tuple[int, ...]))
#> (1, 2, 3)
print(from_string('{"123": [1, 2, 3]}', dict[str, tuple[int, ...]]))
#> {'123': (1, 2, 3)}

👀 If the passed string cannot be interpreted as an object of the specified type, a TypeError exception will be raised.