Skip to content

Commit 4e7a034

Browse files
brettcannonbrettcannon
authored
Merge branch 'main' into builtin-submodules
2 parents 5d5b934 + f513d5c commit 4e7a034

124 files changed

Lines changed: 2762 additions & 1498 deletions

File tree

Some content is hidden

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

‎.devcontainer/devcontainer.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,16 @@
3737
// "ms-python.python"
3838
],
3939
"settings": {
40+
"C_Cpp.default.compilerPath": "/usr/bin/clang",
4041
"C_Cpp.default.cStandard": "c11",
4142
"C_Cpp.default.defines": [
43+
"CONFIG_64",
4244
"Py_BUILD_CORE"
4345
],
46+
"C_Cpp.default.includePath": [
47+
"${workspaceFolder}/*",
48+
"${workspaceFolder}/Include/**"
49+
],
4450
// https://github.com/microsoft/vscode-cpptools/issues/10732
4551
"C_Cpp.errorSquiggles": "disabled",
4652
"editor.insertSpaces": true,

‎Doc/howto/enum.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -284,6 +284,7 @@ The values are chosen by :func:`_generate_next_value_`, which can be
284284
overridden::
285285

286286
>>> class AutoName(Enum):
287+
... @staticmethod
287288
... def _generate_next_value_(name, start, count, last_values):
288289
... return name
289290
...
@@ -372,6 +373,11 @@ below)::
372373
>>> Color.BLUE == 2
373374
False
374375

376+
.. warning::
377+
378+
It is possible to reload modules -- if a reloaded module contains
379+
enums, they will be recreated, and the new members may not
380+
compare identical/equal to the original members.
375381

376382
Allowed members and attributes of enumerations
377383
----------------------------------------------

‎Doc/library/enum.rst‎

Lines changed: 25 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -141,9 +141,8 @@ Module Contents
141141
:func:`global_enum`
142142

143143
Modify the :class:`str() <str>` and :func:`repr` of an enum
144-
to show its members as belonging to the module instead of its class.
145-
Should only be used if the enum members will be exported to the
146-
module global namespace.
144+
to show its members as belonging to the module instead of its class,
145+
and export the enum members to the global namespace.
147146

148147
:func:`show_flag_values`
149148

@@ -170,6 +169,27 @@ Data Types
170169
final *enum*, as well as creating the enum members, properly handling
171170
duplicates, providing iteration over the enum class, etc.
172171

172+
.. method:: EnumType.__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
173+
174+
This method is called in two different ways:
175+
176+
* to look up an existing member:
177+
178+
:cls: The enum class being called.
179+
:value: The value to lookup.
180+
181+
* to use the ``cls`` enum to create a new enum (only if the existing enum
182+
does not have any members):
183+
184+
:cls: The enum class being called.
185+
:value: The name of the new Enum to create.
186+
:names: The names/values of the members for the new Enum.
187+
:module: The name of the module the new Enum is created in.
188+
:qualname: The actual location in the module where this Enum can be found.
189+
:type: A mix-in type for the new Enum.
190+
:start: The first integer value for the Enum (used by :class:`auto`).
191+
:boundary: How to handle out-of-range values from bit operations (:class:`Flag` only).
192+
173193
.. method:: EnumType.__contains__(cls, member)
174194

175195
Returns ``True`` if member belongs to the ``cls``::
@@ -255,26 +275,6 @@ Data Types
255275
names will also be removed from the completed enumeration. See
256276
:ref:`TimePeriod <enum-time-period>` for an example.
257277

258-
.. method:: Enum.__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
259-
260-
This method is called in two different ways:
261-
262-
* to look up an existing member:
263-
264-
:cls: The enum class being called.
265-
:value: The value to lookup.
266-
267-
* to use the ``cls`` enum to create a new enum:
268-
269-
:cls: The enum class being called.
270-
:value: The name of the new Enum to create.
271-
:names: The names/values of the members for the new Enum.
272-
:module: The name of the module the new Enum is created in.
273-
:qualname: The actual location in the module where this Enum can be found.
274-
:type: A mix-in type for the new Enum.
275-
:start: The first integer value for the Enum (used by :class:`auto`).
276-
:boundary: How to handle out-of-range values from bit operations (:class:`Flag` only).
277-
278278
.. method:: Enum.__dir__(self)
279279

280280
Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and
@@ -728,7 +728,6 @@ Data Types
728728
.. attribute:: EJECT
729729

730730
Out-of-range values lose their *Flag* membership and revert to :class:`int`.
731-
This is the default for :class:`IntFlag`::
732731

733732
>>> from enum import Flag, EJECT, auto
734733
>>> class EjectFlag(Flag, boundary=EJECT):
@@ -741,8 +740,8 @@ Data Types
741740

742741
.. attribute:: KEEP
743742

744-
Out-of-range values are kept, and the *Flag* membership is kept. This is
745-
used for some stdlib flags::
743+
Out-of-range values are kept, and the *Flag* membership is kept.
744+
This is the default for :class:`IntFlag`::
746745

747746
>>> from enum import Flag, KEEP, auto
748747
>>> class KeepFlag(Flag, boundary=KEEP):

‎Doc/library/profile.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ the following::
8282

8383
The first line indicates that 214 calls were monitored. Of those calls, 207
8484
were :dfn:`primitive`, meaning that the call was not induced via recursion. The
85-
next line: ``Ordered by: cumulative name``, indicates that the text string in the
85+
next line: ``Ordered by: cumulative time``, indicates that the text string in the
8686
far right column was used to sort the output. The column headings include:
8787

8888
ncalls

‎Doc/library/shutil.rst‎

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -433,23 +433,43 @@ Directory and files operations
433433
When no *path* is specified, the results of :func:`os.environ` are used,
434434
returning either the "PATH" value or a fallback of :attr:`os.defpath`.
435435

436-
On Windows, the current directory is always prepended to the *path* whether
437-
or not you use the default or provide your own, which is the behavior the
438-
command shell uses when finding executables. Additionally, when finding the
439-
*cmd* in the *path*, the ``PATHEXT`` environment variable is checked. For
440-
example, if you call ``shutil.which("python")``, :func:`which` will search
441-
``PATHEXT`` to know that it should look for ``python.exe`` within the *path*
442-
directories. For example, on Windows::
436+
On Windows, the current directory is prepended to the *path* if *mode* does
437+
not include ``os.X_OK``. When the *mode* does include ``os.X_OK``, the
438+
Windows API ``NeedCurrentDirectoryForExePathW`` will be consulted to
439+
determine if the current directory should be prepended to *path*. To avoid
440+
consulting the current working directory for executables: set the environment
441+
variable ``NoDefaultCurrentDirectoryInExePath``.
442+
443+
Also on Windows, the ``PATHEXT`` variable is used to resolve commands
444+
that may not already include an extension. For example, if you call
445+
``shutil.which("python")``, :func:`which` will search ``PATHEXT``
446+
to know that it should look for ``python.exe`` within the *path*
447+
directories. For example, on Windows::
443448

444449
>>> shutil.which("python")
445450
'C:\\Python33\\python.EXE'
446451

452+
This is also applied when *cmd* is a path that contains a directory
453+
component::
454+
455+
>> shutil.which("C:\\Python33\\python")
456+
'C:\\Python33\\python.EXE'
457+
447458
.. versionadded:: 3.3
448459

449460
.. versionchanged:: 3.8
450461
The :class:`bytes` type is now accepted. If *cmd* type is
451462
:class:`bytes`, the result type is also :class:`bytes`.
452463

464+
.. versionchanged:: 3.12
465+
On Windows, the current directory is no longer prepended to the search
466+
path if *mode* includes ``os.X_OK`` and WinAPI
467+
``NeedCurrentDirectoryForExePathW(cmd)`` is false, else the current
468+
directory is prepended even if it is already in the search path;
469+
``PATHEXT`` is used now even when *cmd* includes a directory component
470+
or ends with an extension that is in ``PATHEXT``; and filenames that
471+
have no extension can now be found.
472+
453473
.. exception:: Error
454474

455475
This exception collects exceptions that are raised during a multi-file

‎Doc/library/socket.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1775,7 +1775,7 @@ to sockets.
17751775
much data, if any, was successfully sent.
17761776

17771777
.. versionchanged:: 3.5
1778-
The socket timeout is no more reset each time data is sent successfully.
1778+
The socket timeout is no longer reset each time data is sent successfully.
17791779
The socket timeout is now the maximum total duration to send all data.
17801780

17811781
.. versionchanged:: 3.5
@@ -1998,8 +1998,8 @@ can be changed by calling :func:`setdefaulttimeout`.
19981998

19991999
* In *non-blocking mode*, operations fail (with an error that is unfortunately
20002000
system-dependent) if they cannot be completed immediately: functions from the
2001-
:mod:`select` can be used to know when and whether a socket is available for
2002-
reading or writing.
2001+
:mod:`select` module can be used to know when and whether a socket is available
2002+
for reading or writing.
20032003

20042004
* In *timeout mode*, operations fail if they cannot be completed within the
20052005
timeout specified for the socket (they raise a :exc:`timeout` exception)
@@ -2188,7 +2188,7 @@ manager protocol instead, open a socket with::
21882188
socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM)
21892189

21902190
After binding (:const:`CAN_RAW`) or connecting (:const:`CAN_BCM`) the socket, you
2191-
can use the :meth:`socket.send`, and the :meth:`socket.recv` operations (and
2191+
can use the :meth:`socket.send` and :meth:`socket.recv` operations (and
21922192
their counterparts) on the socket object as usual.
21932193

21942194
This last example might require special privileges::

‎Doc/library/test.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1691,6 +1691,21 @@ The :mod:`test.support.warnings_helper` module provides support for warnings tes
16911691
.. versionadded:: 3.10
16921692

16931693

1694+
.. function:: ignore_warnings(*, category)
1695+
1696+
Suppress warnings that are instances of *category*,
1697+
which must be :exc:`Warning` or a subclass.
1698+
Roughly equivalent to :func:`warnings.catch_warnings`
1699+
with :meth:`warnings.simplefilter('ignore', category=category) <warnings.simplefilter>`.
1700+
For example::
1701+
1702+
@warning_helper.ignore_warnings(category=DeprecationWarning)
1703+
def test_suppress_warning():
1704+
# do something
1705+
1706+
.. versionadded:: 3.8
1707+
1708+
16941709
.. function:: check_no_resource_warning(testcase)
16951710

16961711
Context manager to check that no :exc:`ResourceWarning` was raised. You

‎Doc/library/typing.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1598,6 +1598,15 @@ These are not used in annotations. They are building blocks for creating generic
15981598
import threading
15991599
assert isinstance(threading.Thread(name='Bob'), Named)
16001600

1601+
.. versionchanged:: 3.12
1602+
The internal implementation of :func:`isinstance` checks against
1603+
runtime-checkable protocols now uses :func:`inspect.getattr_static`
1604+
to look up attributes (previously, :func:`hasattr` was used).
1605+
As a result, some objects which used to be considered instances
1606+
of a runtime-checkable protocol may no longer be considered instances
1607+
of that protocol on Python 3.12+, and vice versa.
1608+
Most users are unlikely to be affected by this change.
1609+
16011610
.. note::
16021611

16031612
:func:`!runtime_checkable` will check only the presence of the required

‎Doc/library/unittest.rst‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -244,6 +244,10 @@ Command-line options
244244

245245
Show local variables in tracebacks.
246246

247+
.. cmdoption:: --durations N
248+
249+
Show the N slowest test cases (N=0 for all).
250+
247251
.. versionadded:: 3.2
248252
The command-line options ``-b``, ``-c`` and ``-f`` were added.
249253

@@ -253,10 +257,12 @@ Command-line options
253257
.. versionadded:: 3.7
254258
The command-line option ``-k``.
255259

260+
.. versionadded:: 3.12
261+
The command-line option ``--durations``.
262+
256263
The command line can also be used for test discovery, for running all of the
257264
tests in a project or just a subset.
258265

259-
260266
.. _unittest-test-discovery:
261267

262268
Test Discovery
@@ -2009,6 +2015,13 @@ Loading and running tests
20092015
A list containing :class:`TestCase` instances that were marked as expected
20102016
failures, but succeeded.
20112017

2018+
.. attribute:: collectedDurations
2019+
2020+
A list containing 2-tuples of :class:`TestCase` instances and floats
2021+
representing the elapsed time of each test which was run.
2022+
2023+
.. versionadded:: 3.12
2024+
20122025
.. attribute:: shouldStop
20132026

20142027
Set to ``True`` when the execution of tests should stop by :meth:`stop`.
@@ -2160,14 +2173,27 @@ Loading and running tests
21602173

21612174
.. versionadded:: 3.4
21622175

2176+
.. method:: addDuration(test, elapsed)
2177+
2178+
Called when the test case finishes. *elapsed* is the time represented in
2179+
seconds, and it includes the execution of cleanup functions.
2180+
2181+
.. versionadded:: 3.12
21632182

2164-
.. class:: TextTestResult(stream, descriptions, verbosity)
2183+
.. class:: TextTestResult(stream, descriptions, verbosity, *, durations=None)
21652184

21662185
A concrete implementation of :class:`TestResult` used by the
2167-
:class:`TextTestRunner`.
2186+
:class:`TextTestRunner`. Subclasses should accept ``**kwargs`` to ensure
2187+
compatibility as the interface changes.
21682188

21692189
.. versionadded:: 3.2
21702190

2191+
.. versionadded:: 3.12
2192+
Added *durations* keyword argument.
2193+
2194+
.. versionchanged:: 3.12
2195+
Subclasses should accept ``**kwargs`` to ensure compatibility as the
2196+
interface changes.
21712197

21722198
.. data:: defaultTestLoader
21732199

@@ -2177,7 +2203,8 @@ Loading and running tests
21772203

21782204

21792205
.. class:: TextTestRunner(stream=None, descriptions=True, verbosity=1, failfast=False, \
2180-
buffer=False, resultclass=None, warnings=None, *, tb_locals=False)
2206+
buffer=False, resultclass=None, warnings=None, *, \
2207+
tb_locals=False, durations=None)
21812208
21822209
A basic test runner implementation that outputs results to a stream. If *stream*
21832210
is ``None``, the default, :data:`sys.stderr` is used as the output stream. This class
@@ -2195,14 +2222,17 @@ Loading and running tests
21952222
*warnings* to ``None``.
21962223

21972224
.. versionchanged:: 3.2
2198-
Added the ``warnings`` argument.
2225+
Added the *warnings* parameter.
21992226

22002227
.. versionchanged:: 3.2
22012228
The default stream is set to :data:`sys.stderr` at instantiation time rather
22022229
than import time.
22032230

22042231
.. versionchanged:: 3.5
2205-
Added the tb_locals parameter.
2232+
Added the *tb_locals* parameter.
2233+
2234+
.. versionchanged:: 3.12
2235+
Added the *durations* parameter.
22062236

22072237
.. method:: _makeResult()
22082238

‎Doc/reference/datamodel.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -991,7 +991,8 @@ Internal types
991991
the filename from which the code was compiled; :attr:`co_firstlineno` is
992992
the first line number of the function; :attr:`co_lnotab` is a string
993993
encoding the mapping from bytecode offsets to line numbers (for details
994-
see the source code of the interpreter); :attr:`co_stacksize` is the
994+
see the source code of the interpreter, is deprecated since 3.12
995+
and may be removed in 3.14); :attr:`co_stacksize` is the
995996
required stack size; :attr:`co_flags` is an integer encoding a number
996997
of flags for the interpreter.
997998

0 commit comments

Comments
 (0)