aeat.domain.deadlines._recargo module

Loader and resolver for the Ley 58/2003 art-27 recargo bracket table.

The bracket schedule lives at registry/aeat/legal/ley-58-2003-recargo-bands.toml so the surcharge percentages stay outside Python source and can be revised when the law changes without touching engine code. Two functions are exposed:

• load_recargo_bands() reads and validates the TOML into a tuple of domain.deadlines.RecargoBand records.

• completed_months_late() counts the COMPLETED months between the filing deadline and the presentation date (Art. 27.2 LGT counts only whole months; a fractional month does not count).

• resolve_recargo_band() selects the band whose [min_completed_months, max_completed_months] window contains a given completed-months value.

The deadline engine calls build_recovery_for_overdue() to populate the Recovery field on every OVERDUE ModeloDeadline.

load_recargo_bands(path=None)

Load and validate the recargo bracket TOML.

Parameters:

path (Path | None) – Override path; defaults to the canonical registry location.

Return type:

tuple[RecargoBand, ...]

Returns:

Tuple of RecargoBand records ordered by min_completed_months ascending.

Raises:

DeadlineValidationError – When the TOML cannot be read, is malformed, is missing rows, or carries an invalid band.

completed_months_late(closes_on, reference_today)

Return the number of COMPLETED months between deadline and presentation.

Art. 27.2 LGT escalates the recargo “por cada mes completo de retraso” — by each completed month of delay. A month is completed only when the presentation date has reached the same day-of-month as the deadline in a later month; a fractional (incomplete) month does not count.

Parameters:

• closes_on (date) – The filing window’s close date (deadline).

• reference_today (date) – The date the self-assessment is presented.

Return type:

int

Returns:

Completed months of delay, >= 0 (0 when filed late but within the first incomplete month).

resolve_recargo_band(completed_months, bands)

Return the band whose window contains completed_months.

Parameters:

• completed_months (int) – Completed months past the filing window’s close date, as returned by completed_months_late(). Must be >= 0.

• bands (Sequence[RecargoBand]) – Tuple of bands as returned by load_recargo_bands().

Return type:

RecargoBand

Returns:

The matching RecargoBand.

Raises:

DeadlineValidationError – When completed_months < 0 or no band’s window covers the value (which would indicate a TOML gap).

build_recovery_for_overdue(*, closes_on, reference_today, modelo, period, bands=None)

Resolve the Recovery payload for an OVERDUE obligation.

The recargo percentage is computed precisely per Art. 27.2 LGT from the number of COMPLETED months between closes_on and reference_today (1% + 1% per completed month; 15% + intereses de demora once 12 completed months have elapsed), not from a day-bracket approximation.

Parameters:

• closes_on (date) – The filing window’s close date (deadline).

• reference_today (date) – The date the self-assessment is presented.

• modelo (str) – Modelo identifier the operator must still file.

• period (Period) – Typed filing period for the overdue obligation.

• bands (Sequence[RecargoBand] | None) – Optional pre-loaded band table; when None, the canonical TOML is loaded once.

Return type:

Recovery

Returns:

A Recovery carrying the resolved band, the legal reference, and a runnable next-action command.