Source code for fable_pyculator.web.spec_io

"""JSON serialization for prepared FABLE specs.

Building a spec from a real FABLE workbook is expensive. The portal prepares it once, writes the
typed declaration to a cache under the ignored runtime directory, and reloads it on the next start.
Only declaration metadata is cached; generated values are never cached here.
"""

from __future__ import annotations

import datetime as dt
import math
from typing import Any

from fable_pyculator.spec import (
    FableCalculatorSpec,
    HeadlinePoint,
    HeadlineSeries,
    OutputIndicator,
    OutputTable,
    ScenarioDefinitionTable,
    ScenarioParameter,
    SelectionControl,
    SelectionOption,
)

__all__ = ["spec_from_payload", "spec_summary", "spec_to_payload"]


def jsonable(value: Any) -> Any:
    """Convert workbook values and numpy-like scalars to JSON-safe values."""

    if value is None or isinstance(value, str | bool | int):
        return value
    if isinstance(value, float):
        return value if math.isfinite(value) else None
    if isinstance(value, dt.datetime | dt.date | dt.time):
        return value.isoformat()
    if isinstance(value, dict):
        return {str(key): jsonable(item) for key, item in value.items()}
    if isinstance(value, list | tuple | set):
        return [jsonable(item) for item in value]
    item = getattr(value, "item", None)
    if callable(item):
        try:
            return jsonable(item())
        except (TypeError, ValueError):
            pass
    return str(value)


[docs] def spec_to_payload(spec: FableCalculatorSpec) -> dict[str, Any]: """Serialize a spec to a stable JSON-ready payload.""" return { "parameters": [ { "name": parameter.name, "label": parameter.label, "cell_ref": parameter.cell_ref, "kind": parameter.kind, "unit": parameter.unit, "description": parameter.description, "default": jsonable(parameter.default), "choices": [jsonable(choice) for choice in parameter.choices], "source": parameter.source, } for parameter in spec.parameters ], "selection_controls": [ { "name": control.name, "label": control.label, "table_name": control.table_name, "sheet": control.sheet, "range_ref": control.range_ref, "code_header": control.code_header, "location": control.location, "description": control.description, "default": control.default, "options": [ { "value": option.value, "label": option.label, "selection_cell_ref": option.selection_cell_ref, "description": option.description, "selected": option.selected, } for option in control.options ], } for control in spec.selection_controls ], "scenario_definition_tables": [ { "name": table.name, "sheet": table.sheet, "range_ref": table.range_ref, "cell_refs": [list(row) for row in table.cell_refs], "row_labels": list(table.row_labels), "column_labels": list(table.column_labels), "values": [[jsonable(value) for value in row] for row in table.values], "column_role_tags": list(table.column_role_tags), "raw_column_role_tags": list(table.raw_column_role_tags), "column_role_tag_refs": list(table.column_role_tag_refs), "scenario_locations": list(table.scenario_locations), "scenario_location_refs": list(table.scenario_location_refs), "label": table.label, "description": table.description, } for table in spec.scenario_definition_tables ], "outputs": [ { "name": output.name, "label": output.label, "cell_ref": output.cell_ref, "unit": output.unit, "group": output.group, "description": output.description, } for output in spec.outputs ], "output_tables": [ { "name": table.name, "sheet": table.sheet, "range_ref": table.range_ref, "cell_refs": [list(row) for row in table.cell_refs], "row_labels": list(table.row_labels), "column_labels": list(table.column_labels), "values": [[jsonable(value) for value in row] for row in table.values], "column_flavour_tags": list(table.column_flavour_tags), "raw_column_flavour_tags": list(table.raw_column_flavour_tags), "column_flavour_tag_refs": list(table.column_flavour_tag_refs), "label": table.label, "description": table.description, } for table in spec.output_tables ], "headline_series": [ { "name": series.name, "label": series.label, "group": series.group, "sheet": series.sheet, "table_name": series.table_name, "points": [ {"year": jsonable(point.year), "cell_refs": list(point.cell_refs)} for point in series.points ], "unit": series.unit, "description": series.description, "aggregation": series.aggregation, } for series in spec.headline_series ], "workbook_id": spec.workbook_id, "provenance": spec.provenance, }
[docs] def spec_from_payload(payload: dict[str, Any]) -> FableCalculatorSpec: """Reconstruct a spec from :func:`spec_to_payload` output.""" return FableCalculatorSpec( parameters=[ ScenarioParameter( name=str(item["name"]), label=str(item["label"]), cell_ref=str(item["cell_ref"]), kind=item.get("kind", "number"), unit=item.get("unit"), description=item.get("description"), default=item.get("default"), choices=tuple(item.get("choices", ())), source=item.get("source"), ) for item in payload.get("parameters", []) ], selection_controls=[ SelectionControl( name=str(item["name"]), label=str(item["label"]), table_name=str(item["table_name"]), sheet=str(item["sheet"]), range_ref=str(item["range_ref"]), code_header=str(item["code_header"]), options=tuple( SelectionOption( value=str(option["value"]), label=option.get("label"), selection_cell_ref=str(option["selection_cell_ref"]), description=option.get("description"), selected=bool(option.get("selected", False)), ) for option in item.get("options", []) ), location=item.get("location"), description=item.get("description"), ) for item in payload.get("selection_controls", []) ], scenario_definition_tables=[ ScenarioDefinitionTable( name=str(item["name"]), sheet=str(item["sheet"]), range_ref=str(item["range_ref"]), cell_refs=tuple(tuple(row) for row in item.get("cell_refs", [])), row_labels=tuple(item.get("row_labels", [])), column_labels=tuple(item.get("column_labels", [])), values=tuple(tuple(row) for row in item.get("values", [])), column_role_tags=tuple(item.get("column_role_tags", [])), raw_column_role_tags=tuple(item.get("raw_column_role_tags", [])), column_role_tag_refs=tuple(item.get("column_role_tag_refs", [])), scenario_locations=tuple(item.get("scenario_locations", [])), scenario_location_refs=tuple(item.get("scenario_location_refs", [])), label=item.get("label"), description=item.get("description"), ) for item in payload.get("scenario_definition_tables", []) ], outputs=[ OutputIndicator( name=str(item["name"]), label=str(item["label"]), cell_ref=str(item["cell_ref"]), unit=item.get("unit"), group=item.get("group"), description=item.get("description"), ) for item in payload.get("outputs", []) ], output_tables=[ OutputTable( name=str(item["name"]), sheet=str(item["sheet"]), range_ref=str(item["range_ref"]), cell_refs=tuple(tuple(row) for row in item.get("cell_refs", [])), row_labels=tuple(item.get("row_labels", [])), column_labels=tuple(item.get("column_labels", [])), values=tuple(tuple(row) for row in item.get("values", [])), column_flavour_tags=tuple(item.get("column_flavour_tags", [])), raw_column_flavour_tags=tuple(item.get("raw_column_flavour_tags", [])), column_flavour_tag_refs=tuple(item.get("column_flavour_tag_refs", [])), label=item.get("label"), description=item.get("description"), ) for item in payload.get("output_tables", []) ], headline_series=[ HeadlineSeries( name=str(item["name"]), label=str(item["label"]), group=str(item["group"]), sheet=str(item["sheet"]), table_name=str(item["table_name"]), points=tuple( HeadlinePoint(year=point["year"], cell_refs=tuple(point.get("cell_refs", []))) for point in item.get("points", []) ), unit=item.get("unit"), description=item.get("description"), aggregation=item.get("aggregation", "value"), ) for item in payload.get("headline_series", []) ], workbook_id=payload.get("workbook_id"), provenance=payload.get("provenance"), )
[docs] def spec_summary(spec: FableCalculatorSpec) -> dict[str, Any]: """Return the compact declaration metadata the browser needs.""" return { "workbook_id": spec.workbook_id, "provenance": spec.provenance, "counts": { "parameters": len(spec.parameters), "selection_controls": len(spec.selection_controls), "scenario_definition_tables": len(spec.scenario_definition_tables), "outputs": len(spec.outputs), "output_tables": len(spec.output_tables), "headline_series": len(spec.headline_series), }, "parameters": [ { "name": parameter.name, "label": parameter.label, "kind": parameter.kind, "unit": parameter.unit, "description": parameter.description, "default": jsonable(parameter.default), "choices": [jsonable(choice) for choice in parameter.choices], } for parameter in spec.parameters ], "selection_controls": [ { "name": control.name, "label": control.label, "location": control.location, "description": control.description, "default": control.default, "options": [ { "value": option.value, "label": option.label or option.value, "description": option.description, } for option in control.options ], } for control in spec.selection_controls ], "outputs": [ { "name": output.name, "label": output.label, "group": output.group, "unit": output.unit, "description": output.description, } for output in spec.outputs ], "output_tables": [ { "name": table.name, "label": table.label, "sheet": table.sheet, "range_ref": table.range_ref, "row_count": len(table.row_labels), "column_count": len(table.column_labels), "column_flavour_tags": list(table.column_flavour_tags), } for table in spec.output_tables ], "headline_series": [ { "name": series.name, "label": series.label, "group": series.group, "unit": series.unit, "description": series.description, "year_count": len(series.points), "years": [jsonable(point.year) for point in series.points], } for series in spec.headline_series ], "scenario_definition_tables": [ { "name": table.name, "label": table.label, "sheet": table.sheet, "range_ref": table.range_ref, "row_count": len(table.row_labels), "column_count": len(table.column_labels), "scenario_locations": list(table.scenario_locations), } for table in spec.scenario_definition_tables ], }