aeat.core._period module

Canonical period code enumeration for filing periods.

Period codes represent the filing frequency and scheme for tax returns: - Quarterly: 1T, 2T, 3T, 4T (standard filing periods) - Instalment: 1P, 2P, 3P, 4P (corporate-tax/IS instalment periods) - Annual: 0A - Monthly: 01-12 (calendar months) - OSS/IOSS: EXT-1T, EXT-2T, EXT-3T, EXT-4T (extra-Union scheme) - Ad-hoc/Event: AD-HOC, EVENT-N (event-driven filings)

StandardPeriodCode is the canonical StrEnum for the closed standard vocabulary (1T-4T, 1P-4P, 0A, 01-12). It includes both calendar spans and instalment claves, so callers that need date boundaries must still check Period.has_date_span(). RegistryPeriodCode is the pydantic field annotation for the full registry union: standard members plus extended OSS/IOSS literals, AD-HOC, and the open-ended EVENT-N shape. Period combines one accepted code with a filing year, and PeriodKind classifies the resulting cadence.

This module is the runtime counterpart to the registry domain.calculations.registry.PeriodCode alias and domain.calculations.registry.PeriodSelector schema. Registry objects carry bare period tokens; application services that need a concrete filing window compose those tokens with a year into Period. Operator commands follow the same separated shape (--year YYYY --period <AEAT-token>); any year-qualified filter mini-grammar is converted at the CLI boundary before it reaches this model.

class StandardPeriodCode(*values)

Bases: StrEnum

Canonical enumeration of closed standard filing-period codes.

Quarterly, monthly, and annual members have calendar spans. Instalment members (1P-4P) identify filing/payment events and intentionally do not imply a contiguous ledger date span.

Q1

Q2

Q3

Q4

P1

P2

P3

P4

ANNUAL

JAN

FEB

MAR

APR

MAY

JUN

JUL

AUG

SEP

OCT

NOV

DEC

accepted_period_codes()

Return the fully enumerable period codes.

The tuple includes StandardPeriodCode, extended OSS/IOSS literals, and AD-HOC. It deliberately excludes the infinite EVENT-N family; pair it with accepted_period_patterns() when building help text or parse-error guidance.

Return type:

tuple[str, ...]

accepted_period_patterns()

Return human-readable period-code patterns, including open regex shapes.

Return type:

tuple[str, ...]

RegistryPeriodCode

Pydantic field annotation for bare registry period tokens. Use Period instead when a filing year is known.

alias of Annotated[str, BeforeValidator(func=_validate_period_against_registry, json_schema_input_type=PydanticUndefined)]

exception PeriodError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: AeatError, ValueError

Raised when a Period is constructed from an invalid year/code.

Subclasses ValueError so pydantic validation and existing callers retain value-error compatibility while still routing through the registered AeatError hierarchy required for production exceptions.

Parameters:

• message (str | None)

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

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

class PeriodKind(*values)

Bases: StrEnum

Cadence class of a filing period, derived from its registry code.

QUARTERLY

MONTHLY

ANNUAL

INSTALMENT

EXTENDED

class Period(**data)

Bases: BaseModel

A filing period as one typed value: a year paired with a registry code.

Period is the canonical, fundamental representation of “which filing period” across the whole application. It composes exactly two authoritative fields — the filing_year and the registry period code (a StandardPeriodCode member such as 1T / 0A / 03, or an extended union member such as EXT-1T / AD-HOC / EVENT-3) — and never a combined calendar string (2026Q1 / 2026-03 / 2026). Those calendar shapes are neither accepted inputs nor canonical outputs. The only display projection is the space-separated __str__() form ("2026 1T"), and normal inbound construction is from a (year, code) pair via from_year_and_code().

The model is frozen and hashes by (filing_year, code), so a Period is a drop-in dict key, set member, and equality target wherever a typed period is required. The ledger and aggregation boundary routes through application.aggregation.aggregation_period_for_modelo(), then uses contains() as the single date-boundary authority.

Variables:

• filing_year – Filing year carried separately from the registry token.

• code – Bare RegistryPeriodCode token validated against the registry period union.

Parameters:

• filing_year (int)

• code (Annotated[str, BeforeValidator(func=~aeat.core._period._validate_period_against_registry, json_schema_input_type=PydanticUndefined)])

filing_year: int

code: RegistryPeriodCode

classmethod from_year_and_code(year, code)

Build a Period from a filing year and a bare registry code.

Parameters:

• year (int) – The filing year (e.g. 2026).

• code (str) – A bare registry period code — a StandardPeriodCode value (1T-4T / 1P-4P / 0A / 01-12) or an extended union member (EXT-1T-EXT-4T / AD-HOC / EVENT-N). The code is validated against the registry union; a combined calendar string is refused.

Raises:

PeriodError – When code is not an accepted registry period code or year is outside the supported range.

Return type:

Period

classmethod from_string(value)

Parse the canonical display string emitted by __str__().

Only the separated "YYYY <registry-code>" display form is accepted. Combined calendar strings such as "2026Q1" or "2026-1T" are refused; this method is for display round-trips, not an alternate CLI or registry grammar.

Parameters:

value (str) – Space-separated display string containing a four-digit filing year and a bare registry period code.

Return type:

Period

Returns:

A Period parsed from the canonical display string.

Raises:

PeriodError – When value is not the display form or contains an invalid registry period code.

property year: int

Return the filing year (alias of filing_year).

property registry_token: str

Return the bare registry period code as a string (e.g. "1T").

Use this when calling registry APIs that expect the bare domain.calculations.registry.PeriodCode token rather than a structured Period.

property standard_code: StandardPeriodCode | None

Return the StandardPeriodCode member, or None for extended forms.

property kind: PeriodKind

Return the cadence class derived from the period code.

has_date_span()

Return whether the period maps to an inclusive calendar date span.

Quarterly, monthly, and annual periods cover a contiguous span of calendar dates. Instalment claves (1P-4P) and the extended union members are filing/payment events, not calendar spans, so they return False and start_date / end_date refuse for them.

Return type:

bool

property start_date: date

Return the inclusive first calendar date of the period.

Raises:

PeriodError – When the period has no calendar span (has_date_span() is False).

property end_date: date

Return the inclusive last calendar date of the period.

Raises:

PeriodError – When the period has no calendar span (has_date_span() is False).

contains(value)

Return whether value falls within this period’s inclusive span.

Raises:

PeriodError – When the period has no calendar span.

Return type:

bool

Parameters:

value (date)