Skip to content

fields-metadata

Annotations

Annotations

`annotated-types` Annotations

Annotation	Effect
`DocInfo(text)`	`metadata.doc = text`
`Len(n)` / `MinLen(n)` / `MaxLen(n)`	`metadata.extra['min_length']`, `metadata.extra['max_length']`
`Ge(n)` / `Le(n)`	`metadata.extra['min_value']`, `metadata.extra['max_value']`
`Unit(u)`	`metadata.extra['unit']`

Built-in Library Annotations

Annotation	Effect
`FinalType()`	Per-field: prevents composite type expansion (`metadata.composite = False`)
`Internal()`	Marks the field as internal-only: omits it (and, if composite, its whole nested subtree) from `MetadataExtractor.extract()` results
`Multiline()`	`metadata.extra['multiline'] = True`
`HumanReadableId()`	`metadata.extra['human_readable_id'] = True`; sets `suggested_human_sorting_field` on parent
`Order(n)`	`metadata.order = n` (integer; lower = first; default `1000`)
`NonCategorical()`	`metadata.categorical = False`
`SemanticClassification(s)`	`metadata.classification['semantic'] = s`
`RoleClassification(roles)`	`metadata.classification['role'] = roles`
`TLPClassification(level)`	`metadata.classification['tlp'] = level`
`WellKnownValues(values)`	`metadata.extra['well_known_values'] = values` (pass `None` to remove)
`InternationalURNAnnotation()`	`metadata.extra['urn_type'] = "international"`
`SuggestedValidation(v)`	`metadata.extra['suggested_validation'] = v` (auto-set for pydantic-extra-types country fields)

@final_type decorator marks a whole class as final (equivalent to always applying FinalType()).

Example

from typing import Annotated
from annotated_types import DocInfo, MinLen, MaxLen, Ge, Le, Unit
from fields_metadata import (
    Multiline, HumanReadableId, Order,
    SemanticClassification, TLPClassification, TLPLevel,
    WellKnownValues, NonCategorical,
)

@dataclass
class Article:
    title: Annotated[str, MinLen(1), MaxLen(200), DocInfo("Title")]
    content: Annotated[str, Multiline()]
    word_count: Annotated[int, Ge(0), Le(10000), Unit("words")]
    category: Annotated[str, SemanticClassification("topic"), Order(10)]
    sensitivity: Annotated[str, TLPClassification(TLPLevel.GREEN)]
    status: Annotated[str, WellKnownValues(("draft", "published", "archived"))]
    score: Annotated[float, NonCategorical()]

Omitting Fields with `Internal`

Internal is for fields that are internal bookkeeping on the model itself (schema versions, sync/cache state, etc.) rather than domain data meant for metadata consumers. It works identically for dataclass fields and Pydantic Fields, since it is read from the same typing.Annotated metadata as every other annotation:

from typing import Annotated
from fields_metadata import Internal

@dataclass
class SyncState:
    last_synced_at: str
    etag: str

@dataclass
class Document:
    title: str
    schema_version: Annotated[int, Internal()]
    sync_state: Annotated[SyncState, Internal()]

metadata = MetadataExtractor().extract(Document)
assert set(metadata) == {"title"}

The nested subtree is omitted too: neither sync_state nor sync_state.last_synced_at / sync_state.etag appear in the result above.

`HumanReadableId` Parent Propagation

When a nested field has HumanReadableId, its parent gains extra['suggested_human_sorting_field'] pointing to the full path:

assert metadata["author.name"].extra["human_readable_id"] is True
assert metadata["author"].extra["suggested_human_sorting_field"] == "author.name"