From 1ba202c36a750d2634328e0800eccde4470e2140 Mon Sep 17 00:00:00 2001 From: Inada Naoki Date: Mon, 2 Nov 2026 11:53:14 +0900 Subject: [PATCH] Docs: fix API names, references, and examples (GH-161072) (cherry picked from commit 4594f5a685aa5e491bcbb80e5f8d43a5838e6649) Co-authored-by: Inada Naoki Co-authored-by: Stan Ulbrych --- Doc/c-api/init_config.rst | 4 ++-- Doc/c-api/interp-lifecycle.rst | 6 +++--- Doc/c-api/long.rst | 2 +- Doc/c-api/module.rst | 2 +- Doc/c-api/slots.rst | 2 +- Doc/c-api/type.rst | 6 +++--- Doc/extending/newtypes.rst | 4 ++-- Doc/howto/instrumentation.rst | 2 +- Doc/library/cmd.rst | 6 +++--- Doc/library/configparser.rst | 2 +- Doc/library/ctypes.rst | 2 +- Doc/library/optparse.rst | 2 +- Doc/library/sys.rst | 2 +- Doc/library/time.rst | 2 +- Doc/library/tkinter.ttk.rst | 4 ++-- Doc/library/tomllib.rst | 2 +- Doc/library/unittest.mock-examples.rst | 2 +- Doc/library/unittest.rst | 6 +++--- Doc/library/venv.rst | 9 +++++---- Doc/library/xml.etree.elementtree.rst | 3 ++- Doc/library/zlib.rst | 2 +- Doc/using/configure.rst | 2 +- Doc/using/unix.rst | 2 +- Doc/whatsnew/2.2.rst | 11 ++++++----- Doc/whatsnew/2.6.rst | 4 ++-- Doc/whatsnew/3.2.rst | 2 +- Doc/whatsnew/3.8.rst | 7 ++++--- 27 files changed, 52 insertions(+), 48 deletions(-) diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index b59e2b8205d3048..de04611f49083c9 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -168,7 +168,7 @@ UTF-8 encoded string. See :ref:`Configuration Options `. Get a string list configuration option as an array of null-terminated UTF-8 encoded strings. - * Set *\*length* and *\*value*, and return ``0`` on success. + * Set *\*length* and *\*items*, and return ``0`` on success. * Set an error in *config* and return ``-1`` on error. On success, the string list must be released with @@ -1939,7 +1939,7 @@ PyConfig If equals to zero, ignore the :ref:`environment variables `. - Set to ``0`` by the :option:`-E` environment variable. + Set to ``0`` by the :option:`-E` command-line option. Default: ``1`` in Python config and ``0`` in isolated config. diff --git a/Doc/c-api/interp-lifecycle.rst b/Doc/c-api/interp-lifecycle.rst index fbc96d810ab3eff..15f98ec55ab961e 100644 --- a/Doc/c-api/interp-lifecycle.rst +++ b/Doc/c-api/interp-lifecycle.rst @@ -873,9 +873,9 @@ Process-wide parameters formed from the "official" name of the operating system, converted to lower case, followed by the major revision number; e.g., for Solaris 2.x, which is also known as SunOS 5.x, the value is ``'sunos5'``. On macOS, it is - ``'darwin'``. On Windows, it is ``'win'``. The returned string points into - static storage; the caller should not modify its value. The value is available - to Python code as ``sys.platform``. + ``'darwin'``. On Windows, it is ``'win32'``. The returned string points + into static storage; the caller should not modify its value. The value is + available to Python code as ``sys.platform``. .. c:function:: const char* Py_GetCopyright() diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index c0da28d557a2adc..a200ff667193bd4 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -596,7 +596,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. Macro for converting a Python integer into a process identifier. This can be defined as an alias to :c:func:`PyLong_AsLong`, - :c:func:`PyLong_FromLongLong`, or :c:func:`PyLong_AsInt`, depending on the + :c:func:`PyLong_AsLongLong`, or :c:func:`PyLong_AsInt`, depending on the size of the system's PID type. .. versionadded:: 3.2 diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index e4664ef815f567c..ffed4e21b7cb1ed 100644 --- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -338,7 +338,7 @@ Creation and initialization slots .. versionchanged:: 3.15 - The *slots* argument may be a ``ModuleSpec``-like object, rather than + The *spec* argument may be a ``ModuleSpec``-like object, rather than a true :py:class:`~importlib.machinery.ModuleSpec` instance. Note that previous versions of CPython did not enforce this. diff --git a/Doc/c-api/slots.rst b/Doc/c-api/slots.rst index 8472e8130feca16..abc869fb2631354 100644 --- a/Doc/c-api/slots.rst +++ b/Doc/c-api/slots.rst @@ -197,7 +197,7 @@ Convenience macros {NAME, PySlot_INTPTR, {0}, {(void*)(VALUE)}} #define PySlot_PTR_STATIC(NAME, VALUE) \ - {NAME, PySlot_INTPTR|Py_SLOT_STATIC, {0}, {(void*)(VALUE)}} + {NAME, PySlot_INTPTR|PySlot_STATIC, {0}, {(void*)(VALUE)}} .. versionadded:: 3.15 diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst index 8c9dbf8cdb11f02..e29b24f10d97618 100644 --- a/Doc/c-api/type.rst +++ b/Doc/c-api/type.rst @@ -672,7 +672,7 @@ but need extra remarks for use as slots: .. c:macro:: Py_tp_bases - :c:member:`Slot ID ` for type flags, used to set + :c:member:`Slot ID ` for base types, used to set :c:member:`PyTypeObject.tp_bases`. The slot can be set to a tuple of type objects which the newly created @@ -810,7 +810,7 @@ They will continue to work, but new features will be added as slots for :c:macro:`Py_tp_metaclass` slot. A non-``NULL`` *bases* argument corresponds to the :c:data:`Py_tp_bases` - slot, and takes precedence over :c:data:`Py_tp_bases` and + slot, and takes precedence over :c:data:`Py_tp_base` and :c:data:`Py_tp_bases` slots. A non-``NULL`` *module* argument corresponds to the @@ -981,7 +981,7 @@ They will continue to work, but new features will be added as slots for (PySlot){ .sl_id=tpslot.slot, .sl_flags=PySlot_INTPTR | sub_static, - .sl_ptr=tpslot.func + .sl_ptr=tpslot.pfunc } where ``sub_static`` is ``PySlot_STATIC`` if the slot requires diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst index cb0b66ce0fc77b6..0e2215bda9f847a 100644 --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -305,8 +305,8 @@ have an associated doc string simply by providing the text in the table. An application can use the introspection API to retrieve the descriptor from the class object, and get the doc string using its :attr:`~type.__doc__` attribute. -As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.ml_name` value -of ``NULL`` is required. +As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a +:c:member:`~PyMemberDef.name` value of ``NULL`` is required. .. XXX Descriptors need to be explained in more detail somewhere, but not here. diff --git a/Doc/howto/instrumentation.rst b/Doc/howto/instrumentation.rst index 8f0b0c41ea48617..c7ce5785047a6d5 100644 --- a/Doc/howto/instrumentation.rst +++ b/Doc/howto/instrumentation.rst @@ -457,7 +457,7 @@ available: .. object:: python.function.return(str filename, str funcname, int lineno, frameptr) - This probe point is the converse of ``python.function.return``, and + This probe point is the converse of ``python.function.entry``, and indicates that execution of a Python function has ended (either via ``return``, or via an exception). It is only triggered for pure-Python (bytecode) functions. diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst index e2ad5f9fd5a0912..bde946ca60a8073 100644 --- a/Doc/library/cmd.rst +++ b/Doc/library/cmd.rst @@ -110,15 +110,15 @@ A :class:`Cmd` instance has the following methods: undocumented commands. -.. method:: Cmd.onecmd(str) +.. method:: Cmd.onecmd(line) Interpret the argument as though it had been typed in response to the prompt. This may be overridden, but should not normally need to be; see the :meth:`precmd` and :meth:`postcmd` methods for useful execution hooks. The return value is a flag indicating whether interpretation of commands by the interpreter should stop. If there is a :meth:`!do_\*` method for the command - *str*, the return value of that method is returned, otherwise the return value - from the :meth:`default` method is returned. + *line*, the return value of that method is returned, otherwise the return + value from the :meth:`default` method is returned. .. method:: Cmd.emptyline() diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst index 4d720176fcc334a..ab5a7e32df42180 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -1251,7 +1251,7 @@ ConfigParser Objects Comments in the original configuration file are not preserved when writing the configuration back. What is considered a comment, depends on the given values for - *comment_prefix* and *inline_comment_prefix*. + *comment_prefixes* and *inline_comment_prefixes*. .. method:: remove_option(section, option) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index e0641421c346e4c..128912d7f42409c 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -2846,7 +2846,7 @@ These are the fundamental ctypes data types: Represents the C :c:expr:`unsigned long long` datatype. The constructor accepts an optional integer initializer; no overflow checking is done. On platforms where ``sizeof(long long) == sizeof(long)`` it is an alias - to :class:`c_long`. + to :class:`c_ulong`. .. class:: c_ushort diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index ac184224784c97c..b28a87f7c9523a2 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -1780,7 +1780,7 @@ where ``parser.values`` the object where option values are by default stored (an instance of - optparse.OptionValues). This lets callbacks use the same mechanism as the + optparse.Values). This lets callbacks use the same mechanism as the rest of :mod:`!optparse` for storing option values; you don't need to mess around with globals or closures. You can also access or modify the value(s) of any options already encountered on the command-line. diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 1d1228120a26694..aa4c576660ccb56 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -296,7 +296,7 @@ always available. Unless explicitly noted otherwise, all variables are read-only you might bind it to a function that expects additional arguments (positional and/or keyword). The built-in ``breakpoint()`` function passes its ``*args`` and ``**kws`` straight through. Whatever - ``breakpointhooks()`` returns is returned from ``breakpoint()``. + ``breakpointhook()`` returns is returned from ``breakpoint()``. The default implementation first consults the environment variable :envvar:`PYTHONBREAKPOINT`. If that is set to ``"0"`` then this function diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 992122e8e8e80bb..561c3cb643c99b7 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -678,7 +678,7 @@ Functions * - 5 - .. attribute:: tm_sec - - range [0, 61]; see :ref:`Note (2) ` in :func:`strftime` + - range [0, 61]; see :ref:`Note (3) ` in :func:`strftime` * - 6 - .. attribute:: tm_wday diff --git a/Doc/library/tkinter.ttk.rst b/Doc/library/tkinter.ttk.rst index e5c48ac62ef0846..eecbc3514f1eaf1 100644 --- a/Doc/library/tkinter.ttk.rst +++ b/Doc/library/tkinter.ttk.rst @@ -1493,8 +1493,8 @@ If you don't know the class name of a widget, use the method Example:: img1 = tkinter.PhotoImage(master=root, file='button.png') - img1 = tkinter.PhotoImage(master=root, file='button-pressed.png') - img1 = tkinter.PhotoImage(master=root, file='button-active.png') + img2 = tkinter.PhotoImage(master=root, file='button-pressed.png') + img3 = tkinter.PhotoImage(master=root, file='button-active.png') style = ttk.Style(root) style.element_create('Button.button', 'image', img1, ('pressed', img2), ('active', img3), diff --git a/Doc/library/tomllib.rst b/Doc/library/tomllib.rst index 0a6b9d9d9fad4d0..ad806d9abdd378b 100644 --- a/Doc/library/tomllib.rst +++ b/Doc/library/tomllib.rst @@ -177,7 +177,7 @@ Tables/dicts the source. Integers - TOML recommends supporting integers in ``range(−2**63, 2**63)``. + TOML recommends supporting integers in ``range(-2**63, 2**63)``. .. impl-detail:: :mod:`!tomllib` uses :ref:`Python's limit on integer string conversion diff --git a/Doc/library/unittest.mock-examples.rst b/Doc/library/unittest.mock-examples.rst index b8aa04b9ab246d1..da57f05edcf78fa 100644 --- a/Doc/library/unittest.mock-examples.rst +++ b/Doc/library/unittest.mock-examples.rst @@ -481,7 +481,7 @@ You can stack up multiple patch decorators using this pattern:: When you nest patch decorators the mocks are passed in to the decorated function in the same order they applied (the normal *Python* order that decorators are applied). This means from the bottom up, so in the example -above the mock for ``test_module.ClassName2`` is passed in first. +above the mock for ``package.module.ClassName2`` is passed in first. There is also :func:`patch.dict` for setting values in a dictionary just during a scope and restoring the dictionary to its original state when the test diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 745be80119b1d29..3910fcde8395b14 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -1071,7 +1071,7 @@ Test cases :meth:`assertWarns`. The test passes if *warning* is triggered and fails if it isn't. Any exception is an error. To catch any of a group of warnings, a tuple containing the warning - classes may be passed as *warnings*. + classes may be passed as *warning*. If only the *warning* and possibly the *msg* arguments are given, return a context manager so that the code under test can be written @@ -1135,8 +1135,8 @@ Test cases The context managers can be nested to test that multiple different warnings are emitted:: - with (self.assertWarns(SomeWarning, regex1), - self.assertWarns(OtherWarning, regex2)): + with (self.assertWarnsRegex(SomeWarning, regex1), + self.assertWarnsRegex(OtherWarning, regex2)): do_something() .. versionadded:: 3.2 diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 8bb267d5a0b9588..24c5687be781ac1 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -566,10 +566,11 @@ subclass which installs setuptools and pip into a created virtual environment:: arguments: a string indicating some progress, and a context indicating where the string is coming from. The context argument can have one of three values: - 'main', indicating that it is called from virtualize() - itself, and 'stdout' and 'stderr', which are obtained - by reading lines from the output streams of a subprocess - which is used to install the app. + 'main', indicating that it is called from + install_script() itself, and 'stdout' and 'stderr', + which are obtained by reading lines from the output + streams of a subprocess which is used to install + the app. If a callable is not specified, default progress information is output to sys.stderr. diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index c595fc0974a9d66..7e0fd6a31d1cdef 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -831,7 +831,8 @@ Here's an example that demonstrates use of the XInclude module. To include an XM By default, the **href** attribute is treated as a file name. You can use custom loaders to override this behaviour. Also note that the standard helper does not support XPointer syntax. -To process this file, load it as usual, and pass the root element to the :mod:`!xml.etree.ElementTree` module: +To process this file, load it as usual, and pass the root element to the +:mod:`xml.etree.ElementInclude` module: .. code-block:: python diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst index 266bf968e329b4a..4491c8ba8c3f7cb 100644 --- a/Doc/library/zlib.rst +++ b/Doc/library/zlib.rst @@ -297,7 +297,7 @@ Decompression objects support the following methods and attributes: .. method:: Decompress.decompress(data, /, max_length=0) Decompress *data*, returning a bytes object containing the uncompressed data - corresponding to at least part of the data in *string*. This data should be + corresponding to at least part of *data*. This data should be concatenated to the output produced by any preceding calls to the :meth:`decompress` method. Some of the input data may be preserved in internal buffers for later processing. diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 94fbd833f284a72..caa8eeebf123022 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -1065,7 +1065,7 @@ Linker options This option does nothing if ``--enable-shared`` is not used. - The default (when ``-enable-shared`` is used) is to link the Python + The default (when ``--enable-shared`` is used) is to link the Python interpreter against the built shared library. .. versionadded:: 3.15 diff --git a/Doc/using/unix.rst b/Doc/using/unix.rst index 829bdfe8b1121fd..b64b5e10584b6ca 100644 --- a/Doc/using/unix.rst +++ b/Doc/using/unix.rst @@ -179,7 +179,7 @@ Custom OpenSSL .. code-block:: shell-session $ curl -O https://www.openssl.org/source/openssl-VERSION.tar.gz - $ tar xzf openssl-VERSION + $ tar xzf openssl-VERSION.tar.gz $ pushd openssl-VERSION $ ./config \ --prefix=/usr/local/custom-openssl \ diff --git a/Doc/whatsnew/2.2.rst b/Doc/whatsnew/2.2.rst index 5c69e473af6d5b5..effa7b0bacd94a5 100644 --- a/Doc/whatsnew/2.2.rst +++ b/Doc/whatsnew/2.2.rst @@ -964,11 +964,12 @@ New and Improved Modules :rfc:`2104`. (Contributed by Gerhard Häring.) * Several functions that originally returned lengthy tuples now return - pseudo-sequences that still behave like tuples but also have mnemonic attributes such - as :attr:`!memberst_mtime` or :attr:`~time.struct_time.tm_year`. The enhanced functions include - :func:`~os.stat`, :func:`~os.fstat`, :func:`~os.statvfs`, and :func:`~os.fstatvfs` in the - :mod:`os` module, and :func:`~time.localtime`, :func:`~time.gmtime`, and :func:`~time.strptime` in - the :mod:`time` module. + pseudo-sequences that still behave like tuples but also have mnemonic + attributes such as :attr:`~os.stat_result.st_mtime` or + :attr:`~time.struct_time.tm_year`. The enhanced functions include + :func:`~os.stat`, :func:`~os.fstat`, :func:`~os.statvfs`, and + :func:`~os.fstatvfs` in the :mod:`os` module, and :func:`~time.localtime`, + :func:`~time.gmtime`, and :func:`~time.strptime` in the :mod:`time` module. For example, to obtain a file's size using the old tuples, you'd end up writing something like ``file_size = os.stat(filename)[stat.ST_SIZE]``, but now this can diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index d8c0677bc3cfce6..f17c3c7e4e1be3b 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -2565,8 +2565,8 @@ changes, or look through the Subversion logs for all the details. for the statement being timed and for the setup code. Two convenience functions were added for creating :class:`~timeit.Timer` instances: - ``repeat(stmt, setup, time, repeat, number)`` and - ``timeit(stmt, setup, time, number)`` create an instance and call + ``repeat(stmt, setup, timer, repeat, number)`` and + ``timeit(stmt, setup, timer, number)`` create an instance and call the corresponding method. (Contributed by Erik Demaine; :issue:`1533909`.) diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst index 4626dee3fee873a..f826be205e4e324 100644 --- a/Doc/whatsnew/3.2.rst +++ b/Doc/whatsnew/3.2.rst @@ -1596,7 +1596,7 @@ sqlite3 The :mod:`sqlite3` module was updated to pysqlite version 2.6.0. It has two new capabilities. -* The :attr:`!sqlite3.Connection.in_transit` attribute is true if there is an +* The :attr:`sqlite3.Connection.in_transaction` attribute is true if there is an active transaction for uncommitted changes. * The :meth:`sqlite3.Connection.enable_load_extension` and diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst index b6f375866496261..5f3fad1a1a51b50 100644 --- a/Doc/whatsnew/3.8.rst +++ b/Doc/whatsnew/3.8.rst @@ -908,9 +908,10 @@ for :deco:`property`, :deco:`classmethod`, and :deco:`staticmethod`:: io -- -In development mode (:option:`-X` ``env``) and in :ref:`debug build `, the -:class:`io.IOBase` finalizer now logs the exception if the ``close()`` method -fails. The exception is ignored silently by default in release build. +In development mode (:option:`-X` ``dev``) and in +:ref:`debug build `, the :class:`io.IOBase` finalizer now logs the +exception if the ``close()`` method fails. The exception is ignored silently +by default in release build. (Contributed by Victor Stinner in :issue:`18748`.)