Skip to content

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

InvalidArgumentError(reason: str)

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

InvalidTtlError(ttl: float)

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

LockAcquiringError(resource: str, reason: str)

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

LockConflictedError(resource: str)

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

LockExpiredError(resource: str)

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

LockReleasingError(resource: str, reason: str)

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:

  • resource (str) –

    The resource the lock is for.

  • reason (str) –

    What went wrong.

Record the resource and what went wrong.

LockStorageError

LockStorageError(reason: str)

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

UnserializableKeyError(resource: str)

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.