aeat.domain.calculations.registry._citation_blocklist module

Known-bad Spanish-tax legal citation guardrails for registry validation.

CitationSource

Closed set of Spanish-law source types a registry legal citation may reference.

Maps to the source field on legal_refs entries in the modelo registry TOML authoring tree. Values are lowercase identifiers:

  • "ley" — primary legislation (e.g. LIRPF, LIS, LIVA).

  • "real_decreto" — Royal Decree (e.g. RIRPF, RIS).

  • "real_decreto_legislativo" — consolidated legislative text approved by royal legislative decree (e.g. TRLIRNR).

  • "orden" — Ministerial Order (HAC/EHA prefixes).

  • "reglamento" — secondary regulation.

  • "manual" — AEAT published guidance manual.

  • "instruction" — AEAT instruction document.

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

known_bad_citations()[source]

Return the reviewed KnownBadCitation guardrail entries.

Return type:

tuple[KnownBadCitation, ...]

find_known_bad(source, article, role_text)[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 (Literal['ley', 'real_decreto', 'real_decreto_legislativo', 'orden', 'reglamento', 'manual', 'instruction']) – 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.

Return type:

KnownBadCitation | None

Returns:

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