dycw-utilities 0.130.2__py3-none-any.whl → 0.131.0__py3-none-any.whl

{dycw_utilities-0.130.2.dist-info → dycw_utilities-0.131.0.dist-info}/METADATA

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

{dycw_utilities-0.130.2.dist-info → dycw_utilities-0.131.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=xiyBegs4PBVyJ6bA-ugSHN76oMsqk3uRB1M8N8U1_NQ,60
+utilities/__init__.py,sha256=uJKmD-jecfvyO-bClrlrEbRyiOqLmfntMZDawWbbSAk,60
 utilities/aiolimiter.py,sha256=mD0wEiqMgwpty4XTbawFpnkkmJS6R4JRsVXFUaoitSU,628
 utilities/altair.py,sha256=Gpja-flOo-Db0PIPJLJsgzAlXWoKUjPU1qY-DQ829ek,9156
 utilities/asyncio.py,sha256=lvdgBhuMtxq0dpiwF9g2WMMrit3kqXibN1V5NZ4xdbo,38046
@@ -50,7 +50,7 @@ utilities/pickle.py,sha256=Bhvd7cZl-zQKQDFjUerqGuSKlHvnW1K2QXeU5UZibtg,657
 utilities/platform.py,sha256=48IOKx1IC6ZJXWG-b56ZQptITcNFhWRjELW72o2dGTA,2398
 utilities/polars.py,sha256=QlmUpYTqHNkcLnWOQh1TW22W2QyLzvifCvBcbsqhpdE,63272
 utilities/polars_ols.py,sha256=Uc9V5kvlWZ5cU93lKZ-cfAKdVFFw81tqwLW9PxtUvMs,5618
-utilities/pottery.py,sha256=luBJV4LXQv6MaQdJmTN5R1QOz98visTuf3ayWFT8bHY,1538
+utilities/pottery.py,sha256=-YikdIQFqhFXifyMq5R5z6V6N8y639gAnVVXR4jXxdc,3568
 utilities/pqdm.py,sha256=foRytQybmOQ05pjt5LF7ANyzrIa--4ScDE3T2wd31a4,3118
 utilities/psutil.py,sha256=RtbLKOoIJhqrJmEoHDBVeSD-KPzshtS0FtRXBP9_w2s,3751
 utilities/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -90,7 +90,7 @@ utilities/warnings.py,sha256=un1LvHv70PU-LLv8RxPVmugTzDJkkGXRMZTE2-fTQHw,1771
 utilities/whenever.py,sha256=QbXgFAPuUL7PCp2hajmIP-FFIfIR1J6Y0TxJbeoj60I,18434
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=-5j7IQ9nb7gR43rdgA7ms05im-XuqhAk9EJnQBXxCoQ,1874
-dycw_utilities-0.130.2.dist-info/METADATA,sha256=iA0TZllOrUsCc1Q7--u4Z6r_Lyl7hj1tMYqHQGDCmLA,12989
-dycw_utilities-0.130.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.130.2.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.130.2.dist-info/RECORD,,
+dycw_utilities-0.131.0.dist-info/METADATA,sha256=nFoGHW3OOG6CRJXkrM-qnnpeoyMTas8muYPqY7L5sSM,12989
+dycw_utilities-0.131.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.131.0.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.131.0.dist-info/RECORD,,

utilities/__init__.py

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

utilities/pottery.py

@@ -1,50 +1,116 @@
 from __future__ import annotations
 
-import asyncio
 from contextlib import asynccontextmanager, suppress
-from typing import TYPE_CHECKING
+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
+    from collections.abc import AsyncIterator, Iterable
 
     from utilities.types import Duration, MaybeIterable
 
 
 @asynccontextmanager
-async def yield_locked_resource(
+async def yield_access(
     redis: MaybeIterable[Redis],
     key: str,
     /,
     *,
-    duration: Duration = 10 * SECOND,
+    num: int = 1,
+    timeout_acquire: Duration | None = None,
+    timeout_release: Duration = 10 * SECOND,
     sleep: Duration = MILLISECOND,
-) -> AsyncIterator[AIORedlock]:
-    """Yield a locked resource."""
+    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))
     )
-    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,
+    auto_release_time = datetime_duration_to_float(  # skipif-ci-and-not-linux
+        timeout_release
     )
-    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)
+    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
-        yield lock
+        lock = await _get_first_available_lock(
+            key, locks, num=num, timeout=timeout_acquire, sleep=sleep
+        )
+        yield
     finally:  # skipif-ci-and-not-linux
-        with suppress(ReleaseUnlockedLock):
-            await lock.release()
+        await sleep_dur(duration=throttle)
+        if lock is not None:
+            with suppress(ReleaseUnlockedLock):
+                await lock.release()
 
 
-__all__ = ["yield_locked_resource"]
+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"]