gh-97696 Add documentation for get_coro() behavior with eager tasks

.github/CODEOWNERS

@@ -7,6 +7,9 @@
 # GitHub
 .github/**                    @ezio-melotti @hugovk
 
+# pre-commit
+.pre-commit-config.yaml       @hugovk @AlexWaygood
+
 # Build system
 configure*                    @erlend-aasland @corona10
 

.github/workflows/lint.yml

@@ -0,0 +1,22 @@
+name: Lint
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+      - uses: pre-commit/action@v3.0.0

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: check-yaml
+      - id: trailing-whitespace
+        types_or: [c, python, rst]

Doc/c-api/dict.rst

@@ -154,7 +154,7 @@ Dictionary Objects
 
 .. c:function:: Py_ssize_t PyDict_Size(PyObject *p)
 
-   .. index:: builtin: len
+   .. index:: pair: built-in function; len
 
    Return the number of items in the dictionary.  This is equivalent to
    ``len(p)`` on a dictionary.

Doc/c-api/import.rst

@@ -41,7 +41,7 @@ Importing Modules
 
 .. c:function:: PyObject* PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
 
-   .. index:: builtin: __import__
+   .. index:: pair: built-in function; __import__
 
    Import a module.  This is best described by referring to the built-in Python
    function :func:`__import__`.
@@ -120,7 +120,7 @@ Importing Modules
 
 .. c:function:: PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co)
 
-   .. index:: builtin: compile
+   .. index:: pair: built-in function; compile
 
    Given a module name (possibly of the form ``package.module``) and a code object
    read from a Python bytecode file or obtained from the built-in function

Doc/c-api/list.rst

@@ -45,7 +45,7 @@ List Objects
 
 .. c:function:: Py_ssize_t PyList_Size(PyObject *list)
 
-   .. index:: builtin: len
+   .. index:: pair: built-in function; len
 
    Return the length of the list object in *list*; this is equivalent to
    ``len(list)`` on a list object.
@@ -138,7 +138,7 @@ List Objects
 
 .. c:function:: PyObject* PyList_AsTuple(PyObject *list)
 
-   .. index:: builtin: tuple
+   .. index:: pair: built-in function; tuple
 
    Return a new tuple object containing the contents of *list*; equivalent to
    ``tuple(list)``.

Doc/c-api/mapping.rst

@@ -20,7 +20,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
 .. c:function:: Py_ssize_t PyMapping_Size(PyObject *o)
                Py_ssize_t PyMapping_Length(PyObject *o)
 
-   .. index:: builtin: len
+   .. index:: pair: built-in function; len
 
    Returns the number of keys in object *o* on success, and ``-1`` on failure.
    This is equivalent to the Python expression ``len(o)``.

Doc/c-api/number.rst

@@ -64,15 +64,15 @@ Number Protocol
 
 .. c:function:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)
 
-   .. index:: builtin: divmod
+   .. index:: pair: built-in function; divmod
 
    See the built-in function :func:`divmod`. Returns ``NULL`` on failure.  This is
    the equivalent of the Python expression ``divmod(o1, o2)``.
 
 
 .. c:function:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
 
-   .. index:: builtin: pow
+   .. index:: pair: built-in function; pow
 
    See the built-in function :func:`pow`. Returns ``NULL`` on failure.  This is the
    equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional.
@@ -94,7 +94,7 @@ Number Protocol
 
 .. c:function:: PyObject* PyNumber_Absolute(PyObject *o)
 
-   .. index:: builtin: abs
+   .. index:: pair: built-in function; abs
 
    Returns the absolute value of *o*, or ``NULL`` on failure.  This is the equivalent
    of the Python expression ``abs(o)``.
@@ -192,7 +192,7 @@ Number Protocol
 
 .. c:function:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
 
-   .. index:: builtin: pow
+   .. index:: pair: built-in function; pow
 
    See the built-in function :func:`pow`. Returns ``NULL`` on failure.  The operation
    is done *in-place* when *o1* supports it.  This is the equivalent of the Python
@@ -238,15 +238,15 @@ Number Protocol
 
 .. c:function:: PyObject* PyNumber_Long(PyObject *o)
 
-   .. index:: builtin: int
+   .. index:: pair: built-in function; int
 
    Returns the *o* converted to an integer object on success, or ``NULL`` on
    failure.  This is the equivalent of the Python expression ``int(o)``.
 
 
 .. c:function:: PyObject* PyNumber_Float(PyObject *o)
 
-   .. index:: builtin: float
+   .. index:: pair: built-in function; float
 
    Returns the *o* converted to a float object on success, or ``NULL`` on failure.
    This is the equivalent of the Python expression ``float(o)``.

Doc/c-api/object.rst

@@ -190,7 +190,7 @@ Object Protocol
 
 .. c:function:: PyObject* PyObject_Repr(PyObject *o)
 
-   .. index:: builtin: repr
+   .. index:: pair: built-in function; repr
 
    Compute a string representation of object *o*.  Returns the string
    representation on success, ``NULL`` on failure.  This is the equivalent of the
@@ -202,7 +202,7 @@ Object Protocol
 
 .. c:function:: PyObject* PyObject_ASCII(PyObject *o)
 
-   .. index:: builtin: ascii
+   .. index:: pair: built-in function; ascii
 
    As :c:func:`PyObject_Repr`, compute a string representation of object *o*, but
    escape the non-ASCII characters in the string returned by
@@ -227,7 +227,7 @@ Object Protocol
 
 .. c:function:: PyObject* PyObject_Bytes(PyObject *o)
 
-   .. index:: builtin: bytes
+   .. index:: pair: built-in function; bytes
 
    Compute a bytes representation of object *o*.  ``NULL`` is returned on
    failure and a bytes object on success.  This is equivalent to the Python
@@ -278,7 +278,7 @@ Object Protocol
 
 .. c:function:: Py_hash_t PyObject_Hash(PyObject *o)
 
-   .. index:: builtin: hash
+   .. index:: pair: built-in function; hash
 
    Compute and return the hash value of an object *o*.  On failure, return ``-1``.
    This is the equivalent of the Python expression ``hash(o)``.
@@ -312,7 +312,7 @@ Object Protocol
 
 .. c:function:: PyObject* PyObject_Type(PyObject *o)
 
-   .. index:: builtin: type
+   .. index:: pair: built-in function; type
 
    When *o* is non-``NULL``, returns a type object corresponding to the object type
    of object *o*. On failure, raises :exc:`SystemError` and returns ``NULL``.  This
@@ -332,7 +332,7 @@ Object Protocol
 .. c:function:: Py_ssize_t PyObject_Size(PyObject *o)
                Py_ssize_t PyObject_Length(PyObject *o)
 
-   .. index:: builtin: len
+   .. index:: pair: built-in function; len
 
    Return the length of object *o*.  If the object *o* provides either the sequence
    and mapping protocols, the sequence length is returned.  On error, ``-1`` is

Doc/c-api/sequence.rst

@@ -18,7 +18,7 @@ Sequence Protocol
 .. c:function:: Py_ssize_t PySequence_Size(PyObject *o)
                Py_ssize_t PySequence_Length(PyObject *o)
 
-   .. index:: builtin: len
+   .. index:: pair: built-in function; len
 
    Returns the number of objects in sequence *o* on success, and ``-1`` on
    failure.  This is equivalent to the Python expression ``len(o)``.
@@ -120,7 +120,7 @@ Sequence Protocol
 
 .. c:function:: PyObject* PySequence_Tuple(PyObject *o)
 
-   .. index:: builtin: tuple
+   .. index:: pair: built-in function; tuple
 
    Return a tuple object with the same contents as the sequence or iterable *o*,
    or ``NULL`` on failure.  If *o* is a tuple, a new reference will be returned,

Doc/c-api/set.rst

@@ -107,7 +107,7 @@ or :class:`frozenset` or instances of their subtypes.
 
 .. c:function:: Py_ssize_t PySet_Size(PyObject *anyset)
 
-   .. index:: builtin: len
+   .. index:: pair: built-in function; len
 
    Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
    ``len(anyset)``.  Raises a :exc:`PyExc_SystemError` if *anyset* is not a

Doc/c-api/structures.rst

@@ -347,7 +347,7 @@ method.
 
 .. data:: METH_CLASS
 
-   .. index:: builtin: classmethod
+   .. index:: pair: built-in function; classmethod
 
    The method will be passed the type object as the first parameter rather
    than an instance of the type.  This is used to create *class methods*,
@@ -357,7 +357,7 @@ method.
 
 .. data:: METH_STATIC
 
-   .. index:: builtin: staticmethod
+   .. index:: pair: built-in function; staticmethod
 
    The method will be passed ``NULL`` as the first parameter rather than an
    instance of the type.  This is used to create *static methods*, similar to

Doc/c-api/typeobj.rst

@@ -805,7 +805,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: reprfunc PyTypeObject.tp_repr
 
-   .. index:: builtin: repr
+   .. index:: pair: built-in function; repr
 
    An optional pointer to a function that implements the built-in function
    :func:`repr`.
@@ -870,7 +870,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: hashfunc PyTypeObject.tp_hash
 
-   .. index:: builtin: hash
+   .. index:: pair: built-in function; hash
 
    An optional pointer to a function that implements the built-in function
    :func:`hash`.

Doc/extending/newtypes.rst

@@ -149,7 +149,7 @@ done.  This can be done using the :c:func:`PyErr_Fetch` and
 
 .. index::
    single: string; object representation
-   builtin: repr
+   pair: built-in function; repr
 
 Object Presentation
 -------------------

Doc/howto/clinic.rst

@@ -1033,19 +1033,36 @@ you're not permitted to use:
 Using a return converter
 ------------------------
 
-By default the impl function Argument Clinic generates for you returns ``PyObject *``.
-But your C function often computes some C type, then converts it into the ``PyObject *``
+By default, the impl function Argument Clinic generates for you returns
+:c:type:`PyObject * <PyObject>`.
+But your C function often computes some C type,
+then converts it into the :c:type:`!PyObject *`
 at the last moment.  Argument Clinic handles converting your inputs from Python types
 into native C types—why not have it convert your return value from a native C type
 into a Python type too?
 
 That's what a "return converter" does.  It changes your impl function to return
 some C type, then adds code to the generated (non-impl) function to handle converting
-that value into the appropriate ``PyObject *``.
+that value into the appropriate :c:type:`!PyObject *`.
 
 The syntax for return converters is similar to that of parameter converters.
 You specify the return converter like it was a return annotation on the
-function itself.  Return converters behave much the same as parameter converters;
+function itself, using ``->`` notation.
+
+For example:
+
+.. code-block:: c
+
+   /*[clinic input]
+   add -> int
+
+       a: int
+       b: int
+       /
+
+   [clinic start generated code]*/
+
+Return converters behave much the same as parameter converters;
 they take arguments, the arguments are all keyword-only, and if you're not changing
 any of the default arguments you can omit the parentheses.
 
@@ -1066,19 +1083,17 @@ Currently Argument Clinic supports only a few return converters:
 .. code-block:: none
 
     bool
+    double
+    float
     int
-    unsigned int
     long
-    unsigned int
-    size_t
     Py_ssize_t
-    float
-    double
-    DecodeFSDefault
+    size_t
+    unsigned int
+    unsigned long
 
-None of these take parameters.  For the first three, return -1 to indicate
-error.  For ``DecodeFSDefault``, the return type is ``const char *``; return a ``NULL``
-pointer to indicate an error.
+None of these take parameters.
+For all of these, return ``-1`` to indicate error.
 
 To see all the return converters Argument Clinic supports, along with
 their parameters (if any),