Persistence

Three free functions and nothing else (ADR-0072): the library hands back bytes and takes bytes; where those bytes live is entirely the user’s.

dataforge_ml._serialization.serialize(obj)

Serialize a fitted unit, an imputation decision, or a profile to bytes.

The single write door of the persistence boundary (ADR-0072). It dispatches on the object’s type and produces a self-describing JSON-header envelope the user stores anywhere; a fitted unit additionally carries an opaque joblib payload holding its learned state. A decision’s hyperparameter-override delta rides inside its envelope, so a round-tripped plan re-stamps the same merged units.

Parameters:

obj (FittedUnit or ImputationDecision or StructuralProfileResult) – The object to persist. Any object satisfying the fitted-unit contract (a target_columns property) is serialized through the unit path.

Returns:

The serialized envelope, consumed by deserialize() and inspect().

Return type:

bytes

dataforge_ml._serialization.deserialize(obj)

Reconstruct the original object from bytes produced by serialize().

Polymorphic (ADR-0072): the envelope’s kind tag selects the object type, so the caller never declares what it is deserializing. A decision and a profile rebuild from their JSON data; a fitted unit runs the reconstruction gates — the produced_with version check and the payload SHA-256 — before its joblib payload is unpickled, so a unit produced under an incompatible library/estimator version refuses here rather than transforming to subtly wrong numbers later.

Parameters:

obj (bytes) – Bytes previously returned by serialize().

Returns:

The reconstructed object; a fitted unit’s transform is bit-identical to the original’s on equal input.

Return type:

FittedUnit or ImputationDecision or StructuralProfileResult

Raises:

IncompatibleArtifactError – If the envelope’s kind is unrecognised, or a fitted unit’s format schema or reconstruction-critical dependency version is incompatible, or its payload checksum does not match.

Warning

Deserializing a fitted unit unpickles its payload, which executes arbitrary code — only deserialize bytes you produced or trust. See the module-level trust-boundary note.

dataforge_ml._serialization.inspect(obj)

Read a serialized envelope’s header without unpickling its payload.

The pre-deserialize probe (ADR-0072): it parses only the JSON header, so a caller can check an artifact’s kind, format-schema/library versions, and — for a fitted unit — its produced_with provenance stamp before trusting untrusted-transport bytes into an unpickling deserialize(). The bulky data payload of a decision or profile envelope is omitted; the fitted unit’s opaque joblib tail is never touched.

Parameters:

obj (bytes) – Bytes previously returned by serialize().

Returns:

The envelope header: always kind, format_schema_version, and library_version; for a fitted unit also produced_with, payload_sha256, unit_type, and columns.

Return type:

dict

class dataforge_ml._serialization.IncompatibleArtifactError

Bases: Exception

Raised when a stored artifact cannot be reconstructed safely.

Signals a reconstruction/correctness failure (ADR-0063): the saved bytes cannot be rebuilt faithfully under the format schema and libraries installed right now — a newer format-schema major, a mismatched DataForgeML / scikit-learn / numpy / joblib version, or a payload whose SHA-256 checksum does not match its header. With content-addressed identity and load-for-reuse validation retired (ADR-0072), this is the only load-time failure the library raises; relevance is no longer checked at deserialize.

class dataforge_ml._serialization.ArtifactPythonVersionWarning

Bases: UserWarning

Emitted when an artifact loads under a different Python version.

Signals the one lenient branch of the ADR-0063 load policy: the artifact was saved under a Python version other than the one running now. CPython’s pickle protocol is stable across minor versions, so the load proceeds — this warning is the only signal. Unlike a scikit-learn / numpy / joblib mismatch (which refuses with IncompatibleArtifactError), a Python drift is tolerated. Suppress with warnings.filterwarnings("ignore", category=ArtifactPythonVersionWarning).