aeat.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 PeriodError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError

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

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception PeriodValidationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: PeriodError, ValueError

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

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
period_start_date(filing_year, registry_period)[source]

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)[source]

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-01 for the monthly-as-first-of-month convention the application layer already uses, "1P" → YYYY-04-30, "2P" → YYYY-10-31, "3P" → YYYY-12-31).

Raises:

PeriodValidationError – When registry_period is not a recognised shape.