GeezerVison is showing github.com — The docstring of `str()` should show the default values for object, encoding and errors and should say `bytes-like object` · Issue #137112 · python/cpython
The docstring of str() should show the default values for object, encoding and errors and should say bytes-like object #137112DescriptionThe 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
# HereLinked PRs
ActivityAA-Turner commented on Jul 25, 2025 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 commented on Jul 25, 2025 ContributorAuthor More actions 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'))
# abcAA-Turner commented on Jul 25, 2025 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. changed the title [-]The docstring of `str()` should show the default values for `object`, `encoding` and `errors` and should say `bytes-like object`[/-] [+]Condense the `str()` docstring. [/+] on Jul 26, 2025terryjreedy commented on Jul 26, 2025 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 commented on Jul 26, 2025 Hi! I'm interested in working on this issue. May I take it? changed the title [-]Condense the `str()` docstring. [/-] [+]The docstring of `str()` should show the default values for object, encoding and errors and should say `bytes-like object`[/+] on Aug 1, 2025Joshua-Ward1 commented on Dec 12, 2025 Hi all — I’ve implemented this and opened a PR here: gh-137112: Improve str() docstring defaults and wording (#142650).
The PR updates the signature to include the default values (matching the current docs style), replaces the older bytes_or_buffer wording with “bytes-like object”, and removes the now-redundant explanatory lines for clarity.
CC @terryjreedy @AA-Turner
MetadataMetadataStatusShow more project fields
DevelopmentNo branches or pull requestsIssue actions
|