cadrumo.domain.calculations.registry.citation_blocklist module

Known-bad citation guardrails for registry validation.

CitationSource

Closed parser token set for the registry citation source field.

The tokens identify the syntax category accepted by the validation boundary; the cited declarations and their governing text remain registry data.

alias of Literal[‘ley’, ‘real_decreto’, ‘real_decreto_legislativo’, ‘orden’, ‘reglamento’, ‘manual’, ‘instruction’]

class KnownBadCitation(source, article, role_substring, reason)[source]

Bases: NamedTuple

A guardrail entry recording one mis-cited Spanish-tax legal reference.

Variables:

  • source – The CitationSource category of the misfiring citation (e.g. "ley", "reglamento").

  • article – The article number string as it appears in registry TOML (e.g. "103", "100.3.a").

  • role_substring – A translatable substring that the casilla’s role field must contain to trigger this guard. Matching is done after Unicode diacritic folding and case folding.

  • reason – Human-readable explanation of why the citation is wrong and which article should be used instead. Used in validation error messages surfaced to the registry author.

Parameters:

  • source (Literal['ley', 'real_decreto', 'real_decreto_legislativo', 'orden', 'reglamento', 'manual', 'instruction'])

  • article (str)

  • role_substring (Translatable)

  • reason (str)

source: Literal['ley', 'real_decreto', 'real_decreto_legislativo', 'orden', 'reglamento', 'manual', 'instruction']

Alias for field number 0

article: str

Alias for field number 1

role_substring: Translatable

Alias for field number 2

reason: str

Alias for field number 3

find_known_bad(source, article, role_text, *, effective_date, effective_to=None, authority=None)[source]

Return the first blocklist entry that matches the supplied citation, or None.

Matching is performed after diacritic folding: role_text and every KnownBadCitation.role_substring are lowercased and stripped of combining diacritics before the substring test runs, so "cuota íntegra" and "cuota integra" compare as equal.

Parameters:

  • source (str) – The CitationSource category of the citation being validated.

  • article (str) – The article number string as written in registry TOML.

  • role_text (str) – The free-text role field of the casilla being validated.

  • effective_date (date) – The legal reference’s effective date, used on the catalogue’s filing-period date axis. A date before the registry’s supported filing-year floor is evaluated at the floor instead: the catalogue cannot open a window earlier than the floor, and a norm already in force before the floor is still checked at the earliest coordinate the registry can represent.

  • effective_to (date | None) – The legal reference’s own expiry, when known. A reference whose entire validity ends before the floor is skipped rather than clamped: the registry has no representable coordinate at which that citation could ever be checked.

  • authority (GovernedFactSource | None) – Optional validated authority; omitted callers use the bundled published authority.

Return type:

KnownBadCitation | None

Returns:

The matching KnownBadCitation entry, or None if the citation is not on the blocklist.