dycw-utilities 0.166.26__py3-none-any.whl → 0.166.27__py3-none-any.whl

{dycw_utilities-0.166.26.dist-info → dycw_utilities-0.166.27.dist-info}/METADATA

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

{dycw_utilities-0.166.26.dist-info → dycw_utilities-0.166.27.dist-info}/RECORD

@@ -1,7 +1,7 @@
-utilities/__init__.py,sha256=ypZlN_qCHWy6_qsW0wrMXJ1XcN87MLMxxm-3gFVy0PI,61
+utilities/__init__.py,sha256=HjzeHsUXRBIhhvlhaEdygkT-X4czww6QieOICBEASeM,61
 utilities/aeventkit.py,sha256=ddoleSwW9zdc2tjX5Ge0pMKtYwV_JMxhHYOxnWX2AGM,12609
 utilities/altair.py,sha256=nHdpWt8ZwdUwRQN970MvHd5bRWokNqzHcZQEdSHKRuE,9033
-utilities/asyncio.py,sha256=PUedzQ5deqlSECQ33sam9cRzI9TnygHz3FdOqWJWPTM,15288
+utilities/asyncio.py,sha256=60l1IwjnRGeaVphAFiwDIHyfKoZYKY-XGpptUxGiU-M,17034
 utilities/atomicwrites.py,sha256=tPo6r-Rypd9u99u66B9z86YBPpnLrlHtwox_8Z7T34Y,5790
 utilities/atools.py,sha256=6neeCcgXxK2dlsc0xp15Za7nSucbCgFtAJepGI_-WXU,2549
 utilities/cachetools.py,sha256=v1-9sXHLdOLiwmkq6NB0OUbxeKBuVVN6wmAWefWoaHI,2744
@@ -27,7 +27,7 @@ utilities/hypothesis.py,sha256=CSCJFek07g71iSND7PCty7gyaOT_49QSbnTHn1wWidQ,45535
 utilities/importlib.py,sha256=mV1xT_O_zt_GnZZ36tl3xOmMaN_3jErDWY54fX39F6Y,429
 utilities/inflect.py,sha256=v7YkOWSu8NAmVghPcf4F3YBZQoJCS47_DLf9jbfWIs0,581
 utilities/ipython.py,sha256=V2oMYHvEKvlNBzxDXdLvKi48oUq2SclRg5xasjaXStw,763
-utilities/iterables.py,sha256=8_dljtugLjxL8GCO_udMoH5uldvxdAmsN6aZ3EdnAiA,42564
+utilities/iterables.py,sha256=t2TsW-K3rVlS6y4_tqcc1fk9RwJV-bi7G_VwduMABK0,42558
 utilities/json.py,sha256=-WcGtSsCr9Y42wHZzAMnfvU6ihAfVftylFfRUORaDFo,2102
 utilities/jupyter.py,sha256=ft5JA7fBxXKzP-L9W8f2-wbF0QeYc_2uLQNFDVk4Z-M,2917
 utilities/libcst.py,sha256=ngD4wxnR3Kh-RBVmU5l5ST7cuZLhMZwyMDjHZe5mhTs,5581
@@ -91,8 +91,8 @@ utilities/zoneinfo.py,sha256=tdIScrTB2-B-LH0ukb1HUXKooLknOfJNwHk10MuMYvA,3619
 utilities/pytest_plugins/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
 utilities/pytest_plugins/pytest_randomly.py,sha256=B1qYVlExGOxTywq2r1SMi5o7btHLk2PNdY_b1p98dkE,409
 utilities/pytest_plugins/pytest_regressions.py,sha256=mnHYBfdprz50UGVkVzV1bZERZN5CFfoF8YbokGxdFwU,1639
-dycw_utilities-0.166.26.dist-info/METADATA,sha256=JHYsRNyHleOHEHpUg4jB_MfIxTOCchthwx_YDzuUaWE,1700
-dycw_utilities-0.166.26.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.166.26.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
-dycw_utilities-0.166.26.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.166.26.dist-info/RECORD,,
+dycw_utilities-0.166.27.dist-info/METADATA,sha256=zD73RDL_kiYeNBGjNY5R9krPiTk165csMHzG7DzD35I,1700
+dycw_utilities-0.166.27.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.166.27.dist-info/entry_points.txt,sha256=BOD_SoDxwsfJYOLxhrSXhHP_T7iw-HXI9f2WVkzYxvQ,135
+dycw_utilities-0.166.27.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.166.27.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.166.26"
+__version__ = "0.166.27"

utilities/asyncio.py

@@ -31,6 +31,7 @@ from typing import (
     Self,
     TextIO,
     assert_never,
+    cast,
     overload,
     override,
 )
@@ -38,6 +39,7 @@ from typing import (
 from utilities.functions import ensure_int, ensure_not_none
 from utilities.os import is_pytest
 from utilities.random import SYSTEM_RANDOM
+from utilities.reprlib import get_repr
 from utilities.sentinel import Sentinel, sentinel
 from utilities.shelve import yield_shelf
 from utilities.text import to_bool
@@ -48,6 +50,7 @@ if TYPE_CHECKING:
     from asyncio import _CoroutineLike
     from asyncio.subprocess import Process
     from collections.abc import (
+        AsyncIterable,
         AsyncIterator,
         Callable,
         ItemsView,
@@ -346,6 +349,24 @@ class EnhancedTaskGroup(TaskGroup):
 ##
 
 
+def chain_async[T](*iterables: Iterable[T] | AsyncIterable[T]) -> AsyncIterator[T]:
+    """Asynchronous version of `chain`."""
+
+    async def iterator() -> AsyncIterator[T]:
+        for it in iterables:
+            try:
+                async for item in cast("AsyncIterable[T]", it):
+                    yield item
+            except TypeError:
+                for item in cast("Iterable[T]", it):
+                    yield item
+
+    return iterator()
+
+
+##
+
+
 def get_coroutine_name(func: Callable[[], Coro[Any]], /) -> str:
     """Get the name of a coroutine, and then dispose of it gracefully."""
     coro = func()
@@ -394,6 +415,43 @@ def get_items_nowait[T](queue: Queue[T], /, *, max_size: int | None = None) -> l
 ##
 
 
+async def one_async[T](*iterables: Iterable[T] | AsyncIterable[T]) -> T:
+    """Asynchronous version of `one`."""
+    result: T | Sentinel = sentinel
+    async for item in chain_async(*iterables):
+        if not isinstance(result, Sentinel):
+            raise OneAsyncNonUniqueError(iterables=iterables, first=result, second=item)
+        result = item
+    if isinstance(result, Sentinel):
+        raise OneAsyncEmptyError(iterables=iterables)
+    return result
+
+
+@dataclass(kw_only=True, slots=True)
+class OneAsyncError[T](Exception):
+    iterables: tuple[Iterable[T] | AsyncIterable[T], ...]
+
+
+@dataclass(kw_only=True, slots=True)
+class OneAsyncEmptyError[T](OneAsyncError[T]):
+    @override
+    def __str__(self) -> str:
+        return f"Iterable(s) {get_repr(self.iterables)} must not be empty"
+
+
+@dataclass(kw_only=True, slots=True)
+class OneAsyncNonUniqueError[T](OneAsyncError):
+    first: T
+    second: T
+
+    @override
+    def __str__(self) -> str:
+        return f"Iterable(s) {get_repr(self.iterables)} must contain exactly one item; got {self.first}, {self.second} and perhaps more"
+
+
+##
+
+
 async def put_items[T](items: Iterable[T], queue: Queue[T], /) -> None:
     """Put items into a queue; if full then wait."""
     for item in items:
@@ -542,10 +600,15 @@ async def yield_locked_shelf(
 __all__ = [
     "AsyncDict",
     "EnhancedTaskGroup",
+    "OneAsyncEmptyError",
+    "OneAsyncError",
+    "OneAsyncNonUniqueError",
     "StreamCommandOutput",
+    "chain_async",
     "get_coroutine_name",
     "get_items",
     "get_items_nowait",
+    "one_async",
     "put_items",
     "put_items_nowait",
     "sleep_max",

utilities/iterables.py

@@ -933,7 +933,7 @@ class MergeStrMappingsError(Exception):
 
 def one[T](*iterables: Iterable[T]) -> T:
     """Return the unique value in a set of iterables."""
-    it = iter(chain(*iterables))
+    it = chain(*iterables)
     try:
         first = next(it)
     except StopIteration: