[pull] main from python:main

Doc/c-api/extension-modules.rst

@@ -29,7 +29,7 @@ and must be named after the module name plus an extension listed in
 Extension export hook
 .....................
 
-.. versionadded:: next
+.. versionadded:: 3.15
 
    Support for the :samp:`PyModExport_{<name>}` export hook was added in Python
    3.15. The older way of defining modules is still available: consult either
@@ -191,7 +191,7 @@ the :c:data:`Py_mod_multiple_interpreters` slot.
 ``PyInit`` function
 ...................
 
-.. deprecated:: next
+.. deprecated:: 3.15
 
    This functionality is :term:`soft deprecated`.
    It will not get new features, but there are no plans to remove it.
@@ -272,7 +272,7 @@ For example, a module called ``spam`` would be defined like this::
 Legacy single-phase initialization
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. deprecated:: next
+.. deprecated:: 3.15
 
    Single-phase initialization is :term:`soft deprecated`.
    It is a legacy mechanism to initialize extension

Doc/c-api/module.rst

@@ -142,7 +142,7 @@ Modules created using the C API are typically defined using an
 array of :dfn:`slots`.
 The slots provide a "description" of how a module should be created.
 
-.. versionchanged:: next
+.. versionchanged:: 3.15
 
    Previously, a :c:type:`PyModuleDef` struct was necessary to define modules.
    The older way of defining modules is still available: consult either the
@@ -190,7 +190,7 @@ Metadata slots
    However, it is still recommended to include this slot for introspection
    and debugging purposes.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
       Use :c:member:`PyModuleDef.m_name` instead to support previous versions.
 
@@ -201,7 +201,7 @@ Metadata slots
 
    Usually it is set to a variable created with :c:macro:`PyDoc_STRVAR`.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
       Use :c:member:`PyModuleDef.m_doc` instead to support previous versions.
 
@@ -332,7 +332,7 @@ Creation and initialization slots
 
    .. versionadded:: 3.5
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
 
       The *slots* argument may be a ``ModuleSpec``-like object, rather than
       a true :py:class:`~importlib.machinery.ModuleSpec` instance.
@@ -365,7 +365,7 @@ Creation and initialization slots
 
    .. versionadded:: 3.5
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
 
       Repeated ``Py_mod_exec`` slots are disallowed, except in
       :c:type:`PyModuleDef.m_slots`.
@@ -384,7 +384,7 @@ Creation and initialization slots
    The table must be statically allocated (or otherwise guaranteed to outlive
    the module object).
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
       Use :c:member:`PyModuleDef.m_methods` instead to support previous versions.
 
@@ -434,7 +434,7 @@ To retrieve the state from a given module, use the following functions:
 
    On error, set *\*result* to -1, and return -1 with an exception set.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 
 
@@ -459,7 +459,7 @@ defining the module state.
 
    Use :c:func:`PyModule_GetStateSize` to retrieve the size of a given module.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
       Use :c:member:`PyModuleDef.m_size` instead to support previous versions.
 
@@ -482,7 +482,7 @@ defining the module state.
    (:c:data:`Py_mod_state_size`) is greater than 0 and the module state
    (as returned by :c:func:`PyModule_GetState`) is ``NULL``.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
       Use :c:member:`PyModuleDef.m_size` instead to support previous versions.
 
@@ -510,7 +510,7 @@ defining the module state.
    the cyclic garbage collector is not involved and
    the :c:macro:`Py_mod_state_free` function is called directly.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
       Use :c:member:`PyModuleDef.m_clear` instead to support previous versions.
 
@@ -532,7 +532,7 @@ defining the module state.
    (:c:data:`Py_mod_state_size`) is greater than 0 and the module state
    (as returned by :c:func:`PyModule_GetState`) is ``NULL``.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
       Use :c:member:`PyModuleDef.m_free` instead to support previous versions.
 
@@ -593,15 +593,15 @@ A module's token -- and the *your_token* value to use in the above code -- is:
    This means that :c:macro:`!Py_mod_token` cannot be used in
    :c:member:`PyModuleDef.m_slots`.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 .. c:function:: int PyModule_GetToken(PyObject *module, void** result)
 
    Set *\*result* to the module's token and return 0.
 
    On error, set *\*result* to NULL, and return -1 with an exception set.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 See also :c:func:`PyType_GetModuleByToken`.
 
@@ -641,7 +641,7 @@ rather than from an extension's :ref:`export hook <extension-export-hook>`.
    :c:func:`!PyModule_FromSlotsAndSpec` call.
    In particular, it may be heap-allocated.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 .. c:function:: int PyModule_Exec(PyObject *module)
 
@@ -654,7 +654,7 @@ rather than from an extension's :ref:`export hook <extension-export-hook>`.
    :ref:`legacy single-phase initialization <single-phase-initialization>`,
    this function does nothing and returns 0.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 
 

Doc/c-api/object.rst

@@ -111,7 +111,7 @@ Object Protocol
        object type name: str
        object repr     : 'abcdef'
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 
 .. c:function:: int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)

Doc/c-api/tuple.rst

@@ -148,8 +148,11 @@ Tuple Objects
 Struct Sequence Objects
 -----------------------
 
-Struct sequence objects are the C equivalent of :func:`~collections.namedtuple`
-objects, i.e. a sequence whose items can also be accessed through attributes.
+A struct sequence object is a :term:`named tuple`, that is, a sequence
+whose items can also be accessed through attributes.
+It is similar to :func:`collections.namedtuple`, but provides a slightly
+different interface.
+
 To create a struct sequence, you first have to create a specific struct sequence
 type.
 

Doc/c-api/type.rst

@@ -317,7 +317,7 @@ Type Objects
    and other places where a method's defining class cannot be passed using the
    :c:type:`PyCMethod` calling convention.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 
 .. c:function:: PyObject* PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)

Doc/deprecations/pending-removal-in-3.20.rst

@@ -23,6 +23,7 @@ Pending removal in Python 3.20
   - :mod:`tabnanny`
   - :mod:`tkinter.font`
   - :mod:`tkinter.ttk`
+  - :mod:`wsgiref.simple_server`
   - :mod:`zlib`
 
   (Contributed by Hugo van Kemenade and Stan Ulbrych in :gh:`76007`.)

Doc/glossary.rst

@@ -813,7 +813,7 @@ Glossary
       :func:`itertools.groupby`.
 
       There are several ways to create a key function.  For example. the
-      :meth:`str.lower` method can serve as a key function for case insensitive
+      :meth:`str.casefold` method can serve as a key function for case insensitive
       sorts.  Alternatively, a key function can be built from a
       :keyword:`lambda` expression such as ``lambda r: (r[0], r[2])``.  Also,
       :func:`operator.attrgetter`, :func:`operator.itemgetter`, and

Doc/library/argparse.rst

@@ -1370,7 +1370,7 @@ behavior::
    >>> parser.parse_args('--foo XXX'.split())
    Namespace(bar='XXX')
 
-.. versionchanged:: next
+.. versionchanged:: 3.15
    Single-dash long option now takes precedence over short options.
 
 
@@ -1473,7 +1473,7 @@ this API may be passed as the ``action`` parameter to
 
    .. versionadded:: 3.9
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Added support for single-dash options.
 
       Added support for alternate prefix_chars_.

Doc/library/decimal.rst

@@ -34,10 +34,12 @@ The :mod:`decimal` module provides support for fast correctly rounded
 decimal floating-point arithmetic. It offers several advantages over the
 :class:`float` datatype:
 
-* Decimal "is based on a floating-point model which was designed with people
-  in mind, and necessarily has a paramount guiding principle -- computers must
-  provide an arithmetic that works in the same way as the arithmetic that
-  people learn at school." -- excerpt from the decimal arithmetic specification.
+* Decimal "is based on a `floating-point model
+  <https://speleotrove.com/decimal/damodel.html#refnumber>`__ which was designed
+  with people in mind, and necessarily has a paramount guiding principle --
+  computers must provide an arithmetic that works in the same way as the
+  arithmetic that people learn at school." -- excerpt from the decimal
+  arithmetic specification.
 
 * Decimal numbers can be represented exactly.  In contrast, numbers like
   ``1.1`` and ``2.2`` do not have exact representations in binary
@@ -238,6 +240,26 @@ floating-point flying circus:
    >>> c % a
    Decimal('0.77')
 
+Decimals can be formatted (with :func:`format` built-in or :ref:`f-strings`) in
+fixed-point or scientific notation, using the same formatting syntax (see
+:ref:`formatspec`) as builtin :class:`float` type:
+
+.. doctest::
+
+   >>> format(Decimal('2.675'), "f")
+   '2.675'
+   >>> format(Decimal('2.675'), ".2f")
+   '2.68'
+   >>> f"{Decimal('2.675'):.2f}"
+   '2.68'
+   >>> format(Decimal('2.675'), ".2e")
+   '2.68e+0'
+   >>> with localcontext() as ctx:
+   ...     ctx.rounding = ROUND_DOWN
+   ...     print(format(Decimal('2.675'), ".2f"))
+   ...
+   2.67
+
 And some mathematical functions are also available to Decimal:
 
    >>> getcontext().prec = 28

Doc/library/exceptions.rst

@@ -742,8 +742,8 @@ depending on the system error code.
 
    .. attribute:: characters_written
 
-      An integer containing the number of characters written to the stream
-      before it blocked.  This attribute is available when using the
+      An integer containing the number of **bytes** written to the stream
+      before it blocked. This attribute is available when using the
       buffered I/O classes from the :mod:`io` module.
 
 .. exception:: ChildProcessError

Doc/library/gc.rst

@@ -118,7 +118,7 @@ The :mod:`gc` module provides the following functions:
 
    .. versionadded:: 3.4
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Add ``duration`` and ``candidates``.
 
 
@@ -340,7 +340,7 @@ values but should not rebind them):
 
    .. versionadded:: 3.3
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Add "duration" and "candidates".
 
 

Doc/library/importlib.rst

@@ -210,7 +210,7 @@ Functions
        :exc:`ModuleNotFoundError` is raised when the module being reloaded lacks
        a :class:`~importlib.machinery.ModuleSpec`.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
        If *module* is a lazy module that has not yet been materialized (i.e.,
        loaded via :class:`importlib.util.LazyLoader` and not yet accessed),
        calling :func:`reload` is a no-op and returns the module unchanged.

Doc/library/locale.rst

@@ -48,8 +48,19 @@ The :mod:`locale` module defines the following exception and functions:
    If *locale* is omitted or ``None``, the current setting for *category* is
    returned.
 
+   Example::
+
+      >>> import locale
+      >>> loc = locale.setlocale(locale.LC_ALL)  # get current locale
+      # use German locale; name and availability varies with platform
+      >>> locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8')
+      >>> locale.strcoll('f\xe4n', 'foo')  # compare a string containing an umlaut
+      >>> locale.setlocale(locale.LC_ALL, '')   # use user's preferred locale
+      >>> locale.setlocale(locale.LC_ALL, 'C')  # use default (C) locale
+      >>> locale.setlocale(locale.LC_ALL, loc)  # restore saved locale
+
    :func:`setlocale` is not thread-safe on most systems. Applications typically
-   start with a call of ::
+   start with a call of::
 
       import locale
       locale.setlocale(locale.LC_ALL, '')
@@ -580,18 +591,6 @@ The :mod:`locale` module defines the following exception and functions:
    :func:`localeconv`.
 
 
-Example::
-
-   >>> import locale
-   >>> loc = locale.getlocale()  # get current locale
-   # use German locale; name might vary with platform
-   >>> locale.setlocale(locale.LC_ALL, 'de_DE')
-   >>> locale.strcoll('f\xe4n', 'foo')  # compare a string containing an umlaut
-   >>> locale.setlocale(locale.LC_ALL, '')   # use user's preferred locale
-   >>> locale.setlocale(locale.LC_ALL, 'C')  # use default (C) locale
-   >>> locale.setlocale(locale.LC_ALL, loc)  # restore saved locale
-
-
 Background, details, hints, tips and caveats
 --------------------------------------------