call_report.core.FieldSchemaDiff

class call_report.core.FieldSchemaDiff(*, added: tuple[str, ...], removed: tuple[str, ...], changed: tuple[FieldChange, ...], order_changed: bool = False)

Bases: object

The result of comparing two FieldSchema snapshots via FieldSchema.compare.

added/removed/changed are mutually exclusive: a field appears in exactly one of them (or none, if it’s identical in both schemas).

Attributes:

addedtuple[str, …]

Field names present in the compared-against schema but not this one.

removedtuple[str, …]

Field names present in this schema but not the compared-against one.

changedtuple[FieldChange, …]

Fields present in both schemas, but with different metadata.

order_changedbool

Whether the fields common to both schemas appear in a different relative order. Always False unless FieldSchema.compare was called with check_order=True.

Examples

>>> diff = FieldSchemaDiff(added=("ASSOC",), removed=(), changed=())
>>> diff.added
('ASSOC',)

property is_empty: bool

Return whether the two schemas being compared were identical.

A convenience for the common “did anything change” check, without inspecting added/removed/changed individually.

Returns:

bool

True if there is nothing in added, removed, or changed, and order_changed is False.

Examples

>>> FieldSchemaDiff(added=(), removed=(), changed=()).is_empty
True
>>> FieldSchemaDiff(added=("ASSOC",), removed=(), changed=()).is_empty
False

property content_changed: tuple[FieldChange, ...]

Return the entries in changed whose dtype or definition differs.

A convenience filter over changed for comparing schemas across quarters, where a field is commonly stamped with a different periods (see FieldChange.periods_changed) purely because it was narrowed by FieldSchema.as_of, and that difference carries no signal on its own. changed still reports every such field, so this property is the way to ask what changed beyond that.

Returns:

tuple[FieldChange, …]

The subset of changed where FieldChange.content_changed is True.

Examples

>>> import narwhals as nw
>>> from call_report.core import (
...     FieldAttributes,
...     FieldSchema,
...     FieldVersion,
...     PeriodRange,
... )
>>> def _field(
...     name: str, definition: str, periods: PeriodRange
... ) -> FieldAttributes:
...     return FieldAttributes(
...         name=name,
...         versions=(
...             FieldVersion(
...                 dtype=nw.Int64(), definition=definition, periods=periods
...             ),
...         ),
...     )
>>> q4_2014 = PeriodRange(start="2014-12-31", end="2014-12-31")
>>> q1_2015 = PeriodRange(start="2015-03-31", end="2015-03-31")
>>> before = FieldSchema(
...     fields=[
...         _field("PROVLNS", "old definition", q4_2014),
...         _field("UNINUM", "", q4_2014),
...     ]
... )
>>> after = FieldSchema(
...     fields=[
...         _field("PROVLNS", "new definition", q1_2015),
...         _field("UNINUM", "", q1_2015),
...     ]
... )
>>> diff = before.compare(other=after)
>>> len(diff.changed)
2
>>> [change.name for change in diff.content_changed]
['PROVLNS']