Base class with serialization methods for user-defined Python objects
python -m pip install serializableIf you're using @dataclass (e.g. in vaxrank, pyensembl, or varcode), inherit from DataclassSerializable instead of Serializable. It provides the same serialization surface — to_dict / from_dict / to_json / from_json — but leaves __init__, __eq__, __repr__, and __hash__ to @dataclass, so you get dataclass-native equality and repr without conflicts.
from dataclasses import dataclass
from serializable import DataclassSerializable
@dataclass
class Point(DataclassSerializable):
x: float
y: float
p = Point(1.0, 2.0)
assert Point.from_json(p.to_json()) == pThe on-wire JSON format is identical to Serializable, so mixed codebases interoperate: a DataclassSerializable instance can reference a legacy Serializable object (and vice versa) and still round-trip cleanly. The _SERIALIZABLE_KEYWORD_ALIASES hook works the same way for migrating field names across releases.
Classes which inherit from Serializable are enabled with default implementations of
to_json, from_json, __reduce__ (for pickling), and other serialization
helpers.
A derived class must either:
- have a member data matching the name of each positional argument to
__init__ - provide a user-defined
to_dict()method which returns a dictionary whose keys match the arguments to__init__
Keyword-only arguments to __init__ (those after *) are left out of the default to_dict(), so they can be used for constructor options which aren't part of an object's serialized state.
Pickling goes through the same to_dict() / from_dict() pair, so pickles also survive renamed keywords (see below). Pickles written by versions before 1.2.0 can still be loaded.
If you change the keyword arguments to a class which derives from Serializable but would like to be able to deserialize older JSON representations then you can define a class-level dictionary called _SERIALIZABLE_KEYWORD_ALIASES which maps old keywords to new names (or None if a keyword was removed).
The format records Python classes and modules, which must remain importable when
loading data. Keys starting with two underscores are reserved. Nested Python
values require the serialization helpers rather than ordinary JSON encoding.
to_json raises ValueError for NaN or infinite floats, which standard JSON
can't represent; from_json still reads the NaN / Infinity literals which
older versions wrote.
The site builds with python -m pip install -r requirements-docs.txt followed
by ./docs.sh. Run python scripts/check_docs_examples.py to check the examples.