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

Author: Fidget-Spinner

Doc/extending/extending.rst

@@ -204,17 +204,32 @@ value must be in a particular range or must satisfy other conditions,
 :c:data:`PyExc_ValueError` is appropriate.
 
 You can also define a new exception that is unique to your module.
-For this, you can declare a static global object variable at the beginning
-of the file::
+The simplest way to do this is to declare a static global object variable at
+the beginning of the file::
 
-   static PyObject *SpamError;
+   static PyObject *SpamError = NULL;
 
-and initialize it with an exception object in the module's
+and initialize it by calling :c:func:`PyErr_NewException` in the module's
 :c:data:`Py_mod_exec` function (:c:func:`!spam_module_exec`)::
 
+   SpamError = PyErr_NewException("spam.error", NULL, NULL);
+
+Since :c:data:`!SpamError` is a global variable, it will be overwitten every time
+the module is reinitialized, when the :c:data:`Py_mod_exec` function is called.
+
+For now, let's avoid the issue: we will block repeated initialization by raising an
+:py:exc:`ImportError`::
+
+   static PyObject *SpamError = NULL;
+
    static int
    spam_module_exec(PyObject *m)
    {
+       if (SpamError != NULL) {
+           PyErr_SetString(PyExc_ImportError,
+                           "cannot initialize spam module more than once");
+           return -1;
+       }
        SpamError = PyErr_NewException("spam.error", NULL, NULL);
        if (PyModule_AddObjectRef(m, "SpamError", SpamError) < 0) {
            return -1;
@@ -253,6 +268,11 @@ needed to ensure that it will not be discarded, causing :c:data:`!SpamError` to
 become a dangling pointer. Should it become a dangling pointer, C code which
 raises the exception could cause a core dump or other unintended side effects.
 
+For now, the :c:func:`Py_DECREF` call to remove this reference is missing.
+Even when the Python interpreter shuts down, the global :c:data:`!SpamError`
+variable will not be garbage-collected. It will "leak".
+We did, however, ensure that this will happen at most once per process.
+
 We discuss the use of :c:macro:`PyMODINIT_FUNC` as a function return type later in this
 sample.
 

Doc/library/logging.handlers.rst

@@ -352,6 +352,10 @@ module, supports rotation of disk log files.
       Outputs the record to the file, catering for rollover as described
       previously.
 
+   .. method:: shouldRollover(record)
+
+      See if the supplied record would cause the file to exceed the configured size limit.
+
 .. _timed-rotating-file-handler:
 
 TimedRotatingFileHandler
@@ -459,7 +463,11 @@ timed intervals.
    .. method:: getFilesToDelete()
 
       Returns a list of filenames which should be deleted as part of rollover. These
-      are the absolute paths of the oldest backup log files written by the handler.
+
+   .. method:: shouldRollover(record)
+
+      See if enough time has passed for a rollover to occur and if it has, compute
+      the next rollover time.
 
 .. _socket-handler:
 

Doc/library/math.rst

@@ -10,8 +10,8 @@
 
 --------------
 
-This module provides access to the mathematical functions defined by the C
-standard.
+This module provides access to common mathematical functions and constants,
+including those defined by the C standard.
 
 These functions cannot be used with complex numbers; use the functions of the
 same name from the :mod:`cmath` module if you require support for complex

Doc/library/stdtypes.rst

@@ -1214,6 +1214,8 @@ accepts integers that meet the value restriction ``0 <= x <= 255``).
 | ``s[i] = x``                 | item *i* of *s* is replaced by |                     |
 |                              | *x*                            |                     |
 +------------------------------+--------------------------------+---------------------+
+| ``del s[i]``                 | removes item *i* of *s*        |                     |
++------------------------------+--------------------------------+---------------------+
 | ``s[i:j] = t``               | slice of *s* from *i* to *j*   |                     |
 |                              | is replaced by the contents of |                     |
 |                              | the iterable *t*               |                     |

Doc/library/typing.rst

@@ -3530,28 +3530,32 @@ Constant
 .. data:: TYPE_CHECKING
 
    A special constant that is assumed to be ``True`` by 3rd party static
-   type checkers. It is ``False`` at runtime.
+   type checkers. It's ``False`` at runtime.
+
+   A module which is expensive to import, and which only contain types
+   used for typing annotations, can be safely imported inside an
+   ``if TYPE_CHECKING:`` block.  This prevents the module from actually
+   being imported at runtime; annotations aren't eagerly evaluated
+   (see :pep:`649`) so using undefined symbols in annotations is
+   harmless--as long as you don't later examine them.
+   Your static type analysis tool will set ``TYPE_CHECKING`` to
+   ``True`` during static type analysis, which means the module will
+   be imported and the types will be checked properly during such analysis.
 
    Usage::
 
       if TYPE_CHECKING:
           import expensive_mod
 
-      def fun(arg: 'expensive_mod.SomeType') -> None:
+      def fun(arg: expensive_mod.SomeType) -> None:
           local_var: expensive_mod.AnotherType = other_fun()
 
-   The first type annotation must be enclosed in quotes, making it a
-   "forward reference", to hide the ``expensive_mod`` reference from the
-   interpreter runtime.  Type annotations for local variables are not
-   evaluated, so the second annotation does not need to be enclosed in quotes.
-
-   .. note::
-
-      If ``from __future__ import annotations`` is used,
-      annotations are not evaluated at function definition time.
-      Instead, they are stored as strings in ``__annotations__``.
-      This makes it unnecessary to use quotes around the annotation
-      (see :pep:`563`).
+   If you occasionally need to examine type annotations at runtime
+   which may contain undefined symbols, use
+   :meth:`annotationlib.get_annotations` with a ``format`` parameter
+   of :attr:`annotationlib.Format.STRING` or
+   :attr:`annotationlib.Format.FORWARDREF` to safely retrieve the
+   annotations without raising :exc:`NameError`.
 
    .. versionadded:: 3.5.2
 

Doc/tools/extensions/audit_events.py

@@ -13,7 +13,7 @@
 from sphinx.util.docutils import SphinxDirective
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterator, Set
 
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
@@ -33,7 +33,7 @@
 class AuditEvents:
     def __init__(self) -> None:
         self.events: dict[str, list[str]] = {}
-        self.sources: dict[str, list[tuple[str, str]]] = {}
+        self.sources: dict[str, set[tuple[str, str]]] = {}
 
     def __iter__(self) -> Iterator[tuple[str, list[str], tuple[str, str]]]:
         for name, args in self.events.items():
@@ -47,7 +47,7 @@ def add_event(
             self._check_args_match(name, args)
         else:
             self.events[name] = args
-        self.sources.setdefault(name, []).append(source)
+        self.sources.setdefault(name, set()).add(source)
 
     def _check_args_match(self, name: str, args: list[str]) -> None:
         current_args = self.events[name]
@@ -69,11 +69,11 @@ def _check_args_match(self, name: str, args: list[str]) -> None:
             return
 
     def id_for(self, name) -> str:
-        source_count = len(self.sources.get(name, ()))
+        source_count = len(self.sources.get(name, set()))
         name_clean = re.sub(r"\W", "_", name)
         return f"audit_event_{name_clean}_{source_count}"
 
-    def rows(self) -> Iterator[tuple[str, list[str], list[tuple[str, str]]]]:
+    def rows(self) -> Iterator[tuple[str, list[str], Set[tuple[str, str]]]]:
         for name in sorted(self.events.keys()):
             yield name, self.events[name], self.sources[name]
 
@@ -218,7 +218,7 @@ def _make_row(
         docname: str,
         name: str,
         args: list[str],
-        sources: list[tuple[str, str]],
+        sources: Set[tuple[str, str]],
     ) -> nodes.row:
         row = nodes.row()
         name_node = nodes.paragraph("", nodes.Text(name))
@@ -233,7 +233,7 @@ def _make_row(
         row += nodes.entry("", args_node)
 
         backlinks_node = nodes.paragraph()
-        backlinks = enumerate(sorted(set(sources)), start=1)
+        backlinks = enumerate(sorted(sources), start=1)
         for i, (doc, label) in backlinks:
             if isinstance(label, str):
                 ref = nodes.reference("", f"[{i}]", internal=True)
@@ -258,7 +258,7 @@ def setup(app: Sphinx):
     app.connect("env-purge-doc", audit_events_purge)
     app.connect("env-merge-info", audit_events_merge)
     return {
-        "version": "1.0",
+        "version": "2.0",
         "parallel_read_safe": True,
         "parallel_write_safe": True,
     }

Doc/whatsnew/3.15.rst

@@ -89,6 +89,13 @@ New modules
 Improved modules
 ================
 
+difflib
+-------
+
+* Improved the styling of HTML diff pages generated by the :class:`difflib.HtmlDiff`
+  class, and migrated the output to the HTML5 standard.
+  (Contributed by Jiahao Li in :gh:`134580`.)
+
 ssl
 ---
 

Include/internal/pycore_interp_structs.h

@@ -677,8 +677,11 @@ struct _Py_interp_cached_objects {
 
     /* object.__reduce__ */
     PyObject *objreduce;
+#ifndef Py_GIL_DISABLED
+    /* resolve_slotdups() */
     PyObject *type_slots_pname;
     pytype_slotdef *type_slots_ptrs[MAX_EQUIV];
+#endif
 
     /* TypeVar and related types */
     PyTypeObject *generic_type;

Include/internal/pycore_object.h

@@ -313,7 +313,7 @@ extern int _PyDict_CheckConsistency(PyObject *mp, int check_content);
 // Fast inlined version of PyType_HasFeature()
 static inline int
 _PyType_HasFeature(PyTypeObject *type, unsigned long feature) {
-    return ((FT_ATOMIC_LOAD_ULONG_RELAXED(type->tp_flags) & feature) != 0);
+    return ((type->tp_flags) & feature) != 0;
 }
 
 extern void _PyType_InitCache(PyInterpreterState *interp);

Include/internal/pycore_typeobject.h

@@ -134,7 +134,6 @@ extern int _PyType_AddMethod(PyTypeObject *, PyMethodDef *);
 extern void _PyType_SetFlagsRecursive(PyTypeObject *self, unsigned long mask,
                                       unsigned long flags);
 
-extern unsigned int _PyType_GetVersionForCurrentState(PyTypeObject *tp);
 PyAPI_FUNC(void) _PyType_SetVersion(PyTypeObject *tp, unsigned int version);
 PyTypeObject *_PyType_LookupByVersion(unsigned int version);