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

Author: Fidget-Spinner

Doc/deprecations/c-api-pending-removal-in-3.20.rst

@@ -1,6 +1,13 @@
 Pending removal in Python 3.20
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+* :c:func:`!_PyObject_CallMethodId`, :c:func:`!_PyObject_GetAttrId` and
+  :c:func:`!_PyUnicode_FromId` are deprecated since 3.15 and will be removed in
+  3.20. Instead, use :c:func:`PyUnicode_FromString()` and cache the result in
+  the module state, then call :c:func:`PyObject_CallMethod` or
+  :c:func:`PyObject_GetAttr`.
+  (Contributed by Victor Stinner in :gh:`141049`.)
+
 * The ``cval`` field in :c:type:`PyComplexObject` (:gh:`128813`).
   Use :c:func:`PyComplex_AsCComplex` and :c:func:`PyComplex_FromCComplex`
   to convert a Python complex number to/from the C :c:type:`Py_complex`

Doc/library/argparse.rst

@@ -645,6 +645,27 @@ are set.
 
 .. versionadded:: 3.14
 
+To highlight inline code in your description or epilog text, you can use
+backticks::
+
+   >>> parser = argparse.ArgumentParser(
+   ...     formatter_class=argparse.RawDescriptionHelpFormatter,
+   ...     epilog='''Examples:
+   ...   `python -m myapp --verbose`
+   ...   `python -m myapp --config settings.json`
+   ... ''')
+
+When colors are enabled, the text inside backticks will be displayed in a
+distinct color to help examples stand out. When colors are disabled, backticks
+are preserved as-is, which is readable in plain text.
+
+.. note::
+
+   Backtick markup only applies to description and epilog text. It does not
+   apply to individual argument ``help`` strings.
+
+.. versionadded:: 3.15
+
 
 The add_argument() method
 -------------------------

Doc/library/importlib.rst

@@ -210,6 +210,12 @@ Functions
        :exc:`ModuleNotFoundError` is raised when the module being reloaded lacks
        a :class:`~importlib.machinery.ModuleSpec`.
 
+   .. versionchanged:: next
+       If *module* is a lazy module that has not yet been materialized (i.e.,
+       loaded via :class:`importlib.util.LazyLoader` and not yet accessed),
+       calling :func:`reload` is a no-op and returns the module unchanged.
+       This prevents the reload from unintentionally triggering the lazy load.
+
    .. warning::
       This function is not thread-safe. Calling it from multiple threads can result
       in unexpected behavior. It's recommended to use the :class:`threading.Lock`

Doc/library/profiling.sampling.rst

@@ -191,6 +191,11 @@ production systems. The target process requires no modification and need not
 be restarted. The profiler attaches, collects samples for the specified
 duration, then detaches and produces output.
 
+::
+
+   python -m profiling.sampling attach --live 12345
+   python -m profiling.sampling attach --flamegraph -d 30 -o profile.html 12345
+
 On most systems, attaching to another process requires appropriate permissions.
 See :ref:`profiling-permissions` for platform-specific requirements.
 
@@ -529,6 +534,25 @@ I/O-bound or waiting. The function spends most of its time waiting for network,
 disk, locks, or sleep. CPU optimization won't help here; consider async I/O,
 connection pooling, or reducing wait time instead.
 
+.. code-block:: python
+
+   import time
+
+   def do_sleep():
+       time.sleep(2)
+
+   def do_compute():
+       sum(i**2 for i in range(1000000))
+
+   if __name__ == "__main__":
+       do_sleep()
+       do_compute()
+
+::
+
+   python -m profiling.sampling run --mode=wall script.py  # do_sleep ~98%, do_compute ~1%
+   python -m profiling.sampling run --mode=cpu script.py   # do_sleep absent, do_compute dominates
+
 
 GIL mode
 --------
@@ -553,6 +577,29 @@ GIL?" and "why are my other threads starving?" It can also be useful in
 single-threaded programs to distinguish Python execution time from time spent
 in C extensions or I/O.
 
+.. code-block:: python
+
+   import hashlib
+
+   def hash_work():
+       # C extension - releases GIL during computation
+       for _ in range(200):
+           hashlib.sha256(b"data" * 250000).hexdigest()
+
+   def python_work():
+       # Pure Python - holds GIL during computation
+       for _ in range(3):
+           sum(i**2 for i in range(1000000))
+
+   if __name__ == "__main__":
+       hash_work()
+       python_work()
+
+::
+
+   python -m profiling.sampling run --mode=cpu script.py  # hash_work ~42%, python_work ~38%
+   python -m profiling.sampling run --mode=gil script.py  # hash_work ~5%, python_work ~60%
+
 
 Exception mode
 --------------
@@ -952,6 +999,25 @@ stack often shows event loop internals rather than the logical flow of your
 coroutines. Async-aware mode addresses this by tracking which task is running
 and presenting stacks that reflect the ``await`` chain.
 
+.. code-block:: python
+
+   import asyncio
+
+   async def fetch(url):
+       await asyncio.sleep(0.1)
+       return url
+
+   async def main():
+       for _ in range(50):
+           await asyncio.gather(fetch("a"), fetch("b"), fetch("c"))
+
+   if __name__ == "__main__":
+       asyncio.run(main())
+
+::
+
+   python -m profiling.sampling run --async-aware --flamegraph -o out.html script.py
+
 .. note::
 
    Async-aware profiling requires the target process to have the :mod:`asyncio`

Doc/library/typing.rst

@@ -2869,8 +2869,8 @@ ABCs and Protocols for working with I/O
 ---------------------------------------
 
 .. class:: IO[AnyStr]
-           TextIO[AnyStr]
-           BinaryIO[AnyStr]
+           TextIO
+           BinaryIO
 
    Generic class ``IO[AnyStr]`` and its subclasses ``TextIO(IO[str])``
    and ``BinaryIO(IO[bytes])``

Doc/whatsnew/3.15.rst

@@ -423,6 +423,10 @@ argparse
   default to ``True``. This enables suggestions for mistyped arguments by default.
   (Contributed by Jakob Schluse in :gh:`140450`.)
 
+* Added backtick markup support in description and epilog text to highlight
+  inline code when color output is enabled.
+  (Contributed by Savannah Ostrowski in :gh:`142390`.)
+
 calendar
 --------
 
@@ -1210,6 +1214,13 @@ Deprecated C APIs
   use the :c:type:`PyBytesWriter` API instead.
   (Contributed by Victor Stinner in :gh:`129813`.)
 
+* :c:func:`!_PyObject_CallMethodId`, :c:func:`!_PyObject_GetAttrId` and
+  :c:func:`!_PyUnicode_FromId` are deprecated since 3.15 and will be removed in
+  3.20. Instead, use :c:func:`PyUnicode_FromString()` and cache the result in
+  the module state, then call :c:func:`PyObject_CallMethod` or
+  :c:func:`PyObject_GetAttr`.
+  (Contributed by Victor Stinner in :gh:`141049`.)
+
 * Deprecate :c:member:`~PyComplexObject.cval` field of the
   :c:type:`PyComplexObject` type.
   Use :c:func:`PyComplex_AsCComplex` and :c:func:`PyComplex_FromCComplex`

Include/cpython/abstract.h

@@ -6,7 +6,7 @@
 
 /* Like PyObject_CallMethod(), but expect a _Py_Identifier*
    as the method name. */
-PyAPI_FUNC(PyObject*) _PyObject_CallMethodId(
+Py_DEPRECATED(3.15) PyAPI_FUNC(PyObject*) _PyObject_CallMethodId(
     PyObject *obj,
     _Py_Identifier *name,
     const char *format, ...);

Include/cpython/object.h

@@ -300,7 +300,7 @@ PyAPI_FUNC(void) PyUnstable_Object_Dump(PyObject *);
 // Alias for backward compatibility
 #define _PyObject_Dump PyUnstable_Object_Dump
 
-PyAPI_FUNC(PyObject*) _PyObject_GetAttrId(PyObject *, _Py_Identifier *);
+Py_DEPRECATED(3.15) PyAPI_FUNC(PyObject*) _PyObject_GetAttrId(PyObject *, _Py_Identifier *);
 
 PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *);
 PyAPI_FUNC(void) PyObject_CallFinalizer(PyObject *);

Include/cpython/unicodeobject.h

@@ -778,4 +778,4 @@ static inline int Py_UNICODE_ISALNUM(Py_UCS4 ch) {
 
 // Return an interned Unicode object for an Identifier; may fail if there is no
 // memory.
-PyAPI_FUNC(PyObject*) _PyUnicode_FromId(_Py_Identifier*);
+Py_DEPRECATED(3.15) PyAPI_FUNC(PyObject*) _PyUnicode_FromId(_Py_Identifier*);