Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/filelock/_api.py: 72%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1from __future__ import annotations
3import contextlib
4import inspect
5import logging
6import os
7import time
8import warnings
9from abc import ABCMeta, abstractmethod
10from dataclasses import dataclass
11from threading import local
12from typing import TYPE_CHECKING, Any, cast
13from weakref import WeakValueDictionary
15from ._error import Timeout
17#: Sentinel indicating that no explicit file permission mode was passed.
18#: When used, lock files are created with 0o666 (letting umask and default ACLs control the final permissions)
19#: and fchmod is skipped so that POSIX default ACL inheritance is preserved.
20_UNSET_FILE_MODE: int = -1
22if TYPE_CHECKING:
23 import sys
24 from types import TracebackType
26 from ._read_write import ReadWriteLock
28 if sys.version_info >= (3, 11): # pragma: no cover (py311+)
29 from typing import Self
30 else: # pragma: no cover (<py311)
31 from typing_extensions import Self
34_LOGGER = logging.getLogger("filelock")
37# This is a helper class which is returned by :meth:`BaseFileLock.acquire` and wraps the lock to make sure __enter__
38# is not called twice when entering the with statement. If we would simply return *self*, the lock would be acquired
39# again in the *__enter__* method of the BaseFileLock, but not released again automatically. issue #37 (memory leak)
40class AcquireReturnProxy:
41 """A context-aware object that will release the lock file when exiting."""
43 def __init__(self, lock: BaseFileLock | ReadWriteLock) -> None:
44 self.lock: BaseFileLock | ReadWriteLock = lock
46 def __enter__(self) -> BaseFileLock | ReadWriteLock:
47 return self.lock
49 def __exit__(
50 self,
51 exc_type: type[BaseException] | None,
52 exc_value: BaseException | None,
53 traceback: TracebackType | None,
54 ) -> None:
55 self.lock.release()
58@dataclass
59class FileLockContext:
60 """A dataclass which holds the context for a ``BaseFileLock`` object."""
62 # The context is held in a separate class to allow optional use of thread local storage via the
63 # ThreadLocalFileContext class.
65 #: The path to the lock file.
66 lock_file: str
68 #: The default timeout value.
69 timeout: float
71 #: The mode for the lock files
72 mode: int
74 #: Whether the lock should be blocking or not
75 blocking: bool
77 #: The default polling interval value.
78 poll_interval: float
80 #: The file descriptor for the *_lock_file* as it is returned by the os.open() function, not None when lock held
81 lock_file_fd: int | None = None
83 #: The lock counter is used for implementing the nested locking mechanism.
84 lock_counter: int = 0 # When the lock is acquired is increased and the lock is only released, when this value is 0
87class ThreadLocalFileContext(FileLockContext, local):
88 """A thread local version of the ``FileLockContext`` class."""
91class FileLockMeta(ABCMeta):
92 _instances: WeakValueDictionary[str, BaseFileLock]
94 def __call__( # noqa: PLR0913
95 cls,
96 lock_file: str | os.PathLike[str],
97 timeout: float = -1,
98 mode: int = _UNSET_FILE_MODE,
99 thread_local: bool = True, # noqa: FBT001, FBT002
100 *,
101 blocking: bool = True,
102 is_singleton: bool = False,
103 poll_interval: float = 0.05,
104 **kwargs: Any, # capture remaining kwargs for subclasses # noqa: ANN401
105 ) -> BaseFileLock:
106 if is_singleton:
107 instance = cls._instances.get(str(lock_file))
108 if instance:
109 params_to_check = {
110 "thread_local": (thread_local, instance.is_thread_local()),
111 "timeout": (timeout, instance.timeout),
112 "mode": (mode, instance._context.mode), # noqa: SLF001
113 "blocking": (blocking, instance.blocking),
114 "poll_interval": (poll_interval, instance.poll_interval),
115 }
117 non_matching_params = {
118 name: (passed_param, set_param)
119 for name, (passed_param, set_param) in params_to_check.items()
120 if passed_param != set_param
121 }
122 if not non_matching_params:
123 return cast("BaseFileLock", instance)
125 # parameters do not match; raise error
126 msg = "Singleton lock instances cannot be initialized with differing arguments"
127 msg += "\nNon-matching arguments: "
128 for param_name, (passed_param, set_param) in non_matching_params.items():
129 msg += f"\n\t{param_name} (existing lock has {set_param} but {passed_param} was passed)"
130 raise ValueError(msg)
132 # Workaround to make `__init__`'s params optional in subclasses
133 # E.g. virtualenv changes the signature of the `__init__` method in the `BaseFileLock` class descendant
134 # (https://github.com/tox-dev/filelock/pull/340)
136 all_params = {
137 "timeout": timeout,
138 "mode": mode,
139 "thread_local": thread_local,
140 "blocking": blocking,
141 "is_singleton": is_singleton,
142 "poll_interval": poll_interval,
143 **kwargs,
144 }
146 present_params = inspect.signature(cls.__init__).parameters
147 init_params = {key: value for key, value in all_params.items() if key in present_params}
149 instance = super().__call__(lock_file, **init_params)
151 if is_singleton:
152 cls._instances[str(lock_file)] = instance
154 return cast("BaseFileLock", instance)
157class BaseFileLock(contextlib.ContextDecorator, metaclass=FileLockMeta):
158 """
159 Abstract base class for a file lock object.
161 Provides a reentrant, cross-process exclusive lock backed by OS-level primitives. Subclasses implement the
162 actual locking mechanism (:class:`UnixFileLock <filelock.UnixFileLock>`,
163 :class:`WindowsFileLock <filelock.WindowsFileLock>`, :class:`SoftFileLock <filelock.SoftFileLock>`).
164 """
166 _instances: WeakValueDictionary[str, BaseFileLock]
168 def __init_subclass__(cls, **kwargs: dict[str, Any]) -> None:
169 """Setup unique state for lock subclasses."""
170 super().__init_subclass__(**kwargs)
171 cls._instances = WeakValueDictionary()
173 def __init__( # noqa: PLR0913
174 self,
175 lock_file: str | os.PathLike[str],
176 timeout: float = -1,
177 mode: int = _UNSET_FILE_MODE,
178 thread_local: bool = True, # noqa: FBT001, FBT002
179 *,
180 blocking: bool = True,
181 is_singleton: bool = False,
182 poll_interval: float = 0.05,
183 ) -> None:
184 """
185 Create a new lock object.
187 :param lock_file: path to the file
188 :param timeout: default timeout when acquiring the lock, in seconds. It will be used as fallback value in
189 the acquire method, if no timeout value (``None``) is given. If you want to disable the timeout, set it
190 to a negative value. A timeout of 0 means that there is exactly one attempt to acquire the file lock.
191 :param mode: file permissions for the lockfile. When not specified, the OS controls permissions via umask
192 and default ACLs, preserving POSIX default ACL inheritance in shared directories.
193 :param thread_local: Whether this object's internal context should be thread local or not. If this is set
194 to ``False`` then the lock will be reentrant across threads.
195 :param blocking: whether the lock should be blocking or not
196 :param is_singleton: If this is set to ``True`` then only one instance of this class will be created per
197 lock file. This is useful if you want to use the lock object for reentrant locking without needing to
198 pass the same object around.
199 :param poll_interval: default interval for polling the lock file, in seconds. It will be used as fallback
200 value in the acquire method, if no poll_interval value (``None``) is given.
202 """
203 self._is_thread_local = thread_local
204 self._is_singleton = is_singleton
206 # Create the context. Note that external code should not work with the context directly and should instead use
207 # properties of this class.
208 kwargs: dict[str, Any] = {
209 "lock_file": os.fspath(lock_file),
210 "timeout": timeout,
211 "mode": mode,
212 "blocking": blocking,
213 "poll_interval": poll_interval,
214 }
215 self._context: FileLockContext = (ThreadLocalFileContext if thread_local else FileLockContext)(**kwargs)
217 def is_thread_local(self) -> bool:
218 """:return: a flag indicating if this lock is thread local or not"""
219 return self._is_thread_local
221 @property
222 def is_singleton(self) -> bool:
223 """
224 :return: a flag indicating if this lock is singleton or not
226 .. versionadded:: 3.13.0
227 """
228 return self._is_singleton
230 @property
231 def lock_file(self) -> str:
232 """:return: path to the lock file"""
233 return self._context.lock_file
235 @property
236 def timeout(self) -> float:
237 """
238 :return: the default timeout value, in seconds
240 .. versionadded:: 2.0.0
241 """
242 return self._context.timeout
244 @timeout.setter
245 def timeout(self, value: float | str) -> None:
246 """
247 Change the default timeout value.
249 :param value: the new value, in seconds
251 """
252 self._context.timeout = float(value)
254 @property
255 def blocking(self) -> bool:
256 """
257 :return: whether the locking is blocking or not
259 .. versionadded:: 3.14.0
260 """
261 return self._context.blocking
263 @blocking.setter
264 def blocking(self, value: bool) -> None:
265 """
266 Change the default blocking value.
268 :param value: the new value as bool
270 """
271 self._context.blocking = value
273 @property
274 def poll_interval(self) -> float:
275 """
276 :return: the default polling interval, in seconds
278 .. versionadded:: 3.24.0
279 """
280 return self._context.poll_interval
282 @poll_interval.setter
283 def poll_interval(self, value: float) -> None:
284 """
285 Change the default polling interval.
287 :param value: the new value, in seconds
289 """
290 self._context.poll_interval = value
292 @property
293 def mode(self) -> int:
294 """:return: the file permissions for the lockfile"""
295 return 0o644 if self._context.mode == _UNSET_FILE_MODE else self._context.mode
297 @property
298 def has_explicit_mode(self) -> bool:
299 """:return: whether the file permissions were explicitly set"""
300 return self._context.mode != _UNSET_FILE_MODE
302 def _open_mode(self) -> int:
303 """:return: the mode for os.open() — 0o666 when unset (let umask/ACLs decide), else the explicit mode"""
304 return 0o666 if self._context.mode == _UNSET_FILE_MODE else self._context.mode
306 @abstractmethod
307 def _acquire(self) -> None:
308 """If the file lock could be acquired, self._context.lock_file_fd holds the file descriptor of the lock file."""
309 raise NotImplementedError
311 @abstractmethod
312 def _release(self) -> None:
313 """Releases the lock and sets self._context.lock_file_fd to None."""
314 raise NotImplementedError
316 @property
317 def is_locked(self) -> bool:
318 """
319 :return: A boolean indicating if the lock file is holding the lock currently.
321 .. versionchanged:: 2.0.0
323 This was previously a method and is now a property.
324 """
325 return self._context.lock_file_fd is not None
327 @property
328 def lock_counter(self) -> int:
329 """:return: The number of times this lock has been acquired (but not yet released)."""
330 return self._context.lock_counter
332 def acquire(
333 self,
334 timeout: float | None = None,
335 poll_interval: float | None = None,
336 *,
337 poll_intervall: float | None = None,
338 blocking: bool | None = None,
339 ) -> AcquireReturnProxy:
340 """
341 Try to acquire the file lock.
343 :param timeout: maximum wait time for acquiring the lock, ``None`` means use the default :attr:`~timeout`
344 is and if ``timeout < 0``, there is no timeout and this method will block until the lock could be acquired
345 :param poll_interval: interval of trying to acquire the lock file, ``None`` means use the default
346 :attr:`~poll_interval`
347 :param poll_intervall: deprecated, kept for backwards compatibility, use ``poll_interval`` instead
348 :param blocking: defaults to True. If False, function will return immediately if it cannot obtain a lock on
349 the first attempt. Otherwise, this method will block until the timeout expires or the lock is acquired.
350 :raises Timeout: if fails to acquire lock within the timeout period
351 :return: a context object that will unlock the file when the context is exited
353 .. code-block:: python
355 # You can use this method in the context manager (recommended)
356 with lock.acquire():
357 pass
359 # Or use an equivalent try-finally construct:
360 lock.acquire()
361 try:
362 pass
363 finally:
364 lock.release()
366 .. versionchanged:: 2.0.0
368 This method returns now a *proxy* object instead of *self*,
369 so that it can be used in a with statement without side effects.
371 """
372 # Use the default timeout, if no timeout is provided.
373 if timeout is None:
374 timeout = self._context.timeout
376 if blocking is None:
377 blocking = self._context.blocking
379 if poll_intervall is not None:
380 msg = "use poll_interval instead of poll_intervall"
381 warnings.warn(msg, DeprecationWarning, stacklevel=2)
382 poll_interval = poll_intervall
384 poll_interval = poll_interval if poll_interval is not None else self._context.poll_interval
386 # Increment the number right at the beginning. We can still undo it, if something fails.
387 self._context.lock_counter += 1
389 lock_id = id(self)
390 lock_filename = self.lock_file
391 start_time = time.perf_counter()
392 try:
393 while True:
394 if not self.is_locked:
395 _LOGGER.debug("Attempting to acquire lock %s on %s", lock_id, lock_filename)
396 self._acquire()
397 if self.is_locked:
398 _LOGGER.debug("Lock %s acquired on %s", lock_id, lock_filename)
399 break
400 if blocking is False:
401 _LOGGER.debug("Failed to immediately acquire lock %s on %s", lock_id, lock_filename)
402 raise Timeout(lock_filename) # noqa: TRY301
403 if 0 <= timeout < time.perf_counter() - start_time:
404 _LOGGER.debug("Timeout on acquiring lock %s on %s", lock_id, lock_filename)
405 raise Timeout(lock_filename) # noqa: TRY301
406 msg = "Lock %s not acquired on %s, waiting %s seconds ..."
407 _LOGGER.debug(msg, lock_id, lock_filename, poll_interval)
408 time.sleep(poll_interval)
409 except BaseException: # Something did go wrong, so decrement the counter.
410 self._context.lock_counter = max(0, self._context.lock_counter - 1)
411 raise
412 return AcquireReturnProxy(lock=self)
414 def release(self, force: bool = False) -> None: # noqa: FBT001, FBT002
415 """
416 Releases the file lock. Please note, that the lock is only completely released, if the lock counter is 0.
417 Also note, that the lock file itself is not automatically deleted.
419 :param force: If true, the lock counter is ignored and the lock is released in every case.
421 """
422 if self.is_locked:
423 self._context.lock_counter -= 1
425 if self._context.lock_counter == 0 or force:
426 lock_id, lock_filename = id(self), self.lock_file
428 _LOGGER.debug("Attempting to release lock %s on %s", lock_id, lock_filename)
429 self._release()
430 self._context.lock_counter = 0
431 _LOGGER.debug("Lock %s released on %s", lock_id, lock_filename)
433 def __enter__(self) -> Self:
434 """
435 Acquire the lock.
437 :return: the lock object
439 """
440 self.acquire()
441 return self
443 def __exit__(
444 self,
445 exc_type: type[BaseException] | None,
446 exc_value: BaseException | None,
447 traceback: TracebackType | None,
448 ) -> None:
449 """
450 Release the lock.
452 :param exc_type: the exception type if raised
453 :param exc_value: the exception value if raised
454 :param traceback: the exception traceback if raised
456 """
457 self.release()
459 def __del__(self) -> None:
460 """Called when the lock object is deleted."""
461 self.release(force=True)
464__all__ = [
465 "_UNSET_FILE_MODE",
466 "AcquireReturnProxy",
467 "BaseFileLock",
468]