cadrumo.domain.deadlines.recargo module¶

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

The bracket schedule is published in the typed runtime authority so surcharge percentages stay outside Python source and can be revised without touching engine code. Two functions are exposed:

load_recargo_bands() adapts the published projection into a tuple of domain.deadlines.models.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 graduated band whose [min_completed_months, max_completed_months] window contains a given completed-months value.
more_than_twelve_months_elapsed() decides the 15% + intereses tail: it fires only STRICTLY AFTER the twelve-month anniversary of the deadline (the anniversary day itself stays in the graduated band per Art. 27.2), a boundary a completed-months count alone cannot resolve.

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

load_recargo_bands(*, operation)[source]¶

Adapt recargo brackets from the caller’s pinned published authority.

Adapted once per operation: every overdue obligation a schedule computes asks for the same table, and the table cannot change within a generation.

Return type:: tuple[RecargoBand, ...]
Returns:: Tuple of RecargoBand records ordered by min_completed_months ascending.
Parameters:: operation (PinnedAuthorityOperation)

completed_months_late(closes_on, reference_today)[source]¶

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).

twelve_month_anniversary(closes_on)[source]¶

Return the twelve-month anniversary of the filing window close date.

Art. 27.2 LGT ties the 15% + intereses tail to the filing being presented “una vez transcurridos 12 meses” — once the twelve-month period has fully elapsed. This helper returns the término of that period: the same day-of-month twelve months later. A day-of-month that does not exist in the target month (a 29 February close carried to a non-leap year) clamps to the month’s last day, matching the AEAT “mismo día del mes” convention.

Parameters:: closes_on (date) – The filing window’s close date (deadline).
Return type:: date
Returns:: The date on which twelve months have elapsed since closes_on.

more_than_twelve_months_elapsed(closes_on, reference_today)[source]¶

Return whether reference_today is STRICTLY past the twelve-month term.

Art. 27.2 LGT: the 15% + intereses de demora tail applies only when the self-assessment is presented “una vez transcurridos 12 meses” — after the twelve-month period has elapsed. The statute pins the boundary via the interest clause: intereses run “desde el día siguiente al término de los 12 meses”. The anniversary date itself (the término) therefore still belongs to the graduated 1%-per-completed-month band; only the day after and beyond fall into the 15% tail.

Parameters:

closes_on (date) – The filing window’s close date (deadline).
reference_today (date) – The date the self-assessment is presented.

Return type:

bool

Returns:

True when reference_today is strictly after the twelve-month anniversary of closes_on (the 15% + interest tail applies); False on or before the anniversary (the graduated band applies).

resolve_recargo_band(completed_months, bands)[source]¶

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 an authority gap).

build_recovery_for_overdue(*, closes_on, reference_today, modelo, period, operation, bands=None)[source]¶

Resolve the Recovery payload for an OVERDUE obligation.

The recargo percentage is computed precisely per Art. 27.2 LGT: 1% + 1% per COMPLETED month of delay while inside the first twelve months (up to 13% at the twelve-month anniversary), and 15% + intereses de demora only once the filing is presented “una vez transcurridos 12 meses” — STRICTLY AFTER the twelve-month anniversary. The tail boundary is date-gated rather than derived from the completed-months count alone: the day immediately after the anniversary still reports twelve completed months yet already carries the 15% consequence, so more_than_twelve_months_elapsed() decides the tail while resolve_recargo_band() resolves the graduated band otherwise.

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 for the overdue obligation.
period (Period) – Typed filing period for the overdue obligation.
operation (PinnedAuthorityOperation) – Caller-owned generation-pinned authority operation used when adapting the published band table.
bands (Sequence[RecargoBand] | None) – Optional pre-loaded band table; when None, the published runtime authority is adapted.

Return type:

Recovery

Returns:

A Recovery carrying the resolved band and legal reference.