asyncstdlib 3.12.0__tar.gz → 3.12.2__tar.gz

{asyncstdlib-3.12.0 → asyncstdlib-3.12.2}/PKG-INFO

@@ -1,24 +1,21 @@
 Metadata-Version: 2.1
 Name: asyncstdlib
-Version: 3.12.0
+Version: 3.12.2
 Summary: The missing async toolbox
 Keywords: async,enumerate,itertools,builtins,functools,contextlib
 Author-email: Max Fischer <maxfischer2781@gmail.com>
-Requires-Python: ~=3.6
+Requires-Python: ~=3.8
 Description-Content-Type: text/x-rst
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: typing_extensions; python_version<'3.8'
 Requires-Dist: sphinx ; extra == "doc"
 Requires-Dist: sphinxcontrib-trio ; extra == "doc"
 Requires-Dist: pytest ; extra == "test"
@@ -29,6 +26,7 @@ Requires-Dist: coverage ; extra == "test"
 Requires-Dist: pytest-cov ; extra == "test"
 Requires-Dist: flake8-2020 ; extra == "test"
 Requires-Dist: mypy ; extra == "test" and ( implementation_name=='cpython')
+Requires-Dist: typing-extensions ; extra == "test"
 Project-URL: Documentation, https://asyncstdlib.readthedocs.io/en/latest/
 Project-URL: Source, https://github.com/maxfischer2781/asyncstdlib
 Provides-Extra: doc

{asyncstdlib-3.12.0 → asyncstdlib-3.12.2}/asyncstdlib/__init__.py

@@ -1,4 +1,5 @@
 """The missing async toolbox"""
+
 from .builtins import (
     anext,
     zip,
@@ -18,7 +19,13 @@ from .builtins import (
     sorted,
 )
 from .functools import reduce, lru_cache, cache, cached_property
-from .contextlib import closing, contextmanager, nullcontext, ExitStack
+from .contextlib import (
+    closing,
+    ContextDecorator,
+    contextmanager,
+    nullcontext,
+    ExitStack,
+)
 from .itertools import (
     accumulate,
     batched,
@@ -38,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.0"
+__version__ = "3.12.2"
 
 __all__ = [
     "anext",
@@ -64,6 +71,7 @@ __all__ = [
     "cached_property",
     # contextlib
     "closing",
+    "ContextDecorator",
     "contextmanager",
     "nullcontext",
     "ExitStack",

{asyncstdlib-3.12.0 → asyncstdlib-3.12.2}/asyncstdlib/_core.py

@@ -1,3 +1,13 @@
+"""
+Internal helpers to safely build async abstractions
+
+While some of these helpers have public siblings
+(e.g. :py:class:`~.ScopedIter` and :py:func:`~.asynctools.scoped_iter`)
+they are purposely kept separate.
+Any helpers in this module are *not* bound to maintaining a public interface,
+and offer less convenience to save on overhead.
+"""
+
 from inspect import iscoroutinefunction
 from typing import (
     Any,
@@ -55,20 +65,19 @@ async def _aiter_sync(iterable: Iterable[T]) -> AsyncIterator[T]:
 
 
 class ScopedIter(Generic[T]):
-    """Context manager that provides and cleans up an iterator for an iterable"""
+    """
+    Context manager that provides and cleans up an iterator for an iterable
 
-    __slots__ = ("_iterable", "_iterator")
+    Note that unlike :py:func:`~.asynctools.scoped_iter`, this helper does
+    *not* borrow the iterator automatically. Use :py:func:`~.borrow` if needed.
+    """
+
+    __slots__ = ("_iterator",)
 
     def __init__(self, iterable: AnyIterable[T]):
-        self._iterable: Optional[AnyIterable[T]] = iterable
-        self._iterator: Optional[AsyncIterator[T]] = None
+        self._iterator: AsyncIterator[T] = aiter(iterable)
 
     async def __aenter__(self) -> AsyncIterator[T]:
-        assert (
-            self._iterable is not None
-        ), f"{self.__class__.__name__} is not re-entrant"
-        self._iterator = aiter(self._iterable)
-        self._iterable = None
         return self._iterator
 
     async def __aexit__(
@@ -76,20 +85,18 @@ class ScopedIter(Generic[T]):
         exc_type: Optional[Type[BaseException]],
         exc_val: Optional[BaseException],
         exc_tb: Optional[TracebackType],
-    ) -> bool:
+    ) -> None:
         try:
             aclose = self._iterator.aclose()  # type: ignore
         except AttributeError:
             pass
         else:
             await aclose
-        return False
 
 
-async def borrow(iterator: AsyncIterator[T]) -> AsyncGenerator[T, None]:
+def borrow(iterator: AsyncIterator[T]) -> AsyncGenerator[T, None]:
     """Borrow an async iterator for iteration, preventing it from being closed"""
-    async for item in iterator:
-        yield item
+    return (item async for item in iterator)
 
 
 def awaitify(
@@ -112,8 +119,7 @@ class Awaitify(Generic[T]):
         self._async_call: Optional[Callable[..., Awaitable[T]]] = None
 
     def __call__(self, *args: Any, **kwargs: Any) -> Awaitable[T]:
-        async_call = self._async_call
-        if async_call is None:
+        if (async_call := self._async_call) is None:
             value = self.__wrapped__(*args, **kwargs)
             if isinstance(value, Awaitable):
                 self._async_call = self.__wrapped__  # type: ignore

{asyncstdlib-3.12.0 → asyncstdlib-3.12.2}/asyncstdlib/_lrucache.py

@@ -5,7 +5,11 @@ This is loosely based on the CPython 3.8 implementation. In specific,
 several performance hacks are skipped in favour of maintainability,
 especially when they might not apply to PyPy.
 """
+
+from __future__ import annotations
 from typing import (
+    Generic,
+    TypeVar,
     NamedTuple,
     Callable,
     Any,
@@ -71,20 +75,31 @@ class LRUAsyncCallable(Protocol[AC]):
         """The callable wrapped by this cache"""
         raise NotImplementedError
 
+    def __get__(
+        self: LRUAsyncCallable[Any], instance: object, owner: Optional[type] = None
+    ) -> Any:
+        """Descriptor ``__get__`` for caches to bind them on lookup"""
+        if instance is None:
+            return self
+        return LRUAsyncBoundCallable(self, instance)
+
     #: Get the result of ``await __wrapped__(...)`` from the cache or evaluation
     __call__: AC
 
     def cache_parameters(self) -> CacheParameters:
         """Get the parameters of the cache"""
+        ...
 
     def cache_info(self) -> CacheInfo:
         """
         Get the current performance and boundary of the cache
         as a :py:class:`~typing.NamedTuple`
         """
+        ...
 
     def cache_clear(self) -> None:
         """Evict all call argument patterns and their results from the cache"""
+        ...
 
     def cache_discard(self, *args: Any, **kwargs: Any) -> None:
         """
@@ -95,28 +110,44 @@ class LRUAsyncCallable(Protocol[AC]):
         the descriptor must support wrapping descriptors for this method
         to detect implicit arguments such as ``self``.
         """
+        # Maintainers note:
         # "support wrapping descriptors" means that the wrapping descriptor has to use
         # the cache as a descriptor as well, i.e. invoke its ``__get__`` method instead
         # of just passing in `self`/`cls`/... directly.
+        ...
+
+
+# these are fake and only exist for placeholders
+S = TypeVar("S")
+S2 = TypeVar("S2")
+P = TypeVar("P")
+R = TypeVar("R")
 
 
-class LRUAsyncBoundCallable(LRUAsyncCallable[AC]):
+class LRUAsyncBoundCallable(Generic[S, P, R]):  # type: ignore[reportInvalidTypeVarUse]
     """A :py:class:`~.LRUAsyncCallable` that is bound like a method"""
 
     __slots__ = ("__weakref__", "_lru", "__self__")
 
-    def __init__(self, lru: LRUAsyncCallable[AC], __self__: object):
+    def __init__(self, lru: LRUAsyncCallable[Any], __self__: object):
         self._lru = lru
         self.__self__ = __self__
 
     @property
-    def __wrapped__(self) -> AC:
+    def __wrapped__(self) -> Any:
         return self._lru.__wrapped__
 
     @property
-    def __func__(self) -> LRUAsyncCallable[AC]:
+    def __func__(self) -> LRUAsyncCallable[Any]:
         return self._lru
 
+    def __get__(
+        self: LRUAsyncBoundCallable[S, P, R],
+        instance: S2,
+        owner: Optional[type] = None,
+    ) -> LRUAsyncBoundCallable[S2, P, R]:
+        return LRUAsyncBoundCallable(self._lru, instance)
+
     def __call__(self, *args, **kwargs):  # type: ignore
         return self._lru(self.__self__, *args, **kwargs)
 
@@ -149,15 +180,13 @@ class LRUAsyncBoundCallable(LRUAsyncCallable[AC]):
 
 
 @overload
-def lru_cache(maxsize: AC, typed: bool = ...) -> LRUAsyncCallable[AC]:
-    ...
+def lru_cache(maxsize: AC, typed: bool = ...) -> LRUAsyncCallable[AC]: ...
 
 
 @overload
 def lru_cache(
     maxsize: Optional[int] = ..., typed: bool = ...
-) -> Callable[[AC], LRUAsyncCallable[AC]]:
-    ...
+) -> Callable[[AC], LRUAsyncCallable[AC]]: ...
 
 
 @public_module("asyncstdlib.functools")
@@ -212,7 +241,8 @@ def lru_cache(
     elif callable(maxsize):
         # used as function decorator, first arg is the function to be wrapped
         fast_wrapper = CachedLRUAsyncCallable(cast(AC, maxsize), typed, 128)
-        return update_wrapper(fast_wrapper, maxsize)
+        update_wrapper(fast_wrapper, maxsize)
+        return fast_wrapper
     elif maxsize is not None:
         raise TypeError(
             "first argument to 'lru_cache' must be an int, a callable or None"
@@ -227,7 +257,8 @@ def lru_cache(
             wrapper = UncachedLRUAsyncCallable(function, typed)
         else:
             wrapper = CachedLRUAsyncCallable(function, typed, maxsize)
-        return update_wrapper(wrapper, function)
+        update_wrapper(wrapper, function)
+        return wrapper
 
     return lru_decorator
 
@@ -283,29 +314,19 @@ class CallKey:
         return cls(key)
 
 
-def cache__get(
-    self: LRUAsyncCallable[AC], instance: object, owner: Optional[type] = None
-) -> LRUAsyncCallable[AC]:
-    """Descriptor ``__get__`` for caches to bind them on lookup"""
-    if instance is None:
-        return self
-    return LRUAsyncBoundCallable(self, instance)
-
-
 class UncachedLRUAsyncCallable(LRUAsyncCallable[AC]):
     """Wrap the async ``call`` to track accesses as for caching/memoization"""
 
     __slots__ = ("__weakref__", "__dict__", "__wrapped__", "__misses", "__typed")
 
     __wrapped__: AC
-    __get__ = cache__get
 
     def __init__(self, call: AC, typed: bool):
-        self.__wrapped__ = call
+        self.__wrapped__ = call  # type: ignore[reportIncompatibleMethodOverride]
         self.__misses = 0
         self.__typed = typed
 
-    async def __call__(self, *args, **kwargs):  # type: ignore
+    async def __call__(self, *args: Any, **kwargs: Any) -> Any:  # type: ignore[reportIncompatibleVariableOverride]
         self.__misses += 1
         return await self.__wrapped__(*args, **kwargs)
 
@@ -336,16 +357,15 @@ class MemoizedLRUAsyncCallable(LRUAsyncCallable[AC]):
     )
 
     __wrapped__: AC
-    __get__ = cache__get
 
     def __init__(self, call: AC, typed: bool):
-        self.__wrapped__ = call
+        self.__wrapped__ = call  # type: ignore[reportIncompatibleMethodOverride]
         self.__hits = 0
         self.__misses = 0
         self.__typed = typed
         self.__cache: Dict[Union[CallKey, int, str], Any] = {}
 
-    async def __call__(self, *args, **kwargs):  # type: ignore
+    async def __call__(self, *args: Any, **kwargs: Any) -> Any:  # type: ignore[reportIncompatibleVariableOverride]
         key = CallKey.from_call(args, kwargs, typed=self.__typed)
         try:
             result = self.__cache[key]
@@ -391,17 +411,16 @@ class CachedLRUAsyncCallable(LRUAsyncCallable[AC]):
     )
 
     __wrapped__: AC
-    __get__ = cache__get
 
     def __init__(self, call: AC, typed: bool, maxsize: int):
-        self.__wrapped__ = call
+        self.__wrapped__ = call  # type: ignore[reportIncompatibleMethodOverride]
         self.__hits = 0
         self.__misses = 0
         self.__typed = typed
         self.__maxsize = maxsize
         self.__cache: OrderedDict[Union[int, str, CallKey], Any] = OrderedDict()
 
-    async def __call__(self, *args, **kwargs):  # type: ignore
+    async def __call__(self, *args: Any, **kwargs: Any) -> Any:  # type: ignore[reportIncompatibleVariableOverride]
         key = CallKey.from_call(args, kwargs, typed=self.__typed)
         try:
             result = self.__cache[key]

asyncstdlib-3.12.2/asyncstdlib/_lrucache.pyi

@@ -0,0 +1,90 @@
+from typing import (
+    TypeVar,
+    Any,
+    Awaitable,
+    Callable,
+    Coroutine,
+    Generic,
+    NamedTuple,
+    overload,
+    Protocol,
+)
+from typing_extensions import ParamSpec, Concatenate
+
+from ._typing import AC, TypedDict
+
+class CacheInfo(NamedTuple):
+    hits: int
+    misses: int
+    maxsize: int | None
+    currsize: int
+
+class CacheParameters(TypedDict):
+    maxsize: int | None
+    typed: bool
+
+R = TypeVar("R")
+P = ParamSpec("P")
+S = TypeVar("S")
+S2 = TypeVar("S2")
+
+class LRUAsyncCallable(Protocol[AC]):
+    __slots__: tuple[str, ...]
+    __call__: AC
+    @overload
+    def __get__(
+        self: LRUAsyncCallable[AC], instance: None, owner: type | None = ...
+    ) -> LRUAsyncCallable[AC]: ...
+    @overload
+    def __get__(
+        self: LRUAsyncCallable[Callable[Concatenate[S, P], Coroutine[Any, Any, R]]],
+        instance: S,
+        owner: type | None = ...,
+    ) -> LRUAsyncBoundCallable[S, P, R]: ...
+    @overload
+    def __get__(
+        self: LRUAsyncCallable[Callable[Concatenate[S, P], Awaitable[R]]],
+        instance: S,
+        owner: type | None = ...,
+    ) -> LRUAsyncBoundCallable[S, P, R]: ...
+    @property
+    def __wrapped__(self) -> AC: ...
+    def cache_parameters(self) -> CacheParameters: ...
+    def cache_info(self) -> CacheInfo: ...
+    def cache_clear(self) -> None: ...
+    def cache_discard(self, *args: Any, **kwargs: Any) -> None: ...
+
+class LRUAsyncBoundCallable(Generic[S, P, R]):
+    __slots__: tuple[str, ...]
+    __self__: S
+    __call__: Callable[P, Awaitable[R]]
+    @overload
+    def __get__(
+        self, instance: None, owner: type | None = ...
+    ) -> LRUAsyncBoundCallable[S, P, R]: ...
+    @overload
+    def __get__(
+        self, instance: S2, owner: type | None = ...
+    ) -> LRUAsyncBoundCallable[S2, P, R]: ...
+    def __init__(
+        self,
+        lru: LRUAsyncCallable[Callable[Concatenate[S, P], Awaitable[R]]],
+        __self__: S,
+    ) -> None: ...
+    @property
+    def __wrapped__(self) -> Callable[Concatenate[S, P], Awaitable[R]]: ...
+    @property
+    def __func__(
+        self,
+    ) -> LRUAsyncCallable[Callable[Concatenate[S, P], Awaitable[R]]]: ...
+    def cache_parameters(self) -> CacheParameters: ...
+    def cache_info(self) -> CacheInfo: ...
+    def cache_clear(self) -> None: ...
+    def cache_discard(self, *args: Any, **kwargs: Any) -> None: ...
+
+@overload
+def lru_cache(maxsize: AC, typed: bool = ...) -> LRUAsyncCallable[AC]: ...
+@overload
+def lru_cache(
+    maxsize: int | None = ..., typed: bool = ...
+) -> Callable[[AC], LRUAsyncCallable[AC]]: ...

{asyncstdlib-3.12.0 → asyncstdlib-3.12.2}/asyncstdlib/_typing.py

@@ -4,7 +4,7 @@ Helper module to simplify version specific typing imports
 This module is for internal use only. Do *not* put any new
 "async typing" definitions here.
 """
-import sys
+
 from typing import (
     TypeVar,
     Hashable,
@@ -14,21 +14,14 @@ from typing import (
     Callable,
     Any,
     Awaitable,
+    runtime_checkable,
+    Protocol,
+    ContextManager,
+    TypedDict,
 )
 
-if sys.version_info >= (3, 8):
-    from typing import Protocol, AsyncContextManager, ContextManager, TypedDict
-else:
-    from typing_extensions import (
-        Protocol,
-        AsyncContextManager,
-        ContextManager,
-        TypedDict,
-    )
-
 __all__ = [
     "Protocol",
-    "AsyncContextManager",
     "ContextManager",
     "TypedDict",
     "T",
@@ -43,6 +36,8 @@ __all__ = [
     "HK",
     "LT",
     "ADD",
+    "AClose",
+    "ACloseable",
     "AnyIterable",
 ]
 
@@ -78,5 +73,15 @@ class SupportsAdd(Protocol):
         raise NotImplementedError
 
 
+# await AClose.aclose()
+AClose = TypeVar("AClose", bound="ACloseable")
+
+
+@runtime_checkable
+class ACloseable(Protocol):
+    async def aclose(self) -> None:
+        """Asynchronously close this object"""
+
+
 #: (async) iter T
 AnyIterable = Union[Iterable[T], AsyncIterable[T]]

{asyncstdlib-3.12.0 → asyncstdlib-3.12.2}/asyncstdlib/_utility.py

@@ -1,4 +1,4 @@
-from typing import TypeVar, Any, Optional, Callable
+from typing import TypeVar, Optional, Callable
 
 from ._typing import Protocol
 
@@ -29,21 +29,3 @@ def public_module(
         return thing
 
     return decorator
-
-
-def slot_get(instance: object, name: str) -> Any:
-    """
-    Emulate ``instance.name`` using slot lookup as used for special methods
-
-    This invokes the descriptor protocol, i.e. it calls the attribute's
-    ``__get__`` if available.
-    """
-
-    owner = type(instance)
-    attribute = getattr(owner, name)
-    try:
-        descriptor_get = attribute.__get__
-    except AttributeError:
-        return attribute
-    else:
-        return descriptor_get(instance, owner)