Skip to content

Commit f709deb

Browse files
encukouencukou
committed
Merge in the main branch
2 parents d0d2f73 + 9d3b53c commit f709deb

File tree

203 files changed

+5763
-1781
lines changed

Some content is hidden

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

203 files changed

+5763
-1781
lines changed

‎Doc/c-api/arg.rst

Lines changed: 0 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -113,18 +113,14 @@ There are three ways strings and buffers can be converted to C:
113113
``z`` (:class:`str` or ``None``) [const char \*]
114114
Like ``s``, but the Python object may also be ``None``, in which case the C
115115
pointer is set to ``NULL``.
116-
It is the same as ``s?`` with the C pointer was initialized to ``NULL``.
117116

118117
``z*`` (:class:`str`, :term:`bytes-like object` or ``None``) [Py_buffer]
119118
Like ``s*``, but the Python object may also be ``None``, in which case the
120119
``buf`` member of the :c:type:`Py_buffer` structure is set to ``NULL``.
121-
It is the same as ``s*?`` with the ``buf`` member of the :c:type:`Py_buffer`
122-
structure was initialized to ``NULL``.
123120

124121
``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, :c:type:`Py_ssize_t`]
125122
Like ``s#``, but the Python object may also be ``None``, in which case the C
126123
pointer is set to ``NULL``.
127-
It is the same as ``s#?`` with the C pointer was initialized to ``NULL``.
128124

129125
``y`` (read-only :term:`bytes-like object`) [const char \*]
130126
This format converts a bytes-like object to a C pointer to a
@@ -394,17 +390,6 @@ Other objects
394390
Non-tuple sequences are deprecated if *items* contains format units
395391
which store a borrowed buffer or a borrowed reference.
396392

397-
``unit?`` (anything or ``None``) [*matching-variable(s)*]
398-
``?`` modifies the behavior of the preceding format unit.
399-
The C variable(s) corresponding to that parameter should be initialized
400-
to their default value --- when the argument is ``None``,
401-
:c:func:`PyArg_ParseTuple` does not touch the contents of the corresponding
402-
C variable(s).
403-
If the argument is not ``None``, it is parsed according to the specified
404-
format unit.
405-
406-
.. versionadded:: 3.14
407-
408393
A few other characters have a meaning in a format string. These may not occur
409394
inside nested parentheses. They are:
410395

‎Doc/c-api/init.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2287,7 +2287,7 @@ The C-API provides a basic mutual exclusion lock.
22872287
should not be used to make concurrency control decisions, as the lock
22882288
state may change immediately after the check.
22892289
2290-
.. versionadded:: next
2290+
.. versionadded:: 3.14
22912291
22922292
.. _python-critical-section-api:
22932293
@@ -2372,7 +2372,7 @@ code triggered by the finalizer blocks and calls :c:func:`PyEval_SaveThread`.
23722372
23732373
On the default build, this macro expands to ``{``.
23742374
2375-
.. versionadded:: next
2375+
.. versionadded:: 3.14
23762376
23772377
.. c:macro:: Py_END_CRITICAL_SECTION()
23782378
@@ -2418,7 +2418,7 @@ code triggered by the finalizer blocks and calls :c:func:`PyEval_SaveThread`.
24182418
24192419
On the default build, this macro expands to ``{``.
24202420
2421-
.. versionadded:: next
2421+
.. versionadded:: 3.14
24222422
24232423
.. c:macro:: Py_END_CRITICAL_SECTION2()
24242424

‎Doc/c-api/perfmaps.rst

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,12 @@
55
Support for Perf Maps
66
----------------------
77

8-
On supported platforms (as of this writing, only Linux), the runtime can take
8+
On supported platforms (Linux and macOS), the runtime can take
99
advantage of *perf map files* to make Python functions visible to an external
10-
profiling tool (such as `perf <https://perf.wiki.kernel.org/index.php/Main_Page>`_).
11-
A running process may create a file in the ``/tmp`` directory, which contains entries
12-
that can map a section of executable code to a name. This interface is described in the
10+
profiling tool (such as `perf <https://perf.wiki.kernel.org/index.php/Main_Page>`_ or
11+
`samply <https://github.com/mstange/samply/>`_). A running process may create a
12+
file in the ``/tmp`` directory, which contains entries that can map a section
13+
of executable code to a name. This interface is described in the
1314
`documentation of the Linux Perf tool <https://git.kernel.org/pub/scm/linux/
1415
kernel/git/torvalds/linux.git/tree/tools/perf/Documentation/jit-interface.txt>`_.
1516

‎Doc/extending/extending.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -214,7 +214,7 @@ and initialize it by calling :c:func:`PyErr_NewException` in the module's
214214

215215
SpamError = PyErr_NewException("spam.error", NULL, NULL);
216216

217-
Since :c:data:`!SpamError` is a global variable, it will be overwitten every time
217+
Since :c:data:`!SpamError` is a global variable, it will be overwritten every time
218218
the module is reinitialized, when the :c:data:`Py_mod_exec` function is called.
219219

220220
For now, let's avoid the issue: we will block repeated initialization by raising an

‎Doc/glossary.rst

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -462,7 +462,7 @@ Glossary
462462
core and with user code.
463463

464464
f-string
465-
String literals prefixed with ``'f'`` or ``'F'`` are commonly called
465+
String literals prefixed with ``f`` or ``F`` are commonly called
466466
"f-strings" which is short for
467467
:ref:`formatted string literals <f-strings>`. See also :pep:`498`.
468468

@@ -1322,6 +1322,11 @@ Glossary
13221322

13231323
See also :term:`borrowed reference`.
13241324

1325+
t-string
1326+
String literals prefixed with ``t`` or ``T`` are commonly called
1327+
"t-strings" which is short for
1328+
:ref:`template string literals <t-strings>`.
1329+
13251330
text encoding
13261331
A string in Python is a sequence of Unicode code points (in range
13271332
``U+0000``--``U+10FFFF``). To store or transfer a string, it needs to be

‎Doc/howto/free-threading-extensions.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,8 @@ that return :term:`strong references <strong reference>`.
161161
+===================================+===================================+
162162
| :c:func:`PyList_GetItem` | :c:func:`PyList_GetItemRef` |
163163
+-----------------------------------+-----------------------------------+
164+
| :c:func:`PyList_GET_ITEM` | :c:func:`PyList_GetItemRef` |
165+
+-----------------------------------+-----------------------------------+
164166
| :c:func:`PyDict_GetItem` | :c:func:`PyDict_GetItemRef` |
165167
+-----------------------------------+-----------------------------------+
166168
| :c:func:`PyDict_GetItemWithError` | :c:func:`PyDict_GetItemRef` |

‎Doc/howto/perf_profiling.rst

Lines changed: 41 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,34 +2,35 @@
22

33
.. _perf_profiling:
44

5-
==============================================
6-
Python support for the Linux ``perf`` profiler
7-
==============================================
5+
========================================================
6+
Python support for the ``perf map`` compatible profilers
7+
========================================================
88

99
:author: Pablo Galindo
1010

11-
`The Linux perf profiler <https://perf.wiki.kernel.org>`_
12-
is a very powerful tool that allows you to profile and obtain
13-
information about the performance of your application.
14-
``perf`` also has a very vibrant ecosystem of tools
15-
that aid with the analysis of the data that it produces.
11+
`The Linux perf profiler <https://perf.wiki.kernel.org>`_ and
12+
`samply <https://github.com/mstange/samply>`_ are powerful tools that allow you to
13+
profile and obtain information about the performance of your application.
14+
Both tools have vibrant ecosystems that aid with the analysis of the data they produce.
1615

17-
The main problem with using the ``perf`` profiler with Python applications is that
18-
``perf`` only gets information about native symbols, that is, the names of
16+
The main problem with using these profilers with Python applications is that
17+
they only get information about native symbols, that is, the names of
1918
functions and procedures written in C. This means that the names and file names
20-
of Python functions in your code will not appear in the output of ``perf``.
19+
of Python functions in your code will not appear in the profiler output.
2120

2221
Since Python 3.12, the interpreter can run in a special mode that allows Python
23-
functions to appear in the output of the ``perf`` profiler. When this mode is
22+
functions to appear in the output of compatible profilers. When this mode is
2423
enabled, the interpreter will interpose a small piece of code compiled on the
25-
fly before the execution of every Python function and it will teach ``perf`` the
24+
fly before the execution of every Python function and it will teach the profiler the
2625
relationship between this piece of code and the associated Python function using
2726
:doc:`perf map files <../c-api/perfmaps>`.
2827

2928
.. note::
3029

31-
Support for the ``perf`` profiler is currently only available for Linux on
32-
select architectures. Check the output of the ``configure`` build step or
30+
Support for profiling is available on Linux and macOS on select architectures.
31+
Perf is available on Linux, while samply can be used on both Linux and macOS.
32+
samply support on macOS is available starting from Python 3.15.
33+
Check the output of the ``configure`` build step or
3334
check the output of ``python -m sysconfig | grep HAVE_PERF_TRAMPOLINE``
3435
to see if your system is supported.
3536

@@ -148,6 +149,31 @@ Instead, if we run the same experiment with ``perf`` support enabled we get:
148149
149150
150151
152+
Using the samply profiler
153+
-------------------------
154+
155+
samply is a modern profiler that can be used as an alternative to perf.
156+
It uses the same perf map files that Python generates, making it compatible
157+
with Python's profiling support. samply is particularly useful on macOS
158+
where perf is not available.
159+
160+
To use samply with Python, first install it following the instructions at
161+
https://github.com/mstange/samply, then run::
162+
163+
$ samply record PYTHONPERFSUPPORT=1 python my_script.py
164+
165+
This will open a web interface where you can analyze the profiling data
166+
interactively. The advantage of samply is that it provides a modern
167+
web-based interface for analyzing profiling data and works on both Linux
168+
and macOS.
169+
170+
On macOS, samply support requires Python 3.15 or later. Also on macOS, samply
171+
can't profile signed Python executables due to restrictions by macOS. You can
172+
profile with Python binaries that you've compiled yourself, or which are
173+
unsigned or locally-signed (such as anything installed by Homebrew). In
174+
order to attach to running processes on macOS, run ``samply setup`` once (and
175+
every time samply is updated) to self-sign the samply binary.
176+
151177
How to enable ``perf`` profiling support
152178
----------------------------------------
153179

‎Doc/library/annotationlib.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -511,7 +511,7 @@ code execution even with no access to any globals or builtins. For example:
511511
512512
>>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__.__builtins__["print"]("Hello world")): pass
513513
...
514-
>>> annotationlib.get_annotations(f, format=annotationlib.Format.SOURCE)
514+
>>> annotationlib.get_annotations(f, format=annotationlib.Format.STRING)
515515
Hello world
516516
{'x': 'None'}
517517

‎Doc/library/array.rst

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ defined:
2424
+-----------+--------------------+-------------------+-----------------------+-------+
2525
| ``'u'`` | wchar_t | Unicode character | 2 | \(1) |
2626
+-----------+--------------------+-------------------+-----------------------+-------+
27-
| ``'w'`` | Py_UCS4 | Unicode character | 4 | |
27+
| ``'w'`` | Py_UCS4 | Unicode character | 4 | \(2) |
2828
+-----------+--------------------+-------------------+-----------------------+-------+
2929
| ``'h'`` | signed short | int | 2 | |
3030
+-----------+--------------------+-------------------+-----------------------+-------+
@@ -60,6 +60,9 @@ Notes:
6060
.. deprecated-removed:: 3.3 3.16
6161
Please migrate to ``'w'`` typecode.
6262

63+
(2)
64+
.. versionadded:: 3.13
65+
6366

6467
The actual representation of values is determined by the machine architecture
6568
(strictly speaking, by the C implementation). The actual size can be accessed

‎Doc/library/ast.rst

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -289,9 +289,9 @@ Literals
289289
* ``conversion`` is an integer:
290290

291291
* -1: no formatting
292-
* 115: ``!s`` string formatting
293-
* 114: ``!r`` repr formatting
294-
* 97: ``!a`` ascii formatting
292+
* 115 (``ord('s')``): ``!s`` string formatting
293+
* 114 (``ord('r')``): ``!r`` repr formatting
294+
* 97 (``ord('a')``): ``!a`` ASCII formatting
295295

296296
* ``format_spec`` is a :class:`JoinedStr` node representing the formatting
297297
of the value, or ``None`` if no format was specified. Both
@@ -325,6 +325,54 @@ Literals
325325
Constant(value='.3')]))]))
326326

327327

328+
.. class:: TemplateStr(values)
329+
330+
A t-string, comprising a series of :class:`Interpolation` and :class:`Constant`
331+
nodes.
332+
333+
.. doctest::
334+
335+
>>> print(ast.dump(ast.parse('t"{name} finished {place:ordinal}"', mode='eval'), indent=4))
336+
Expression(
337+
body=TemplateStr(
338+
values=[
339+
Interpolation(
340+
value=Name(id='name'),
341+
str='name',
342+
conversion=-1),
343+
Constant(value=' finished '),
344+
Interpolation(
345+
value=Name(id='place'),
346+
str='place',
347+
conversion=-1,
348+
format_spec=JoinedStr(
349+
values=[
350+
Constant(value='ordinal')]))]))
351+
352+
.. versionadded:: 3.14
353+
354+
355+
.. class:: Interpolation(value, str, conversion, format_spec)
356+
357+
Node representing a single interpolation field in a t-string.
358+
359+
* ``value`` is any expression node (such as a literal, a variable, or a
360+
function call).
361+
* ``str`` is a constant containing the text of the interpolation expression.
362+
* ``conversion`` is an integer:
363+
364+
* -1: no conversion
365+
* 115: ``!s`` string conversion
366+
* 114: ``!r`` repr conversion
367+
* 97: ``!a`` ascii conversion
368+
369+
* ``format_spec`` is a :class:`JoinedStr` node representing the formatting
370+
of the value, or ``None`` if no format was specified. Both
371+
``conversion`` and ``format_spec`` can be set at the same time.
372+
373+
.. versionadded:: 3.14
374+
375+
328376
.. class:: List(elts, ctx)
329377
Tuple(elts, ctx)
330378

0 commit comments

Comments
 (0)