cadrumo.adapters.persistence.storage.bucket.errors module

Canonical 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.hierarchy.CadrumoError; the project error registry’s __init_subclass__ hook binds each subclass to its declared core.errors.error_codes.ErrorCode row at import time.

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

Bases: SecureStorageError

Base class for every per-bucket lifecycle error.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

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

Bases: BucketError

Raised when a bucket parameter fails validation.

Parameters:

  • message (str | None)

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

Return type:

None

code
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
exception BucketAlreadyPresentError(*, bucket_id)[source]

Bases: BucketError

Raised when provisioning would collide with an existing bucket id.

Carries the conflicting bucket id.

Parameters:

bucket_id (str)

Return type:

None

code
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
exception BucketLockedError(*, bucket_id)[source]

Bases: BucketError

Raised when an operation requires an unlocked BucketSession.

Carries the storage identity and the failed unlocked-state observation. Recovery policy belongs to the boundary because a bucket id is not a verified public profile-action argument.

Parameters:

bucket_id (str)

Return type:

None

code