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 super().items() (i.e. MutableMapping.items) 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. Both reviewers on that PR (StanFromIreland, picnixz) focused on the .rst only, so the docstring was left out of scope 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 previously corrected this docstring in 2012 but only for the section-argument overload; the no-argument overload was added later.)
Linked PRs
Documentation
The docstring of
configparser.ConfigParser.itemsatLib/configparser.py:887-897describes only the call with asectionargument:When called with no arguments,
items()delegates tosuper().items()(i.e.MutableMapping.items) and returns acollections.abc.ItemsViewof(section_name, section_proxy)pairs — not alistof(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. Both reviewers on that PR (StanFromIreland, picnixz) focused on the.rstonly, so the docstring was left out of scope and is tracked here.Suggested fix
Reword the docstring so that both overloads are described, e.g.:
(
bpo-15803/ gh-60007 previously corrected this docstring in 2012 but only for the section-argument overload; the no-argument overload was added later.)Linked PRs