Skip to content

Commit

Permalink
Merge branch 'main' into pythongh-128520-local-module-move
Browse files Browse the repository at this point in the history
  • Loading branch information
barneygale authored Mar 3, 2025
2 parents 3e0ba6c + 8a64a62 commit 6f08092
Show file tree
Hide file tree
Showing 57 changed files with 2,429 additions and 1,306 deletions.
2 changes: 1 addition & 1 deletion Doc/c-api/arg.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
Parsing arguments and building values
=====================================

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

Expand Down
5 changes: 5 additions & 0 deletions Doc/c-api/structures.rst
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,11 @@ under :ref:`reference counting <countingrefs>`.
See documentation of :c:type:`PyVarObject` above.


.. c:var:: PyTypeObject PyBaseObject_Type
The base class of all other objects, the same as :class:`object` in Python.


.. c:function:: int Py_Is(PyObject *x, PyObject *y)
Test if the *x* object is the *y* object, the same as ``x is y`` in Python.
Expand Down
21 changes: 11 additions & 10 deletions Doc/library/collections.rst
Original file line number Diff line number Diff line change
Expand Up @@ -748,8 +748,8 @@ stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
returns or raises is then returned or raised by :meth:`~object.__getitem__`.

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


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

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

.. versionchanged:: 3.7
Removed the *verbose* parameter and the :attr:`_source` attribute.
Removed the *verbose* parameter and the :attr:`!_source` attribute.

.. versionchanged:: 3.7
Added the *defaults* parameter and the :attr:`_field_defaults`
Added the *defaults* parameter and the :attr:`~somenamedtuple._field_defaults`
attribute.

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

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

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

* :class:`OrderedDict` has a :meth:`move_to_end` method to efficiently
* :class:`OrderedDict` has a :meth:`~OrderedDict.move_to_end` method to efficiently
reposition an element to an endpoint.

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

* Until Python 3.8, :class:`dict` lacked a :meth:`__reversed__` method.
* Until Python 3.8, :class:`dict` lacked a :meth:`~object.__reversed__` method.


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

.. versionchanged:: 3.6
With the acceptance of :pep:`468`, order is retained for keyword arguments
passed to the :class:`OrderedDict` constructor and its :meth:`update`
passed to the :class:`OrderedDict` constructor and its :meth:`~dict.update`
method.

.. versionchanged:: 3.9
Expand Down
24 changes: 24 additions & 0 deletions Doc/library/concurrent.futures.rst
Original file line number Diff line number Diff line change
Expand Up @@ -415,6 +415,30 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
require the *fork* start method for :class:`ProcessPoolExecutor` you must
explicitly pass ``mp_context=multiprocessing.get_context("fork")``.

.. method:: terminate_workers()

Attempt to terminate all living worker processes immediately by calling
:meth:`Process.terminate <multiprocessing.Process.terminate>` on each of them.
Internally, it will also call :meth:`Executor.shutdown` to ensure that all
other resources associated with the executor are freed.

After calling this method the caller should no longer submit tasks to the
executor.

.. versionadded:: next

.. method:: kill_workers()

Attempt to kill all living worker processes immediately by calling
:meth:`Process.kill <multiprocessing.Process.kill>` on each of them.
Internally, it will also call :meth:`Executor.shutdown` to ensure that all
other resources associated with the executor are freed.

After calling this method the caller should no longer submit tasks to the
executor.

.. versionadded:: next

.. _processpoolexecutor-example:

ProcessPoolExecutor Example
Expand Down
9 changes: 5 additions & 4 deletions Doc/library/constants.rst
Original file line number Diff line number Diff line change
Expand Up @@ -46,11 +46,12 @@ A small number of constants live in the built-in namespace. They are:

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

.. note::
.. caution::

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

.. versionchanged:: 3.9
Evaluating :data:`!NotImplemented` in a boolean context was deprecated.
Expand Down
89 changes: 55 additions & 34 deletions Doc/library/email.errors.rst
Original file line number Diff line number Diff line change
Expand Up @@ -77,51 +77,72 @@ object would have a defect, but the containing messages would not.

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

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

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

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

.. versionadded:: 3.3
The start boundary claimed in the :mailheader:`Content-Type` header was
never found.

* :class:`FirstHeaderLineIsContinuationDefect` -- The message had a continuation
line as its first header line.
.. exception:: CloseBoundaryNotFoundDefect

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

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

.. versionadded:: 3.3
.. exception:: FirstHeaderLineIsContinuationDefect

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

.. deprecated:: 3.3
This defect has not been used for several Python versions.
.. exception:: MisplacedEnvelopeHeaderDefect

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

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

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

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

* :class:`InvalidDateDefect` -- When decoding an invalid or unparsable date field.
The original value is kept as-is.
.. exception:: MalformedHeaderDefect

A header was found that was missing a colon, or was otherwise malformed.

.. deprecated:: 3.3
This defect has not been used for several Python versions.

.. exception:: MultipartInvariantViolationDefect

A message claimed to be a :mimetype:`multipart`, but no subparts were found.
Note that when a message has this defect, its
:meth:`~email.message.Message.is_multipart` method may return ``False``
even though its content type claims to be :mimetype:`multipart`.

.. exception:: InvalidBase64PaddingDefect

When decoding a block of base64 encoded bytes, the padding was not correct.
Enough padding is added to perform the decode, but the resulting decoded
bytes may be invalid.

.. exception:: InvalidBase64CharactersDefect

When decoding a block of base64 encoded bytes, characters outside the base64
alphabet were encountered. The characters are ignored, but the resulting
decoded bytes may be invalid.

.. exception:: InvalidBase64LengthDefect

When decoding a block of base64 encoded bytes, the number of non-padding
base64 characters was invalid (1 more than a multiple of 4). The encoded
block was kept as-is.

.. exception:: InvalidDateDefect

When decoding an invalid or unparsable date field. The original value is
kept as-is.
10 changes: 6 additions & 4 deletions Doc/library/exceptions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -333,11 +333,13 @@ The following exceptions are the exceptions that are usually raised.
meant to be supported at all -- in that case either leave the operator /
method undefined or, if a subclass, set it to :data:`None`.

.. note::
.. caution::

:exc:`!NotImplementedError` and :data:`!NotImplemented` are not
interchangeable. This exception should only be used as described
above; see :data:`NotImplemented` for details on correct usage of
the built-in constant.

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

.. exception:: OSError([arg])
OSError(errno, strerror[, filename[, winerror[, filename2]]])
Expand Down
5 changes: 3 additions & 2 deletions Doc/library/importlib.metadata.rst
Original file line number Diff line number Diff line change
Expand Up @@ -268,8 +268,9 @@ Distribution versions

.. function:: version(distribution_name)

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

Raises :exc:`PackageNotFoundError` if the named distribution
package is not installed in the current Python environment.
Expand Down
23 changes: 22 additions & 1 deletion Doc/library/traceback.rst
Original file line number Diff line number Diff line change
Expand Up @@ -508,7 +508,9 @@ the module-level functions described above.
A :class:`!FrameSummary` object represents a single :ref:`frame <frame-objects>`
in a :ref:`traceback <traceback-objects>`.

.. class:: FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)
.. class:: FrameSummary(filename, lineno, name, *,\
lookup_line=True, locals=None,\
line=None, end_lineno=None, colno=None, end_colno=None)

Represents a single :ref:`frame <frame-objects>` in the
:ref:`traceback <traceback-objects>` or stack that is being formatted
Expand Down Expand Up @@ -544,6 +546,25 @@ in a :ref:`traceback <traceback-objects>`.
trailing whitespace stripped.
If the source is not available, it is ``None``.

.. attribute:: FrameSummary.end_lineno

The last line number of the source code for this frame.
By default, it is set to ``lineno`` and indexation starts from 1.

.. versionchanged:: 3.13
The default value changed from ``None`` to ``lineno``.

.. attribute:: FrameSummary.colno

The column number of the source code for this frame.
By default, it is ``None`` and indexation starts from 0.

.. attribute:: FrameSummary.end_colno

The last column number of the source code for this frame.
By default, it is ``None`` and indexation starts from 0.


.. _traceback-example:

Examples of Using the Module-Level Functions
Expand Down
30 changes: 23 additions & 7 deletions Doc/library/uuid.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@

This module provides immutable :class:`UUID` objects (the :class:`UUID` class)
and the functions :func:`uuid1`, :func:`uuid3`, :func:`uuid4`, :func:`uuid5`,
and :func:`uuid.uuid8` for generating version 1, 3, 4, 5, and 8 UUIDs as
specified in :rfc:`9562` (which supersedes :rfc:`4122`).
:func:`uuid6`, and :func:`uuid8` for generating version 1, 3, 4, 5, 6,
and 8 UUIDs as specified in :rfc:`9562` (which supersedes :rfc:`4122`).

If all you want is a unique ID, you should probably call :func:`uuid1` or
:func:`uuid4`. Note that :func:`uuid1` may compromise privacy since it creates
Expand Down Expand Up @@ -153,8 +153,8 @@ which relays any information about the UUID's safety, using this enumeration:
The UUID version number (1 through 8, meaningful only when the variant is
:const:`RFC_4122`).

.. versionchanged:: 3.14
Added UUID version 8.
.. versionchanged:: next
Added UUID versions 6 and 8.


.. attribute:: UUID.is_safe
Expand Down Expand Up @@ -212,6 +212,22 @@ The :mod:`uuid` module defines the following functions:
that will be encoded using UTF-8).


.. function:: uuid6(node=None, clock_seq=None)

Generate a UUID from a sequence number and the current time according to
:rfc:`9562`.
This is an alternative to :func:`uuid1` to improve database locality.

When *node* is not specified, :func:`getnode` is used to obtain the hardware
address as a 48-bit positive integer. When a sequence number *clock_seq* is
not specified, a pseudo-random 14-bit positive integer is generated.

If *node* or *clock_seq* exceed their expected bit count, only their least
significant bits are kept.

.. versionadded:: next


.. function:: uuid8(a=None, b=None, c=None)

Generate a pseudo-random UUID according to
Expand Down Expand Up @@ -314,7 +330,7 @@ The :mod:`uuid` module can be executed as a script from the command line.

.. code-block:: sh
python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid8}] [-n NAMESPACE] [-N NAME]
python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid6,uuid8}] [-n NAMESPACE] [-N NAME]
The following options are accepted:

Expand All @@ -330,8 +346,8 @@ The following options are accepted:
Specify the function name to use to generate the uuid. By default :func:`uuid4`
is used.

.. versionadded:: 3.14
Allow generating UUID version 8.
.. versionchanged:: next
Allow generating UUID versions 6 and 8.

.. option:: -n <namespace>
--namespace <namespace>
Expand Down
2 changes: 0 additions & 2 deletions Doc/tools/.nitignore
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,9 @@ Doc/extending/extending.rst
Doc/library/ast.rst
Doc/library/asyncio-extending.rst
Doc/library/asyncio-subprocess.rst
Doc/library/collections.rst
Doc/library/decimal.rst
Doc/library/email.charset.rst
Doc/library/email.compat32-message.rst
Doc/library/email.errors.rst
Doc/library/email.parser.rst
Doc/library/exceptions.rst
Doc/library/functools.rst
Expand Down
Loading

0 comments on commit 6f08092

Please sign in to comment.