8000 Merge branch 'main' into color_step1 · python/cpython@8ef9217 · GitHub
[go: up one dir, main page]
Skip to content

Commit 8ef9217

Browse files
StanFromIrelandStanFromIreland
authored
Merge branch 'main' into color_step1
2 parents b456133 + 3dfed23 commit 8ef9217

File tree

151 files changed

+7423
-1804
lines changed

Some content is hidden

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

151 files changed

+7423
-1804
lines changed

‎Doc/c-api/init_config.rst

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -363,7 +363,7 @@ Configuration Options
363363
- Read-only
364364
* - ``"import_time"``
365365
- :c:member:`import_time <PyConfig.import_time>`
366-
- ``bool``
366+
- ``int``
367367
- Read-only
368368
* - ``"inspect"``
369369
- :c:member:`inspect <PyConfig.inspect>`
@@ -1477,13 +1477,19 @@ PyConfig
14771477
14781478
.. c:member:: int import_time
14791479
1480-
If non-zero, profile import time.
1480+
If ``1``, profile import time.
1481+
If ``2``, include additional output that indicates
1482+
when an imported module has already been loaded.
14811483
1482-
Set the ``1`` by the :option:`-X importtime <-X>` option and the
1484+
Set by the :option:`-X importtime <-X>` option and the
14831485
:envvar:`PYTHONPROFILEIMPORTTIME` environment variable.
14841486
14851487
Default: ``0``.
14861488
1489+
.. versionchanged:: next
1490+
1491+
Added support for ``import_time = 2``
1492+
14871493
.. c:member:: int inspect
14881494
14891495
Enter interactive mode after executing a script or a command.

‎Doc/c-api/object.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -737,3 +737,21 @@ Object Protocol
737737
caller must hold a :term:`strong reference` to *obj* when calling this.
738738
739739
.. versionadded:: 3.14
740+
741+
.. c:function:: int PyUnstable_Object_IsUniquelyReferenced(PyObject *op)
742+
743+
Determine if *op* only has one reference.
744+
745+
On GIL-enabled builds, this function is equivalent to
746+
:c:expr:`Py_REFCNT(op) == 1`.
747+
748+
On a :term:`free threaded <free threading>` build, this checks if *op*'s
749+
:term:`reference count` is equal to one and additionally checks if *op*
750+
is only used by this thread. :c:expr:`Py_REFCNT(op) == 1` is **not**
751+
thread-safe on free threaded builds; prefer this function.
752+
753+
The caller must hold an :term:`attached thread state`, despite the fact
754+
that this function doesn't call into the Python interpreter. This function
755+
cannot fail.
756+
757+
.. versionadded:: 3.14

‎Doc/c-api/refcounting.rst

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,14 @@ of Python objects.
2323
2424
Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count.
2525
26-
See also the function :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary()`.
26+
.. note::
27+
28+
On :term:`free threaded <free threading>` builds of Python, returning 1
29+
isn't sufficient to determine if it's safe to treat *o* as having no
30+
access by other threads. Use :c:func:`PyUnstable_Object_IsUniquelyReferenced`
31+
for that instead.
32+
33+
See also the function :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary()`.
2734
2835
.. versionchanged:: 3.10
2936
:c:func:`Py_REFCNT()` is changed to the inline static function.

‎Doc/library/cmdline.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _library-cmdline:
2+
13
++++++++++++++++++++++++++++++++++++
24
Modules command-line interface (CLI)
35
++++++++++++++++++++++++++++++++++++

‎Doc/library/gc.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -128,8 +128,8 @@ The :mod:`gc` module provides the following functions:
128128
starts. For each collection, all the objects in the young generation and some
129129
fraction of the old generation is collected.
130130

131-
In the free-threaded build, the increase in process resident set size (RSS)
132-
is also checked before running the collector. If the RSS has not increased
131+
In the free-threaded build, the increase in process memory usage is also
132+
checked before running the collector. If the memory usage has not increased
133133
by 10% since the last collection and the net number of object allocations
134134
has not exceeded 40 times *threshold0*, the collection is not run.
135135

‎Doc/library/getpass.rst

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616

1717
The :mod:`getpass` module provides two functions:
1818

19-
.. function:: getpass(prompt='Password: ', stream=None)
19+
.. function:: getpass(prompt='Password: ', stream=None, *, echo_char=None)
2020

2121
Prompt the user for a password without echoing. The user is prompted using
2222
the string *prompt*, which defaults to ``'Password: '``. On Unix, the
@@ -25,6 +25,12 @@ The :mod:`getpass` module provides two functions:
2525
(:file:`/dev/tty`) or if that is unavailable to ``sys.stderr`` (this
2626
argument is ignored on Windows).
2727

28+
The *echo_char* argument controls how user input is displayed while typing.
29+
If *echo_char* is ``None`` (default), input remains hidden. Otherwise,
30+
*echo_char* must be a printable ASCII string and each typed character
31+
is replaced by it. For example, ``echo_char='*'`` will display
32+
asterisks instead of the actual input.
33+
2834
If echo free input is unavailable getpass() falls back to printing
2935
a warning message to *stream* and reading from ``sys.stdin`` and
3036
issuing a :exc:`GetPassWarning`.
@@ -33,6 +39,9 @@ The :mod:`getpass` module provides two functions:
3339
If you call getpass from within IDLE, the input may be done in the
3440
terminal you launched IDLE from rather than the idle window itself.
3541

42+
.. versionchanged:: next
43+
Added the *echo_char* parameter for keyboard feedback.
44+
3645
.. exception:: GetPassWarning
3746

57AE
3847
A :exc:`UserWarning` subclass issued when password input may be echoed.

‎Doc/library/sys.rst

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1282,6 +1282,64 @@ always available. Unless explicitly noted otherwise, all variables are read-only
12821282

12831283
.. versionadded:: 3.5
12841284

1285+
.. data:: _jit
1286+
1287+
Utilities for observing just-in-time compilation.
1288+
1289+
.. impl-detail::
1290+
1291+
JIT compilation is an *experimental implementation detail* of CPython.
1292+
``sys._jit`` is not guaranteed to exist or behave the same way in all
1293+
Python implementations, versions, or build configurations.
1294+
1295+
.. versionadded:: next
1296+
1297+
.. function:: _jit.is_available()
1298+
1299+
Return ``True`` if the current Python executable supports JIT compilation,
1300+
and ``False`` otherwise. This can be controlled by building CPython with
1301+
the ``--experimental-jit`` option on Windows, and the
1302+
:option:`--enable-experimental-jit` option on all other platforms.
1303+
1304+
.. function:: _jit.is_enabled()
1305+
1306+
Return ``True`` if JIT compilation is enabled for the current Python
1307+
process (implies :func:`sys._jit.is_available`), and ``False`` otherwise.
1308+
If JIT compilation is available, this can be controlled by setting the
1309+
:envvar:`PYTHON_JIT` environment variable to ``0`` (disabled) or ``1``
1310+
(enabled) at interpreter startup.
1311+
1312+
.. function:: _jit.is_active()
1313+
1314+
Return ``True`` if the topmost Python frame is currently executing JIT
1315+
code (implies :func:`sys._jit.is_enabled`), and ``False`` otherwise.
1316+
1317+
.. note::
1318+
1319+
This function is intended for testing and debugging the JIT itself.
1320+
It should be avoided for any other purpose.
1321+
1322+
.. note::
1323+
1324+
Due to the nature of tracing JIT compilers, repeated calls to this
1325+
function may give surprising results. For example, branching on its
1326+
return value will likely lead to unexpected behavior (if doing so
1327+
causes JIT code to be entered or exited):
1328+
1329+
.. code-block:: pycon
1330+
1331+
>>> for warmup in range(BIG_NUMBER):
1332+
... # This line is "hot", and is eventually JIT-compiled:
1333+
... if sys._jit.is_active():
1334+
... # This line is "cold", and is run in the interpreter:
1335+
... assert sys._jit.is_active()
1336+
...
1337+
Traceback (most recent call last):
1338+
File "<stdin>", line 5, in <module>
1339+
assert sys._jit.is_active()
1340+
~~~~~~~~~~~~~~~~~~^^
1341+
AssertionError
1342+
12851343
.. data:: last_exc
12861344

12871345
This variable is not always defined; it is set to the exception instance

‎Doc/library/typing.rst

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1098,6 +1098,12 @@ These can be used as types in annotations. They all support subscription using
10981098

10991099
Union[Union[int, str], float] == Union[int, str, float]
11001100

1101+
However, this does not apply to unions referenced through a type
1102+
alias, to avoid forcing evaluation of the underlying :class:`TypeAliasType`::
1103+
1104+
type A = Union[int, str]
1105+
Union[A, float] != Union[int, str, float]
1106+
11011107
* Unions of a single argument vanish, e.g.::
11021108

11031109
Union[int] == int # The constructor actually returns int
@@ -1230,6 +1236,32 @@ These can be used as types in annotations. They all support subscription using
12301236
is allowed as type argument to ``Literal[...]``, but type checkers may
12311237
impose restrictions. See :pep:`586` for more details about literal types.
12321238

1239+
Additional details:
1240+
1241+
* The arguments must be literal values and there must be at least one.
1242+
1243+
* Nested ``Literal`` types are flattened, e.g.::
1244+
1245+
assert Literal[Literal[1, 2], 3] == Literal[1, 2, 3]
1246+
1247+
However, this does not apply to ``Literal`` types referenced through a type
1248+
alias, to avoid forcing evaluation of the underlying :class:`TypeAliasType`::
1249+
1250+
type A = Literal[1, 2]
1251+
assert Literal[A, 3] != Literal[1, 2, 3]
1252+
1253+
* Redundant arguments are skipped, e.g.::
1254+
1255+
assert Literal[1, 2, 1] == Literal[1, 2]
1256+
1257+
* When comparing literals, the argument order is ignored, e.g.::
1258+
1259+
assert Literal[1, 2] == Literal[2, 1]
1260+
1261+
* You cannot subclass or instantiate a ``Literal``.
1262+
1263+
* You cannot write ``Literal[X][Y]``.
1264+
12331265
.. versionadded:: 3.8
12341266

12351267
.. versionchanged:: 3.9.1
@@ -1400,6 +1432,14 @@ These can be used as types in annotations. They all support subscription using
14001432
int, ValueRange(3, 10), ctype("char")
14011433
]
14021434

1435+
However, this does not apply to ``Annotated`` types referenced through a type
1436+
alias, to avoid forcing evaluation of the underlying :class:`TypeAliasType`::
1437+
1438+
type From3To10[T] = Annotated[T, ValueRange(3, 10)]
1439+
assert Annotated[From3To10[int], ctype("char")] != Annotated[
1440+
int, ValueRange(3, 10), ctype("char")
1441+
]
1442+
14031443
Duplicated metadata elements are not removed::
14041444

14051445
assert Annotated[int, ValueRange(3, 10)] != Annotated[

‎Doc/using/cmdline.rst

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -539,11 +539,21 @@ Miscellaneous options
539539
* ``-X importtime`` to show how long each import takes. It shows module
540540
name, cumulative time (including nested imports) and self time (excluding
541541
nested imports). Note that its output may be broken in multi-threaded
542-
application. Typical usage is ``python3 -X importtime -c 'import
543-
asyncio'``. See also :envvar:`PYTHONPROFILEIMPORTTIME`.
542+
application. Typical usage is ``python -X importtime -c 'import asyncio'``.
543+
544+
``-X importtime=2`` enables additional output that indicates when an
545+
imported module has already been loaded. In such cases, the string
546+
``cached`` will be printed in both time columns.
547+
548+
See also :envvar:`PYTHONPROFILEIMPORTTIME`.
544549

545550
.. versionadded:: 3.7
546551

552+
.. versionchanged:: next
553+
554+
Added ``-X importtime=2`` to also trace imports of loaded modules,
555+
and reserved values other than ``1`` and ``2`` for future use.
556+
547557
* ``-X dev``: enable :ref:`Python Development Mode <devmode>`, introducing
548558
additional runtime checks that are too expensive to be enabled by
549559
default. See also :envvar:`PYTHONDEVMODE`.
@@ -982,12 +992,17 @@ conflict.
982992

983993
.. envvar:: PYTHONPROFILEIMPORTTIME
984994

985-
If this environment variable is set to a non-empty string, Python will
986-
show how long each import takes.
995+
If this environment variable is set to ``1``, Python will show
996+
how long each import takes. If set to ``2``, Python will include output for
997+
imported modules that have already been loaded.
987998
This is equivalent to setting the :option:`-X` ``importtime`` option.
988999

9891000
.. versionadded:: 3.7
9901001

1002+
.. versionchanged:: next
1003+
1004+
Added ``PYTHONPROFILEIMPORTTIME=2`` to also trace imports of loaded modules.
1005+
9911006

9921007
.. envvar:: PYTHONASYNCIODEBUG
9931008

@@ -1279,6 +1294,14 @@ conflict.
12791294

12801295
.. versionadded:: 3.14
12811296

1297+
.. envvar:: PYTHON_JIT
1298+
1299+
On builds where experimental just-in-time compilation is available, this
1300+
variable can force the JIT to be disabled (``0``) or enabled (``1``) at
1301+
interpreter startup.
1302+
1303+
.. versionadded:: 3.13
1304+
12821305
Debug-mode variables
12831306
~~~~~~~~~~~~~~~~~~~~
12841307

‎Doc/using/configure.rst

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -302,14 +302,21 @@ General Options
302302

303303
.. option:: --enable-experimental-jit=[no|yes|yes-off|interpreter]
304304

305-
Indicate how to integrate the :ref:`JIT compiler <whatsnew313-jit-compiler>`.
306-
307-
* ``no`` - build the interpreter without the JIT.
308-
* ``yes`` - build the interpreter with the JIT.
309-
* ``yes-off`` - build the interpreter with the JIT but disable it by default.
310-
* ``interpreter`` - build the interpreter without the JIT, but with the tier 2 enabled interpreter.
311-
312-
By convention, ``--enable-experimental-jit`` is a shorthand for ``--enable-experimental-jit=yes``.
305+
Indicate how to integrate the :ref:`experimental just-in-time compiler <whatsnew314-jit-compiler>`.
306+
307+
* ``no``: Don't build the JIT.
308+
* ``yes``: Enable the JIT. To disable it at runtime, set the environment
309+
variable :envvar:`PYTHON_JIT=0 <PYTHON_JIT>`.
310+
* ``yes-off``: Build the JIT, but disable it by default. To enable it at
311+
runtime, set the environment variable :envvar:`PYTHON_JIT=1 <PYTHON_JIT>`.
312+
* ``interpreter``: Enable the "JIT interpreter" (only useful for those
313+
debugging the JIT itself). To disable it at runtime, set the environment
314+
variable :envvar:`PYTHON_JIT=0 <PYTHON_JIT>`.
315+
316+
``--enable-experimental-jit=no`` is the default behavior if the option is not
317+
provided, and ``--enable-experimental-jit`` is shorthand for
318+
``--enable-experimental-jit=yes``. See :file:`Tools/jit/README.md` for more
319+
information, including how to install the necessary build-time dependencies.
313320

314321
.. note::
315322

0 commit comments

Comments
 (0)
0