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 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 

116 def __call__( # noqa: PLR0913 

117 cls: type[_T], 

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

119 timeout: float = -1, 

120 mode: int = _UNSET_FILE_MODE, 

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

122 *, 

123 blocking: bool = True, 

124 is_singleton: bool = False, 

125 poll_interval: float = 0.05, 

126 lifetime: float | None = None, 

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

128 ) -> _T: 

129 if is_singleton: 

130 instance = cls._instances.get(str(lock_file)) 

131 if instance: 

132 params_to_check = { 

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

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

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

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

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

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

139 } 

140 

141 non_matching_params = { 

142 name: (passed_param, set_param) 

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

144 if passed_param != set_param 

145 } 

146 if not non_matching_params: 

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

148 

149 # parameters do not match; raise error 

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

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

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

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

154 raise ValueError(msg) 

155 

156 # Workaround to make `__init__`'s params optional in subclasses 

157 # E.g. virtualenv changes the signature of the `__init__` method in the `BaseFileLock` class descendant 

158 # (https://github.com/tox-dev/filelock/pull/340) 

159 

160 all_params = { 

161 "timeout": timeout, 

162 "mode": mode, 

163 "thread_local": thread_local, 

164 "blocking": blocking, 

165 "is_singleton": is_singleton, 

166 "poll_interval": poll_interval, 

167 "lifetime": lifetime, 

168 **kwargs, 

169 } 

170 

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

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

173 

174 instance = super().__call__(lock_file, **init_params) 

175 

176 if is_singleton: 

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

178 

179 return instance 

180 

181 

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

183 """ 

184 Abstract base class for a file lock object. 

185 

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

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

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

189 

190 """ 

191 

192 _instances: WeakValueDictionary[str, BaseFileLock] 

193 

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

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

196 super().__init_subclass__(**kwargs) 

197 cls._instances = WeakValueDictionary() 

198 

199 def __init__( # noqa: PLR0913 

200 self, 

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

202 timeout: float = -1, 

203 mode: int = _UNSET_FILE_MODE, 

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

205 *, 

206 blocking: bool = True, 

207 is_singleton: bool = False, 

208 poll_interval: float = 0.05, 

209 lifetime: float | None = None, 

210 ) -> None: 

211 """ 

212 Create a new lock object. 

213 

214 :param lock_file: path to the file 

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

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

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

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

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

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

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

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

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

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

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

226 with ``thread_local=False``. 

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

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

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

230 same object around. 

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

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

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

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

235 default) means locks never expire. 

236 

237 """ 

238 self._is_thread_local = thread_local 

239 self._is_singleton = is_singleton 

240 

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

242 # properties of this class. 

243 kwargs: dict[str, Any] = { 

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

245 "timeout": timeout, 

246 "mode": mode, 

247 "blocking": blocking, 

248 "poll_interval": poll_interval, 

249 "lifetime": lifetime, 

250 } 

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

252 

253 def is_thread_local(self) -> bool: 

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

255 return self._is_thread_local 

256 

257 @property 

258 def is_singleton(self) -> bool: 

259 """ 

260 :returns: a flag indicating if this lock is singleton or not 

261 

262 .. versionadded:: 3.13.0 

263 

264 """ 

265 return self._is_singleton 

266 

267 @property 

268 def lock_file(self) -> str: 

269 """:returns: path to the lock file""" 

270 return self._context.lock_file 

271 

272 @property 

273 def timeout(self) -> float: 

274 """ 

275 :returns: the default timeout value, in seconds 

276 

277 .. versionadded:: 2.0.0 

278 

279 """ 

280 return self._context.timeout 

281 

282 @timeout.setter 

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

284 """ 

285 Change the default timeout value. 

286 

287 :param value: the new value, in seconds 

288 

289 """ 

290 self._context.timeout = float(value) 

291 

292 @property 

293 def blocking(self) -> bool: 

294 """ 

295 :returns: whether the locking is blocking or not 

296 

297 .. versionadded:: 3.14.0 

298 

299 """ 

300 return self._context.blocking 

301 

302 @blocking.setter 

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

304 """ 

305 Change the default blocking value. 

306 

307 :param value: the new value as bool 

308 

309 """ 

310 self._context.blocking = value 

311 

312 @property 

313 def poll_interval(self) -> float: 

314 """ 

315 :returns: the default polling interval, in seconds 

316 

317 .. versionadded:: 3.24.0 

318 

319 """ 

320 return self._context.poll_interval 

321 

322 @poll_interval.setter 

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

324 """ 

325 Change the default polling interval. 

326 

327 :param value: the new value, in seconds 

328 

329 """ 

330 self._context.poll_interval = value 

331 

332 @property 

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

334 """ 

335 :returns: the lock lifetime in seconds, or ``None`` if the lock never expires 

336 

337 .. versionadded:: 3.24.0 

338 

339 """ 

340 return self._context.lifetime 

341 

342 @lifetime.setter 

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

344 """ 

345 Change the lock lifetime. 

346 

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

348 

349 """ 

350 self._context.lifetime = value 

351 

352 @property 

353 def mode(self) -> int: 

354 """:returns: the file permissions for the lockfile""" 

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

356 

357 @property 

358 def has_explicit_mode(self) -> bool: 

359 """:returns: whether the file permissions were explicitly set""" 

360 return self._context.mode != _UNSET_FILE_MODE 

361 

362 def _open_mode(self) -> int: 

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

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

365 

366 def _try_break_expired_lock(self) -> None: 

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

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

369 return 

370 with contextlib.suppress(OSError): 

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

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

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

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

375 st = os.lstat(self.lock_file) 

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

377 return 

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

379 

380 @abstractmethod 

381 def _acquire(self) -> None: 

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

383 raise NotImplementedError 

384 

385 @abstractmethod 

386 def _release(self) -> None: 

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

388 raise NotImplementedError 

389 

390 @property 

391 def is_locked(self) -> bool: 

392 """ 

393 :returns: A boolean indicating if the lock file is holding the lock currently. 

394 

395 .. versionchanged:: 2.0.0 

396 

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

398 

399 """ 

400 return self._context.lock_file_fd is not None 

401 

402 @property 

403 def lock_counter(self) -> int: 

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

405 return self._context.lock_counter 

406 

407 @staticmethod 

408 def _check_give_up( # noqa: PLR0913 

409 lock_id: int, 

410 lock_filename: str, 

411 *, 

412 blocking: bool, 

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

414 timeout: float, 

415 start_time: float, 

416 ) -> bool: 

417 if blocking is False: 

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

419 return True 

420 if cancel_check is not None and cancel_check(): 

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

422 return True 

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

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

425 return True 

426 return False 

427 

428 def acquire( 

429 self, 

430 timeout: float | None = None, 

431 poll_interval: float | None = None, 

432 *, 

433 poll_intervall: float | None = None, 

434 blocking: bool | None = None, 

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

436 ) -> AcquireReturnProxy: 

437 """ 

438 Try to acquire the file lock. 

439 

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

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

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

443 :attr:`~poll_interval` 

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

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

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

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

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

449 

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

451 

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

453 

454 .. code-block:: python 

455 

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

457 with lock.acquire(): 

458 pass 

459 

460 # Or use an equivalent try-finally construct: 

461 lock.acquire() 

462 try: 

463 pass 

464 finally: 

465 lock.release() 

466 

467 .. versionchanged:: 2.0.0 

468 

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

470 without side effects. 

471 

472 """ 

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

474 if timeout is None: 

475 timeout = self._context.timeout 

476 

477 if blocking is None: 

478 blocking = self._context.blocking 

479 

480 if poll_intervall is not None: 

481 msg = "use poll_interval instead of poll_intervall" 

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

483 poll_interval = poll_intervall 

484 

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

486 

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

488 self._context.lock_counter += 1 

489 

490 lock_id = id(self) 

491 lock_filename = self.lock_file 

492 canonical = _canonical(lock_filename) 

493 

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

495 if would_block and (existing := _registry.held.get(canonical)) is not None and existing != lock_id: 

496 self._context.lock_counter -= 1 

497 msg = ( 

498 f"Deadlock: lock '{lock_filename}' is already held by a different " 

499 f"FileLock instance in this thread. Use is_singleton=True to " 

500 f"enable reentrant locking across instances." 

501 ) 

502 raise RuntimeError(msg) 

503 

504 start_time = time.perf_counter() 

505 try: 

506 self._poll_until_acquired( 

507 blocking=blocking, 

508 cancel_check=cancel_check, 

509 timeout=timeout, 

510 poll_interval=poll_interval, 

511 start_time=start_time, 

512 ) 

513 except BaseException: 

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

515 if self._context.lock_counter == 0: 

516 _registry.held.pop(canonical, None) 

517 raise 

518 if self._context.lock_counter == 1: 

519 _registry.held[canonical] = lock_id 

520 return AcquireReturnProxy(lock=self) 

521 

522 def _poll_until_acquired( 

523 self, 

524 *, 

525 blocking: bool, 

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

527 timeout: float, 

528 poll_interval: float, 

529 start_time: float, 

530 ) -> None: 

531 lock_id = id(self) 

532 lock_filename = self.lock_file 

533 while True: 

534 if not self.is_locked: 

535 self._try_break_expired_lock() 

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

537 self._acquire() 

538 if self.is_locked: 

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

540 return 

541 if self._check_give_up( 

542 lock_id, 

543 lock_filename, 

544 blocking=blocking, 

545 cancel_check=cancel_check, 

546 timeout=timeout, 

547 start_time=start_time, 

548 ): 

549 raise Timeout(lock_filename) 

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

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

552 time.sleep(poll_interval) 

553 

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

555 """ 

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

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

558 

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

560 

561 """ 

562 if self.is_locked: 

563 self._context.lock_counter -= 1 

564 

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

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

567 

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

569 self._release() 

570 self._context.lock_counter = 0 

571 _registry.held.pop(_canonical(lock_filename), None) 

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

573 

574 def __enter__(self) -> Self: 

575 """ 

576 Acquire the lock. 

577 

578 :returns: the lock object 

579 

580 """ 

581 self.acquire() 

582 return self 

583 

584 def __exit__( 

585 self, 

586 exc_type: type[BaseException] | None, 

587 exc_value: BaseException | None, 

588 traceback: TracebackType | None, 

589 ) -> None: 

590 """ 

591 Release the lock. 

592 

593 :param exc_type: the exception type if raised 

594 :param exc_value: the exception value if raised 

595 :param traceback: the exception traceback if raised 

596 

597 """ 

598 self.release() 

599 

600 def __del__(self) -> None: 

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

602 self.release(force=True) 

603 

604 

605__all__ = [ 

606 "_UNSET_FILE_MODE", 

607 "AcquireReturnProxy", 

608 "BaseFileLock", 

609]