From d7e65b434b7b838711c7df302e048731558f9a2c Mon Sep 17 00:00:00 2001 From: Inada Naoki Date: Mon, 2 Nov 2026 05:59:29 +0000 Subject: [PATCH 1/2] Docs: correct API descriptions and identifiers --- Doc/c-api/frame.rst | 2 -- Doc/c-api/gcsupport.rst | 2 +- Doc/c-api/gen.rst | 4 ++-- Doc/c-api/object.rst | 2 +- Doc/c-api/typeobj.rst | 2 +- Doc/howto/descriptor.rst | 2 +- Doc/howto/enum.rst | 2 +- Doc/howto/isolating-extensions.rst | 2 +- Doc/howto/perf_profiling.rst | 2 +- Doc/howto/remote_debugging.rst | 2 +- Doc/library/bz2.rst | 2 +- Doc/library/dis.rst | 2 +- Doc/library/textwrap.rst | 8 ++++---- Doc/reference/expressions.rst | 3 ++- 14 files changed, 18 insertions(+), 19 deletions(-) diff --git a/Doc/c-api/frame.rst b/Doc/c-api/frame.rst index 4159ff6e5965fbd..9e15804c941ce5b 100644 --- a/Doc/c-api/frame.rst +++ b/Doc/c-api/frame.rst @@ -99,8 +99,6 @@ See also :ref:`Reflection `. Get the *frame*'s :attr:`~frame.f_lasti` attribute. - Returns -1 if ``frame.f_lasti`` is ``None``. - .. versionadded:: 3.11 diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst index 0106fc115ff180d..2afade177674a2e 100644 --- a/Doc/c-api/gcsupport.rst +++ b/Doc/c-api/gcsupport.rst @@ -42,7 +42,7 @@ rules: .. warning:: If a type adds the Py_TPFLAGS_HAVE_GC, then it *must* implement at least a :c:member:`~PyTypeObject.tp_traverse` handler or explicitly use one - from its subclass or subclasses. + from a base class. When calling :c:func:`PyType_Ready` or some of the APIs that indirectly call it like :c:func:`PyType_FromSpecWithBases` or diff --git a/Doc/c-api/gen.rst b/Doc/c-api/gen.rst index 88c3cc31186826a..707bfdf2412d934 100644 --- a/Doc/c-api/gen.rst +++ b/Doc/c-api/gen.rst @@ -6,8 +6,8 @@ Generator Objects ----------------- Generator objects are what Python uses to implement generator iterators. They -are normally created by iterating over a function that yields values, rather -than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`. +are normally created by calling a generator function, rather than explicitly +calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`. .. c:type:: PyGenObject diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index eedeb180c6b7606..de73cd4c9342a27 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -423,7 +423,7 @@ Object Protocol If *cls* has a :meth:`~type.__subclasscheck__` method, it will be called to determine the subclass status as described in :pep:`3119`. Otherwise, *derived* is a subclass of *cls* if it is a direct or indirect subclass, - i.e. contained in :attr:`cls.__mro__ `. + i.e. if *cls* is contained in :attr:`derived.__mro__ `. Normally only class objects, i.e. instances of :class:`type` or a derived class, are considered classes. However, objects can override this by having diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index ee6df73a105d85e..56dd0bd32470cbc 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -2527,7 +2527,7 @@ and :c:data:`PyType_Type` effectively act as defaults.) Specifically, if *type* uses the default metaclass, ``type->tp_vectorcall`` must behave the same as - :c:expr:`PyType_Type->tp_call`, which: + ``Py_TYPE(type)->tp_call``, which: - calls ``type->tp_new``, diff --git a/Doc/howto/descriptor.rst b/Doc/howto/descriptor.rst index 7233898860ada14..801d76dd80aabfd 100644 --- a/Doc/howto/descriptor.rst +++ b/Doc/howto/descriptor.rst @@ -1754,7 +1754,7 @@ At this point, the metaclass has loaded member objects for *x* and *y*:: >>> isinstance(vars(H)['y'], Member) True -When instances are created, they have a ``slot_values`` list where the +When instances are created, they have a ``_slotvalues`` list where the attributes are stored: .. doctest:: diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst index adb9dc9a4879eb5..d006bc842a8566c 100644 --- a/Doc/howto/enum.rst +++ b/Doc/howto/enum.rst @@ -913,7 +913,7 @@ Some rules: :class:`~dataclasses.dataclass` 6. %-style formatting: ``%s`` and ``%r`` call the :class:`Enum` class's :meth:`~object.__str__` and :meth:`~object.__repr__` respectively; other codes (such as - ``%i`` or ``%h`` for IntEnum) treat the enum member as its mixed-in type. + ``%i`` or ``%x`` for IntEnum) treat the enum member as its mixed-in type. 7. :ref:`Formatted string literals `, :meth:`str.format`, and :func:`format` will use the enum's :meth:`~object.__str__` method. diff --git a/Doc/howto/isolating-extensions.rst b/Doc/howto/isolating-extensions.rst index 6092c75f48fdef0..302c15528d5ef31 100644 --- a/Doc/howto/isolating-extensions.rst +++ b/Doc/howto/isolating-extensions.rst @@ -530,7 +530,7 @@ and the corresponding :c:type:`PyCMethod` signature:: PyTypeObject *defining_class, // defining class PyObject *const *args, // C array of arguments Py_ssize_t nargs, // length of "args" - PyObject *kwnames) // NULL, or dict of keyword arguments + PyObject *kwnames) // NULL, or tuple of keyword argument names Once you have the defining class, call :c:func:`PyType_GetModuleState` to get the state of its associated module. diff --git a/Doc/howto/perf_profiling.rst b/Doc/howto/perf_profiling.rst index 5565f99b244f11b..f6400e884144def 100644 --- a/Doc/howto/perf_profiling.rst +++ b/Doc/howto/perf_profiling.rst @@ -273,7 +273,7 @@ or using the environment variable:: ``perf inject --jit`` command will read ``perf.data``, automatically pick up the perf dump file that Python creates (in -``/tmp/perf-$PID.dump``), and then create ``perf.jit.data`` which merges all the +``/tmp/jit-$PID.dump``), and then create ``perf.jit.data`` which merges all the JIT information together. It should also create a lot of ``jitted-XXXX-N.so`` files in the current directory which are ELF images for all the JIT trampolines that were created by Python. diff --git a/Doc/howto/remote_debugging.rst b/Doc/howto/remote_debugging.rst index f5f45c399ae1fff..278de58ff489da6 100644 --- a/Doc/howto/remote_debugging.rst +++ b/Doc/howto/remote_debugging.rst @@ -98,7 +98,7 @@ necessary entitlement and add it to the Python binary: codesign --sign - --entitlements get-task-allow.plist path/to/bin/python3 where ``path/to/bin/python3`` is the path to your Python binary, which you can -find by e.g. running ``which python3`` or evaluating ``sys.base_executable`` at +find by e.g. running ``which python3`` or evaluating ``sys._base_executable`` at the Python REPL. (These instructions are for a non-framework build of Python. Framework builds may need to be configured differently.) diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst index e52565dd4bb0a77..5cec2fc4fb8010e 100644 --- a/Doc/library/bz2.rst +++ b/Doc/library/bz2.rst @@ -277,7 +277,7 @@ Incremental (de)compression .. attribute:: needs_input ``False`` if the :meth:`.decompress` method can provide more - decompressed data before requiring new uncompressed input. + decompressed data before requiring new compressed input. .. versionadded:: 3.5 diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 7cfa713f9d0d403..5a93a328d487289 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -1299,7 +1299,7 @@ iterations of the loop. * the global ``super`` With respect to its argument, it works similarly to :opcode:`LOAD_ATTR`, - except that ``namei`` is shifted left by 2 bits instead of 1. + except that ``namei`` is shifted right by 2 bits instead of 1. The low bit of ``namei`` signals to attempt a method load, as with :opcode:`LOAD_ATTR`, which results in pushing ``NULL`` and the loaded method. diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst index d12968dee91f3c3..93a8c98f0667aa8 100644 --- a/Doc/library/textwrap.rst +++ b/Doc/library/textwrap.rst @@ -250,10 +250,10 @@ hyphenated words; only then will long words be broken if necessary, unless :attr:`fix_sentence_endings` is false by default. - Since the sentence detection algorithm relies on ``string.lowercase`` for - the definition of "lowercase letter", and a convention of using two spaces - after a period to separate sentences on the same line, it is specific to - English-language texts. + Since the sentence detection algorithm defines "lowercase letter" using + the characters in ``string.ascii_lowercase``, and relies on a convention + of using two spaces after a period to separate sentences on the same line, + it is specific to English-language texts. .. attribute:: break_long_words diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 558f94e65f6c3fc..b9390055d571d25 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -1273,7 +1273,8 @@ This *finalizer* may be registered by calling :func:`sys.set_asyncgen_hooks`. When first iterated over, an asynchronous generator-iterator will store the registered *finalizer* to be called upon finalization. For a reference example of a *finalizer* method see the implementation of -``asyncio.Loop.shutdown_asyncgens`` in :source:`Lib/asyncio/base_events.py`. +``asyncio.BaseEventLoop.shutdown_asyncgens`` in +:source:`Lib/asyncio/base_events.py`. The expression ``yield from `` is a syntax error when used in an asynchronous generator function. From bb6a6943a459aaac80d343704ddc4184aa06220b Mon Sep 17 00:00:00 2001 From: Inada Naoki Date: Mon, 2 Nov 2026 08:46:56 +0000 Subject: [PATCH 2/2] Docs: clarify asynchronous generator finalization --- Doc/library/sys.rst | 2 +- Doc/reference/expressions.rst | 24 +++++++++++------------- 2 files changed, 12 insertions(+), 14 deletions(-) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 1bc70f12de01c20..33de85b04f4b0ea 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -2061,7 +2061,7 @@ always available. Unless explicitly noted otherwise, all variables are read-only .. versionadded:: 3.6 See :pep:`525` for more details, and for a reference example of a *finalizer* method see the implementation of - ``asyncio.Loop.shutdown_asyncgens`` in + ``asyncio.BaseEventLoop._asyncgen_finalizer_hook`` in :source:`Lib/asyncio/base_events.py` .. note:: diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index b9390055d571d25..dba85db67b65e27 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -1249,8 +1249,7 @@ If an asynchronous generator happens to exit early by :keyword:`break`, the call task being cancelled, or other exceptions, the generator's async cleanup code will run and possibly raise exceptions or access context variables in an unexpected context--perhaps after the lifetime of tasks it depends, or -during the event loop shutdown when the async-generator garbage collection hook -is called. +during the event loop shutdown. To prevent this, the caller must explicitly close the async generator by calling :meth:`~agen.aclose` method to finalize the generator and ultimately detach it from the event loop. @@ -1263,17 +1262,16 @@ construct could result in a failure to execute pending :keyword:`finally` clauses. In this case, it is the responsibility of the event loop or scheduler running the asynchronous generator to call the asynchronous generator-iterator's :meth:`~agen.aclose` method and run the resulting -coroutine object, thus allowing any pending :keyword:`!finally` clauses -to execute. - -To take care of finalization upon event loop termination, an event loop should -define a *finalizer* function which takes an asynchronous generator-iterator and -presumably calls :meth:`~agen.aclose` and executes the coroutine. -This *finalizer* may be registered by calling :func:`sys.set_asyncgen_hooks`. -When first iterated over, an asynchronous generator-iterator will store the -registered *finalizer* to be called upon finalization. For a reference example -of a *finalizer* method see the implementation of -``asyncio.BaseEventLoop.shutdown_asyncgens`` in +awaitable, thus allowing any pending :keyword:`!finally` clauses to execute. + +To handle finalization when an asynchronous generator is about to be garbage +collected, an event loop should define a *finalizer* function which takes an +asynchronous generator-iterator and schedules the awaitable returned by +:meth:`~agen.aclose`. This *finalizer* may be registered by calling +:func:`sys.set_asyncgen_hooks`. When first iterated over, an asynchronous +generator-iterator will store the registered *finalizer* to be called upon +finalization. For a reference example of a *finalizer* method see the +implementation of ``asyncio.BaseEventLoop._asyncgen_finalizer_hook`` in :source:`Lib/asyncio/base_events.py`. The expression ``yield from `` is a syntax error when used in an