Skip to content

Commit 6d89e9d

Browse files
picnixzpicnixz
authored
Merge branch 'main' into perf/uuid/init-128150
2 parents ea23629 + b00e125 commit 6d89e9d

File tree

290 files changed

+12157
-6713
lines changed

Some content is hidden

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

290 files changed

+12157
-6713
lines changed

‎.github/workflows/build.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ jobs:
4646
# reproducible: to get the same tools versions (autoconf, aclocal, ...)
4747
runs-on: ubuntu-24.04
4848
container:
49-
image: ghcr.io/python/autoconf:2024.11.11.11786316759
49+
image: ghcr.io/python/autoconf:2025.01.02.12581854023
5050
timeout-minutes: 60
5151
needs: check_source
5252
if: needs.check_source.outputs.run_tests == 'true'
@@ -63,7 +63,7 @@ jobs:
6363
run: echo "IMAGE_VERSION=${ImageVersion}" >> "$GITHUB_ENV"
6464
- name: Check Autoconf and aclocal versions
6565
run: |
66-
grep "Generated by GNU Autoconf 2.71" configure
66+
grep "Generated by GNU Autoconf 2.72" configure
6767
grep "aclocal 1.16.5" aclocal.m4
6868
grep -q "runstatedir" configure
6969
grep -q "PKG_PROG_PKG_CONFIG" aclocal.m4

‎.github/workflows/reusable-docs.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ jobs:
9999
# Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
100100
doctest:
101101
name: 'Doctest'
102-
runs-on: ubuntu-22.04
102+
runs-on: ubuntu-24.04
103103
timeout-minutes: 60
104104
steps:
105105
- uses: actions/checkout@v4

‎.pre-commit-config.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ repos:
5555
hooks:
5656
- id: check-dependabot
5757
- id: check-github-workflows
58+
- id: check-readthedocs
5859

5960
- repo: https://github.com/rhysd/actionlint
6061
rev: v1.7.4

‎Doc/about.rst

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
=====================
2-
About these documents
3-
=====================
1+
========================
2+
About this documentation
3+
========================
44

55

6-
These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
7-
document processor specifically written for the Python documentation.
6+
Python's documentation is generated from `reStructuredText`_ sources
7+
using `Sphinx`_, a documentation generator originally created for Python
8+
and now maintained as an independent project.
89

910
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
1011
.. _Sphinx: https://www.sphinx-doc.org/
@@ -20,14 +21,14 @@ volunteers are always welcome!
2021
Many thanks go to:
2122

2223
* Fred L. Drake, Jr., the creator of the original Python documentation toolset
23-
and writer of much of the content;
24+
and author of much of the content;
2425
* the `Docutils <https://docutils.sourceforge.io/>`_ project for creating
2526
reStructuredText and the Docutils suite;
2627
* Fredrik Lundh for his Alternative Python Reference project from which Sphinx
2728
got many good ideas.
2829

2930

30-
Contributors to the Python Documentation
31+
Contributors to the Python documentation
3132
----------------------------------------
3233

3334
Many people have contributed to the Python language, the Python standard

‎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/object.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -493,6 +493,13 @@ Object Protocol
493493
on failure. This is equivalent to the Python statement ``del o[key]``.
494494
495495
496+
.. c:function:: int PyObject_DelItemString(PyObject *o, const char *key)
497+
498+
This is the same as :c:func:`PyObject_DelItem`, but *key* is
499+
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
500+
rather than a :c:expr:`PyObject*`.
501+
502+
496503
.. c:function:: PyObject* PyObject_Dir(PyObject *o)
497504
498505
This is equivalent to the Python expression ``dir(o)``, returning a (possibly

‎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:: next
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:: next
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

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy