amir0907 commited on
Commit
bbb8345
·
verified ·
1 Parent(s): e0d5897

Upload env/portalocker/exceptions.py

Browse files
Files changed (1) hide show
  1. 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)