[issue39574] str.__doc__ is misleading

[Steven D'Aprano]

Steven D'Aprano <steve+python at pearwood.info> added the comment:

On Fri, Feb 07, 2020 at 12:33:45PM +0000, Serhiy Storchaka wrote:
> 
> Serhiy Storchaka <storchaka+cpython at gmail.com> added the comment:
> 
> See a discussion on Python-Dev: https://mail.python.org/archives/list/python-dev@python.org/message/YMIGWRUERUG66CKRJXDXNPCIDHRQJY6V/

I don't know whether the very odd calls 

    str(encoding='spam')
    str(errors='eggs')
    str(encoding='spam', errors='eggs')

are intentional or not. I suspect not: to me, it looks like an accident 
of implementation, not a deliberate feature. Under what circumstances 
would somebody intentionally provide an encoding and error handler when 
they aren't actually going to use them? There may be really unusual 
cases:

    args = () if condition else (mybytes,)
    str = str(*args, encoding='spam')

but I doubt they are going to be either common or something we ought to 
encourage. Regardless of whether we deprecate and remove those three odd 
cases or not, I don't think we should bother documenting them.

If anyone disagrees, and wants to document them, that's okay, but you 
can document them as a separate PR with a separate discussion. Let's 
just fix the confusion over the default encoding here and worry about 
other issues later. Don't let the perfect get in the way of the good 
enough for now :-)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue39574>
_______________________________________