call_report.core.ReportingPeriod#

class call_report.core.ReportingPeriod(*, year: int, quarter: Quarter)[source]#

Bases: object

A single calendar-quarter reporting period.

Instances are normally created via from_period_end() rather than the constructor directly.

Attributes:

yearint: The four-digit calendar year.
quarterQuarter: The calendar quarter.

Examples

>>> period = ReportingPeriod.from_period_end(value="2026-03-31")
>>> period.label
'2026Q1'

classmethod from_period_end(*, value: str | date) → ReportingPeriod[source]#

Build a ReportingPeriod from a quarter-end date.

This is the primary, validated entry point for constructing a ReportingPeriod from user-supplied input.

Parameters:

valuestr or datetime.date: An ISO "YYYY-MM-DD" string or a datetime.date, naming a real calendar quarter-end date.

Returns:

ReportingPeriod: The period ending on value.

Raises:

InvalidPeriodError: If value cannot be parsed as a date, or is a valid calendar date that does not fall on 03-31, 06-30, 09-30, or 12-31.

Examples

>>> ReportingPeriod.from_period_end(value="2026-03-31").label
'2026Q1'

property month: int[source]#

Return the quarter-end month.

This is a convenience alias for self.quarter.last_month.

Returns:

int: 3, 6, 9, or 12.

Examples

>>> ReportingPeriod.from_period_end(value="2026-03-31").month
3

property period_end: date[source]#

Return the quarter-end calendar date.

This is the inverse of from_period_end(): round-tripping a period through period_end and back reproduces the same period.

Returns:

datetime.date: The last calendar day of this period’s quarter.

Examples

>>> ReportingPeriod.from_period_end(value="2026-03-31").period_end
datetime.date(2026, 3, 31)

property label: str[source]#

Return a short, human-readable label for this period.

Intended for log messages, error text, and reprs, not for parsing.

Returns:

str: A label of the form "YYYYQn", e.g. "2026Q1".

Examples

>>> ReportingPeriod.from_period_end(value="2026-03-31").label
'2026Q1'

next(*, n: int = 1) → ReportingPeriod[source]#

Return the period n quarters after this one.

Advancing past December rolls over into Q1 of the following year.

Parameters:

nint, default 1: Number of quarters to advance. May be negative.

Returns:

ReportingPeriod: The resulting period, with year rollover handled automatically.

Examples

>>> ReportingPeriod.from_period_end(value="2025-12-31").next().label
'2026Q1'

previous(*, n: int = 1) → ReportingPeriod[source]#

Return the period n quarters before this one.

Going back past Q1 rolls over into Q4 of the preceding year.

Parameters:

nint, default 1: Number of quarters to go back. May be negative.

Returns:

ReportingPeriod: The resulting period, with year rollover handled automatically.

Examples

>>> ReportingPeriod.from_period_end(value="2026-03-31").previous().label
'2025Q4'