From eac90624eb3a220d2fb14a0d349ed2c68f7111a2 Mon Sep 17 00:00:00 2001 From: Antoni Baum Date: Sun, 1 Dec 2024 20:48:41 -0800 Subject: [PATCH] Docs --- docs/conf.py | 2 +- src/filelock/read_write/__init__.py | 20 ++++++++++++++++++++ src/filelock/read_write/_wrapper.py | 8 +++++++- src/filelock/read_write/asyncio/__init__.py | 18 ++++++++++++++++-- src/filelock/read_write/asyncio/_api.py | 3 +-- src/filelock/read_write/asyncio/_wrapper.py | 1 + 6 files changed, 46 insertions(+), 6 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ed569a1..08e5d9e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,7 +38,7 @@ intersphinx_mapping = {"python": ("https://docs.python.org/3", None)} nitpicky = True -nitpick_ignore = [("py_class", "filelock.asyncio.AsyncReleasable"), ("py_class", "filelock._api.Releasable")] +nitpick_ignore = [("py:class", "filelock.asyncio.AsyncReleasable"), ("py:class", "filelock._api.Releasable")] extlinks = { "issue": ("https://github.com/tox-dev/py-filelock/issues/%s", "issue #%s"), "pr": ("https://github.com/tox-dev/py-filelock/issues/%s", "PR #%s"), diff --git a/src/filelock/read_write/__init__.py b/src/filelock/read_write/__init__.py index 209d31f..5ce8d95 100644 --- a/src/filelock/read_write/__init__.py +++ b/src/filelock/read_write/__init__.py @@ -17,6 +17,9 @@ AsyncReadWriteFileLock, AsyncReadWriteFileLockWrapper, BaseAsyncReadWriteFileLock, + BaseAsyncReadWriteFileLockWrapper, + UnixAsyncReadWriteFileLock, + UnixAsyncReadWriteFileLockWrapper, ) if TYPE_CHECKING: @@ -28,16 +31,27 @@ if has_fcntl: 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 ReadWriteFileLock = UnixReadWriteFileLock ReadWriteFileLockWrapper = UnixReadWriteFileLockWrapper has_read_write_file_lock = True else: + + class UnixReadWriteFileLock(BaseReadWriteFileLock): + """Unix implementation of a read/write FileLock.""" + + class UnixReadWriteFileLockWrapper(BaseReadWriteFileLockWrapper): + """Wrapper for a Unix implementation of a read/write FileLock.""" + ReadWriteFileLock = _DisabledReadWriteFileLock ReadWriteFileLockWrapper = _DisabledReadWriteFileLockWrapper has_read_write_file_lock = False @@ -47,9 +61,15 @@ class UnixReadWriteFileLockWrapper(BaseReadWriteFileLockWrapper): "AsyncReadWriteFileLock", "AsyncReadWriteFileLockWrapper", "BaseAsyncReadWriteFileLock", + "BaseAsyncReadWriteFileLockWrapper", "BaseReadWriteFileLock", + "BaseReadWriteFileLockWrapper", "ReadWriteFileLock", "ReadWriteFileLockWrapper", "ReadWriteMode", + "UnixAsyncReadWriteFileLock", + "UnixAsyncReadWriteFileLockWrapper", + "UnixReadWriteFileLock", + "UnixReadWriteFileLockWrapper", "has_read_write_file_lock", ] diff --git a/src/filelock/read_write/_wrapper.py b/src/filelock/read_write/_wrapper.py index 5aec714..a1b626b 100644 --- a/src/filelock/read_write/_wrapper.py +++ b/src/filelock/read_write/_wrapper.py @@ -10,6 +10,12 @@ class BaseReadWriteFileLockWrapper(ABC): + """ + Convenience wrapper for read/write locks. + + Provides `.read()` and `.write()` methods to easily access a read or write lock. + """ + _read_write_file_lock_cls: type[BaseReadWriteFileLock] def __init__( # noqa: PLR0913 @@ -26,7 +32,7 @@ def __init__( # noqa: PLR0913 """ Convenience wrapper for read/write locks. - See filelock.read_write.ReadWriteFileLock for description of the parameters. + See ReadWriteFileLock for description of the parameters. """ self.read_lock = self._read_write_file_lock_cls( lock_file=lock_file, diff --git a/src/filelock/read_write/asyncio/__init__.py b/src/filelock/read_write/asyncio/__init__.py index e901790..a6af37b 100644 --- a/src/filelock/read_write/asyncio/__init__.py +++ b/src/filelock/read_write/asyncio/__init__.py @@ -28,15 +28,26 @@ if has_fcntl: class UnixAsyncReadWriteFileLock(BaseAsyncReadWriteFileLock): + """Unix implementation of an async read/write FileLock.""" + _shared_file_lock_cls: type[BaseAsyncFileLock] = AsyncNonExclusiveUnixFileLock _exclusive_file_lock_cls: type[BaseAsyncFileLock] = AsyncUnixFileLock - class UnixReadWriteFileLockWrapper(BaseAsyncReadWriteFileLockWrapper): + class UnixAsyncReadWriteFileLockWrapper(BaseAsyncReadWriteFileLockWrapper): + """Wrapper for a Unix implementation of an async read/write FileLock.""" + _read_write_file_lock_cls = UnixAsyncReadWriteFileLock AsyncReadWriteFileLock = UnixAsyncReadWriteFileLock - AsyncReadWriteFileLockWrapper = UnixReadWriteFileLockWrapper + AsyncReadWriteFileLockWrapper = UnixAsyncReadWriteFileLockWrapper else: + + class UnixAsyncReadWriteFileLock(BaseAsyncReadWriteFileLock): + """Unix implementation of an async read/write FileLock.""" + + class UnixAsyncReadWriteFileLockWrapper(BaseAsyncReadWriteFileLockWrapper): + """Wrapper for a Unix implementation of an async read/write FileLock.""" + AsyncReadWriteFileLock = _DisabledAsyncReadWriteFileLock AsyncReadWriteFileLockWrapper = _DisabledAsyncReadWriteFileLockWrapper @@ -45,4 +56,7 @@ class UnixReadWriteFileLockWrapper(BaseAsyncReadWriteFileLockWrapper): "AsyncReadWriteFileLock", "AsyncReadWriteFileLockWrapper", "BaseAsyncReadWriteFileLock", + "BaseAsyncReadWriteFileLockWrapper", + "UnixAsyncReadWriteFileLock", + "UnixAsyncReadWriteFileLockWrapper", ] diff --git a/src/filelock/read_write/asyncio/_api.py b/src/filelock/read_write/asyncio/_api.py index 353c27a..7f0f6a4 100644 --- a/src/filelock/read_write/asyncio/_api.py +++ b/src/filelock/read_write/asyncio/_api.py @@ -127,7 +127,7 @@ async def acquire( # type: ignore[override] Try to acquire the file lock. :param timeout: maximum wait time for acquiring the lock, ``None`` means use the default - :attr:`~BaseFileLock.timeout` is and if ``timeout < 0``, there is no timeout and + :attr:`filelock.BaseFileLock.timeout` is and if ``timeout < 0``, there is no timeout and this method will block until the lock could be acquired :param poll_interval: interval of trying to acquire the lock file :param blocking: defaults to True. If False, function will return immediately if it cannot obtain a lock on the @@ -237,5 +237,4 @@ def __init__(self, *args, **kwargs) -> None: # type: ignore[no-untyped-def] # __all__ = [ "BaseAsyncReadWriteFileLock", - "_DisabledAsyncReadWriteFileLock", ] diff --git a/src/filelock/read_write/asyncio/_wrapper.py b/src/filelock/read_write/asyncio/_wrapper.py index 66a89e9..f18b1b9 100644 --- a/src/filelock/read_write/asyncio/_wrapper.py +++ b/src/filelock/read_write/asyncio/_wrapper.py @@ -16,6 +16,7 @@ class BaseAsyncReadWriteFileLockWrapper(BaseReadWriteFileLockWrapper): """ Convenience wrapper class for async read/write locks. + Provides `.read()` and `.write()` methods to easily access a read or write lock. """