Merge branch 'main' of https://github.com/colesbury/cpython

.github/workflows/build.yml

@@ -120,7 +120,9 @@ jobs:
 
   check_generated_files:
     name: 'Check if generated files are up to date'
-    runs-on: ubuntu-latest
+    # Don't use ubuntu-latest but a specific version to make the job
+    # reproducible: to get the same tools versions (autoconf, aclocal, ...)
+    runs-on: ubuntu-22.04
     timeout-minutes: 60
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true'
@@ -143,15 +145,16 @@ jobs:
       - name: Check Autoconf and aclocal versions
         run: |
           grep "Generated by GNU Autoconf 2.71" configure
-          grep "aclocal 1.16.4" aclocal.m4
+          grep "aclocal 1.16.5" aclocal.m4
           grep -q "runstatedir" configure
           grep -q "PKG_PROG_PKG_CONFIG" aclocal.m4
       - name: Configure CPython
         run: |
           # Build Python with the libpython dynamic library
           ./configure --config-cache --with-pydebug --enable-shared
-      - name: Regenerate autoconf files with container image
-        run: make regen-configure
+      - name: Regenerate autoconf files
+        # Same command used by Tools/build/regen-configure.sh ($AUTORECONF)
+        run: autoreconf -ivf -Werror
       - name: Build CPython
         run: |
           make -j4 regen-all
@@ -518,7 +521,6 @@ jobs:
       uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe
       with:
         allowed-failures: >-
-          build_macos,
           build_macos_free_threaded,
           build_ubuntu_free_threaded,
           build_ubuntu_ssltests,

.github/workflows/posix-deps-apt.sh

@@ -1,9 +1,11 @@
 #!/bin/sh
 apt-get update
 
+# autoconf-archive is needed by autoreconf (check_generated_files job)
 apt-get -yq install \
     build-essential \
     pkg-config \
+    autoconf-archive \
     ccache \
     gdb \
     lcov \

Doc/Makefile

@@ -29,6 +29,7 @@ help:
 	@echo "  venv       to create a venv with necessary tools"
 	@echo "  html       to make standalone HTML files"
 	@echo "  htmlview   to open the index page built by the html target in your browser"
+	@echo "  htmllive   to rebuild and reload HTML files in your browser"
 	@echo "  htmlhelp   to make HTML files and a HTML help project"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  text       to make plain text files"
@@ -139,6 +140,11 @@ pydoc-topics: build
 htmlview: html
 	$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))"
 
+.PHONY: htmllive
+htmllive: SPHINXBUILD = $(VENVDIR)/bin/sphinx-autobuild
+htmllive: SPHINXOPTS = --re-ignore="/venv/"
+htmllive: html
+
 .PHONY: clean
 clean: clean-venv
 	-rm -rf build/*

Doc/bugs.rst

@@ -38,7 +38,7 @@ though it may take a while to be processed.
    `Helping with Documentation <https://devguide.python.org/docquality/#helping-with-documentation>`_
       Comprehensive guide for individuals that are interested in contributing to Python documentation.
 
-   `Documentation Translations <https://devguide.python.org/documenting/#translating>`_
+   `Documentation Translations <https://devguide.python.org/documentation/translating/>`_
       A list of GitHub pages for documentation translation and their primary contacts.
 
 

Doc/c-api/bytes.rst

@@ -155,6 +155,7 @@ called with a non-bytes parameter.
 
    Return the null-terminated contents of the object *obj*
    through the output variables *buffer* and *length*.
+   Returns ``0`` on success.
 
    If *length* is ``NULL``, the bytes object
    may not contain embedded null bytes;

Doc/c-api/dict.rst

@@ -173,6 +173,33 @@ Dictionary Objects
 
    .. versionadded:: 3.4
 
+
+.. c:function:: int PyDict_Pop(PyObject *p, PyObject *key, PyObject **result)
+
+   Remove *key* from dictionary *p* and optionally return the removed value.
+   Do not raise :exc:`KeyError` if the key missing.
+
+   - If the key is present, set *\*result* to a new reference to the removed
+     value if *result* is not ``NULL``, and return ``1``.
+   - If the key is missing, set *\*result* to ``NULL`` if *result* is not
+     ``NULL``, and return ``0``.
+   - On error, raise an exception and return ``-1``.
+
+   This is similar to :meth:`dict.pop`, but without the default value and
+   not raising :exc:`KeyError` if the key missing.
+
+   .. versionadded:: 3.13
+
+
+.. c:function:: int PyDict_PopString(PyObject *p, const char *key, PyObject **result)
+
+   Similar to :c:func:`PyDict_Pop`, but *key* is specified as a
+   :c:expr:`const char*` UTF-8 encoded bytes string, rather than a
+   :c:expr:`PyObject*`.
+
+   .. versionadded:: 3.13
+
+
 .. c:function:: PyObject* PyDict_Items(PyObject *p)
 
    Return a :c:type:`PyListObject` containing all the items from the dictionary.

Doc/c-api/hash.rst

@@ -0,0 +1,48 @@
+.. highlight:: c
+
+PyHash API
+----------
+
+See also the :c:member:`PyTypeObject.tp_hash` member.
+
+.. c:type:: Py_hash_t
+
+   Hash value type: signed integer.
+
+   .. versionadded:: 3.2
+
+.. c:type:: Py_uhash_t
+
+   Hash value type: unsigned integer.
+
+   .. versionadded:: 3.2
+
+
+.. c:type:: PyHash_FuncDef
+
+   Hash function definition used by :c:func:`PyHash_GetFuncDef`.
+
+   .. c::member:: Py_hash_t (*const hash)(const void *, Py_ssize_t)
+
+      Hash function.
+
+   .. c:member:: const char *name
+
+      Hash function name (UTF-8 encoded string).
+
+   .. c:member:: const int hash_bits
+
+      Internal size of the hash value in bits.
+
+   .. c:member:: const int seed_bits
+
+      Size of seed input in bits.
+
+   .. versionadded:: 3.4
+
+
+.. c:function:: PyHash_FuncDef* PyHash_GetFuncDef(void)
+
+   Get the hash function definition.
+
+   .. versionadded:: 3.4

Doc/c-api/list.rst

@@ -128,6 +128,30 @@ List Objects
    list is not supported.
 
 
+.. c:function:: int PyList_Extend(PyObject *list, PyObject *iterable)
+
+   Extend *list* with the contents of *iterable*.  This is the same as
+   ``PyList_SetSlice(list, PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable)``
+   and analogous to ``list.extend(iterable)`` or ``list += iterable``.
+
+   Raise an exception and return ``-1`` if *list* is not a :class:`list`
+   object. Return 0 on success.
+
+   .. versionadded:: 3.13
+
+
+.. c:function:: int PyList_Clear(PyObject *list)
+
+   Remove all items from *list*.  This is the same as
+   ``PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, NULL)`` and analogous to
+   ``list.clear()`` or ``del list[:]``.
+
+   Raise an exception and return ``-1`` if *list* is not a :class:`list`
+   object.  Return 0 on success.
+
+   .. versionadded:: 3.13
+
+
 .. c:function:: int PyList_Sort(PyObject *list)
 
    Sort the items of *list* in place.  Return ``0`` on success, ``-1`` on

Doc/c-api/unicode.rst

@@ -992,19 +992,11 @@ These are the UTF-8 codec APIs:
 
    As :c:func:`PyUnicode_AsUTF8AndSize`, but does not store the size.
 
-   Raise an exception if the *unicode* string contains embedded null
-   characters. To accept embedded null characters and truncate on purpose
-   at the first null byte, ``PyUnicode_AsUTF8AndSize(unicode, NULL)`` can be
-   used instead.
-
    .. versionadded:: 3.3
 
    .. versionchanged:: 3.7
       The return type is now ``const char *`` rather of ``char *``.
 
-   .. versionchanged:: 3.13
-      Raise an exception if the string contains embedded null characters.
-
 
 UTF-32 Codecs
 """""""""""""

Doc/c-api/utilities.rst

@@ -17,6 +17,7 @@ and parsing function arguments and constructing Python values from C values.
    marshal.rst
    arg.rst
    conversion.rst
+   hash.rst
    reflection.rst
    codec.rst
    perfmaps.rst

Doc/conf.py

@@ -288,9 +288,8 @@
     "pr_id": os.getenv("READTHEDOCS_VERSION")
 }
 
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-html_last_updated_fmt = '%b %d, %Y'
+# This 'Last updated on:' timestamp is inserted at the bottom of every page.
+html_last_updated_fmt = time.strftime('%b %d, %Y (%H:%M UTC)', time.gmtime())
 
 # Path to find HTML templates.
 templates_path = ['tools/templates']

Doc/glossary.rst

@@ -1138,6 +1138,11 @@ Glossary
       an :term:`expression` or one of several constructs with a keyword, such
       as :keyword:`if`, :keyword:`while` or :keyword:`for`.
 
+   static type checker
+      An external tool that reads Python code and analyzes it, looking for
+      issues such as incorrect types. See also :term:`type hints <type hint>`
+      and the :mod:`typing` module.
+
    strong reference
       In Python's C API, a strong reference is a reference to an object
       which is owned by the code holding the reference.  The strong
@@ -1214,8 +1219,8 @@ Glossary
       attribute, or a function parameter or return value.
 
       Type hints are optional and are not enforced by Python but
-      they are useful to static type analysis tools, and aid IDEs with code
-      completion and refactoring.
+      they are useful to :term:`static type checkers <static type checker>`.
+      They can also aid IDEs with code completion and refactoring.
 
       Type hints of global variables, class attributes, and functions,
       but not local variables, can be accessed using

Doc/howto/descriptor.rst

@@ -943,6 +943,10 @@ it can be updated:
     >>> Movie('Star Wars').director
     'J.J. Abrams'
 
+.. testcleanup::
+
+   conn.close()
+
 
 Pure Python Equivalents
 ^^^^^^^^^^^^^^^^^^^^^^^

Doc/howto/enum.rst

@@ -607,9 +607,9 @@ The complete signature is::
         start=1,
         )
 
-:value: What the new enum class will record as its name.
+* *value*: What the new enum class will record as its name.
 
-:names: The enum members.  This can be a whitespace- or comma-separated string
+* *names*: The enum members.  This can be a whitespace- or comma-separated string
   (values will start at 1 unless otherwise specified)::
 
     'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'
@@ -626,13 +626,13 @@ The complete signature is::
 
     {'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}
 
-:module: name of module where new enum class can be found.
+* *module*: name of module where new enum class can be found.
 
-:qualname: where in module new enum class can be found.
+* *qualname*: where in module new enum class can be found.
 
-:type: type to mix in to new enum class.
+* *type*: type to mix in to new enum class.
 
-:start: number to start counting at if only names are passed in.
+* *start*: number to start counting at if only names are passed in.
 
 .. versionchanged:: 3.5
    The *start* parameter was added.