Read/Write File Lock

docs/api.rst

@@ -4,3 +4,7 @@ API
 .. automodule:: filelock
     :members:
     :show-inheritance:
+
+.. automodule:: filelock.read_write
+    :members:
+    :show-inheritance:

docs/index.rst

@@ -191,8 +191,19 @@ cases.
 Asyncio support
 ---------------
 
-This library currently does not support asyncio. We'd recommend adding an asyncio variant though if someone can make a
-pull request for it, `see here <https://github.com/tox-dev/py-filelock/issues/99>`_.
+This library supports asyncio. See :class:`AsyncFileLock <filelock.AsyncFileLock>`.
+
+Read/write FileLock
+-------------------
+
+An implementation of a read/write FileLock is also available: and :class:`ReadWriteFileLockWrapper <filelock.read_write.ReadWriteFileLockWrapper>` and
+:class:`AsyncReadWriteFileLockWrapper <filelock.read_write.AsyncReadWriteFileLockWrapper>`.
+
+Multiple readers can hold the lock at the same time, but a writer is guaranteed to hold the lock exclusively across both readers and writers.
+
+The lock is writer-preferring on a best effort basis (there are no guarantees).
+
+Currently, this FileLock type is implemented only for Unix.
 
 FileLocks and threads
 ---------------------

src/filelock/__init__.py

@@ -12,13 +12,14 @@
 import warnings
 from typing import TYPE_CHECKING
 
-from ._api import AcquireReturnProxy, BaseFileLock
+from ._api import AcquireReturnProxy, BaseFileLock, LockProtocol
 from ._error import Timeout
 from ._soft import SoftFileLock
 from ._unix import UnixFileLock, has_fcntl
 from ._windows import WindowsFileLock
 from .asyncio import (
     AsyncAcquireReturnProxy,
+    AsyncLockProtocol,
     AsyncSoftFileLock,
     AsyncUnixFileLock,
     AsyncWindowsFileLock,
@@ -56,12 +57,14 @@
     "AcquireReturnProxy",
     "AsyncAcquireReturnProxy",
     "AsyncFileLock",
+    "AsyncLockProtocol",
     "AsyncSoftFileLock",
     "AsyncUnixFileLock",
     "AsyncWindowsFileLock",
     "BaseAsyncFileLock",
     "BaseFileLock",
     "FileLock",
+    "LockProtocol",
     "SoftFileLock",
     "Timeout",
     "UnixFileLock",

src/filelock/_api.py

@@ -9,7 +9,7 @@
 from abc import ABCMeta, abstractmethod
 from dataclasses import dataclass
 from threading import local
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, Protocol, cast
 from weakref import WeakValueDictionary
 
 from ._error import Timeout
@@ -26,17 +26,37 @@
 
 _LOGGER = logging.getLogger("filelock")
 
+DEFAULT_POLL_INTERVAL = 0.05
+
+
+class LockProtocol(Protocol):
+    """Protocol for objects implementing ``acquire`` and ``release`` methods."""
+
+    @abstractmethod
+    def acquire(
+        self,
+        timeout: float | None = None,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        *,
+        poll_intervall: float | None = None,
+        blocking: bool | None = None,
+    ) -> AcquireReturnProxy: ...
+
+    @abstractmethod
+    def release(self, force: bool = False) -> None:  # noqa: FBT001, FBT002
+        ...
+
 
 # This is a helper class which is returned by :meth:`BaseFileLock.acquire` and wraps the lock to make sure __enter__
 # is not called twice when entering the with statement. If we would simply return *self*, the lock would be acquired
 # again in the *__enter__* method of the BaseFileLock, but not released again automatically. issue #37 (memory leak)
 class AcquireReturnProxy:
     """A context-aware object that will release the lock file when exiting."""
 
-    def __init__(self, lock: BaseFileLock) -> None:
+    def __init__(self, lock: LockProtocol) -> None:
         self.lock = lock
 
-    def __enter__(self) -> BaseFileLock:
+    def __enter__(self) -> LockProtocol:
         return self.lock
 
     def __exit__(
@@ -271,7 +291,7 @@ def lock_counter(self) -> int:
     def acquire(
         self,
         timeout: float | None = None,
-        poll_interval: float = 0.05,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
         *,
         poll_intervall: float | None = None,
         blocking: bool | None = None,

src/filelock/_unix.py

@@ -23,6 +23,10 @@ def _acquire(self) -> None:
         def _release(self) -> None:
             raise NotImplementedError
 
+    class NonExclusiveUnixFileLock(UnixFileLock):
+        """Uses the :func:`fcntl.flock` to non-exclusively lock the lock file on unix systems."""
+
+
 else:  # pragma: win32 no cover
     try:
         import fcntl
@@ -34,6 +38,8 @@ def _release(self) -> None:
     class UnixFileLock(BaseFileLock):
         """Uses the :func:`fcntl.flock` to hard lock the lock file on unix systems."""
 
+        _fcntl_mode: int = fcntl.LOCK_EX
+
         def _acquire(self) -> None:
             ensure_directory_exists(self.lock_file)
             open_flags = os.O_RDWR | os.O_TRUNC
@@ -43,7 +49,7 @@ def _acquire(self) -> None:
             with suppress(PermissionError):  # This locked is not owned by this UID
                 os.fchmod(fd, self._context.mode)
             try:
-                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                fcntl.flock(fd, self._fcntl_mode | fcntl.LOCK_NB)
             except OSError as exception:
                 os.close(fd)
                 if exception.errno == ENOSYS:  # NotImplemented error
@@ -61,8 +67,14 @@ def _release(self) -> None:
             fcntl.flock(fd, fcntl.LOCK_UN)
             os.close(fd)
 
+    class NonExclusiveUnixFileLock(UnixFileLock):
+        """Uses the :func:`fcntl.flock` to non-exclusively lock the lock file on unix systems."""
+
+        _fcntl_mode = fcntl.LOCK_SH
+
 
 __all__ = [
+    "NonExclusiveUnixFileLock",
     "UnixFileLock",
     "has_fcntl",
 ]

src/filelock/asyncio.py

@@ -7,14 +7,15 @@
 import logging
 import os
 import time
+from abc import abstractmethod
 from dataclasses import dataclass
 from threading import local
-from typing import TYPE_CHECKING, Any, Callable, NoReturn, cast
+from typing import TYPE_CHECKING, Any, Callable, NoReturn, Protocol, cast
 
-from ._api import BaseFileLock, FileLockContext, FileLockMeta
+from ._api import DEFAULT_POLL_INTERVAL, BaseFileLock, FileLockContext, FileLockMeta
 from ._error import Timeout
 from ._soft import SoftFileLock
-from ._unix import UnixFileLock
+from ._unix import NonExclusiveUnixFileLock, UnixFileLock
 from ._windows import WindowsFileLock
 
 if TYPE_CHECKING:
@@ -31,6 +32,23 @@
 _LOGGER = logging.getLogger("filelock")
 
 
+class AsyncLockProtocol(Protocol):
+    """Protocol for async objects implementing ``acquire`` and ``release`` methods."""
+
+    @abstractmethod
+    async def acquire(
+        self,
+        timeout: float | None = None,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        *,
+        blocking: bool | None = None,
+    ) -> AsyncAcquireReturnProxy: ...
+
+    @abstractmethod
+    async def release(self, force: bool = False) -> None:  # noqa: FBT001, FBT002
+        ...
+
+
 @dataclass
 class AsyncFileLockContext(FileLockContext):
     """A dataclass which holds the context for a ``BaseAsyncFileLock`` object."""
@@ -52,10 +70,10 @@ class AsyncThreadLocalFileContext(AsyncFileLockContext, local):
 class AsyncAcquireReturnProxy:
     """A context-aware object that will release the lock file when exiting."""
 
-    def __init__(self, lock: BaseAsyncFileLock) -> None:  # noqa: D107
+    def __init__(self, lock: AsyncLockProtocol) -> None:  # noqa: D107
         self.lock = lock
 
-    async def __aenter__(self) -> BaseAsyncFileLock:  # noqa: D105
+    async def __aenter__(self) -> AsyncLockProtocol:  # noqa: D105
         return self.lock
 
     async def __aexit__(  # noqa: D105
@@ -180,7 +198,7 @@ def loop(self) -> asyncio.AbstractEventLoop | None:
     async def acquire(  # type: ignore[override]
         self,
         timeout: float | None = None,
-        poll_interval: float = 0.05,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
         *,
         blocking: bool | None = None,
     ) -> AsyncAcquireReturnProxy:
@@ -329,12 +347,17 @@ class AsyncUnixFileLock(UnixFileLock, BaseAsyncFileLock):
     """Uses the :func:`fcntl.flock` to hard lock the lock file on unix systems."""
 
 
+class AsyncNonExclusiveUnixFileLock(NonExclusiveUnixFileLock, BaseAsyncFileLock):
+    """Uses the :func:`fcntl.flock` to non-exclusively lock the lock file on unix systems."""
+
+
 class AsyncWindowsFileLock(WindowsFileLock, BaseAsyncFileLock):
     """Uses the :func:`msvcrt.locking` to hard lock the lock file on windows systems."""
 
 
 __all__ = [
     "AsyncAcquireReturnProxy",
+    "AsyncNonExclusiveUnixFileLock",
     "AsyncSoftFileLock",
     "AsyncUnixFileLock",
     "AsyncWindowsFileLock",

src/filelock/read_write/__init__.py

@@ -0,0 +1,64 @@
+"""Read/write file lock."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from filelock._unix import NonExclusiveUnixFileLock, UnixFileLock, has_fcntl
+from filelock.read_write._api import BaseReadWriteFileLock, ReadWriteMode, _DisabledReadWriteFileLock
+from filelock.read_write._wrapper import BaseReadWriteFileLockWrapper, _DisabledReadWriteFileLockWrapper
+from filelock.read_write.asyncio import (
+    AsyncReadWriteFileLock,
+    AsyncReadWriteFileLockWrapper,
+    BaseAsyncReadWriteFileLock,
+    BaseAsyncReadWriteFileLockWrapper,
+    UnixAsyncReadWriteFileLock,
+    UnixAsyncReadWriteFileLockWrapper,
+)
+
+if TYPE_CHECKING:
+    from filelock._api import BaseFileLock
+
+ReadWriteFileLock: type[BaseReadWriteFileLock]
+ReadWriteFileLockWrapper: type[BaseReadWriteFileLockWrapper]
+
+
+class UnixReadWriteFileLock(BaseReadWriteFileLock):
+    """Unix implementation of a read/write FileLock."""
+
+    _shared_file_lock_cls: type[BaseFileLock] = NonExclusiveUnixFileLock
+    _exclusive_file_lock_cls: type[BaseFileLock] = UnixFileLock
+
+
+class UnixReadWriteFileLockWrapper(BaseReadWriteFileLockWrapper):
+    """Wrapper for a Unix implementation of a read/write FileLock."""
+
+    _read_write_file_lock_cls = UnixReadWriteFileLock
+
+
+if has_fcntl:  # pragma: win32 no cover
+    ReadWriteFileLock = UnixReadWriteFileLock
+    ReadWriteFileLockWrapper = UnixReadWriteFileLockWrapper
+    has_read_write_file_lock = True
+else:  # pragma: win32 cover
+    ReadWriteFileLock = _DisabledReadWriteFileLock
+    ReadWriteFileLockWrapper = _DisabledReadWriteFileLockWrapper
+    has_read_write_file_lock = False
+
+
+__all__ = [
+    "AsyncReadWriteFileLock",
+    "AsyncReadWriteFileLockWrapper",
+    "BaseAsyncReadWriteFileLock",
+    "BaseAsyncReadWriteFileLockWrapper",
+    "BaseReadWriteFileLock",
+    "BaseReadWriteFileLockWrapper",
+    "ReadWriteFileLock",
+    "ReadWriteFileLockWrapper",
+    "ReadWriteMode",
+    "UnixAsyncReadWriteFileLock",
+    "UnixAsyncReadWriteFileLockWrapper",
+    "UnixReadWriteFileLock",
+    "UnixReadWriteFileLockWrapper",
+    "has_read_write_file_lock",
+]