cadrumo.domain.period module

Date-boundary helpers for filing-period registry tokens.

Period is the backend filing-period authority: a filing year plus registry token, constructed with Period.from_year_and_code. This module provides only date-boundary helpers for bare registry tokens.

Do not treat this module as canonical period storage. Prefer typed Period at domain boundaries and decompose to filing_year plus registry_token only at registry/helper seams.

The nP tokens are the Impuesto sobre Sociedades pago-fraccionado instalment claves (Modelo 202). Per the AEAT Modelo 202 instructions, 1P is the payment made in the first twenty days of April, 2P the equivalent October payment, and 3P the December payment; the period-boundary helpers map each instalment to its payment month.

These helpers are not a display parser, not a ledger date-span authority, and not a replacement for registry period validation. They accept the bare tokens already selected by an owning caller and raise typed domain period errors when the token cannot be mapped.

Callers wrap ValueError into their own domain error type (e.g. ModeloBuilderError, RegistrySnapshotError) at the boundary they own.

exception RegistryPeriodError(message=None, *, context=None, translated_message=None)

Bases: CadrumoError

Base class for errors raised by this bare registry-token helper module.

Parameters:

• message (str | None)

• context (Mapping[str, object] | None)

• translated_message (str | None)

Return type:

None

code

exception PeriodValidationError(message=None, *, context=None, translated_message=None)

Bases: RegistryPeriodError

Raised when a bare registry token cannot be mapped to helper dates.

Parameters:

• message (str | None)

• context (Mapping[str, object] | None)

• translated_message (str | None)

Return type:

None

code

period_start_date(filing_year, registry_period)

Return the inclusive start-of-period date for a registry token.

Parameters:

• filing_year (int) – The filing year carried by the typed period scope.

• registry_period (str) – Bare registry token such as "1T" … "4T", "01" … "12", "0A", or Modelo 202 instalments "1P" … "3P".

Return type:

date

Returns:

The first day of the period the token covers (e.g. "1T" → YYYY-01-01, "4T" → YYYY-10-01, "0A" → YYYY-01-01, "03" → YYYY-03-01, "1P" → YYYY-04-01, "2P" → YYYY-10-01, "3P" → YYYY-12-01).

Raises:

PeriodValidationError – When registry_period is not a recognised shape.

period_end_date(filing_year, registry_period)

Return the inclusive end-of-period date for a registry token.

Parameters:

• filing_year (int) – The filing year carried by the typed period scope.

• registry_period (str) – Bare registry token such as "1T" … "4T", "01" … "12", "0A", or Modelo 202 instalments "1P" … "3P".

Return type:

date

Returns:

The last day of the period the token covers (e.g. "1T" → YYYY-03-31, "0A" and "4T" → YYYY-12-31, "03" → YYYY-03-31, "1P" → YYYY-04-30, "2P" → YYYY-10-31, "3P" → YYYY-12-31).

Raises:

PeriodValidationError – When registry_period is not a recognised shape.

calculation_filing_date(period)

Resolve the deterministic filing date used by a calculation context.

This is deliberately distinct from period_end_date(). The latter is a strict bare-token range helper and continues to refuse tokens that do not represent a ledger date span. A calculation already owns a typed Period, however, and needs a date for every accepted code so temporal registry parameters resolve consistently across calculation, verification, filing replay, and calculation-sheet paths.

Parameters:

period (Period) – The typed filing-period scope of the calculation.

Return type:

date

Returns:

The inclusive end date for contiguous periods; the corresponding ordinary quarter end for EXT-nT; Modelo 202 payment-month ends for 1P through 3P; and 31 December for 4P, AD-HOC, and EVENT-N.