aeat.domain.contribuyente._keys module

Schema-backed registry of editable taxpayer-profile keys.

The registry is a tuple of strict ProfileKey records compiled from the wizard descriptor catalogue (aeat.application.wizard._catalogue.WIZARD_FLOWS) and pushed into this domain registry via register_profile_keys() when the wizard package is imported (its __init__ eagerly runs the compiler’s registration). The domain never pulls upward into the application layer (DB-17): reading the registry before the push raises ProfileKeysRegistrationError. Each entry carries the canonical key path (dot-separated), a requirement flag (required vs optional for declaration export), and a short multilingual description rendered in operator-facing surfaces.

Adding a new key means appending a WizardQuestion to the relevant flow in the wizard catalogue. The ProfileKey class itself remains the canonical schema record consumed by validate_profile and every profile editor surface.

class ProfileKeyRequirement(*values)

Bases: StrEnum

Whether a profile key is mandatory before declaration export.

REQUIRED

OPTIONAL

class ProfileKey(**data)

Bases: BaseModel

Strict frozen record describing one editable profile key.

Parameters:

• key (str)

• requirement (ProfileKeyRequirement)

• description (Translatable)

• required_when_key (str | None)

• required_when_value (str | None)

key: str

requirement: ProfileKeyRequirement

description: tr

required_when_key: str | None

required_when_value: str | None

classmethod from_key(raw)

Return the ProfileKey for raw after canonical normalisation.

Normalisation strips surrounding whitespace, lowercases, and folds dashes into dots so "TAX.ID" and "tax.id" resolve to the same registry entry.

Parameters:

raw (str) – Raw profile key string, possibly with non-canonical casing or separator characters.

Return type:

ProfileKey

Returns:

The matching ProfileKey from the registry.

Raises:

KeyError – When the normalised form is not in the registry.

register_profile_keys(keys)

Seed the domain profile-key registry from outside the domain layer.

The compiled tuple normally lives behind a lazy import inside _build_profile_keys(). Outer layers (the wizard compiler) can call this function at their own import time to seed the cache directly, so the lazy import is never triggered. Calling this function twice with different tuples raises a RuntimeError so the registration stays single-writer.

Return type:

None

Parameters:

keys (tuple[ProfileKey, ...])

profile_keys()

Return the full registered ProfileKey tuple, resolved at call time.

Unlike the PROFILE_KEYS module attribute (resolved once, at whatever moment a caller’s from ... import PROFILE_KEYS statement executes), this function always defers resolution to the moment it is called. Callers that read the registry from inside a function body (rather than at their own module-import time) should prefer this function so they cannot race the wizard catalogue’s registration.

Return type:

tuple[ProfileKey, ...]

get_profile_key(key)

Return the ProfileKey for key.

Performs canonical normalisation (strip / lowercase / dash-to-dot) before the registry lookup so case-insensitive callers resolve to the same entry as the canonical form.

Parameters:

key (str) – Raw profile key string to look up.

Return type:

ProfileKey

Returns:

The matching ProfileKey from the registry.

required_profile_keys()

Return only the keys whose requirement is REQUIRED.

Return type:

tuple[ProfileKey, ...]

Returns:

Tuple of ProfileKey entries that are required.

optional_profile_keys()

Return only the ProfileKey entries whose requirement is OPTIONAL.

Return type:

tuple[ProfileKey, ...]