Merge branch 'main' into ctypes-p2p

Author: code-of-kpp

.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/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/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,58 @@
     exclude_patterns.append(venvdir + '/*')
 
 nitpick_ignore = [
+    # 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.

Doc/extending/extending.rst

@@ -237,10 +237,10 @@ Note that the Python name for the exception object is :exc:`spam.error`.  The
 being :exc:`Exception` (unless another class is passed in instead of ``NULL``),
 described in :ref:`bltin-exceptions`.
 
-Note also that the :c:data:`SpamError` variable retains a reference to the newly
+Note also that the :c:data:`!SpamError` variable retains a reference to the newly
 created exception class; this is intentional!  Since the exception could be
 removed from the module by external code, an owned reference to the class is
-needed to ensure that it will not be discarded, causing :c:data:`SpamError` to
+needed to ensure that it will not be discarded, causing :c:data:`!SpamError` to
 become a dangling pointer. Should it become a dangling pointer, C code which
 raises the exception could cause a core dump or other unintended side effects.
 
@@ -281,17 +281,17 @@ statement::
 It returns ``NULL`` (the error indicator for functions returning object pointers)
 if an error is detected in the argument list, relying on the exception set by
 :c:func:`PyArg_ParseTuple`.  Otherwise the string value of the argument has been
-copied to the local variable :c:data:`command`.  This is a pointer assignment and
+copied to the local variable :c:data:`!command`.  This is a pointer assignment and
 you are not supposed to modify the string to which it points (so in Standard C,
-the variable :c:data:`command` should properly be declared as ``const char
+the variable :c:data:`!command` should properly be declared as ``const char
 *command``).
 
 The next statement is a call to the Unix function :c:func:`system`, passing it
 the string we just got from :c:func:`PyArg_ParseTuple`::
 
    sts = system(command);
 
-Our :func:`spam.system` function must return the value of :c:data:`sts` as a
+Our :func:`!spam.system` function must return the value of :c:data:`!sts` as a
 Python object.  This is done using the function :c:func:`PyLong_FromLong`. ::
 
    return PyLong_FromLong(sts);

Doc/howto/argparse.rst

@@ -788,6 +788,59 @@ but not both at the same time:
      -q, --quiet
 
 
+How to translate the argparse output
+====================================
+
+The output of the :mod:`argparse` module such as its help text and error
+messages are all made translatable using the :mod:`gettext` module. This
+allows applications to easily localize messages produced by
+:mod:`argparse`. See also :ref:`i18n-howto`.
+
+For instance, in this :mod:`argparse` output:
+
+.. code-block:: shell-session
+
+   $ python prog.py --help
+   usage: prog.py [-h] [-v | -q] x y
+
+   calculate X to the power of Y
+
+   positional arguments:
+     x              the base
+     y              the exponent
+
+   options:
+     -h, --help     show this help message and exit
+     -v, --verbose
+     -q, --quiet
+
+The strings ``usage:``, ``positional arguments:``, ``options:`` and
+``show this help message and exit`` are all translatable.
+
+In order to translate these strings, they must first be extracted
+into a ``.po`` file. For example, using `Babel <https://babel.pocoo.org/>`__,
+run this command:
+
+.. code-block:: shell-session
+
+  $ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py
+
+This command will extract all translatable strings from the :mod:`argparse`
+module and output them into a file named ``messages.po``. This command assumes
+that your Python installation is in ``/usr/lib``.
+
+You can find out the location of the :mod:`argparse` module on your system
+using this script::
+
+   import argparse
+   print(argparse.__file__)
+
+Once the messages in the ``.po`` file are translated and the translations are
+installed using :mod:`gettext`, :mod:`argparse` will be able to display the
+translated messages.
+
+To translate your own strings in the :mod:`argparse` output, use :mod:`gettext`.
+
 Conclusion
 ==========
 

Doc/howto/functional.rst

@@ -1072,8 +1072,8 @@ write the obvious :keyword:`for` loop::
 
 A related function is :func:`itertools.accumulate(iterable, func=operator.add)
 <itertools.accumulate>`.  It performs the same calculation, but instead of
-returning only the final result, :func:`accumulate` returns an iterator that
-also yields each partial result::
+returning only the final result, :func:`~itertools.accumulate` returns an iterator
+that also yields each partial result::
 
     itertools.accumulate([1, 2, 3, 4, 5]) =>
       1, 3, 6, 10, 15

Doc/howto/isolating-extensions.rst

@@ -483,14 +483,14 @@ to get the state::
         return NULL;
     }
 
-``PyType_GetModuleByDef`` works by searching the
+:c:func:`!PyType_GetModuleByDef` works by searching the
 :term:`method resolution order` (i.e. all superclasses) for the first
 superclass that has a corresponding module.
 
 .. note::
 
    In very exotic cases (inheritance chains spanning multiple modules
-   created from the same definition), ``PyType_GetModuleByDef`` might not
+   created from the same definition), :c:func:`!PyType_GetModuleByDef` might not
    return the module of the true defining class. However, it will always
    return a module with the same definition, ensuring a compatible
    C memory layout.