Merge branch 'main' into pythongh-103247

.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

.github/workflows/require-pr-label.yml

@@ -4,6 +4,10 @@ on:
  pull_request:
  types: [opened, reopened, labeled, unlabeled, synchronize]
 
+permissions:
+ issues: read
+ pull-requests: read
+
 jobs:
  label:
  name: DO-NOT-MERGE / unresolved review

.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),