Title: str.__doc__ needs an update
Type: enhancement Stage: needs patch
Components: Documentation, Interpreter Core, Unicode Versions: Python 3.6, Python 3.5
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ezio.melotti, haypo, lemburg, martin.panter
Priority: normal Keywords: easy

Created on 2015-04-22 13:13 by lemburg, last changed 2017-02-23 18:22 by garvitdelhi.

Pull Requests
URL Status Linked Edit
PR 257 open garvitdelhi, 2017-02-23 18:22
Messages (2)
msg241798 - (view) Author: Marc-Andre Lemburg (lemburg) * (Python committer) Date: 2015-04-22 13:13
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.
msg257364 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-01-02 21:25
Slightly easier to read version:

>>> pprint(str.__doc__)
("str(object='') -> str\n"
 'str(bytes_or_buffer[, encoding[, errors]]) -> str\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")
Date User Action Args
2017-02-23 18:22:57garvitdelhisetpull_requests: + pull_request227
2016-01-02 21:25:13martin.pantersetnosy: + martin.panter
messages: + msg257364
2016-01-02 08:41:51ezio.melottisetassignee: docs@python
components: + Documentation
versions: - Python 3.4
keywords: + easy
nosy: + docs@python

type: enhancement
stage: needs patch
2015-04-22 13:13:46lemburgcreate