climate_ref_core.serialisation

JSON wire format for the objects that cross a process boundary.

An executor may run a diagnostic in another process or on another node, which means the execution definition and its result have to be encoded.

JSON cannot represent everything these objects hold, and values with no JSON equivalent are written as tagged objects carrying a __ref_type__ key. The types that need this are paths, cftime dates and the pandas frame of selected datasets.

TAG = '__ref_type__' module-attribute

Key marking an object as a tagged value rather than a plain mapping.

from_wire(value)

Rebuild a value encoded by to_wire

Parameters:

Name	Type	Description	Default
value	Any	JSON structure to decode.	required

Raises:

Type	Description
ValueError	If the structure carries a tag this version does not understand.

Returns:

Type	Description
Any	The decoded value.

Source code in packages/climate-ref-core/src/climate_ref_core/serialisation.py

def from_wire(value: Any) -> Any:
    """
    Rebuild a value encoded by [to_wire][climate_ref_core.serialisation.to_wire]

    Parameters
    ----------
    value
        JSON structure to decode.

    Raises
    ------
    ValueError
        If the structure carries a tag this version does not understand.

    Returns
    -------
    :
        The decoded value.
    """
    if isinstance(value, dict):
        tag = value.get(TAG)
        if tag is not None:
            if tag not in _DECODERS:
                raise ValueError(f"Unknown tagged value {tag!r}")
            return _DECODERS[tag](value)
        return {key: from_wire(item) for key, item in value.items()}
    if isinstance(value, list):
        return [from_wire(item) for item in value]
    return value

to_wire(value)

Convert a value into its JSON representation

Parameters:

Name	Type	Description	Default
value	Any	Value to encode. Containers are walked recursively.	required

Raises:

Type	Description
TypeError	If the value has no JSON representation.

Returns:

Type	Description
Any	A structure built only from types that json can serialise.

Source code in packages/climate-ref-core/src/climate_ref_core/serialisation.py

def to_wire(value: Any) -> Any:
    """
    Convert a value into its JSON representation

    Parameters
    ----------
    value
        Value to encode. Containers are walked recursively.

    Raises
    ------
    TypeError
        If the value has no JSON representation.

    Returns
    -------
    :
        A structure built only from types that `json` can serialise.
    """
    for kind, tag in _WIRE_TYPES:
        if isinstance(value, kind):
            return {TAG: tag, **_converter.unstructure(value)}

    if isinstance(value, pd.DataFrame):
        return _encode_frame(value)
    if isinstance(value, SourceDatasetType):
        return value.value
    if isinstance(value, dict):
        return {key: to_wire(item) for key, item in value.items()}
    if isinstance(value, list | tuple):
        return [to_wire(item) for item in value]

    return _encode_scalar(value)