Merge branch 'main' into protz_md5_sha1

Author: msprotz

.github/workflows/build.yml

@@ -154,15 +154,25 @@ jobs:
     needs: check_source
     if: needs.check_source.outputs.run_tests == 'true'
     env:
+      HOMEBREW_NO_ANALYTICS: 1
+      HOMEBREW_NO_AUTO_UPDATE: 1
+      HOMEBREW_NO_INSTALL_CLEANUP: 1
       PYTHONSTRICTEXTENSIONBUILD: 1
     steps:
     - uses: actions/checkout@v3
-    - name: Prepare homebrew environment variables
+    - name: Install Homebrew dependencies
+      run: brew install pkg-config openssl@1.1 xz gdbm tcl-tk
+    - name: Prepare Homebrew environment variables
       run: |
-        echo "LDFLAGS=-L$(brew --prefix tcl-tk)/lib" >> $GITHUB_ENV
+        echo "CFLAGS=-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" >> $GITHUB_ENV
+        echo "LDFLAGS=-L$(brew --prefix gdbm)/lib -I$(brew --prefix xz)/lib" >> $GITHUB_ENV
         echo "PKG_CONFIG_PATH=$(brew --prefix openssl@1.1)/lib/pkgconfig:$(brew --prefix tcl-tk)/lib/pkgconfig" >> $GITHUB_ENV
     - name: Configure CPython
-      run: ./configure --with-pydebug --prefix=/opt/python-dev
+      run: |
+        ./configure \
+          --with-pydebug \
+          --prefix=/opt/python-dev \
+          --with-openssl="$(brew --prefix openssl@1.1)"
     - name: Build CPython
       run: make -j4
     - name: Display build info

Doc/c-api/exceptions.rst

@@ -402,58 +402,45 @@ Querying the error indicator
 
 .. c:function:: PyObject *PyErr_GetRaisedException(void)
 
-   Returns the exception currently being raised, clearing the exception at
-   the same time. Do not confuse this with the exception currently being
-   handled which can be accessed with  :c:func:`PyErr_GetHandledException`.
+   Return the exception currently being raised, clearing the error indicator at
+   the same time.
 
-   .. note::
+   This function is used by code that needs to catch exceptions,
+   or code that needs to save and restore the error indicator temporarily.
 
-      This function is normally only used by code that needs to catch exceptions or
-      by code that needs to save and restore the error indicator temporarily, e.g.::
+   For example::
 
-         {
-            PyObject *exc = PyErr_GetRaisedException();
+      {
+         PyObject *exc = PyErr_GetRaisedException();
 
-            /* ... code that might produce other errors ... */
+         /* ... code that might produce other errors ... */
 
-            PyErr_SetRaisedException(exc);
-         }
+         PyErr_SetRaisedException(exc);
+      }
+
+   .. seealso:: :c:func:`PyErr_GetHandledException`,
+                to save the exception currently being handled.
 
    .. versionadded:: 3.12
 
 
 .. c:function:: void PyErr_SetRaisedException(PyObject *exc)
 
-   Sets the exception currently being raised ``exc``.
-   If the exception is already set, it is cleared first.
-
-   ``exc`` must be a valid exception.
-   (Violating this rules will cause subtle problems later.)
-   This call consumes a reference to the ``exc`` object: you must own a
-   reference to that object before the call and after the call you no longer own
-   that reference.
-   (If you don't understand this, don't use this function. I warned you.)
+   Set *exc* as the exception currently being raised,
+   clearing the existing exception if one is set.
 
-   .. note::
+   .. warning::
 
-      This function is normally only used by code that needs to save and restore the
-      error indicator temporarily.  Use :c:func:`PyErr_GetRaisedException` to save
-      the current exception, e.g.::
-
-         {
-            PyObject *exc = PyErr_GetRaisedException();
-
-            /* ... code that might produce other errors ... */
-
-            PyErr_SetRaisedException(exc);
-         }
+      This call steals a reference to *exc*, which must be a valid exception.
 
    .. versionadded:: 3.12
 
 
 .. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
 
-    As of 3.12, this function is deprecated. Use :c:func:`PyErr_GetRaisedException` instead.
+   .. deprecated:: 3.12
+
+      Use :c:func:`PyErr_GetRaisedException` instead.
 
    Retrieve the error indicator into three variables whose addresses are passed.
    If the error indicator is not set, set all three variables to ``NULL``.  If it is
@@ -462,8 +449,10 @@ Querying the error indicator
 
    .. note::
 
-      This function is normally only used by code that needs to catch exceptions or
-      by code that needs to save and restore the error indicator temporarily, e.g.::
+      This function is normally only used by legacy code that needs to catch
+      exceptions or save and restore the error indicator temporarily.
+
+      For example::
 
          {
             PyObject *type, *value, *traceback;
@@ -474,15 +463,17 @@ Querying the error indicator
             PyErr_Restore(type, value, traceback);
          }
 
-   .. deprecated:: 3.12
-
 
 .. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
 
-    As of 3.12, this function is deprecated. Use :c:func:`PyErr_SetRaisedException` instead.
+   .. deprecated:: 3.12
+
+      Use :c:func:`PyErr_SetRaisedException` instead.
 
-   Set the error indicator from the three objects.  If the error indicator is
-   already set, it is cleared first.  If the objects are ``NULL``, the error
+   Set the error indicator from the three objects,
+   *type*, *value*, and *traceback*,
+   clearing the existing exception if one is set.
+   If the objects are ``NULL``, the error
    indicator is cleared.  Do not pass a ``NULL`` type and non-``NULL`` value or
    traceback.  The exception type should be a class.  Do not pass an invalid
    exception type or value. (Violating these rules will cause subtle problems
@@ -493,18 +484,17 @@ Querying the error indicator
 
    .. note::
 
-      This function is normally only used by code that needs to save and restore the
-      error indicator temporarily.  Use :c:func:`PyErr_Fetch` to save the current
-      error indicator.
-
-   .. deprecated:: 3.12
+      This function is normally only used by legacy code that needs to
+      save and restore the error indicator temporarily.
+      Use :c:func:`PyErr_Fetch` to save the current error indicator.
 
 
 .. c:function:: void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)
 
-   As of 3.12, this function is deprecated.
-   Use :c:func:`PyErr_GetRaisedException` instead of :c:func:`PyErr_Fetch` to avoid
-   any possible de-normalization.
+   .. deprecated:: 3.12
+
+      Use :c:func:`PyErr_GetRaisedException` instead,
+      to avoid any possible de-normalization.
 
    Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
    can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
@@ -522,8 +512,6 @@ Querying the error indicator
            PyException_SetTraceback(val, tb);
          }
 
-   .. deprecated:: 3.12
-
 
 .. c:function:: PyObject* PyErr_GetHandledException(void)
 
@@ -771,14 +759,12 @@ Exception Objects
 
 .. c:function:: PyObject* PyException_GetArgs(PyObject *ex)
 
-   Return args of the given exception as a new reference,
-   as accessible from Python through :attr:`args`.
+   Return :attr:`~BaseException.args` of exception *ex*.
 
 
 .. c:function:: void PyException_SetArgs(PyObject *ex, PyObject *args)
 
-   Set the args of the given exception,
-   as accessible from Python through :attr:`args`.
+   Set :attr:`~BaseException.args` of exception *ex* to *args*.
 
 
 .. _unicodeexceptions:

Doc/c-api/function.rst

@@ -169,7 +169,7 @@ There are a few functions specific to Python functions.
    before the modification to *func* takes place, so the prior state of *func*
    can be inspected. The runtime is permitted to optimize away the creation of
    function objects when possible. In such cases no event will be emitted.
-   Although this creates the possitibility of an observable difference of
+   Although this creates the possibility of an observable difference of
    runtime behavior depending on optimization decisions, it does not change
    the semantics of the Python code being executed.
 

Doc/c-api/module.rst

@@ -388,15 +388,15 @@ objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
 
 .. c:function:: PyObject * PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
 
-   Create a new module object, given the definition in *module* and the
+   Create a new module object, given the definition in *def* and the
    ModuleSpec *spec*.  This behaves like :c:func:`PyModule_FromDefAndSpec2`
    with *module_api_version* set to :const:`PYTHON_API_VERSION`.
 
    .. versionadded:: 3.5
 
 .. c:function:: PyObject * PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
 
-   Create a new module object, given the definition in *module* and the
+   Create a new module object, given the definition in *def* and the
    ModuleSpec *spec*, assuming the API version *module_api_version*.
    If that version does not match the version of the running interpreter,
    a :exc:`RuntimeWarning` is emitted.

Doc/data/refcounts.dat

@@ -606,6 +606,9 @@ PyErr_GetExcInfo:PyObject**:ptype:+1:
 PyErr_GetExcInfo:PyObject**:pvalue:+1:
 PyErr_GetExcInfo:PyObject**:ptraceback:+1:
 
+PyErr_GetRaisedException:PyObject*::+1:
+PyErr_SetRaisedException::::
+
 PyErr_GivenExceptionMatches:int:::
 PyErr_GivenExceptionMatches:PyObject*:given:0:
 PyErr_GivenExceptionMatches:PyObject*:exc:0:
@@ -836,6 +839,8 @@ PyEval_EvalFrameEx:int:throwflag::
 PyEval_MergeCompilerFlags:int:::
 PyEval_MergeCompilerFlags:PyCompilerFlags*:cf::
 
+PyException_GetArgs:PyObject*::+1:
+
 PyException_GetCause:PyObject*::+1:
 PyException_GetCause:PyObject*:ex:0:
 

Doc/library/argparse.rst

@@ -1867,7 +1867,7 @@ Sub-commands
      ...
      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser()
-     >>> subparsers = parser.add_subparsers()
+     >>> subparsers = parser.add_subparsers(required=True)
      >>>
      >>> # create the parser for the "foo" command
      >>> parser_foo = subparsers.add_parser('foo')

Doc/library/asyncio-stream.rst

@@ -206,12 +206,20 @@ StreamReader
 
    .. coroutinemethod:: read(n=-1)
 
-      Read up to *n* bytes.  If *n* is not provided, or set to ``-1``,
-      read until EOF and return all read bytes.
+      Read up to *n* bytes from the stream.
 
+      If *n* is not provided or set to ``-1``,
+      read until EOF, then return all read :class:`bytes`.
       If EOF was received and the internal buffer is empty,
       return an empty ``bytes`` object.
 
+      If *n* is ``0``, return an empty ``bytes`` object immediately.
+
+      If *n* is positive, return at most *n* available ``bytes``
+      as soon as at least 1 byte is available in the internal buffer.
+      If EOF is received before any byte is read, return an empty
+      ``bytes`` object.
+
    .. coroutinemethod:: readline()
 
       Read one line, where "line" is a sequence of bytes

Doc/library/cmath.rst

@@ -15,11 +15,27 @@ the function is then applied to the result of the conversion.
 
 .. note::
 
-   On platforms with hardware and system-level support for signed
-   zeros, functions involving branch cuts are continuous on *both*
-   sides of the branch cut: the sign of the zero distinguishes one
-   side of the branch cut from the other.  On platforms that do not
-   support signed zeros the continuity is as specified below.
+   For functions involving branch cuts, we have the problem of deciding how to
+   define those functions on the cut itself. Following Kahan's "Branch cuts for
+   complex elementary functions" paper, as well as Annex G of C99 and later C
+   standards, we use the sign of zero to distinguish one side of the branch cut
+   from the other: for a branch cut along (a portion of) the real axis we look
+   at the sign of the imaginary part, while for a branch cut along the
+   imaginary axis we look at the sign of the real part.
+
+   For example, the :func:`cmath.sqrt` function has a branch cut along the
+   negative real axis. An argument of ``complex(-2.0, -0.0)`` is treated as
+   though it lies *below* the branch cut, and so gives a result on the negative
+   imaginary axis::
+
+      >>> cmath.sqrt(complex(-2.0, -0.0))
+      -1.4142135623730951j
+
+   But an argument of ``complex(-2.0, 0.0)`` is treated as though it lies above
+   the branch cut::
+
+      >>> cmath.sqrt(complex(-2.0, 0.0))
+      1.4142135623730951j
 
 
 Conversions to and from polar coordinates
@@ -44,14 +60,11 @@ rectangular coordinates to polar coordinates and back.
 
 .. function:: phase(x)
 
-   Return the phase of *x* (also known as the *argument* of *x*), as a
-   float.  ``phase(x)`` is equivalent to ``math.atan2(x.imag,
-   x.real)``.  The result lies in the range [-\ *π*, *π*], and the branch
-   cut for this operation lies along the negative real axis,
-   continuous from above.  On systems with support for signed zeros
-   (which includes most systems in current use), this means that the
-   sign of the result is the same as the sign of ``x.imag``, even when
-   ``x.imag`` is zero::
+   Return the phase of *x* (also known as the *argument* of *x*), as a float.
+   ``phase(x)`` is equivalent to ``math.atan2(x.imag, x.real)``.  The result
+   lies in the range [-\ *π*, *π*], and the branch cut for this operation lies
+   along the negative real axis.  The sign of the result is the same as the
+   sign of ``x.imag``, even when ``x.imag`` is zero::
 
       >>> phase(complex(-1.0, 0.0))
       3.141592653589793
@@ -92,8 +105,8 @@ Power and logarithmic functions
 .. function:: log(x[, base])
 
    Returns the logarithm of *x* to the given *base*. If the *base* is not
-   specified, returns the natural logarithm of *x*. There is one branch cut, from 0
-   along the negative real axis to -∞, continuous from above.
+   specified, returns the natural logarithm of *x*. There is one branch cut,
+   from 0 along the negative real axis to -∞.
 
 
 .. function:: log10(x)
@@ -112,9 +125,9 @@ Trigonometric functions
 
 .. function:: acos(x)
 
-   Return the arc cosine of *x*. There are two branch cuts: One extends right from
-   1 along the real axis to ∞, continuous from below. The other extends left from
-   -1 along the real axis to -∞, continuous from above.
+   Return the arc cosine of *x*. There are two branch cuts: One extends right
+   from 1 along the real axis to ∞. The other extends left from -1 along the
+   real axis to -∞.
 
 
 .. function:: asin(x)
@@ -125,9 +138,8 @@ Trigonometric functions
 .. function:: atan(x)
 
    Return the arc tangent of *x*. There are two branch cuts: One extends from
-   ``1j`` along the imaginary axis to ``∞j``, continuous from the right. The
-   other extends from ``-1j`` along the imaginary axis to ``-∞j``, continuous
-   from the left.
+   ``1j`` along the imaginary axis to ``∞j``. The other extends from ``-1j``
+   along the imaginary axis to ``-∞j``.
 
 
 .. function:: cos(x)
@@ -151,23 +163,21 @@ Hyperbolic functions
 .. function:: acosh(x)
 
    Return the inverse hyperbolic cosine of *x*. There is one branch cut,
-   extending left from 1 along the real axis to -∞, continuous from above.
+   extending left from 1 along the real axis to -∞.
 
 
 .. function:: asinh(x)
 
    Return the inverse hyperbolic sine of *x*. There are two branch cuts:
-   One extends from ``1j`` along the imaginary axis to ``∞j``,
-   continuous from the right.  The other extends from ``-1j`` along
-   the imaginary axis to ``-∞j``, continuous from the left.
+   One extends from ``1j`` along the imaginary axis to ``∞j``.  The other
+   extends from ``-1j`` along the imaginary axis to ``-∞j``.
 
 
 .. function:: atanh(x)
 
    Return the inverse hyperbolic tangent of *x*. There are two branch cuts: One
-   extends from ``1`` along the real axis to ``∞``, continuous from below. The
-   other extends from ``-1`` along the real axis to ``-∞``, continuous from
-   above.
+   extends from ``1`` along the real axis to ``∞``. The other extends from
+   ``-1`` along the real axis to ``-∞``.
 
 
 .. function:: cosh(x)