Merge branch 'main' into lockfreecp

* main: (76 commits)
  Fix syntax error in struct doc example (python#102160)
  pythongh-99108: Import MD5 and SHA1 from HACL* (python#102089)
  pythonGH-101777: `queue.rst`: use 2 spaces after a period to be consistent. (python#102143)
  Few coverage nitpicks for the cmath module (python#102067)
  pythonGH-100982: Restrict `FOR_ITER_RANGE` to a single instruction to allow instrumentation. (pythonGH-101985)
  pythongh-102135: Update turtle docs to rename wikipedia demo to rosette (python#102137)
  pythongh-99942: python.pc on android/cygwin should link to libpython per configure.ac (pythonGH-100356)
  pythongh-95672 fix typo SkitTest to SkipTest (pythongh-102119)
  pythongh-101936: Update the default value of fp from io.StringIO to io.BytesIO (pythongh-102100)
  pythongh-102008: simplify test_except_star by using sys.exception() instead of sys.exc_info() (python#102009)
  pythongh-101903: Remove obsolete undefs for previously removed macros Py_EnterRecursiveCall and Py_LeaveRecursiveCall (python#101923)
  pythongh-100556: Improve clarity of `or` docs (python#100589)
  pythongh-101777: Make `PriorityQueue` docs slightly clearer (python#102026)
  pythongh-101965: Fix usage of Py_EnterRecursiveCall return value in _bisectmodule.c (pythonGH-101966)
  pythongh-101578: Amend exception docs (python#102057)
  pythongh-101961 fileinput.hookcompressed should not set the encoding value for the binary mode (pythongh-102068)
  pythongh-102056: Fix a few bugs in error handling of exception printing code (python#102078)
  pythongh-102011: use sys.exception() instead of sys.exc_info() in docs where possible (python#102012)
  pythongh-101566: Sync with zipp 3.14. (pythonGH-102018)
  pythonGH-99818: improve the documentation for zipfile.Path and Traversable (pythonGH-101589)
  ...

Author: carljm

.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 [email protected] 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 [email protected])/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 [email protected])"
     - name: Build CPython
       run: make -j4
     - name: Display build info

Doc/c-api/dict.rst

@@ -80,7 +80,7 @@ Dictionary Objects
 
 .. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
 
-   Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
+   Remove the entry in dictionary *p* with key *key*. *key* must be :term:`hashable`;
    if it isn't, :exc:`TypeError` is raised.
    If *key* is not in the dictionary, :exc:`KeyError` is raised.
    Return ``0`` on success or ``-1`` on failure.

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/c-api/object.rst

@@ -281,7 +281,7 @@ Object Protocol
 
 .. c:function:: Py_hash_t PyObject_HashNotImplemented(PyObject *o)
 
-   Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and return ``-1``.
+   Set a :exc:`TypeError` indicating that ``type(o)`` is not :term:`hashable` and return ``-1``.
    This function receives special treatment when stored in a ``tp_hash`` slot,
    allowing a type to explicitly indicate to the interpreter that it is not
    hashable.

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/faq/programming.rst

@@ -1979,7 +1979,7 @@ method result will be released right away.  The disadvantage is that if
 instances accumulate, so too will the accumulated method results.  They
 can grow without bound.
 
-The *lru_cache* approach works with methods that have hashable
+The *lru_cache* approach works with methods that have :term:`hashable`
 arguments.  It creates a reference to the instance unless special
 efforts are made to pass in weak references.
 

Doc/library/abc.rst

@@ -21,7 +21,7 @@ The :mod:`collections` module has some concrete classes that derive from
 ABCs; these can, of course, be further derived. In addition, the
 :mod:`collections.abc` submodule has some ABCs that can be used to test whether
 a class or instance provides a particular interface, for example, if it is
-hashable or if it is a mapping.
+:term:`hashable` or if it is a mapping.
 
 
 This module provides the metaclass :class:`ABCMeta` for defining ABCs and

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