ts_shape.loader.metadata.metadata_json_loader

Classes:

• MetadataJsonLoader –

  Load metadata JSON of shape:

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.

Parameters:

• 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": {...}}, ...]

• strict

  (bool, default: True ) –

  If True, enforce presence of required keys and unique UUIDs.

Methods:

• filter_by_label –

  Filter rows by a set or sequence of labels.

• filter_by_uuid –

  Filter rows by a set or sequence of UUIDs.

• from_file –

  Create a loader from a JSON file on disk.

• from_str –

  Create a loader from a JSON string.

• get_by_label –

  Retrieve the first row matching a label as a dictionary.

• get_by_uuid –

  Retrieve a row by UUID as a dictionary.

• head –

  Convenience wrapper for DataFrame.head.

• join_with –

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

• list_labels –

  Return all non-null labels.

• list_uuids –

  Return a list of UUIDs present in the metadata index.

• to_df –

  Return the underlying DataFrame.

Source code in src/ts_shape/loader/metadata/metadata_json_loader.py

def __init__(self, json_data: Any, *, strict: bool = True):
    """
    Create a loader from JSON-like data.

    Args:
        json_data: 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": {...}}, ...]
        strict: If True, enforce presence of required keys and unique UUIDs.
    """
    self.json_data = json_data
    self.strict = strict
    self.df = self._to_dataframe()

filter_by_label

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

Filter rows by a set or sequence of labels.

Parameters:

• labels

  (Iterable[str]) –

  Iterable of label strings to retain.

Returns:

• DataFrame –

  Filtered DataFrame.

Source code in src/ts_shape/loader/metadata/metadata_json_loader.py

def filter_by_label(self, labels: Iterable[str]) -> pd.DataFrame:
    """
    Filter rows by a set or sequence of labels.

    Args:
        labels: Iterable of label strings to retain.

    Returns:
        Filtered DataFrame.
    """
    labels_set = set(labels)
    return self.df[self.df["label"].isin(labels_set)]

filter_by_uuid

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

Filter rows by a set or sequence of UUIDs.

Parameters:

• uuids

  (Iterable[str]) –

  Iterable of UUID strings to retain.

Returns:

• DataFrame –

  Filtered DataFrame.

Source code in src/ts_shape/loader/metadata/metadata_json_loader.py

def filter_by_uuid(self, uuids: Iterable[str]) -> pd.DataFrame:
    """
    Filter rows by a set or sequence of UUIDs.

    Args:
        uuids: Iterable of UUID strings to retain.

    Returns:
        Filtered DataFrame.
    """
    uuids_set = set(uuids)
    return self.df[self.df.index.isin(uuids_set)]

from_file classmethod

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

Create a loader from a JSON file on disk.

Parameters:

• filepath

  (str) –

  Path to the JSON file.

• strict

  (bool, default: True ) –

  Validation behavior; when True, enforces required fields and unique UUIDs.

Returns:

• MetadataJsonLoader –

  MetadataJsonLoader instance.

Source code in src/ts_shape/loader/metadata/metadata_json_loader.py

@classmethod
def from_file(cls, filepath: str, *, strict: bool = True) -> "MetadataJsonLoader":
    """
    Create a loader from a JSON file on disk.

    Args:
        filepath: Path to the JSON file.
        strict: Validation behavior; when True, enforces required fields and unique UUIDs.

    Returns:
        MetadataJsonLoader instance.
    """
    with open(filepath, "r", encoding="utf-8") as f:
        data = json.load(f)
    return cls(data, strict=strict)

from_str classmethod

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

Create a loader from a JSON string.

Parameters:

• json_str

  (str) –

  Raw JSON content as a string.

• strict

  (bool, default: True ) –

  Validation behavior; when True, enforces required fields and unique UUIDs.

Returns:

• MetadataJsonLoader –

  MetadataJsonLoader instance.

Source code in src/ts_shape/loader/metadata/metadata_json_loader.py

@classmethod
def from_str(cls, json_str: str, *, strict: bool = True) -> "MetadataJsonLoader":
    """
    Create a loader from a JSON string.

    Args:
        json_str: Raw JSON content as a string.
        strict: Validation behavior; when True, enforces required fields and unique UUIDs.

    Returns:
        MetadataJsonLoader instance.
    """
    return cls(json.loads(json_str), strict=strict)

get_by_label

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

Retrieve the first row matching a label as a dictionary.

Parameters:

• label

  (str) –

  Label value to search for.

Returns:

• Optional[Dict[str, Any]] –

  Row as a dict, or None if not found.

Source code in src/ts_shape/loader/metadata/metadata_json_loader.py

def get_by_label(self, label: str) -> Optional[Dict[str, Any]]:
    """
    Retrieve the first row matching a label as a dictionary.

    Args:
        label: Label value to search for.

    Returns:
        Row as a dict, or None if not found.
    """
    row = self.df[self.df["label"] == label]
    return None if row.empty else row.iloc[0].to_dict()

get_by_uuid

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

Retrieve a row by UUID as a dictionary.

Parameters:

• uuid

  (str) –

  UUID key (index) to look up.

Returns:

• Optional[Dict[str, Any]] –

  Row as a dict, or None if not present.

Source code in src/ts_shape/loader/metadata/metadata_json_loader.py

def get_by_uuid(self, uuid: str) -> Optional[Dict[str, Any]]:
    """
    Retrieve a row by UUID as a dictionary.

    Args:
        uuid: UUID key (index) to look up.

    Returns:
        Row as a dict, or None if not present.
    """
    if uuid not in self.df.index:
        return None
    return self.df.loc[uuid].to_dict()

head

head(n: int = 5) -> DataFrame

Convenience wrapper for DataFrame.head.

Parameters:

• n

  (int, default: 5 ) –

  Number of rows to return.

Returns:

• DataFrame –

  Top n rows of the metadata DataFrame.

Source code in src/ts_shape/loader/metadata/metadata_json_loader.py

def head(self, n: int = 5) -> pd.DataFrame:
    """
    Convenience wrapper for DataFrame.head.

    Args:
        n: Number of rows to return.

    Returns:
        Top n rows of the metadata DataFrame.
    """
    return self.df.head(n)

join_with

join_with(other_df: DataFrame, how: str = 'inner') -> DataFrame

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

Parameters:

• other_df

  (DataFrame) –

  DataFrame to join with (must be indexed compatibly).

• how

  (str, default: 'inner' ) –

  Join strategy (e.g., 'inner', 'left', 'outer').

Returns:

• DataFrame –

  Joined pandas DataFrame.

Source code in src/ts_shape/loader/metadata/metadata_json_loader.py

def join_with(self, other_df: pd.DataFrame, how: str = "inner") -> pd.DataFrame:
    """
    Join the metadata DataFrame with another DataFrame on the 'uuid' index.

    Args:
        other_df: DataFrame to join with (must be indexed compatibly).
        how: Join strategy (e.g., 'inner', 'left', 'outer').

    Returns:
        Joined pandas DataFrame.
    """
    return self.df.join(other_df, how=how)

list_labels

list_labels() -> List[str]

Return all non-null labels.

Returns:

• List[str] –

  List of label strings.

Source code in src/ts_shape/loader/metadata/metadata_json_loader.py

def list_labels(self) -> List[str]:
    """
    Return all non-null labels.

    Returns:
        List of label strings.
    """
    return list(self.df["label"].dropna().astype(str))

list_uuids

list_uuids() -> List[str]

Return a list of UUIDs present in the metadata index.

Returns:

• List[str] –

  List of UUID strings.

Source code in src/ts_shape/loader/metadata/metadata_json_loader.py

def list_uuids(self) -> List[str]:
    """
    Return a list of UUIDs present in the metadata index.

    Returns:
        List of UUID strings.
    """
    return list(self.df.index.astype(str))

to_df

to_df(copy: bool = True) -> DataFrame

Return the underlying DataFrame.

Parameters:

• copy

  (bool, default: True ) –

  When True, returns a copy; otherwise returns a view/reference.

Returns:

• DataFrame –

  pandas DataFrame indexed by 'uuid'.

Source code in src/ts_shape/loader/metadata/metadata_json_loader.py

def to_df(self, copy: bool = True) -> pd.DataFrame:
    """
    Return the underlying DataFrame.

    Args:
        copy: When True, returns a copy; otherwise returns a view/reference.

    Returns:
        pandas DataFrame indexed by 'uuid'.
    """
    return self.df.copy() if copy else self.df