Merge remote-tracking branch 'original/main'

Author: richardhob

Doc/c-api/exceptions.rst

@@ -222,17 +222,21 @@ For convenience, some of these functions will always return a
 
 .. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
 
-   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
-   filename is given as a C string.  *filename* is decoded from the filesystem
-   encoding (:func:`os.fsdecode`).
+   Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior
+   that if *filename* is not ``NULL``, it is decoded from the filesystem
+   encoding (:func:`os.fsdecode`) and passed to the constructor of
+   :exc:`OSError` as a third parameter to be used to define the
+   :attr:`!filename` attribute of the exception instance.
 
    .. availability:: Windows.
 
 
 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
 
-   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
-   additional parameter specifying the exception type to be raised.
+   Similar to :c:func:`PyErr_SetExcFromWindowsErr`, with the additional behavior
+   that if *filename* is not ``NULL``, it is passed to the constructor of
+   :exc:`OSError` as a third parameter to be used to define the
+   :attr:`!filename` attribute of the exception instance.
 
    .. availability:: Windows.
 

Doc/c-api/init_config.rst

@@ -82,6 +82,8 @@ PyWideStringList
    If *length* is non-zero, *items* must be non-``NULL`` and all strings must be
    non-``NULL``.
 
+   .. c:namespace:: NULL
+
    Methods:
 
    .. c:function:: PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)
@@ -101,6 +103,8 @@ PyWideStringList
 
       Python must be preinitialized to call this function.
 
+   .. c:namespace:: PyWideStringList
+
    Structure fields:
 
    .. c:member:: Py_ssize_t length

Doc/c-api/module.rst

@@ -338,6 +338,7 @@ The available slot types are:
    The *value* pointer of this slot must point to a function of the signature:
 
    .. c:function:: PyObject* create_module(PyObject *spec, PyModuleDef *def)
+      :noindex:
 
    The function receives a :py:class:`~importlib.machinery.ModuleSpec`
    instance, as defined in :PEP:`451`, and the module definition.
@@ -372,6 +373,7 @@ The available slot types are:
    The signature of the function is:
 
    .. c:function:: int exec_module(PyObject* module)
+      :noindex:
 
    If multiple ``Py_mod_exec`` slots are specified, they are processed in the
    order they appear in the *m_slots* array.
@@ -380,6 +382,8 @@ The available slot types are:
 
    Specifies one of the following values:
 
+   .. c:namespace:: NULL
+
    .. c:macro:: Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED
 
       The module does not support being imported in subinterpreters.

Doc/c-api/typeobj.rst

@@ -1403,7 +1403,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
        are allowed to be removed even if the instance is still alive).
 
    Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to
-   :c:func:`local_traverse` to have these specific names; don't name them just
+   :c:func:`!local_traverse` to have these specific names; don't name them just
    anything.
 
    Instances of :ref:`heap-allocated types <heap-types>` hold a reference to

Doc/c-api/unicode.rst

@@ -1292,7 +1292,7 @@ the user settings on the machine running the codec.
 
    Encode the Unicode object using the specified code page and return a Python
    bytes object.  Return ``NULL`` if an exception was raised by the codec. Use
-   :c:macro:`CP_ACP` code page to get the MBCS encoder.
+   :c:macro:`!CP_ACP` code page to get the MBCS encoder.
 
    .. versionadded:: 3.3
 

Doc/extending/newtypes.rst

@@ -298,7 +298,7 @@ have an associated doc string simply by providing the text in the table.  An
 application can use the introspection API to retrieve the descriptor from the
 class object, and get the doc string using its :attr:`__doc__` attribute.
 
-As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.name` value
+As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.ml_name` value
 of ``NULL`` is required.
 
 .. XXX Descriptors need to be explained in more detail somewhere, but not here.

Doc/extending/newtypes_tutorial.rst

@@ -45,7 +45,7 @@ extension module :mod:`!custom`:
    allows defining heap-allocated extension types using the
    :c:func:`PyType_FromSpec` function, which isn't covered in this tutorial.
 
-.. literalinclude:: ../includes/custom.c
+.. literalinclude:: ../includes/newtypes/custom.c
 
 Now that's quite a bit to take in at once, but hopefully bits will seem familiar
 from the previous chapter.  This file defines three things:
@@ -194,36 +194,32 @@ This adds the type to the module dictionary.  This allows us to create
    >>> mycustom = custom.Custom()
 
 That's it!  All that remains is to build it; put the above code in a file called
-:file:`custom.c` and:
+:file:`custom.c`,
+
+.. literalinclude:: ../includes/newtypes/pyproject.toml
+
+in a file called :file:`pyproject.toml`, and
 
 .. code-block:: python
 
-   from distutils.core import setup, Extension
-   setup(name="custom", version="1.0",
-         ext_modules=[Extension("custom", ["custom.c"])])
+   from setuptools import Extension, setup
+   setup(ext_modules=[Extension("custom", ["custom.c"])])
 
 in a file called :file:`setup.py`; then typing
 
 .. code-block:: shell-session
 
-   $ python setup.py build
+   $ python -m pip install .
 
-at a shell should produce a file :file:`custom.so` in a subdirectory; move to
-that directory and fire up Python --- you should be able to ``import custom`` and
-play around with Custom objects.
+in a shell should produce a file :file:`custom.so` in a subdirectory
+and install it; now fire up Python --- you should be able to ``import custom``
+and play around with ``Custom`` objects.
 
 That wasn't so hard, was it?
 
 Of course, the current Custom type is pretty uninteresting. It has no data and
 doesn't do anything. It can't even be subclassed.
 
-.. note::
-   While this documentation showcases the standard :mod:`!distutils` module
-   for building C extensions, it is recommended in real-world use cases to
-   use the newer and better-maintained ``setuptools`` library.  Documentation
-   on how to do this is out of scope for this document and can be found in
-   the `Python Packaging User's Guide <https://packaging.python.org/tutorials/distributing-packages/>`_.
-
 
 Adding data and methods to the Basic example
 ============================================
@@ -232,7 +228,7 @@ Let's extend the basic example to add some data and methods.  Let's also make
 the type usable as a base class. We'll create a new module, :mod:`!custom2` that
 adds these capabilities:
 
-.. literalinclude:: ../includes/custom2.c
+.. literalinclude:: ../includes/newtypes/custom2.c
 
 
 This version of the module has a number of changes.
@@ -514,17 +510,21 @@ We rename :c:func:`!PyInit_custom` to :c:func:`!PyInit_custom2`, update the
 module name in the :c:type:`PyModuleDef` struct, and update the full class
 name in the :c:type:`PyTypeObject` struct.
 
-Finally, we update our :file:`setup.py` file to build the new module:
+Finally, we update our :file:`setup.py` file to include the new module,
 
 .. code-block:: python
 
-   from distutils.core import setup, Extension
-   setup(name="custom", version="1.0",
-         ext_modules=[
-            Extension("custom", ["custom.c"]),
-            Extension("custom2", ["custom2.c"]),
-            ])
+   from setuptools import Extension, setup
+   setup(ext_modules=[
+       Extension("custom", ["custom.c"]),
+       Extension("custom2", ["custom2.c"]),
+   ])
+
+and then we re-install so that we can ``import custom2``:
+
+.. code-block:: shell-session
 
+   $ python -m pip install .
 
 Providing finer control over data attributes
 ============================================
@@ -535,7 +535,7 @@ version of our module, the instance variables :attr:`!first` and :attr:`!last`
 could be set to non-string values or even deleted. We want to make sure that
 these attributes always contain strings.
 
-.. literalinclude:: ../includes/custom3.c
+.. literalinclude:: ../includes/newtypes/custom3.c
 
 
 To provide greater control, over the :attr:`!first` and :attr:`!last` attributes,
@@ -682,7 +682,7 @@ To allow a :class:`!Custom` instance participating in a reference cycle to
 be properly detected and collected by the cyclic GC, our :class:`!Custom` type
 needs to fill two additional slots and to enable a flag that enables these slots:
 
-.. literalinclude:: ../includes/custom4.c
+.. literalinclude:: ../includes/newtypes/custom4.c
 
 
 First, the traversal method lets the cyclic GC know about subobjects that could
@@ -806,7 +806,7 @@ increases an internal counter:
    >>> print(s.increment())
    2
 
-.. literalinclude:: ../includes/sublist.c
+.. literalinclude:: ../includes/newtypes/sublist.c
 
 
 As you can see, the source code closely resembles the :class:`!Custom` examples in