aeat.domain.calculations.registry._errors module

Registry error types for AEAT legal calculation definitions.

This module provides classmethod factories on RegistryValidationError and RegistrySnapshotError for each canonical raise scenario. The factory pattern pins the context-dict keys downstream consumers (aeat.core.errors._registry template renderer, CLI JSON emit via SchemaEnvelope, i18n locales referencing keys by name) rely on.

The existing raise RegistryValidationError(message, context=...) shape stays valid for one-off scenarios that haven’t been promoted to canonical factories yet; migration is additive and non-breaking.

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

Bases: AeatError, ValueError

Base error for registry loading, resolution, and validation.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception RegistryLoadError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: RegistryError

Raised when registry files cannot be parsed into strict schema objects.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception RegistryValidationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: RegistryError, CoreValidationError

Raised when registry definitions are incomplete or contradictory.

Inherits from CoreValidationError to participate in the shared CoreValidationError catch surface across all layers. RegistryError already provides ValueError co-inheritance.

Canonical raise scenarios route through one of the for_* classmethod factories so the context-dict keys consumed by locale templates and CLI JSON emit are pinned to a named contract per scenario.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

classmethod for_unsupported_op(op)[source]

Formula expression uses an op the runtime does not implement.

Canonical key: op. Twelve raise sites today.

Return type:

Self

Parameters:

op (str)

classmethod for_unsupported_comparison_op(op)[source]

compare(...) received an op name outside the closed comparison set.

Return type:

Self

Parameters:

op (str)

classmethod for_unknown_parameter(*, parameter_id)[source]

A formula referenced a parameter id absent from the revision.

Canonical key: parameter_id. Seven raise sites today.

Return type:

Self

Parameters:

parameter_id (str)

classmethod for_dispatch_key_unknown(*, op, binding_id, dispatch_key, available_keys)[source]

A formula’s dispatch_table is missing the resolved enum key.

Canonical keys: op, binding_id, dispatch_key, available_keys. Three raise sites today (lookup_bracket_by_ccaa / lookup_parameter_by_entity_type / lookup_bracket_by_entity_type).

Return type:

Self

Parameters:
classmethod for_lookup_dispatch_arg_kind(*, op, position, expected_kind)[source]

A lookup-dispatch op’s positional arg has the wrong leaf kind.

Canonical keys: op, position, expected_kind. Four raise sites today.

Return type:

Self

Parameters:

  • op (str)

  • position (str)

  • expected_kind (str)

classmethod for_lookup_dispatch_arg_count(*, op, expected)[source]

A lookup-dispatch op was passed the wrong number of args.

Canonical keys: op, expected.

Return type:

Self

Parameters:
classmethod for_dispatch_parameter_kind(*, parameter_id, op)[source]

A dispatched parameter has the wrong data_type for its op.

Return type:

Self

Parameters:
classmethod for_enum_binding_value_missing(*, binding_id, op)[source]

A required enum binding has no supplied value at evaluation time.

Canonical keys: binding_id, op.

Return type:

Self

Parameters:

  • binding_id (BindingId)

  • op (str)

classmethod for_binding_value_missing(*, binding_id)[source]

A required binding has no supplied value at evaluation time.

Return type:

Self

Parameters:

binding_id (BindingId)

classmethod for_relation_value_missing(*, relation_id)[source]

A required relation has no supplied value at evaluation time.

Return type:

Self

Parameters:

relation_id (RelationId)

classmethod for_casilla_referenced_before_evaluation(*, casilla_id)[source]

A formula referenced a casilla that hasn’t been evaluated yet.

Return type:

Self

Parameters:

casilla_id (CasillaId)

classmethod for_unknown_input_casilla_ids(*, casilla_ids)[source]

Inputs to the runtime referenced casilla ids absent from the revision.

Return type:

Self

Parameters:

casilla_ids (Sequence[CasillaId])

classmethod for_computed_supplied_as_input(*, casilla_ids)[source]

Inputs to the runtime supplied values for computed casillas.

Return type:

Self

Parameters:

casilla_ids (Sequence[CasillaId])

classmethod for_bracket_no_window(*, parameter_id, as_of)[source]

A bracket-table parameter has no bracket valid for the requested date.

Return type:

Self

Parameters:

  • parameter_id (str)

  • as_of (str)

classmethod for_bracket_no_coverage(*, parameter_id, base)[source]

A bracket-table parameter has no bracket covering the requested base.

Return type:

Self

Parameters:

  • parameter_id (str)

  • base (str)

classmethod for_bracket_negative_base(*, parameter_id, base)[source]

A bracket-table lookup received a negative base value.

Return type:

Self

Parameters:

  • parameter_id (str)

  • base (str)

classmethod for_divide_by_zero()[source]

A formula expression divides by zero at runtime.

Return type:

Self

classmethod for_empty_expression()[source]

A formula expression contains no leaf or op (empty).

Return type:

Self

code: ClassVar[ErrorCode]
exception RegistrySnapshotError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: RegistryError

Raised when a filing-grade snapshot cannot be selected.

The single canonical raise scenario is for_modelo_not_registered at the _authority.modelo boundary; the bare constructor stays valid for one-off scenarios not yet promoted to a factory.

Two temporal-selection scenarios carry structured context as dedicated subclasses (NoRevisionForPeriodError, AmbiguousRevisionSelectionError) so a consumer dispatches by except type rather than parsing the human-readable message. Both subclass this type, so every existing except RegistrySnapshotError site catches them unchanged.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

classmethod for_modelo_not_registered(*, modelo_id)[source]

The requested modelo id has no registered revision.

Return type:

Self

Parameters:

modelo_id (str)

code: ClassVar[ErrorCode]
exception NoRevisionForPeriodError(*, modelo_id, filing_year, period, revision_id)[source]

Bases: RegistrySnapshotError

No registry revision matches the requested temporal natural key.

Raised by select_revision() when the (modelo, filing year, period, optional date window, optional revision id) constraints select zero candidate revisions. Carries the natural-key components as structured context so a consumer (e.g. the config profile preflight resolver) can build an instructive refusal without parsing the message. Catchable as RegistrySnapshotError.

Structured attributes: modelo_id, filing_year, period, revision_id.

Parameters:

  • modelo_id (str)

  • filing_year (int)

  • period (str)

  • revision_id (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception AmbiguousRevisionSelectionError(*, modelo_id, candidate_ids)[source]

Bases: RegistrySnapshotError

More than one registry revision matches the temporal natural key.

Raised by select_revision() when the constraints select two or more candidate revisions. Carries the candidate revision ids as a structured, already-sorted tuple so a consumer can list them in an operator refusal without re-parsing the message. Catchable as RegistrySnapshotError.

Structured attributes: modelo_id, candidate_ids.

Parameters:

  • modelo_id (str)

  • candidate_ids (Iterable[str])

Return type:

None

code: ClassVar[ErrorCode]
exception CasillaConstraintViolationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: RegistryError

Raised when a computed casilla value falls outside its declared constraints.

The constraint set is casilla.constraints (sign, min_value, max_value). The error envelope carries casilla_id, the offending value, the offended constraint clause, and the casilla’s legal_refs so the operator sees the BOE permalink that justifies the rule.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]