Merge remote-tracking branch 'upstream/main' into jump_if_bool

Author: iritkatriel

Doc/c-api/memory.rst

@@ -403,7 +403,7 @@ Customize Memory Allocators
 .. c:type:: PyMemAllocatorEx
 
    Structure used to describe a memory block allocator. The structure has
-   four fields:
+   the following fields:
 
    +----------------------------------------------------------+---------------------------------------+
    | Field                                                    | Meaning                               |

Doc/conf.py

@@ -139,7 +139,7 @@
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
-_stdauthor = r'Guido van Rossum\\and the Python development team'
+_stdauthor = 'Guido van Rossum and the Python development team'
 latex_documents = [
     ('c-api/index', 'c-api.tex',
      'The Python/C API', _stdauthor, 'manual'),

Doc/faq/programming.rst

@@ -1951,9 +1951,9 @@ relevant instance attributes are mutable, the *cached_property* approach
 can't be made to work because it cannot detect changes to the
 attributes.
 
-The *lru_cache* approach can be made to work, but the class needs to define the
-*__eq__* and *__hash__* methods so the cache can detect relevant attribute
-updates::
+To make the *lru_cache* approach work when the *station_id* is mutable,
+the class needs to define the *__eq__* and *__hash__* methods so that
+the cache can detect relevant attribute updates::
 
     class Weather:
         "Example with a mutable station identifier"

Doc/library/pickle.rst

@@ -147,7 +147,7 @@ to read the pickle produced.
   earlier versions of Python.
 
 * Protocol version 2 was introduced in Python 2.3.  It provides much more
-  efficient pickling of :term:`new-style class`\es.  Refer to :pep:`307` for
+  efficient pickling of :term:`new-style classes <new-style class>`.  Refer to :pep:`307` for
   information about improvements brought by protocol 2.
 
 * Protocol version 3 was added in Python 3.0.  It has explicit support for
@@ -261,7 +261,7 @@ process more convenient:
    protocol argument is needed.  Bytes past the pickled representation
    of the object are ignored.
 
-   Arguments *file*, *fix_imports*, *encoding*, *errors*, *strict* and *buffers*
+   Arguments *fix_imports*, *encoding*, *errors*, *strict* and *buffers*
    have the same meaning as in the :class:`Unpickler` constructor.
 
    .. versionchanged:: 3.8
@@ -368,7 +368,7 @@ The :mod:`pickle` module exports three classes, :class:`Pickler`,
 
       .. versionadded:: 3.3
 
-   .. method:: reducer_override(self, obj)
+   .. method:: reducer_override(obj)
 
       Special reducer that can be defined in :class:`Pickler` subclasses. This
       method has priority over any reducer in the :attr:`dispatch_table`.  It
@@ -494,20 +494,18 @@ What can be pickled and unpickled?
 
 The following types can be pickled:
 
-* ``None``, ``True``, and ``False``
-
-* integers, floating point numbers, complex numbers
+* ``None``, ``True``, and ``False``;
 
-* strings, bytes, bytearrays
+* integers, floating-point numbers, complex numbers;
 
-* tuples, lists, sets, and dictionaries containing only picklable objects
+* strings, bytes, bytearrays;
 
-* functions defined at the top level of a module (using :keyword:`def`, not
-  :keyword:`lambda`)
+* tuples, lists, sets, and dictionaries containing only picklable objects;
 
-* built-in functions defined at the top level of a module
+* functions (built-in and user-defined) defined at the top level of a module
+  (using :keyword:`def`, not :keyword:`lambda`);
 
-* classes that are defined at the top level of a module
+* classes defined at the top level of a module;
 
 * instances of such classes whose the result of calling :meth:`__getstate__`
   is picklable  (see section :ref:`pickle-inst` for details).
@@ -519,14 +517,14 @@ structure may exceed the maximum recursion depth, a :exc:`RecursionError` will b
 raised in this case.  You can carefully raise this limit with
 :func:`sys.setrecursionlimit`.
 
-Note that functions (built-in and user-defined) are pickled by "fully qualified"
-name reference, not by value. [#]_  This means that only the function name is
+Note that functions (built-in and user-defined) are pickled by fully qualified
+name, not by value. [#]_  This means that only the function name is
 pickled, along with the name of the module the function is defined in.  Neither
 the function's code, nor any of its function attributes are pickled.  Thus the
 defining module must be importable in the unpickling environment, and the module
 must contain the named object, otherwise an exception will be raised. [#]_
 
-Similarly, classes are pickled by named reference, so the same restrictions in
+Similarly, classes are pickled by fully qualified name, so the same restrictions in
 the unpickling environment apply.  Note that none of the class's code or data is
 pickled, so in the following example the class attribute ``attr`` is not
 restored in the unpickling environment::
@@ -536,7 +534,7 @@ restored in the unpickling environment::
 
    picklestring = pickle.dumps(Foo)
 
-These restrictions are why picklable functions and classes must be defined in
+These restrictions are why picklable functions and classes must be defined at
 the top level of a module.
 
 Similarly, when class instances are pickled, their class's code and data are not
@@ -568,7 +566,7 @@ implementation of this behaviour::
    def save(obj):
        return (obj.__class__, obj.__dict__)
 
-   def load(cls, attributes):
+   def restore(cls, attributes):
        obj = cls.__new__(cls)
        obj.__dict__.update(attributes)
        return obj
@@ -807,14 +805,15 @@ the code ::
    f = io.BytesIO()
    p = MyPickler(f)
 
-does the same, but all instances of ``MyPickler`` will by default
-share the same dispatch table.  The equivalent code using the
-:mod:`copyreg` module is ::
+does the same but all instances of ``MyPickler`` will by default
+share the private dispatch table.  On the other hand, the code ::
 
    copyreg.pickle(SomeClass, reduce_SomeClass)
    f = io.BytesIO()
    p = pickle.Pickler(f)
 
+modifies the global dispatch table shared by all users of the :mod:`copyreg` module.
+
 .. _pickle-state:
 
 Handling Stateful Objects
@@ -1117,7 +1116,7 @@ Here is an example of an unpickler allowing only few safe classes from the
        """Helper function analogous to pickle.loads()."""
        return RestrictedUnpickler(io.BytesIO(s)).load()
 
-A sample usage of our unpickler working has intended::
+A sample usage of our unpickler working as intended::
 
     >>> restricted_loads(pickle.dumps([1, 2, range(15)]))
     [1, 2, range(0, 15)]
@@ -1161,7 +1160,7 @@ For the simplest code, use the :func:`dump` and :func:`load` functions. ::
 
    # An arbitrary collection of objects supported by pickle.
    data = {
-       'a': [1, 2.0, 3, 4+6j],
+       'a': [1, 2.0, 3+4j],
        'b': ("character string", b"byte string"),
        'c': {None, True, False}
    }
@@ -1217,6 +1216,6 @@ The following example reads the resulting pickled data. ::
    operations.
 
 .. [#] The limitation on alphanumeric characters is due to the fact
-   the persistent IDs, in protocol 0, are delimited by the newline
+   that persistent IDs in protocol 0 are delimited by the newline
    character.  Therefore if any kind of newline characters occurs in
-   persistent IDs, the resulting pickle will become unreadable.
+   persistent IDs, the resulting pickled data will become unreadable.

Doc/library/pkgutil.rst

@@ -26,7 +26,7 @@ support.
       __path__ = extend_path(__path__, __name__)
 
    This will add to the package's ``__path__`` all subdirectories of directories
-   on ``sys.path`` named after the package.  This is useful if one wants to
+   on :data:`sys.path` named after the package.  This is useful if one wants to
    distribute different parts of a single logical package as multiple
    directories.
 
@@ -128,9 +128,9 @@ support.
 
    Yield :term:`finder` objects for the given module name.
 
-   If fullname contains a '.', the finders will be for the package
+   If fullname contains a ``'.'``, the finders will be for the package
    containing fullname, otherwise they will be all registered top level
-   finders (i.e. those on both sys.meta_path and sys.path_hooks).
+   finders (i.e. those on both :data:`sys.meta_path` and :data:`sys.path_hooks`).
 
    If the named module is in a package, that package is imported as a side
    effect of invoking this function.
@@ -145,7 +145,7 @@ support.
 .. function:: iter_modules(path=None, prefix='')
 
    Yields :class:`ModuleInfo` for all submodules on *path*, or, if
-   *path* is ``None``, all top-level modules on ``sys.path``.
+   *path* is ``None``, all top-level modules on :data:`sys.path`.
 
    *path* should be either ``None`` or a list of paths to look for modules in.
 

Doc/library/ssl.rst

@@ -1397,7 +1397,7 @@ SSL sockets also have the following additional methods and attributes:
 .. method:: SSLSocket.version()
 
    Return the actual SSL protocol version negotiated by the connection
-   as a string, or ``None`` is no secure connection is established.
+   as a string, or ``None`` if no secure connection is established.
    As of this writing, possible return values include ``"SSLv2"``,
    ``"SSLv3"``, ``"TLSv1"``, ``"TLSv1.1"`` and ``"TLSv1.2"``.
    Recent OpenSSL versions may define more return values.
@@ -1548,7 +1548,7 @@ to speed up repeated connections from the same clients.
    string must be the path to a single file in PEM format containing the
    certificate as well as any number of CA certificates needed to establish
    the certificate's authenticity.  The *keyfile* string, if present, must
-   point to a file containing the private key in.  Otherwise the private
+   point to a file containing the private key.  Otherwise the private
    key will be taken from *certfile* as well.  See the discussion of
    :ref:`ssl-certificates` for more information on how the certificate
    is stored in the *certfile*.

Doc/library/stdtypes.rst

@@ -2189,7 +2189,11 @@ expression support in the :mod:`re` module).
         >>> "they're bill's friends from the UK".title()
         "They'Re Bill'S Friends From The Uk"
 
-   A workaround for apostrophes can be constructed using regular expressions::
+   The :func:`string.capwords` function does not have this problem, as it
+   splits words on spaces only.
+
+   Alternatively, a workaround for apostrophes can be constructed using regular
+   expressions::
 
         >>> import re
         >>> def titlecase(s):

Doc/whatsnew/3.11.rst

@@ -833,6 +833,7 @@ Deprecated
   slated for removal in Python 3.13:
 
   * :mod:`aifc`
+  * :mod:`audioop`
 
   (Contributed by Brett Cannon in :issue:`47061`.)
 
@@ -1210,7 +1211,7 @@ Porting to Python 3.11
   explicitly include the header files after ``#include <Python.h>``.
   (Contributed by Victor Stinner in :issue:`45434`.)
 
-* The non-limited API files ``cellobject.h``, ``classobject.h``, ``context.h``,
+* The non-limited API files ``cellobject.h``, ``classobject.h``, ``code.h``, ``context.h``,
   ``funcobject.h``, ``genobject.h`` and ``longintrepr.h`` have been moved to
   the ``Include/cpython`` directory. Moreover, the ``eval.h`` header file was
   removed. These files must not be included directly, as they are already

Include/Python.h

@@ -68,7 +68,7 @@
 #include "cpython/classobject.h"
 #include "fileobject.h"
 #include "pycapsule.h"
-#include "code.h"
+#include "cpython/code.h"
 #include "pyframe.h"
 #include "traceback.h"
 #include "sliceobject.h"

Include/code.h

@@ -6,61 +6,22 @@
 extern "C" {
 #endif
 
-#ifndef Py_LIMITED_API
-typedef struct {
-    double real;
-    double imag;
-} Py_complex;
-
-/* Operations on complex numbers from complexmodule.c */
-
-PyAPI_FUNC(Py_complex) _Py_c_sum(Py_complex, Py_complex);
-PyAPI_FUNC(Py_complex) _Py_c_diff(Py_complex, Py_complex);
-PyAPI_FUNC(Py_complex) _Py_c_neg(Py_complex);
-PyAPI_FUNC(Py_complex) _Py_c_prod(Py_complex, Py_complex);
-PyAPI_FUNC(Py_complex) _Py_c_quot(Py_complex, Py_complex);
-PyAPI_FUNC(Py_complex) _Py_c_pow(Py_complex, Py_complex);
-PyAPI_FUNC(double) _Py_c_abs(Py_complex);
-#endif
-
 /* Complex object interface */
 
-/*
-PyComplexObject represents a complex number with double-precision
-real and imaginary parts.
-*/
-#ifndef Py_LIMITED_API
-typedef struct {
-    PyObject_HEAD
-    Py_complex cval;
-} PyComplexObject;
-#endif
-
 PyAPI_DATA(PyTypeObject) PyComplex_Type;
 
 #define PyComplex_Check(op) PyObject_TypeCheck(op, &PyComplex_Type)
 #define PyComplex_CheckExact(op) Py_IS_TYPE(op, &PyComplex_Type)
 
-#ifndef Py_LIMITED_API
-PyAPI_FUNC(PyObject *) PyComplex_FromCComplex(Py_complex);
-#endif
 PyAPI_FUNC(PyObject *) PyComplex_FromDoubles(double real, double imag);
 
 PyAPI_FUNC(double) PyComplex_RealAsDouble(PyObject *op);
 PyAPI_FUNC(double) PyComplex_ImagAsDouble(PyObject *op);
-#ifndef Py_LIMITED_API
-PyAPI_FUNC(Py_complex) PyComplex_AsCComplex(PyObject *op);
-#endif
 
-/* Format the object based on the format_spec, as defined in PEP 3101
-   (Advanced String Formatting). */
 #ifndef Py_LIMITED_API
-PyAPI_FUNC(int) _PyComplex_FormatAdvancedWriter(
-    _PyUnicodeWriter *writer,
-    PyObject *obj,
-    PyObject *format_spec,
-    Py_ssize_t start,
-    Py_ssize_t end);
+#  define Py_CPYTHON_COMPLEXOBJECT_H
+#  include "cpython/complexobject.h"
+#  undef Py_CPYTHON_COMPLEXOBJECT_H
 #endif
 
 #ifdef __cplusplus

Include/complexobject.h

@@ -1,5 +1,10 @@
-#ifndef Py_CPYTHON_CODE_H
-#  error "this header file must not be included directly"
+/* Definitions for bytecode */
+
+#ifndef Py_LIMITED_API
+#ifndef Py_CODE_H
+#define Py_CODE_H
+#ifdef __cplusplus
+extern "C" {
 #endif
 
 /* Each instruction in a code object is a fixed-width value,
@@ -204,3 +209,9 @@ PyAPI_FUNC(int) _PyCode_GetExtra(PyObject *code, Py_ssize_t index,
                                  void **extra);
 PyAPI_FUNC(int) _PyCode_SetExtra(PyObject *code, Py_ssize_t index,
                                  void *extra);
+
+#ifdef __cplusplus
+}
+#endif
+#endif  // !Py_CODE_H
+#endif  // !Py_LIMITED_API