8000 Merge branch 'main' into gh-63882-doc_strings · srinivasreddy/cpython@298a20f · GitHub
[go: up one dir, main page]
Skip to content

Commit 298a20f

Browse files
srinivasreddysrinivasreddy
committed
Merge branch 'main' into pythongh-63882-doc_strings
2 parents 49a12e6 + 313b96e commit 298a20f

File tree

312 files changed

+8989
-3665
lines changed

Some content is hidden

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

312 files changed

+8989
-3665
lines changed

‎.github/CODEOWNERS

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -96,13 +96,14 @@ Doc/library/site.rst @FFY00
9696
Lib/test/test_except*.py @iritkatriel
9797
Objects/exceptions.c @iritkatriel
9898

99-
# Hashing
100-
**/*hashlib* @gpshead @tiran
99+
# Hashing & cryptographic primitives
100+
**/*hashlib* @gpshead @tiran @picnixz
101101
**/*pyhash* @gpshead @tiran
102-
**/sha* @gpshead @tiran
103-
Modules/md5* @gpshead @tiran
104-
**/*blake* @gpshead @tiran
102+
**/sha* @gpshead @tiran @picnixz
103+
Modules/md5* @gpshead @tiran @picnixz
104+
**/*blake* @gpshead @tiran @picnixz
105105
Modules/_hacl/** @gpshead
106+
**/*hmac* @gpshead @picnixz
106107

107108
# logging
108109
**/*logging* @vsajip

‎.github/workflows/reusable-change-detection.yml

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,22 @@ jobs:
8383
# into the PR branch anyway.
8484
#
8585
# https://github.com/python/core-workflow/issues/373
86-
git diff --name-only "origin/$GITHUB_BASE_REF.." | grep -qvE '(\.rst$|^Doc|^Misc|^\.pre-commit-config\.yaml$|\.ruff\.toml$|\.md$|mypy\.ini$)' && echo "run-tests=true" >> "$GITHUB_OUTPUT" || true
86+
grep_ignore_args=(
87+
# file extensions
88+
-e '\.md$'
89+
-e '\.rst$'
90+
# top-level folders
91+
-e '^Doc/'
92+
-e '^Misc/'
93+
# configuration files
94+
-e '^\.github/CODEOWNERS$'
95+
-e '^\.pre-commit-config\.yaml$'
96+
-e '\.ruff\.toml$'
97+
-e 'mypy\.ini$'
98+
)
99+
git diff --name-only "origin/$GITHUB_BASE_REF.." \
100+
| grep -qvE "${grep_ignore_args[@]}" \
101+
&& echo "run-tests=true" >> "$GITHUB_OUTPUT" || true
87102
fi
88103
89104
# Check if we should run hypothesis tests

‎Doc/c-api/apiabiversion.rst

Lines changed: 76 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,13 @@
66
API and ABI Versioning
77
***********************
88

9+
10+
Build-time version constants
11+
----------------------------
12+
913
CPython exposes its version number in the following macros.
10-
Note that these correspond to the version code is **built** with,
11-
not necessarily the version used at **run time**.
14+
Note that these correspond to the version code is **built** with.
15+
See :c:var:`Py_Version` for the version used at **run time**.
1216

1317
See :ref:`stable` for a discussion of API and ABI stability across versions.
1418

@@ -37,37 +41,83 @@ See :ref:`stable` for a discussion of API and ABI stability across versions.
3741
.. c:macro:: PY_VERSION_HEX
3842
3943
The Python version number encoded in a single integer.
44+
See :c:func:`Py_PACK_FULL_VERSION` for the encoding details.
4045

41-
The underlying version information can be found by treating it as a 32 bit
42-
number in the following manner:
43-
44-
+-------+-------------------------+-------------------------+--------------------------+
45-
| Bytes | Bits (big endian order) | Meaning | Value for ``3.4.1a2`` |
46-
+=======+=========================+=========================+==========================+
47-
| 1 | 1-8 | ``PY_MAJOR_VERSION`` | ``0x03`` |
48-
+-------+-------------------------+-------------------------+--------------------------+
49-
| 2 | 9-16 | ``PY_MINOR_VERSION`` | ``0x04`` |
50-
+-------+-------------------------+-------------------------+--------------------------+
51-
| 3 | 17-24 | ``PY_MICRO_VERSION`` | ``0x01`` |
52-
+-------+-------------------------+-------------------------+--------------------------+
53-
| 4 | 25-28 | ``PY_RELEASE_LEVEL`` | ``0xA`` |
54-
+ +-------------------------+-------------------------+--------------------------+
55-
| | 29-32 | ``PY_RELEASE_SERIAL`` | ``0x2`` |
56-
+-------+-------------------------+-------------------------+--------------------------+
46+
Use this for numeric comparisons, for example,
47+
``#if PY_VERSION_HEX >= ...``.
5748

58-
Thus ``3.4.1a2`` is hexversion ``0x030401a2`` and ``3.10.0`` is
59-
hexversion ``0x030a00f0``.
6049

61-
Use this for numeric comparisons, e.g. ``#if PY_VERSION_HEX >= ...``.
62-
63-
This version is also available via the symbol :c:var:`Py_Version`.
50+
Run-time version
51+
----------------
6452

6553
.. c:var:: const unsigned long Py_Version
6654
67-
The Python runtime version number encoded in a single constant integer, with
68-
the same format as the :c:macro:`PY_VERSION_HEX` macro.
55+
The Python runtime version number encoded in a single constant integer.
56+
See :c:func:`Py_PACK_FULL_VERSION` for the encoding details.
6957
This contains the Python version used at run time.
7058

59+
Use this for numeric comparisons, for example, ``if (Py_Version >= ...)``.
60+
7161
.. versionadded:: 3.11
7262

73-
All the given macros are defined in :source:`Include/patchlevel.h`.
63+
64+
Bit-packing macros
65+
------------------
66+
67+
.. c:function:: uint32_t Py_PACK_FULL_VERSION(int major, int minor, int micro, int release_level, int release_serial)
68+
69+
Return the given version, encoded as a single 32-bit integer with
70+
the following structure:
71+
72+
+------------------+-------+----------------+-----------+--------------------------+
73+
| | No. | | | Example values |
74+
| | of | | +-------------+------------+
75+
| Argument | bits | Bit mask | Bit shift | ``3.4.1a2`` | ``3.10.0`` |
76+
+==================+=======+================+===========+=============+============+
77+
| *major* | 8 | ``0xFF000000`` | 24 | ``0x03`` | ``0x03`` |
78+
+------------------+-------+----------------+-----------+-------------+------------+
79+
| *minor* | 8 | ``0x00FF0000`` | 16 | ``0x04`` | ``0x0A`` |
80+
+------------------+-------+----------------+-----------+-------------+------------+
81+
| *micro* | 8 | ``0x0000FF00`` | 8 | ``0x01`` | ``0x00`` |
82+
+------------------+-------+----------------+-----------+-------------+------------+
83+
| *release_level* | 4 | ``0x000000F0`` | 4 | ``0xA`` | ``0xF`` |
84+
+------------------+-------+----------------+-----------+-------------+------------+
85+
| *release_serial* | 4 | ``0x0000000F`` | 0 | ``0x2`` | ``0x0`` |
86+
+------------------+-------+----------------+-----------+-------------+------------+
87+
88+
For example:
89+
90+
+-------------+------------------------------------+-----------------+
91+
| Version | ``Py_PACK_FULL_VERSION`` arguments | Encoded version |
92+
+=============+====================================+=================+
93+
| ``3.4.1a2`` | ``(3, 4, 1, 0xA, 2)`` | ``0x030401a2`` |
94+
+-------------+------------------------------------+-----------------+
95+
| ``3.10.0`` | ``(3, 10, 0, 0xF, 0)`` | ``0x030a00f0`` |
96+
+-------------+------------------------------------+-----------------+
97+
98+
Out-of range bits in the arguments are ignored.
99+
That is, the macro can be defined as:
100+
101+
.. code-block:: c
102+
103+
#ifndef Py_PACK_FULL_VERSION
104+
#define Py_PACK_FULL_VERSION(X, Y, Z, LEVEL, SERIAL) ( \
105+
(((X) & 0xff) << 24) | \
106+
(((Y) & 0xff) << 16) | \
107+
(((Z) & 0xff) << 8) | \
108+
(((LEVEL) & 0xf) << 4) | \
109+
(((SERIAL) & 0xf) << 0))
110+
#endif
111+
112+
``Py_PACK_FULL_VERSION`` is primarily a macro, intended for use in
113+
``#if`` directives, but it is also available as an exported function.
114+
115+
.. versionadded:: 3.14
116+
117+
.. c:function:: uint32_t Py_PACK_VERSION(int major, int minor)
118+
119+
Equivalent to ``Py_PACK_FULL_VERSION(major, minor, 0, 0, 0)``.
120+
The result does not correspond to any Python release, but is useful
121+
in numeric comparisons.
122+
123+
.. versionadded:: 3.14

‎Doc/c-api/arg.rst

Lines changed: 23 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -229,12 +229,24 @@ There are three ways strings and buffers can be converted to C:
229229
Numbers
230230
-------
231231

232+
These formats allow representing Python numbers or single characters as C numbers.
233+
Formats that require :class:`int`, :class:`float` or :class:`complex` can
234+
also use the corresponding special methods :meth:`~object.__index__`,
235+
:meth:`~object.__float__` or :meth:`~object.__complex__` to convert
236+
the Python object to the required type.
237+
238+
For signed integer formats, :exc:`OverflowError` is raised if the value
239+
is out of range for the C type.
240+
For unsigned integer formats, no range checking is done --- the
241+
most significant bits are silently truncated when the receiving field is too
242+
small to receive the value.
243+
232244
``b`` (:class:`int`) [unsigned char]
233-
Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
245+
Convert a nonnegative Python integer to an unsigned tiny integer, stored in a C
234246
:c:expr:`unsigned char`.
235247

236248
``B`` (:class:`int`) [unsigned char]
237-
Convert a Python integer to a tiny int without overflow checking, stored in a C
249+
Convert a Python integer to a tiny integer without overflow checking, stored in a C
238250
:c:expr:`unsigned char`.
239251

240252
``h`` (:class:`int`) [short int]
@@ -307,7 +319,7 @@ Other objects
307319

308320
.. _o_ampersand:
309321

310-
``O&`` (object) [*converter*, *anything*]
322+
``O&`` (object) [*converter*, *address*]
311323
Convert a Python object to a C variable through a *converter* function. This
312324
takes two arguments: the first is a function, the second is the address of a C
313325
variable (of arbitrary type), converted to :c:expr:`void *`. The *converter*
@@ -321,14 +333,20 @@ Other objects
321333
the conversion has failed. When the conversion fails, the *converter* function
322334
should raise an exception and leave the content of *address* unmodified.
323335

324-
If the *converter* returns ``Py_CLEANUP_SUPPORTED``, it may get called a
336+
.. c:macro:: Py_CLEANUP_SUPPORTED
337+
:no-typesetting:
338+
339+
If the *converter* returns :c:macro:`!Py_CLEANUP_SUPPORTED`, it may get called a
325340
second time if the argument parsing eventually fails, giving the converter a
326341
chance to release any memory that it had already allocated. In this second
327342
call, the *object* parameter will be ``NULL``; *address* will have the same value
328343
as in the original call.
329344

345+
Examples of converters: :c:func:`PyUnicode_FSConverter` and
346+
:c:func:`PyUnicode_FSDecoder`.
347+
330348
.. versionchanged:: 3.1
331-
``Py_CLEANUP_SUPPORTED`` was added.
349+
:c:macro:`!Py_CLEANUP_SUPPORTED` was added.
332350

333351
``p`` (:class:`bool`) [int]
334352
Tests the value passed in for truth (a boolean **p**\ redicate) and converts
@@ -344,12 +362,6 @@ Other objects
344362
in *items*. The C arguments must correspond to the individual format units in
345363
*items*. Format units for sequences may be nested.
346364

347-
It is possible to pass "long" integers (integers whose value exceeds the
348-
platform's :c:macro:`LONG_MAX`) however no proper range checking is done --- the
349-
most significant bits are silently truncated when the receiving field is too
350-
small to receive the value (actually, the semantics are inherited from downcasts
351-
in C --- your mileage may vary).
352-
353365
A few other characters have a meaning in a format string. These may not occur
354366
inside nested parentheses. They are:
355367

‎Doc/c-api/init.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1492,6 +1492,17 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
14921492
14931493
.. versionadded:: 3.8
14941494
1495+
1496+
.. c:function:: PyObject* PyUnstable_InterpreterState_GetMainModule(PyInterpreterState *interp)
1497+
1498+
Return a :term:`strong reference` to the ``__main__`` `module object <moduleobjects>`_
1499+
for the given interpreter.
1500+
1501+
The caller must hold the GIL.
1502+
1503+
.. versionadded:: 3.13
1504+
1505+
14951506
.. c:type:: PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, _PyInterpreterFrame *frame, int throwflag)
14961507
14971508
Type of a frame evaluation function.

‎Doc/c-api/sys.rst

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,38 @@ Operating System Utilities
216216
The function now uses the UTF-8 encoding on Windows if
217217
:c:member:`PyPreConfig.legacy_windows_fs_encoding` is zero.
218218
219+
.. c:function:: FILE* Py_fopen(PyObject *path, const char *mode)
220+
221+
Similar to :c:func:`!fopen`, but *path* is a Python object and
222+
an exception is set on error.
223+
224+
*path* must be a :class:`str` object, a :class:`bytes` object,
225+
or a :term:`path-like object`.
226+
227+
On success, return the new file pointer.
228+
On error, set an exception and return ``NULL``.
229+
230+
The file must be closed by :c:func:`Py_fclose` rather than calling directly
231+
:c:func:`!fclose`.
232+
233+
The file descriptor is created non-inheritable (:pep:`446`).
234+
235+
The caller must hold the GIL.
236+
237+
.. versionadded:: 3.14
238+
239+
240+
.. c:function:: int Py_fclose(FILE *file)
241+
242+
Close a file that was opened by :c:func:`Py_fopen`.
243+
244+
On success, return ``0``.
245+
On error, return ``EOF`` and ``errno`` is set to indicate the error.
246+
In either case, any further access (including another call to
247+
:c:func:`Py_fclose`) to the stream results in undefined behavior.
248+
249+
.. versionadded:: 3.14
250+
219251
220252
.. _systemfunctions:
221253

‎Doc/c-api/unicode.rst

Lines changed: 27 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -786,33 +786,52 @@ Functions encoding to and decoding from the :term:`filesystem encoding and
786786
error handler` (:pep:`383` and :pep:`529`).
787787
788788
To encode file names to :class:`bytes` during argument parsing, the ``"O&"``
789-
converter should be used, passing :c:func:`PyUnicode_FSConverter` as the
789+
converter should be used, passing :c:func:`!PyUnicode_FSConverter` as the
790790
conversion function:
791791
792792
.. c:function:: int PyUnicode_FSConverter(PyObject* obj, void* result)
793793
794-
ParseTuple converter: encode :class:`str` objects -- obtained directly or
794+
:ref:`PyArg_Parse\* converter <arg-parsing>`: encode :class:`str` objects -- obtained directly or
795795
through the :class:`os.PathLike` interface -- to :class:`bytes` using
796796
:c:func:`PyUnicode_EncodeFSDefault`; :class:`bytes` objects are output as-is.
797-
*result* must be a :c:expr:`PyBytesObject*` which must be released when it is
798-
no longer used.
797+
*result* must be an address of a C variable of type :c:expr:`PyObject*`
798+
(or :c:expr:`PyBytesObject*`).
799+
On success, set the variable to a new :term:`strong reference` to
800+
a :ref:`bytes object <bytesobjects>` which must be released
801+
when it is no longer used and return a non-zero value
802+
(:c:macro:`Py_CLEANUP_SUPPORTED`).
803+
Embedded null bytes are not allowed in the result.
804+
On failure, return ``0`` with an exception set.
805+
806+
If *obj* is ``NULL``, the function releases a strong reference
807+
stored in the variable referred by *result* and returns ``1``.
799808
800809
.. versionadded:: 3.1
801810
802811
.. versionchanged:: 3.6
803812
Accepts a :term:`path-like object`.
804813
805814
To decode file names to :class:`str` during argument parsing, the ``"O&"``
806-
converter should be used, passing :c:func:`PyUnicode_FSDecoder` as the
815+
converter should be used, passing :c:func:`!PyUnicode_FSDecoder` as the
807816
conversion function:
808817
809818
.. c:function:: int PyUnicode_FSDecoder(PyObject* obj, void* result)
810819
811-
ParseTuple converter: decode :class:`bytes` objects -- obtained either
820+
:ref:`PyArg_Parse\* converter <arg-parsing>`: decode :class:`bytes` objects -- obtained either
812821
directly or indirectly through the :class:`os.PathLike` interface -- to
813822
:class:`str` using :c:func:`PyUnicode_DecodeFSDefaultAndSize`; :class:`str`
814-
objects are output as-is. *result* must be a :c:expr:`PyUnicodeObject*` which
815-
must be released when it is no longer used.
823+
objects are output as-is.
824+
*result* must be an address of a C variable of type :c:expr:`PyObject*`
825+
(or :c:expr:`PyUnicodeObject*`).
826+
On success, set the variable to a new :term:`strong reference` to
827+
a :ref:`Unicode object <unicodeobjects>` which must be released
828+
when it is no longer used and return a non-zero value
829+
(:c:macro:`Py_CLEANUP_SUPPORTED`).
830+
Embedded null characters are not allowed in the result.
831+
On failure, return ``0`` with an exception set.
832+
833+
If *obj* is ``NULL``, release the strong reference
834+
to the object referred to by *result* and return ``1``.
816835
817836
.. versionadded:: 3.2
818837

‎Doc/data/stable_abi.dat

Lines changed: 2 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Doc/deprecations/pending-removal-in-3.16.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,11 @@ Pending removal in Python 3.16
5757
In the rare case that you need the bitwise inversion of
5858
the underlying integer, convert to ``int`` explicitly (``~int(x)``).
5959

60+
* :mod:`functools`:
61+
62+
* Calling the Python implementation of :func:`functools.reduce` with *function*
63+
or *sequence* as keyword arguments has been deprecated since Python 3.14.
64+
6065
* :mod:`shutil`:
6166

6267
* The :class:`!ExecError` exception
@@ -79,8 +84,3 @@ Pending removal in Python 3.16
7984

8085
* The undocumented and unused :attr:`!TarFile.tarfile` attribute
8186
has been deprecated since Python 3.13.
82-
83-
* :mod:`functools`:
84-
85-
* Calling the Python implementation of :func:`functools.reduce` with *function*
86-
or *sequence* as keyword arguments has been deprecated since Python 3.14.

0 commit comments

Comments
 (0)
0