typedload

library2.41pypypi✓ verified 29d ago

typedload is a Python library designed to load and dump data from JSON-like formats into statically typed data structures. It supports standard Python types such as NamedTuples, dataclasses, sets, and enums, enforcing a schema by performing type checks and casts as needed. It also facilitates dumping typed data structures back to JSON-like dictionaries and lists. This library is particularly useful for projects leveraging Mypy, as it guarantees data conformity to specified schemas at runtime. It is actively maintained, with frequent releases; the current version is 2.40.

serialization data

pip install typedload

package ↗homepage ↗

INSTALL

IMPORT

SIG · TYPEDLOAD

typedload

serializationpythonv2.41

Install

1.7s avg

Import

12ms

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 v2.41 · 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.95 runs

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

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.008s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

load

✓ from typedload import load

dump

✓ from typedload import dump

This example demonstrates how to define typed data structures using dataclasses and NamedTuple, then use `typedload.load` to convert a dictionary (typically from JSON) into these structures. It also shows `typedload.dump` for converting them back to a dictionary. Default values for fields are automatically handled during loading.

import dataclasses from typing import NamedTuple, List from typedload import load, dump @dataclasses.dataclass class User: username: str shell: str = 'bash' sessions: List[str] = dataclasses.field(default_factory=list) class Logins(NamedTuple): users: List[User] data_from_json = { 'users': [ { 'username': 'salvo', 'shell': 'bash', 'sessions': ['pts/4', 'tty7', 'pts/6'] }, { 'username': 'lop' } ] } # Load the dictionary into typed data structures loaded_data: Logins = load(data_from_json, Logins) print(f"Loaded Data: {loaded_data}") assert loaded_data.users[0].username == 'salvo' assert loaded_data.users[1].shell == 'bash' # Default value applied # Dump the typed data structure back to a dictionary dumped_data = dump(loaded_data) print(f"Dumped Data: {dumped_data}") assert dumped_data['users'][0]['username'] == 'salvo'

Debug

Known issues

gotchaUntagged Unions can lead to non-deterministic loading results if input data matches multiple types within the union. While `typedload` supports untagged unions, it's safer and faster to use `Literal` fields to tag unions for explicit type identification. For debugging, `uniondebugconflict=True` can detect such ambiguities but incurs a performance cost.

fix

Prefer using tagged unions with `typing.Literal` to explicitly differentiate types. If untagged unions are necessary, ensure data unambiguously maps to a single type or be aware of potential non-deterministic behavior. Use `load(data, SomeUnion, uniondebugconflict=True)` for debugging.

affects: 2.x

gotchaThe distinction between `typing.Optional[T]` and a field with a default value is important. `Optional[T]` means the field *must* be present in the input data but can be `None`. A field with a default value, however, can be entirely *omitted* from the input data, and `typedload` will use the default. Misunderstanding this can lead to unexpected validation errors.

fix

Always provide `None` explicitly for `Optional[T]` fields in input data if the value is `None`. For truly optional fields that can be omitted, define a default value (e.g., `field: str = 'default'` or `field: List[str] = dataclasses.field(default_factory=list)`).

affects: 2.x

breakingDirectly using a bare `list` (e.g., `my_list: list`) as a type annotation for loading into a dataclass field will cause a crash. This annotation is treated differently by `typedload` and is not equivalent to `list[typing.Any]` at runtime.

fix

Always specify the type argument for generic collections like `list`. Use `my_list: list[Any]` or `my_list: list[str]` (or any specific type) instead of `my_list: list`.

affects: 2.x

deprecatedSince version 2.23, the default behavior for dumping `datetime.date`, `datetime.time`, and `datetime.datetime` objects has shifted. The previous method of dumping them as a list of integers (e.g., `[year, month, day, ...]`) is now deprecated. The recommended way is to dump them as ISO 8601 strings.

fix

When dumping `datetime` objects and desiring ISO 8601 strings, ensure `isodates=True` is passed to the `dump` function (e.g., `typedload.dump(obj, isodates=True)`). If relying on the old integer list format, be aware it may be removed in future major versions.

affects: >=2.23

gotchaWhen dumping dataclass instances, fields whose values match their declared default values in the dataclass definition may be implicitly omitted from the serialized output. This behavior can lead to incomplete data being serialized, even if the field was explicitly populated during loading, if its value happens to match the default. This is often done to reduce payload size but can be unexpected.

fix

If all fields must always be present in the dumped output, regardless of whether their value matches a default, ensure that `typedload.dump` is configured to include all fields (e.g., check for an `omit_defaults=False` or similar option). Alternatively, if possible, avoid assigning default values to fields that must always be present in the serialized output.

affects: 2.x

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'typedload'

The 'typedload' library has not been installed in the current Python environment.

fix

pip install typedload

TypeError: 'hello' is not an int

The input data provided to `typedload.load()` cannot be converted to the target type specified.

fix

Ensure the input data's type or value is compatible with the expected type for the field or target class.

KeyError: 'b'

The input dictionary provided to `typedload.load()` is missing a required key for the target type (e.g., TypedDict, dataclass).

fix

Ensure the input dictionary contains all required keys for the target type.

ImportError: cannot import name 'TypedloadException' from 'typedload'

The `TypedloadException` class is located within the `typedload.exceptions` submodule, not directly in the top-level `typedload` package.

fix

from typedload.exceptions import TypedloadException

Upgrade

Version history

2.41latest on PyPI · released May 23, 2026

Audit

Dependencies

attrsoptionalUsed for defining typed classes, an alternative to dataclasses or NamedTuple. Not strictly required if using stdlib types.

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

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

homepagehttps://ltworf.codeberg.page/typedload/ ↗