cadrumo.domain.deadlines.plazo module

Registry lookup for filing window close dates (plazo voluntario).

Provides a profile-free function to ask “when does the plazo voluntario close for this modelo + filing year + period?” directly from the registry deadline windows. The result feeds the pre-calculation extemporaneidad surface in cadrumo.application.modelo.work_plazo. Post-calculation consumers that know resultado or Modelo 210 tipo-renta context call the sibling resolve_filing_window entry point; both paths therefore share the same canonical matcher.

Core types: ModeloRevision.

resolve_filing_closes_on(modelo, filing_year, period, *, authority=None)[source]

Return the close date of the plazo voluntario for a modelo+year+period.

Queries the validated registry authority for filing_year through resolve_filing_window() and returns the closes_on of its unique unqualified match. This function deliberately accepts no resultado or Modelo 210 tipo-renta context: it is the pre-calculation convenience, while post-calculation callers use resolve_filing_window directly rather than owning another matcher.

The resolved value belongs to the matching DeadlineWindowDefinition.

Matching rule: the registry window period must carry the same filing year and bare registry period token as the supplied WorkUnit period (e.g. "1T", "0A", "01").

Annual Modelo 100 uses its tax year as the registry key even though its normal campaign runs in the following calendar year. A close date for tax year 2024 can therefore fall in 2025. This function never borrows a following-year or future-year window when an exact match is absent.

Returns None when no registry window exactly matches the combination. The modelo might have no deadline window for that year, or its period token might not match any window. None means the deadline data is unavailable; callers continue without a close date.

A modelo absent from the registry is NOT one of those causes and REFUSES with RegistrySnapshotError rather than returning None. Production reaches this through the Modelo enum, so an unregistered id is a caller bug or unvalidated external input; returning None would hand that caller “no deadline”, and an extemporaneidad computed from it would silently drop the recargo.

Parameters:

  • modelo (str) – Agencia Estatal de Administración Tributaria (AEAT) modelo code (e.g. "130", "303").

  • filing_year (int) – Tax year for which the work unit was created.

  • period (Period) – WorkUnit bare registry period token (e.g. "1T", "0A", "01").

  • authority (PinnedAuthorityOperation | None) – Optional generation-pinned authority operation.

Return type:

date | None

Returns:

The date on which the filing window closes, or None if not found.

resolve_filing_window(modelo, filing_year, period, *, resultado=None, tipo_renta_code=None, authority=None)[source]

Return the registry deadline window for a modelo+year+period, or None.

This is the single matching authority for “which registry deadline window covers this filing target”. Every consumer — the extemporaneidad surface that needs only closes_on, and the overview calendar that also needs opens_on and payment_cutoff_on — resolves through here, so a change to the year/token matching rule or to the no-window behaviour can never move one surface without the other.

Matching uses the registry’s canonical atomic deadline coordinate. The filing year and bare period token must be exact; a window’s absent qualifier scope is a wildcard, while an authored resultado or tipo-renta scope must contain the requested canonical value. No following-year or future-year window is ever borrowed when an exact match is absent.

None means one thing only: the registry loaded, and declares no window matching this combination. A registry that cannot be read or validated is NOT an absence of deadline and is not reported as one – the RegistryError propagates.

Reading deadline_windows costs full modelo validation, because the authority validates the modelo before projecting its windows. Catching that failure here and returning None turned any registry-wide validation fault into the claim that AEAT declares no filing deadline for this modelo and period – a failure laundered into a confident answer about when a taxpayer must file. The sibling deadline engine wraps the same call and raises with the failing stage named; this now agrees with it.

Parameters:

  • modelo (str) – Agencia Estatal de Administración Tributaria (AEAT) modelo code (e.g. "130", "303").

  • filing_year (int) – Tax year for which the filing target was created.

  • period (Period) – The typed filing period to match.

  • resultado (ResultDisposition | None) – Optional canonical post-calculation result disposition.

  • tipo_renta_code (str | None) – Optional official two-digit Modelo 210 tipo-renta code.

  • authority (PinnedAuthorityOperation | None) – Optional generation-pinned authority operation.

Return type:

DeadlineWindowDefinition | None

Returns:

The matching DeadlineWindowDefinition, or None when the registry declares no window for the combination.

Raises:

  • RegistryError – The registry could not be read or validated. The caller is told the deadline is unknown rather than absent.

  • DeadlineValidationError – More than one window matches the atomic request coordinate. Ambiguous registry authority is never treated as absence.