Merge remote-tracking branch 'upstream/main' into docs-mv-sphinx-lint…

…-to-pre-commit
python · hugovk · Jun 18, 2023 · Jun 13, 2023 · Jun 18, 2023 · Jun 18, 2023
commit be2a3c71579064532dc58f384a49514f6843a539
diff --git a/.azure-pipelines/ci.yml b/.azure-pipelines/ci.yml
@@ -14,20 +14,6 @@ jobs:
   - template: ./prebuild-checks.yml
 
 
-- job: Docs_PR
-  displayName: Docs PR
-  dependsOn: Prebuild
-  condition: and(succeeded(), eq(dependencies.Prebuild.outputs['docs.run'], 'true'))
-
-  pool:
-    vmImage: ubuntu-22.04
-
-  steps:
-  - template: ./docs-steps.yml
-    parameters:
-      upload: true
-
-
 - job: macOS_CI_Tests
   displayName: macOS CI Tests
   dependsOn: Prebuild

diff --git a/.azure-pipelines/docs-steps.yml b/.azure-pipelines/docs-steps.yml
diff --git a/.azure-pipelines/pr.yml b/.azure-pipelines/pr.yml
@@ -14,18 +14,6 @@ jobs:
   - template: ./prebuild-checks.yml
 
 
-- job: Docs_PR
-  displayName: Docs PR
-  dependsOn: Prebuild
-  condition: and(succeeded(), eq(dependencies.Prebuild.outputs['docs.run'], 'true'))
-
-  pool:
-    vmImage: ubuntu-22.04
-
-  steps:
-  - template: ./docs-steps.yml
-
-
 - job: macOS_PR_Tests
   displayName: macOS PR Tests
   dependsOn: Prebuild

diff --git a/.azure-pipelines/prebuild-checks.yml b/.azure-pipelines/prebuild-checks.yml
@@ -11,18 +11,6 @@ steps:
   displayName: Fetch comparison tree
   condition: and(succeeded(), variables['System.PullRequest.TargetBranch'])
 
-- script: |
-   if ! git diff --name-only $(diffTarget) | grep -qE '(\.rst$|^Doc|^Misc)'
-   then
-     echo "No docs were updated: docs.run=false"
-     echo "##vso[task.setvariable variable=run;isOutput=true]false"
-   else
-     echo "Docs were updated: docs.run=true"
-     echo "##vso[task.setvariable variable=run;isOutput=true]true"
-   fi
-  displayName: Detect documentation changes
-  name: docs
-
 - script: |
    if ! git diff --name-only $(diffTarget) | grep -qvE '(\.rst$|^Doc|^Misc)'
    then

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -232,17 +232,16 @@ jobs:
         path: config.cache
         key: ${{ github.job }}-${{ runner.os }}-${{ needs.check_source.outputs.config_hash }}
     - name: Install Homebrew dependencies
-      run: brew install pkg-config openssl@1.1 xz gdbm tcl-tk
+      run: brew install pkg-config openssl@3.0 xz gdbm tcl-tk
     - name: Configure CPython
       run: |
-        CFLAGS="-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" \
-        LDFLAGS="-L$(brew --prefix gdbm)/lib -I$(brew --prefix xz)/lib" \
-        PKG_CONFIG_PATH="$(brew --prefix tcl-tk)/lib/pkgconfig" \
+        GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \
+        GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \
         ./configure \
           --config-cache \
           --with-pydebug \
           --prefix=/opt/python-dev \
-          --with-openssl="$(brew --prefix openssl@1.1)"
+          --with-openssl="$(brew --prefix openssl@3.0)"
     - name: Build CPython
       run: make -j4
     - name: Display build info

diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
@@ -439,16 +439,24 @@ API Functions
    .. versionadded:: 3.2
 
 
-.. XXX deprecated, will be removed
 .. c:function:: int PyArg_Parse(PyObject *args, const char *format, ...)
 
-   Function used to deconstruct the argument lists of "old-style" functions ---
-   these are functions which use the :const:`METH_OLDARGS` parameter parsing
-   method, which has been removed in Python 3.  This is not recommended for use
-   in parameter parsing in new code, and most code in the standard interpreter
-   has been modified to no longer use this for that purpose.  It does remain a
-   convenient way to decompose other tuples, however, and may continue to be
-   used for that purpose.
+   Parse the parameter of a function that takes a single positional parameter
+   into a local variable.  Returns true on success; on failure, it returns
+   false and raises the appropriate exception.
+
+   Example::
+
+       // Function using METH_O calling convention
+       static PyObject*
+       my_function(PyObject *module, PyObject *arg)
+       {
+           int value;
+           if (!PyArg_Parse(arg, "i:my_function", &value)) {
+               return NULL;
+           }
+           // ... use value ...
+       }
 
 
 .. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)

diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst
@@ -3,7 +3,7 @@
 .. _floatobjects:
 
 Floating Point Objects
-----------------------
+======================
 
 .. index:: pair: object; floating point
 
@@ -79,7 +79,7 @@ Floating Point Objects
 
 
 Pack and Unpack functions
-=========================
+-------------------------
 
 The pack and unpack functions provide an efficient platform-independent way to
 store floating-point values as byte strings. The Pack routines produce a bytes
@@ -104,7 +104,7 @@ happens in such cases is partly accidental (alas).
 .. versionadded:: 3.11
 
 Pack functions
---------------
+^^^^^^^^^^^^^^
 
 The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an
 :c:expr:`int` argument, non-zero if you want the bytes string in little-endian
@@ -135,7 +135,7 @@ There are two problems on non-IEEE platforms:
 
 
 Unpack functions
-----------------
+^^^^^^^^^^^^^^^^
 
 The unpack routines read 2, 4 or 8 bytes, starting at *p*.  *le* is an
 :c:expr:`int` argument, non-zero if the bytes string is in little-endian format

diff --git a/Doc/c-api/frame.rst b/Doc/c-api/frame.rst
@@ -134,7 +134,7 @@ See also :ref:`Reflection <reflection>`.
 
 
 Internal Frames
----------------
+^^^^^^^^^^^^^^^
 
 Unless using :pep:`523`, you will not need this.
 

diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst
@@ -38,6 +38,9 @@ Importing Modules
       to per-module locks for most purposes, so this function's special
       behaviour isn't needed anymore.
 
+   .. deprecated-removed:: 3.13 3.15
+      Use :c:func:`PyImport_ImportModule` instead.
+
 
 .. c:function:: PyObject* PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
 

diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst
@@ -113,7 +113,7 @@ Slice Objects
 
 
 Ellipsis Object
----------------
+^^^^^^^^^^^^^^^
 
 
 .. c:var:: PyObject *Py_Ellipsis

diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
@@ -258,7 +258,7 @@ The following functions and structs are used to create
    (or *Py_tp_base[s]* slots if *bases* is ``NULL``, see below).
 
    Metaclasses that override :c:member:`~PyTypeObject.tp_new` are not
-   supported.
+   supported, except if ``tp_new`` is ``NULL``.
    (For backwards compatibility, other ``PyType_From*`` functions allow
    such metaclasses. They ignore ``tp_new``, which may result in incomplete
    initialization. This is deprecated and in Python 3.14+ such metaclasses will

diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
@@ -168,7 +168,7 @@ representation of the instance for which it is called.  Here is a simple
 example::
 
    static PyObject *
-   newdatatype_repr(newdatatypeobject * obj)
+   newdatatype_repr(newdatatypeobject *obj)
    {
        return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",
                                    obj->obj_UnderlyingDatatypePtr->size);
@@ -188,7 +188,7 @@ used instead.
 Here is a simple example::
 
    static PyObject *
-   newdatatype_str(newdatatypeobject * obj)
+   newdatatype_str(newdatatypeobject *obj)
    {
        return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",
                                    obj->obj_UnderlyingDatatypePtr->size);
@@ -338,7 +338,7 @@ Here is an example::
 
        PyErr_Format(PyExc_AttributeError,
                     "'%.100s' object has no attribute '%.400s'",
-                    tp->tp_name, name);
+                    Py_TYPE(obj)->tp_name, name);
        return NULL;
    }
 
@@ -379,7 +379,7 @@ Here is a sample implementation, for a datatype that is considered equal if the
 size of an internal pointer is equal::
 
    static PyObject *
-   newdatatype_richcmp(PyObject *obj1, PyObject *obj2, int op)
+   newdatatype_richcmp(newdatatypeobject *obj1, newdatatypeobject *obj2, int op)
    {
        PyObject *result;
        int c, size1, size2;
@@ -478,7 +478,7 @@ This function takes three arguments:
 Here is a toy ``tp_call`` implementation::
 
    static PyObject *
-   newdatatype_call(newdatatypeobject *self, PyObject *args, PyObject *kwds)
+   newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *kwds)
    {
        PyObject *result;
        const char *arg1;

diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst
@@ -135,7 +135,7 @@ Python versions are numbered "A.B.C" or "A.B":
 
 See :pep:`6` for more information about bugfix releases.
 
-Not all releases are bugfix releases.  In the run-up to a new major release, a
+Not all releases are bugfix releases.  In the run-up to a new feature release, a
 series of development releases are made, denoted as alpha, beta, or release
 candidate.  Alphas are early releases in which interfaces aren't yet finalized;
 it's not unexpected to see an interface change between two alpha releases.
@@ -297,9 +297,9 @@ How stable is Python?
 
 Very stable.  New, stable releases have been coming out roughly every 6 to 18
 months since 1991, and this seems likely to continue.  As of version 3.9,
-Python will have a major new release every 12 months (:pep:`602`).
+Python will have a new feature release every 12 months (:pep:`602`).
 
-The developers issue "bugfix" releases of older versions, so the stability of
+The developers issue bugfix releases of older versions, so the stability of
 existing releases gradually improves.  Bugfix releases, indicated by a third
 component of the version number (e.g. 3.5.3, 3.6.2), are managed for stability;
 only fixes for known problems are included in a bugfix release, and it's

diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst
@@ -517,7 +517,16 @@ from that module.
     nested in other classes.
 
 It is possible to modify how enum members are pickled/unpickled by defining
-:meth:`__reduce_ex__` in the enumeration class.
+:meth:`__reduce_ex__` in the enumeration class.  The default method is by-value,
+but enums with complicated values may want to use by-name::
+
+    >>> class MyEnum(Enum):
+    ...     __reduce_ex__ = enum.pickle_by_enum_name
+
+.. note::
+
+    Using by-name for flags is not recommended, as unnamed aliases will
+    not unpickle.
 
 
 Functional API

diff --git a/Doc/install/index.rst b/Doc/install/index.rst
@@ -696,7 +696,7 @@ is supplied to suppress this behaviour.  So you could simply edit
    import sys
    sys.path.append('/www/python/')
 
-However, if you reinstall the same major version of Python (perhaps when
+However, if you reinstall the same minor version of Python (perhaps when
 upgrading from 2.2 to 2.2.2, for example) :file:`site.py` will be overwritten by
 the stock version.  You'd have to remember that it was modified and save a copy
 before doing the installation.

diff --git a/Doc/library/array.rst b/Doc/library/array.rst
@@ -57,7 +57,7 @@ Notes:
       ``Py_UNICODE``. This change doesn't affect its behavior because
       ``Py_UNICODE`` is alias of ``wchar_t`` since Python 3.3.
 
-   .. deprecated-removed:: 3.3 4.0
+   .. deprecated-removed:: 3.3 3.16
       Please migrate to ``'w'`` typecode.
 
 

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
@@ -426,6 +426,9 @@ Sleeping
    .. versionchanged:: 3.10
       Removed the *loop* parameter.
 
+   .. versionchanged:: 3.13
+      Raises :exc:`ValueError` if *delay* is :data:`~math.nan`.
+
 
 Running Tasks Concurrently
 ==========================

diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
@@ -1497,7 +1497,7 @@ are also included in the pure Python version for compatibility.
 
    The value is ``True``.  Deprecated, because Python now always has threads.
 
-.. deprecated:: 3.9
+   .. deprecated:: 3.9
 
 .. data:: HAVE_CONTEXTVAR
-Original file line number
+Diff line change
@@ Expand Up / @@ -134,7 +134,7 @@ See also :ref:`Reflection <reflection>`. @@
     Internal Frames
-    ---------------
+    ^^^^^^^^^^^^^^^
     Unless using :pep:`523`, you will not need this.
@@ Expand Down @@