Merge branch 'main' into superfix

* main: (73 commits)
  Thoroughly refactor the cases generator (python#107151)
  Docs: Add missing markup to Argument Clinic docs (python#106876)
  pythongh-107162: Document errcode.h usage in its comment (python#107177)
  pythongh-106320: Remove private _PyDict C API (python#107145)
  Fix PyVectorcall_Function doc versionadded (python#107140)
  Docs: Remove duplicate word in Argument Clinic howto heading (python#107169)
  pythongh-107017: Change Chapter Strings to Texts in the Introduction chapter. (python#107104)
  pythongh-106320: Remove private _PyObject C API (python#107159)
  Docs: fix typo in os.pwrite docstring (python#107087)
  pythongh-105291: Add link to migration guide for distutils (python#107130)
  pythongh-106948: Docs: Disable links for C standard library functions, OS utility functions and system calls (python#107062)
  pythongh-106320: Remove _PyBytes_Join() C API (python#107144)
  pythongh-106320: Remove private _PyObject C API (python#107147)
  pythongh-106320: Remove _PyTuple_MaybeUntrack() C API (python#107143)
  pythongh-106320: Remove _PyIsSelectable_fd() C API (python#107142)
  Remove superflous whitespaces in `layout.html`. (pythonGH-107067)
  pythongh-107122: Update what's news for dbm.*dbm.clear() method (pythongh-107135)
  pythongh-107122: Add clear method to dbm.ndbm module (pythongh-107126)
  pythongh-62519: Make pgettext search plurals when translation is not found (python#107118)
  pythongh-107122: Add clear method to dbm.gdbm.module (pythongh-107127)
  ...

Author: carljm

.github/workflows/reusable-docs.yml

@@ -28,35 +28,28 @@ jobs:
         cache-dependency-path: 'Doc/requirements.txt'
     - name: 'Install build dependencies'
       run: make -C Doc/ venv
-    - name: 'Build HTML documentation'
-      run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
 
-    # Add pull request annotations for Sphinx nitpicks (missing references)
+    # To annotate PRs with Sphinx nitpicks (missing references)
     - name: 'Get list of changed files'
       if: github.event_name == 'pull_request'
       id: changed_files
       uses: Ana06/[email protected]
       with:
         filter: "Doc/**"
         format: csv  # works for paths with spaces
-    - name: 'Build changed files in nit-picky mode'
-      if: github.event_name == 'pull_request'
+    - name: 'Build HTML documentation'
       continue-on-error: true
       run: |
         set -Eeuo pipefail
-        # Mark files the pull request modified
-        python Doc/tools/touch-clean-files.py --clean '${{ steps.changed_files.outputs.added_modified }}'
-        # Build docs with the '-n' (nit-picky) option; convert warnings to annotations
-        make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n --keep-going" html 2>&1 |
-            python Doc/tools/warnings-to-gh-actions.py
-
-    # Ensure some files always pass Sphinx nit-picky mode (no missing references)
-    - name: 'Build known-good files in nit-picky mode'
+        # Build docs with the '-n' (nit-picky) option; write warnings to file
+        make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going -w sphinx-warnings.txt" html
+    - name: 'Check warnings'
+      if: github.event_name == 'pull_request'
       run: |
-        # Mark files that must pass nit-picky
-        python Doc/tools/touch-clean-files.py
-        # Build docs with the '-n' (nit-picky) option, convert warnings to errors (-W)
-        make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going" html 2>&1
+        python Doc/tools/check-warnings.py \
+          --check-and-annotate '${{ steps.changed_files.outputs.added_modified }}' \
+          --fail-if-regression \
+          --fail-if-improved
 
   # This build doesn't use problem matchers or check annotations
   build_doc_oldest_supported_sphinx:

.pre-commit-config.yaml

@@ -10,7 +10,7 @@ repos:
         types_or: [c, python, rst]
 
   - repo: https://github.com/sphinx-contrib/sphinx-lint
-    rev: v0.6.7
+    rev: v0.6.8
     hooks:
       - id: sphinx-lint
         args: [--enable=default-role]

Doc/c-api/arg.rst

@@ -555,7 +555,7 @@ Building values
       Same as ``s#``.
 
    ``u`` (:class:`str`) [const wchar_t \*]
-      Convert a null-terminated :c:expr:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
+      Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
       data to a Python Unicode object.  If the Unicode buffer pointer is ``NULL``,
       ``None`` is returned.
 

Doc/c-api/buffer.rst

@@ -225,7 +225,7 @@ object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical
 structure of the memory can vary drastically, the consumer uses the *flags*
 argument to specify the exact buffer type it can handle.
 
-All :c:data:`Py_buffer` fields are unambiguously defined by the request
+All :c:type:`Py_buffer` fields are unambiguously defined by the request
 type.
 
 request-independent fields
@@ -464,7 +464,7 @@ Buffer-related functions
 
 .. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *format)
 
-   Return the implied :c:data:`~Py_buffer.itemsize` from :c:data:`~Py_buffer.format`.
+   Return the implied :c:member:`~Py_buffer.itemsize` from :c:member:`~Py_buffer.format`.
    On error, raise an exception and return -1.
 
    .. versionadded:: 3.9

Doc/c-api/call.rst

@@ -152,7 +152,7 @@ Vectorcall Support API
    This is mostly useful to check whether or not *op* supports vectorcall,
    which can be done by checking ``PyVectorcall_Function(op) != NULL``.
 
-   .. versionadded:: 3.8
+   .. versionadded:: 3.9
 
 .. c:function:: PyObject* PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)
 

Doc/c-api/exceptions.rst

@@ -163,7 +163,7 @@ For convenience, some of these functions will always return a
    This is a convenience function to raise an exception when a C library function
    has returned an error and set the C variable :c:data:`errno`.  It constructs a
    tuple object whose first item is the integer :c:data:`errno` value and whose
-   second item is the corresponding error message (gotten from :c:func:`strerror`),
+   second item is the corresponding error message (gotten from :c:func:`!strerror`),
    and then calls ``PyErr_SetObject(type, object)``.  On Unix, when the
    :c:data:`errno` value is :c:macro:`EINTR`, indicating an interrupted system call,
    this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,

Doc/c-api/iterator.rst

@@ -6,7 +6,7 @@ Iterator Objects
 ----------------
 
 Python provides two general-purpose iterator objects.  The first, a sequence
-iterator, works with an arbitrary sequence supporting the :meth:`__getitem__`
+iterator, works with an arbitrary sequence supporting the :meth:`~object.__getitem__`
 method.  The second works with a callable object and a sentinel value, calling
 the callable for each item in the sequence, and ending the iteration when the
 sentinel value is returned.

Doc/c-api/mapping.rst

@@ -13,7 +13,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
 
    Return ``1`` if the object provides the mapping protocol or supports slicing,
    and ``0`` otherwise.  Note that it returns ``1`` for Python classes with
-   a :meth:`__getitem__` method, since in general it is impossible to
+   a :meth:`~object.__getitem__` method, since in general it is impossible to
    determine what type of keys the class supports. This function always succeeds.
 
 
@@ -90,7 +90,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
    This is equivalent to the Python expression ``key in o``.
    This function always succeeds.
 
-   Note that exceptions which occur while calling the :meth:`__getitem__`
+   Note that exceptions which occur while calling the :meth:`~object.__getitem__`
    method will get suppressed.
    To get error reporting use :c:func:`PyObject_GetItem()` instead.
 
@@ -101,7 +101,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
    This is equivalent to the Python expression ``key in o``.
    This function always succeeds.
 
-   Note that exceptions which occur while calling the :meth:`__getitem__`
+   Note that exceptions which occur while calling the :meth:`~object.__getitem__`
    method and creating a temporary string object will get suppressed.
    To get error reporting use :c:func:`PyMapping_GetItemString()` instead.
 

Doc/c-api/memory.rst

@@ -581,7 +581,7 @@ that the treatment of negative indices differs from a Python slice):
     default).
 
     A serial number, incremented by 1 on each call to a malloc-like or
-    realloc-like function.  Big-endian ``size_t``.  If "bad memory" is detected
+    realloc-like function.  Big-endian :c:type:`size_t`.  If "bad memory" is detected
     later, the serial number gives an excellent way to set a breakpoint on the
     next run, to capture the instant at which this block was passed out.  The
     static function bumpserialno() in obmalloc.c is the only place the serial

Doc/c-api/method.rst

@@ -7,8 +7,8 @@ Instance Method Objects
 
 .. index:: pair: object; instancemethod
 
-An instance method is a wrapper for a :c:data:`PyCFunction` and the new way
-to bind a :c:data:`PyCFunction` to a class object. It replaces the former call
+An instance method is a wrapper for a :c:type:`PyCFunction` and the new way
+to bind a :c:type:`PyCFunction` to a class object. It replaces the former call
 ``PyMethod_New(func, NULL, class)``.
 
 

Doc/c-api/module.rst

@@ -145,7 +145,7 @@ or request "multi-phase initialization" by returning the definition struct itsel
 
    .. c:member:: PyModuleDef_Base m_base
 
-      Always initialize this member to :c:data:`PyModuleDef_HEAD_INIT`.
+      Always initialize this member to :c:macro:`PyModuleDef_HEAD_INIT`.
 
    .. c:member:: const char *m_name
 

Doc/c-api/refcounting.rst

@@ -101,7 +101,7 @@ of Python objects.
    .. warning::
 
       The deallocation function can cause arbitrary Python code to be invoked (e.g.
-      when a class instance with a :meth:`__del__` method is deallocated).  While
+      when a class instance with a :meth:`~object.__del__` method is deallocated).  While
       exceptions in such code are not propagated, the executed code has free access to
       all Python global variables.  This means that any object that is reachable from
       a global variable should be in a consistent state before :c:func:`Py_DECREF` is

Doc/c-api/sequence.rst

@@ -9,7 +9,7 @@ Sequence Protocol
 .. c:function:: int PySequence_Check(PyObject *o)
 
    Return ``1`` if the object provides the sequence protocol, and ``0`` otherwise.
-   Note that it returns ``1`` for Python classes with a :meth:`__getitem__`
+   Note that it returns ``1`` for Python classes with a :meth:`~object.__getitem__`
    method, unless they are :class:`dict` subclasses, since in general it
    is impossible to determine what type of keys the class supports.  This
    function always succeeds.

Doc/c-api/sys.rst

@@ -106,15 +106,15 @@ Operating System Utilities
 .. c:function:: PyOS_sighandler_t PyOS_getsig(int i)
 
    Return the current signal handler for signal *i*.  This is a thin wrapper around
-   either :c:func:`sigaction` or :c:func:`signal`.  Do not call those functions
+   either :c:func:`!sigaction` or :c:func:`!signal`.  Do not call those functions
    directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:expr:`void
    (\*)(int)`.
 
 
 .. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
 
    Set the signal handler for signal *i* to be *h*; return the old signal handler.
-   This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`.  Do
+   This is a thin wrapper around either :c:func:`!sigaction` or :c:func:`!signal`.  Do
    not call those functions directly!  :c:type:`PyOS_sighandler_t` is a typedef
    alias for :c:expr:`void (\*)(int)`.
 

Doc/c-api/type.rst

@@ -215,7 +215,7 @@ Type Objects
    ``Py_TYPE(self)`` may be a *subclass* of the intended class, and subclasses
    are not necessarily defined in the same module as their superclass.
    See :c:type:`PyCMethod` to get the class that defines the method.
-   See :c:func:`PyType_GetModuleByDef` for cases when ``PyCMethod`` cannot
+   See :c:func:`PyType_GetModuleByDef` for cases when :c:type:`!PyCMethod` cannot
    be used.
 
    .. versionadded:: 3.9

Doc/c-api/typeobj.rst

@@ -2255,8 +2255,8 @@ Number Object Structures
 
    .. note::
 
-      The :c:data:`nb_reserved` field should always be ``NULL``.  It
-      was previously called :c:data:`nb_long`, and was renamed in
+      The :c:member:`~PyNumberMethods.nb_reserved` field should always be ``NULL``.  It
+      was previously called :c:member:`!nb_long`, and was renamed in
       Python 3.0.1.
 
 .. c:member:: binaryfunc PyNumberMethods.nb_add

Doc/c-api/unicode.rst

@@ -44,7 +44,7 @@ Python:
 
 .. c:type:: Py_UNICODE
 
-   This is a typedef of :c:expr:`wchar_t`, which is a 16-bit type or 32-bit type
+   This is a typedef of :c:type:`wchar_t`, which is a 16-bit type or 32-bit type
    depending on the platform.
 
    .. versionchanged:: 3.3
@@ -437,11 +437,11 @@ APIs:
    +----------+-----------------------------------------------------+
    | ``ll``   | :c:expr:`long long` or :c:expr:`unsigned long long` |
    +----------+-----------------------------------------------------+
-   | ``j``    | :c:expr:`intmax_t` or :c:expr:`uintmax_t`           |
+   | ``j``    | :c:type:`intmax_t` or :c:type:`uintmax_t`           |
    +----------+-----------------------------------------------------+
-   | ``z``    | :c:expr:`size_t` or :c:expr:`ssize_t`               |
+   | ``z``    | :c:type:`size_t` or :c:type:`ssize_t`               |
    +----------+-----------------------------------------------------+
-   | ``t``    | :c:expr:`ptrdiff_t`                                 |
+   | ``t``    | :c:type:`ptrdiff_t`                                 |
    +----------+-----------------------------------------------------+
 
    The length modifier ``l`` for following conversions ``s`` or ``V`` specify
@@ -520,7 +520,7 @@ APIs:
 
    .. note::
       The width formatter unit is number of characters rather than bytes.
-      The precision formatter unit is number of bytes or :c:expr:`wchar_t`
+      The precision formatter unit is number of bytes or :c:type:`wchar_t`
       items (if the length modifier ``l`` is used) for ``"%s"`` and
       ``"%V"`` (if the ``PyObject*`` argument is ``NULL``), and a number of
       characters for ``"%A"``, ``"%U"``, ``"%S"``, ``"%R"`` and ``"%V"``
@@ -839,21 +839,21 @@ conversion function:
 wchar_t Support
 """""""""""""""
 
-:c:expr:`wchar_t` support for platforms which support it:
+:c:type:`wchar_t` support for platforms which support it:
 
 .. c:function:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
 
-   Create a Unicode object from the :c:expr:`wchar_t` buffer *w* of the given *size*.
+   Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given *size*.
    Passing ``-1`` as the *size* indicates that the function must itself compute the length,
    using wcslen.
    Return ``NULL`` on failure.
 
 
 .. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size)
 
-   Copy the Unicode object contents into the :c:expr:`wchar_t` buffer *w*.  At most
-   *size* :c:expr:`wchar_t` characters are copied (excluding a possibly trailing
-   null termination character).  Return the number of :c:expr:`wchar_t` characters
+   Copy the Unicode object contents into the :c:type:`wchar_t` buffer *w*.  At most
+   *size* :c:type:`wchar_t` characters are copied (excluding a possibly trailing
+   null termination character).  Return the number of :c:type:`wchar_t` characters
    copied or ``-1`` in case of an error.  Note that the resulting :c:expr:`wchar_t*`
    string may or may not be null-terminated.  It is the responsibility of the caller
    to make sure that the :c:expr:`wchar_t*` string is null-terminated in case this is
@@ -867,7 +867,7 @@ wchar_t Support
    Convert the Unicode object to a wide character string. The output string
    always ends with a null character. If *size* is not ``NULL``, write the number
    of wide characters (excluding the trailing null termination character) into
-   *\*size*. Note that the resulting :c:expr:`wchar_t` string might contain
+   *\*size*. Note that the resulting :c:type:`wchar_t` string might contain
    null characters, which would cause the string to be truncated when used with
    most C functions. If *size* is ``NULL`` and the :c:expr:`wchar_t*` string
    contains null characters a :exc:`ValueError` is raised.

Doc/c-api/veryhigh.rst

@@ -17,7 +17,7 @@ parameter.  The available start symbols are :c:data:`Py_eval_input`,
 following the functions which accept them as parameters.
 
 Note also that several of these functions take :c:expr:`FILE*` parameters.  One
-particular issue which needs to be handled carefully is that the :c:expr:`FILE`
+particular issue which needs to be handled carefully is that the :c:type:`FILE`
 structure for different C libraries can be different and incompatible.  Under
 Windows (at least), it is possible for dynamically linked extensions to actually
 use different libraries, so care should be taken that :c:expr:`FILE*` parameters

Doc/conf.py

@@ -77,6 +77,76 @@
     exclude_patterns.append(venvdir + '/*')
 
 nitpick_ignore = [
+    # Standard C functions
+    ('c:func', 'calloc'),
+    ('c:func', 'dlopen'),
+    ('c:func', 'exec'),
+    ('c:func', 'fcntl'),
+    ('c:func', 'fork'),
+    ('c:func', 'free'),
+    ('c:func', 'gmtime'),
+    ('c:func', 'localtime'),
+    ('c:func', 'main'),
+    ('c:func', 'malloc'),
+    ('c:func', 'printf'),
+    ('c:func', 'realloc'),
+    ('c:func', 'snprintf'),
+    ('c:func', 'sprintf'),
+    ('c:func', 'stat'),
+    ('c:func', 'system'),
+    ('c:func', 'vsnprintf'),
+    # Standard C types
+    ('c:type', 'FILE'),
+    ('c:type', '__int'),
+    ('c:type', 'intmax_t'),
+    ('c:type', 'off_t'),
+    ('c:type', 'ptrdiff_t'),
+    ('c:type', 'siginfo_t'),
+    ('c:type', 'size_t'),
+    ('c:type', 'ssize_t'),
+    ('c:type', 'time_t'),
+    ('c:type', 'uintmax_t'),
+    ('c:type', 'va_list'),
+    ('c:type', 'wchar_t'),
+    # Standard C macros
+    ('c:macro', 'LLONG_MAX'),
+    ('c:macro', 'LLONG_MIN'),
+    ('c:macro', 'LONG_MAX'),
+    ('c:macro', 'LONG_MIN'),
+    # Standard C variables
+    ('c:data', 'errno'),
+    # Standard environment variables
+    ('envvar', 'BROWSER'),
+    ('envvar', 'COLUMNS'),
+    ('envvar', 'COMSPEC'),
+    ('envvar', 'DISPLAY'),
+    ('envvar', 'HOME'),
+    ('envvar', 'HOMEDRIVE'),
+    ('envvar', 'HOMEPATH'),
+    ('envvar', 'IDLESTARTUP'),
+    ('envvar', 'LANG'),
+    ('envvar', 'LANGUAGE'),
+    ('envvar', 'LC_ALL'),
+    ('envvar', 'LC_CTYPE'),
+    ('envvar', 'LC_COLLATE'),
+    ('envvar', 'LC_MESSAGES'),
+    ('envvar', 'LC_MONETARY'),
+    ('envvar', 'LC_NUMERIC'),
+    ('envvar', 'LC_TIME'),
+    ('envvar', 'LINES'),
+    ('envvar', 'LOGNAME'),
+    ('envvar', 'PAGER'),
+    ('envvar', 'PATH'),
+    ('envvar', 'PATHEXT'),
+    ('envvar', 'SOURCE_DATE_EPOCH'),
+    ('envvar', 'TEMP'),
+    ('envvar', 'TERM'),
+    ('envvar', 'TMP'),
+    ('envvar', 'TMPDIR'),
+    ('envvar', 'TZ'),
+    ('envvar', 'USER'),
+    ('envvar', 'USERNAME'),
+    ('envvar', 'USERPROFILE'),
     # Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot
     # be resolved, as the method is currently undocumented. For context, see
     # https://github.com/python/cpython/pull/103289.