plaid.utils.sample_json¶

def sample_to_json_payload(sample: Sample) -> dict[str, Any]:
    """Convert a full Sample to a JSON-compatible payload.

    Args:
        sample: Sample instance to serialize.

    Returns:
        A JSON-compatible dictionary containing format metadata and all
        timestamped CGNS trees from the sample.
    """
    trees_payload = []
    for time, tree in sample.data.items():
        trees_payload.append(
            {
                "time": _encode_time(time),
                "tree": cgns_tree_to_json_payload(tree),
            }
        )

    return {
        "format": FORMAT_NAME,
        "version": FORMAT_VERSION,
        "trees": trees_payload,
    }

def sample_from_json_payload(payload: dict[str, Any]) -> Sample:
    """Rebuild a full Sample from a JSON-compatible payload.

    Args:
        payload: Payload produced by :func:`sample_to_json_payload`.

    Returns:
        A reconstructed :class:`Sample`.

    Raises:
        ValueError: If payload format or version is unsupported.
    """
    if payload.get("format") != FORMAT_NAME:
        raise ValueError(f"Unsupported Sample JSON format: {payload.get('format')!r}")
    if payload.get("version") != FORMAT_VERSION:
        raise ValueError(f"Unsupported Sample JSON version: {payload.get('version')!r}")

    trees = payload.get("trees")
    if not isinstance(trees, list):
        raise ValueError("Sample JSON payload must contain a list in 'trees'")

    from ..containers.sample import Sample

    sample = Sample()
    for entry in trees:
        if not isinstance(entry, dict):
            raise ValueError("Each Sample JSON tree entry must be a dictionary")
        if "time" not in entry or "tree" not in entry:
            raise ValueError(
                "Each Sample JSON tree entry must contain 'time' and 'tree'"
            )

        time_value = _decode_time(entry["time"])
        sample.data[time_value] = cgns_tree_from_json_payload(entry["tree"])

    return sample

def sample_to_json(sample: "Sample", **json_kwargs: Any) -> str:
    """Convert a full Sample to a JSON string.

    Args:
        sample: Sample instance to serialize.
        **json_kwargs: Extra keyword arguments forwarded to :func:`json.dumps`.

    Returns:
        A JSON string containing the encoded sample.
    """
    return json.dumps(sample_to_json_payload(sample), **json_kwargs)

def sample_from_json(text: str) -> Sample:
    """Rebuild a Sample from a JSON string.

    Args:
        text: JSON string produced by :func:`sample_to_json`.

    Returns:
        A reconstructed :class:`Sample`.
    """
    payload = json.loads(text)
    return sample_from_json_payload(payload)