Field Paths

Field paths are the keys in the dict[str, FieldMetadata] returned by extract().

Path type	Separator	Example
Nested field	.	"address.street", "company.departments.name"
Derived field	__	"created_at__year", "price__normalized"

FieldMetadata does not store the path itself — it is implicit in the dictionary key.

@dataclass
class Address:
    street: str
    city: str

@dataclass
class Person:
    name: str
    address: Address

extractor = MetadataExtractor()
metadata = extractor.extract(Person)

assert "name" in metadata
assert "address" in metadata
assert "address.street" in metadata
assert "address.city" in metadata

Reconstructing a Path from Metadata

def get_field_path(field_meta: FieldMetadata) -> str:
    parts = [field_meta.field_name]
    current = field_meta.parent_field
    while current:
        parts.insert(0, current.field_name)
        current = current.parent_field
    return ".".join(parts)

assert get_field_path(metadata["address.street"]) == "address.street"

FieldsPath Helper

from fields_metadata import FieldsPath

path = FieldsPath.from_field_metadata("address.street", metadata)
assert path.get_path_string() == "address.street"

for field_meta in path:
    print(f"{field_meta.field_name}: {field_meta.field_type}")