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)
  ...

.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/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