Merge remote-tracking branch 'upstream/main' into 3.14-calendar-colour

Author: hugovk

.github/workflows/build.yml

@@ -46,7 +46,7 @@ jobs:
     # reproducible: to get the same tools versions (autoconf, aclocal, ...)
     runs-on: ubuntu-24.04
     container:
-      image: ghcr.io/python/autoconf:2024.11.11.11786316759
+      image: ghcr.io/python/autoconf:2025.01.02.12581854023
     timeout-minutes: 60
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true'
@@ -63,7 +63,7 @@ jobs:
         run: echo "IMAGE_VERSION=${ImageVersion}" >> "$GITHUB_ENV"
       - name: Check Autoconf and aclocal versions
         run: |
-          grep "Generated by GNU Autoconf 2.71" configure
+          grep "Generated by GNU Autoconf 2.72" configure
           grep "aclocal 1.16.5" aclocal.m4
           grep -q "runstatedir" configure
           grep -q "PKG_PROG_PKG_CONFIG" aclocal.m4

Doc/about.rst

@@ -1,10 +1,11 @@
-=====================
-About these documents
-=====================
+========================
+About this documentation
+========================
 
 
-These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
-document processor specifically written for the Python documentation.
+Python's documentation is generated from `reStructuredText`_ sources
+using `Sphinx`_, a documentation generator originally created for Python
+and now maintained as an independent project.
 
 .. _reStructuredText: https://docutils.sourceforge.io/rst.html
 .. _Sphinx: https://www.sphinx-doc.org/
@@ -20,14 +21,14 @@ volunteers are always welcome!
 Many thanks go to:
 
 * Fred L. Drake, Jr., the creator of the original Python documentation toolset
-  and writer of much of the content;
+  and author of much of the content;
 * the `Docutils <https://docutils.sourceforge.io/>`_ project for creating
   reStructuredText and the Docutils suite;
 * Fredrik Lundh for his Alternative Python Reference project from which Sphinx
   got many good ideas.
 
 
-Contributors to the Python Documentation
+Contributors to the Python documentation
 ----------------------------------------
 
 Many people have contributed to the Python language, the Python standard

Doc/conf.py

@@ -101,9 +101,7 @@
 
 # Create table of contents entries for domain objects (e.g. functions, classes,
 # attributes, etc.). Default is True.
-toc_object_entries = True
-# Hide parents to tidy up long entries in sidebar
-toc_object_entries_show_parents = 'hide'
+toc_object_entries = False
 
 # Ignore any .rst files in the includes/ directory;
 # they're embedded in pages but not rendered as individual pages.

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

@@ -79,3 +79,8 @@ Pending removal in Python 3.16
 
   * The undocumented and unused :attr:`!TarFile.tarfile` attribute
     has been deprecated since Python 3.13.
+
+* :mod:`functools`:
+
+  * Calling the Python implementation of :func:`functools.reduce` with *function*
+    or *sequence* as keyword arguments has been deprecated since Python 3.14.

Doc/howto/free-threading-extensions.rst

@@ -96,8 +96,10 @@ Most of the C API is thread-safe, but there are some exceptions.
 
 * **Struct Fields**: Accessing fields in Python C API objects or structs
   directly is not thread-safe if the field may be concurrently modified.
-* **Macros**: Accessor macros like :c:macro:`PyList_GET_ITEM` and
-  :c:macro:`PyList_SET_ITEM` do not perform any error checking or locking.
+* **Macros**: Accessor macros like :c:macro:`PyList_GET_ITEM`,
+  :c:macro:`PyList_SET_ITEM`, and macros like
+  :c:macro:`PySequence_Fast_GET_SIZE` that use the object returned by
+  :c:func:`PySequence_Fast` do not perform any error checking or locking.
   These macros are not thread-safe if the container object may be modified
   concurrently.
 * **Borrowed References**: C API functions that return

Doc/library/calendar.rst

@@ -138,6 +138,13 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
 
    :class:`TextCalendar` instances have the following methods:
 
+   .. method:: formatday(theday, weekday, width)
+
+      Return a string representing a single day formatted with the given *width*.
+      If *theday* is ``0``, return a string of spaces of
+      the specified width, representing an empty day. The *weekday* parameter
+      is unused.
+
    .. method:: formatweek(theweek, w=0, highlight_day=None)
 
       Return a single week in a string with no newline. If *w* is provided, it
@@ -151,6 +158,20 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
          <using-on-controlling-color>`.
 
 
+   .. method:: formatweekday(weekday, width)
+
+      Return a string representing the name of a single weekday formatted to
+      the specified *width*. The *weekday* parameter is an integer representing
+      the day of the week, where ``0`` is Monday and ``6`` is Sunday.
+
+
+   .. method:: formatweekheader(width)
+
+      Return a string containing the header row of weekday names, formatted
+      with the given *width* for each column. The names depend on the locale
+      settings and are padded to the specified width.
+
+
    .. method:: formatmonth(theyear, themonth, w=0, l=0, highlight_day=None)
 
       Return a month's calendar in a multi-line string. If *w* is provided, it
@@ -165,6 +186,14 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
          <using-on-controlling-color>`.
 
 
+   .. method:: formatmonthname(theyear, themonth, width=0, withyear=True)
+
+      Return a string representing the month's name centered within the
+      specified *width*. If *withyear* is ``True``, include the year in the
+      output. The *theyear* and *themonth* parameters specify the year
+      and month for the name to be formatted respectively.
+
+
    .. method:: prmonth(theyear, themonth, w=0, l=0)
 
       Print a month's calendar as returned by :meth:`formatmonth`.
@@ -460,7 +489,7 @@ The :mod:`calendar` module exports the following data attributes:
 
    A sequence that represents the months of the year in the current locale.  This
    follows normal convention of January being month number 1, so it has a length of
-   13 and  ``month_name[0]`` is the empty string.
+   13 and ``month_name[0]`` is the empty string.
 
        >>> import calendar
        >>> list(calendar.month_name)

Doc/library/decimal.rst

@@ -1033,7 +1033,7 @@ New contexts can also be created using the :class:`Context` constructor
 described below. In addition, the module provides three pre-made contexts:
 
 
-.. class:: BasicContext
+.. data:: BasicContext
 
    This is a standard context defined by the General Decimal Arithmetic
    Specification.  Precision is set to nine.  Rounding is set to
@@ -1044,7 +1044,7 @@ described below. In addition, the module provides three pre-made contexts:
    Because many of the traps are enabled, this context is useful for debugging.
 
 
-.. class:: ExtendedContext
+.. data:: ExtendedContext
 
    This is a standard context defined by the General Decimal Arithmetic
    Specification.  Precision is set to nine.  Rounding is set to
@@ -1057,7 +1057,7 @@ described below. In addition, the module provides three pre-made contexts:
    presence of conditions that would otherwise halt the program.
 
 
-.. class:: DefaultContext
+.. data:: DefaultContext
 
    This context is used by the :class:`Context` constructor as a prototype for new
    contexts.  Changing a field (such a precision) has the effect of changing the

Doc/library/pyexpat.rst

@@ -941,6 +941,13 @@ The ``errors`` module has the following attributes:
    has been breached.
 
 
+.. data:: XML_ERROR_NOT_STARTED
+
+   The parser was tried to be stopped or suspended before it started.
+
+   .. versionadded:: next
+
+
 .. rubric:: Footnotes
 
 .. [1] The encoding string included in XML output should conform to the

Doc/library/re.rst

@@ -572,11 +572,8 @@ character ``'$'``.
    Word boundaries are determined by the current locale
    if the :py:const:`~re.LOCALE` flag is used.
 
-   .. note::
-
-      Note that ``\B`` does not match an empty string, which differs from
-      RE implementations in other programming languages such as Perl.
-      This behavior is kept for compatibility reasons.
+   .. versionchanged:: next
+      ``\B`` now matches empty input string.
 
 .. index:: single: \d; in regular expressions
 

Doc/library/turtle.rst

@@ -1823,7 +1823,8 @@ Window control
 
 .. function:: bgpic(picname=None)
 
-   :param picname: a string, name of a gif-file or ``"nopic"``, or ``None``
+   :param picname: a string, name of an image file (PNG, GIF, PGM, and PPM)
+                   or ``"nopic"``, or ``None``
 
    Set background image or return name of current backgroundimage.  If *picname*
    is a filename, set the corresponding image as background.  If *picname* is
@@ -2200,9 +2201,9 @@ Settings and special methods
 .. function:: register_shape(name, shape=None)
               addshape(name, shape=None)
 
-   There are three different ways to call this function:
+   There are four different ways to call this function:
 
-   (1) *name* is the name of a gif-file and *shape* is ``None``: Install the
+   (1) *name* is the name of an image file (PNG, GIF, PGM, and PPM) and *shape* is ``None``: Install the
        corresponding image shape. ::
 
        >>> screen.register_shape("turtle.gif")
@@ -2211,20 +2212,33 @@ Settings and special methods
           Image shapes *do not* rotate when turning the turtle, so they do not
           display the heading of the turtle!
 
-   (2) *name* is an arbitrary string and *shape* is a tuple of pairs of
+   (2) *name* is an arbitrary string and *shape* is the name of an image file (PNG, GIF, PGM, and PPM): Install the
+       corresponding image shape. ::
+
+       >>> screen.register_shape("turtle", "turtle.gif")
+
+       .. note::
+          Image shapes *do not* rotate when turning the turtle, so they do not
+          display the heading of the turtle!
+
+   (3) *name* is an arbitrary string and *shape* is a tuple of pairs of
        coordinates: Install the corresponding polygon shape.
 
        .. doctest::
           :skipif: _tkinter is None
 
           >>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3)))
 
-   (3) *name* is an arbitrary string and *shape* is a (compound) :class:`Shape`
+   (4) *name* is an arbitrary string and *shape* is a (compound) :class:`Shape`
        object: Install the corresponding compound shape.
 
    Add a turtle shape to TurtleScreen's shapelist.  Only thusly registered
    shapes can be used by issuing the command ``shape(shapename)``.
 
+   .. versionchanged:: next
+      Added support for PNG, PGM, and PPM image formats.
+      Both a shape name and an image file name can be specified.
+
 
 .. function:: turtles()