sift_client.util.metadata ¶

CLASS	DESCRIPTION
`Metadata`	Entity metadata: a dict of key -> first value, plus access to every

FUNCTION	DESCRIPTION
`expand_metadata_for_write`	Expand a `Metadata` mapping into a plain write dict, keeping every value.
`metadata_dict_to_proto`	Converts metadata dictionary into a list of MetadataValue objects.
`metadata_proto_to_dict`	Converts a list of MetadataValue objects into a Metadata mapping.

Metadata ¶

Metadata(
    first_values: dict[str, str | float | bool]
    | None = None,
    all_values: dict[str, list[str | float | bool]]
    | None = None,
)

Bases: Dict[str, Union[str, float, bool]]

Entity metadata: a dict of key -> first value, plus access to every value of a key via getall().

A metadata key may hold multiple values (multi-value metadata), kept in canonical order. Plain dict access (md["k"], md.get("k"), iteration, ==) sees the first value only -- the same value every single-value context uses -- so existing code written against scalar metadata keeps working unchanged. getall(key) returns the full ordered value list; its first element is always the dict value.

Build the mapping from a first-value dict and optional full value lists.

METHOD	DESCRIPTION
`getall`	Return every value of `key` as a new list, in canonical order.

getall ¶

getall(key: str) -> list[str | float | bool]

Return every value of key as a new list, in canonical order.

Keys absent from the metadata yield []; keys holding a single value yield a one-element list.

expand_metadata_for_write ¶

expand_metadata_for_write(
    metadata: Mapping[str, str | float | bool | list[str]],
) -> Mapping[str, str | float | bool | list[str]]

Expand a Metadata mapping into a plain write dict, keeping every value.

Metadata hides values beyond the first behind getall(); pydantic write models serialize fields with model_dump, which would flatten the mapping to its first-value dict view and silently drop the rest. Calling this in a before-validator keeps round-trips (update.metadata = entity.metadata) lossless: single-value keys stay scalars, multi-value keys become lists.

Any other mapping is returned unchanged.

metadata_dict_to_proto ¶

metadata_dict_to_proto(
    _metadata: Mapping[str, str | float | bool | list[str]],
) -> list[MetadataValue]

Converts metadata dictionary into a list of MetadataValue objects.

A value may be a scalar (str | float | bool) or a list[str]. A list produces one MetadataValue per element under the same key, in list order -- the canonical order for multi-value metadata. Only string values may repeat (mirroring the backend rule), so list elements must be strings, and a list must not be empty: replace semantics mean a key is removed by omitting it, not by writing an empty list.

PARAMETER	DESCRIPTION
`_metadata`	Dictionary of metadata key-value pairs. TYPE: `Mapping[str, str \| float \| bool \| list[str]]`

RETURNS	DESCRIPTION
`list[MetadataValue]`	List of MetadataValue objects.

metadata_proto_to_dict ¶

metadata_proto_to_dict(
    metadata: list[MetadataValue],
) -> Metadata

Converts a list of MetadataValue objects into a Metadata mapping.

A key may appear multiple times when it holds multiple values (multi-value metadata). The mapping's dict view keeps the first value of each key -- the API returns values in canonical order, so this matches the value every other single-value context (e.g. backend flattening) uses -- and Metadata.getall(key) returns the full ordered list.

PARAMETER	DESCRIPTION
`metadata`	List of MetadataValue objects. TYPE: `list[MetadataValue]`

RETURNS	DESCRIPTION
`Metadata`	Metadata mapping of key-value pairs (first value per key; all values
`Metadata`	via getall).