GH-85979: Clarify specification of object.__await__ (GH-22320)

(cherry picked from commit f59c7f8)

Co-authored-by: Paolo Lammens <[email protected]>
Co-authored-by: Kumar Aditya <[email protected]>

Author: 3 people

Doc/reference/datamodel.rst

@@ -2879,6 +2879,14 @@ are awaitable.
    :term:`awaitable` objects.  For instance, :class:`asyncio.Future` implements
    this method to be compatible with the :keyword:`await` expression.
 
+   .. note::
+
+      The language doesn't place any restriction on the type or value of the
+      objects yielded by the iterator returned by ``__await__``, as this is
+      specific to the implementation of the asynchronous execution framework
+      (e.g. :mod:`asyncio`) that will be managing the :term:`awaitable` object.
+
+
 .. versionadded:: 3.5
 
 .. seealso:: :pep:`492` for additional information about awaitable objects.