mt_metadata.base.pydantic_helpers

Field introspection utilities for Pydantic BaseModel classes with lazy in-memory caching and optional on-disk caching.

This module builds a JSON-serializable nested “field tree” for any Pydantic BaseModel, avoiding instantiation and guarding against infinite recursion.

Leaf nodes are serializable summaries and include:

  • type

  • default

  • deprecated

  • description

  • title

  • default_factory (if present)

  • enum (for Enum/Literal types)

  • enum_names (for Enum subclasses)

  • examples (from Field(…, json_schema_extra={‘examples’: […]}))

  • required (from Field(…, json_schema_extra={‘required’: True/False}))

  • units (from Field(…, json_schema_extra={‘units’: ‘…’}))

  • has_validators (True if any field validators are present)

  • constraints:

    • ge, le, gt, lt

    • multiple_of

    • min_length, max_length, pattern

    • min_items, max_items, unique_items

    • const, format

    • nullable

Nested nodes represent BaseModel-typed fields and contain further trees.

Notes

  • List, Dict, and Union types are treated as simple fields (non-expanded), unless the Union directly contains a BaseModel, in which case the first BaseModel type is expanded.

  • A special-case hook (SPECIAL_CASE_MODEL_NAMES) lets you treat certain BaseModel types (e.g., “MTime”) as simple fields.

  • Constraints are derived from Pydantic’s JSON Schema via TypeAdapter(annotation).json_schema().

Attributes

APP_NAME

SPECIAL_CASE_MODEL_NAMES

Functions

get_all_fields_serializable(model_or_cls)

Build a JSON-serializable nested dictionary of fields for a Pydantic BaseModel.

flatten_field_tree_map(tree[, prefix])

Flatten a nested field tree (as returned by get_all_fields_serializable) into

clear_field_caches()

Clear the in-memory field tree cache.

Module Contents

mt_metadata.base.pydantic_helpers.APP_NAME = 'mt_metadata'
mt_metadata.base.pydantic_helpers.SPECIAL_CASE_MODEL_NAMES
mt_metadata.base.pydantic_helpers.get_all_fields_serializable(model_or_cls)

Build a JSON-serializable nested dictionary of fields for a Pydantic BaseModel.

This function avoids instantiating models, caches results in memory, and (optionally) persists/retrieves the serialized tree to/from disk.

Parameters:

model_or_cls (type[BaseModel] or BaseModel) – The BaseModel class (preferred) or an instance. If an instance is provided, its class will be used.

Returns:

A nested, JSON-serializable dictionary describing the model’s fields. Leaf nodes are field summaries; nested nodes correspond to BaseModel-typed fields.

Return type:

Dict[str, Any]

Notes

  • Uses a sentinel write to the cache prior to recursion to break cycles.

  • The on-disk cache file name is derived from the class’s fully-qualified name, Pydantic version, and a fingerprint of the field schema.

mt_metadata.base.pydantic_helpers.flatten_field_tree_map(tree, prefix='')

Flatten a nested field tree (as returned by get_all_fields_serializable) into a dictionary keyed by dotted field paths, where each value is the leaf field’s serializable summary.

Parameters:

  • tree (Dict[str, Any]) – The nested field tree. Leaf nodes are dicts that contain “__field__”: True; nested nodes are dictionaries whose values are more field trees.

  • prefix (str, optional) – A prefix to prepend to each key (useful when flattening under a known root), by default “”.

Returns:

A mapping from dotted paths (e.g., “inner.a”) to the corresponding leaf summary dictionaries (e.g., {“__field__”: True, “type”: “<class ‘int’>”, …}).

Return type:

Dict[str, Dict[str, Any]]

Notes

  • Only leaf nodes marked with “__field__”: True are included in the output.

  • Nested BaseModel nodes (i.e., dictionaries without `”__field__”: True”) are traversed.

  • Keys are constructed using dot notation to reflect the hierarchy.

mt_metadata.base.pydantic_helpers.clear_field_caches()

Clear the in-memory field tree cache.

This does not remove any on-disk cache files.