Improve various signatures that shouldn't be async def, but currently are (#7491)

Co-authored-by: Thomas Grainger <tagrain@gmail.com>

stdlib/_typeshed/__init__.pyi

@@ -7,7 +7,7 @@ import ctypes
 import mmap
 import sys
 from os import PathLike
-from typing import AbstractSet, Any, Container, Generic, Iterable, Protocol, TypeVar
+from typing import AbstractSet, Any, Awaitable, Container, Generic, Iterable, Protocol, TypeVar
 from typing_extensions import Final, Literal, final
 
 _KT = TypeVar("_KT")
@@ -33,7 +33,7 @@ class SupportsNext(Protocol[_T_co]):
 
 # stable
 class SupportsAnext(Protocol[_T_co]):
-    async def __anext__(self) -> _T_co: ...
+    def __anext__(self) -> Awaitable[_T_co]: ...
 
 # Comparison protocols
 

stdlib/builtins.pyi

@@ -29,6 +29,7 @@ from typing import (
     IO,
     AbstractSet,
     Any,
+    Awaitable,
     BinaryIO,
     ByteString,
     Generic,
@@ -72,6 +73,8 @@ _T4 = TypeVar("_T4")
 _T5 = TypeVar("_T5")
 _SupportsNextT = TypeVar("_SupportsNextT", bound=SupportsNext[Any], covariant=True)
 _SupportsAnextT = TypeVar("_SupportsAnextT", bound=SupportsAnext[Any], covariant=True)
+_AwaitableT = TypeVar("_AwaitableT", bound=Awaitable[Any])
+_AwaitableT_co = TypeVar("_AwaitableT_co", bound=Awaitable[Any], covariant=True)
 
 class _SupportsIter(Protocol[_T_co]):
     def __iter__(self) -> _T_co: ...
@@ -1068,8 +1071,15 @@ class _PathLike(Protocol[_AnyStr_co]):
 
 if sys.version_info >= (3, 10):
     def aiter(__async_iterable: _SupportsAiter[_SupportsAnextT]) -> _SupportsAnextT: ...
+
+    class _SupportsSynchronousAnext(Protocol[_AwaitableT_co]):
+        def __anext__(self) -> _AwaitableT_co: ...
+
     @overload
-    async def anext(__i: SupportsAnext[_T]) -> _T: ...
+    # `anext` is not, in fact, an async function. When default is not provided
+    # `anext` is just a passthrough for `obj.__anext__`
+    # See discussion in #7491 and pure-Python implementation of `anext` at https://github.com/python/cpython/blob/ea786a882b9ed4261eafabad6011bc7ef3b5bf94/Lib/test/test_asyncgen.py#L52-L80
+    def anext(__i: _SupportsSynchronousAnext[_AwaitableT]) -> _AwaitableT: ...
     @overload
     async def anext(__i: SupportsAnext[_T], default: _VT) -> _T | _VT: ...
 

stdlib/contextlib.pyi

@@ -154,7 +154,7 @@ class closing(AbstractContextManager[_SupportsCloseT]):
 
 if sys.version_info >= (3, 10):
     class _SupportsAclose(Protocol):
-        async def aclose(self) -> object: ...
+        def aclose(self) -> Awaitable[object]: ...
     _SupportsAcloseT = TypeVar("_SupportsAcloseT", bound=_SupportsAclose)
 
     class aclosing(AbstractAsyncContextManager[_SupportsAcloseT]):

stdlib/typing.pyi

@@ -752,26 +752,22 @@ class AsyncIterable(Protocol[_T_co]):
 @runtime_checkable
 class AsyncIterator(AsyncIterable[_T_co], Protocol[_T_co]):
     @abstractmethod
-    async def __anext__(self) -> _T_co: ...
+    def __anext__(self) -> Awaitable[_T_co]: ...
     def __aiter__(self) -> AsyncIterator[_T_co]: ...
 
 class AsyncGenerator(AsyncIterator[_T_co], Generic[_T_co, _T_contra]):
+    def __anext__(self) -> Awaitable[_T_co]: ...
     @abstractmethod
-    async def __anext__(self) -> _T_co: ...
-    @abstractmethod
-    async def asend(self, __value: _T_contra) -> _T_co: ...
+    def asend(self, __value: _T_contra) -> Awaitable[_T_co]: ...
     @overload
     @abstractmethod
-    async def athrow(
+    def athrow(
         self, __typ: Type[BaseException], __val: BaseException | object = ..., __tb: TracebackType | None = ...
-    ) -> _T_co: ...
+    ) -> Awaitable[_T_co]: ...
     @overload
     @abstractmethod
-    async def athrow(self, __typ: BaseException, __val: None = ..., __tb: TracebackType | None = ...) -> _T_co: ...
-    @abstractmethod
-    async def aclose(self) -> None: ...
-    @abstractmethod
-    def __aiter__(self) -> AsyncGenerator[_T_co, _T_contra]: ...
+    def athrow(self, __typ: BaseException, __val: None = ..., __tb: TracebackType | None = ...) -> Awaitable[_T_co]: ...
+    def aclose(self) -> Awaitable[None]: ...
     @property
     def ag_await(self) -> Any: ...
     @property