[issue39574] str.__doc__ is misleading

[Steven D'Aprano]

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

The docs are correct, you are just misinterpreting them. Which could, I guess, suggest the docs could do with improvement.

With *one* argument, `str(obj)` returns a string via `object.__str__(obj)` or `repr(obj)`, whichever is defined. That includes the case where obj is a bytes object.

*Only* in the two or three argument case where you explicitly provide either the encoding or errors parameter will bytes be decoded. But you must provide at least one of encoding or errors. If you provide neither, you have the one-argument form above.

The default value for encoding is only relevant in cases like this:

    # encoding defaults to sys.getdefaultencoding()
    py> str(b'a', errors='ignore')
    'a'



Here's my suggested rewording:


***


str(object='') -> str
str(bytes_or_buffer [, encoding] [, errors]) -> str

Create a new string object from the given object.

If a single argument is given, returns the result of object.__str__() (if defined) or repr(object).

If encoding or errors or both are specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. If errors is specified, the default encoding is sys.getdefaultencoding(). If encoding is specified, errors defaults to 'strict'.

----------
nosy: +steven.daprano
versions: +Python 3.6, Python 3.7, Python 3.8, Python 3.9

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