Error handling

file-keeper provides a comprehensive set of exceptions to help you handle errors gracefully. This page documents the available exceptions and provides guidance on how to handle them.

General exception hierarchy

All exceptions in file-keeper inherit from the base FilesError exception. This allows you to catch all file-keeper related errors with a single except block. More specific exceptions are derived from FilesError to provide more detailed error information.

Note

file-keeper's exceptions can be imported from file_keeper.core.exceptions

from file_keeper.core.exceptions import FilesError

try:
    ...
except FilesError:
    ...

As a shortcut, they can be accessed from the exc object available at the root of file-keeper module

from file_keeper import exc

try:
    ...
except exc.FilesError:
    ...

Example error handling

from file_keeper import make_storage, make_upload, exc

try:
    storage = make_storage("my_storage", {"type": "file_keeper:fs", "path": "/nonexistent/path"})
except exc.InvalidStorageConfigurationError as e:
    print(f"Error configuring storage: {e}")

upload = make_upload(b"Hello, file-keeper!")

try:
    storage.upload("my_file.txt", upload)
except exc.ExistingFileError as e:
    print(f"File already exists: {e}")

`exc`

Exception definitions for the extension.

Hierarchy:

Exception
- FilesError
  - StorageError

`ContentError(storage, msg)`

Bases: UploadError

Storage cannot accept uploaded content.

`ExistingFileError(storage, location)`

Bases: LocationError

File already exists.

`ExtrasError(problem)`

Bases: StorageError

Wrong extras passed to storage method.

`FilesError`

Bases: Exception

Base error for catch-all scenario.

`InvalidStorageConfigurationError(adapter_or_storage, problem)`

Bases: StorageError

Storage cannot be initialized with given configuration.

`LargeUploadError(actual_size, max_size)`

Bases: UploadError

Planned upload exceeds allowed size.

`LocationError(storage, location)`

Bases: StorageError

Storage cannot use given location.

`LocationTransformerError(transformer)`

Bases: UploadError

Undefined location transformer.

`MissingExtrasError(key)`

Bases: ExtrasError

Expected extras are missing from the call.

`MissingFileError(storage, location)`

Bases: LocationError

File does not exist.

`MissingStorageConfigurationError(adapter_or_storage, option)`

Bases: InvalidStorageConfigurationError

Storage cannot be initialized due to missing option.

`MultipartUploadError`

Bases: UploadError

Error related to multipart upload process.

`PermissionError(storage, operation, problem)`

Bases: StorageError

Storage client does not have required permissions.

`ResumableUploadError`

Bases: UploadError

Error related to resumable upload process.

`StorageDataError(problem)`

Bases: StorageError

Wrong storage_data used for operation.

`StorageError`

Bases: FilesError

Error related to storage.

`UnknownAdapterError(adapter)`

Bases: StorageError

Specified storage adapter is not registered.

`UnknownStorageError(storage)`

Bases: StorageError

Storage with the given name is not configured.

`UnsupportedOperationError(operation, storage)`

Bases: StorageError

Requested operation is not supported by storage.

`UploadError`

Bases: StorageError

Error related to file upload process.

`UploadHashMismatchError(actual, expected)`

Bases: UploadMismatchError

Expected value of hash match the actual value.

`UploadMismatchError(attribute, actual, expected)`

Bases: UploadError

Expected value of file attribute doesn't match the actual value.

`UploadOutOfBoundError(actual_size, max_size)`

Bases: LargeUploadError

Ongoing upload exceeds expected size.

`UploadSizeMismatchError(actual, expected)`

Bases: UploadMismatchError

Expected value of upload size doesn't match the actual value.

`UploadTypeMismatchError(actual, expected)`

Bases: UploadMismatchError

Expected value of content type doesn't match the actual value.

`WrongUploadTypeError(content_type)`

Bases: UploadError

Storage does not support given MIMEType.