[docs] [issue24024] str.__doc__ needs an update

[Martin Panter]

Martin Panter added the comment:

Slightly easier to read version:

>>> pprint(str.__doc__)
("str(object='') -> str\n"
 'str(bytes_or_buffer[, encoding[, errors]]) -> str\n'
 '\n'
 'Create a new string object from the given object. If encoding or\n'
 'errors is specified, then the object must expose a data buffer\n'
 'that will be decoded using the given encoding and error handler.\n'
 'Otherwise, returns the result of object.__str__() (if defined)\n'
 'or repr(object).\n'
 'encoding defaults to sys.getdefaultencoding().\n'
 "errors defaults to 'strict'.")

I don’t exactly understand your complaint.

Do you want to say encoding directly defaults to UTF-8, bypassing the getdefaultencoding() reference?

Do you want to explicitly point out that bytes() and bytearray() expose a data buffer and can therefore be decoded? This is already hinted in the name bytes_or_buffer.

Do you want to clarify that the Otherwise sentence applies when encoding and errors are not specified, rather than when the object does not expose a buffer?

Maybe another thing to change could be fixing the second signature, to show that an explicit encoding can be omitted, and bytes_or_buffer is not a valid keyword name:

str(object, encoding="utf-8", errors="strict")

----------
nosy: +martin.panter

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue24024>
_______________________________________