In Python 3.4.3, the doc string of the str() builtin still reads: "str(object='') -> str\nstr(bytes_or_buffer[, encoding[, errors]]) -> str\n\nCreate a new string object from the given object. If encoding or\nerrors is specified, then the object must expose a data buffer\nthat will be decoded using the given encoding and error handler.\nOtherwise, returns the result of object.__str__() (if defined)\nor repr(object).\nencoding defaults to sys.getdefaultencoding().\nerrors defaults to 'strict'." This no longer matches what str() does. sys.getdefaultencoding() always returns 'utf-8' and str() accepts bytes, bytearray or buffer-like objects as input when using an encoding, any object with .__str__() method defined or repr(obj) otherwise.
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")
The current docstring is correct. The signature str(object, encoding="utf-8", errors="strict") is not correct, because str(object) is not the same as str(object, encoding="utf-8", errors="strict"). >>> str([1, 2]) '[1, 2]' >>> str([1, 2], encoding="utf-8", errors="strict") Traceback (most recent call last): File "", line 1, in TypeError: decoding to str: need a bytes-like object, list found >>> str(b'abc') __main__:1: BytesWarning: str() on a bytes instance "b'abc'" >>> str(b'abc', encoding="utf-8", errors="strict") 'abc'
