haive.core.schema.utils ======================= .. py:module:: haive.core.schema.utils .. autoapi-nested-parse:: Utility functions for schema manipulation in the Haive framework. This module provides the SchemaUtils class containing static methods for working with schemas in the Haive Schema System. It includes utilities for formatting type annotations, extracting field information, creating field definitions, and building schemas programmatically. The utilities in this module are primarily used by the SchemaComposer and StateSchemaManager classes, but they can also be useful for custom schema manipulation tasks or when working with schemas directly. Key capabilities include: - Type annotation formatting for readable representation of complex types - Field information extraction from Pydantic field objects - Pydantic field creation with proper metadata - Support for special types like Optional, Union, and generics - Helper functions for schema display and debug visualization .. rubric:: Examples from haive.core.schema.utils import SchemaUtils from typing import List, Optional # Format a type annotation type_str = SchemaUtils.format_type_annotation(List[Optional[str]]) print(type_str) # "List[Optional[str]]" # Extract field info from a Pydantic model from pydantic import BaseModel, Field class MyModel(BaseModel): name: str = Field(default="default", description="User name") field_info = MyModel.model_fields["name"] default, default_repr, desc = SchemaUtils.extract_field_info(field_info) # default = "default", desc = "User name" Classes ------- .. autoapisummary:: haive.core.schema.utils.SchemaUtils Module Contents --------------- .. py:class:: SchemaUtils Utility functions for schema manipulation and formatting. This class provides static methods for working with schema-related tasks such as formatting type annotations, extracting field information, and building state schemas from components. The methods focus on common operations needed when programmatically working with schemas and Pydantic models in the Haive framework. Key methods include: - format_type_annotation: Creates readable string representations of type annotations - extract_field_info: Extracts default values and descriptions from Pydantic fields - create_pydantic_field: Creates Pydantic Field objects with proper metadata - extract_model_info: Analyzes a Pydantic model to extract useful information - format_default_value: Creates string representations of default values - analyze_field_type: Determines characteristics of field types (generic, optional, etc.) These utilities are designed to work with both Pydantic v1 and v2, handling differences in field structures and model internals. They're used extensively throughout the Haive Schema System to provide consistent handling of types and field definitions. .. py:method:: add_field_to_schema(schema, name, field_type, default = None, description = None, shared = False, reducer = None) :staticmethod: Add a field to an existing schema class. :param schema: Existing schema class. :param name: Field name to add. :param field_type: Type of the field. :param default: Default value. :param description: Optional field description. :param shared: Whether the field is shared with parent. :param reducer: Optional reducer function. :returns: Updated schema class with the new field. .. py:method:: build_state_schema(name, fields, shared_fields = None, reducers = None, base_class = None) :staticmethod: Build a state schema from field definitions. :param name: Name for the schema class. :param fields: Dictionary mapping field names to (type, default) tuples. :param shared_fields: Optional list of fields shared with parent. :param reducers: Optional dictionary mapping field names to reducer functions. :param base_class: Optional base class (defaults to StateSchema). :returns: A new schema class. .. py:method:: extract_field_info(field_info) :staticmethod: Extract useful information from a Pydantic FieldInfo. :param field_info: Pydantic field info object. :returns: Tuple of (default_value, default_string_representation, description). .. py:method:: format_schema_as_python(schema_name, fields, properties = None, computed_properties = None, class_methods = None, static_methods = None, field_descriptions = None, shared_fields = None, reducer_fields = None, base_class = 'StateSchema') :staticmethod: Format a schema definition as Python code. Creates a string representation of a schema class with all its fields, properties, methods, and metadata. :param schema_name: Name of the schema class. :param fields: Dictionary of field names to (type, field_info) tuples. :param properties: Optional dictionary of property names to property methods. :param computed_properties: Optional dictionary of computed property definitions. :param class_methods: Optional dictionary of class method names to methods. :param static_methods: Optional dictionary of static method names to methods. :param field_descriptions: Optional dictionary of field descriptions. :param shared_fields: Optional set of field names that are shared with parent. :param reducer_fields: Optional dictionary of fields with reducer functions. :param base_class: Base class name for the schema. :returns: String containing the Python code representation. .. py:method:: format_type_annotation(type_hint) :staticmethod: Format a type hint for pretty printing. Creates a clean, readable string representation of a type annotation. :param type_hint: The type hint to format. :returns: A clean string representation of the type. .. py:method:: get_reducer_name(reducer) :staticmethod: Get a serializable name for a reducer function. :param reducer: Reducer function. :returns: Serializable name for the reducer.