Type-Based Derived Field Hooks

Generate derived fields automatically based on a field's effective_type.

API: extractor.register_type_hook(field_type, callback)

• field_type: the type that triggers the hook (e.g. datetime, int)
• callback: Callable[[TMetadata], dict[str, TMetadata]] — receives the source field's metadata and returns a mapping of derived field paths to metadata objects

from datetime import datetime
from dataclasses import dataclass
from fields_metadata import MetadataExtractor, FieldMetadata, FieldsPath

@dataclass
class Event:
    title: str
    event_datetime: datetime

extractor = MetadataExtractor()

def datetime_components(source: FieldMetadata) -> dict[str, FieldMetadata]:
    metadata_map = extractor._cache.get(Event, {})
    path_obj = FieldsPath.from_field_metadata(source.field_name, metadata_map)
    base = path_obj.get_path_string(complimentary=True) if path_obj else source.field_name

    return {
        f"{base}__year": FieldMetadata(
            field_name=f"{source.field_name}__year",
            field_type=int, effective_type=int,
            numeric=True, derived=True, parent_field=base,
            doc="Year of the date",
            extra={"suggested_validation": "year"},
        ),
        f"{base}__month": FieldMetadata(
            field_name=f"{source.field_name}__month",
            field_type=int, effective_type=int,
            numeric=True, derived=True, parent_field=base,
            doc="Month of the date",
            extra={"min_value": 1, "max_value": 12, "suggested_validation": "month"},
        ),
    }

extractor.register_type_hook(datetime, datetime_components)
metadata = extractor.extract(Event)

assert metadata["event_datetime__year"].derived is True
assert metadata["event_datetime__month"].derived is True

Derived field paths use __ as separator to distinguish them from nested paths.