cadrumo.core.identity.documents module

Spanish tax-identifier parser and check-character validator.

This module owns the immutable format shape and pure validation arithmetic, while a caller supplies every operative declaration from its authority. Core validation performs no registry lookup, file access, or provider registration. The public validate_identity() parser returns an IdentityDocument member and raises IdentityError on malformed input. Callers that need the canonical string form use validate_spanish_tax_id().

class SpanishTaxIdFormat(width, country_prefix, country_prefixed_width, country_prefix_strip_width, prefixed_nif_leaders, nie_leaders, cif_leaders, nif_letters, nie_prefix_substitutions, cif_digit_only_kinds, cif_letter_only_kinds, cif_letter_table)[source]

Bases: object

Immutable declarations required by the pure Spanish tax-ID kernel.

This type defines structure only. Every operative value is supplied by a governed authority fact and no default is intentionally available here.

Parameters:

  • width (int)

  • country_prefix (str)

  • country_prefixed_width (int)

  • country_prefix_strip_width (int)

  • prefixed_nif_leaders (str)

  • nie_leaders (str)

  • cif_leaders (str)

  • nif_letters (str)

  • nie_prefix_substitutions (tuple[tuple[str, str], ...])

  • cif_digit_only_kinds (str)

  • cif_letter_only_kinds (str)

  • cif_letter_table (str)

width: int
country_prefix: str
country_prefixed_width: int
country_prefix_strip_width: int
prefixed_nif_leaders: str
nie_leaders: str
cif_leaders: str
nif_letters: str
nie_prefix_substitutions: tuple[tuple[str, str], ...]
cif_digit_only_kinds: str
cif_letter_only_kinds: str
cif_letter_table: str
class IdentityDocument(*values)[source]

Bases: StrEnum

Closed catalogue of recognised Spanish identity-document kinds.

Variables:

  • NIF – Número de Identificación Fiscal — Spanish nationals.

  • NIE – Número de Identidad de Extranjero — foreign residents.

  • CIF – Código de Identificación Fiscal — legal entities.

NIF
NIE
CIF
is_identity_structurally_shaped(candidate)[source]

Return whether candidate has a tax-identity lexical shape.

This is intentionally a syntax-only admission predicate for low-level consumers such as redaction. It does not claim that the candidate is a currently recognised Spanish NIF, NIE, or CIF: leader membership, checksum tables, and control-character partitions remain supplied by an explicit authority format to validate_identity().

Return type:

bool

Parameters:

candidate (object)

exception IdentityError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoError

Raised when a candidate string is not a valid Spanish identity document.

Bound to the registered error code INTEGRITY_IDENTITY_DOCUMENT in ALL_DECLARED_ERROR_CODES. Carries a human-readable diagnostic that names the failing shape (NIF, NIE, CIF) and, where relevant, the expected vs observed check character.

Its canonical registered ancestry is CadrumoError. Pydantic validators translate this registered failure to ValueError at their narrow validator boundary.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
nif_check_letter(number, tax_id_format)[source]

Return the AEAT NIF / NIE check letter for a numeric body.

Resolves the governed check-letter table without retaining a local catalogue. This is the single source of the check-letter computation for the whole cadrumo.core.identity package; the sibling cadrumo.core.identity.tax_id consumes it rather than re-declaring the modulo expression, and every enum-returning validator in this module computes its expected letter through it.

Return type:

str

Parameters:
validate_identity(candidate, tax_id_format)[source]

Parse and check-letter-validate a Spanish identity document.

Disambiguates by the leader sets in the registry-owned mapping, then applies the checksum/control algorithm for the selected shape and returns the parsed IdentityDocument.

Parameters:

  • candidate (object) – A free-form candidate value. Strings tolerate surrounding whitespace, dashes, spaces, and casing; non-string values are rejected with a typed IdentityError.

  • tax_id_format (SpanishTaxIdFormat) – Complete authority-supplied format declarations.

Return type:

IdentityDocument

Returns:

The matching IdentityDocument enum member.

Raises:

IdentityError – When candidate is not a string, is empty, or does not match any valid shape, or when the check letter or digit fails the AEAT algorithm.