The docstring of `str()` should show the default values for object, encoding and errors and should say `bytes-like object`

[hyperkai]

The docstring of str() doesn't show the default values for object, encoding and errors and does say bytes_or_buffer as shown below:

print(help(str))
# class str(object)
#  |  str(object='') -> str
#  |  str(bytes_or_buffer[, encoding[, errors]]) -> str

So, the docstring of str() should show the default values for object, encoding and errors and should say bytes-like object as shown below:

print(help(str))
# class str(object)
#  |  str(object='') -> str
#  |  str(object=b'', encoding='utf-8', errors='strict') -> str # Here
#  |  str(bytes-like object[, encoding[, errors]]) -> str
          # Here

Linked PRs

• gh-137112: Improve str() docstring defaults and wording #142650

[AA-Turner]

Can you elaborate on the argument for splitting bytes and buffers? I don't think it makes sense to say that there's a 'default' for bytes, as str() returns the empty string.

A

[hyperkai]

Because bytes-like object also includes bytearray() and array.array() not just bytes() and memoryview()(buffer) as the doc says as shown below. *bytearray() and array.array() work with str():

An object that supports the Buffer Protocol and can export a C-contiguous buffer. This includes all bytes, bytearray, and array.array objects, as well as many common memoryview objects.

v = bytearray(b'Good Job!')

print(str(object=v, encoding='utf-8', errors='strict'))
# Good Job!

import array

v = array.array('i', [ord('a'), ord('b'), ord('c')])

print(str(object=v, encoding='utf-8', errors='strict'))
# abc

[AA-Turner]

I'm still not sure I understand -- the section you quote notes that bytes-like objects are also buffers; the current docstring of str notes support for bytes or buffers.

[terryjreedy]

The proposed second line is the second line from https://docs.python.org/3/library/functions.html#func-str. This signature is repeated at https://docs.python.org/3/library/stdtypes.html#str, where it is followed with much more detail. It should replace, not be added to the old and somewhat obsolete current line. The current docstring also continues with more explanation and ends with \nencoding defaults to 'utf-8'.\nerrors defaults to 'strict'. This could then be removed as redundant.

The docstring already had the defaults, but this change will move them up into the signature in the current style and make them immediately readable and easier to find in an IDE call hint, such as IDLE's.

(I checked that object is optional even when the other args are present.)

[iqra-codes]

Hi! I'm interested in working on this issue. May I take it?