asyncstdlib 3.12.3__tar.gz → 3.12.5__tar.gz

{asyncstdlib-3.12.3 → asyncstdlib-3.12.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: asyncstdlib
-Version: 3.12.3
+Version: 3.12.5
 Summary: The missing async toolbox
 Keywords: async,enumerate,itertools,builtins,functools,contextlib
 Author-email: Max Fischer <maxfischer2781@gmail.com>
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: sphinx ; extra == "doc"
 Requires-Dist: sphinxcontrib-trio ; extra == "doc"
 Requires-Dist: pytest ; extra == "test"

{asyncstdlib-3.12.3 → asyncstdlib-3.12.5}/asyncstdlib/__init__.py

@@ -45,7 +45,7 @@ from .itertools import (
 from .asynctools import borrow, scoped_iter, await_each, any_iter, apply, sync
 from .heapq import merge, nlargest, nsmallest
 
-__version__ = "3.12.3"
+__version__ = "3.12.5"
 
 __all__ = [
     "anext",

{asyncstdlib-3.12.3 → asyncstdlib-3.12.5}/asyncstdlib/_lrucache.py

@@ -28,7 +28,9 @@ from ._typing import Protocol, TypedDict, AC
 from ._utility import public_module
 
 
-@public_module("asyncstdlib.functools")
+@public_module(
+    "asyncstdlib.functools"
+)  # pyright: ignore[reportArgumentType,reportUntypedClassDecorator]
 class CacheInfo(NamedTuple):
     """
     Metadata on the current state of a cache
@@ -81,7 +83,9 @@ class LRUAsyncCallable(Protocol[AC]):
         """Descriptor ``__get__`` for caches to bind them on lookup"""
         if instance is None:
             return self
-        return LRUAsyncBoundCallable(self, instance)
+        return LRUAsyncBoundCallable(
+            self, instance
+        )  # pyright: ignore[reportUnknownVariableType]
 
     #: Get the result of ``await __wrapped__(...)`` from the cache or evaluation
     __call__: AC
@@ -120,7 +124,7 @@ class LRUAsyncCallable(Protocol[AC]):
 # these are fake and only exist for placeholders
 S = TypeVar("S")
 S2 = TypeVar("S2")
-P = TypeVar("P")
+P = TypeVar("P")  # actually a ParamSpec, see .pyi
 R = TypeVar("R")
 
 

{asyncstdlib-3.12.3 → asyncstdlib-3.12.5}/asyncstdlib/asynctools.py

@@ -10,6 +10,7 @@ from typing import (
     Awaitable,
     AsyncIterable,
     Callable,
+    Coroutine,
     Any,
     overload,
     Optional,
@@ -76,7 +77,7 @@ class _BorrowedAsyncIterator(AsyncGenerator[T, S]):
         if hasattr(self, "athrow"):
             self.athrow = wrapper_iterator.athrow
 
-    def aclose(self) -> Awaitable[None]:
+    def aclose(self) -> Coroutine[Any, Any, None]:
         return self._aclose_wrapper()
 
 
@@ -110,16 +111,25 @@ class _ScopedAsyncIteratorContext(AsyncContextManager[AsyncIterator[T]]):
         self._borrowed_iter = _ScopedAsyncIterator(self._iterator)
         return self._borrowed_iter
 
-    async def __aexit__(self, *args: Any) -> bool:
+    async def __aexit__(self, *args: Any) -> None:
         await self._borrowed_iter._aclose_wrapper()  # type: ignore
         await self._iterator.aclose()  # type: ignore
-        return False
 
     def __repr__(self) -> str:
         return f"<{self.__class__.__name__} of {self._iterator!r} at 0x{(id(self)):x}>"
 
 
-def borrow(iterator: AsyncIterator[T], /) -> AsyncIterator[T]:
+@overload
+def borrow(iterator: AsyncGenerator[T, S], /) -> AsyncGenerator[T, S]: ...
+
+
+@overload
+def borrow(iterator: AsyncIterator[T], /) -> AsyncIterator[T]: ...
+
+
+def borrow(
+    iterator: Union[AsyncIterator[T], AsyncGenerator[T, Any]], /
+) -> Union[AsyncIterator[T], AsyncGenerator[T, Any]]:
     """
     Borrow an async iterator, preventing to ``aclose`` it
 
@@ -142,7 +152,7 @@ def borrow(iterator: AsyncIterator[T], /) -> AsyncIterator[T]:
             "borrowing requires an async iterator "
             + f"with __aiter__ and __anext__ method, got {type(iterator).__name__}"
         )
-    return _BorrowedAsyncIterator(iterator)
+    return _BorrowedAsyncIterator[T, Any](iterator)
 
 
 def scoped_iter(iterable: AnyIterable[T], /) -> AsyncContextManager[AsyncIterator[T]]:

{asyncstdlib-3.12.3 → asyncstdlib-3.12.5}/asyncstdlib/contextlib.py

@@ -199,9 +199,8 @@ class Closing(Generic[AClose]):
     async def __aenter__(self) -> AClose:
         return self.thing
 
-    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         await self.thing.aclose()
-        return False
 
 
 closing = Closing
@@ -239,8 +238,8 @@ class NullContext(AsyncContextManager[T]):
     async def __aenter__(self) -> T:
         return self.enter_result
 
-    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
-        return False
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        return None
 
 
 nullcontext = NullContext

{asyncstdlib-3.12.3 → asyncstdlib-3.12.5}/asyncstdlib/contextlib.pyi

@@ -66,7 +66,7 @@ class closing(Generic[AClose]):
         exc_type: type[BaseException] | None,
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
-    ) -> bool: ...
+    ) -> None: ...
 
 class nullcontext(AsyncContextManager[T]):
     enter_result: T
@@ -74,14 +74,17 @@ class nullcontext(AsyncContextManager[T]):
     @overload
     def __init__(self: nullcontext[None], enter_result: None = ...) -> None: ...
     @overload
-    def __init__(self: nullcontext[T], enter_result: T) -> None: ...
+    def __init__(
+        self: nullcontext[T],  # pyright: ignore[reportInvalidTypeVarUse]
+        enter_result: T,
+    ) -> None: ...
     async def __aenter__(self: nullcontext[T]) -> T: ...
     async def __aexit__(
         self,
         exc_type: type[BaseException] | None,
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
-    ) -> bool: ...
+    ) -> None: ...
 
 SE = TypeVar(
     "SE",

asyncstdlib-3.12.5/asyncstdlib/functools.py

@@ -0,0 +1,316 @@
+from asyncio import iscoroutinefunction
+from typing import (
+    Callable,
+    Awaitable,
+    Union,
+    Any,
+    Generic,
+    Generator,
+    Optional,
+    Coroutine,
+    AsyncContextManager,
+    Type,
+    cast,
+)
+
+from ._typing import T, AC, AnyIterable, R
+from ._core import ScopedIter, awaitify as _awaitify, Sentinel
+from .builtins import anext
+from .contextlib import nullcontext
+
+from ._lrucache import (
+    lru_cache,
+    CacheInfo,
+    CacheParameters,
+    LRUAsyncCallable,
+    LRUAsyncBoundCallable,
+)
+
+__all__ = [
+    "cache",
+    "lru_cache",
+    "CacheInfo",
+    "CacheParameters",
+    "LRUAsyncCallable",
+    "LRUAsyncBoundCallable",
+    "reduce",
+    "cached_property",
+    "CachedProperty",
+]
+
+
+def cache(user_function: AC) -> LRUAsyncCallable[AC]:
+    """
+    Simple unbounded cache, aka memoization,  for async functions
+
+    This is a convenience function, equivalent to :py:func:`~.lru_cache`
+    with a ``maxsize`` of :py:data:`None`.
+    """
+    return lru_cache(maxsize=None)(user_function)
+
+
+class AwaitableValue(Generic[R]):
+    """Helper to provide an arbitrary value in ``await``"""
+
+    __slots__ = ("value",)
+
+    def __init__(self, value: R):
+        self.value = value
+
+    # noinspection PyUnreachableCode
+    def __await__(self) -> Generator[None, None, R]:
+        return self.value
+        yield  # type: ignore # pragma: no cover
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.value!r})"
+
+
+class _FutureCachedValue(Generic[R, T]):
+    """A placeholder object to control concurrent access to a cached awaitable value.
+
+    When given a lock to coordinate access, only the first task to await on a
+    cached property triggers the underlying coroutine. Once a value has been
+    produced, all tasks are unblocked and given the same, single value.
+
+    """
+
+    __slots__ = ("_get_attribute", "_instance", "_name", "_lock")
+
+    def __init__(
+        self,
+        get_attribute: Callable[[T], Coroutine[Any, Any, R]],
+        instance: T,
+        name: str,
+        lock: AsyncContextManager[Any],
+    ):
+        self._get_attribute = get_attribute
+        self._instance = instance
+        self._name = name
+        self._lock = lock
+
+    def __await__(self) -> Generator[None, None, R]:
+        return self._await_impl().__await__()
+
+    @property
+    def _instance_value(self) -> Awaitable[R]:
+        """Retrieve whatever is currently cached on the instance
+
+        If the instance (no longer) has this attribute, it was deleted and the
+        process is restarted by delegating to the descriptor.
+
+        """
+        try:
+            return self._instance.__dict__[self._name]
+        except KeyError:
+            # something deleted the cached value or future cached value placeholder. Restart
+            # the fetch by delegating to the cached_property descriptor.
+            return getattr(self._instance, self._name)
+
+    async def _await_impl(self) -> R:
+        if (stored := self._instance_value) is self:
+            # attempt to get the lock
+            async with self._lock:
+                # check again for a cached value
+                if (stored := self._instance_value) is self:
+                    # the instance attribute is still this placeholder, and we
+                    # hold the lock. Start the getter to store the value on the
+                    # instance and return the value.
+                    return await self._get_attribute(self._instance)
+
+        # another task produced a value, or the instance.__dict__ object was
+        # deleted in the interim.
+        return await stored
+
+    def __repr__(self) -> str:
+        return (
+            f"<{type(self).__name__} for '{type(self._instance).__name__}."
+            f"{self._name}' at {id(self):#x}>"
+        )
+
+
+class CachedProperty(Generic[T, R]):
+    def __init__(
+        self,
+        getter: Callable[[T], Awaitable[R]],
+        asynccontextmanager_type: Type[AsyncContextManager[Any]] = nullcontext,
+    ):
+        self.func = getter
+        self.attrname = None
+        self.__doc__ = getter.__doc__
+        self._asynccontextmanager_type = asynccontextmanager_type
+
+    def __set_name__(self, owner: Any, name: str) -> None:
+        if self.attrname is None:
+            self.attrname = name
+        elif name != self.attrname:
+            raise TypeError(
+                "Cannot assign the same cached_property to two different names "
+                f"({self.attrname!r} and {name!r})."
+            )
+
+    def __get__(
+        self, instance: Optional[T], owner: Optional[Type[Any]]
+    ) -> Union["CachedProperty[T, R]", Awaitable[R]]:
+        if instance is None:
+            return self
+
+        name = self.attrname
+        if name is None:
+            raise TypeError(
+                "Cannot use cached_property instance without calling __set_name__ on it."
+            )
+
+        # check for write access first; not all objects have __dict__ (e.g. class defines slots)
+        try:
+            cache = instance.__dict__
+        except AttributeError:
+            msg = (
+                f"No '__dict__' attribute on {type(instance).__name__!r} "
+                f"instance to cache {name!r} property."
+            )
+            raise TypeError(msg) from None
+
+        # store a placeholder for other tasks to access the future cached value
+        # on this instance. It takes care of coordinating between different
+        # tasks awaiting on the placeholder until the cached value has been
+        # produced.
+        wrapper = _FutureCachedValue(
+            self._get_attribute, instance, name, self._asynccontextmanager_type()
+        )
+        cache[name] = wrapper
+        return wrapper
+
+    async def _get_attribute(self, instance: T) -> R:
+        value = await self.func(instance)
+        name = self.attrname
+        assert name is not None  # enforced in __get__
+        instance.__dict__[name] = AwaitableValue(value)
+        return value
+
+
+def cached_property(
+    type_or_getter: Union[Type[AsyncContextManager[Any]], Callable[[T], Awaitable[R]]],
+    /,
+) -> Union[
+    Callable[[Callable[[T], Awaitable[R]]], CachedProperty[T, R]],
+    CachedProperty[T, R],
+]:
+    """
+    Transform a method into an attribute whose value is cached
+
+    When applied to an asynchronous method of a class, instances have an attribute
+    of the same name as the method (similar to :py:class:`property`). Using this
+    attribute with ``await`` provides the value of using the method with ``await``.
+
+    The attribute value is cached on the instance after being computed;
+    subsequent uses of the attribute with ``await`` provide the cached value,
+    without executing the method again.
+    The cached value can be cleared using ``del``, in which case the next
+    access will recompute the value using the wrapped method.
+
+    .. code-block:: python3
+
+        import asyncstdlib as a
+
+        class Resource:
+            def __init__(self, url):
+                self.url = url
+
+            @a.cached_property
+            async def data(self):
+                return await asynclib.get(self.url)
+
+        resource = Resource("http://example.com")
+        print(await resource.data)  # needs some time...
+        print(await resource.data)  # finishes instantly
+        del resource.data
+        print(await resource.data)  # needs some time...
+
+    Unlike a :py:class:`property`, this type does not support
+    :py:meth:`~property.setter` or :py:meth:`~property.deleter`.
+
+    If the attribute is accessed by multiple tasks before a cached value has
+    been produced, the getter can be run more than once. The final cached value
+    is determined by the last getter coroutine to return. To enforce that the
+    getter is executed at most once, provide an appropriate lock type - e.g. the
+    :py:class:`asyncio.Lock` class in an :py:mod:`asyncio` application - and
+    access is automatically synchronised.
+
+    .. code-block:: python3
+
+        from asyncio import Lock, gather
+
+        class Resource:
+            def __init__(self, url):
+                self.url = url
+
+            @a.cached_property(Lock)
+            async def data(self):
+                return await asynclib.get(self.url)
+
+        resource = Resource("http://example.com")
+        print(*(await gather(resource.data, resource.data)))
+
+    .. note::
+
+        Instances on which a value is to be cached must have a
+        ``__dict__`` attribute that is a mutable mapping.
+    """
+    if isinstance(type_or_getter, type) and issubclass(
+        type_or_getter, AsyncContextManager
+    ):
+
+        def decorator(
+            coroutine: Callable[[T], Awaitable[R]],
+        ) -> CachedProperty[T, R]:
+            return CachedProperty(
+                coroutine,
+                asynccontextmanager_type=cast(
+                    Type[AsyncContextManager[Any]], type_or_getter
+                ),
+            )
+
+        return decorator
+
+    if not iscoroutinefunction(type_or_getter):
+        raise ValueError("cached_property can only be used with a coroutine function")
+
+    return CachedProperty(type_or_getter)
+
+
+__REDUCE_SENTINEL = Sentinel("<no default>")
+
+
+async def reduce(
+    function: Union[Callable[[T, T], T], Callable[[T, T], Awaitable[T]]],
+    iterable: AnyIterable[T],
+    initial: T = __REDUCE_SENTINEL,  # type: ignore
+) -> T:
+    """
+    Reduce an (async) iterable by cumulative application of an (async) function
+
+    :raises TypeError: if ``iterable`` is empty and ``initial`` is not given
+
+    Applies the ``function`` from the beginning of ``iterable``, as if executing
+    ``await function(current, anext(iterable))`` until ``iterable`` is exhausted.
+    Note that the output of ``function`` should be valid as its first input.
+
+    The optional ``initial`` is prepended to all items of ``iterable``
+    when applying ``function``. If the combination of ``initial``
+    and ``iterable`` contains exactly one item, it is returned without
+    calling ``function``.
+    """
+    async with ScopedIter(iterable) as item_iter:
+        try:
+            value = (
+                initial if initial is not __REDUCE_SENTINEL else await anext(item_iter)
+            )
+        except StopAsyncIteration:
+            raise TypeError(
+                "reduce() of empty sequence with no initial value"
+            ) from None
+        function = _awaitify(function)
+        async for head in item_iter:
+            value = await function(value, head)
+    return value

asyncstdlib-3.12.5/asyncstdlib/functools.pyi

@@ -0,0 +1,40 @@
+from typing import Any, AsyncContextManager, Awaitable, Callable, Generic, overload
+
+from ._typing import T, T1, T2, AC, AnyIterable, R
+
+from ._lrucache import (
+    LRUAsyncCallable as LRUAsyncCallable,
+    LRUAsyncBoundCallable as LRUAsyncBoundCallable,
+    lru_cache as lru_cache,
+)
+
+def cache(user_function: AC) -> LRUAsyncCallable[AC]: ...
+
+class CachedProperty(Generic[T, R]):
+    def __init__(
+        self,
+        getter: Callable[[T], Awaitable[R]],
+        lock_type: type[AsyncContextManager[Any]] = ...,
+    ) -> None: ...
+    def __set_name__(self, owner: Any, name: str) -> None: ...
+    @overload
+    def __get__(self, instance: None, owner: type[Any]) -> "CachedProperty[T, R]": ...
+    @overload
+    def __get__(self, instance: T, owner: type | None) -> Awaitable[R]: ...
+    # __set__ is not defined at runtime, but you are allowed to replace the cached value
+    def __set__(self, instance: T, value: R) -> None: ...  # type: ignore[misc]  # pyright: ignore[reportGeneralTypeIssues]
+    # __del__ is not defined at runtime, but you are allowed to delete the cached value
+    def __del__(self, instance: T) -> None: ...
+
+@overload
+def cached_property(getter: Callable[[T], Awaitable[R]], /) -> CachedProperty[T, R]: ...
+@overload
+def cached_property(
+    asynccontextmanager_type: type[AsyncContextManager[Any]], /
+) -> Callable[[Callable[[T], Awaitable[R]]], CachedProperty[T, R]]: ...
+@overload
+async def reduce(
+    function: Callable[[T1, T2], T1], iterable: AnyIterable[T2], initial: T1
+) -> T1: ...
+@overload
+async def reduce(function: Callable[[T, T], T], iterable: AnyIterable[T]) -> T: ...

{asyncstdlib-3.12.3 → asyncstdlib-3.12.5}/asyncstdlib/itertools.py

@@ -13,12 +13,13 @@ from typing import (
     Iterable,
     Iterator,
     Tuple,
+    cast,
     overload,
     AsyncGenerator,
 )
 from collections import deque
 
-from ._typing import ACloseable, T, AnyIterable, ADD
+from ._typing import ACloseable, R, T, AnyIterable, ADD
 from ._utility import public_module
 from ._core import (
     ScopedIter,
@@ -35,6 +36,7 @@ from .builtins import (
 )
 
 S = TypeVar("S")
+T_co = TypeVar("T_co", covariant=True)
 
 
 async def cycle(iterable: AnyIterable[T]) -> AsyncIterator[T]:
@@ -335,8 +337,8 @@ class NoLock:
     async def __aenter__(self) -> None:
         pass
 
-    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
-        return False
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        return None
 
 
 async def tee_peer(
@@ -454,15 +456,14 @@ class Tee(Generic[T]):
     ) -> Union[AsyncIterator[T], Tuple[AsyncIterator[T], ...]]:
         return self._children[item]
 
-    def __iter__(self) -> Iterator[AnyIterable[T]]:
+    def __iter__(self) -> Iterator[AsyncIterator[T]]:
         yield from self._children
 
     async def __aenter__(self) -> "Tee[T]":
         return self
 
-    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         await self.aclose()
-        return False
 
     async def aclose(self) -> None:
         for child in self._children:
@@ -543,12 +544,86 @@ async def identity(x: T) -> T:
     return x
 
 
-async def groupby(
-    iterable: AnyIterable[Any],
-    key: Optional[
-        Union[Callable[[Any], Any], Callable[[Any], Awaitable[Any]]]
-    ] = identity,
-) -> AsyncIterator[Tuple[Any, AsyncIterator[Any]]]:
+class _GroupByState(Generic[R, T_co]):
+    """Internal state for the groupby iterator, shared between the parent and groups"""
+
+    __slots__ = (
+        "_iterator",
+        "_key_func",
+        "_current_value",
+        "target_key",
+        "current_key",
+        "current_group",
+    )
+
+    _sentinel = cast(T_co, object())
+
+    def __init__(
+        self, iterator: AsyncIterator[T_co], key_func: Callable[[T_co], Awaitable[R]]
+    ):
+        self._iterator = iterator
+        self._key_func = key_func
+        self._current_value = self._sentinel
+
+    async def step(self) -> None:
+        # can raise StopAsyncIteration
+        value = await anext(self._iterator)
+        key = await self._key_func(value)
+        self._current_value, self.current_key = value, key
+
+    async def maybe_step(self) -> None:
+        """Only step if there is no current value"""
+        if self._current_value is self._sentinel:
+            await self.step()
+
+    def consume_value(self) -> T_co:
+        """Return the current value after removing it from the current state"""
+        value, self._current_value = self._current_value, self._sentinel
+        return value
+
+    async def aclose(self) -> None:
+        """Close the underlying iterator"""
+        if (group := self.current_group) is not None:
+            await group.aclose()
+        if isinstance(self._iterator, ACloseable):
+            await self._iterator.aclose()
+
+
+class _Grouper(AsyncIterator[T_co], Generic[R, T_co]):
+    """A single group iterator, part of a series of groups yielded by groupby"""
+
+    __slots__ = ("_target_key", "_state")
+
+    def __init__(self, target_key: R, state: "_GroupByState[R, T_co]") -> None:
+        self._target_key = target_key
+        self._state = state
+
+    async def __anext__(self) -> T_co:
+        state = self._state
+        # the groupby already advanced to another group
+        if state.current_group is not self:
+            raise StopAsyncIteration
+        await state.maybe_step()
+        # the step advanced the iterator to another group
+        if self._target_key != state.current_key:
+            raise StopAsyncIteration
+        return state.consume_value()
+
+    async def aclose(self) -> None:
+        """
+        Close the group iterator
+
+        Note: this does _not_ close the underlying groupby managed iterator;
+        closing a single group shouldn't affect other groups in the series.
+        """
+        state = self._state
+        if state.current_group is not self:
+            return
+        state.current_group = None
+
+
+@public_module(__name__, "groupby")
+class GroupBy(AsyncIterator[Tuple[R, AsyncIterator[T_co]]], Generic[R, T_co]):
     """
     Create an async iterator over consecutive keys and groups from the (async) iterable
 
@@ -568,49 +643,44 @@ async def groupby(
     required up-front for sorting, this loses the advantage of asynchronous,
     lazy iteration and evaluation.
     """
-    # whether the current group was exhausted and the next begins already
-    exhausted = False
-    # `current_*`: buffer for key/value the current group peeked beyond its end
-    current_key = current_value = nothing = object()
-    make_key: Callable[[Any], Awaitable[Any]] = (
-        _awaitify(key) if key is not None else identity  # type: ignore
-    )
-    async with ScopedIter(iterable) as async_iter:
-        # fast-forward mode: advance to the next group
-        async def seek_group() -> AsyncIterator[Any]:
-            nonlocal current_value, current_key, exhausted
-            # Note: `value` always ends up being some T
-            # - value is something: we can never unset it
-            # - value is `nothing`: the previous group was not exhausted,
-            #                       and we scan at least one new value
-            value: Any = current_value
-            if not exhausted:
-                previous_key = current_key
-                while previous_key == current_key:
-                    value = await anext(async_iter)
-                    current_key = await make_key(value)
-            current_value = nothing
-            exhausted = False
-            return group(current_key, value=value)
-
-        # the lazy iterable of all items with the same key
-        async def group(desired_key: Any, value: Any) -> AsyncIterator[Any]:
-            nonlocal current_value, current_key, exhausted
-            yield value
-            async for value in async_iter:
-                next_key: Any = await make_key(value)
-                if next_key == desired_key:
-                    yield value
-                else:
-                    exhausted = True
-                    current_value = value
-                    current_key = next_key
-                    break
 
+    __slots__ = ("_state",)
+
+    def __init__(
+        self,
+        iterable: AnyIterable[T_co],
+        key: Optional[
+            Union[Callable[[T_co], R], Callable[[T_co], Awaitable[R]]]
+        ] = None,
+    ):
+        key_func = (
+            cast(Callable[[T_co], Awaitable[R]], identity)
+            if key is None
+            else _awaitify(key)
+        )
+        self._state = _GroupByState(aiter(iterable), key_func)
+
+    async def __anext__(self) -> Tuple[R, AsyncIterator[T_co]]:
+        state = self._state
+        # already disable the current group to avoid concurrency issues
+        state.current_group = None
+        await state.maybe_step()
         try:
-            while True:
-                next_group = await seek_group()
-                async with ScopedIter(next_group) as scoped_group:
-                    yield current_key, scoped_group
-        except StopAsyncIteration:
-            return
+            target_key = state.target_key
+        except AttributeError:
+            # no target key yet, skip scanning
+            pass
+        else:
+            # scan to the next group
+            while state.current_key == target_key:
+                await state.step()
+
+        state.target_key = current_key = state.current_key
+        state.current_group = group = _Grouper(current_key, state)
+        return (current_key, group)
+
+    async def aclose(self) -> None:
+        await self._state.aclose()
+
+
+groupby = GroupBy

{asyncstdlib-3.12.3 → asyncstdlib-3.12.5}/asyncstdlib/itertools.pyi

@@ -130,9 +130,9 @@ class tee(Generic[T]):
     def __getitem__(self, item: int) -> AsyncIterator[T]: ...
     @overload
     def __getitem__(self, item: slice) -> tuple[AsyncIterator[T], ...]: ...
-    def __iter__(self) -> Iterator[AnyIterable[T]]: ...
+    def __iter__(self) -> Iterator[AsyncIterator[T]]: ...
     async def __aenter__(self: Self) -> Self: ...
-    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool: ...
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None: ...
     async def aclose(self) -> None: ...
 
 def pairwise(iterable: AnyIterable[T]) -> AsyncIterator[tuple[T, T]]: ...
@@ -223,13 +223,15 @@ def zip_longest(
     fillvalue: F,
 ) -> AsyncIterator[tuple[T | F, ...]]: ...
 
-K = TypeVar("K")
+K_co = TypeVar("K_co", covariant=True)
+T_co = TypeVar("T_co", covariant=True)
 
 @overload
 def groupby(
-    iterable: AnyIterable[T], key: None = ...
-) -> AsyncIterator[tuple[T, AsyncIterator[T]]]: ...
+    iterable: AnyIterable[T_co], key: None = ...
+) -> AsyncIterator[tuple[T_co, AsyncIterator[T_co]]]: ...
 @overload
 def groupby(
-    iterable: AnyIterable[T], key: Callable[[T], Awaitable[K]] | Callable[[T], K]
-) -> AsyncIterator[tuple[K, AsyncIterator[T]]]: ...
+    iterable: AnyIterable[T_co],
+    key: Callable[[T_co], Awaitable[K_co]] | Callable[[T], K_co],
+) -> AsyncIterator[tuple[K_co, AsyncIterator[T_co]]]: ...

{asyncstdlib-3.12.3 → asyncstdlib-3.12.5}/pyproject.toml

@@ -20,6 +20,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
 ]
 license = {"file" = "LICENSE"}
 keywords = ["async", "enumerate", "itertools", "builtins", "functools", "contextlib"]

{asyncstdlib-3.12.3 → asyncstdlib-3.12.5}/unittests/test_functools.py

@@ -3,8 +3,9 @@ import functools
 import pytest
 
 import asyncstdlib as a
+from asyncstdlib.functools import CachedProperty
 
-from .utility import sync, asyncify, multi_sync, Switch, Schedule
+from .utility import Lock, Schedule, Switch, asyncify, multi_sync, sync
 
 
 @sync
@@ -24,24 +25,23 @@ async def test_cached_property():
     assert (await pair.total) == 3
     del pair.total
     assert (await pair.total) == 4
-    assert type(Pair.total) is a.cached_property
+    assert type(Pair.total) is CachedProperty
 
 
 @sync
 async def test_cache_property_nodict():
-    # note: The exact error is version- and possibly implementation-dependent.
-    #       Some Python version wrap all errors from __set_name__.
-    with pytest.raises(Exception):  # noqa: B017
+    class Foo:
+        __slots__ = ()
 
-        class Pair:
-            __slots__ = "a", "b"
+        def __init__(self):
+            pass  # pragma: no cover
 
-            def __init__(self, a, b):
-                pass  # pragma: no cover
+        @a.cached_property
+        async def bar(self):
+            pass  # pragma: no cover
 
-            @a.cached_property
-            async def total(self):
-                pass  # pragma: no cover
+    with pytest.raises(TypeError):
+        Foo().bar
 
 
 @multi_sync
@@ -66,6 +66,54 @@ async def test_cache_property_order():
     assert (await val.cached) == 1337  # last value fetched
 
 
+@multi_sync
+async def test_cache_property_lock_order():
+    class Value:
+        def __init__(self, value):
+            self.value = value
+
+        @a.cached_property(Lock)
+        async def cached(self):
+            value = self.value
+            await Switch()
+            return value
+
+    async def check_cached(to, expected):
+        val.value = to
+        assert (await val.cached) == expected
+
+    val = Value(0)
+    await Schedule(check_cached(5, 5), check_cached(12, 5), check_cached(1337, 5))
+    assert (await val.cached) == 5  # first value fetched
+
+
+@multi_sync
+async def test_cache_property_lock_deletion():
+    class Value:
+        def __init__(self, value):
+            self.value = value
+
+        @a.cached_property(Lock)
+        async def cached(self):
+            value = self.value
+            await Switch()
+            return value
+
+    async def check_cached(to, expected):
+        val.value = to
+        assert (await val.cached) == expected
+
+    async def delete_attribute(to):
+        val.value = to
+        awaitable = val.cached
+        del val.cached
+        assert (await awaitable) == to
+
+    val = Value(0)
+    await Schedule(check_cached(5, 5), delete_attribute(12), check_cached(1337, 12))
+    assert (await val.cached) == 12  # first value fetch after deletion
+
+
 @sync
 async def test_reduce():
     async def reduction(x, y):

{asyncstdlib-3.12.3 → asyncstdlib-3.12.5}/unittests/test_functools_lru.py

@@ -1,3 +1,4 @@
+from typing import Callable, Any
 import sys
 
 import pytest
@@ -7,8 +8,15 @@ import asyncstdlib as a
 from .utility import sync
 
 
-def method_counter(size):
+class Counter:
+    kind: object
+    count: Any
+
+
+def method_counter(size: "int | None") -> "type[Counter]":
     class Counter:
+        kind = None
+
         def __init__(self):
             self._count = 0
 
@@ -20,9 +28,10 @@ def method_counter(size):
     return Counter
 
 
-def classmethod_counter(size):
+def classmethod_counter(size: "int | None") -> "type[Counter]":
     class Counter:
         _count = 0
+        kind = classmethod
 
         def __init__(self):
             type(self)._count = 0
@@ -36,32 +45,40 @@ def classmethod_counter(size):
     return Counter
 
 
-def staticmethod_counter(size):
+def staticmethod_counter(size: "int | None") -> "type[Counter]":
     # I'm sorry for writing this test – please don't do this at home!
-    _count = 0
+    count: int = 0
 
     class Counter:
+        kind = staticmethod
+
         def __init__(self):
-            nonlocal _count
-            _count = 0
+            nonlocal count
+            count = 0
 
         @staticmethod
         @a.lru_cache(maxsize=size)
         async def count():
-            nonlocal _count
-            _count += 1
-            return _count
+            nonlocal count
+            count += 1
+            return count
 
     return Counter
 
 
-counter_factories = [method_counter, classmethod_counter, staticmethod_counter]
+counter_factories: "list[Callable[[int | None], type[Counter]]]" = [
+    method_counter,
+    classmethod_counter,
+    staticmethod_counter,
+]
 
 
 @pytest.mark.parametrize("size", [0, 3, 10, None])
 @pytest.mark.parametrize("counter_factory", counter_factories)
 @sync
-async def test_method_plain(size, counter_factory):
+async def test_method_plain(
+    size: "int | None", counter_factory: "Callable[[int | None], type[Counter]]"
+):
     """Test caching without resetting"""
 
     counter_type = counter_factory(size)
@@ -76,7 +93,9 @@ async def test_method_plain(size, counter_factory):
 @pytest.mark.parametrize("size", [0, 3, 10, None])
 @pytest.mark.parametrize("counter_factory", counter_factories)
 @sync
-async def test_method_clear(size, counter_factory):
+async def test_method_clear(
+    size: "int | None", counter_factory: "Callable[[int | None], type[Counter]]"
+):
     """Test caching with resetting everything"""
     counter_type = counter_factory(size)
     for _instance in range(4):
@@ -91,14 +110,16 @@ async def test_method_clear(size, counter_factory):
 @pytest.mark.parametrize("size", [0, 3, 10, None])
 @pytest.mark.parametrize("counter_factory", counter_factories)
 @sync
-async def test_method_discard(size, counter_factory):
+async def test_method_discard(
+    size: "int | None", counter_factory: "Callable[[int | None], type[Counter]]"
+):
     """Test caching with resetting specific item"""
     counter_type = counter_factory(size)
-    if (
-        sys.version_info < (3, 9)
-        and type(counter_type.__dict__["count"]) is classmethod
+    if not (
+        (3, 9) <= sys.version_info[:2] <= (3, 12)
+        or counter_type.kind is not classmethod
     ):
-        pytest.skip("classmethod does not respect descriptors up to 3.8")
+        pytest.skip("classmethod only respects descriptors between 3.9 and 3.12")
     for _instance in range(4):
         instance = counter_type()
         for reset in range(5):
@@ -111,7 +132,9 @@ async def test_method_discard(size, counter_factory):
 @pytest.mark.parametrize("size", [0, 3, 10, None])
 @pytest.mark.parametrize("counter_factory", counter_factories)
 @sync
-async def test_method_metadata(size, counter_factory):
+async def test_method_metadata(
+    size: "int | None", counter_factory: "Callable[[int | None], type[Counter]]"
+):
     """Test cache metadata on methods"""
     tp = counter_factory(size)
     for instance in range(4):
@@ -133,7 +156,7 @@ async def test_method_metadata(size, counter_factory):
 
 
 @pytest.mark.parametrize("size", [None, 0, 10, 128])
-def test_wrapper_attributes(size):
+def test_wrapper_attributes(size: "int | None"):
     class Bar:
         @a.lru_cache
         async def method(self, int_arg: int):

asyncstdlib-3.12.3/asyncstdlib/functools.py

@@ -1,201 +0,0 @@
-from typing import (
-    Callable,
-    Awaitable,
-    Union,
-    Any,
-    Generic,
-    Generator,
-    Optional,
-    Coroutine,
-    overload,
-)
-
-from ._typing import T, AC, AnyIterable
-from ._core import ScopedIter, awaitify as _awaitify, Sentinel
-from .builtins import anext
-from ._utility import public_module
-
-from ._lrucache import (
-    lru_cache,
-    CacheInfo,
-    CacheParameters,
-    LRUAsyncCallable,
-    LRUAsyncBoundCallable,
-)
-
-__all__ = [
-    "cache",
-    "lru_cache",
-    "CacheInfo",
-    "CacheParameters",
-    "LRUAsyncCallable",
-    "LRUAsyncBoundCallable",
-    "reduce",
-    "cached_property",
-]
-
-
-def cache(user_function: AC) -> LRUAsyncCallable[AC]:
-    """
-    Simple unbounded cache, aka memoization,  for async functions
-
-    This is a convenience function, equivalent to :py:func:`~.lru_cache`
-    with a ``maxsize`` of :py:data:`None`.
-    """
-    return lru_cache(maxsize=None)(user_function)
-
-
-class AwaitableValue(Generic[T]):
-    """Helper to provide an arbitrary value in ``await``"""
-
-    __slots__ = ("value",)
-
-    def __init__(self, value: T):
-        self.value = value
-
-    # noinspection PyUnreachableCode
-    def __await__(self) -> Generator[None, None, T]:
-        return self.value
-        yield  # type: ignore # pragma: no cover
-
-    def __repr__(self) -> str:
-        return f"{self.__class__.__name__}({self.value!r})"
-
-
-class _RepeatableCoroutine(Generic[T]):
-    """Helper to ``await`` a coroutine also more or less than just once"""
-
-    __slots__ = ("call", "args", "kwargs")
-
-    def __init__(
-        self, __call: Callable[..., Coroutine[Any, Any, T]], *args: Any, **kwargs: Any
-    ):
-        self.call = __call
-        self.args = args
-        self.kwargs = kwargs
-
-    def __await__(self) -> Generator[Any, Any, T]:
-        return self.call(*self.args, **self.kwargs).__await__()
-
-    def __repr__(self) -> str:
-        return f"<{self.__class__.__name__} object {self.call.__name__} at {id(self)}>"
-
-
-@public_module(__name__, "cached_property")
-class CachedProperty(Generic[T]):
-    """
-    Transform a method into an attribute whose value is cached
-
-    When applied to an asynchronous method of a class, instances have an attribute
-    of the same name as the method (similar to :py:class:`property`). Using this
-    attribute with ``await`` provides the value of using the method with ``await``.
-
-    The attribute value is cached on the instance after being computed;
-    subsequent uses of the attribute with ``await`` provide the cached value,
-    without executing the method again.
-    The cached value can be cleared using ``del``, in which case the next
-    access will recompute the value using the wrapped method.
-
-    .. code-block:: python3
-
-        import asyncstdlib as a
-
-        class Resource:
-            def __init__(self, url):
-                self.url = url
-
-            @a.cached_property
-            async def data(self):
-                return await asynclib.get(self.url)
-
-        resource = Resource(1, 3)
-        print(await resource.data)  # needs some time...
-        print(await resource.data)  # finishes instantly
-        del resource.data
-        print(await resource.data)  # needs some time...
-
-    Unlike a :py:class:`property`, this type does not support
-    :py:meth:`~property.setter` or :py:meth:`~property.deleter`.
-
-    .. note::
-
-        Instances on which a value is to be cached must have a
-        ``__dict__`` attribute that is a mutable mapping.
-    """
-
-    def __init__(self, getter: Callable[[Any], Awaitable[T]]):
-        self.__wrapped__ = getter
-        self._name = getter.__name__
-        self.__doc__ = getter.__doc__
-
-    def __set_name__(self, owner: Any, name: str) -> None:
-        # Check whether we can store anything on the instance
-        # Note that this is a failsafe, and might fail ugly.
-        # People who are clever enough to avoid this heuristic
-        # should also be clever enough to know the why and what.
-        if not any("__dict__" in dir(cls) for cls in owner.__mro__):
-            raise TypeError(
-                "'cached_property' requires '__dict__' "
-                f"on {owner.__name__!r} to store {name}"
-            )
-        self._name = name
-
-    @overload
-    def __get__(self, instance: None, owner: type) -> "CachedProperty[T]": ...
-
-    @overload
-    def __get__(self, instance: object, owner: Optional[type]) -> Awaitable[T]: ...
-
-    def __get__(
-        self, instance: Optional[object], owner: Optional[type]
-    ) -> Union["CachedProperty[T]", Awaitable[T]]:
-        if instance is None:
-            return self
-        # __get__ may be called multiple times before it is first awaited to completion
-        # provide a placeholder that acts just like the final value does
-        return _RepeatableCoroutine(self._get_attribute, instance)
-
-    async def _get_attribute(self, instance: object) -> T:
-        value = await self.__wrapped__(instance)
-        instance.__dict__[self._name] = AwaitableValue(value)
-        return value
-
-
-cached_property = CachedProperty
-
-
-__REDUCE_SENTINEL = Sentinel("<no default>")
-
-
-async def reduce(
-    function: Union[Callable[[T, T], T], Callable[[T, T], Awaitable[T]]],
-    iterable: AnyIterable[T],
-    initial: T = __REDUCE_SENTINEL,  # type: ignore
-) -> T:
-    """
-    Reduce an (async) iterable by cumulative application of an (async) function
-
-    :raises TypeError: if ``iterable`` is empty and ``initial`` is not given
-
-    Applies the ``function`` from the beginning of ``iterable``, as if executing
-    ``await function(current, anext(iterable))`` until ``iterable`` is exhausted.
-    Note that the output of ``function`` should be valid as its first input.
-
-    The optional ``initial`` is prepended to all items of ``iterable``
-    when applying ``function``. If the combination of ``initial``
-    and ``iterable`` contains exactly one item, it is returned without
-    calling ``function``.
-    """
-    async with ScopedIter(iterable) as item_iter:
-        try:
-            value = (
-                initial if initial is not __REDUCE_SENTINEL else await anext(item_iter)
-            )
-        except StopAsyncIteration:
-            raise TypeError(
-                "reduce() of empty sequence with no initial value"
-            ) from None
-        function = _awaitify(function)
-        async for head in item_iter:
-            value = await function(value, head)
-    return value

asyncstdlib-3.12.3/asyncstdlib/functools.pyi

@@ -1,26 +0,0 @@
-from typing import Any, Awaitable, Callable, Generic, overload
-
-from ._typing import T, T1, T2, AC, AnyIterable
-
-from ._lrucache import (
-    LRUAsyncCallable as LRUAsyncCallable,
-    LRUAsyncBoundCallable as LRUAsyncBoundCallable,
-    lru_cache as lru_cache,
-)
-
-def cache(user_function: AC) -> LRUAsyncCallable[AC]: ...
-
-class cached_property(Generic[T]):
-    def __init__(self, getter: Callable[[Any], Awaitable[T]]) -> None: ...
-    def __set_name__(self, owner: Any, name: str) -> None: ...
-    @overload
-    def __get__(self, instance: None, owner: type) -> "cached_property[T]": ...
-    @overload
-    def __get__(self, instance: object, owner: type | None) -> Awaitable[T]: ...
-
-@overload
-async def reduce(
-    function: Callable[[T1, T2], T1], iterable: AnyIterable[T2], initial: T1
-) -> T1: ...
-@overload
-async def reduce(function: Callable[[T, T], T], iterable: AnyIterable[T]) -> T: ...