salvus.flow.acta.serialization
salvus.flow.acta.serialization salvus flow acta serialization Type-based serialization for task inputs and outputs.
Resolution order: Annotated override, exact-type registry entry, Acta
serialization methods, then Pydantic model fields. Unsupported types have
no fallback serializer.
Pydantic encoding includes defaults, excluded fields, and allowed extras; private and computed attributes are omitted. Nested values use their own serializers. Readers validate fields against the current model.
Union annotations are supported when every member has a serializer. Stored artifacts retain their concrete member’s type ID and encoding.
Registered readers must safely handle stored bytes. Reader registration and content hashes do not establish trust in a shared cache’s writers. A reader must not execute source or import arbitrary names supplied by stored data.
Type IDs, format IDs, versions, and serialized bytes affect artifact identity. Encodings need not be byte-identical for equal values.
Functions
register_serializer()
register_serializer()def register_serializer(serializer: Serializer) -> None: ...Register the default serializer for its exact Python type.
Replaces any existing writer. Use Annotated for per-parameter overrides.
serializerSerializer — The serializer to register.
registered_serializers()
registered_serializers()def registered_serializers() -> dict[type | types.UnionType, Serializer]: ...Return a snapshot of the registry, for diagnostics.
serializer_for()
serializer_for()def serializer_for(annotation: object) -> Serializer | None: ...Resolve the serializer for a type annotation, if any.
annotationobject — A resolved annotation: a plain type, a union of supported types, orAnnotated[T, serializer].
Annotated metadata, else the registered serializer, else one synthesized from the type’s own acta serialization dunders, else a Pydantic field serializer, else None.serializer_for_descriptor()
serializer_for_descriptor()def serializer_for_descriptor(
type_id: str, format_id: str, format_version: int
) -> Serializer: ...Resolve an installed reader from persistent output metadata.
type_idstr — Logical type ID stored in the descriptor.format_idstr — Stored encoding ID.format_versionint — Stored encoding version.
serializer_for_value()
serializer_for_value()def serializer_for_value(value: object) -> Serializer | None: ...Resolve the serializer for a runtime value (output serialization).
valueobject — The object a task body returned.
type(value) (exact match, then the type’s own dunders, then Pydantic fields), or None.value_digest()
value_digest()def value_digest(value: Any) -> str: ...Hash an exact typed value, including defaults and codec identities.
valueAny — A supported scalar, container, or serializer-bearing object.
Classes
Serializer
Serializerclass Serializer(builtins.object):
def __init__(
self,
python_type: type | types.UnionType,
format_name: str,
serialize: Callable[[Any], bytes],
deserialize: Callable[[bytes], Any],
deserialize_path: Callable[[pathlib.Path], Any] | None = None,
type_id: str = "",
format_id: str = "",
format_version: int = 1,
member_type_ids: tuple[str, ...] = (),
) -> None: ...How one Python type round-trips through stored bytes.
python_typetype | types.UnionType — Exact Python type or a union of serializable types; register subclasses separately.format_namestr — Short format tag ("hdf5","netcdf","json"), for diagnostics and docs.serializeCallable[[Any], bytes] — Turn an instance into bytes.deserializeCallable[[bytes], Any] — Turn bytes back into an instance.deserialize_pathCallable[[pathlib.Path], Any] | None =None— Optional deserializer receiving the artifact’s local path.type_idstr =''— Stable logical type ID. Defaults to the type’s own__acta_type_id__, otherwise its qualified Python name. Set explicitly for persistence across module moves. Subclasses do not inherit their parent’s type ID.format_idstr =''— Stable encoding ID; defaults toformat_name.format_versionint =1— Positive encoding version. Old readers remain registered when a newer writer is registered.member_type_idstuple[str, ...] =()— Logical type IDs accepted by a union annotation.
accepts()
accepts()def accepts(self, stored: Serializer) -> bool: ...Accept matching logical identities or concrete subclasses.
Subclasses retain their own stored reader and encoding. A different logical identity for the same Python class is still rejected.
storedSerializer — Reader selected by the stored artifact descriptor.