mt_metadata.base.pydantic_helpers
=================================

.. py:module:: mt_metadata.base.pydantic_helpers

.. autoapi-nested-parse::

   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.

   .. rubric:: 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
----------

.. autoapisummary::

   mt_metadata.base.pydantic_helpers.APP_NAME
   mt_metadata.base.pydantic_helpers.SPECIAL_CASE_MODEL_NAMES


Functions
---------

.. autoapisummary::

   mt_metadata.base.pydantic_helpers.get_all_fields_serializable
   mt_metadata.base.pydantic_helpers.flatten_field_tree_map
   mt_metadata.base.pydantic_helpers.clear_field_caches


Module Contents
---------------

.. py:data:: APP_NAME
   :value: 'mt_metadata'


.. py:data:: SPECIAL_CASE_MODEL_NAMES

.. py:function:: 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.

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

   :returns: A nested, JSON-serializable dictionary describing the model's fields.
             Leaf nodes are field summaries; nested nodes correspond to BaseModel-typed fields.
   :rtype: Dict[str, Any]

   .. rubric:: 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.


.. py:function:: 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.

   :param tree: The nested field tree. Leaf nodes are dicts that contain `"__field__": True`;
                nested nodes are dictionaries whose values are more field trees.
   :type tree: Dict[str, Any]
   :param prefix: A prefix to prepend to each key (useful when flattening under a known root),
                  by default "".
   :type prefix: str, optional

   :returns: A mapping from dotted paths (e.g., "inner.a") to the corresponding leaf summary
             dictionaries (e.g., {"__field__": True, "type": "<class 'int'>", ...}).
   :rtype: Dict[str, Dict[str, Any]]

   .. rubric:: 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.


.. py:function:: clear_field_caches()

   Clear the in-memory field tree cache.

   This does not remove any on-disk cache files.