classification
Title: Check accuracy of str() doc string for its encoding argument
Type: Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: closed Resolution: duplicate
Dependencies: Superseder: str.__doc__ is misleading
View: 39574
Assigned To: docs@python Nosy List: docs@python, martin.panter, rhettinger, serhiy.storchaka
Priority: normal Keywords:

Created on 2018-11-26 18:49 by rhettinger, last changed 2020-02-08 04:23 by martin.panter. This issue is now closed.

Messages (5)
msg330454 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-11-26 18:49
The "encoding" parameter is documented to default to sys.getdefaultencoding(). That may be true but there doesn't seem to be a way to use that default because objects will all have a __str__ or __repr__ that will be run instead.

-------------------------------------------
>>> import sys
>>> sys.getdefaultencoding()     # Default encoding is utf-8
'utf-8'
>>> buffer = b'lim x \xe2\x9f\xb6 \xe2\x88\x9e, 1/sin\xc2\xb2(x)'
>>> str(buffer, 'utf-8')         # Explicit argument decodes properly
'lim x ⟶ ∞, 1/sin²(x)'   
>>> str(buffer)                  # Despite the default, repr is shown 
"b'lim x \\xe2\\x9f\\xb6 \\xe2\\x88\\x9e, 1/sin\\xc2\\xb2(x)'"

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

Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.
msg330455 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-11-26 19:07
>>> str(buffer, errors='strict')
'lim x ⟶ ∞, 1/sin²(x)'
msg330457 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-11-26 19:20
We may need to reword this a bit to show that the default system encoding only applies if "errors" is specified; otherwise, the argument pattern is mysterious.
msg330458 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-11-26 19:37
Is not it exactly what the docsting says?

> If encoding or
> errors is specified, then the object must expose a data buffer
> that will be decoded using the given encoding and error handler.
> Otherwise, returns the result of object.__str__() (if defined)
> or repr(object).
msg361621 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2020-02-08 04:23
Closing in favour of Issue 39574 where a new wording is proposed
History
Date User Action Args
2020-02-08 04:23:54martin.pantersetstatus: open -> closed

superseder: str.__doc__ is misleading

nosy: + martin.panter
messages: + msg361621
resolution: duplicate
stage: resolved
2018-11-26 19:37:58serhiy.storchakasetmessages: + msg330458
2018-11-26 19:20:30rhettingersetmessages: + msg330457
2018-11-26 19:07:25serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg330455
2018-11-26 18:49:06rhettingercreate