serializable

serializable saves Python objects as JSON or pickles and reconstructs the same classes, including nested objects. Subclass DataclassSerializable for a dataclass, or Serializable for a class whose constructor arguments describe its state. It is the serialization layer of the OpenVax libraries: varcode and vaxrank results, pyensembl genomes and sercol collections all save and reload through it.

Install

python -m pip install serializable

Python 3.11 or later is required.

Quick start

from dataclasses import dataclass
from serializable import DataclassSerializable

@dataclass
class Point(DataclassSerializable):
    x: float
    y: float

point = Point(1.0, 2.0)
restored = Point.from_json(point.to_json())
print(point.to_dict())
print(restored)
print(restored == point)

{'x': 1.0, 'y': 2.0}
Point(x=1.0, y=2.0)
True

to_dict() gives the constructor fields; to_json() also records the class and its module so from_json() can rebuild it. The dataclass keeps its own generated constructor, equality, representation and hashing. The recorded module and class must be importable when loading, so load data only from sources you trust. A class or function defined inside another function can't be looked up again, so serializing it raises ValueError.

Documentation

The documentation covers, in reading order:

1. Getting started: the example above, choosing a base class, and the format's limits.
2. Save classes and files: constructor-based classes, JSON files, pickles and nested containers.
3. Change field names: read data written before a constructor argument was renamed.
4. API reference.

Development

python -m pip install -e ".[dev]"   # or ./develop.sh, which uses .venv
./format.sh   # ruff format
./lint.sh     # ruff check, ruff format --check and mypy
./test.sh     # pytest with coverage
python -m pip install -r requirements-docs.txt
./docs.sh     # mkdocs build --strict, then a rendered-link check
python scripts/check_docs_examples.py   # run docs examples, compare output

Every PR bumps serializable/version.py. Maintainers release with ./deploy.sh from a clean master.

License

Apache 2.0; see LICENSE.