Skip to content

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()

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.

Parameters
  • serializer Serializer — The serializer to register.
Returns None

registered_serializers()

def registered_serializers() -> dict[type | types.UnionType, Serializer]: ...

Return a snapshot of the registry, for diagnostics.

Returns dict[type | types.UnionType, Serializer]

serializer_for()

def serializer_for(annotation: object) -> Serializer | None: ...

Resolve the serializer for a type annotation, if any.

Parameters
  • annotation object — A resolved annotation: a plain type, a union of supported types, or Annotated[T, serializer].
Returns Serializer | None — The override serializer from 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()

def serializer_for_descriptor(
    type_id: str, format_id: str, format_version: int
) -> Serializer: ...

Resolve an installed reader from persistent output metadata.

Parameters
  • type_id str — Logical type ID stored in the descriptor.
  • format_id str — Stored encoding ID.
  • format_version int — Stored encoding version.
Returns Serializer

serializer_for_value()

def serializer_for_value(value: object) -> Serializer | None: ...

Resolve the serializer for a runtime value (output serialization).

Parameters
  • value object — The object a task body returned.
Returns Serializer | None — The serializer registered for type(value) (exact match, then the type’s own dunders, then Pydantic fields), or None.

value_digest()

def value_digest(value: Any) -> str: ...

Hash an exact typed value, including defaults and codec identities.

Parameters
  • value Any — A supported scalar, container, or serializer-bearing object.
Returns str — The digest of its lossless field encoding.

Classes

Serializer

class 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.

Parameters
  • python_type type | types.UnionType — Exact Python type or a union of serializable types; register subclasses separately.
  • format_name str — Short format tag ("hdf5", "netcdf", "json"), for diagnostics and docs.
  • serialize Callable[[Any], bytes] — Turn an instance into bytes.
  • deserialize Callable[[bytes], Any] — Turn bytes back into an instance.
  • deserialize_path Callable[[pathlib.Path], Any] | None = None — Optional deserializer receiving the artifact’s local path.
  • type_id str = '' — 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_id str = '' — Stable encoding ID; defaults to format_name.
  • format_version int = 1 — Positive encoding version. Old readers remain registered when a newer writer is registered.
  • member_type_ids tuple[str, ...] = () — Logical type IDs accepted by a union annotation.
Methods
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.

Parameters
  • stored Serializer — Reader selected by the stored artifact descriptor.
Returns bool