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

[Taeknology]

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-150132: Document the no-argument overload of ConfigParser.items() #150133