Note that `configparser.ConfigParser.items` returns a `collections.abc.ItemsView` in the first overload

[jonathandung]

Documentation

When the items method of an instance of configparser.ConfigParser is called without a section argument, the implementation delegates to the items method of the superclass directly to return a typical view of dictionary items; that is, a special set-like iterator over tuples of the form (section_name, section_proxy). This is as opposed to the documented behaviour, which states a list is returned for both overloads (regardless if section is passed).

[picnixz]

I think we should just avoid the term "list" here. What we want is the weak form, namely .items() is "similar" to dict.items(). Expecting a list is not stronger than just being compatible with .items() so we could just remove the list implementation detail.

Otherwise, we need to really return a list but in this case, we won't have a real view on the items. I think the intent was to say that it's as if we're representing the configuration as dictionary and .items() behaves like dict.items() but no more.

cc @jaraco

[jonathandung]

But when section is specified, the implementation actually constructs a list using a comprehension and returns it. Should that be changed?

[picnixz]

No, but then I wonder whether the term "list" was for "list object" or to mention a generic "sequence-like" object. What I'm confused about is:

parser.items() is compatible with the mapping protocol (returns a list of section_name, section_proxy pairs including the DEFAULTSECT). However, this method can also be invoked with arguments: parser.items(section, raw, vars). The latter call returns a list of option, value pairs for a specified section, with all interpolations expanded (unless raw=True is provided).

It says "mapping protocol". But the mapping protocol for items() does not force it to be a list. Being a list (of pairs) is stronger here (though, one could argue that we don't really have a view of items itself, because items() returns a view on the items).

With a dict, changing the original dict would alter the object returned by .items(). Here we return a list, so changes to the configuration won't be reflected (only changes to the sections themselves will be reflected).

I think the intent was to make it a view on the sections themselves but not on the entire configuration itself (or I may be wrong). OTOH, calling items() without a section gives you a view on the entire configuration.

• Calling items() gives a full view but you cannot index that view.
• Calling items(something) gives you a partial view but you can index it.

I don't know whether the indexation is important. If it's important, we need to use list(super().items()). If it's not important, we can leave it as is and amend the docs. But since I don't know, I leave it to Jason.

---

Personally, I wouldn't expect .items() to return an indexable object but at the same time, it's not possible to return a subview without creating a new object. So, changing the docs to say that there is a minor discrepency may be ok (if people want a list, they can cast the result themselves; it's easier than breaking code).