From d92c5fc181eabffa104e042c1a2b2d4e51f02dbc Mon Sep 17 00:00:00 2001 From: Inada Naoki Date: Mon, 2 Nov 2026 11:53:14 +0900 Subject: [PATCH] [3.14] 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/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/unittest.mock-examples.rst | 2 +- Doc/library/unittest.rst | 2 +- Doc/library/venv.rst | 9 +++++---- Doc/library/xml.etree.elementtree.rst | 3 ++- Doc/library/zlib.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 ++++--- 22 files changed, 43 insertions(+), 39 deletions(-) diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index edf6039b20ee5f..e4505369abed41 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 @@ -1936,7 +1936,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 82d13b7701c9b1..86ee3b65caee35 100644 --- a/Doc/c-api/interp-lifecycle.rst +++ b/Doc/c-api/interp-lifecycle.rst @@ -839,9 +839,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 6cd30831afad50..c450b05eb2bf82 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -589,7 +589,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/extending/newtypes.rst b/Doc/extending/newtypes.rst index 1627bbe1ab258b..878b452422ccc2 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 06c1ae40da5e67..1e1ba702f8659a 100644 --- a/Doc/howto/instrumentation.rst +++ b/Doc/howto/instrumentation.rst @@ -460,7 +460,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 8636fecb8323a4..390cf20490fd98 100644 --- a/Doc/library/cmd.rst +++ b/Doc/library/cmd.rst @@ -112,15 +112,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 f73252a90265cf..4686b673a4459b 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -1253,7 +1253,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 76001821d9d469..b7e83b0eaac82d 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -2835,7 +2835,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 5a95f6e78d1eda..c6ec00bf3e3e86 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -1783,7 +1783,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 23e317c96bbe94..9aa5a9d910ee29 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -251,7 +251,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 e6bbd9c07c83b1..a298b68ec37c16 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -664,7 +664,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 68ea834747ebfe..a8b5b94bd58751 100644 --- a/Doc/library/tkinter.ttk.rst +++ b/Doc/library/tkinter.ttk.rst @@ -1495,8 +1495,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/unittest.mock-examples.rst b/Doc/library/unittest.mock-examples.rst index 176b1b6903a19d..fcf4ae0e7bc964 100644 --- a/Doc/library/unittest.mock-examples.rst +++ b/Doc/library/unittest.mock-examples.rst @@ -482,7 +482,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 5460be03671d2f..ebcf1eacf13833 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -1076,7 +1076,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 diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 59ec863c14ffa2..355cd9873f62ad 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -564,10 +564,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 4db772dbc1bf99..8687912e5f7918 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -823,7 +823,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 15c701f44ca5ec..8d81e51857f2cf 100644 --- a/Doc/library/zlib.rst +++ b/Doc/library/zlib.rst @@ -269,7 +269,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/unix.rst b/Doc/using/unix.rst index a9950ef7525497..d0496cdab96741 100644 --- a/Doc/using/unix.rst +++ b/Doc/using/unix.rst @@ -182,7 +182,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 5c69e473af6d5b..effa7b0bacd94a 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 60ea5b87f8ab61..e1bbadefcc717b 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 0af4670b0b120e..75de404ef3d9ef 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 650b75d0acebd1..a3a92689a01db3 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`.)