A grep through the codebase shows that RawConfigParser.items() is the only .items() method in the stdlib which accepts arguments.

This is annoying as a stdlib user because when I see the arguments being passed to RawConfigParser.items(), I have _no idea_ what they do.  Instinctively, I do not expect .items() to take arguments, and I have to go and work out what it does each time.

I think it would be both easier to understand, and more consistent with general Pythonic practice, if the two codepaths in RawConfigParser.items() were split in to separate methods; one which takes no arguments (which will continue to behave as it does today when called that way) and one which is named in a way that makes it clearer what it does (and takes arguments).

For backward compatibility reasons this will not be changed.  I don't know if the idea of adding a method and doing a documentation deprecation is worth it or not.

I think the proposed change is not worth it. Developments in type checking (in particular overloading) make it unambiguous what the return type will be from just a static inspection of the call site. (Given that the _UNSET value is intended to be private.) See also https://github.com/python/mypy/issues/3805#issuecomment-320561797

Having ironed out my confusion over typing the method, I agree that making
the types more obvious is not a compelling argument for this change.

That said, I think the current API has been confusing to me in the past,
and I think the proposed change is still a worthwhile improvement for users
of this module.

On Mon, Aug 7, 2017 at 12:08 AM Guido van Rossum <report@bugs.python.org>
wrote:

>
> Guido van Rossum added the comment:
>
> I think the proposed change is not worth it. Developments in type checking
> (in particular overloading) make it unambiguous what the return type will
> be from just a static inspection of the call site. (Given that the _UNSET
> value is intended to be private.) See also
> https://github.com/python/mypy/issues/3805#issuecomment-320561797
>
> ----------
> nosy: +gvanrossum
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue31129>
> _______________________________________
>

I don't think this is worth it.