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

Author: Joshua-Ward1

Lib/test/test_pydoc/test_pydoc.py

@@ -801,6 +801,17 @@ def run_pydoc_pager(request, what, expected_first_line):
         run_pydoc_pager('sys', 'sys', 'Help on built-in module sys:')
         run_pydoc_pager(sys, 'sys', 'Help on built-in module sys:')
 
+    @requires_docstrings
+    def test_str_docstring_signature(self):
+        doc = pydoc.TextDoc()
+        text = clean_text(doc.docclass(str))
+        self.assertIn(" |  str(object='') -> str", text)
+        self.assertIn(" |  str(object=b'', encoding='utf-8', errors='strict') -> str", text)
+        self.assertNotIn("str(bytes_or_buffer", text)
+        self.assertIn("bytes-like object", text)
+        self.assertNotIn("encoding defaults", text)
+        self.assertNotIn("errors defaults", text)
+
     def test_showtopic(self):
         with captured_stdout() as showtopic_io:
             helper = pydoc.Helper()

Misc/NEWS.d/next/Library/2025-12-10-14-24-18.gh-issue-137112.kjAJy7.rst

@@ -0,0 +1,3 @@
+Updated ``str()`` help text to show the default ``encoding`` and ``errors``
+values and to describe decoding input as a bytes-like object, matching the
+documentation signature.

Objects/unicodeobject.c

@@ -13968,15 +13968,13 @@ _PyUnicode_ExactDealloc(PyObject *op)
 
 PyDoc_STRVAR(unicode_doc,
 "str(object='') -> str\n\
-str(bytes_or_buffer[, encoding[, errors]]) -> str\n\
+str(object=b'', encoding='utf-8', errors='strict') -> 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\
+errors is specified, then the object must be a bytes-like object\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 'utf-8'.\n\
-errors defaults to 'strict'.");
+or repr(object).");
 
 static PyObject *unicode_iter(PyObject *seq);