typedload

Load and dump json-like data into typed data structures in Python3, enforcing a schema on the data.

This module provides an API to load dictionaries and lists (usually loaded from json) into Python's NamedTuples, dataclass, sets, enums, and various other typed data structures; respecting all the type-hints and performing type checks or casts when needed.

It can also dump from typed data structures to json-like dictionaries and lists.

It is very useful for projects that use Mypy and deal with untyped data like json, because it guarantees that the data will follow the specified schema.

It is released with a GPLv3 license but it is possible to ask for LGPLv3.

GPLv3 logo

Example

For example this dictionary, loaded from a json:

data = {
    'users': [
        {
            'username': 'salvo',
            'shell': 'bash',
            'sessions': ['pts/4', 'tty7', 'pts/6']
        },
        {
            'username': 'lop'
        }
    ],
}

Can be treated more easily if loaded into this type:

@dataclasses.dataclass
class User:
    username: str
    shell: str = 'bash'
    sessions: list[str] = dataclasses.field(default_factory=list)

class Logins(NamedTuple):
    users: list[User]

And the data can be loaded into the structure with this:

t_data = typedload.load(data, Logins)

And then converted back:

data = typedload.dump(t_data)

Supported types

Since this is not magic, not all types are supported.

The following things are supported:

Basic python types (int, str, bool, float, NoneType)
NamedTuple
Enum
Optional[SomeType]
list[SomeType]
dict[TypeA, TypeB]
tuple[TypeA, TypeB, TypeC] and tuple[SomeType, ...]
set[SomeType]
TypeA | TypeB
dataclass
attr.s
ForwardRef (Refer to the type in its own definition)
Literal
TypedDict
datetime.date, datetime.time, datetime.datetime
re.Pattern
Path
IPv4Address, IPv6Address
typing.Any
typing.NewType
uuid.UUID
typedload.moretypes

Unions

typedload works fine with untagged unions. However using Literal fields to tag them makes it much faster.

Using Mypy

Mypy and similar tools work without requiring any plugins.

# This is treated as Any, no checks done.
data = json.load(f)

# This is treated as dict[str, int]
# but there will be runtime errors if the data does not
# match the expected format
data = json.load(f)  # type: dict[str, int]

# This is treated as dict[str, int] and an exception is
# raised if the actual data is not dict[str, int]
data = typedload.load(json.load(f), dict[str, int])

So when using Mypy, it makes sense to make sure that the type is correct, rather than hoping the data will respect the format.

Extending

Type handlers can easily be added, and existing ones can be replaced, so the library is fully cusomizable and can work with any type.

Inheriting a base class is not required.

Install

pip install typedload
apt install python3-typedload
Latest and greatest .deb file is in releases

Documentation

Online documentation
In the docs/ directory

The tests are hard to read but provide more in depth examples of the capabilities of this module.

Used by

As dependency, typedload is used by those entities. Feel free to add to the list.

Lyft
Several universities around the world (via Relational)
People who love IRC (via localslackirc)
No clue but it gets thousands of downloads per day according to pypi

Release files for typedload 2.41

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for typedload 2.41
File	Size	Uploaded
typedload-2.41.tar.gz	53.0 kB	May 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for typedload 2.41
File	Interpreter	ABI	Platform	Reset
typedload-2.41-py3-none-any.whl 44.2 kB May 23, 2026	Python 3	none	any	Details

Total release size: 97.1 kB

Release files / typedload-2.41.tar.gz

Download URL	typedload-2.41.tar.gz
Size	53.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`85ed3911b465781acc4ea2d124e2fc0a99148566a2db5d6e906b210b69782267`
BLAKE2b-256 checksum How to use checksums	`1589145d218f30234d1246b4d80199d9de9a68ce34f1dcafec52c04b110c51ae`
Upload date	May 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.12`

Release files / typedload-2.41-py3-none-any.whl

Download URL	typedload-2.41-py3-none-any.whl
Size	44.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6d29ab64918ac30a756e1cf383e4fd122ce058a240a48cd323a46ae82c3f44b6`
BLAKE2b-256 checksum How to use checksums	`32a7910bdaf944e2e68226082c2aad75716c3331f6a93743c1c3f38b533711fa`
Upload date	May 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.12`