Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/filelock/_api.py: 69%

1from __future__ import annotations 

2 

3import contextlib 

4import inspect 

5import logging 

6import os 

7import sys 

8import time 

9import warnings 

10from abc import ABCMeta, abstractmethod 

11from dataclasses import dataclass 

12from threading import Lock, local 

13from typing import TYPE_CHECKING, Any, TypeVar 

14from weakref import WeakValueDictionary 

15 

16from ._error import Timeout 

17from ._util import break_lock_file 

18 

19#: Sentinel indicating that no explicit file permission mode was passed. 

20#: When used, lock files are created with 0o666 (letting umask and default ACLs control the final permissions) 

21#: and fchmod is skipped so that POSIX default ACL inheritance is preserved. 

22_UNSET_FILE_MODE: int = -1 

23 

24if TYPE_CHECKING: 

25 from collections.abc import Callable 

26 from types import TracebackType 

27 

28 from ._read_write import ReadWriteLock 

29 from ._soft_rw import SoftReadWriteLock 

30 

31 if sys.version_info >= (3, 11): # pragma: no cover (py311+) 

32 from typing import Self 

33 else: # pragma: no cover (<py311) 

34 from typing_extensions import Self 

35 

36 

37_LOGGER = logging.getLogger("filelock") 

38 

39# On Windows os.path.realpath calls CreateFileW with share_mode=0, which blocks concurrent DeleteFileW and causes 

40# livelocks under threaded contention with SoftFileLock. os.path.abspath is purely string-based and avoids this. 

41_canonical = os.path.abspath if sys.platform == "win32" else os.path.realpath 

42 

43 

44class _ThreadLocalRegistry(local): 

45 def __init__(self) -> None: 

46 super().__init__() 

47 self.held: dict[str, int] = {} 

48 

49 

50_registry = _ThreadLocalRegistry() 

51 

52 

53# This is a helper class which is returned by :meth:`BaseFileLock.acquire` and wraps the lock to make sure __enter__ 

54# is not called twice when entering the with statement. If we would simply return *self*, the lock would be acquired 

55# again in the *__enter__* method of the BaseFileLock, but not released again automatically. issue #37 (memory leak) 

56class AcquireReturnProxy: 

57 """A context-aware object that will release the lock file when exiting.""" 

58 

59 def __init__(self, lock: BaseFileLock | ReadWriteLock | SoftReadWriteLock) -> None: 

60 self.lock: BaseFileLock | ReadWriteLock | SoftReadWriteLock = lock 

61 

62 def __enter__(self) -> BaseFileLock | ReadWriteLock | SoftReadWriteLock: 

63 return self.lock 

64 

65 def __exit__( 

66 self, 

67 exc_type: type[BaseException] | None, 

68 exc_value: BaseException | None, 

69 traceback: TracebackType | None, 

70 ) -> None: 

71 self.lock.release() 

72 

73 

74@dataclass 

75class FileLockContext: 

76 """A dataclass which holds the context for a ``BaseFileLock`` object.""" 

77 

78 # The context is held in a separate class to allow optional use of thread local storage via the 

79 # ThreadLocalFileContext class. 

80 

81 #: The path to the lock file. 

82 lock_file: str 

83 

84 #: The default timeout value. 

85 timeout: float 

86 

87 #: The mode for the lock files 

88 mode: int 

89 

90 #: Whether the lock should be blocking or not 

91 blocking: bool 

92 

93 #: The default polling interval value. 

94 poll_interval: float 

95 

96 #: The lock lifetime in seconds; ``None`` means the lock never expires. 

97 lifetime: float | None = None 

98 

99 #: The file descriptor for the *_lock_file* as it is returned by the os.open() function, not None when lock held 

100 lock_file_fd: int | None = None 

101 

102 #: The lock counter is used for implementing the nested locking mechanism. 

103 lock_counter: int = 0 # When the lock is acquired is increased and the lock is only released, when this value is 0 

104 

105 

106class ThreadLocalFileContext(FileLockContext, local): 

107 """A thread local version of the ``FileLockContext`` class.""" 

108 

109 

110_T = TypeVar("_T", bound="BaseFileLock") 

111 

112 

113class FileLockMeta(ABCMeta): 

114 _instances: WeakValueDictionary[str, BaseFileLock] 

115 _instances_lock: Lock 

116 

117 def __call__( # noqa: PLR0913 

118 cls: type[_T], 

119 lock_file: str | os.PathLike[str], 

120 timeout: float = -1, 

121 mode: int = _UNSET_FILE_MODE, 

122 thread_local: bool = True, # noqa: FBT001, FBT002 

123 *, 

124 blocking: bool = True, 

125 is_singleton: bool = False, 

126 poll_interval: float = 0.05, 

127 lifetime: float | None = None, 

128 **kwargs: Any, # capture remaining kwargs for subclasses # noqa: ANN401 

129 ) -> _T: 

130 params = { 

131 "timeout": timeout, 

132 "mode": mode, 

133 "thread_local": thread_local, 

134 "blocking": blocking, 

135 "is_singleton": is_singleton, 

136 "poll_interval": poll_interval, 

137 "lifetime": lifetime, 

138 **kwargs, 

139 } 

140 if not is_singleton: 

141 return cls._create_instance(lock_file, params) 

142 

143 # Look up, build and store under one lock. Without it two threads racing the first construction for a 

144 # path both miss the cache and each build their own instance, so callers relying on is_singleton for 

145 # reentrant locking across instances end up with two "singletons" and acquire()'s deadlock check then 

146 # rejects a legitimate reentrant acquire; the unguarded writes to the WeakValueDictionary are a data 

147 # race besides. ReadWriteLock and SoftReadWriteLock already guard their singleton caches this way. 

148 with cls._instances_lock: 

149 if (instance := cls._instances.get(str(lock_file))) is None: 

150 instance = cls._create_instance(lock_file, params) 

151 cls._instances[str(lock_file)] = instance 

152 return instance 

153 

154 params_to_check = { 

155 "thread_local": (thread_local, instance.is_thread_local()), 

156 "timeout": (timeout, instance.timeout), 

157 "mode": (mode, instance._context.mode), # noqa: SLF001 

158 "blocking": (blocking, instance.blocking), 

159 "poll_interval": (poll_interval, instance.poll_interval), 

160 "lifetime": (lifetime, instance.lifetime), 

161 } 

162 

163 non_matching_params = { 

164 name: (passed_param, set_param) 

165 for name, (passed_param, set_param) in params_to_check.items() 

166 if passed_param != set_param 

167 } 

168 if not non_matching_params: 

169 return instance # ty: ignore[invalid-return-type] # https://github.com/astral-sh/ty/issues/3231 

170 

171 # parameters do not match; raise error 

172 msg = "Singleton lock instances cannot be initialized with differing arguments" 

173 msg += "\nNon-matching arguments: " 

174 for param_name, (passed_param, set_param) in non_matching_params.items(): 

175 msg += f"\n\t{param_name} (existing lock has {set_param} but {passed_param} was passed)" 

176 raise ValueError(msg) 

177 

178 def _create_instance(cls: type[_T], lock_file: str | os.PathLike[str], params: dict[str, Any]) -> _T: 

179 # Keep only the params this subclass's __init__ accepts: virtualenv narrows the signature of its 

180 # BaseFileLock descendant, so passing the full set would break it (https://github.com/tox-dev/filelock/pull/340). 

181 present_params = inspect.signature(cls.__init__).parameters 

182 init_params = {key: value for key, value in params.items() if key in present_params} 

183 return super().__call__(lock_file, **init_params) 

184 

185 

186class BaseFileLock(contextlib.ContextDecorator, metaclass=FileLockMeta): 

187 """ 

188 Abstract base class for a file lock object. 

189 

190 Provides a reentrant, cross-process exclusive lock backed by OS-level primitives. Subclasses implement the actual 

191 locking mechanism (:class:`UnixFileLock <filelock.UnixFileLock>`, :class:`WindowsFileLock 

192 <filelock.WindowsFileLock>`, :class:`SoftFileLock <filelock.SoftFileLock>`). 

193 

194 """ 

195 

196 _instances: WeakValueDictionary[str, BaseFileLock] 

197 _instances_lock: Lock 

198 

199 #: How the cross-instance deadlock message names the conflicting holder; the async subclass says "task". 

200 _deadlock_holder_desc: str = "FileLock instance in this thread" 

201 

202 def __init_subclass__(cls, **kwargs: dict[str, Any]) -> None: 

203 """Setup unique state for lock subclasses.""" 

204 super().__init_subclass__(**kwargs) 

205 cls._instances = WeakValueDictionary() 

206 cls._instances_lock = Lock() 

207 

208 def __init__( # noqa: PLR0913 

209 self, 

210 lock_file: str | os.PathLike[str], 

211 timeout: float = -1, 

212 mode: int = _UNSET_FILE_MODE, 

213 thread_local: bool = True, # noqa: FBT001, FBT002 

214 *, 

215 blocking: bool = True, 

216 is_singleton: bool = False, 

217 poll_interval: float = 0.05, 

218 lifetime: float | None = None, 

219 ) -> None: 

220 """ 

221 Create a new lock object. 

222 

223 :param lock_file: path to the file 

224 :param timeout: default timeout when acquiring the lock, in seconds. It will be used as fallback value in the 

225 acquire method, if no timeout value (``None``) is given. If you want to disable the timeout, set it to a 

226 negative value. A timeout of 0 means that there is exactly one attempt to acquire the file lock. 

227 :param mode: file permissions for the lockfile. When not specified, the OS controls permissions via umask and 

228 default ACLs, preserving POSIX default ACL inheritance in shared directories. 

229 :param thread_local: Whether this object's internal context should be thread local or not. If this is set to 

230 ``False`` then the lock will be reentrant across threads. When ``True`` (the default), **all fields of the 

231 lock's internal context are per-thread**, including the configuration values ``poll_interval``, ``timeout``, 

232 ``blocking``, ``mode``, and ``lifetime``. Setting one of these properties from one thread does not change 

233 the value seen by another thread; threads that did not perform the write continue to see the value supplied 

234 at construction time. If you need configuration values to be visible across threads, construct the lock 

235 with ``thread_local=False``. 

236 :param blocking: whether the lock should be blocking or not 

237 :param is_singleton: If this is set to ``True`` then only one instance of this class will be created per lock 

238 file. This is useful if you want to use the lock object for reentrant locking without needing to pass the 

239 same object around. 

240 :param poll_interval: default interval for polling the lock file, in seconds. It will be used as fallback value 

241 in the acquire method, if no poll_interval value (``None``) is given. 

242 :param lifetime: maximum time in seconds a lock can be held before it is considered expired. When set, a waiting 

243 process will break a lock whose file modification time is older than ``lifetime`` seconds. ``None`` (the 

244 default) means locks never expire. 

245 

246 """ 

247 self._is_thread_local = thread_local 

248 self._is_singleton = is_singleton 

249 

250 # Create the context. Note that external code should not work with the context directly and should instead use 

251 # properties of this class. 

252 kwargs: dict[str, Any] = { 

253 "lock_file": os.fspath(lock_file), 

254 "timeout": timeout, 

255 "mode": mode, 

256 "blocking": blocking, 

257 "poll_interval": poll_interval, 

258 "lifetime": lifetime, 

259 } 

260 self._context: FileLockContext = (ThreadLocalFileContext if thread_local else FileLockContext)(**kwargs) 

261 

262 def is_thread_local(self) -> bool: 

263 """:returns: a flag indicating if this lock is thread local or not""" 

264 return self._is_thread_local 

265 

266 @property 

267 def is_singleton(self) -> bool: 

268 """ 

269 A flag indicating if this lock is singleton or not. 

270 

271 .. versionadded:: 3.13.0 

272 

273 """ 

274 return self._is_singleton 

275 

276 @property 

277 def lock_file(self) -> str: 

278 """Path to the lock file.""" 

279 return self._context.lock_file 

280 

281 @property 

282 def timeout(self) -> float: 

283 """ 

284 The default timeout value, in seconds. 

285 

286 .. versionadded:: 2.0.0 

287 

288 """ 

289 return self._context.timeout 

290 

291 @timeout.setter 

292 def timeout(self, value: float | str) -> None: 

293 """ 

294 Change the default timeout value. 

295 

296 :param value: the new value, in seconds 

297 

298 """ 

299 self._context.timeout = float(value) 

300 

301 @property 

302 def blocking(self) -> bool: 

303 """ 

304 Whether the locking is blocking or not. 

305 

306 .. versionadded:: 3.14.0 

307 

308 """ 

309 return self._context.blocking 

310 

311 @blocking.setter 

312 def blocking(self, value: bool) -> None: 

313 """ 

314 Change the default blocking value. 

315 

316 :param value: the new value as bool 

317 

318 """ 

319 self._context.blocking = value 

320 

321 @property 

322 def poll_interval(self) -> float: 

323 """ 

324 The default polling interval, in seconds. 

325 

326 .. versionadded:: 3.24.0 

327 

328 """ 

329 return self._context.poll_interval 

330 

331 @poll_interval.setter 

332 def poll_interval(self, value: float) -> None: 

333 """ 

334 Change the default polling interval. 

335 

336 :param value: the new value, in seconds 

337 

338 """ 

339 self._context.poll_interval = value 

340 

341 @property 

342 def lifetime(self) -> float | None: 

343 """ 

344 The lock lifetime in seconds, or ``None`` if the lock never expires. 

345 

346 .. versionadded:: 3.24.0 

347 

348 """ 

349 return self._context.lifetime 

350 

351 @lifetime.setter 

352 def lifetime(self, value: float | None) -> None: 

353 """ 

354 Change the lock lifetime. 

355 

356 :param value: the new value in seconds, or ``None`` to disable expiration 

357 

358 :raises ValueError: if *value* is a negative number 

359 :raises TypeError: if *value* is not ``None`` and not a real number 

360 

361 """ 

362 if value is not None: 

363 if isinstance(value, bool) or not isinstance(value, (int, float)): 

364 msg = f"lifetime must be a non-negative number or None, not {type(value).__name__}" 

365 raise TypeError(msg) 

366 if value < 0: 

367 msg = f"lifetime must be non-negative, not {value!r}" 

368 raise ValueError(msg) 

369 self._context.lifetime = value 

370 

371 @property 

372 def mode(self) -> int: 

373 """The file permissions for the lockfile.""" 

374 return 0o644 if self._context.mode == _UNSET_FILE_MODE else self._context.mode 

375 

376 @property 

377 def has_explicit_mode(self) -> bool: 

378 """Whether the file permissions were explicitly set.""" 

379 return self._context.mode != _UNSET_FILE_MODE 

380 

381 def _open_mode(self) -> int: 

382 """:returns: the mode for os.open() — 0o666 when unset (let umask/ACLs decide), else the explicit mode""" 

383 return 0o666 if self._context.mode == _UNSET_FILE_MODE else self._context.mode 

384 

385 def _try_break_expired_lock(self) -> None: 

386 """Remove the lock file if its modification time exceeds the configured :attr:`lifetime`.""" 

387 if (lifetime := self._context.lifetime) is None: 

388 return 

389 with contextlib.suppress(OSError): 

390 # lstat, not stat: an attacker with write access to the lock directory can replace a held 

391 # lock file with a symlink pointing at an old file, making stat() report the target's stale 

392 # mtime so a waiter breaks a live lock and two processes hold it at once. lstat reads the 

393 # symlink's own mtime, matching the O_NOFOLLOW reads elsewhere. 

394 st = os.lstat(self.lock_file) 

395 if time.time() - st.st_mtime < lifetime: 

396 return 

397 break_lock_file(self.lock_file, st.st_mtime, st.st_ino) 

398 

399 @abstractmethod 

400 def _acquire(self) -> None: 

401 """If the file lock could be acquired, self._context.lock_file_fd holds the file descriptor of the lock file.""" 

402 raise NotImplementedError 

403 

404 @abstractmethod 

405 def _release(self) -> None: 

406 """Releases the lock and sets self._context.lock_file_fd to None.""" 

407 raise NotImplementedError 

408 

409 @property 

410 def is_locked(self) -> bool: 

411 """ 

412 A boolean indicating if the lock file is holding the lock currently. 

413 

414 .. versionchanged:: 2.0.0 

415 

416 This was previously a method and is now a property. 

417 

418 """ 

419 return self._context.lock_file_fd is not None 

420 

421 @property 

422 def lock_counter(self) -> int: 

423 """The number of times this lock has been acquired (but not yet released).""" 

424 return self._context.lock_counter 

425 

426 @staticmethod 

427 def _check_give_up( # noqa: PLR0913 

428 lock_id: int, 

429 lock_filename: str, 

430 *, 

431 blocking: bool, 

432 cancel_check: Callable[[], bool] | None, 

433 timeout: float, 

434 start_time: float, 

435 ) -> bool: 

436 if blocking is False: 

437 _LOGGER.debug("Failed to immediately acquire lock %s on %s", lock_id, lock_filename) 

438 return True 

439 if cancel_check is not None and cancel_check(): 

440 _LOGGER.debug("Cancellation requested for lock %s on %s", lock_id, lock_filename) 

441 return True 

442 if 0 <= timeout < time.perf_counter() - start_time: 

443 _LOGGER.debug("Timeout on acquiring lock %s on %s", lock_id, lock_filename) 

444 return True 

445 return False 

446 

447 def acquire( 

448 self, 

449 timeout: float | None = None, 

450 poll_interval: float | None = None, 

451 *, 

452 poll_intervall: float | None = None, 

453 blocking: bool | None = None, 

454 cancel_check: Callable[[], bool] | None = None, 

455 ) -> AcquireReturnProxy: 

456 """ 

457 Try to acquire the file lock. 

458 

459 :param timeout: maximum wait time for acquiring the lock, ``None`` means use the default :attr:`~timeout` is and 

460 if ``timeout < 0``, there is no timeout and this method will block until the lock could be acquired 

461 :param poll_interval: interval of trying to acquire the lock file, ``None`` means use the default 

462 :attr:`~poll_interval` 

463 :param poll_intervall: deprecated, kept for backwards compatibility, use ``poll_interval`` instead 

464 :param blocking: defaults to True. If False, function will return immediately if it cannot obtain a lock on the 

465 first attempt. Otherwise, this method will block until the timeout expires or the lock is acquired. 

466 :param cancel_check: a callable returning ``True`` when the acquisition should be canceled. Checked on each poll 

467 iteration. When triggered, raises :class:`~Timeout` just like an expired timeout. 

468 

469 :returns: a context object that will unlock the file when the context is exited 

470 

471 :raises Timeout: if fails to acquire lock within the timeout period 

472 

473 .. code-block:: python 

474 

475 # You can use this method in the context manager (recommended) 

476 with lock.acquire(): 

477 pass 

478 

479 # Or use an equivalent try-finally construct: 

480 lock.acquire() 

481 try: 

482 pass 

483 finally: 

484 lock.release() 

485 

486 .. versionchanged:: 2.0.0 

487 

488 This method returns now a *proxy* object instead of *self*, so that it can be used in a with statement 

489 without side effects. 

490 

491 """ 

492 # Use the default timeout, if no timeout is provided. 

493 if timeout is None: 

494 timeout = self._context.timeout 

495 

496 if blocking is None: 

497 blocking = self._context.blocking 

498 

499 if poll_intervall is not None: 

500 msg = "use poll_interval instead of poll_intervall" 

501 warnings.warn(msg, DeprecationWarning, stacklevel=2) 

502 poll_interval = poll_intervall 

503 

504 poll_interval = poll_interval if poll_interval is not None else self._context.poll_interval 

505 

506 # Increment the number right at the beginning. We can still undo it, if something fails. 

507 self._context.lock_counter += 1 

508 

509 canonical = _canonical(self.lock_file) 

510 self._raise_if_would_deadlock(canonical, timeout=timeout, blocking=blocking) 

511 

512 start_time = time.perf_counter() 

513 try: 

514 self._poll_until_acquired( 

515 blocking=blocking, 

516 cancel_check=cancel_check, 

517 timeout=timeout, 

518 poll_interval=poll_interval, 

519 start_time=start_time, 

520 ) 

521 except BaseException: 

522 self._undo_acquire(canonical) 

523 raise 

524 self._commit_acquire(canonical) 

525 return AcquireReturnProxy(lock=self) 

526 

527 def _raise_if_would_deadlock(self, canonical: str, *, timeout: float, blocking: bool) -> None: 

528 """ 

529 Fail fast when a *different* live instance already holds this path on the current thread/task. 

530 

531 Only the first, indefinitely-blocking acquire can self-deadlock this way: waiting in the OS primitive would 

532 block on a lock this thread already owns. A finite timeout or ``blocking=False`` keeps the normal Timeout path. 

533 """ 

534 would_block = self._context.lock_counter == 1 and not self.is_locked and timeout < 0 and blocking 

535 if would_block and _registry.held.get(canonical) not in {None, id(self)}: 

536 self._context.lock_counter -= 1 

537 msg = ( 

538 f"Deadlock: lock '{self.lock_file}' is already held by a different {self._deadlock_holder_desc}. " 

539 f"Use is_singleton=True to enable reentrant locking across instances." 

540 ) 

541 raise RuntimeError(msg) 

542 

543 def _undo_acquire(self, canonical: str) -> None: 

544 """Roll back the counter after a failed acquire, dropping the registry entry once nothing holds the path.""" 

545 self._context.lock_counter = max(0, self._context.lock_counter - 1) 

546 if self._context.lock_counter == 0: 

547 _registry.held.pop(canonical, None) 

548 

549 def _commit_acquire(self, canonical: str) -> None: 

550 """Record this instance as the holder once the first acquire succeeds, so peers can detect the deadlock.""" 

551 if self._context.lock_counter == 1: 

552 _registry.held[canonical] = id(self) 

553 

554 def _drop_registry_entry(self) -> None: 

555 """Forget this path's holder on release so a later cross-instance acquire is not misread as a deadlock.""" 

556 _registry.held.pop(_canonical(self.lock_file), None) 

557 

558 def _poll_until_acquired( 

559 self, 

560 *, 

561 blocking: bool, 

562 cancel_check: Callable[[], bool] | None, 

563 timeout: float, 

564 poll_interval: float, 

565 start_time: float, 

566 ) -> None: 

567 lock_id = id(self) 

568 lock_filename = self.lock_file 

569 while True: 

570 if not self.is_locked: 

571 self._try_break_expired_lock() 

572 _LOGGER.debug("Attempting to acquire lock %s on %s", lock_id, lock_filename) 

573 self._acquire() 

574 if self.is_locked: 

575 _LOGGER.debug("Lock %s acquired on %s", lock_id, lock_filename) 

576 return 

577 if self._check_give_up( 

578 lock_id, 

579 lock_filename, 

580 blocking=blocking, 

581 cancel_check=cancel_check, 

582 timeout=timeout, 

583 start_time=start_time, 

584 ): 

585 raise Timeout(lock_filename) 

586 msg = "Lock %s not acquired on %s, waiting %s seconds ..." 

587 _LOGGER.debug(msg, lock_id, lock_filename, poll_interval) 

588 time.sleep(poll_interval) 

589 

590 def release(self, force: bool = False) -> None: # noqa: FBT001, FBT002 

591 """ 

592 Release the file lock. The lock is only completely released when the lock counter reaches 0. The lock file 

593 itself may be deleted automatically, the behavior is platform-specific. 

594 

595 :param force: If true, the lock counter is ignored and the lock is released in every case. 

596 

597 """ 

598 if self.is_locked: 

599 self._context.lock_counter -= 1 

600 

601 if self._context.lock_counter == 0 or force: 

602 lock_id, lock_filename = id(self), self.lock_file 

603 

604 _LOGGER.debug("Attempting to release lock %s on %s", lock_id, lock_filename) 

605 self._release() 

606 self._context.lock_counter = 0 

607 self._drop_registry_entry() 

608 _LOGGER.debug("Lock %s released on %s", lock_id, lock_filename) 

609 

610 def __enter__(self) -> Self: 

611 """ 

612 Acquire the lock. 

613 

614 :returns: the lock object 

615 

616 """ 

617 self.acquire() 

618 return self 

619 

620 def __exit__( 

621 self, 

622 exc_type: type[BaseException] | None, 

623 exc_value: BaseException | None, 

624 traceback: TracebackType | None, 

625 ) -> None: 

626 """ 

627 Release the lock. 

628 

629 :param exc_type: the exception type if raised 

630 :param exc_value: the exception value if raised 

631 :param traceback: the exception traceback if raised 

632 

633 """ 

634 self.release() 

635 

636 def __del__(self) -> None: 

637 """Called when the lock object is deleted.""" 

638 self.release(force=True) 

639 

640 

641__all__ = [ 

642 "_UNSET_FILE_MODE", 

643 "AcquireReturnProxy", 

644 "BaseFileLock", 

645]