This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: str.__doc__ needs an update
Type: enhancement Stage: resolved
Components: Documentation, Interpreter Core, Unicode Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ezio.melotti, lemburg, martin.panter, serhiy.storchaka, vstinner
Priority: normal Keywords: easy

Created on 2015-04-22 13:13 by lemburg, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 257 closed garvitdelhi, 2017-02-23 18:22
Messages (3)
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'
 '\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")
msg314453 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-03-26 13:49
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 "<stdin>", line 1, in <module>
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'
History
Date User Action Args
2022-04-11 14:58:15adminsetgithub: 68212
2018-04-22 10:55:42serhiy.storchakasetstatus: pending -> closed
resolution: rejected
stage: needs patch -> resolved
2018-03-26 13:49:48serhiy.storchakasetstatus: open -> pending
nosy: + serhiy.storchaka
messages: + msg314453

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