asyncstdlib 3.12.1__tar.gz → 3.12.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: asyncstdlib
-Version: 3.12.1
+Version: 3.12.2
 Summary: The missing async toolbox
 Keywords: async,enumerate,itertools,builtins,functools,contextlib
 Author-email: Max Fischer <maxfischer2781@gmail.com>
@@ -26,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.1 → asyncstdlib-3.12.2}/asyncstdlib/__init__.py

@@ -19,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,
@@ -39,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.1"
+__version__ = "3.12.2"
 
 __all__ = [
     "anext",
@@ -65,6 +71,7 @@ __all__ = [
     "cached_property",
     # contextlib
     "closing",
+    "ContextDecorator",
     "contextmanager",
     "nullcontext",
     "ExitStack",

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

@@ -6,7 +6,10 @@ 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,
@@ -72,6 +75,14 @@ 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
 
@@ -106,23 +117,37 @@ class LRUAsyncCallable(Protocol[AC]):
         ...
 
 
-class LRUAsyncBoundCallable(LRUAsyncCallable[AC]):
+# these are fake and only exist for placeholders
+S = TypeVar("S")
+S2 = TypeVar("S2")
+P = TypeVar("P")
+R = TypeVar("R")
+
+
+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)
 
@@ -289,22 +314,12 @@ 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  # type: ignore[reportIncompatibleMethodOverride]
@@ -342,7 +357,6 @@ class MemoizedLRUAsyncCallable(LRUAsyncCallable[AC]):
     )
 
     __wrapped__: AC
-    __get__ = cache__get
 
     def __init__(self, call: AC, typed: bool):
         self.__wrapped__ = call  # type: ignore[reportIncompatibleMethodOverride]
@@ -397,7 +411,6 @@ class CachedLRUAsyncCallable(LRUAsyncCallable[AC]):
     )
 
     __wrapped__: AC
-    __get__ = cache__get
 
     def __init__(self, call: AC, typed: bool, maxsize: int):
         self.__wrapped__ = call  # type: ignore[reportIncompatibleMethodOverride]

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.1 → asyncstdlib-3.12.2}/asyncstdlib/_typing.py

@@ -14,13 +14,14 @@ from typing import (
     Callable,
     Any,
     Awaitable,
+    runtime_checkable,
+    Protocol,
+    ContextManager,
+    TypedDict,
 )
 
-from typing import Protocol, AsyncContextManager, ContextManager, TypedDict
-
 __all__ = [
     "Protocol",
-    "AsyncContextManager",
     "ContextManager",
     "TypedDict",
     "T",
@@ -35,6 +36,8 @@ __all__ = [
     "HK",
     "LT",
     "ADD",
+    "AClose",
+    "ACloseable",
     "AnyIterable",
 ]
 
@@ -70,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.1 → asyncstdlib-3.12.2}/asyncstdlib/asynctools.py

@@ -2,6 +2,7 @@ from asyncio import iscoroutinefunction
 from functools import wraps
 from typing import (
     Union,
+    AsyncContextManager,
     AsyncIterator,
     TypeVar,
     AsyncGenerator,
@@ -14,7 +15,7 @@ from typing import (
     Optional,
 )
 
-from ._typing import AsyncContextManager, T, T1, T2, T3, T4, T5, AnyIterable
+from ._typing import T, T1, T2, T3, T4, T5, AnyIterable
 from ._core import aiter
 from .contextlib import nullcontext
 
@@ -50,11 +51,11 @@ class _BorrowedAsyncIterator(AsyncGenerator[T, S]):
         self.__anext__ = self._wrapper.__anext__  # type: ignore
         if hasattr(iterator, "asend"):
             self.asend = (
-                iterator.asend  # pyright: ignore[reportUnknownMemberType,reportGeneralTypeIssues]
+                iterator.asend  # pyright: ignore[reportUnknownMemberType,reportAttributeAccessIssue]
             )
         if hasattr(iterator, "athrow"):
             self.athrow = (
-                iterator.athrow  # pyright: ignore[reportUnknownMemberType,reportGeneralTypeIssues]
+                iterator.athrow  # pyright: ignore[reportUnknownMemberType,reportAttributeAccessIssue]
             )
 
     def __aiter__(self) -> AsyncGenerator[T, S]:
@@ -409,9 +410,9 @@ async def any_iter(
         async for item in iterable:
             yield (
                 item if not isinstance(item, Awaitable) else await item
-            )  # pyright: ignore[reportGeneralTypeIssues]
+            )  # pyright: ignore[reportReturnType]
     else:
         for item in iterable:
             yield (
                 item if not isinstance(item, Awaitable) else await item
-            )  # pyright: ignore[reportGeneralTypeIssues]
+            )  # pyright: ignore[reportReturnType]

{asyncstdlib-3.12.1 → asyncstdlib-3.12.2}/asyncstdlib/builtins.py

@@ -444,7 +444,7 @@ async def sorted(
         try:
             return _sync_builtins.sorted(iterable, reverse=reverse)  # type: ignore
         except TypeError:
-            items: "_sync_builtins.list[Any]" = [item async for item in aiter(iterable)]
+            items: _sync_builtins.list[Any] = [item async for item in aiter(iterable)]
             items.sort(reverse=reverse)
             return items
     else:

{asyncstdlib-3.12.1 → asyncstdlib-3.12.2}/asyncstdlib/contextlib.py

@@ -8,18 +8,17 @@ from typing import (
     Any,
     Awaitable,
     Deque,
-    overload,
+    AsyncContextManager,
 )
 from functools import wraps
 from collections import deque
 from functools import partial
 import sys
 
-from ._typing import Protocol, AsyncContextManager, ContextManager, T, C
+from ._typing import AClose, ContextManager, AC, T, C
 from ._core import awaitify
 from ._utility import public_module
 
-
 AnyContextManager = Union[AsyncContextManager[T], ContextManager[T]]
 
 
@@ -28,18 +27,10 @@ AnyContextManager = Union[AsyncContextManager[T], ContextManager[T]]
 AbstractContextManager = AsyncContextManager
 
 
-class ACloseable(Protocol):
-    async def aclose(self) -> None:
-        """Asynchronously close this object"""
-
-
-AC = TypeVar("AC", bound=ACloseable)
-
-
 def contextmanager(
     func: Callable[..., AsyncGenerator[T, None]]
 ) -> Callable[..., AsyncContextManager[T]]:
-    """
+    r"""
     Create an asynchronous context manager out of an asynchronous generator function
 
     This is intended as a decorator for an asynchronous generator function.
@@ -50,7 +41,7 @@ def contextmanager(
     .. code-block:: python3
 
         @contextmanager
-        async def Context(*args, **kwargs):
+        async def context(*args, **kwargs):
             # __aenter__
             yield  # context value
             # __aexit__
@@ -58,6 +49,9 @@ def contextmanager(
     Note that if an exception ends the context block, it gets re-raised at the ``yield``
     inside the asynchronous generator (via :py:meth:`~agen.athrow`). In order to handle
     this exception, the ``yield`` should be wrapped in a ``try`` statement.
+
+    The created context manager is a :py:class:`~.ContextDecorator` and can also be used
+    as a decorator. It is automatically entered when a decorated function is ``await``\ ed.
     """
 
     @wraps(func)
@@ -67,13 +61,62 @@ def contextmanager(
     return helper
 
 
-class _AsyncGeneratorContextManager(Generic[T]):
+class ContextDecorator(AsyncContextManager[T]):
+    """
+    Base class to turn an async context manager into a decorator as well
+
+    Inheriting from this class adds the scaffolding to automatically enter
+    an async context manager on awaiting any callable decorated with it:
+
+    .. code:: python3
+
+        class DecoratorAndContext(ContextDecorator):
+            async def __aenter__(self) -> Any:
+                print("entering", self)
+
+            async def __aexit__(self, *exc):
+                print("exiting", self)
+
+        @DecoratorAndContext()
+        async def func():
+            print("running some function...")
+
+    The context manager can still be used regularly in `async with` statements.
+
+    Since functions are decorated with an existing context manager instance,
+    the same instance is entered and exited on every call. If the context is
+    not safe to be entered multiple times or even concurrently it should implement
+    the method ``_recreate_cm(:Self) -> Self`` to create a copy of itself.
+    """
+
+    __slots__ = ()
+
+    def _recreate_cm(self):
+        """Return another instance of the context manager that is ready for entering again"""
+        # Default to assuming the CM is reentrant, concurrency safe, ... and just return itself.
+        # Since for the `async` case many CMs have to be this anyway, this should apply most.
+        return self
+
+    def __call__(self, func: AC, /) -> AC:
+        @wraps(func)
+        async def inner(*args: Any, **kwds: Any) -> Any:
+            async with self._recreate_cm():
+                return await func(*args, **kwds)
+
+        return inner  # type: ignore
+
+
+class _AsyncGeneratorContextManager(ContextDecorator[T]):
     def __init__(
         self, func: Callable[..., AsyncGenerator[T, None]], args: Any, kwds: Any
     ):
         self.gen = func(*args, **kwds)
+        self.__recreate_args = func, args, kwds
         self.__doc__ = getattr(func, "__doc__", type(self).__doc__)
 
+    def _recreate_cm(self):
+        return type(self)(*self.__recreate_args)
+
     async def __aenter__(self) -> T:
         try:
             return await self.gen.__anext__()
@@ -126,7 +169,7 @@ class _AsyncGeneratorContextManager(Generic[T]):
 
 
 @public_module(__name__, "closing")
-class Closing(Generic[AC]):
+class Closing(Generic[AClose]):
     """
     Create an :term:`asynchronous context manager` to ``aclose`` some ``thing`` on exit
 
@@ -150,10 +193,10 @@ class Closing(Generic[AC]):
                  is eventually closed and only :term:`borrowed <borrowing>` until then.
     """
 
-    def __init__(self, thing: AC):
+    def __init__(self, thing: AClose):
         self.thing = thing
 
-    async def __aenter__(self) -> AC:
+    async def __aenter__(self) -> AClose:
         return self.thing
 
     async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
@@ -165,7 +208,7 @@ closing = Closing
 
 
 @public_module(__name__, "nullcontext")
-class NullContext(Generic[T]):
+class NullContext(AsyncContextManager[T]):
     """
     Create an :term:`asynchronous context manager` that only returns ``enter_result``
 
@@ -190,22 +233,10 @@ class NullContext(Generic[T]):
 
     __slots__ = ("enter_result",)
 
-    @overload
-    def __init__(self: "NullContext[None]", enter_result: None = ...) -> None: ...
-
-    @overload
-    def __init__(self: "NullContext[T]", enter_result: T) -> None: ...
-
-    def __init__(self, enter_result: Optional[T] = None):
+    def __init__(self, enter_result: T = None):
         self.enter_result = enter_result
 
-    @overload
-    async def __aenter__(self: "NullContext[None]") -> None: ...
-
-    @overload
-    async def __aenter__(self: "NullContext[T]") -> T: ...
-
-    async def __aenter__(self) -> Optional[T]:
+    async def __aenter__(self) -> T:
         return self.enter_result
 
     async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
@@ -215,15 +246,7 @@ class NullContext(Generic[T]):
 nullcontext = NullContext
 
 
-SE = TypeVar(
-    "SE",
-    bound=Union[
-        AsyncContextManager[Any],
-        ContextManager[Any],
-        Callable[[Any, BaseException, Any], Optional[bool]],
-        Callable[[Any, BaseException, Any], Awaitable[Optional[bool]]],
-    ],
-)
+SE = TypeVar("SE")
 
 
 class ExitStack:

asyncstdlib-3.12.2/asyncstdlib/contextlib.pyi

@@ -0,0 +1,115 @@
+from typing import (
+    TypeVar,
+    Generic,
+    AsyncGenerator,
+    Callable,
+    Optional,
+    Any,
+    Awaitable,
+    overload,
+    AsyncContextManager,
+)
+from typing_extensions import ParamSpec, Self
+from types import TracebackType
+from abc import ABCMeta
+
+from ._typing import AClose, ContextManager, AC, T, R
+
+AnyContextManager = AsyncContextManager[T] | ContextManager[T]
+
+class ContextDecorator(AsyncContextManager[T], metaclass=ABCMeta):
+    """
+    Base class for an async context manager useable as a decorator as well
+
+    Inheriting from this class adds the scaffolding to automatically enter
+    an async context manager on awaiting any callable decorated with it:
+
+    .. code:: python3
+
+        class DecoratorAndContext(AsyncContextDecorator):
+            async def __aenter__(self) -> Any:
+                print("entering", self)
+
+            async def __aexit__(self, *exc):
+                print("exiting", self)
+
+        @DecoratorAndContext()
+        async def func():
+            # DecoratorAndContext has been entered already
+            print("running some function...")
+            # DecoratorAndContext will be exited immediately
+
+    The context manager can still be used regularly in `async with` statements.
+
+    Since functions are decorated with an existing context manager instance,
+    the same instance is entered and exited on every call. If the context is
+    not safe to be entered multiple times or even concurrently the subclass
+    should implement the method `_recreate_cm(:Self) -> Self` to create a copy.
+    """
+
+    __slots__ = ()
+
+    def _recreate_cm(self: Self) -> Self: ...
+    def __call__(self, func: AC, /) -> AC: ...
+
+P = ParamSpec("P")
+
+def contextmanager(
+    func: Callable[P, AsyncGenerator[T, None]]
+) -> Callable[P, ContextDecorator[T]]: ...
+
+class closing(Generic[AClose]):
+    def __init__(self, thing: AClose) -> None: ...
+    async def __aenter__(self: Self) -> Self: ...
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> bool: ...
+
+class nullcontext(AsyncContextManager[T]):
+    enter_result: T
+
+    @overload
+    def __init__(self: nullcontext[None], enter_result: None = ...) -> None: ...
+    @overload
+    def __init__(self: nullcontext[T], 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: ...
+
+SE = TypeVar(
+    "SE",
+    bound=AsyncContextManager[Any]
+    | ContextManager[Any]
+    | Callable[
+        [type[BaseException] | None, BaseException | None, TracebackType | None],
+        Optional[bool],
+    ]
+    | Callable[
+        [type[BaseException] | None, BaseException | None, TracebackType | None],
+        Awaitable[Optional[bool]],
+    ],
+)
+
+class ExitStack:
+    def __init__(self) -> None: ...
+    def pop_all(self: Self) -> Self: ...
+    def push(self, exit: SE) -> SE: ...
+    def callback(
+        self, callback: Callable[P, R], *args: P.args, **kwargs: P.kwargs
+    ) -> Callable[P, R]: ...
+    async def enter_context(self, cm: AnyContextManager[T]) -> T: ...
+    async def aclose(self) -> None: ...
+    async def __aenter__(self: Self) -> Self: ...
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        tb: TracebackType | None,
+    ) -> bool: ...