metadata_json_loader

metadata_json_loader ¤

MetadataJsonLoader ¤

MetadataJsonLoader(json_data: Any, *, strict: bool = True)

Load metadata JSON of shape

{ "uuid": {"0": "...", "1": "...", ...}, "label": {"0": "...", "1": "...", ...}, "config": {"0": {...}, "1": {...}, ...} }

into a pandas DataFrame with flattened config columns.

Create a loader from JSON-like data.

Parameters:

Name	Type	Description	Default
`json_data`	`Any`	Supported shapes: - dict of columns with index-maps: {"uuid": {"0": ...}, "label": {...}, "config": {...}} - dict of columns with lists: {"uuid": [...], "label": [...], "config": [...]} - list of records: [{"uuid": ..., "label": ..., "config": {...}}, ...]	required
`strict`	`bool`	If True, enforce presence of required keys and unique UUIDs.	`True`

from_file `classmethod` ¤

from_file(
    filepath: str, *, strict: bool = True
) -> MetadataJsonLoader

Create a loader from a JSON file on disk.

Parameters:

Name	Type	Description	Default
`filepath`	`str`	Path to the JSON file.	required
`strict`	`bool`	Validation behavior; when True, enforces required fields and unique UUIDs.	`True`

Returns:

Type	Description
`MetadataJsonLoader`	MetadataJsonLoader instance.

from_str `classmethod` ¤

from_str(
    json_str: str, *, strict: bool = True
) -> MetadataJsonLoader

Create a loader from a JSON string.

Parameters:

Name	Type	Description	Default
`json_str`	`str`	Raw JSON content as a string.	required
`strict`	`bool`	Validation behavior; when True, enforces required fields and unique UUIDs.	`True`

Returns:

Type	Description
`MetadataJsonLoader`	MetadataJsonLoader instance.

to_df ¤

to_df(copy: bool = True) -> pd.DataFrame

Return the underlying DataFrame.

Parameters:

Name	Type	Description	Default
`copy`	`bool`	When True, returns a copy; otherwise returns a view/reference.	`True`

Returns:

Type	Description
`DataFrame`	pandas DataFrame indexed by 'uuid'.

head ¤

head(n: int = 5) -> pd.DataFrame

Convenience wrapper for DataFrame.head.

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of rows to return.	`5`

Returns:

Type	Description
`DataFrame`	Top n rows of the metadata DataFrame.

get_by_uuid ¤

get_by_uuid(uuid: str) -> Optional[Dict[str, Any]]

Retrieve a row by UUID as a dictionary.

Parameters:

Name	Type	Description	Default
`uuid`	`str`	UUID key (index) to look up.	required

Returns:

Type	Description
`Optional[Dict[str, Any]]`	Row as a dict, or None if not present.

get_by_label ¤

get_by_label(label: str) -> Optional[Dict[str, Any]]

Retrieve the first row matching a label as a dictionary.

Parameters:

Name	Type	Description	Default
`label`	`str`	Label value to search for.	required

Returns:

Type	Description
`Optional[Dict[str, Any]]`	Row as a dict, or None if not found.

join_with ¤

join_with(
    other_df: DataFrame, how: str = "inner"
) -> pd.DataFrame

Join the metadata DataFrame with another DataFrame on the 'uuid' index.

Parameters:

Name	Type	Description	Default
`other_df`	`DataFrame`	DataFrame to join with (must be indexed compatibly).	required
`how`	`str`	Join strategy (e.g., 'inner', 'left', 'outer').	`'inner'`

Returns:

Type	Description
`DataFrame`	Joined pandas DataFrame.

filter_by_uuid ¤

filter_by_uuid(uuids: Iterable[str]) -> pd.DataFrame

Filter rows by a set or sequence of UUIDs.

Parameters:

Name	Type	Description	Default
`uuids`	`Iterable[str]`	Iterable of UUID strings to retain.	required

Returns:

Type	Description
`DataFrame`	Filtered DataFrame.

filter_by_label ¤

filter_by_label(labels: Iterable[str]) -> pd.DataFrame

Filter rows by a set or sequence of labels.

Parameters:

Name	Type	Description	Default
`labels`	`Iterable[str]`	Iterable of label strings to retain.	required

Returns:

Type	Description
`DataFrame`	Filtered DataFrame.

list_uuids ¤

list_uuids() -> List[str]

Return a list of UUIDs present in the metadata index.

Returns:

Type	Description
`List[str]`	List of UUID strings.

list_labels ¤

list_labels() -> List[str]

Return all non-null labels.

Returns:

Type	Description
`List[str]`	List of label strings.

metadata_json_loader