Skip to content

Commit e93d3f2

Browse files
code-of-kppcode-of-kpp
authored
Merge branch 'main' into ctypes-p2p
2 parents 0eeea13 + b273837 commit e93d3f2

File tree

153 files changed

+1482
-768
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

153 files changed

+1482
-768
lines changed

‎.pre-commit-config.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ repos:
1010
types_or: [c, python, rst]
1111

1212
- repo: https://github.com/sphinx-contrib/sphinx-lint
13-
rev: v0.6.7
13+
rev: v0.6.8
1414
hooks:
1515
- id: sphinx-lint
1616
args: [--enable=default-role]

‎Doc/c-api/arg.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -555,7 +555,7 @@ Building values
555555
Same as ``s#``.
556556
557557
``u`` (:class:`str`) [const wchar_t \*]
558-
Convert a null-terminated :c:expr:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
558+
Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
559559
data to a Python Unicode object. If the Unicode buffer pointer is ``NULL``,
560560
``None`` is returned.
561561

‎Doc/c-api/buffer.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -225,7 +225,7 @@ object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical
225225
structure of the memory can vary drastically, the consumer uses the *flags*
226226
argument to specify the exact buffer type it can handle.
227227

228-
All :c:data:`Py_buffer` fields are unambiguously defined by the request
228+
All :c:type:`Py_buffer` fields are unambiguously defined by the request
229229
type.
230230

231231
request-independent fields
@@ -464,7 +464,7 @@ Buffer-related functions
464464
465465
.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *format)
466466
467-
Return the implied :c:data:`~Py_buffer.itemsize` from :c:data:`~Py_buffer.format`.
467+
Return the implied :c:member:`~Py_buffer.itemsize` from :c:member:`~Py_buffer.format`.
468468
On error, raise an exception and return -1.
469469
470470
.. versionadded:: 3.9

‎Doc/c-api/iterator.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Iterator Objects
66
----------------
77

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

‎Doc/c-api/mapping.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
1313
1414
Return ``1`` if the object provides the mapping protocol or supports slicing,
1515
and ``0`` otherwise. Note that it returns ``1`` for Python classes with
16-
a :meth:`__getitem__` method, since in general it is impossible to
16+
a :meth:`~object.__getitem__` method, since in general it is impossible to
1717
determine what type of keys the class supports. This function always succeeds.
1818
1919
@@ -90,7 +90,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
9090
This is equivalent to the Python expression ``key in o``.
9191
This function always succeeds.
9292
93-
Note that exceptions which occur while calling the :meth:`__getitem__`
93+
Note that exceptions which occur while calling the :meth:`~object.__getitem__`
9494
method will get suppressed.
9595
To get error reporting use :c:func:`PyObject_GetItem()` instead.
9696
@@ -101,7 +101,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
101101
This is equivalent to the Python expression ``key in o``.
102102
This function always succeeds.
103103
104-
Note that exceptions which occur while calling the :meth:`__getitem__`
104+
Note that exceptions which occur while calling the :meth:`~object.__getitem__`
105105
method and creating a temporary string object will get suppressed.
106106
To get error reporting use :c:func:`PyMapping_GetItemString()` instead.
107107

‎Doc/c-api/memory.rst

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

‎Doc/c-api/method.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ Instance Method Objects
77

88
.. index:: pair: object; instancemethod
99

10-
An instance method is a wrapper for a :c:data:`PyCFunction` and the new way
11-
to bind a :c:data:`PyCFunction` to a class object. It replaces the former call
10+
An instance method is a wrapper for a :c:type:`PyCFunction` and the new way
11+
to bind a :c:type:`PyCFunction` to a class object. It replaces the former call
1212
``PyMethod_New(func, NULL, class)``.
1313

1414

‎Doc/c-api/module.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ or request "multi-phase initialization" by returning the definition struct itsel
145145
146146
.. c:member:: PyModuleDef_Base m_base
147147
148-
Always initialize this member to :c:data:`PyModuleDef_HEAD_INIT`.
148+
Always initialize this member to :c:macro:`PyModuleDef_HEAD_INIT`.
149149
150150
.. c:member:: const char *m_name
151151

‎Doc/c-api/refcounting.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ of Python objects.
101101
.. warning::
102102
103103
The deallocation function can cause arbitrary Python code to be invoked (e.g.
104-
when a class instance with a :meth:`__del__` method is deallocated). While
104+
when a class instance with a :meth:`~object.__del__` method is deallocated). While
105105
exceptions in such code are not propagated, the executed code has free access to
106106
all Python global variables. This means that any object that is reachable from
107107
a global variable should be in a consistent state before :c:func:`Py_DECREF` is

‎Doc/c-api/sequence.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Sequence Protocol
99
.. c:function:: int PySequence_Check(PyObject *o)
1010
1111
Return ``1`` if the object provides the sequence protocol, and ``0`` otherwise.
12-
Note that it returns ``1`` for Python classes with a :meth:`__getitem__`
12+
Note that it returns ``1`` for Python classes with a :meth:`~object.__getitem__`
1313
method, unless they are :class:`dict` subclasses, since in general it
1414
is impossible to determine what type of keys the class supports. This
1515
function always succeeds.

‎Doc/c-api/type.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,7 @@ Type Objects
215215
``Py_TYPE(self)`` may be a *subclass* of the intended class, and subclasses
216216
are not necessarily defined in the same module as their superclass.
217217
See :c:type:`PyCMethod` to get the class that defines the method.
218-
See :c:func:`PyType_GetModuleByDef` for cases when ``PyCMethod`` cannot
218+
See :c:func:`PyType_GetModuleByDef` for cases when :c:type:`!PyCMethod` cannot
219219
be used.
220220
221221
.. versionadded:: 3.9

‎Doc/c-api/typeobj.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2255,8 +2255,8 @@ Number Object Structures
22552255

22562256
.. note::
22572257

2258-
The :c:data:`nb_reserved` field should always be ``NULL``. It
2259-
was previously called :c:data:`nb_long`, and was renamed in
2258+
The :c:member:`~PyNumberMethods.nb_reserved` field should always be ``NULL``. It
2259+
was previously called :c:member:`!nb_long`, and was renamed in
22602260
Python 3.0.1.
22612261

22622262
.. c:member:: binaryfunc PyNumberMethods.nb_add

‎Doc/c-api/unicode.rst

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ Python:
4444

4545
.. c:type:: Py_UNICODE
4646
47-
This is a typedef of :c:expr:`wchar_t`, which is a 16-bit type or 32-bit type
47+
This is a typedef of :c:type:`wchar_t`, which is a 16-bit type or 32-bit type
4848
depending on the platform.
4949

5050
.. versionchanged:: 3.3
@@ -437,11 +437,11 @@ APIs:
437437
+----------+-----------------------------------------------------+
438438
| ``ll`` | :c:expr:`long long` or :c:expr:`unsigned long long` |
439439
+----------+-----------------------------------------------------+
440-
| ``j`` | :c:expr:`intmax_t` or :c:expr:`uintmax_t` |
440+
| ``j`` | :c:type:`intmax_t` or :c:type:`uintmax_t` |
441441
+----------+-----------------------------------------------------+
442-
| ``z`` | :c:expr:`size_t` or :c:expr:`ssize_t` |
442+
| ``z`` | :c:type:`size_t` or :c:type:`ssize_t` |
443443
+----------+-----------------------------------------------------+
444-
| ``t`` | :c:expr:`ptrdiff_t` |
444+
| ``t`` | :c:type:`ptrdiff_t` |
445445
+----------+-----------------------------------------------------+
446446
447447
The length modifier ``l`` for following conversions ``s`` or ``V`` specify
@@ -520,7 +520,7 @@ APIs:
520520
521521
.. note::
522522
The width formatter unit is number of characters rather than bytes.
523-
The precision formatter unit is number of bytes or :c:expr:`wchar_t`
523+
The precision formatter unit is number of bytes or :c:type:`wchar_t`
524524
items (if the length modifier ``l`` is used) for ``"%s"`` and
525525
``"%V"`` (if the ``PyObject*`` argument is ``NULL``), and a number of
526526
characters for ``"%A"``, ``"%U"``, ``"%S"``, ``"%R"`` and ``"%V"``
@@ -839,21 +839,21 @@ conversion function:
839839
wchar_t Support
840840
"""""""""""""""
841841
842-
:c:expr:`wchar_t` support for platforms which support it:
842+
:c:type:`wchar_t` support for platforms which support it:
843843
844844
.. c:function:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
845845
846-
Create a Unicode object from the :c:expr:`wchar_t` buffer *w* of the given *size*.
846+
Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given *size*.
847847
Passing ``-1`` as the *size* indicates that the function must itself compute the length,
848848
using wcslen.
849849
Return ``NULL`` on failure.
850850
851851
852852
.. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size)
853853
854-
Copy the Unicode object contents into the :c:expr:`wchar_t` buffer *w*. At most
855-
*size* :c:expr:`wchar_t` characters are copied (excluding a possibly trailing
856-
null termination character). Return the number of :c:expr:`wchar_t` characters
854+
Copy the Unicode object contents into the :c:type:`wchar_t` buffer *w*. At most
855+
*size* :c:type:`wchar_t` characters are copied (excluding a possibly trailing
856+
null termination character). Return the number of :c:type:`wchar_t` characters
857857
copied or ``-1`` in case of an error. Note that the resulting :c:expr:`wchar_t*`
858858
string may or may not be null-terminated. It is the responsibility of the caller
859859
to make sure that the :c:expr:`wchar_t*` string is null-terminated in case this is
@@ -867,7 +867,7 @@ wchar_t Support
867867
Convert the Unicode object to a wide character string. The output string
868868
always ends with a null character. If *size* is not ``NULL``, write the number
869869
of wide characters (excluding the trailing null termination character) into
870-
*\*size*. Note that the resulting :c:expr:`wchar_t` string might contain
870+
*\*size*. Note that the resulting :c:type:`wchar_t` string might contain
871871
null characters, which would cause the string to be truncated when used with
872872
most C functions. If *size* is ``NULL`` and the :c:expr:`wchar_t*` string
873873
contains null characters a :exc:`ValueError` is raised.

‎Doc/c-api/veryhigh.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ parameter. The available start symbols are :c:data:`Py_eval_input`,
1717
following the functions which accept them as parameters.
1818

1919
Note also that several of these functions take :c:expr:`FILE*` parameters. One
20-
particular issue which needs to be handled carefully is that the :c:expr:`FILE`
20+
particular issue which needs to be handled carefully is that the :c:type:`FILE`
2121
structure for different C libraries can be different and incompatible. Under
2222
Windows (at least), it is possible for dynamically linked extensions to actually
2323
use different libraries, so care should be taken that :c:expr:`FILE*` parameters

‎Doc/conf.py

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,58 @@
7777
exclude_patterns.append(venvdir + '/*')
7878

7979
nitpick_ignore = [
80+
# Standard C types
81+
('c:type', 'FILE'),
82+
('c:type', '__int'),
83+
('c:type', 'intmax_t'),
84+
('c:type', 'off_t'),
85+
('c:type', 'ptrdiff_t'),
86+
('c:type', 'siginfo_t'),
87+
('c:type', 'size_t'),
88+
('c:type', 'ssize_t'),
89+
('c:type', 'time_t'),
90+
('c:type', 'uintmax_t'),
91+
('c:type', 'va_list'),
92+
('c:type', 'wchar_t'),
93+
# Standard C macros
94+
('c:macro', 'LLONG_MAX'),
95+
('c:macro', 'LLONG_MIN'),
96+
('c:macro', 'LONG_MAX'),
97+
('c:macro', 'LONG_MIN'),
98+
# Standard C variables
99+
('c:data', 'errno'),
100+
# Standard environment variables
101+
('envvar', 'BROWSER'),
102+
('envvar', 'COLUMNS'),
103+
('envvar', 'COMSPEC'),
104+
('envvar', 'DISPLAY'),
105+
('envvar', 'HOME'),
106+
('envvar', 'HOMEDRIVE'),
107+
('envvar', 'HOMEPATH'),
108+
('envvar', 'IDLESTARTUP'),
109+
('envvar', 'LANG'),
110+
('envvar', 'LANGUAGE'),
111+
('envvar', 'LC_ALL'),
112+
('envvar', 'LC_CTYPE'),
113+
('envvar', 'LC_COLLATE'),
114+
('envvar', 'LC_MESSAGES'),
115+
('envvar', 'LC_MONETARY'),
116+
('envvar', 'LC_NUMERIC'),
117+
('envvar', 'LC_TIME'),
118+
('envvar', 'LINES'),
119+
('envvar', 'LOGNAME'),
120+
('envvar', 'PAGER'),
121+
('envvar', 'PATH'),
122+
('envvar', 'PATHEXT'),
123+
('envvar', 'SOURCE_DATE_EPOCH'),
124+
('envvar', 'TEMP'),
125+
('envvar', 'TERM'),
126+
('envvar', 'TMP'),
127+
('envvar', 'TMPDIR'),
128+
('envvar', 'TZ'),
129+
('envvar', 'USER'),
130+
('envvar', 'USERNAME'),
131+
('envvar', 'USERPROFILE'),
80132
# Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot
81133
# be resolved, as the method is currently undocumented. For context, see
82134
# https://github.com/python/cpython/pull/103289.

‎Doc/extending/extending.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -237,10 +237,10 @@ Note that the Python name for the exception object is :exc:`spam.error`. The
237237
being :exc:`Exception` (unless another class is passed in instead of ``NULL``),
238238
described in :ref:`bltin-exceptions`.
239239

240-
Note also that the :c:data:`SpamError` variable retains a reference to the newly
240+
Note also that the :c:data:`!SpamError` variable retains a reference to the newly
241241
created exception class; this is intentional! Since the exception could be
242242
removed from the module by external code, an owned reference to the class is
243-
needed to ensure that it will not be discarded, causing :c:data:`SpamError` to
243+
needed to ensure that it will not be discarded, causing :c:data:`!SpamError` to
244244
become a dangling pointer. Should it become a dangling pointer, C code which
245245
raises the exception could cause a core dump or other unintended side effects.
246246

@@ -281,17 +281,17 @@ statement::
281281
It returns ``NULL`` (the error indicator for functions returning object pointers)
282282
if an error is detected in the argument list, relying on the exception set by
283283
:c:func:`PyArg_ParseTuple`. Otherwise the string value of the argument has been
284-
copied to the local variable :c:data:`command`. This is a pointer assignment and
284+
copied to the local variable :c:data:`!command`. This is a pointer assignment and
285285
you are not supposed to modify the string to which it points (so in Standard C,
286-
the variable :c:data:`command` should properly be declared as ``const char
286+
the variable :c:data:`!command` should properly be declared as ``const char
287287
*command``).
288288

289289
The next statement is a call to the Unix function :c:func:`system`, passing it
290290
the string we just got from :c:func:`PyArg_ParseTuple`::
291291

292292
sts = system(command);
293293

294-
Our :func:`spam.system` function must return the value of :c:data:`sts` as a
294+
Our :func:`!spam.system` function must return the value of :c:data:`!sts` as a
295295
Python object. This is done using the function :c:func:`PyLong_FromLong`. ::
296296

297297
return PyLong_FromLong(sts);

‎Doc/howto/argparse.rst

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -788,6 +788,59 @@ but not both at the same time:
788788
-q, --quiet
789789
790790
791+
How to translate the argparse output
792+
====================================
793+
794+
The output of the :mod:`argparse` module such as its help text and error
795+
messages are all made translatable using the :mod:`gettext` module. This
796+
allows applications to easily localize messages produced by
797+
:mod:`argparse`. See also :ref:`i18n-howto`.
798+
799+
For instance, in this :mod:`argparse` output:
800+
801+
.. code-block:: shell-session
802+
803+
$ python prog.py --help
804+
usage: prog.py [-h] [-v | -q] x y
805+
806+
calculate X to the power of Y
807+
808+
positional arguments:
809+
x the base
810+
y the exponent
811+
812+
options:
813+
-h, --help show this help message and exit
814+
-v, --verbose
815+
-q, --quiet
816+
817+
The strings ``usage:``, ``positional arguments:``, ``options:`` and
818+
``show this help message and exit`` are all translatable.
819+
820+
In order to translate these strings, they must first be extracted
821+
into a ``.po`` file. For example, using `Babel <https://babel.pocoo.org/>`__,
822+
run this command:
823+
824+
.. code-block:: shell-session
825+
826+
$ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py
827+
828+
This command will extract all translatable strings from the :mod:`argparse`
829+
module and output them into a file named ``messages.po``. This command assumes
830+
that your Python installation is in ``/usr/lib``.
831+
832+
You can find out the location of the :mod:`argparse` module on your system
833+
using this script::
834+
835+
import argparse
836+
print(argparse.__file__)
837+
838+
Once the messages in the ``.po`` file are translated and the translations are
839+
installed using :mod:`gettext`, :mod:`argparse` will be able to display the
840+
translated messages.
841+
842+
To translate your own strings in the :mod:`argparse` output, use :mod:`gettext`.
843+
791844
Conclusion
792845
==========
793846

‎Doc/howto/functional.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1072,8 +1072,8 @@ write the obvious :keyword:`for` loop::
10721072

10731073
A related function is :func:`itertools.accumulate(iterable, func=operator.add)
10741074
<itertools.accumulate>`. It performs the same calculation, but instead of
1075-
returning only the final result, :func:`accumulate` returns an iterator that
1076-
also yields each partial result::
1075+
returning only the final result, :func:`~itertools.accumulate` returns an iterator
1076+
that also yields each partial result::
10771077

10781078
itertools.accumulate([1, 2, 3, 4, 5]) =>
10791079
1, 3, 6, 10, 15

‎Doc/howto/isolating-extensions.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -483,14 +483,14 @@ to get the state::
483483
return NULL;
484484
}
485485

486-
``PyType_GetModuleByDef`` works by searching the
486+
:c:func:`!PyType_GetModuleByDef` works by searching the
487487
:term:`method resolution order` (i.e. all superclasses) for the first
488488
superclass that has a corresponding module.
489489

490490
.. note::
491491

492492
In very exotic cases (inheritance chains spanning multiple modules
493-
created from the same definition), ``PyType_GetModuleByDef`` might not
493+
created from the same definition), :c:func:`!PyType_GetModuleByDef` might not
494494
return the module of the true defining class. However, it will always
495495
return a module with the same definition, ensuring a compatible
496496
C memory layout.

0 commit comments

Comments
 (0)