Skip to content

yggdrasil.pickle

pickle

Yggdrasil's serde wire format — re-export the canonical surface.

The actual implementation lives under :mod:yggdrasil.pickle.ser; this package re-exposes the four entry points (:func:dump, :func:dumps, :func:load, :func:loads) plus :func:serialize and the error / Serialized / Tags types at the top level so call sites can write the canonical from yggdrasil.pickle import dumps, loads without reaching into .ser.

Re-exports go through __getattr__ (PEP 562) rather than a top-level import because yggdrasil.pickle.ser.serde pulls in :mod:yggdrasil.io, which transitively re-enters :mod:yggdrasil.data during data_field.py's own load (data_field.py does import yggdrasil.pickle.json before its classes are bound). An eager re-export here would race that import and raise ImportError: cannot import name 'Field' from partially initialized module. Deferring to first attribute access breaks the cycle.

HeaderDecodeError

Bases: SerializationError

Raised when a header cannot be parsed from the buffer.

InvalidCodecError

Bases: SerializationError

Raised when an unknown codec id is encountered.

MetadataDecodeError

Bases: SerializationError

Raised when encoded metadata is malformed.

SerializationError

Bases: RuntimeError

Base exception for yggdrasil.pickle.ser.

Serialized dataclass 

Serialized(head: Header, data: IO)

Bases: ABC, Generic[T]

module_and_name staticmethod 

module_and_name(obj: Any, *, fallback: str = '') -> tuple[str, str]

Return (module, qualname) for obj.

Robust across Python objects, including many C-extension / PyArrow objects where module may be missing or misleading.

dump 

dump(
    obj: Any,
    fp: IO[bytes] | Path | str,
    *,
    metadata: Mapping[bytes, bytes] | None = None,
    codec: int | None = None
) -> None

Serialise obj and write it to fp (file-like, :class:~pathlib.Path, or str path).

dumps 

dumps(
    obj: Any,
    *,
    metadata: Mapping[bytes, bytes] | None = None,
    codec: int | None = None,
    b64: bool = False
) -> bytes | str

Serialise obj to bytes, or to a URL-safe base-64 str when b64 is True.

load 

load(
    fp: IO[bytes] | Path | str,
    *,
    unpickle: bool = True,
    clean_corrupted: bool = False,
    default: Any = None
) -> Any

Read a serialised payload from fp and optionally unpickle it.

loads 

loads(s: bytes | str, *, unpickle: bool = True) -> Any

Deserialise from s (bytes or URL-safe base-64 str).

serialize 

serialize(
    obj: Any,
    *,
    metadata: Mapping[bytes, bytes] | None = None,
    codec: int | None = None
) -> Serialized

Wrap obj in a :class:Serialized instance without writing to a buffer.