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

1from __future__ import annotations 

2 

3import os 

4import sys 

5import warnings 

6from contextlib import suppress 

7from errno import EACCES, EAGAIN, ENOSYS, EWOULDBLOCK 

8from pathlib import Path 

9from typing import Final, cast 

10 

11from ._api import BaseFileLock 

12from ._util import ensure_directory_exists 

13 

14has_fcntl = False 

15if sys.platform == "win32": # pragma: win32 cover 

16 

17 class UnixFileLock(BaseFileLock): 

18 """Uses the :func:`fcntl.flock` to hard lock the lock file on unix systems.""" 

19 

20 def _acquire(self) -> None: 

21 raise NotImplementedError 

22 

23 def _release(self) -> None: 

24 raise NotImplementedError 

25 

26else: # pragma: win32 no cover 

27 try: 

28 import fcntl 

29 

30 _ = (fcntl.flock, fcntl.LOCK_EX, fcntl.LOCK_NB, fcntl.LOCK_UN) 

31 except (ImportError, AttributeError): 

32 _FCNTL_UNAVAILABLE: Final[str] = "fcntl is unavailable" 

33 

34 def _lock_fd_nonblocking(_fd: int) -> bool: 

35 raise OSError(ENOSYS, _FCNTL_UNAVAILABLE) 

36 

37 def _unlock_fd(_fd: int) -> None: 

38 raise OSError(ENOSYS, _FCNTL_UNAVAILABLE) 

39 

40 else: 

41 has_fcntl = True 

42 # Contention errnos for a nonblocking flock. EAGAIN/EWOULDBLOCK are the usual "held elsewhere" codes; some 

43 # filesystems report EACCES instead, so treat it as contention too rather than a permanent error. 

44 _CONTENTION_ERRNOS: Final[frozenset[int]] = frozenset({EACCES, EAGAIN, EWOULDBLOCK}) 

45 

46 def _lock_fd_nonblocking(fd: int) -> bool: 

47 # One nonblocking exclusive flock attempt shared by UnixFileLock and lock_descriptor, so both contend on 

48 # the same lock and classify errors identically. The caller owns fd; this never closes it. 

49 try: 

50 fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB) 

51 except OSError as exception: 

52 if exception.errno in _CONTENTION_ERRNOS: 

53 return False 

54 raise 

55 return True 

56 

57 def _unlock_fd(fd: int) -> None: 

58 fcntl.flock(fd, fcntl.LOCK_UN) 

59 

60 class UnixFileLock(BaseFileLock): 

61 """ 

62 Uses the :func:`fcntl.flock` to hard lock the lock file on unix systems. 

63 

64 We leave the lock file in place after release. Unlinking a locked file on Unix splits 

65 waiters across inodes and breaks mutual exclusion for processes that coordinate via the 

66 same path. 

67 """ 

68 

69 def _acquire(self) -> None: 

70 missing_flock = self._acquire_native() 

71 if missing_flock is not None: 

72 self._switch_to_soft_lock(*missing_flock) 

73 

74 def _acquire_native(self) -> tuple[int, OSError] | None: 

75 ensure_directory_exists(self.lock_file) 

76 # Open without O_TRUNC and defer truncation and fchmod until after flock succeeds: a contender that loses 

77 # the lock must not truncate the holder's file (erasing caller diagnostics) or change its mode. The winner 

78 # truncates and normalizes mode once it owns the lock (#591). 

79 open_flags = os.O_RDWR 

80 if (o_nofollow := getattr(os, "O_NOFOLLOW", None)) is not None: 

81 open_flags |= o_nofollow 

82 open_flags |= os.O_CREAT 

83 open_mode = self._open_mode() 

84 try: 

85 fd = os.open(self.lock_file, open_flags, open_mode) 

86 except FileNotFoundError: 

87 # On FUSE/NFS, os.open(O_CREAT) is not atomic; a split LOOKUP + CREATE lets a concurrent unlink() 

88 # delete the file between them. For a valid path, treat ENOENT as transient contention. For an 

89 # invalid path (e.g. empty string), re-raise to avoid an infinite retry loop. 

90 if self.lock_file and Path(self.lock_file).parent.exists(): 

91 return None 

92 raise 

93 except PermissionError: 

94 # Sticky-bit dirs (e.g. /tmp): O_CREAT fails if the file is owned by another user (#317). 

95 # Fall back to opening the existing file without O_CREAT. 

96 if not Path(self.lock_file).exists(): 

97 raise 

98 try: 

99 fd = os.open(self.lock_file, open_flags & ~os.O_CREAT, open_mode) 

100 except FileNotFoundError: 

101 return None 

102 self._mark_descriptor_pending(fd) 

103 try: 

104 locked = _lock_fd_nonblocking(fd) 

105 except OSError as exception: 

106 if exception.errno != ENOSYS: 

107 self._mark_descriptor_released() 

108 os.close(fd) 

109 raise # contention returns False from _lock_fd_nonblocking, so any raise here is a real failure 

110 return fd, exception 

111 if locked: 

112 self._finalize_locked_fd(fd) 

113 else: 

114 self._mark_descriptor_released() 

115 os.close(fd) # contention; let the retry loop try again 

116 return None 

117 

118 def _switch_to_soft_lock(self, fd: int, missing_flock: OSError) -> None: 

119 # The filesystem does not implement flock. Capture the opened file's identity before closing so the cleanup 

120 # below removes only this attempt's placeholder, not a peer's replacement. 

121 identity: tuple[int, int] | None = None 

122 with suppress(OSError): 

123 identity = (fstat := os.fstat(fd)).st_dev, fstat.st_ino 

124 self._mark_descriptor_released() 

125 os.close(fd) 

126 if not self._fallback_to_soft or self._preserve_lock_file or self._on_acquired is not None: 

127 # Fail closed: the caller opted out of existence-lock semantics (#603), asked to preserve the pathname 

128 # (#605), or set an on_acquired hook (#607), none of which a soft lock can honor. 

129 raise missing_flock 

130 with suppress(OSError): 

131 current = os.lstat(self.lock_file) 

132 if identity == (current.st_dev, current.st_ino): 

133 Path(self.lock_file).unlink() 

134 self._fallback_to_soft_lock() 

135 self._acquire() 

136 

137 def _finalize_locked_fd(self, fd: int) -> None: 

138 # Runs with the flock held. Truncate and normalize mode under a guard so any failure closes fd rather than 

139 # leaking it and its lock. A concurrent _release() may have unlinked the inode between our open() and 

140 # flock() (st_nlink 0), leaving a useless dead-inode lock; drop it and let the retry loop start fresh. 

141 keep = False 

142 try: 

143 stat_result = os.fstat(fd) 

144 if stat_result.st_nlink != 0: 

145 os.ftruncate(fd, 0) 

146 self._apply_explicit_mode(fd) 

147 keep = True 

148 except OSError: 

149 self._mark_descriptor_released() 

150 os.close(fd) 

151 raise 

152 if keep: 

153 self._mark_descriptor_owned(fd, (stat_result.st_dev, stat_result.st_ino)) 

154 else: 

155 self._mark_descriptor_released() 

156 os.close(fd) 

157 

158 def _apply_explicit_mode(self, fd: int) -> None: 

159 if self.has_explicit_mode: 

160 with suppress(PermissionError): 

161 os.fchmod(fd, self._context.mode) 

162 

163 def _fallback_to_soft_lock(self) -> None: 

164 # Import lazily: this runs only on the rare flock fallback, and asyncio imports _unix, so a 

165 # module-level import of it here would cycle. 

166 from ._soft import SoftFileLock # ruff:ignore[import-outside-top-level] 

167 

168 warnings.warn("flock not supported on this filesystem, falling back to SoftFileLock", stacklevel=2) 

169 from .asyncio import AsyncSoftFileLock, BaseAsyncFileLock # ruff:ignore[import-outside-top-level] 

170 

171 self.__class__ = AsyncSoftFileLock if isinstance(self, BaseAsyncFileLock) else SoftFileLock 

172 

173 def _release(self) -> None: 

174 fd = cast("int", self._context.lock_file_fd) 

175 # Retain the descriptor until flock succeeds: a failed unlock leaves the kernel lock held, so is_locked 

176 # must keep reporting held for a retry. Once flock commits, clear held state and close as post-unlock 

177 # cleanup; a close failure (EIO on FUSE/Docker bind mounts) does not make the kernel lock held again. 

178 _unlock_fd(fd) 

179 self._mark_descriptor_released() 

180 self._close_released_fd(fd, default_suppresses=True) 

181 

182 

183if sys.platform == "win32": # pragma: win32 cover 

184 __all__ = ["UnixFileLock", "has_fcntl"] 

185else: # pragma: win32 no cover 

186 __all__ = ["UnixFileLock", "_lock_fd_nonblocking", "_unlock_fd", "has_fcntl"]