archimedes.tree.register_dataclass¶

archimedes.tree.register_dataclass( nodetype: Typ, data_fields: Sequence[str] | None = None, meta_fields: Sequence[str] | None = None, drop_fields: Sequence[str] = (), ) → Typ¶

This function registers a dataclass type as a tree node, with control over which fields are treated as leaf data versus metadata. Fields marked as metadata are excluded from transformations and treated as static configuration.

Parameters:

nodetype (type) – The dataclass type to register as tree-compatible.
data_fields (sequence of str, optional) – Names of fields that should be treated as data (leaf values). If None and the type is a dataclass, fields are inferred based on metadata.
meta_fields (sequence of str, optional) – Names of fields that should be treated as metadata. If None and the type is a dataclass, fields are inferred based on metadata.
drop_fields (sequence of str, optional) – Names of fields to exclude from both data and metadata categories.

Returns:

nodetype – The input type, now registered as tree-compatible.

Return type:

type

Notes

When to use:

For fine-grained control over how dataclass fields are handled in tree ops
When you need some fields treated as static configuration rather than data
For advanced customization of tree behavior for complex data models

Usually, instead of using this function directly, you’ll want to use the @struct decorator which handles registration automatically and allows field classification via the field(static=True) parameter. This function is mainly used internally to register the decorated classes.

Data fields are included when flattening a tree and are considered leaf values that can be transformed. Meta fields are static configuration not included in transformations but preserved during reconstruction.

Raises:

TypeError – If data_fields and meta_fields aren’t both specified when either is specified, or if they are both None and the type is not a dataclass.
ValueError – If the specified fields don’t match the actual dataclass fields with init=True.