xtr_storage.exception ¶
Every error this library raises.
All of them derive from :class:StorageError, so one except catches
anything storing a file can go wrong with, and a narrower one handles a single
cause. The failures of an operation a backend refused share
:class:StorageOperationFailedError and name that operation, which is the
clause a retry belongs in; everything else — a path that is not a path, a
capability a backend does not have, a package that is not installed — is a
mistake to fix rather than to retry.
Each carries the data a caller needs as typed attributes rather than forcing a message to be parsed, and no message ever repeats a credential.
ChecksumAlgorithmNotSupportedError ¶
Bases: UnableToProvideChecksumError
The backend keeps checksums, but not in the algorithm that was asked for.
An object store hands out the digests it happens to hold — an entity tag, an MD5 it recorded on upload — and nothing else. A storage treats this as "ask me differently", not as a failure: it reads the file and computes the digest itself. It surfaces only when a caller went to the backend directly.
Attributes:
-
location(str) –The path a checksum was wanted for, as the caller gave it.
-
algorithm(str) –The algorithm that was asked for.
-
reason(str) –Why there is none.
Record the path and the algorithm the backend does not keep.
CorruptedPathDetectedError ¶
Bases: StorageError
A path held a control or formatting character.
Anything Unicode files under "other" — a null byte, an escape, a zero-width joiner — is refused rather than passed on. Such a character survives a comparison but not a filesystem, a url or a log line, so a path holding one means two names that look identical and are not.
Attributes:
-
path(str) –The path that was refused, as the caller gave it.
Record the path that cannot be used.
FeatureNotSupportedError ¶
Bases: StorageError, NotImplementedError
The backend behind this adapter has no such capability.
Kept apart from every operation failure on purpose: a failed operation may work next time, this one never will. It says "configure something else", not "try again" — so a retry loop catching operation failures leaves it alone, and a caller that can do without the capability catches this one class and goes on.
Also a :class:NotImplementedError, which is what an implementation that
does not implement something raises.
Attributes:
-
feature(Feature) –The capability that is missing.
-
adapter(str) –The name of the adapter class that does not have it.
Record which capability is missing from which adapter.
InvalidArgumentError ¶
Bases: StorageError, ValueError
A storage, an adapter or a generator was given an argument it cannot use.
Raised where the argument is given — an empty prefix, a checksum algorithm this machine does not have, an expiry without a time zone — rather than on the first attempt to reach a backend.
Also a :class:ValueError, so code that already guards its configuration
with except ValueError keeps working without learning a new exception.
Attributes:
-
reason(str) –What is wrong with the argument.
Record what is wrong with the argument.
InvalidStreamError ¶
Bases: StorageError, TypeError
A write was given contents it cannot stream.
A stream is bytes arriving in pieces — an async iterable, a plain iterable or an open binary file. Text is not one: it would have to be encoded, and guessing which encoding is how files end up unreadable. The caller encodes and hands in bytes.
Also a :class:TypeError, because that is what handing in the wrong kind
of thing is.
Attributes:
-
received(str) –The name of the type that was handed in.
Record what was handed in instead of a stream.
InvalidVisibilityError ¶
Bases: StorageError, ValueError
A value was handed in as a visibility and is not one.
Visibility travels as a plain string through configuration files and request bodies, so it is parsed on the way in and anything unknown is refused there — before an adapter turns it into permissions or an access policy it cannot take back.
Also a :class:ValueError, so code already guarding its configuration
with except ValueError keeps working.
Attributes:
-
visibility(str) –The value that was refused.
Record the value that is not a visibility.
MissingBackendError ¶
Bases: StorageError, ImportError
The package this adapter talks to its backend through is not installed.
Backends live behind extras so an application installs only the ones it reaches. An adapter imports its package the first time it is used, and turns a failed import into this — an error naming the extra to install, rather than a traceback about a module nobody asked for.
Also an :class:ImportError, so it reads as what it is.
Attributes:
-
package(str) –The package that is missing.
-
extra(str) –The extra of this distribution that installs it.
Record the missing package and the extra that brings it.
PathTraversalDetectedError ¶
Bases: StorageError
A path walked up past the root of the storage.
Every path is resolved before it reaches a backend, and one whose ..
segments take it above the root is refused there — a storage answers for
what it holds and for nothing beside it. A storage may also refuse ..
outright, which raises this for any path carrying one.
Attributes:
-
path(str) –The path that was refused, as the caller gave it.
Record the path that climbed out.
StorageError ¶
Bases: Exception
Base class for every error raised by this library.
Catch this to handle anything storing a file can go wrong with; catch a subclass to handle one cause. Every subclass carries the data a caller needs as typed attributes and composes its own message from them, so nothing has to be parsed back out of a string.
A message is built from paths and from the reason the backend gave. It never carries a key, a token or a connection string: an error travels into logs and responses, and credentials must not travel with it.
StorageOperationFailedError ¶
Bases: StorageError
Something a storage was asked to do failed; the operation says what.
This is the line between "the backend refused this attempt" and every
other kind of error — a path that is not a path, a feature the backend
does not have, an argument that makes no sense. Code that retries, or that
turns a failure into a response, catches this one class and reads
:attr:operation rather than listing every subclass.
Whatever the backend raised is chained as __cause__.
Attributes:
-
operation(Operation) –What was being attempted. Every concrete subclass sets it; reading it off this class itself raises :class:
AttributeError, which is how a subclass that forgot to set it is found.
SymbolicLinkEncounteredError ¶
Bases: StorageError
A listing ran into a symbolic link and was told to refuse them.
A link can point anywhere, including outside the storage, so following one would quietly hand out what the storage does not hold. An adapter that meets one either skips it or raises this, depending on how it was built.
Attributes:
-
location(str) –The link that was met, as the storage names it.
Record the link that was refused.
UnableToCheckDirectoryExistenceError ¶
Bases: UnableToCheckExistenceError
Asking whether a directory is there failed.
The class name is what tells a reader a directory was being looked for; the message stays the same as its parent's so the two read alike in a log.
Attributes:
-
location(str) –The path that was checked, as the caller gave it.
UnableToCheckExistenceError ¶
Bases: StorageOperationFailedError
Asking whether a path is there failed.
Not an answer of "no": the backend could not be asked at all. The two subclasses say whether a file or a directory was being looked for, and this class catches both.
Attributes:
-
location(str) –The path that was checked, as the caller gave it.
Record the path that could not be checked.
UnableToCheckFileExistenceError ¶
Bases: UnableToCheckExistenceError
Asking whether a file is there failed.
The class name is what tells a reader a file was being looked for; the message stays the same as its parent's so the two read alike in a log.
Attributes:
-
location(str) –The path that was checked, as the caller gave it.
UnableToCopyFileError ¶
Bases: StorageOperationFailedError
Copying a file failed; the destination may be half-written.
A copy across backends is a read streamed into a write, so a failure part way through leaves whatever reached the destination. The source is never touched.
Attributes:
-
source(str) –The path that was copied from, as the caller gave it.
-
destination(str) –The path that was copied to, as the caller gave it.
-
reason(str) –What the backend said, empty when it said nothing.
Record both paths and why the copy failed.
UnableToCreateDirectoryError ¶
Bases: StorageOperationFailedError
Creating a directory failed.
Attributes:
-
location(str) –The directory that was created, as the caller gave it.
-
reason(str) –What the backend said, empty when it said nothing.
Record the directory and why creating it failed.
UnableToDeleteDirectoryError ¶
Bases: StorageOperationFailedError
Deleting a directory and everything under it failed.
The deletion is not atomic anywhere: part of the tree may be gone. A caller that must end up with nothing there deletes again rather than assuming either outcome.
Attributes:
-
location(str) –The directory that was deleted, as the caller gave it.
-
reason(str) –What the backend said, empty when it said nothing.
Record the directory and why deleting it failed.
UnableToDeleteFileError ¶
Bases: StorageOperationFailedError
Deleting a file failed while the file was there.
Deleting what is not there is not a failure: a delete asks for the file to be gone, and it is. This is raised only when the backend refused.
Attributes:
-
location(str) –The path that was deleted, as the caller gave it.
-
reason(str) –What the backend said, empty when it said nothing.
Record the path and why deleting it failed.
UnableToGeneratePublicUrlError ¶
Bases: StorageError
A file has no address anyone can fetch it from.
Usually configuration rather than breakage: nothing told the storage what its files are served under, and the backend does not know either. A chain of generators raises this once every one of them has declined.
Attributes:
-
location(str) –The path a url was wanted for, as the caller gave it.
-
reason(str) –Why there is none, empty when nothing more is known.
Record the path and why it has no public url.
UnableToGenerateTemporaryUrlError ¶
Bases: StorageError
A file has no address that lets the bearer fetch it until a deadline.
A backend signs such a url with the credentials it holds, so this covers both "this backend does not sign" and "signing failed". The message never repeats what was signed with.
Attributes:
-
location(str) –The path a url was wanted for, as the caller gave it.
-
reason(str) –Why there is none, empty when nothing more is known.
Record the path and why it has no temporary url.
UnableToListContentsError ¶
Bases: StorageOperationFailedError
Listing a directory failed, at its start or part way through.
A listing is lazy, so this can surface on any step of the iteration, not
only on the call that asked for it. :attr:deep is carried because a
shallow listing and a deep one are different requests to the backend and
fail for different reasons.
Attributes:
-
location(str) –The directory that was listed, as the caller gave it.
-
deep(bool) –Whether everything below it was being listed too.
Record the directory and how far the listing reached.
UnableToMoveFileError ¶
Bases: StorageOperationFailedError
Moving a file failed; the source may still be there.
A move across backends is a copy followed by a delete, so a failure can leave the file in both places or in neither. The error names both paths for that reason: which one to look at depends on where it stopped.
Attributes:
-
source(str) –The path that was moved from, as the caller gave it.
-
destination(str) –The path that was moved to, as the caller gave it.
-
reason(str) –What the backend said, empty when it said nothing.
Record both paths and why the move failed.
UnableToProvideChecksumError ¶
Bases: StorageError
A file's checksum could neither be read from the backend nor computed.
Not an operation failure: a checksum is a capability, and a storage that cannot get one from the backend falls back to reading the file and hashing it. This is what is left when that fails too.
Attributes:
-
location(str) –The path a checksum was wanted for, as the caller gave it.
-
reason(str) –Why there is none, empty when nothing more is known.
Record the path and why no checksum could be produced.
UnableToReadFileError ¶
Bases: StorageOperationFailedError
A file could not be read: it is not there, or the backend refused.
Missing and unreadable are one error on purpose. An object store answers
both the same way, so a caller that wants to know whether a file is there
asks file_exists rather than reading it and reading the failure.
Attributes:
-
location(str) –The path that was read, as the caller gave it.
-
reason(str) –What the backend said, empty when it said nothing.
Record the path and why reading it failed.
UnableToResolveMountError ¶
Bases: StorageError
A location could not be routed to one of the mounted storages.
Raised before anything is attempted: the location carries no mount name, carries an empty one, or names a storage nothing was mounted under. It is a mistake in the location, not a failure of the storage behind it, which is why it is not one of the operation failures.
Attributes:
-
location(str) –The location that was routed, as the caller gave it.
-
reason(str) –What is wrong with it.
Record the location and why it routes nowhere.
UnableToRetrieveMetadataError ¶
Bases: StorageOperationFailedError
A file's size, type, visibility or last write could not be read.
One error for all four, with :attr:metadata_type saying which: they fail
together — a missing file has none of them — and a caller asking for two
would otherwise catch two exception types for one cause. The classmethods
build each kind, so no call site has to spell the name.
Attributes:
-
location(str) –The path the metadata was read for, as the caller gave it.
-
metadata_type(str) –Which piece was asked for —
last_modified,visibility,file_sizeormime_type. -
reason(str) –What the backend said, empty when it said nothing.
Record the path, what was asked for, and why it could not be read.
last_modified
classmethod
¶
Build the failure for the moment a file was last written.
visibility
classmethod
¶
Build the failure for who may read a file.
file_size
classmethod
¶
Build the failure for how many bytes a file holds.
mime_type
classmethod
¶
Build the failure for what kind of content a file holds.
UnableToSetVisibilityError ¶
Bases: StorageOperationFailedError
Changing who may read a file or a directory failed.
A backend that has no notion of visibility at all raises
:class:~xtr_storage.exception.FeatureNotSupportedError instead: this one
means the backend has it and the attempt failed.
Attributes:
-
location(str) –The path whose visibility was set, as the caller gave it.
-
reason(str) –What the backend said, empty when it said nothing.
Record the path and why its visibility could not be set.
UnableToWriteFileError ¶
Bases: StorageOperationFailedError
Writing a file failed, whether or not anything was written.
A backend that fails midway may leave a partial object behind; the error says where to look, not what survived, because only the backend knows.
Attributes:
-
location(str) –The path that was written to, as the caller gave it.
-
reason(str) –What the backend said, empty when it said nothing.
Record the path and why writing it failed.