aeat.adapters.persistence.storage.bucket._errors module

Typed exception hierarchy for the per-bucket directory model.

Each class carries a structured payload (active bucket id, holding PID, conflicting bucket id, recovery context) so callers can render typed diagnostics without re-parsing the message string. Every class inherits from core.errors.AeatError; the project error registry’s __init_subclass__ hook binds each subclass to its declared core.errors.ErrorCode row at import time.

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

Bases: SecureStorageError

Base class for every per-bucket lifecycle error.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: BucketError

Raised when a bucket parameter or manifest field fails validation.

Parameters:

  • message (str | None)

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

Return type:

None

code: ClassVar[ErrorCode]
exception NoActiveBucketError(detail=None)[source]

Bases: BucketError

Raised when no active bucket can be resolved.

The precedence chain is exhausted (no --bucket flag, no AEAT_ACTIVE_BUCKET env, no pointer file), and the process refuses to proceed.

Parameters:

detail (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception BucketBusyError(*, bucket_id, holding_pid)[source]

Bases: BucketError

Raised when a second process attempts to unlock a held bucket.

Carries the holding PID so the caller can render the diagnostic without re-parsing the lockfile.

Parameters:

  • bucket_id (str)

  • holding_pid (int)

Return type:

None

code: ClassVar[ErrorCode]
exception BucketAlreadyPresentError(*, bucket_id)[source]

Bases: BucketError

Raised when an import would collide with an existing bucket id.

Carries the conflicting bucket id.

Parameters:

bucket_id (str)

Return type:

None

code: ClassVar[ErrorCode]
exception BucketPathTooLongError(*, bucket_id, path)[source]

Bases: BucketError

Raised when provisioning a bucket directory exceeds the Windows MAX_PATH ceiling.

Classified via core.paths.is_windows_long_path_error() from a caught WinError 3 / WinError 206 on legacy (non long-path-aware) Windows workstations. Distinct from BucketValidationError so the CLI names the actual cause (the resolved bucket directory tree is too deep for MAX_PATH) instead of a generic validation failure.

Parameters:
Return type:

None

code: ClassVar[ErrorCode]
exception BucketLockedError(*, bucket_id)[source]

Bases: BucketError

Raised when an operation requires an unlocked BucketSession.

Carries the locked bucket id so the diagnostic can point the operator at aeat config switch NAME.

Parameters:

bucket_id (str)

Return type:

None

code: ClassVar[ErrorCode]
exception RecoveryUnavailableError(*, bucket_id)[source]

Bases: BucketError

Raised when the recovery wrap cannot be loaded for the active bucket.

Distinguishes “recovery never enrolled” (the bucket’s manifest has recovery_enrolled = false) from a torn or tampered envelope; the typed payload carries the active bucket id.

Parameters:

bucket_id (str)

Return type:

None

code: ClassVar[ErrorCode]
exception RecoveryVerificationError(detail=None)[source]

Bases: BucketError

Raised when the operator-typed recovery code does not decode.

Fired by aeat config recover when the 24-word entry does not unwrap the bucket’s recovery envelope.

Parameters:

detail (str | None)

Return type:

None

code: ClassVar[ErrorCode]