aeat.application.calculations._errors module

Typed exception hierarchy for the calculations application layer.

These exceptions are raised by previous-filing, binding-prefill, IVA compensation, and encrypted observation-repository services at the application boundary. Every class inherits from CoreError; validation failures use CoreValidationError so CLI and API callers receive registry-backed envelopes instead of generic ValueError or TypeError failures.

See also

application.calculations._binding_prefill:

Previous-filing binding readers that raise BindingPrefillTypeError.

application.calculations._iva_compensation_history:

Modelo 303 IVA compensation carry-forward readers that raise IvaCompensationModeloError.

application.calculations._observations_repository:

Encrypted observation storage that raises ObservationKeyError and ObservationCasillaReferenceError.

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

Bases: CoreError

Raised when a non-Modelo 303 observation is passed to IVA compensation history.

The IVA compensation carry-forward pipeline is exclusively sourced from Modelo 303 filed observations. Passing any other modelo to iva_compensation_state_from_filed_observation(), iva_compensation_state_from_registry_observation(), or iva_compensation_annual_summary_from_filed_observation() violates the calculation boundary contract.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: CoreValidationError

Raised when a binding selector field carries an unexpected runtime type.

Binding selectors flow through pydantic with a union value type, so static analysis loses the per-key shape. This error is raised by the selector narrowing helpers in application.calculations._binding_prefill. It protects resolve_bindings_from_local_store() from selector values that do not match the expected int | str or str | tuple[str, ...] shape.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: CoreValidationError

Raised when an observation key component fails its repository contract.

The repository key for a (modelo, filing_year, period) triple must satisfy safe_repository_id() for string components and fall within the supported year range [2000, 2099] for the integer year component. The key builders in application.calculations._observations_repository raise this error instead of a bare ValueError so failures propagate through the typed error registry and produce structured envelopes.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: CoreValidationError

Raised when a persisted filing observation names undeclared casillas.

CalculationObservationRepository is the encrypted calculation-history substrate for cross-period and cross-modelo reads. It must not persist a RegistryModeloObservation whose casilla keys are only syntactically valid CasillaId strings; every key must be declared by the resolved RegistrySnapshot for that modelo, year, and period via undeclared_casilla_ids().

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]