treekle🌳

tree + pickle: pickle's semantics, written as a plain tree of dicts, lists, and scalars instead of opaque bytes.

Quick Start

# Mac:
#   # Required for quick install.
#   brew install uv

# Ubuntu/Debian:
#   # Required for quick install.
#   sudo apt-get install -y curl
#   curl -LsSf https://astral.sh/uv/install.sh | sh

uv add treekle

# Alternatively: python -m pip install treekle

to_plain turns a value into plain data any JSON, TOML, or YAML writer can store. from_plain turns it back into the type you ask for. Neither touches text, so the wire format is yours.

Example

from __future__ import annotations

from collections.abc import Callable
from dataclasses import dataclass
from pathlib import Path
from types import MappingProxyType

import json
import math

from treekle import ABSENT, ReadError, from_plain, to_plain


def by_name(user: User) -> str:
    return user.name


@dataclass
class User:
    name: str


@dataclass
class Job:
    owner: User
    reviewer: User
    fallback: object
    sort_key: Callable[[User], str]
    output: type
    root: Path
    timeout: float
    env: MappingProxyType[str, str]


ada = User("ada")
job = Job(
    owner=ada,
    reviewer=ada,  # the same object
    fallback=ABSENT,  # a singleton
    sort_key=by_name,  # a function
    output=dict,  # a class
    root=Path("/srv"),
    timeout=math.inf,  # JSON has no inf
    env=MappingProxyType({"LANG": "C"}),
)

back = from_plain(json.loads(json.dumps(to_plain(job))), Job, allow_imports=True)
assert back.owner is back.reviewer
assert back.fallback is ABSENT
assert back.sort_key is by_name
assert back.output is dict
assert back.root == Path("/srv")
assert back.timeout == math.inf
assert isinstance(back.env, MappingProxyType)

Every other library fails on the same job:

• pickle

  TypeError: cannot pickle 'mappingproxy' object
  

• jsonpickle

  AttributeError: 'Absent' object attribute '_instance' is read-only
  

• pydantic

  PydanticSchemaGenerationError: Unable to generate pydantic-core schema for mappingproxy[str, str]. Set `arbitrary_types_allowed=True` in the model_config to ignore this error or implement `__get_pydantic_core_schema__` on your type to fully support it.
  

• msgspec

  TypeError: Encoding objects of type Absent is unsupported
  

• cattrs

  TypeError: Object of type Absent is not JSON serializable
  

• mashumaro

  UnserializableField: Field "fallback" of type object in Job is not serializable
  

Additionally, treekle reads bad inputs all the way through:

@dataclass
class Team:
    a: User
    b: User
    c: User


bad = '{"a": {"name": "ada"}, "b": {"name": 7}, "c": {"name": 8}}'
try:
    from_plain(json.loads(bad), Team)
except ReadError as error:
    error.partial
    # Team(a=User(name='ada'),
    #      b=User(name=Invalid(raw=7, reason='cannot read 7 as str')),
    #      c=User(name=Invalid(raw=8, reason='cannot read 8 as str')))

Every other library on the same bad:

• jsonpickle

  {'a': {'name': 'ada'}, 'b': {'name': 7}, 'c': {'name': 8}}
  

• pydantic

  ValidationError: 2 validation errors for Team
  b.name
    Input should be a valid string [type=string_type, input_value=7, input_type=int]
  c.name
    Input should be a valid string [type=string_type, input_value=8, input_type=int]
  

• msgspec

  ValidationError: Expected `str`, got `int` - at `$.b.name`
  

• cattrs

  Team(a=User(name='ada'), b=User(name='7'), c=User(name='8'))
  

• mashumaro

  Team(a=User(name='ada'), b=User(name='7'), c=User(name='8'))
  

Captured with jsonpickle 4.1.3, pydantic 2.13.5, msgspec 0.22.0, cattrs 26.2.1, and mashumaro 3.23.

A lambda has no import path, so it is refused when written, not when read:

to_plain(lambda x: x)
# TypeError: Cannot serialize <function <lambda> ...>: import path
# '__main__.<lambda>' does not resolve to the same object.

Features

Tags for what JSON lacks

Anything a wire format cannot carry natively becomes a py/* tag, spelled as jsonpickle spells it where one exists:

Shared objects and cycles

A repeat is written as py/ref, the path to its first occurrence, so model.encoder is model.decoder survives the round trip. Cycles terminate the same way. Older py/id back-references still read.

The type decides, unless a tag does

from_plain(data, T) reads data as T: a JSON array as a tuple[int, int], "red" as Color.RED, a dict as a dataclass. Where the data carries a tag, the tag decides, so a field typed object or a Protocol reads back as whatever class the payload names, if that class fits the annotation. Importing a class by name is gated behind allow_imports=True.

Best-effort decoding

A bad part does not stop the read. ReadError.partial is the value with an Invalid in place of each bad part; ReadError.bad maps each bad part's path to its Invalid.

Wire-invariant

The core never parses or prints text. treekle.json_loads is the one reader: json_loads(text, T) parses and reads as T in one call. This is its whole body, minus overloads and docstring:

import json


def json_loads(
    text: str | bytes,
    target: object = ABSENT,
    *,
    hooks: Hooks = MappingProxyType({}),
    allow_imports: bool = False,
    strict: bool = True,
) -> object:
    tree = cast("MutablePlainTree", json.loads(text))
    if target is ABSENT:
        return tree
    return from_plain(
        tree,
        target,
        hooks=hooks,
        allow_imports=allow_imports,
        strict=strict,
    )

Why not another serializer

tl;dr: The pickle-style libraries have a nearly orthogonal feature set to the JSON-style libraries. The group either is forgiving about types (like callables) and forgoes type-strictness or cannot tolerate types to achieve safety. jsonpickle is arguably the most similar to treekle (and was our default choice until making treekle).

✅ = yes, ❌ = no. Star counts checked 2026-10-11. Corrections welcome -- open a PR.

• C/Rust: the core is a compiled extension, not pure Python.
• stdlib: part of the standard library, or importing nothing outside it.
• plain: encodes to plain dicts, lists, and scalars, so any writer stores it: JSON, YAML, TOML.
• typed result: a type checker infers T from decode(data, T), not Any.
• typed contents: every nested field and element is checked against its annotation, e.g. list[Layer]. An isinstance check on jsonpickle's result would fix typed result, not this.
• untagged input: data with no py/* tags reads as the declared type, so hand-written config works.
• class from data: decode builds the class the payload names by import path (a subclass, a Protocol implementation, or any class) and rejects one that does not fit the field's annotation.
• callables: a function round-trips by import path, with no special field type.
• shared refs: an object referenced twice decodes as one object; cycles too.
• best-effort: bad input yields the partial value and every bad part's location.

Details: each cell is what a probe of jsonpickle 4.1, pydantic 2.13, msgspec 0.22, cattrs 26.2, and mashumaro 3.23 returned:

• plain: the call that encodes to plain data.
• typed result: what basedpyright infers for decoding a dataclass Layer.
• typed contents: Net with layers: list[Layer], given layers[0].width = "x". jsonpickle with a top-level isinstance(obj, Net) check returned Net(layers=[{'width': 'x'}]).
• untagged input: a valid Net payload with no py/* tags.
• class from data: a payload naming a class, read into a base-class field, a Protocol field, and an object field. cattrs keeps the subclass with include_subclasses; pydantic and msgspec need a closed tagged union. "misfit": a payload naming a class that is neither a subclass of the base-class field nor an implementation of the Protocol field.
• callables: a field holding a module-level function.
• shared refs: one object in two fields.
• best-effort: two bad fields.

One cycle shape fails to read: one through a dataclass decoded as its declared type.

Speed

Times are totals over the exp000 config of each of 43 priml baselines, with each library's time as a multiple of msgspec-struct's under ×.

• warm: repeat calls on classes each library has already seen.
• cold: the first call on classes no library has seen.

• encode: each library on the config itself. msgspec is given enc_hook=repr, its only way past the callables a config holds, and writes no class names or shared references, so it writes less than treekle. Both msgspec rows encode alike.
• decode: msgspec cannot decode the configs: its unions may not mix a class with anything but None. So decode times the closest thing every library reads: each config rebuilt as dataclasses holding only plain values. msgspec-struct reads it into tagged msgspec.Struct twins; msgspec-dataclass into the dataclasses themselves, which fails (❌) on 14 configs whose unions hold two dataclasses it cannot tell apart.
• treekle-rust, treekle-python: the compiled core, built profile-guided as the release wheels are, and the Python fallback a platform without a wheel gets.

Python 3.14, one core of an Intel Core Ultra 7 255H. Reproduce with scripts/bench_configs.py.