stouputils 1.16.3__py3-none-any.whl → 1.17.0__py3-none-any.whl

stouputils/lock/re_entrant.py

@@ -0,0 +1,115 @@
+
+# Imports
+import os
+from typing import ClassVar
+
+from .base import LockFifo
+
+
+class RLockFifo(LockFifo):
+    """ A re-entrant cross-process lock backed by a file.
+
+    This lock is re-entrant for the same owner, where owner identity is the
+    tuple ``(path, pid, thread_id)``. Repeated calls to :meth:`acquire` by the
+    same owner increment an internal counter; only the final :meth:`release`
+    will release the underlying file lock managed by :class:`LockFifo`.
+
+    Key behaviour:
+      - Owner identity: (path, pid, thread_id)
+      - Reentrancy applies only within the same thread of the same process.
+        Other threads or processes will block (or raise ``LockTimeoutError``)
+        according to the lock's timeout and blocking parameters.
+      - Implemented on top of :class:`LockFifo` and shares its constructor
+        parameters and error semantics.
+
+    Args:
+        name               (str):           Lock filename or path. If a simple name is given,
+            it is created in the system temporary directory.
+        timeout            (float | None):  Seconds to wait for the lock. ``None`` means block indefinitely.
+        blocking           (bool):          Whether to block until acquired (subject to ``timeout``).
+        check_interval     (float):         Interval between lock attempts, in seconds.
+        fifo               (bool):          Whether to enforce Fifo ordering (default: True).
+        fifo_stale_timeout (float | None):  Seconds after which a ticket is considered stale; if ``None`` the lock's ``timeout`` value will be used.
+
+    Raises:
+        LockTimeoutError: If the lock could not be acquired within the timeout (LockError & TimeoutError subclass)
+        LockError: On unexpected locking errors. (RunTimeError subclass)
+
+    Examples:
+        >>> with RLockFifo("my.lock", timeout=5):
+        ...     # critical section
+        ...     pass
+
+        >>> lock = RLockFifo("my.lock")
+        >>> lock.acquire()
+        >>> lock.acquire()  # re-entrant acquire by same thread/process
+        >>> lock.release()
+        >>> lock.release()  # underlying lock released here
+
+        >>> # Reentrancy with Fifo enabled should not create multiple tickets
+        >>> lock = RLockFifo("my_r.lock", fifo=True, timeout=1)
+        >>> lock.acquire()
+        >>> lock.acquire()
+        >>> lock.release()
+        >>> lock.release()
+
+        >>> # Cleanup behaviour: after closing a re-entrant lock the queue should be removed when empty
+        >>> import tempfile, os
+        >>> tmp = tempfile.mkdtemp()
+        >>> p = tmp + "/rlock"
+        >>> r = RLockFifo(p, fifo=True, timeout=1)
+        >>> r.acquire(); r.acquire(); r.release(); r.release(); r.close()
+        >>> os.path.exists(p + ".queue")
+        False
+    """
+    owners: ClassVar[dict[tuple[str, int, int], int]] = {}
+    """ Mapping of owner keys to re-entrant acquisition counts. """
+
+    def __init__(
+        self,
+        name: str,
+        timeout: float | None = None,
+        blocking: bool = True,
+        check_interval: float = 0.05,
+        fifo: bool = True,
+        fifo_stale_timeout: float | None = None
+    ) -> None:
+        """ Initialize the re-entrant lock and compute owner key.
+
+        The attribute ``self.key`` is a tuple ``(path, pid, thread_id)`` used to
+        track ownership and re-entrant acquisition counts in the
+        :class:`owners` mapping.
+        """
+        super().__init__(name, timeout=timeout, blocking=blocking, check_interval=check_interval, fifo=fifo, fifo_stale_timeout=fifo_stale_timeout)
+        self.key: tuple[str, int, int] = (self.path, os.getpid(), __import__("threading").get_ident())
+
+    def acquire(self, timeout: float | None = None, blocking: bool | None = None, check_interval: float | None = None) -> None:
+        """ Acquire the lock with re-entrancy for the same owner.
+
+        If the current owner (same ``self.key``) already holds the lock, the
+        internal counter is incremented and the underlying file lock is not
+        re-acquired. Otherwise this delegates to :meth:`LockFifo.acquire`.
+        """
+        cnt: int = self.owners.get(self.key, 0)
+        if cnt > 0:
+            self.owners[self.key] = cnt + 1
+            return
+        super().acquire(timeout=timeout, blocking=blocking, check_interval=check_interval)
+        self.owners[self.key] = 1
+
+    def release(self) -> None:
+        """ Release the lock for this owner.
+
+        Decrements the re-entrant counter for the current owner and only when
+        the counter reaches zero the underlying :class:`LockFifo` is released.
+        """
+        cnt: int = self.owners.get(self.key, 0)
+        if cnt <= 1:
+            # last release: release underlying lock
+            try:
+                super().release()
+            finally:
+                self.owners.pop(self.key, None)
+        else:
+            self.owners[self.key] = cnt - 1
+

stouputils/lock/re_entrant.pyi

@@ -0,0 +1,81 @@
+from .base import LockFifo as LockFifo
+from typing import ClassVar
+
+class RLockFifo(LockFifo):
+    ''' A re-entrant cross-process lock backed by a file.
+
+    This lock is re-entrant for the same owner, where owner identity is the
+    tuple ``(path, pid, thread_id)``. Repeated calls to :meth:`acquire` by the
+    same owner increment an internal counter; only the final :meth:`release`
+    will release the underlying file lock managed by :class:`LockFifo`.
+
+    Key behaviour:
+      - Owner identity: (path, pid, thread_id)
+      - Reentrancy applies only within the same thread of the same process.
+        Other threads or processes will block (or raise ``LockTimeoutError``)
+        according to the lock\'s timeout and blocking parameters.
+      - Implemented on top of :class:`LockFifo` and shares its constructor
+        parameters and error semantics.
+
+    Args:
+        name               (str):           Lock filename or path. If a simple name is given,
+            it is created in the system temporary directory.
+        timeout            (float | None):  Seconds to wait for the lock. ``None`` means block indefinitely.
+        blocking           (bool):          Whether to block until acquired (subject to ``timeout``).
+        check_interval     (float):         Interval between lock attempts, in seconds.
+        fifo               (bool):          Whether to enforce Fifo ordering (default: True).
+        fifo_stale_timeout (float | None):  Seconds after which a ticket is considered stale; if ``None`` the lock\'s ``timeout`` value will be used.
+
+    Raises:
+        LockTimeoutError: If the lock could not be acquired within the timeout (LockError & TimeoutError subclass)
+        LockError: On unexpected locking errors. (RunTimeError subclass)
+
+    Examples:
+        >>> with RLockFifo("my.lock", timeout=5):
+        ...     # critical section
+        ...     pass
+
+        >>> lock = RLockFifo("my.lock")
+        >>> lock.acquire()
+        >>> lock.acquire()  # re-entrant acquire by same thread/process
+        >>> lock.release()
+        >>> lock.release()  # underlying lock released here
+
+        >>> # Reentrancy with Fifo enabled should not create multiple tickets
+        >>> lock = RLockFifo("my_r.lock", fifo=True, timeout=1)
+        >>> lock.acquire()
+        >>> lock.acquire()
+        >>> lock.release()
+        >>> lock.release()
+
+        >>> # Cleanup behaviour: after closing a re-entrant lock the queue should be removed when empty
+        >>> import tempfile, os
+        >>> tmp = tempfile.mkdtemp()
+        >>> p = tmp + "/rlock"
+        >>> r = RLockFifo(p, fifo=True, timeout=1)
+        >>> r.acquire(); r.acquire(); r.release(); r.release(); r.close()
+        >>> os.path.exists(p + ".queue")
+        False
+    '''
+    owners: ClassVar[dict[tuple[str, int, int], int]]
+    key: tuple[str, int, int]
+    def __init__(self, name: str, timeout: float | None = None, blocking: bool = True, check_interval: float = 0.05, fifo: bool = True, fifo_stale_timeout: float | None = None) -> None:
+        """ Initialize the re-entrant lock and compute owner key.
+
+        The attribute ``self.key`` is a tuple ``(path, pid, thread_id)`` used to
+        track ownership and re-entrant acquisition counts in the
+        :class:`owners` mapping.
+        """
+    def acquire(self, timeout: float | None = None, blocking: bool | None = None, check_interval: float | None = None) -> None:
+        """ Acquire the lock with re-entrancy for the same owner.
+
+        If the current owner (same ``self.key``) already holds the lock, the
+        internal counter is incremented and the underlying file lock is not
+        re-acquired. Otherwise this delegates to :meth:`LockFifo.acquire`.
+        """
+    def release(self) -> None:
+        """ Release the lock for this owner.
+
+        Decrements the re-entrant counter for the current owner and only when
+        the counter reaches zero the underlying :class:`LockFifo` is released.
+        """

stouputils/lock/redis_fifo.py

@@ -0,0 +1,299 @@
+
+# Imports
+from __future__ import annotations
+
+import time
+import uuid
+from collections.abc import Awaitable
+from contextlib import AbstractContextManager
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import redis
+
+from .shared import LockError, LockTimeoutError
+
+
+class RedisLockFifo(AbstractContextManager["RedisLockFifo"]):
+    """ A Redis-backed inter-process lock (requires `redis`).
+
+    This lock provides optional Fifo fairness (enabled by default) and is
+    implemented using atomic Redis primitives. Acquisition of the underlying
+    lock uses an owner token and `SET NX` (with optional PX expiry when a
+    timeout/TTL is specified). When Fifo is enabled the implementation uses
+    a small ticket queue using `INCR` + `ZADD` and only the queue head attempts
+    to `SET NX`. Release uses an atomic Lua script to ensure only the token
+    owner can delete the lock key.
+
+    Notes:
+      - The lock stores a locally-generated random token; releasing without the
+        correct token has no effect on the remote key.
+      - When Fifo is enabled, queue entries are removed when the client acquires
+        the lock; stale queue entries (from crashed clients) are removed lazily
+        when their age exceeds ``fifo_stale_timeout`` (defaults to ``timeout`` if
+        ``None``).
+      - This class raises ``ImportError`` if the ``redis`` package is not
+        installed and raises ``LockTimeoutError`` / ``LockError`` for runtime
+        acquisition errors.
+
+    Args:
+        name               (str):           Redis key name used for the lock.
+        redis_client       (redis.Redis | None): Optional Redis client. A client is created lazily if not provided.
+        timeout            (float | None):  Maximum time to wait for the lock and (when provided) the lock TTL used by ``SET PX`` in seconds. ``None`` means block indefinitely and no automatic expiry.
+        blocking           (bool):          Whether to block until acquired (subject to ``timeout``).
+        check_interval     (float):         Poll interval while waiting for the lock, in seconds.
+        fifo               (bool):          Whether to enforce Fifo ordering using a ZSET queue (default: True).
+        fifo_stale_timeout (float | None):  Seconds after which a queue entry is considered stale; if ``None`` the lock's ``timeout`` value will be used; if both are ``None``, no stale cleanup is performed.
+
+    Raises:
+        ImportError: If the ``redis`` package is not installed.
+        LockTimeoutError: If the lock cannot be acquired within ``timeout``.
+        LockError: On unexpected redis errors.
+
+    Examples:
+        >>> # Redis-backed examples; run only on non-Windows environments
+        >>> def _redis_doctest():
+        ...     import redis, time
+        ...     client = redis.Redis()
+        ...
+        ...     # Simple usage (assumes redis is available in the test environment)
+        ...     with RedisLockFifo('test:lock', timeout=1):
+        ...         pass
+        ...
+        ...     # Non-Fifo usage example
+        ...     with RedisLockFifo('test:lock', fifo=False, timeout=1):
+        ...         pass
+        ...
+        ...     # Fifo stale-ticket behaviour (requires a local redis server)
+        ...     # Inject a stale head entry
+        ...     name = 'doctest:lock:stale'
+        ...     _ = client.delete(f"{name}:queue")
+        ...     _ = client.delete(f"{name}:seq")
+        ...     _ = client.delete(name)
+        ...     old_ts = int((time.time() - 10) * 1000)
+        ...     _ = client.zadd(f"{name}:queue", {f"1:stale:{old_ts}": 1})
+        ...     # Now acquire with small stale timeout which should remove head then succeed
+        ...     with RedisLockFifo(name, fifo=True, fifo_stale_timeout=0.01, timeout=1):
+        ...         print('acquired')
+        ...     _ = client.delete(f"{name}:queue")
+        ...     _ = client.delete(f"{name}:seq")
+        ...     _ = client.delete(name)
+        ...     # After using the lock, the queue keys should be removed when empty
+        ...     with RedisLockFifo(name, timeout=1):
+        ...         pass
+        ...     print(client.exists(f"{name}:queue") == 0 and client.exists(f"{name}:seq") == 0)
+        ...
+        ...     # Non-Fifo acquisition should not create queue keys
+        ...     name2 = 'doctest:lock:nonfifo'
+        ...     _ = client.delete(f"{name2}:queue"); _ = client.delete(f"{name2}:seq")
+        ...     with RedisLockFifo(name2, fifo=False, timeout=1):
+        ...         pass
+        ...     print(client.exists(f"{name2}:queue") == 0 and client.exists(f"{name2}:seq") == 0)
+        ...
+        >>> import os
+        >>> if os.name != 'nt':
+        ...     _redis_doctest()
+        ... else:
+        ...     print("acquired\\nTrue\\nTrue")
+        acquired
+        True
+        True
+    """  # noqa: E501
+
+
+    RELEASE_SCRIPT: str = """
+    if redis.call('get', KEYS[1]) == ARGV[1] then
+        return redis.call('del', KEYS[1])
+    else
+        return 0
+    end
+    """
+
+    def __init__(
+        self,
+        name: str,
+        redis_client: redis.Redis | None = None,
+        timeout: float | None = None,
+        blocking: bool = True,
+        check_interval: float = 0.05,
+        fifo: bool = True,
+        fifo_stale_timeout: float | None = None
+    ) -> None:
+        try:
+            import redis  # type: ignore  # noqa: F401
+        except (ImportError, ModuleNotFoundError) as e:
+            raise ImportError("`redis` package is not installed; Please install it to use RedisLockFifo.") from e
+        self.name: str = name
+        self.client: redis.Redis | None = redis_client
+        self.timeout: float | None = timeout
+        self.blocking: bool = blocking
+        self.check_interval: float = check_interval
+        self.fifo: bool = fifo
+        self.fifo_stale_timeout: float | None = fifo_stale_timeout
+        self.token: str | None = None
+        self.queue_member: str | None = None
+        # Lazy queue backend; created on first Fifo acquisition
+        self.queue = None
+
+
+    def ensure_client(self) -> redis.Redis:
+        """ Ensure a ``redis.Redis`` client is available (lazy creation). """
+        if self.client is None:
+            import redis
+            self.client = redis.Redis()
+        return self.client
+
+    def _cleanup_stalequeue(self) -> None:
+        """ Remove a stale head member from the queue if it exceeds the stale timeout. """
+        if not self.fifo:
+            return
+        # Determine effective stale timeout (seconds)
+        stale: float | None = self.fifo_stale_timeout if self.fifo_stale_timeout is not None else self.timeout
+        if stale is None:
+            return
+        client: redis.Redis = self.ensure_client()
+        try:
+            head: Awaitable[Any] | Any = client.zrange(f"{self.name}:queue", 0, 0) # type: ignore
+            if not head:
+                return
+            head_member = str(head[0].decode()) # type: ignore
+            # member format: ticket:token:ts_ms
+            parts: list[str] = head_member.split(":")
+            if len(parts) < 3:
+                return
+            ts_ms: int = int(parts[2])
+            age: float = (time.monotonic() * 1000) - ts_ms
+            if age >= (stale * 1000):
+                try:
+                    client.zrem(f"{self.name}:queue", head_member)
+                except Exception:
+                    pass
+        except Exception:
+            pass
+
+    def acquire(self, timeout: float | None = None, blocking: bool | None = None, check_interval: float | None = None) -> None:
+        """ Acquire the Redis lock.
+
+        When Fifo is enabled (default), this function obtains a ticket via INCR
+        and registers it in a ZSET. The client waits until its ticket is the
+        head of the queue and then attempts to SET NX the lock key.
+        """
+        # Use instance defaults if parameters not provided
+        if blocking is None:
+            blocking = self.blocking
+        if timeout is None:
+            timeout = self.timeout
+        if check_interval is None:
+            check_interval = self.check_interval
+        deadline: float | None = None if timeout is None else (time.monotonic() + timeout)
+        self.client = self.ensure_client()
+        token: str = uuid.uuid4().hex
+
+        # Non-Fifo fast path
+        if not self.fifo:
+            while True:
+                px: int | None = None if timeout is None else int((timeout or 0) * 1000)
+                try:
+                    ok: Any = self.client.set(self.name, token, nx=True, px=px)
+                except Exception as exc:
+                    raise LockError(str(exc)) from exc
+                if ok:
+                    self.token = token
+                    return
+                if not blocking:
+                    raise LockTimeoutError("Lock is already held and blocking is False")
+                if deadline is not None and time.monotonic() >= deadline:
+                    raise LockTimeoutError(f"Timeout while waiting for redis lock '{self.name}'")
+                time.sleep(check_interval)
+
+        # Fifo path using RedisTicketQueue backend
+        try:
+            if self.queue is None:
+                from .queue import RedisTicketQueue
+                self.queue = RedisTicketQueue(self.name, self.client, stale_timeout=(self.fifo_stale_timeout if self.fifo_stale_timeout is not None else self.timeout))
+            ticket, member = self.queue.register()
+
+            while True:
+                self.queue.cleanup_stale()
+                if not self.queue.is_head(ticket):
+                    if not blocking:
+                        raise LockTimeoutError("Lock is already held and blocking is False")
+                    if deadline is not None and time.monotonic() >= deadline:
+                        raise LockTimeoutError(f"Timeout while waiting for redis lock '{self.name}'")
+                    time.sleep(check_interval)
+                    continue
+                # We're head; attempt to SET NX
+                px = None if timeout is None else int((timeout or 0) * 1000)
+                try:
+                    ok: Any = self.client.set(self.name, token, nx=True, px=px)
+                except Exception as exc:
+                    raise LockError(str(exc)) from exc
+                if ok:
+                    self.token = token
+                    try:
+                        self.queue.remove(member)
+                        self.queue_member = None
+                    except Exception:
+                        pass
+                    return
+                if not blocking:
+                    raise LockTimeoutError("Lock is already held and blocking is False")
+                if deadline is not None and time.monotonic() >= deadline:
+                    raise LockTimeoutError(f"Timeout while waiting for redis lock '{self.name}'")
+                time.sleep(check_interval)
+        except Exception:
+            # On error, ensure we remove our queue entry if present
+            try:
+                if hasattr(self, "queue") and self.queue is not None and self.queue_member is not None:
+                    self.queue.remove(self.queue_member)
+                    self.queue_member = None
+            except Exception:
+                pass
+            raise
+
+
+    def release(self) -> None:
+        """ Release the lock if currently owned by this instance.
+
+        Uses an atomic Lua script to check that the stored token matches the
+        key value and deletes it only when owned. Additionally removes any
+        lingering queue entry for this client.
+        """
+        if not self.token:
+            return
+        self.client = self.ensure_client()
+
+        try:
+            # Use eval to run atomic check-and-del
+            self.client.eval(self.RELEASE_SCRIPT, 1, self.name, self.token)
+        finally:
+            # Ensure local state cleared and remove any queue entry we may have left
+            try:
+                if self.queue_member is not None:
+                    self.client.zrem(f"{self.name}:queue", self.queue_member)
+            except Exception:
+                pass
+            self.queue_member = None
+            self.token = None
+
+            # Best-effort cleanup of the queue keys when empty
+            try:
+                if hasattr(self, "queue") and self.queue is not None:
+                    try:
+                        self.queue.cleanup_stale()
+                    except Exception:
+                        pass
+                    try:
+                        self.queue.maybe_cleanup()
+                    except Exception:
+                        pass
+            except Exception:
+                pass
+
+    def __enter__(self) -> RedisLockFifo:
+        self.acquire()
+        return self
+
+    def __exit__(self, exc_type: type | None, exc: BaseException | None, tb: Any | None) -> None:
+        self.release()
+

stouputils/lock/redis_fifo.pyi

@@ -0,0 +1,123 @@
+import redis
+from .shared import LockError as LockError, LockTimeoutError as LockTimeoutError
+from _typeshed import Incomplete
+from contextlib import AbstractContextManager
+from typing import Any
+
+class RedisLockFifo(AbstractContextManager['RedisLockFifo']):
+    ''' A Redis-backed inter-process lock (requires `redis`).
+
+    This lock provides optional Fifo fairness (enabled by default) and is
+    implemented using atomic Redis primitives. Acquisition of the underlying
+    lock uses an owner token and `SET NX` (with optional PX expiry when a
+    timeout/TTL is specified). When Fifo is enabled the implementation uses
+    a small ticket queue using `INCR` + `ZADD` and only the queue head attempts
+    to `SET NX`. Release uses an atomic Lua script to ensure only the token
+    owner can delete the lock key.
+
+    Notes:
+      - The lock stores a locally-generated random token; releasing without the
+        correct token has no effect on the remote key.
+      - When Fifo is enabled, queue entries are removed when the client acquires
+        the lock; stale queue entries (from crashed clients) are removed lazily
+        when their age exceeds ``fifo_stale_timeout`` (defaults to ``timeout`` if
+        ``None``).
+      - This class raises ``ImportError`` if the ``redis`` package is not
+        installed and raises ``LockTimeoutError`` / ``LockError`` for runtime
+        acquisition errors.
+
+    Args:
+        name               (str):           Redis key name used for the lock.
+        redis_client       (redis.Redis | None): Optional Redis client. A client is created lazily if not provided.
+        timeout            (float | None):  Maximum time to wait for the lock and (when provided) the lock TTL used by ``SET PX`` in seconds. ``None`` means block indefinitely and no automatic expiry.
+        blocking           (bool):          Whether to block until acquired (subject to ``timeout``).
+        check_interval     (float):         Poll interval while waiting for the lock, in seconds.
+        fifo               (bool):          Whether to enforce Fifo ordering using a ZSET queue (default: True).
+        fifo_stale_timeout (float | None):  Seconds after which a queue entry is considered stale; if ``None`` the lock\'s ``timeout`` value will be used; if both are ``None``, no stale cleanup is performed.
+
+    Raises:
+        ImportError: If the ``redis`` package is not installed.
+        LockTimeoutError: If the lock cannot be acquired within ``timeout``.
+        LockError: On unexpected redis errors.
+
+    Examples:
+        >>> # Redis-backed examples; run only on non-Windows environments
+        >>> def _redis_doctest():
+        ...     import redis, time
+        ...     client = redis.Redis()
+        ...
+        ...     # Simple usage (assumes redis is available in the test environment)
+        ...     with RedisLockFifo(\'test:lock\', timeout=1):
+        ...         pass
+        ...
+        ...     # Non-Fifo usage example
+        ...     with RedisLockFifo(\'test:lock\', fifo=False, timeout=1):
+        ...         pass
+        ...
+        ...     # Fifo stale-ticket behaviour (requires a local redis server)
+        ...     # Inject a stale head entry
+        ...     name = \'doctest:lock:stale\'
+        ...     _ = client.delete(f"{name}:queue")
+        ...     _ = client.delete(f"{name}:seq")
+        ...     _ = client.delete(name)
+        ...     old_ts = int((time.time() - 10) * 1000)
+        ...     _ = client.zadd(f"{name}:queue", {f"1:stale:{old_ts}": 1})
+        ...     # Now acquire with small stale timeout which should remove head then succeed
+        ...     with RedisLockFifo(name, fifo=True, fifo_stale_timeout=0.01, timeout=1):
+        ...         print(\'acquired\')
+        ...     _ = client.delete(f"{name}:queue")
+        ...     _ = client.delete(f"{name}:seq")
+        ...     _ = client.delete(name)
+        ...     # After using the lock, the queue keys should be removed when empty
+        ...     with RedisLockFifo(name, timeout=1):
+        ...         pass
+        ...     print(client.exists(f"{name}:queue") == 0 and client.exists(f"{name}:seq") == 0)
+        ...
+        ...     # Non-Fifo acquisition should not create queue keys
+        ...     name2 = \'doctest:lock:nonfifo\'
+        ...     _ = client.delete(f"{name2}:queue"); _ = client.delete(f"{name2}:seq")
+        ...     with RedisLockFifo(name2, fifo=False, timeout=1):
+        ...         pass
+        ...     print(client.exists(f"{name2}:queue") == 0 and client.exists(f"{name2}:seq") == 0)
+        ...
+        >>> import os
+        >>> if os.name != \'nt\':
+        ...     _redis_doctest()
+        ... else:
+        ...     print("acquired\\nTrue\\nTrue")
+        acquired
+        True
+        True
+    '''
+    RELEASE_SCRIPT: str
+    name: str
+    client: redis.Redis | None
+    timeout: float | None
+    blocking: bool
+    check_interval: float
+    fifo: bool
+    fifo_stale_timeout: float | None
+    token: str | None
+    queue_member: str | None
+    queue: Incomplete
+    def __init__(self, name: str, redis_client: redis.Redis | None = None, timeout: float | None = None, blocking: bool = True, check_interval: float = 0.05, fifo: bool = True, fifo_stale_timeout: float | None = None) -> None: ...
+    def ensure_client(self) -> redis.Redis:
+        """ Ensure a ``redis.Redis`` client is available (lazy creation). """
+    def _cleanup_stalequeue(self) -> None:
+        """ Remove a stale head member from the queue if it exceeds the stale timeout. """
+    def acquire(self, timeout: float | None = None, blocking: bool | None = None, check_interval: float | None = None) -> None:
+        """ Acquire the Redis lock.
+
+        When Fifo is enabled (default), this function obtains a ticket via INCR
+        and registers it in a ZSET. The client waits until its ticket is the
+        head of the queue and then attempts to SET NX the lock key.
+        """
+    def release(self) -> None:
+        """ Release the lock if currently owned by this instance.
+
+        Uses an atomic Lua script to check that the stored token matches the
+        key value and deletes it only when owned. Additionally removes any
+        lingering queue entry for this client.
+        """
+    def __enter__(self) -> RedisLockFifo: ...
+    def __exit__(self, exc_type: type | None, exc: BaseException | None, tb: Any | None) -> None: ...

stouputils/lock/shared.py

@@ -0,0 +1,30 @@
+
+# Imports
+import os
+import tempfile
+
+from ..io import clean_path
+
+
+class LockError(RuntimeError):
+    """ Base lock error. """
+class LockTimeoutError(TimeoutError, LockError):
+    """ Raised when a lock could not be acquired within ``timeout`` seconds. """
+
+
+def resolve_path(path: str) -> str:
+    """ Resolve a lock file path, placing it in the system temporary directory if only a name is given.
+
+    Examples:
+        >>> import os, tempfile
+        >>> p = resolve_path('foo.lock')
+        >>> os.path.basename(p) == 'foo.lock'
+        True
+    """
+    path = clean_path(path)
+    name = os.path.basename(path)
+    if name == path:
+        path = f"{tempfile.gettempdir()}/{name}"
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    return path
+

stouputils/lock/shared.pyi

@@ -0,0 +1,16 @@
+from ..io import clean_path as clean_path
+
+class LockError(RuntimeError):
+    """ Base lock error. """
+class LockTimeoutError(TimeoutError, LockError):
+    """ Raised when a lock could not be acquired within ``timeout`` seconds. """
+
+def resolve_path(path: str) -> str:
+    """ Resolve a lock file path, placing it in the system temporary directory if only a name is given.
+
+    Examples:
+        >>> import os, tempfile
+        >>> p = resolve_path('foo.lock')
+        >>> os.path.basename(p) == 'foo.lock'
+        True
+    """