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

1""" 

2A platform independent file lock that supports the with-statement. 

3 

4.. autodata:: filelock.__version__ 

5 :no-value: 

6 

7.. autodata:: filelock.OwnerMode 

8 

9.. autodata:: filelock.CompromiseReason 

10 

11""" 

12 

13from __future__ import annotations 

14 

15__lazy_modules__ = ["filelock._descriptor", "filelock._error", "importlib"] 

16 

17import sys # simplint: ignore[SMP407] # lazy loader and platform selection live here 

18import warnings # simplint: ignore[SMP407] # lazy loader and platform selection live here 

19from importlib import import_module # simplint: ignore[SMP407] # PEP 562 loader imports submodules by name 

20from typing import TYPE_CHECKING, Final # simplint: ignore[SMP407] # TYPE_CHECKING and Final for module constants 

21 

22from filelock._api import AcquireReturnProxy, BaseFileLock, CloseErrorPolicy, ContextErrorPolicy, LockOptions 

23from filelock._descriptor import lock_descriptor, unlock_descriptor 

24from filelock._error import LeaseSettingsMismatch, SoftFileLockLifetimeWarning, SoftFileLockProtocolError, Timeout 

25from filelock._unix import UnixFileLock 

26from filelock._unix import has_fcntl as _has_fcntl # simplint: ignore[SMP407] # private probe feeding public has_fcntl 

27from filelock._windows import WindowsFileLock 

28 

29# Keeps ``filelock.version`` the string 4.0.12 exposed rather than the submodule. 

30from filelock.version import version # simplint: ignore[SMP407] # API exposes filelock.version as this string 

31 

32if TYPE_CHECKING: # simplint: ignore[SMP407] # type-checker platform lock aliases 

33 from filelock import asyncio 

34 from filelock._async_read_write import AsyncAcquireReadWriteReturnProxy, AsyncReadWriteLock 

35 from filelock._lease import CompromiseReason, LeaseCompromise, SoftFileLease 

36 from filelock._marker import MarkerSoftFileLock, OwnerMode, OwnerRecord 

37 from filelock._read_write import ReadWriteLock 

38 from filelock._soft import SoftFileLock 

39 from filelock._soft_rw._async import AsyncAcquireSoftReadWriteReturnProxy, AsyncSoftReadWriteLock 

40 from filelock._soft_rw._sync import SoftReadWriteLock 

41 from filelock._strict import StrictSoftFileClaim, StrictSoftFileClaimState, StrictSoftFileLock 

42 from filelock.asyncio import ( 

43 AsyncAcquireReturnProxy, 

44 AsyncSoftFileLease, 

45 AsyncSoftFileLock, 

46 AsyncStrictSoftFileLock, 

47 AsyncUnixFileLock, 

48 AsyncWindowsFileLock, 

49 BaseAsyncFileLock, 

50 ) 

51 

52#: version of the project as a string 

53__version__: Final[str] = version # simplint: ignore[SMP407] # public __version__ is a Final assignment 

54 

55#: ``True`` when :func:`fcntl.flock` is available. Off Windows, :data:`FileLock` then resolves to 

56#: :class:`UnixFileLock`, otherwise to :class:`SoftFileLock`. Always ``False`` on Windows. 

57#: 

58#: :meta hide-value: 

59has_fcntl: Final[bool] = _has_fcntl # simplint: ignore[SMP102, SMP407] # public name; renaming breaks importers 

60 

61 

62if sys.platform == "win32": # pragma: win32 cover # simplint: ignore[SMP407] # platform selection runs at import 

63 _FileLock: type[BaseFileLock] = WindowsFileLock 

64else: # pragma: win32 no cover # ruff:ignore[collapsible-else-if] # the else carries the win32 no-cover pragma 

65 if has_fcntl: 

66 _FileLock: type[BaseFileLock] = UnixFileLock 

67 else: 

68 from filelock._soft import SoftFileLock 

69 

70 _FileLock = SoftFileLock 

71 warnings.warn("only soft file lock is available", stacklevel=2) 

72 

73if TYPE_CHECKING: # simplint: ignore[SMP407] # type-checker FileLock alias 

74 #: Alias for the lock, which should be used for the current platform. 

75 FileLock = SoftFileLock 

76 #: Alias for the async lock, which should be used for the current platform. 

77 AsyncFileLock = AsyncSoftFileLock 

78else: 

79 #: Alias for the lock, which should be used for the current platform. 

80 FileLock = _FileLock 

81 

82# Importing asyncio and sqlite3 costs more than the rest of the package, so names that need them load on first access. 

83_LAZY_ATTRIBUTES: Final[dict[str, str]] = { # simplint: ignore[SMP407] # lookup read by PEP 562 __getattr__ 

84 "AsyncAcquireReadWriteReturnProxy": "._async_read_write", 

85 "AsyncAcquireReturnProxy": ".asyncio", 

86 "AsyncAcquireSoftReadWriteReturnProxy": "._soft_rw._async", 

87 "AsyncFileLock": ".asyncio", 

88 "AsyncReadWriteLock": "._async_read_write", 

89 "AsyncSoftFileLease": ".asyncio", 

90 "AsyncSoftFileLock": ".asyncio", 

91 "AsyncSoftReadWriteLock": "._soft_rw._async", 

92 "AsyncStrictSoftFileLock": ".asyncio", 

93 "AsyncUnixFileLock": ".asyncio", 

94 "AsyncWindowsFileLock": ".asyncio", 

95 "BaseAsyncFileLock": ".asyncio", 

96 "CompromiseReason": "._lease", 

97 "LeaseCompromise": "._lease", 

98 "MarkerSoftFileLock": "._marker", 

99 "OwnerMode": "._marker", 

100 "OwnerRecord": "._marker", 

101 "ReadWriteLock": "._read_write", 

102 "SoftFileLease": "._lease", 

103 "SoftFileLock": "._soft", 

104 "SoftReadWriteLock": "._soft_rw._sync", 

105 "StrictSoftFileClaim": "._strict", 

106 "StrictSoftFileClaimState": "._strict", 

107 "StrictSoftFileLock": "._strict", 

108 "asyncio": ".asyncio", 

109} 

110 

111 

112def __getattr__( # simplint: ignore[SMP407] # PEP 562 __getattr__ lives here 

113 name: str, 

114) -> object: # simplint: ignore[SMP602] # lazy attributes span several types 

115 if (module_name := _LAZY_ATTRIBUTES.get(name)) is None: 

116 msg = f"module {__name__!r} has no attribute {name!r}" 

117 raise AttributeError(msg) 

118 try: 

119 module = import_module(module_name, __name__) 

120 except ImportError as error: 

121 # Only a missing sqlite3 module (the package, CPython's _sqlite3, PyPy's _sqlite3_cffi) leaves the read-write 

122 # locks None; a frozen application that left out a filelock module gets the error that names it. 

123 sqlite_missing = (error.name or "").startswith(("sqlite3", "_sqlite3")) 

124 if module_name not in {"._read_write", "._async_read_write"} or not sqlite_missing: 

125 raise 

126 value = None # pragma: lacks sqlite3 

127 else: 

128 if name == "asyncio": 

129 value = module 

130 else: 

131 value = getattr(module, f"Async{_FileLock.__name__}" if name == "AsyncFileLock" else name) 

132 globals()[name] = value 

133 return value 

134 

135 

136def __dir__() -> list[str]: # simplint: ignore[SMP407] # PEP 562 __dir__ lives here 

137 return sorted({*globals(), *_LAZY_ATTRIBUTES}) 

138 

139 

140__all__ = [ 

141 "AcquireReturnProxy", 

142 "AsyncAcquireReadWriteReturnProxy", 

143 "AsyncAcquireReturnProxy", 

144 "AsyncAcquireSoftReadWriteReturnProxy", 

145 "AsyncFileLock", 

146 "AsyncReadWriteLock", 

147 "AsyncSoftFileLease", 

148 "AsyncSoftFileLock", 

149 "AsyncSoftReadWriteLock", 

150 "AsyncStrictSoftFileLock", 

151 "AsyncUnixFileLock", 

152 "AsyncWindowsFileLock", 

153 "BaseAsyncFileLock", 

154 "BaseFileLock", 

155 "CloseErrorPolicy", 

156 "CompromiseReason", 

157 "ContextErrorPolicy", 

158 "FileLock", 

159 "LeaseCompromise", 

160 "LeaseSettingsMismatch", 

161 "LockOptions", 

162 "MarkerSoftFileLock", 

163 "OwnerMode", 

164 "OwnerRecord", 

165 "ReadWriteLock", 

166 "SoftFileLease", 

167 "SoftFileLock", 

168 "SoftFileLockLifetimeWarning", 

169 "SoftFileLockProtocolError", 

170 "SoftReadWriteLock", 

171 "StrictSoftFileClaim", 

172 "StrictSoftFileClaimState", 

173 "StrictSoftFileLock", 

174 "Timeout", 

175 "UnixFileLock", 

176 "WindowsFileLock", 

177 "__version__", 

178 "asyncio", 

179 "has_fcntl", 

180 "lock_descriptor", 

181 "unlock_descriptor", 

182]