call_report.core.FieldAttributes

class call_report.core.FieldAttributes(*, name: str, versions: tuple[FieldVersion, ...])

Bases: object

Cross-time metadata for a single field within a call report file.

Unlike a per-period layout entry, this describes a field across its whole known history rather than a single period. A field whose dtype or definition changed while it stayed continuously present (e.g. a field whose embedded code list grew over time, with no presence gap) is represented as multiple FieldVersion objects with adjacent periods, rather than forcing one dtype/definition across the field’s entire history.

Attributes:

namestr

The field’s name, as it appears in the source’s layout files.

versionstuple[FieldVersion, …]

One or more chronologically ordered, non-overlapping FieldVersion objects describing this field’s dtype/definition over time. More than one version means the field’s dtype or definition changed at some point, was dropped and later reintroduced, or both. Adjacent versions always differ in dtype/definition, since identical adjacent content is rejected as something that should have been expressed as a single version.

Raises:

SchemaError

If versions is empty, or its spans are out of order, overlapping, or adjacent with identical dtype/definition.

Examples

>>> import narwhals as nw
>>> from call_report.core import FieldAttributes, FieldVersion, PeriodRange
>>> inv_code = FieldAttributes(
...     name="INV_CODE",
...     versions=(
...         FieldVersion(
...             dtype=nw.Int64(),
...             definition="Investment Code: 10 U.S. Treasury securities...",
...             periods=PeriodRange(start="2000-03-31", end="2014-12-31"),
...         ),
...         FieldVersion(
...             dtype=nw.Int64(),
...             definition="Investment Code: 10 U.S. Treasury securities..."
...             "15 SBA securities...",
...             periods=PeriodRange(start="2015-03-31", end="2026-03-31"),
...         ),
...     ),
... )
>>> inv_code.first_period.label
'2000Q1'
>>> inv_code.last_period.label
'2026Q1'

property first_period: ReportingPeriod

Return the earliest period this field is present in.

This is the start of this field’s earliest version, not necessarily the start of the file it belongs to.

Returns:

ReportingPeriod

The first period of this field’s earliest version.

Examples

>>> import narwhals as nw
>>> from call_report.core import FieldAttributes, FieldVersion, PeriodRange
>>> field = FieldAttributes(
...     name="UNINUM",
...     versions=(
...         FieldVersion(
...             dtype=nw.Int64(),
...             definition="",
...             periods=PeriodRange(start="2000-03-31", end="2005-12-31"),
...         ),
...     ),
... )
>>> field.first_period.label
'2000Q1'

property last_period: ReportingPeriod

Return the latest period this field is present in.

This is the end of this field’s latest version, not necessarily the end of the file it belongs to.

Returns:

ReportingPeriod

The last period of this field’s latest version.

Examples

>>> import narwhals as nw
>>> from call_report.core import FieldAttributes, FieldVersion, PeriodRange
>>> field = FieldAttributes(
...     name="UNINUM",
...     versions=(
...         FieldVersion(
...             dtype=nw.Int64(),
...             definition="",
...             periods=PeriodRange(start="2000-03-31", end="2005-12-31"),
...         ),
...     ),
... )
>>> field.last_period.label
'2005Q4'