Upload env/portalocker/exceptions.py
Browse files- env/portalocker/exceptions.py +337 -0
env/portalocker/exceptions.py
ADDED
|
@@ -0,0 +1,337 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""Exceptions raised when acquiring, holding, or releasing a lock fails.
|
| 2 |
+
|
| 3 |
+
Hierarchy::
|
| 4 |
+
|
| 5 |
+
BaseLockException
|
| 6 |
+
LockException
|
| 7 |
+
AlreadyLocked
|
| 8 |
+
LockLostError
|
| 9 |
+
FileToLarge (deprecated, never raised)
|
| 10 |
+
|
| 11 |
+
`BaseLockException` is the shared base and is rarely raised directly;
|
| 12 |
+
catch `LockException` to handle any locking failure, `AlreadyLocked` to
|
| 13 |
+
handle contention specifically, or `LockLostError` to handle a
|
| 14 |
+
distributed lock that was revoked while held.
|
| 15 |
+
"""
|
| 16 |
+
|
| 17 |
+
import contextlib
|
| 18 |
+
import typing
|
| 19 |
+
import warnings
|
| 20 |
+
|
| 21 |
+
from . import types
|
| 22 |
+
|
| 23 |
+
|
| 24 |
+
class BaseLockException(Exception): # noqa: N818
|
| 25 |
+
"""Common base for every exception this module defines.
|
| 26 |
+
|
| 27 |
+
Not raised directly; `LockException` and its subclasses are. Beyond
|
| 28 |
+
the standard `Exception` payload, instances carry:
|
| 29 |
+
|
| 30 |
+
- `fh`: the filehandle (or file descriptor, or file-like object)
|
| 31 |
+
that was being locked when the failure happened, if one was
|
| 32 |
+
available yet. `None` when the failure happened before a handle
|
| 33 |
+
existed, e.g. while opening the file.
|
| 34 |
+
- `fh_name`: the name of that file as a plain string, when the
|
| 35 |
+
handle had one. `None` otherwise.
|
| 36 |
+
- `strerror`: the OS error message, when the failure came from a
|
| 37 |
+
system call. `None` otherwise.
|
| 38 |
+
|
| 39 |
+
Instances pickle, so they survive the trip out of a
|
| 40 |
+
`multiprocessing` worker back to the parent process. An open file
|
| 41 |
+
object cannot be pickled, so `fh` is dropped (replaced by `None`)
|
| 42 |
+
during pickling; `fh_name` still identifies the file afterwards, and
|
| 43 |
+
an integer file descriptor is kept as-is. This applies recursively
|
| 44 |
+
when one lock exception wraps another in its ``args``.
|
| 45 |
+
`copy.deepcopy` behaves like pickling and drops the handle too,
|
| 46 |
+
while `copy.copy` keeps `fh` shared with the original, since a
|
| 47 |
+
shallow copy never leaves the process where the handle is valid.
|
| 48 |
+
|
| 49 |
+
Example:
|
| 50 |
+
>>> from portalocker import exceptions
|
| 51 |
+
>>> try:
|
| 52 |
+
... raise exceptions.LockException(
|
| 53 |
+
... exceptions.LockException.LOCK_FAILED,
|
| 54 |
+
... 'Resource temporarily unavailable',
|
| 55 |
+
... )
|
| 56 |
+
... except exceptions.LockException as exc:
|
| 57 |
+
... exc.strerror
|
| 58 |
+
'Resource temporarily unavailable'
|
| 59 |
+
"""
|
| 60 |
+
|
| 61 |
+
LOCK_FAILED: typing.Final = 1
|
| 62 |
+
"""The only error code this package has ever raised.
|
| 63 |
+
|
| 64 |
+
The Windows lockers pass it as the first positional argument, with
|
| 65 |
+
the OS message second, so ``exc.args`` is ``(1, message)`` there. The
|
| 66 |
+
POSIX lockers put the original `OSError` in the first slot instead,
|
| 67 |
+
with ``str`` of it second, so code that inspects ``exc.args[0]``
|
| 68 |
+
sees this constant only on Windows. It does not distinguish between
|
| 69 |
+
causes and exists for backwards compatibility.
|
| 70 |
+
"""
|
| 71 |
+
|
| 72 |
+
strerror: str | None = None # ensure attribute always exists
|
| 73 |
+
|
| 74 |
+
fh_name: str | None = None
|
| 75 |
+
"""Name of the file behind `fh` as a plain string, when it had one.
|
| 76 |
+
|
| 77 |
+
Unlike `fh` itself, this survives pickling, so an exception that
|
| 78 |
+
crossed a process boundary still says which file was involved.
|
| 79 |
+
"""
|
| 80 |
+
|
| 81 |
+
def __init__(
|
| 82 |
+
self,
|
| 83 |
+
*args: typing.Any,
|
| 84 |
+
fh: types.IO | int | types.HasFileno | None = None,
|
| 85 |
+
**kwargs: typing.Any,
|
| 86 |
+
) -> None:
|
| 87 |
+
"""Store `fh` and extract `strerror` from `args[1]`.
|
| 88 |
+
|
| 89 |
+
Args:
|
| 90 |
+
*args: Forwarded to `Exception.__init__`. If a second
|
| 91 |
+
positional argument is present and is a `str`, it becomes
|
| 92 |
+
`strerror`; this mirrors the two-argument `OSError`
|
| 93 |
+
convention (an error code, then a message) so a locking
|
| 94 |
+
failure looks the same whether it originated on POSIX or
|
| 95 |
+
on Windows.
|
| 96 |
+
fh: The filehandle involved in the failure, if any. Stored
|
| 97 |
+
unchanged on `self.fh`.
|
| 98 |
+
**kwargs: Ignored here; accepted so that subclasses which add
|
| 99 |
+
their own keyword-only arguments (e.g. `AlreadyLocked`'s
|
| 100 |
+
`holder_pid`) can forward the rest of their keyword
|
| 101 |
+
arguments through `super().__init__(*args, **kwargs)`
|
| 102 |
+
without this initialiser rejecting them.
|
| 103 |
+
"""
|
| 104 |
+
self.fh = fh
|
| 105 |
+
# A broken handle may raise from its `name` property (a detached
|
| 106 |
+
# `io.TextIOWrapper` raises `ValueError`), which `getattr` with a
|
| 107 |
+
# default does not swallow. The name is a debugging nicety, so any
|
| 108 |
+
# failure to read it simply leaves `fh_name` as `None`.
|
| 109 |
+
name: typing.Any = None
|
| 110 |
+
with contextlib.suppress(Exception):
|
| 111 |
+
name = getattr(fh, 'name', None)
|
| 112 |
+
self.fh_name = name if isinstance(name, str) else None
|
| 113 |
+
self.strerror = (
|
| 114 |
+
str(args[1])
|
| 115 |
+
if len(args) > 1 and isinstance(args[1], str)
|
| 116 |
+
else None
|
| 117 |
+
)
|
| 118 |
+
Exception.__init__(self, *args)
|
| 119 |
+
|
| 120 |
+
def __reduce__(
|
| 121 |
+
self,
|
| 122 |
+
) -> tuple[
|
| 123 |
+
type['BaseLockException'],
|
| 124 |
+
tuple[typing.Any, ...],
|
| 125 |
+
dict[str, typing.Any],
|
| 126 |
+
]:
|
| 127 |
+
"""Pickle without the filehandle, which cannot be pickled.
|
| 128 |
+
|
| 129 |
+
`BaseException.__reduce__` includes the full instance ``__dict__``
|
| 130 |
+
in the pickle payload (and bypasses ``__getstate__``, which is
|
| 131 |
+
why this override targets ``__reduce__`` itself). With an open
|
| 132 |
+
file object on `fh` that made every lock exception unpicklable,
|
| 133 |
+
so a `multiprocessing` worker hitting contention crashed the
|
| 134 |
+
result pipe with a ``MaybeEncodingError`` instead of delivering
|
| 135 |
+
`AlreadyLocked` to the parent.
|
| 136 |
+
|
| 137 |
+
Returns:
|
| 138 |
+
The standard ``(callable, args, state)`` reduction triple:
|
| 139 |
+
the class, the ``args`` tuple, and a copy of the instance
|
| 140 |
+
dict in which a non-integer `fh` is replaced by `None`. An
|
| 141 |
+
integer file descriptor pickles fine and is kept, and
|
| 142 |
+
`fh_name` keeps identifying the file either way. Exceptions
|
| 143 |
+
nested inside ``args`` are reduced recursively by pickle
|
| 144 |
+
itself, so a wrapped lock exception sheds its own handle the
|
| 145 |
+
same way.
|
| 146 |
+
"""
|
| 147 |
+
state: dict[str, typing.Any] = dict(self.__dict__)
|
| 148 |
+
if state.get('fh') is not None and not isinstance(state['fh'], int):
|
| 149 |
+
state['fh'] = None
|
| 150 |
+
return (self.__class__, self.args, state)
|
| 151 |
+
|
| 152 |
+
def __copy__(self) -> 'BaseLockException':
|
| 153 |
+
"""Shallow-copy the exception, keeping the filehandle.
|
| 154 |
+
|
| 155 |
+
`copy.copy` falls back to ``__reduce_ex__`` when no ``__copy__``
|
| 156 |
+
is defined, and the pickle reduction above deliberately drops
|
| 157 |
+
`fh`. That is right for pickling and for `copy.deepcopy`, where
|
| 158 |
+
the handle would have to be serialised or duplicated, but a
|
| 159 |
+
shallow copy stays inside the process where the handle is still
|
| 160 |
+
perfectly usable, so dropping it there would lose information
|
| 161 |
+
for no safety gain. This override keeps `fh` shared between the
|
| 162 |
+
original and the copy, which is exactly what a shallow copy
|
| 163 |
+
means.
|
| 164 |
+
|
| 165 |
+
Returns:
|
| 166 |
+
A new instance of the same class with the same ``args`` and
|
| 167 |
+
a shallow copy of the instance attributes, `fh` included.
|
| 168 |
+
``__init__`` is bypassed, so copying a deprecated subclass
|
| 169 |
+
does not re-emit its construction warning.
|
| 170 |
+
"""
|
| 171 |
+
new_exception: BaseLockException = self.__class__.__new__(
|
| 172 |
+
self.__class__
|
| 173 |
+
)
|
| 174 |
+
new_exception.args = self.args
|
| 175 |
+
new_exception.__dict__.update(self.__dict__)
|
| 176 |
+
return new_exception
|
| 177 |
+
|
| 178 |
+
|
| 179 |
+
class LockException(BaseLockException):
|
| 180 |
+
"""Raised when acquiring or releasing a lock fails.
|
| 181 |
+
|
| 182 |
+
This is the general-purpose locking failure and the type to catch
|
| 183 |
+
when any locking error is acceptable to handle uniformly:
|
| 184 |
+
`AlreadyLocked` derives from it, so `except LockException` also
|
| 185 |
+
catches contention (as does the deprecated, never-raised
|
| 186 |
+
`FileToLarge`).
|
| 187 |
+
|
| 188 |
+
.. versionchanged:: 4.0.0
|
| 189 |
+
On POSIX, lock failures now populate `strerror` and pass the
|
| 190 |
+
OS error message as the second positional argument, matching the
|
| 191 |
+
contract this module already followed on Windows. The first
|
| 192 |
+
positional argument on POSIX stays the original `OSError`, where
|
| 193 |
+
Windows passes the `LOCK_FAILED` code. Previously, `str(exc)` on
|
| 194 |
+
POSIX returned the bare underlying `OSError` text; it now
|
| 195 |
+
returns the 2-argument exception repr instead, for example
|
| 196 |
+
``(BlockingIOError(11, 'Resource temporarily unavailable'),
|
| 197 |
+
'[Errno 11] Resource temporarily unavailable')``. Code that
|
| 198 |
+
parsed `str(exc)` on POSIX should read `.strerror` instead, which
|
| 199 |
+
has held the message consistently on both platforms since 4.0.0.
|
| 200 |
+
"""
|
| 201 |
+
|
| 202 |
+
|
| 203 |
+
class AlreadyLocked(LockException):
|
| 204 |
+
"""Raised when a lock is held elsewhere and cannot be acquired.
|
| 205 |
+
|
| 206 |
+
This is what `Lock.acquire` raises immediately when
|
| 207 |
+
`fail_when_locked=True` and the first attempt finds the lock already
|
| 208 |
+
held, and also what it raises when `timeout` expires while waiting
|
| 209 |
+
for the lock to become free.
|
| 210 |
+
"""
|
| 211 |
+
|
| 212 |
+
holder_pid: int | None = None
|
| 213 |
+
"""The PID of the process already holding the lock, when known.
|
| 214 |
+
|
| 215 |
+
`None` unless a caller has populated it explicitly; acquiring a lock
|
| 216 |
+
does not discover or fill this in by itself.
|
| 217 |
+
"""
|
| 218 |
+
|
| 219 |
+
def __init__(
|
| 220 |
+
self,
|
| 221 |
+
*args: typing.Any,
|
| 222 |
+
holder_pid: int | None = None,
|
| 223 |
+
**kwargs: typing.Any,
|
| 224 |
+
) -> None:
|
| 225 |
+
"""Initialise like `BaseLockException`, plus record `holder_pid`.
|
| 226 |
+
|
| 227 |
+
Args:
|
| 228 |
+
*args: Forwarded to `BaseLockException.__init__`.
|
| 229 |
+
holder_pid: The PID of the process already holding the lock,
|
| 230 |
+
if known. Stored on `self.holder_pid`; unlike `fh` and
|
| 231 |
+
`strerror`, `BaseLockException` has no equivalent
|
| 232 |
+
attribute, so this is the one addition `AlreadyLocked`
|
| 233 |
+
makes over its base initialiser.
|
| 234 |
+
**kwargs: Forwarded to `BaseLockException.__init__`.
|
| 235 |
+
"""
|
| 236 |
+
super().__init__(*args, **kwargs)
|
| 237 |
+
self.holder_pid = holder_pid
|
| 238 |
+
|
| 239 |
+
|
| 240 |
+
class LockLostError(LockException):
|
| 241 |
+
"""Raised when a lock that was successfully acquired is lost again.
|
| 242 |
+
|
| 243 |
+
`portalocker.RedisLock` keeps its lock in a live pubsub
|
| 244 |
+
subscription, so the lock can be revoked from outside the holding
|
| 245 |
+
process: a severed network connection, a ``CLIENT KILL`` issued by
|
| 246 |
+
an administrator, or a reap by another contender that saw this
|
| 247 |
+
holder stop answering pings. This exception is how that revocation
|
| 248 |
+
reaches the code that thought it still held the lock. It is raised
|
| 249 |
+
by `portalocker.RedisLock.ensure_held` and by the ``with`` block
|
| 250 |
+
exit of a lock that was lost while the block ran; the underlying
|
| 251 |
+
cause (usually a ``redis.exceptions.ConnectionError``) is attached
|
| 252 |
+
as ``__cause__``.
|
| 253 |
+
|
| 254 |
+
Beyond the `LockException` payload, instances carry `channel` and
|
| 255 |
+
`holder_id` so a handler that manages several locks can tell which
|
| 256 |
+
one died.
|
| 257 |
+
|
| 258 |
+
Example:
|
| 259 |
+
>>> from portalocker import exceptions
|
| 260 |
+
>>> error = exceptions.LockLostError(
|
| 261 |
+
... exceptions.LockException.LOCK_FAILED,
|
| 262 |
+
... 'lock lost',
|
| 263 |
+
... channel='jobs',
|
| 264 |
+
... holder_id='a1b2',
|
| 265 |
+
... )
|
| 266 |
+
>>> error.channel, error.holder_id
|
| 267 |
+
('jobs', 'a1b2')
|
| 268 |
+
|
| 269 |
+
.. versionadded:: 4.2.0
|
| 270 |
+
"""
|
| 271 |
+
|
| 272 |
+
channel: str | None = None
|
| 273 |
+
"""The pubsub channel the lost lock lived on, when known."""
|
| 274 |
+
|
| 275 |
+
holder_id: str | None = None
|
| 276 |
+
"""The `RedisLock.holder_id` of the holder that lost the lock."""
|
| 277 |
+
|
| 278 |
+
def __init__(
|
| 279 |
+
self,
|
| 280 |
+
*args: typing.Any,
|
| 281 |
+
channel: str | None = None,
|
| 282 |
+
holder_id: str | None = None,
|
| 283 |
+
**kwargs: typing.Any,
|
| 284 |
+
) -> None:
|
| 285 |
+
"""Initialise like `LockException`, plus record the lock identity.
|
| 286 |
+
|
| 287 |
+
Args:
|
| 288 |
+
*args: Forwarded to `LockException.__init__`.
|
| 289 |
+
channel: The pubsub channel the lost lock lived on. Stored
|
| 290 |
+
on `self.channel`.
|
| 291 |
+
holder_id: The holder id of the lock instance that lost the
|
| 292 |
+
lock. Stored on `self.holder_id`.
|
| 293 |
+
**kwargs: Forwarded to `LockException.__init__`.
|
| 294 |
+
"""
|
| 295 |
+
super().__init__(*args, **kwargs)
|
| 296 |
+
self.channel = channel
|
| 297 |
+
self.holder_id = holder_id
|
| 298 |
+
|
| 299 |
+
|
| 300 |
+
class FileToLarge(LockException):
|
| 301 |
+
"""Deprecated and never raised; kept only for backwards compatibility.
|
| 302 |
+
|
| 303 |
+
No version of this package has ever raised it: it was defined for a
|
| 304 |
+
file-too-large failure mode that the locking backends never
|
| 305 |
+
reported. Code catching it catches nothing, so it is deprecated and
|
| 306 |
+
instantiating it emits a `DeprecationWarning`. Catch `LockException`
|
| 307 |
+
instead.
|
| 308 |
+
|
| 309 |
+
The misspelling in the name (`FileToLarge`, rather than
|
| 310 |
+
`FileTooLarge`) is a long-standing typo in the public API. It is kept
|
| 311 |
+
exactly as-is instead of being silently renamed, which would break
|
| 312 |
+
`except FileToLarge` in existing code.
|
| 313 |
+
|
| 314 |
+
.. deprecated:: 4.2.0
|
| 315 |
+
Will be removed in a future major release.
|
| 316 |
+
"""
|
| 317 |
+
|
| 318 |
+
def __init__(self, *args: typing.Any, **kwargs: typing.Any) -> None:
|
| 319 |
+
"""Initialise like `LockException`, plus warn about deprecation.
|
| 320 |
+
|
| 321 |
+
Args:
|
| 322 |
+
*args: Forwarded to `LockException.__init__`.
|
| 323 |
+
**kwargs: Forwarded to `LockException.__init__`.
|
| 324 |
+
|
| 325 |
+
Warns:
|
| 326 |
+
DeprecationWarning: Always. The warning points at the caller
|
| 327 |
+
(``stacklevel=2``) so the deprecated construction site
|
| 328 |
+
shows up in the report, not this initialiser.
|
| 329 |
+
"""
|
| 330 |
+
warnings.warn(
|
| 331 |
+
'FileToLarge is deprecated: portalocker has never raised it '
|
| 332 |
+
'and it will be removed in a future major release. Catch '
|
| 333 |
+
'LockException instead.',
|
| 334 |
+
DeprecationWarning,
|
| 335 |
+
stacklevel=2,
|
| 336 |
+
)
|
| 337 |
+
super().__init__(*args, **kwargs)
|