xtr_lock.exception ¶
Every error this library raises.
All of them derive from :class:LockError, so one except catches
anything a lock can go wrong with, and a narrower one handles a single
cause. Each carries the data a caller needs as typed attributes rather than
forcing a message to be parsed.
InvalidArgumentError ¶
Bases: LockError, ValueError
A lock, a store or a factory was given an argument it cannot work with.
Raised where the argument is given — a lock directory that cannot be written, a connection no store knows, a refresh with no duration — rather than on the first attempt to lock.
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.
InvalidTtlError ¶
Bases: InvalidArgumentError
A store was given a lifetime it cannot keep a lock for.
A store whose locks expire on their own needs a lifetime greater than zero: a lock that expires the moment it is taken protects nothing.
Attributes:
-
ttl(float) –The lifetime, in seconds, that was refused.
Record the lifetime that was refused.
LockAcquiringError ¶
Bases: LockError, RuntimeError
Acquiring a lock, or extending one, failed for a reason other than contention.
The store could not be reached, or answered with an error. The underlying
error is chained as __cause__. Contention is not a failure of this
kind: a lock someone else holds is
:class:~xtr_lock.exception.LockConflictedError, and a lock whose
lifetime ran out before the store confirmed it is
:class:~xtr_lock.exception.LockExpiredError.
Attributes:
-
resource(str) –The resource the lock is for.
-
reason(str) –What was being attempted when it failed.
Record the resource and what was being attempted.
LockConflictedError ¶
Bases: LockError, RuntimeError
Someone else holds the lock.
The one signal a store gives for contention. A non-blocking
:meth:~xtr_lock.lock.Lock.acquire turns it into False; a blocking
one waits it out; :meth:~xtr_lock.lock.Lock.refresh lets it through,
since a lock that can no longer be extended has been lost.
Attributes:
-
resource(str) –The resource someone else holds.
Record the resource someone else holds.
LockError ¶
Bases: Exception
Base class for every error raised by this library.
Catch this to handle anything locking 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.
LockExpiredError ¶
Bases: LockError, RuntimeError
A lock's lifetime ran out before the store confirmed it.
Storing the lock took longer than the lock was meant to live — a slow network, several stores in a row — so by the time it was stored it had already expired. The store has been asked to forget it again.
Attributes:
-
resource(str) –The resource the lock is for.
Record the resource whose lock expired.
LockReleasingError ¶
Bases: LockError, RuntimeError
Releasing a lock failed, or the lock was still there afterwards.
A store's delete can fail outright — the underlying error is then
chained as __cause__ — or appear to succeed while the lock remains,
which is checked for rather than trusted.
Attributes:
Record the resource and what went wrong.
LockStorageError ¶
Bases: LockError, RuntimeError
The storage behind a store failed.
Not a question of who holds the lock: the lock file could not be opened,
the server answered a command with an error. Whatever the storage said is
kept in :attr:reason, and its own error, when there is one, is chained
as __cause__.
Attributes:
-
reason(str) –What the storage reported.
Record what the storage reported.
UnserializableKeyError ¶
Bases: LockError, RuntimeError
A key holding something that cannot leave the process was pickled.
Some stores keep an operating system handle on the key — an open file descriptor, for one — which means nothing to another process. Once such a store has touched a key, the key refuses to be pickled rather than arrive somewhere else claiming a lock it cannot hold.
Attributes:
-
resource(str) –The resource the key is for.
Record the resource the key is for.