ConfigParser.items() docstring does not describe the no-argument overload

Documentation

The docstring of configparser.ConfigParser.items at Lib/configparser.py:887-897 describes only the call with a section argument:

def items(self, section=_UNSET, raw=False, vars=None):
    """Return a list of (name, value) tuples for each option in a section.

    All % interpolations are expanded in the return values, based on the
    defaults passed into the constructor, unless the optional argument
    `raw` is true.  Additional substitutions may be provided using the
    `vars` argument, which must be a dictionary whose contents overrides
    any pre-existing defaults.

    The section DEFAULT is special.
    """
    if section is _UNSET:
        return super().items()
    ...
    return [(option, value_getter(option)) for option in orig_keys]

When called with no arguments, items() delegates to the items() method inherited from collections.abc.Mapping and returns a collections.abc.ItemsView of (section_name, section_proxy) pairs — not a list of (name, value) tuples. The docstring currently mentions neither this overload nor its return type.

This is a follow-up to gh-149050 / gh-150059, which fixed the same kind of mismatch in Doc/library/configparser.rst. StanFromIreland reviewed that PR, while picnixz discussed the behavior on the issue. The .rst change remained scoped to the library documentation, so the docstring was left unchanged and is tracked here.

Suggested fix

Reword the docstring so that both overloads are described, e.g.:

"""Return the items of the parser or of a section.

When *section* is not given, return an :class:`~collections.abc.ItemsView`
of `(section_name, section_proxy)` pairs, including `DEFAULTSECT`.

Otherwise, return a list of `(name, value)` tuples for each option in the
given section.  All % interpolations are expanded in the return values,
based on the defaults passed into the constructor, unless the optional
argument `raw` is true.  Additional substitutions may be provided using
the `vars` argument, which must be a dictionary whose contents overrides
any pre-existing defaults.

The section DEFAULT is special.
"""

(bpo-15803 / gh-60007 corrected the module-level API summary in 2012. The no-argument overload itself was added in 2010, but this method docstring continued to describe only the section-argument form.)

Linked PRs

• gh-150133

從 Lib/configparser.py:887-897 開始，並比較 ConfigParser.items() 與繼承的 Mapping.items() 行為。在進行變更之前，檢查連結的文件後續事項和 gh-150133。完成的標準是：docstring 準確描述無引數的 ItemsView 形式，以及帶有 section 引數的清單形式。