[pull] main from python:main

Doc/c-api/allocation.rst

@@ -140,10 +140,6 @@ Allocating Objects on the Heap
       * :c:member:`~PyTypeObject.tp_alloc`
 
 
-.. c:function:: void PyObject_Del(void *op)
-
-   Same as :c:func:`PyObject_Free`.
-
 .. c:var:: PyObject _Py_NoneStruct
 
    Object which is visible in Python as ``None``.  This should only be accessed
@@ -156,3 +152,35 @@ Allocating Objects on the Heap
    :ref:`moduleobjects`
       To allocate and create extension modules.
 
+
+Deprecated aliases
+^^^^^^^^^^^^^^^^^^
+
+These are :term:`soft deprecated` aliases to existing functions and macros.
+They exist solely for backwards compatibility.
+
+
+.. list-table::
+   :widths: auto
+   :header-rows: 1
+
+   * * Deprecated alias
+     * Function
+   * * .. c:macro:: PyObject_NEW(type, typeobj)
+     * :c:macro:`PyObject_New`
+   * * .. c:macro:: PyObject_NEW_VAR(type, typeobj, n)
+     * :c:macro:`PyObject_NewVar`
+   * * .. c:macro:: PyObject_INIT(op, typeobj)
+     * :c:func:`PyObject_Init`
+   * * .. c:macro:: PyObject_INIT_VAR(op, typeobj, n)
+     * :c:func:`PyObject_InitVar`
+   * * .. c:macro:: PyObject_MALLOC(n)
+     * :c:func:`PyObject_Malloc`
+   * * .. c:macro:: PyObject_REALLOC(p, n)
+     * :c:func:`PyObject_Realloc`
+   * * .. c:macro:: PyObject_FREE(p)
+     * :c:func:`PyObject_Free`
+   * * .. c:macro:: PyObject_DEL(p)
+     * :c:func:`PyObject_Free`
+   * * .. c:macro:: PyObject_Del(p)
+     * :c:func:`PyObject_Free`

Doc/c-api/concrete.rst

@@ -115,5 +115,13 @@ Other Objects
    gen.rst
    coro.rst
    contextvars.rst
-   datetime.rst
    typehints.rst
+
+
+C API for extension modules
+===========================
+
+.. toctree::
+
+   curses.rst
+   datetime.rst

Doc/c-api/curses.rst

@@ -0,0 +1,138 @@
+.. highlight:: c
+
+Curses C API
+------------
+
+:mod:`curses` exposes a small C interface for extension modules.
+Consumers must include the header file :file:`py_curses.h` (which is not
+included by default by :file:`Python.h`) and :c:func:`import_curses` must
+be invoked, usually as part of the module initialisation function, to populate
+:c:var:`PyCurses_API`.
+
+.. warning::
+
+   Neither the C API nor the pure Python :mod:`curses` module are compatible
+   with subinterpreters.
+
+.. c:macro:: import_curses()
+
+   Import the curses C API. The macro does not need a semi-colon to be called.
+
+   On success, populate the :c:var:`PyCurses_API` pointer.
+
+   On failure, set :c:var:`PyCurses_API` to NULL and set an exception.
+   The caller must check if an error occurred via :c:func:`PyErr_Occurred`:
+
+   .. code-block::
+
+      import_curses();  // semi-colon is optional but recommended
+      if (PyErr_Occurred()) { /* cleanup */ }
+
+
+.. c:var:: void **PyCurses_API
+
+   Dynamically allocated object containing the curses C API.
+   This variable is only available once :c:macro:`import_curses` succeeds.
+
+   ``PyCurses_API[0]`` corresponds to :c:data:`PyCursesWindow_Type`.
+
+   ``PyCurses_API[1]``, ``PyCurses_API[2]``, and ``PyCurses_API[3]``
+   are pointers to predicate functions of type ``int (*)(void)``.
+
+   When called, these predicates return whether :func:`curses.setupterm`,
+   :func:`curses.initscr`, and :func:`curses.start_color` have been called
+   respectively.
+
+   See also the convenience macros :c:macro:`PyCursesSetupTermCalled`,
+   :c:macro:`PyCursesInitialised`, and :c:macro:`PyCursesInitialisedColor`.
+
+   .. note::
+
+      The number of entries in this structure is subject to changes.
+      Consider using :c:macro:`PyCurses_API_pointers` to check if
+      new fields are available or not.
+
+
+.. c:macro:: PyCurses_API_pointers
+
+   The number of accessible fields (``4``) in :c:var:`PyCurses_API`.
+   This number is incremented whenever new fields are added.
+
+
+.. c:var:: PyTypeObject PyCursesWindow_Type
+
+   The :ref:`heap type <heap-types>` corresponding to :class:`curses.window`.
+
+
+.. c:function:: int PyCursesWindow_Check(PyObject *op)
+
+   Return true if *op* is a :class:`curses.window` instance, false otherwise.
+
+
+The following macros are convenience macros expanding into C statements.
+In particular, they can only be used as ``macro;`` or ``macro``, but not
+``macro()`` or ``macro();``.
+
+.. c:macro:: PyCursesSetupTermCalled
+
+   Macro checking if :func:`curses.setupterm` has been called.
+
+   The macro expansion is roughly equivalent to:
+
+   .. code-block::
+
+      {
+          typedef int (*predicate_t)(void);
+          predicate_t was_setupterm_called = (predicate_t)PyCurses_API[1];
+          if (!was_setupterm_called()) {
+              return NULL;
+          }
+      }
+
+
+.. c:macro:: PyCursesInitialised
+
+   Macro checking if :func:`curses.initscr` has been called.
+
+   The macro expansion is roughly equivalent to:
+
+   .. code-block::
+
+      {
+          typedef int (*predicate_t)(void);
+          predicate_t was_initscr_called = (predicate_t)PyCurses_API[2];
+          if (!was_initscr_called()) {
+              return NULL;
+          }
+      }
+
+
+.. c:macro:: PyCursesInitialisedColor
+
+   Macro checking if :func:`curses.start_color` has been called.
+
+   The macro expansion is roughly equivalent to:
+
+   .. code-block::
+
+      {
+          typedef int (*predicate_t)(void);
+          predicate_t was_start_color_called = (predicate_t)PyCurses_API[3];
+          if (!was_start_color_called()) {
+              return NULL;
+          }
+      }
+
+
+Internal data
+-------------
+
+The following objects are exposed by the C API but should be considered
+internal-only.
+
+.. c:macro:: PyCurses_CAPSULE_NAME
+
+   Name of the curses capsule to pass to :c:func:`PyCapsule_Import`.
+
+   Internal usage only. Use :c:macro:`import_curses` instead.
+

Doc/c-api/exceptions.rst

@@ -788,6 +788,17 @@ Exception Classes
 Exception Objects
 =================
 
+.. c:function:: int PyExceptionInstance_Check(PyObject *op)
+
+   Return true if *op* is an instance of :class:`BaseException`, false
+   otherwise. This function always succeeds.
+
+
+.. c:macro:: PyExceptionInstance_Class(op)
+
+   Equivalent to :c:func:`Py_TYPE(op) <Py_TYPE>`.
+
+
 .. c:function:: PyObject* PyException_GetTraceback(PyObject *ex)
 
    Return the traceback associated with the exception as a new reference, as

Doc/c-api/veryhigh.rst

@@ -13,8 +13,9 @@ the interpreter.
 
 Several of these functions accept a start symbol from the grammar as a
 parameter.  The available start symbols are :c:data:`Py_eval_input`,
-:c:data:`Py_file_input`, and :c:data:`Py_single_input`.  These are described
-following the functions which accept them as parameters.
+:c:data:`Py_file_input`, :c:data:`Py_single_input`, and
+:c:data:`Py_func_type_input`.  These are described following the functions
+which accept them as parameters.
 
 Note also that several of these functions take :c:expr:`FILE*` parameters.  One
 particular issue which needs to be handled carefully is that the :c:type:`FILE`
@@ -183,8 +184,7 @@ the same library that the Python runtime is using.
    objects *globals* and *locals* with the compiler flags specified by
    *flags*.  *globals* must be a dictionary; *locals* can be any object
    that implements the mapping protocol.  The parameter *start* specifies
-   the start symbol and must one of the following:
-   :c:data:`Py_eval_input`, :c:data:`Py_file_input`, or :c:data:`Py_single_input`.
+   the start symbol and must one of the :ref:`available start symbols <start-symbols>`.
 
    Returns the result of executing the code as a Python object, or ``NULL`` if an
    exception was raised.
@@ -233,8 +233,8 @@ the same library that the Python runtime is using.
 
    Parse and compile the Python source code in *str*, returning the resulting code
    object.  The start symbol is given by *start*; this can be used to constrain the
-   code which can be compiled and should be :c:data:`Py_eval_input`,
-   :c:data:`Py_file_input`, or :c:data:`Py_single_input`.  The filename specified by
+   code which can be compiled and should be :ref:`available start symbols
+   <start-symbols>`.  The filename specified by
    *filename* is used to construct the code object and may appear in tracebacks or
    :exc:`SyntaxError` exception messages.  This returns ``NULL`` if the code
    cannot be parsed or compiled.
@@ -297,32 +297,6 @@ the same library that the Python runtime is using.
    true on success, false on failure.
 
 
-.. c:var:: int Py_eval_input
-
-   .. index:: single: Py_CompileString (C function)
-
-   The start symbol from the Python grammar for isolated expressions; for use with
-   :c:func:`Py_CompileString`.
-
-
-.. c:var:: int Py_file_input
-
-   .. index:: single: Py_CompileString (C function)
-
-   The start symbol from the Python grammar for sequences of statements as read
-   from a file or other source; for use with :c:func:`Py_CompileString`.  This is
-   the symbol to use when compiling arbitrarily long Python source code.
-
-
-.. c:var:: int Py_single_input
-
-   .. index:: single: Py_CompileString (C function)
-
-   The start symbol from the Python grammar for a single statement; for use with
-   :c:func:`Py_CompileString`. This is the symbol used for the interactive
-   interpreter loop.
-
-
 .. c:struct:: PyCompilerFlags
 
    This is the structure used to hold compiler flags.  In cases where code is only
@@ -366,3 +340,52 @@ the same library that the Python runtime is using.
    as :c:macro:`CO_FUTURE_ANNOTATIONS` to enable features normally
    selectable using :ref:`future statements <future>`.
    See :ref:`c_codeobject_flags` for a complete list.
+
+
+.. _start-symbols:
+
+Available start symbols
+^^^^^^^^^^^^^^^^^^^^^^^
+
+
+.. c:var:: int Py_eval_input
+
+   .. index:: single: Py_CompileString (C function)
+
+   The start symbol from the Python grammar for isolated expressions; for use with
+   :c:func:`Py_CompileString`.
+
+
+.. c:var:: int Py_file_input
+
+   .. index:: single: Py_CompileString (C function)
+
+   The start symbol from the Python grammar for sequences of statements as read
+   from a file or other source; for use with :c:func:`Py_CompileString`.  This is
+   the symbol to use when compiling arbitrarily long Python source code.
+
+
+.. c:var:: int Py_single_input
+
+   .. index:: single: Py_CompileString (C function)
+
+   The start symbol from the Python grammar for a single statement; for use with
+   :c:func:`Py_CompileString`. This is the symbol used for the interactive
+   interpreter loop.
+
+
+.. c:var:: int Py_func_type_input
+
+   .. index:: single: Py_CompileString (C function)
+
+   The start symbol from the Python grammar for a function type; for use with
+   :c:func:`Py_CompileString`. This is used to parse "signature type comments"
+   from :pep:`484`.
+
+   This requires the :c:macro:`PyCF_ONLY_AST` flag to be set.
+
+   .. seealso::
+      * :py:class:`ast.FunctionType`
+      * :pep:`484`
+
+   .. versionadded:: 3.8

Doc/c-api/weakref.rst

@@ -19,7 +19,14 @@ as much as it can.
 
 .. c:function:: int PyWeakref_CheckRef(PyObject *ob)
 
-   Return non-zero if *ob* is a reference object.  This function always succeeds.
+   Return non-zero if *ob* is a reference object or a subclass of the reference
+   type.  This function always succeeds.
+
+
+.. c:function:: int PyWeakref_CheckRefExact(PyObject *ob)
+
+   Return non-zero if *ob* is a reference object, but not a subclass of the
+   reference type.  This function always succeeds.
 
 
 .. c:function:: int PyWeakref_CheckProxy(PyObject *ob)

Doc/deprecations/pending-removal-in-3.17.rst

@@ -23,6 +23,12 @@ Pending removal in Python 3.17
     (Contributed by Shantanu Jain in :gh:`91896`.)
 
 
+* :mod:`encodings`:
+
+  - Passing non-ascii *encoding* names to :func:`encodings.normalize_encoding`
+    is deprecated and scheduled for removal in Python 3.17.
+    (Contributed by Stan Ulbrych in :gh:`136702`)
+
 * :mod:`typing`:
 
   - Before Python 3.14, old-style unions were implemented using the private class

Include/cpython/pyhash.h

@@ -7,15 +7,15 @@
 
 /* Parameters used for the numeric hash implementation.  See notes for
    _Py_HashDouble in Python/pyhash.c.  Numeric hashes are based on
-   reduction modulo the prime 2**_PyHASH_BITS - 1. */
+   reduction modulo the prime 2**PyHASH_BITS - 1. */
 
 #if SIZEOF_VOID_P >= 8
 #  define PyHASH_BITS 61
 #else
 #  define PyHASH_BITS 31
 #endif
 
-#define PyHASH_MODULUS (((size_t)1 << _PyHASH_BITS) - 1)
+#define PyHASH_MODULUS (((size_t)1 << PyHASH_BITS) - 1)
 #define PyHASH_INF 314159
 #define PyHASH_IMAG PyHASH_MULTIPLIER
 

Lib/email/_header_value_parser.py

@@ -796,6 +796,10 @@ def params(self):
                         value = urllib.parse.unquote(value, encoding='latin-1')
                     else:
                         try:
+                            # Explicitly look up the codec for warning generation, see gh-140030
+                            # Can be removed in 3.17
+                            import codecs
+                            codecs.lookup(charset)
                             value = value.decode(charset, 'surrogateescape')
                         except (LookupError, UnicodeEncodeError):
                             # XXX: there should really be a custom defect for