call_report.fca.layout.FCALayout#

class call_report.fca.layout.FCALayout(*, scenario: Literal['single', 'single_multiple', 'single_multiple_single'], variables: Any, leading_columns: tuple[str, ...], multi_columns: tuple[str, ...], trailing_columns: tuple[str, ...])[source]#

Bases: object

A parsed FCA layout, with its scenario, variables, and column groups.

Returned by parse_layout. The column groups tell read_schedule_file() how to split each data row into its single- and multiple-occurrence parts.

Attributes:

scenario{“single”, “single_multiple”, “single_multiple_single”}: Which of the three structural scenarios this layout follows.
variablesAny: A native dataframe (of the configured backend) with one row per variable and columns name, type, decimal_position, definition, is_multi.
leading_columnstuple[str, …]: Single-occurrence column names appearing before the multi-occurrence run, if any.
multi_columnstuple[str, …]: Multiple-occurrence column names, in layout order. The first entry is always the code column. Empty for the "single" scenario.
trailing_columnstuple[str, …]: Single-occurrence column names appearing after the multi-occurrence run. Only ever non-empty for "single_multiple_single".

variables_as_dicts() → list[dict[str, Any]][source]#

Return the variables frame as a list of plain dicts.

A convenience for inspecting variables without depending on which dataframe backend is currently configured.

Returns:

list[dict[str, Any]]: One dict per variable, in layout order.

to_field_schema(*, period: str | date | ReportingPeriod) → FieldSchema[source]#

Convert this layout into a FieldSchema covering a single period.

A layout describes one release, so period has to be supplied rather than read off the layout. Every field gets exactly one call_report.core.FieldVersion, spanning only that quarter, with its dtype from infer_field_dtype and its definition from the layout’s own text. Comparing the result against the canonical, cross-time metadata call_report.fca.get_fca_file_metadata returns is the cheapest way to notice a release whose layout disagrees with the shipped metadata.

The multiple-occurrence distinction multi_columns records is not carried over. call_report.core.FieldSchema describes a file’s fields, not how each row is split into occurrence groups.

Parameters:

periodstr, datetime.date, or ReportingPeriod: The quarter-end this layout was published for.

Returns:

FieldSchema: One field per layout variable, in layout order.

Raises:

InvalidPeriodError: If period is not a valid quarter-end date.
SchemaError: If this layout declares the same variable name twice.

Examples

>>> from call_report.core import ReportingPeriod
>>> from call_report.fca.transport import PackagedArchiveTransport
>>> transport = PackagedArchiveTransport()
>>> release_dir = transport.resolve(
...     period=ReportingPeriod.from_period_end(value="2026-03-31")
... )
>>> layout = parse_layout(path=release_dir / "D_RCB.TXT")
>>> schema = layout.to_field_schema(period="2026-03-31")
>>> schema.names[:3]
('SYSTEM', 'DIST', 'ASSOC')
>>> schema["UNINUM"].versions[0].periods[0].label
'2026Q1'