Skip to content

Commit 500b483

Browse files
encukouencukou
committed
Merge in the main branch
2 parents bf4086c + 6c48ed7 commit 500b483

File tree

105 files changed

+4113
-3393
lines changed

Some content is hidden

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

105 files changed

+4113
-3393
lines changed

‎Doc/c-api/arg.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
Parsing arguments and building values
66
=====================================
77

8-
These functions are useful when creating your own extensions functions and
8+
These functions are useful when creating your own extension functions and
99
methods. Additional information and examples are available in
1010
:ref:`extending-index`.
1111

‎Doc/c-api/structures.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,11 @@ under :ref:`reference counting <countingrefs>`.
6363
See documentation of :c:type:`PyVarObject` above.
6464

6565

66+
.. c:var:: PyTypeObject PyBaseObject_Type
67+
68+
The base class of all other objects, the same as :class:`object` in Python.
69+
70+
6671
.. c:function:: int Py_Is(PyObject *x, PyObject *y)
6772
6873
Test if the *x* object is the *y* object, the same as ``x is y`` in Python.

‎Doc/library/collections.rst‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -748,8 +748,8 @@ stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
748748
returns or raises is then returned or raised by :meth:`~object.__getitem__`.
749749

750750
Note that :meth:`__missing__` is *not* called for any operations besides
751-
:meth:`~object.__getitem__`. This means that :meth:`get` will, like normal
752-
dictionaries, return ``None`` as a default rather than using
751+
:meth:`~object.__getitem__`. This means that :meth:`~dict.get` will, like
752+
normal dictionaries, return ``None`` as a default rather than using
753753
:attr:`default_factory`.
754754

755755

@@ -849,8 +849,9 @@ they add the ability to access fields by name instead of position index.
849849
Returns a new tuple subclass named *typename*. The new subclass is used to
850850
create tuple-like objects that have fields accessible by attribute lookup as
851851
well as being indexable and iterable. Instances of the subclass also have a
852-
helpful docstring (with typename and field_names) and a helpful :meth:`__repr__`
853-
method which lists the tuple contents in a ``name=value`` format.
852+
helpful docstring (with *typename* and *field_names*) and a helpful
853+
:meth:`~object.__repr__` method which lists the tuple contents in a ``name=value``
854+
format.
854855

855856
The *field_names* are a sequence of strings such as ``['x', 'y']``.
856857
Alternatively, *field_names* can be a single string with each fieldname
@@ -894,10 +895,10 @@ they add the ability to access fields by name instead of position index.
894895
Added the *module* parameter.
895896

896897
.. versionchanged:: 3.7
897-
Removed the *verbose* parameter and the :attr:`_source` attribute.
898+
Removed the *verbose* parameter and the :attr:`!_source` attribute.
898899

899900
.. versionchanged:: 3.7
900-
Added the *defaults* parameter and the :attr:`_field_defaults`
901+
Added the *defaults* parameter and the :attr:`~somenamedtuple._field_defaults`
901902
attribute.
902903

903904
.. doctest::
@@ -1109,7 +1110,7 @@ Some differences from :class:`dict` still remain:
11091110
A regular :class:`dict` can emulate the order sensitive equality test with
11101111
``p == q and all(k1 == k2 for k1, k2 in zip(p, q))``.
11111112

1112-
* The :meth:`popitem` method of :class:`OrderedDict` has a different
1113+
* The :meth:`~OrderedDict.popitem` method of :class:`OrderedDict` has a different
11131114
signature. It accepts an optional argument to specify which item is popped.
11141115

11151116
A regular :class:`dict` can emulate OrderedDict's ``od.popitem(last=True)``
@@ -1119,7 +1120,7 @@ Some differences from :class:`dict` still remain:
11191120
with ``(k := next(iter(d)), d.pop(k))`` which will return and remove the
11201121
leftmost (first) item if it exists.
11211122

1122-
* :class:`OrderedDict` has a :meth:`move_to_end` method to efficiently
1123+
* :class:`OrderedDict` has a :meth:`~OrderedDict.move_to_end` method to efficiently
11231124
reposition an element to an endpoint.
11241125

11251126
A regular :class:`dict` can emulate OrderedDict's ``od.move_to_end(k,
@@ -1130,7 +1131,7 @@ Some differences from :class:`dict` still remain:
11301131
OrderedDict's ``od.move_to_end(k, last=False)`` which moves the key
11311132
and its associated value to the leftmost (first) position.
11321133

1133-
* Until Python 3.8, :class:`dict` lacked a :meth:`__reversed__` method.
1134+
* Until Python 3.8, :class:`dict` lacked a :meth:`~object.__reversed__` method.
11341135

11351136

11361137
.. class:: OrderedDict([items])
@@ -1185,7 +1186,7 @@ anywhere a regular dictionary is used.
11851186

11861187
.. versionchanged:: 3.6
11871188
With the acceptance of :pep:`468`, order is retained for keyword arguments
1188-
passed to the :class:`OrderedDict` constructor and its :meth:`update`
1189+
passed to the :class:`OrderedDict` constructor and its :meth:`~dict.update`
11891190
method.
11901191

11911192
.. versionchanged:: 3.9

‎Doc/library/concurrent.futures.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -415,6 +415,30 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
415415
require the *fork* start method for :class:`ProcessPoolExecutor` you must
416416
explicitly pass ``mp_context=multiprocessing.get_context("fork")``.
417417

418+
.. method:: terminate_workers()
419+
420+
Attempt to terminate all living worker processes immediately by calling
421+
:meth:`Process.terminate <multiprocessing.Process.terminate>` on each of them.
422+
Internally, it will also call :meth:`Executor.shutdown` to ensure that all
423+
other resources associated with the executor are freed.
424+
425+
After calling this method the caller should no longer submit tasks to the
426+
executor.
427+
428+
.. versionadded:: next
429+
430+
.. method:: kill_workers()
431+
432+
Attempt to kill all living worker processes immediately by calling
433+
:meth:`Process.kill <multiprocessing.Process.kill>` on each of them.
434+
Internally, it will also call :meth:`Executor.shutdown` to ensure that all
435+
other resources associated with the executor are freed.
436+
437+
After calling this method the caller should no longer submit tasks to the
438+
executor.
439+
440+
.. versionadded:: next
441+
418442
.. _processpoolexecutor-example:
419443

420444
ProcessPoolExecutor Example

‎Doc/library/constants.rst‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -46,11 +46,12 @@ A small number of constants live in the built-in namespace. They are:
4646

4747
See :ref:`implementing-the-arithmetic-operations` for examples.
4848

49-
.. note::
49+
.. caution::
5050

51-
``NotImplementedError`` and :data:`!NotImplemented` are not interchangeable,
52-
even though they have similar names and purposes.
53-
See :exc:`NotImplementedError` for details on when to use it.
51+
:data:`!NotImplemented` and :exc:`!NotImplementedError` are not
52+
interchangeable. This constant should only be used as described
53+
above; see :exc:`NotImplementedError` for details on correct usage
54+
of the exception.
5455

5556
.. versionchanged:: 3.9
5657
Evaluating :data:`!NotImplemented` in a boolean context was deprecated.

‎Doc/library/email.errors.rst‎

Lines changed: 55 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -77,51 +77,72 @@ object would have a defect, but the containing messages would not.
7777

7878
All defect classes are subclassed from :class:`email.errors.MessageDefect`.
7979

80-
* :class:`NoBoundaryInMultipartDefect` -- A message claimed to be a multipart,
81-
but had no :mimetype:`boundary` parameter.
80+
.. exception:: NoBoundaryInMultipartDefect
8281

83-
* :class:`StartBoundaryNotFoundDefect` -- The start boundary claimed in the
84-
:mailheader:`Content-Type` header was never found.
82+
A message claimed to be a multipart, but had no :mimetype:`boundary`
83+
parameter.
8584

86-
* :class:`CloseBoundaryNotFoundDefect` -- A start boundary was found, but
87-
no corresponding close boundary was ever found.
85+
.. exception:: StartBoundaryNotFoundDefect
8886

89-
.. versionadded:: 3.3
87+
The start boundary claimed in the :mailheader:`Content-Type` header was
88+
never found.
9089

91-
* :class:`FirstHeaderLineIsContinuationDefect` -- The message had a continuation
92-
line as its first header line.
90+
.. exception:: CloseBoundaryNotFoundDefect
9391

94-
* :class:`MisplacedEnvelopeHeaderDefect` - A "Unix From" header was found in the
95-
middle of a header block.
92+
A start boundary was found, but no corresponding close boundary was ever
93+
found.
9694

97-
* :class:`MissingHeaderBodySeparatorDefect` - A line was found while parsing
98-
headers that had no leading white space but contained no ':'. Parsing
99-
continues assuming that the line represents the first line of the body.
95+
.. versionadded:: 3.3
10096

101-
.. versionadded:: 3.3
97+
.. exception:: FirstHeaderLineIsContinuationDefect
10298

103-
* :class:`MalformedHeaderDefect` -- A header was found that was missing a colon,
104-
or was otherwise malformed.
99+
The message had a continuation line as its first header line.
105100

106-
.. deprecated:: 3.3
107-
This defect has not been used for several Python versions.
101+
.. exception:: MisplacedEnvelopeHeaderDefect
108102

109-
* :class:`MultipartInvariantViolationDefect` -- A message claimed to be a
110-
:mimetype:`multipart`, but no subparts were found. Note that when a message
111-
has this defect, its :meth:`~email.message.Message.is_multipart` method may
112-
return ``False`` even though its content type claims to be :mimetype:`multipart`.
103+
A "Unix From" header was found in the middle of a header block.
113104

114-
* :class:`InvalidBase64PaddingDefect` -- When decoding a block of base64
115-
encoded bytes, the padding was not correct. Enough padding is added to
116-
perform the decode, but the resulting decoded bytes may be invalid.
105+
.. exception:: MissingHeaderBodySeparatorDefect
117106

118-
* :class:`InvalidBase64CharactersDefect` -- When decoding a block of base64
119-
encoded bytes, characters outside the base64 alphabet were encountered.
120-
The characters are ignored, but the resulting decoded bytes may be invalid.
107+
A line was found while parsing headers that had no leading white space but
108+
contained no ':'. Parsing continues assuming that the line represents the
109+
first line of the body.
121110

122-
* :class:`InvalidBase64LengthDefect` -- When decoding a block of base64 encoded
123-
bytes, the number of non-padding base64 characters was invalid (1 more than
124-
a multiple of 4). The encoded block was kept as-is.
111+
.. versionadded:: 3.3
125112

126-
* :class:`InvalidDateDefect` -- When decoding an invalid or unparsable date field.
127-
The original value is kept as-is.
113+
.. exception:: MalformedHeaderDefect
114+
115+
A header was found that was missing a colon, or was otherwise malformed.
116+
117+
.. deprecated:: 3.3
118+
This defect has not been used for several Python versions.
119+
120+
.. exception:: MultipartInvariantViolationDefect
121+
122+
A message claimed to be a :mimetype:`multipart`, but no subparts were found.
123+
Note that when a message has this defect, its
124+
:meth:`~email.message.Message.is_multipart` method may return ``False``
125+
even though its content type claims to be :mimetype:`multipart`.
126+
127+
.. exception:: InvalidBase64PaddingDefect
128+
129+
When decoding a block of base64 encoded bytes, the padding was not correct.
130+
Enough padding is added to perform the decode, but the resulting decoded
131+
bytes may be invalid.
132+
133+
.. exception:: InvalidBase64CharactersDefect
134+
135+
When decoding a block of base64 encoded bytes, characters outside the base64
136+
alphabet were encountered. The characters are ignored, but the resulting
137+
decoded bytes may be invalid.
138+
139+
.. exception:: InvalidBase64LengthDefect
140+
141+
When decoding a block of base64 encoded bytes, the number of non-padding
142+
base64 characters was invalid (1 more than a multiple of 4). The encoded
143+
block was kept as-is.
144+
145+
.. exception:: InvalidDateDefect
146+
147+
When decoding an invalid or unparsable date field. The original value is
148+
kept as-is.

‎Doc/library/exceptions.rst‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -333,11 +333,13 @@ The following exceptions are the exceptions that are usually raised.
333333
meant to be supported at all -- in that case either leave the operator /
334334
method undefined or, if a subclass, set it to :data:`None`.
335335

336-
.. note::
336+
.. caution::
337+
338+
:exc:`!NotImplementedError` and :data:`!NotImplemented` are not
339+
interchangeable. This exception should only be used as described
340+
above; see :data:`NotImplemented` for details on correct usage of
341+
the built-in constant.
337342

338-
``NotImplementedError`` and :data:`NotImplemented` are not interchangeable,
339-
even though they have similar names and purposes. See
340-
:data:`!NotImplemented` for details on when to use it.
341343

342344
.. exception:: OSError([arg])
343345
OSError(errno, strerror[, filename[, winerror[, filename2]]])

‎Doc/library/importlib.metadata.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -268,8 +268,9 @@ Distribution versions
268268

269269
.. function:: version(distribution_name)
270270

271-
Return the installed distribution package version for the named
272-
distribution package.
271+
Return the installed distribution package
272+
`version <https://packaging.python.org/en/latest/specifications/core-metadata/#version>`__
273+
for the named distribution package.
273274

274275
Raises :exc:`PackageNotFoundError` if the named distribution
275276
package is not installed in the current Python environment.

‎Doc/library/pathlib.rst‎

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1571,8 +1571,7 @@ Creating files and directories
15711571
Copying, moving and deleting
15721572
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15731573

1574-
.. method:: Path.copy(target, *, follow_symlinks=True, dirs_exist_ok=False, \
1575-
preserve_metadata=False)
1574+
.. method:: Path.copy(target, *, follow_symlinks=True, preserve_metadata=False)
15761575

15771576
Copy this file or directory tree to the given *target*, and return a new
15781577
:class:`!Path` instance pointing to *target*.
@@ -1582,12 +1581,6 @@ Copying, moving and deleting
15821581
default), the symlink's target is copied. Otherwise, the symlink is
15831582
recreated at the destination.
15841583

1585-
If the source is a directory and *dirs_exist_ok* is false (the default), a
1586-
:exc:`FileExistsError` is raised if the target is an existing directory.
1587-
If *dirs_exists_ok* is true, the copying operation will overwrite
1588-
existing files within the destination tree with corresponding files
1589-
from the source tree.
1590-
15911584
If *preserve_metadata* is false (the default), only directory structures
15921585
and file data are guaranteed to be copied. Set *preserve_metadata* to true
15931586
to ensure that file and directory permissions, flags, last access and
@@ -1604,7 +1597,7 @@ Copying, moving and deleting
16041597

16051598

16061599
.. method:: Path.copy_into(target_dir, *, follow_symlinks=True, \
1607-
dirs_exist_ok=False, preserve_metadata=False)
1600+
preserve_metadata=False)
16081601

16091602
Copy this file or directory tree into the given *target_dir*, which should
16101603
be an existing directory. Other arguments are handled identically to

‎Doc/library/profile.rst‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -123,23 +123,32 @@ them in various ways.
123123

124124
.. _profile-cli:
125125

126+
.. program:: cProfile
127+
126128
The files :mod:`cProfile` and :mod:`profile` can also be invoked as a script to
127129
profile another script. For example::
128130

129131
python -m cProfile [-o output_file] [-s sort_order] (-m module | myscript.py)
130132

131-
``-o`` writes the profile results to a file instead of to stdout
133+
.. option:: -o <output_file>
134+
135+
Writes the profile results to a file instead of to stdout.
136+
137+
.. option:: -s <sort_order>
138+
139+
Specifies one of the :func:`~pstats.Stats.sort_stats` sort values
140+
to sort the output by.
141+
This only applies when :option:`-o <cProfile -o>` is not supplied.
132142

133-
``-s`` specifies one of the :func:`~pstats.Stats.sort_stats` sort values to sort
134-
the output by. This only applies when ``-o`` is not supplied.
143+
.. option:: -m <module>
135144

136-
``-m`` specifies that a module is being profiled instead of a script.
145+
Specifies that a module is being profiled instead of a script.
137146

138-
.. versionadded:: 3.7
139-
Added the ``-m`` option to :mod:`cProfile`.
147+
.. versionadded:: 3.7
148+
Added the ``-m`` option to :mod:`cProfile`.
140149

141-
.. versionadded:: 3.8
142-
Added the ``-m`` option to :mod:`profile`.
150+
.. versionadded:: 3.8
151+
Added the ``-m`` option to :mod:`profile`.
143152

144153
The :mod:`pstats` module's :class:`~pstats.Stats` class has a variety of methods
145154
for manipulating and printing the data saved into a profile results file::

0 commit comments

Comments
 (0)