From 31985e2945689dea914b657233d5bf8f6ca41d62 Mon Sep 17 00:00:00 2001
From: Joshua-Ward1 <joshie@flewognetworks.wales>
Date: Fri, 12 Dec 2025 15:41:18 -0500
Subject: [PATCH] gh-137112: Improve str() docstring defaults and wording

---
 Lib/test/test_pydoc/test_pydoc.py                     | 11 +++++++++++
 .../2025-12-10-14-24-18.gh-issue-137112.kjAJy7.rst    |  3 +++
 Objects/unicodeobject.c                               |  8 +++-----
 3 files changed, 17 insertions(+), 5 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Library/2025-12-10-14-24-18.gh-issue-137112.kjAJy7.rst

diff --git a/Lib/test/test_pydoc/test_pydoc.py b/Lib/test/test_pydoc/test_pydoc.py
index c640416327efbf..81b95bd4355b1a 100644
--- a/Lib/test/test_pydoc/test_pydoc.py
+++ b/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()
diff --git a/Misc/NEWS.d/next/Library/2025-12-10-14-24-18.gh-issue-137112.kjAJy7.rst b/Misc/NEWS.d/next/Library/2025-12-10-14-24-18.gh-issue-137112.kjAJy7.rst
new file mode 100644
index 00000000000000..3490a09797fa49
--- /dev/null
+++ b/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.
diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c
index f737a885f197a0..6aa010ed33f0eb 100644
--- a/Objects/unicodeobject.c
+++ b/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);