dycw-utilities 0.130.1__tar.gz → 0.131.0__tar.gz

{dycw_utilities-0.130.1 → dycw_utilities-0.131.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.130.1
+Version: 0.131.0
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12

{dycw_utilities-0.130.1 → dycw_utilities-0.131.0}/pyproject.toml

@@ -94,7 +94,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.130.1"
+version = "0.131.0"
 
 [project.optional-dependencies]
 logging = [
@@ -341,7 +341,7 @@ zzz-test-zoneinfo = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.130.1"
+current_version = "0.131.0"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

dycw_utilities-0.131.0/src/tests/test_pottery.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from asyncio import TaskGroup, sleep
+from re import search
+from typing import TYPE_CHECKING
+
+from pytest import mark, param, raises
+
+from tests.conftest import SKIPIF_CI_AND_NOT_LINUX
+from tests.test_redis import yield_test_redis
+from utilities.iterables import one
+from utilities.pottery import (
+    _YieldAccessNumLocksError,
+    _YieldAccessUnableToAcquireLockError,
+    yield_access,
+)
+from utilities.text import unique_str
+from utilities.timer import Timer
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis
+
+
+async def _func_access(num_tasks: int, key: str, /, *, num_locks: int = 1) -> None:
+    async def coroutine() -> None:
+        async with yield_test_redis() as redis, yield_access(redis, key, num=num_locks):
+            await sleep(0.1)
+
+    async with TaskGroup() as tg:
+        _ = [tg.create_task(coroutine()) for _ in range(num_tasks)]
+
+
+class TestYieldAccess:
+    @SKIPIF_CI_AND_NOT_LINUX
+    @mark.parametrize(
+        ("num_tasks", "num_locks", "min_time"),
+        [
+            param(1, 1, 0.1),
+            param(1, 2, 0.1),
+            param(1, 3, 0.1),
+            param(2, 1, 0.2),
+            param(2, 2, 0.1),
+            param(2, 3, 0.1),
+            param(2, 4, 0.1),
+            param(2, 5, 0.1),
+            param(3, 1, 0.3),
+            param(3, 2, 0.2),
+            param(3, 3, 0.1),
+            param(3, 4, 0.1),
+            param(3, 5, 0.1),
+            param(4, 1, 0.4),
+            param(4, 2, 0.2),
+            param(4, 3, 0.2),
+            param(4, 4, 0.1),
+            param(4, 5, 0.1),
+        ],
+    )
+    async def test_main(
+        self, *, num_tasks: int, num_locks: int, min_time: float
+    ) -> None:
+        with Timer() as timer:
+            await _func_access(num_tasks, unique_str(), num_locks=num_locks)
+        assert min_time <= float(timer) <= 3 * min_time
+
+    async def test_error_num_locks(self) -> None:
+        key = unique_str()
+        with raises(
+            _YieldAccessNumLocksError,
+            match=r"Number of locks for '\w+' must be positive; got 0",
+        ):
+            async with yield_test_redis() as redis, yield_access(redis, key, num=0):
+                ...
+
+    @SKIPIF_CI_AND_NOT_LINUX
+    async def test_error_unable_to_acquire_lock(self) -> None:
+        key = unique_str()
+
+        async def coroutine(redis: Redis, key: str, /) -> None:
+            async with yield_access(
+                redis, key, num=1, timeout_acquire=0.1, throttle=0.5
+            ):
+                await sleep(0.1)
+
+        with raises(ExceptionGroup) as exc_info:  # noqa: PT012
+            async with yield_test_redis() as redis, TaskGroup() as tg:
+                _ = tg.create_task(coroutine(redis, key))
+                _ = tg.create_task(coroutine(redis, key))
+        error = one(exc_info.value.exceptions)
+        assert isinstance(error, _YieldAccessUnableToAcquireLockError)
+        assert search(
+            r"Unable to acquire any 1 of 1 locks for '\w+' after 0\.1", str(error)
+        )

{dycw_utilities-0.130.1 → dycw_utilities-0.131.0}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.130.1"
+__version__ = "0.131.0"

dycw_utilities-0.131.0/src/utilities/pottery.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager, suppress
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, override
+
+from pottery import AIORedlock
+from pottery.exceptions import ReleaseUnlockedLock
+from redis.asyncio import Redis
+
+from utilities.asyncio import sleep_dur, timeout_dur
+from utilities.datetime import MILLISECOND, SECOND, datetime_duration_to_float
+from utilities.iterables import always_iterable
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Iterable
+
+    from utilities.types import Duration, MaybeIterable
+
+
+@asynccontextmanager
+async def yield_access(
+    redis: MaybeIterable[Redis],
+    key: str,
+    /,
+    *,
+    num: int = 1,
+    timeout_acquire: Duration | None = None,
+    timeout_release: Duration = 10 * SECOND,
+    sleep: Duration = MILLISECOND,
+    throttle: Duration | None = None,
+) -> AsyncIterator[None]:
+    """Acquire access to a locked resource, amongst 1 of multiple connections."""
+    if num <= 0:
+        raise _YieldAccessNumLocksError(key=key, num=num)
+    masters = (  # skipif-ci-and-not-linux
+        {redis} if isinstance(redis, Redis) else set(always_iterable(redis))
+    )
+    auto_release_time = datetime_duration_to_float(  # skipif-ci-and-not-linux
+        timeout_release
+    )
+    locks = [  # skipif-ci-and-not-linux
+        AIORedlock(
+            key=f"{key}_{i}_of_{num}",
+            masters=masters,
+            auto_release_time=auto_release_time,
+        )
+        for i in range(1, num + 1)
+    ]
+    lock: AIORedlock | None = None  # skipif-ci-and-not-linux
+    try:  # skipif-ci-and-not-linux
+        lock = await _get_first_available_lock(
+            key, locks, num=num, timeout=timeout_acquire, sleep=sleep
+        )
+        yield
+    finally:  # skipif-ci-and-not-linux
+        await sleep_dur(duration=throttle)
+        if lock is not None:
+            with suppress(ReleaseUnlockedLock):
+                await lock.release()
+
+
+async def _get_first_available_lock(
+    key: str,
+    locks: Iterable[AIORedlock],
+    /,
+    *,
+    num: int = 1,
+    timeout: Duration | None = None,
+    sleep: Duration | None = None,
+) -> AIORedlock:
+    locks = list(locks)  # skipif-ci-and-not-linux
+    error = _YieldAccessUnableToAcquireLockError(  # skipif-ci-and-not-linux
+        key=key, num=num, timeout=timeout
+    )
+    async with timeout_dur(  # skipif-ci-and-not-linux
+        duration=timeout, error=error
+    ):
+        while True:
+            if (result := await _get_first_available_lock_if_any(locks)) is not None:
+                return result
+            await sleep_dur(duration=sleep)
+
+
+async def _get_first_available_lock_if_any(
+    locks: Iterable[AIORedlock], /
+) -> AIORedlock | None:
+    for lock in locks:  # skipif-ci-and-not-linux
+        if await lock.acquire(blocking=False):
+            return lock
+    return None  # skipif-ci-and-not-linux
+
+
+@dataclass(kw_only=True, slots=True)
+class YieldAccessError(Exception):
+    key: str
+    num: int
+
+
+@dataclass(kw_only=True, slots=True)
+class _YieldAccessNumLocksError(YieldAccessError):
+    @override
+    def __str__(self) -> str:
+        return f"Number of locks for {self.key!r} must be positive; got {self.num}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _YieldAccessUnableToAcquireLockError(YieldAccessError):
+    timeout: Duration | None
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to acquire any 1 of {self.num} locks for {self.key!r} after {self.timeout}"  # skipif-ci-and-not-linux
+
+
+__all__ = ["YieldAccessError", "yield_access"]

dycw_utilities-0.130.1/src/tests/test_pottery.py

@@ -1,28 +0,0 @@
-from __future__ import annotations
-
-from asyncio import TaskGroup, sleep
-
-from tests.conftest import SKIPIF_CI_AND_NOT_LINUX
-from tests.test_redis import yield_test_redis
-from utilities.pottery import yield_locked_resource
-from utilities.text import unique_str
-from utilities.timer import Timer
-
-
-async def _coroutine(key: str) -> None:
-    async with yield_test_redis() as redis, yield_locked_resource(redis, key):
-        await sleep(0.1)
-
-
-async def _asyncio_runner(num_tasks: int, key: str) -> None:
-    async with TaskGroup() as tg:
-        _ = [tg.create_task(_coroutine(key)) for _ in range(num_tasks)]
-
-
-class TestYieldLockedResource:
-    @SKIPIF_CI_AND_NOT_LINUX
-    async def test_single_process(self) -> None:
-        with Timer() as timer:
-            await _asyncio_runner(3, unique_str())
-        min_time = 0.3
-        assert min_time <= float(timer) <= 3 * min_time

dycw_utilities-0.130.1/src/utilities/pottery.py

@@ -1,50 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-from contextlib import asynccontextmanager, suppress
-from typing import TYPE_CHECKING
-
-from pottery import AIORedlock
-from pottery.exceptions import ReleaseUnlockedLock
-from redis.asyncio import Redis
-
-from utilities.datetime import MILLISECOND, SECOND, datetime_duration_to_float
-from utilities.iterables import always_iterable
-
-if TYPE_CHECKING:
-    from collections.abc import AsyncIterator
-
-    from utilities.types import Duration, MaybeIterable
-
-
-@asynccontextmanager
-async def yield_locked_resource(
-    redis: MaybeIterable[Redis],
-    key: str,
-    /,
-    *,
-    duration: Duration = 10 * SECOND,
-    sleep: Duration = MILLISECOND,
-) -> AsyncIterator[None]:
-    """Yield a locked resource."""
-    masters = (  # skipif-ci-and-not-linux
-        {redis} if isinstance(redis, Redis) else set(always_iterable(redis))
-    )
-    duration_use = datetime_duration_to_float(duration)  # skipif-ci-and-not-linux
-    lock = AIORedlock(  # skipif-ci-and-not-linux
-        key=key,
-        masters=masters,
-        auto_release_time=duration_use,
-        context_manager_timeout=duration_use,
-    )
-    sleep_use = datetime_duration_to_float(sleep)  # skipif-ci-and-not-linux
-    while not await lock.acquire():  # pragma: no cover
-        _ = await asyncio.sleep(sleep_use)
-    try:  # skipif-ci-and-not-linux
-        yield
-    finally:  # skipif-ci-and-not-linux
-        with suppress(ReleaseUnlockedLock):
-            await lock.release()
-
-
-__all__ = ["yield_locked_resource"]