gcubed.reporting.chartpacks

Load G-Cubed chartpacks into a format-neutral reporting model.

class ChartpackError(builtins.ValueError):

Raised when a chartpack violates its serialization or data contract.

Inherited Members

builtins.BaseException: BaseException; with_traceback; add_note; args

@dataclass(frozen=True)

class ChartpackSeries:

One exact series in a normalized chartpack.

variable: str = ''

label: str | None = None

color: str | None = None

line: str = 'solid'

start_year: int | None = None

end_year: int | None = None

x_variable: str | None = None

y_variable: str | None = None

role: str | None = None

variables: tuple[str, ...]

Return the projection rows consumed by an ordinary or paired series.

@dataclass(frozen=True)

class ChartpackChart:

One chart with its normalized exact series.

series: tuple[ChartpackSeries, ...]

title: str | None = None

start_year: int | None = None

end_year: int | None = None

min_value: int | float | None = None

max_value: int | float | None = None

section_label: str | None = None

chart_type: str | None = None

caption: str | None = None

year: int | None = None

year_selector: bool = False

observation_mode: str = 'single-year'

display_selector: bool = False

color_by_sign: bool = False

level_base: int | float | None = None

view_group: str | None = None

view_label: str | None = None

orientation: str | None = None

show_labels: bool = False

sort: str | None = None

x_axis: dict | None = None

y_axis_label: str | None = None

x_dimension: str | None = None

y_dimension: str | None = None

color_axis: dict | None = None

group_dimension: str | None = None

reconciliation: dict | None = None

variables: tuple[str, ...]

Include scatter axes and composition totals in projection extraction.

@dataclass(frozen=True)

class ChartpackSection:

One ordered presentation heading in a normalized chartpack.

ChartpackSection(label: str | None = None)

label: str | None = None

@dataclass(frozen=True)

class ChartpackDocument:

A validated chartpack ready for projection extraction and rendering.

ChartpackDocument( title: str, charts: tuple[ChartpackChart, ...], source_format: str, source_text: str, table_of_contents: bool = False, sector_selection_dimensions: tuple[str, ...] = (), sector_selection_include_default: bool = False, entries: tuple[ChartpackSection | ChartpackChart, ...] = ())

title: str

charts: tuple[ChartpackChart, ...]

source_format: str

source_text: str

table_of_contents: bool = False

sector_selection_dimensions: tuple[str, ...] = ()

sector_selection_include_default: bool = False

entries: tuple[ChartpackSection | ChartpackChart, ...] = ()

variables: tuple[str, ...]

Return unique exact variables in first-authored order.

semantic_manifest: tuple[str, tuple[ChartpackChart, ...]]

Return serialization-independent normalized chartpack semantics.

@dataclass(frozen=True)

class ParsedChartpack:

Authored chartpack syntax independent of a projection catalogue.

ParsedChartpack( path: pathlib.Path, source_format: str, source_text: str, authored_document: object)

path: pathlib.Path

source_format: str

source_text: str

authored_document: object

@dataclass(frozen=True)

class ResolvedChartpack:

Exact chartpack series plus the metadata signature used to resolve them.

ResolvedChartpack( parsed: ParsedChartpack, document: ChartpackDocument, catalogue_signature: tuple)

parsed: ParsedChartpack

document: ChartpackDocument

catalogue_signature: tuple

def load_chartpack( chartpack_path: pathlib.Path, projections: pandas.DataFrame) -> ChartpackDocument:

Load a CSV or YAML chartpack and validate its exact variables.

def prepare_setup_charts( chartpack_config: dict, projections: pandas.DataFrame | None = None, *, context_path: pathlib.Path | None = None) -> list[dict]:

Resolve and implicitly split portable setup chart declarations.

def render_chartpack_yaml( chartpack_config: dict, *, projections: pandas.DataFrame | None = None, context_path: pathlib.Path | None = None) -> str:

Render and validate a model-aware setup chartpack without writing it.

def write_chartpack_yaml( chartpack_path: pathlib.Path, chartpack_config: dict, *, projections: pandas.DataFrame | None = None, overwrite: bool = False) -> None:

Write a model-aware setup chartpack configuration as canonical YAML.

def convert_csv_chartpack_to_yaml( csv_path: pathlib.Path, yaml_path: pathlib.Path, projections: pandas.DataFrame, *, overwrite: bool = False, version: int | str = 1) -> ChartpackDocument:

Convert legacy CSV to exact YAML at a released chartpack version.