call_report.core.BaseCallReport#

class call_report.core.BaseCallReport[source]#

Bases: ABC

Abstract base for every source-specific call report entry point.

Concrete subclasses (one per Source) accept start and end as their first two constructor parameters, store all constructor parameters verbatim as identically-named attributes (doing no validation work in __init__, per the sklearn estimator convention), and implement the abstract methods below.

Examples

>>> from call_report.core import BaseCallReport
>>> from call_report.fca import FCACallReport
>>> from call_report.fca.transport import PackagedArchiveTransport
>>> report = FCACallReport(
...     start="2026-03-31",
...     end="2026-03-31",
...     transport=PackagedArchiveTransport(),
... )
>>> isinstance(report, BaseCallReport)
True

abstractmethod fetch() → Self[source]#

Validate this instance’s parameters and resolve its release files.

Populates trailing-underscore attributes describing what was found (e.g. the resolved periods and any non-fatal issues encountered). Subsequent calls to load-family methods call this automatically if it has not run yet.

Returns:

Self: This instance, to support method chaining.

Examples

>>> from call_report.fca import FCACallReport
>>> from call_report.fca.transport import PackagedArchiveTransport
>>> report = FCACallReport(
...     start="2026-03-31",
...     end="2026-03-31",
...     transport=PackagedArchiveTransport(),
... )
>>> report.fetch() is report
True

final load(*, schedule: Any, dataframe_type: None = None) → NativeDataFrame[source]#

final load(*, schedule: Any, dataframe_type: Literal['pandas']) → pandas.DataFrame

final load(*, schedule: Any, dataframe_type: Literal['pyarrow_table']) → pyarrow.Table

final load(*, schedule: Any, dataframe_type: Literal['polars_dataframe']) → polars.DataFrame

final load(*, schedule: Any, dataframe_type: Literal['polars_lazyframe']) → polars.LazyFrame

Load a single schedule, stacked across every requested period.

Concrete sources implement _load rather than this method. load itself cannot be overridden, so every source applies dataframe_type the same way, in one place.

Parameters:

scheduleAny: The schedule to load, in whatever form the concrete source accepts (typically an enum member or a case-insensitive name).
dataframe_type{“pandas”, “pyarrow_table”, “polars_lazyframe”, “polars_dataframe”}, optional: The dataframe type to convert the result to as a final step. Leave this None (the default) to get back whatever backend call_report.config.get_config currently has configured. Set it when the code that consumes this result needs a specific type, for example a pandas DataFrame while the package is configured to use polars.

Returns:

NativeDataFrame: A native dataframe of the configured backend, or of dataframe_type if it was supplied.

Examples

>>> from call_report.fca import FCACallReport
>>> from call_report.fca.transport import PackagedArchiveTransport
>>> report = FCACallReport(
...     start="2026-03-31",
...     end="2026-03-31",
...     transport=PackagedArchiveTransport(),
... )
>>> frame = report.load(schedule="RCB")
>>> frame.shape
(2240, 12)

final load_all(*, dataframe_type: None = None) → dict[Any, NativeDataFrame][source]#

final load_all(*, dataframe_type: Literal['pandas']) → dict[Any, pandas.DataFrame]

final load_all(*, dataframe_type: Literal['pyarrow_table']) → dict[Any, pyarrow.Table]

final load_all(*, dataframe_type: Literal['polars_dataframe']) → dict[Any, polars.DataFrame]

final load_all(*, dataframe_type: Literal['polars_lazyframe']) → dict[Any, polars.LazyFrame]

Load every schedule discovered across the requested periods.

Equivalent to calling load once per schedule returned by available_schedules that is actually present in range. Concrete sources implement _load_all rather than this method. load_all itself cannot be overridden, so every source applies dataframe_type the same way, in one place.

Parameters:

dataframe_type{“pandas”, “pyarrow_table”, “polars_lazyframe”, “polars_dataframe”}, optional: The dataframe type to convert every result to. Leave this None (the default) to get back whatever backend call_report.config.get_config currently has configured.

Returns:

dict[Any, NativeDataFrame]: A mapping from schedule to its stacked native dataframe.

Examples

>>> from call_report.fca import FCACallReport
>>> from call_report.fca.transport import PackagedArchiveTransport
>>> report = FCACallReport(
...     start="2026-03-31",
...     end="2026-03-31",
...     transport=PackagedArchiveTransport(),
... )
>>> frames = report.load_all()
>>> len(frames)
35

final load_institutions(*, dataframe_type: None = None) → NativeDataFrame[source]#

final load_institutions(*, dataframe_type: Literal['pandas']) → pandas.DataFrame

final load_institutions(*, dataframe_type: Literal['pyarrow_table']) → pyarrow.Table

final load_institutions(*, dataframe_type: Literal['polars_dataframe']) → polars.DataFrame

final load_institutions(*, dataframe_type: Literal['polars_lazyframe']) → polars.LazyFrame

Load the institution roster, stacked across every requested period.

The roster is handled separately from load since it describes institutions themselves rather than a financial schedule. Concrete sources implement _load_institutions rather than this method. load_institutions itself cannot be overridden, so every source applies dataframe_type the same way, in one place.

Parameters:

dataframe_type{“pandas”, “pyarrow_table”, “polars_lazyframe”, “polars_dataframe”}, optional: The dataframe type to convert the result to as a final step. Leave this None (the default) to get back whatever backend call_report.config.get_config currently has configured. Set it when the code that consumes this result needs a specific type, for example a pandas DataFrame while the package is configured to use polars.

Returns:

NativeDataFrame: A native dataframe of the configured backend, or of dataframe_type if it was supplied.

Examples

>>> from call_report.fca import FCACallReport
>>> from call_report.fca.transport import PackagedArchiveTransport
>>> report = FCACallReport(
...     start="2026-03-31",
...     end="2026-03-31",
...     transport=PackagedArchiveTransport(),
... )
>>> institutions = report.load_institutions()
>>> institutions.shape
(64, 13)

abstractmethod get_layout(*, schedule: Any, period: Any = None) → Any[source]#

Return the variable-metadata layout for a schedule.

Layouts can drift across periods (new variables added, scenarios changing), so callers can inspect either a single period or the whole requested range at once.

Parameters:

scheduleAny: The schedule to describe.
periodAny, optional: A specific period to describe. If omitted, implementations typically return the layout for every period in range that has the schedule.

Returns:

Any: A single layout object, or a mapping of period to layout, depending on whether period was supplied.

Examples

>>> from call_report.fca import FCACallReport
>>> from call_report.fca.transport import PackagedArchiveTransport
>>> report = FCACallReport(
...     start="2026-03-31",
...     end="2026-03-31",
...     transport=PackagedArchiveTransport(),
... )
>>> layout = report.get_layout(schedule="RCB", period="2026-03-31")
>>> layout.scenario
'single_multiple'

abstractmethod available_periods() → tuple[ReportingPeriod, ...][source]#

Return every period the source is known to publish.

This reflects the source’s overall catalog, independent of whatever start/end this particular instance was constructed with.

Returns:

tuple[ReportingPeriod, …]: The known-available periods, oldest first.

Examples

>>> from call_report.fca import FCACallReport
>>> from call_report.fca.transport import PackagedArchiveTransport
>>> report = FCACallReport(
...     start="2026-03-31",
...     end="2026-03-31",
...     transport=PackagedArchiveTransport(),
... )
>>> periods = report.available_periods()
>>> periods[0].label
'2000Q1'

abstractmethod available_schedules() → tuple[Any, ...][source]#

Return every schedule the source’s format has ever used.

Like available_periods, this reflects the source’s overall catalog rather than what this particular instance requested.

Returns:

tuple[Any, …]: The known schedules, in whatever form the concrete source uses.

Examples

>>> from call_report.fca import FCACallReport
>>> from call_report.fca.transport import PackagedArchiveTransport
>>> report = FCACallReport(
...     start="2026-03-31",
...     end="2026-03-31",
...     transport=PackagedArchiveTransport(),
... )
>>> len(report.available_schedules())
37

get_params(*, deep: bool = True) → dict[str, Any][source]#

Return this instance’s constructor parameters and current values.

Parameter names are discovered by introspecting the concrete subclass’s __init__ signature, so subclasses never need to redeclare them here.

Parameters:

deepbool, default True: Reserved for future nested-estimator composition, matching the sklearn convention. It has no effect for the sources currently in this package.

Returns:

dict[str, Any]: A mapping from constructor parameter name to its current value.

Examples

>>> from call_report.fca import FCACallReport
>>> from call_report.fca.transport import PackagedArchiveTransport
>>> report = FCACallReport(
...     start="2026-03-31",
...     end="2026-03-31",
...     transport=PackagedArchiveTransport(),
... )
>>> report.get_params()["start"]
'2026-03-31'
>>> sorted(report.get_params())
['end', 'schema_policy', 'start', 'transport']

set_params(**params: Any) → Self[source]#

Update one or more constructor parameters in place.

This does not re-run fetch, so any previously fetched state becomes stale until fetch is called again.

Parameters:

**paramsAny: Parameter name/value pairs. Each name must be one of this instance’s constructor parameters.

Returns:

Self: This instance, to support method chaining.

Raises:

ValueError: If a name in params is not a valid constructor parameter.

Examples

>>> from call_report.fca import FCACallReport
>>> from call_report.fca.transport import PackagedArchiveTransport
>>> report = FCACallReport(
...     start="2026-03-31",
...     end="2026-03-31",
...     transport=PackagedArchiveTransport(),
... )
>>> report.set_params(schema_policy="strict") is report
True
>>> report.schema_policy
'strict'