Add a str class entry to the "Text Sequence Type" section (issue #16209).

This commit also moves the documentation for the str built-in function to
the new class entry.  Links to :class:`str` now go to the class entry with
the string methods immediately afterwards.

6 files changed, 78 insertions, 56 deletions

diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index d895547..a47183c 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -160,10 +160,10 @@ Object Protocol
    a string similar to that returned by :c:func:`PyObject_Repr` in Python 2.
    Called by the :func:`ascii` built-in function.
 
+   .. index:: string; PyObject_Str (C function)
 
-.. c:function:: PyObject* PyObject_Str(PyObject *o)
 
-   .. index:: builtin: str
+.. c:function:: PyObject* PyObject_Str(PyObject *o)
 
    Compute a string representation of object *o*.  Returns the string
    representation on success, *NULL* on failure.  This is the equivalent of the
diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
index 376d09a..08a70a2 100644
--- a/Doc/extending/newtypes.rst
+++ b/Doc/extending/newtypes.rst
@@ -982,12 +982,12 @@ done.  This can be done using the :c:func:`PyErr_Fetch` and
    }
 
 
-Object Presentation
--------------------
-
 .. index::
+   single: string; object representation
    builtin: repr
-   builtin: str
+
+Object Presentation
+-------------------
 
 In Python, there are two ways to generate a textual representation of an object:
 the :func:`repr` function, and the :func:`str` function.  (The :func:`print`
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index a92c378..07765ce 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -14,7 +14,7 @@ are always available.  They are listed here in alphabetical order.
 :func:`all`          :func:`dir`        :func:`hex`         :func:`next`      :func:`slice`
 :func:`any`          :func:`divmod`     :func:`id`          :func:`object`    :func:`sorted`
 :func:`ascii`        :func:`enumerate`  :func:`input`       :func:`oct`       :func:`staticmethod`
-:func:`bin`          :func:`eval`       :func:`int`         :func:`open`      :func:`str`
+:func:`bin`          :func:`eval`       :func:`int`         :func:`open`      |func-str|_
 :func:`bool`         :func:`exec`       :func:`isinstance`  :func:`ord`       :func:`sum`
 :func:`bytearray`    :func:`filter`     :func:`issubclass`  :func:`pow`       :func:`super`
 :func:`bytes`        :func:`float`      :func:`iter`        :func:`print`     |func-tuple|_
@@ -34,6 +34,7 @@ are always available.  They are listed here in alphabetical order.
 .. |func-memoryview| replace:: ``memoryview()``
 .. |func-set| replace:: ``set()``
 .. |func-list| replace:: ``list()``
+.. |func-str| replace:: ``str()``
 .. |func-tuple| replace:: ``tuple()``
 .. |func-range| replace:: ``range()``
 
@@ -521,12 +522,12 @@ are always available.  They are listed here in alphabetical order.
 
    The float type is described in :ref:`typesnumeric`.
 
-
-.. function:: format(value[, format_spec])
-
    .. index::
-      pair: str; format
       single: __format__
+      single: string; format() (built-in function)
+
+
+.. function:: format(value[, format_spec])
 
    Convert a *value* to a "formatted" representation, as controlled by
    *format_spec*.  The interpretation of *format_spec* will depend on the type
@@ -1238,44 +1239,12 @@ are always available.  They are listed here in alphabetical order.
 .. _func-str:
 .. function:: str(object='')
               str(object=b'', encoding='utf-8', errors='strict')
+   :noindex:
 
-   Return a :ref:`string <textseq>` version of *object*.  If *object* is not
-   provided, returns the empty string.  Otherwise, the behavior of ``str()``
-   depends on whether *encoding* or *errors* is given, as follows.
-
-   If neither *encoding* nor *errors* is given, ``str(object)`` returns
-   :meth:`object.__str__() <object.__str__>`, which is the "informal" or nicely
-   printable string representation of *object*.  For string objects, this is
-   the string itself.  If *object* does not have a :meth:`~object.__str__`
-   method, then :func:`str` falls back to returning
-   :meth:`repr(object) <repr>`.
+   Return a :class:`str` version of *object*.  See :func:`str` for details.
 
-   .. index::
-      single: buffer protocol; str() (built-in function)
-      single: bytes; str() (built-in function)
-
-   If at least one of *encoding* or *errors* is given, *object* should be a
-   :class:`bytes` or :class:`bytearray` object, or more generally any object
-   that supports the :ref:`buffer protocol <bufferobjects>`.  In this case, if
-   *object* is a :class:`bytes` (or :class:`bytearray`) object, then
-   ``str(bytes, encoding, errors)`` is equivalent to
-   :meth:`bytes.decode(encoding, errors) <bytes.decode>`.  Otherwise, the bytes
-   object underlying the buffer object is obtained before calling
-   :meth:`bytes.decode`.  See :ref:`binaryseq` and
-   :ref:`bufferobjects` for information on buffer objects.
-
-   Passing a :class:`bytes` object to :func:`str` without the *encoding*
-   or *errors* arguments falls under the first case of returning the informal
-   string representation (see also the :option:`-b` command-line option to
-   Python).  For example::
-
-      >>> str(b'Zoot!')
-      "b'Zoot!'"
-
-   ``str`` is a built-in :term:`type`.  For more information on the string
-   type and its methods, see the :ref:`textseq` and :ref:`string-methods`
-   sections.  To output formatted strings, see the :ref:`string-formatting`
-   section.  In addition, see the :ref:`stringservices` section.
+   ``str`` is the built-in string :term:`class`.  For general information
+   about strings, see :ref:`textseq`.
 
 
 .. function:: sum(iterable[, start])
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index bf5d756..138405a 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1348,7 +1348,7 @@ range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.)
 
 .. index::
    single: string; text sequence type
-   single: str() (built-in function); (see also string)
+   single: str (built-in class); (see also string)
    object: string
 
 .. _textseq:
@@ -1376,8 +1376,8 @@ See :ref:`strings` for more about the various forms of string literal,
 including supported escape sequences, and the ``r`` ("raw") prefix that
 disables most escape sequence processing.
 
-Strings may also be created from other objects with the built-in
-function :func:`str`.
+Strings may also be created from other objects using the :class:`str`
+constructor.
 
 Since there is no separate "character" type, indexing a string produces
 strings of length 1. That is, for a non-empty string *s*, ``s[0] == s[0:1]``.
@@ -1394,13 +1394,61 @@ multiple fragments.
    once again permitted on string literals. It has no effect on the meaning
    of string literals and cannot be combined with the ``r`` prefix.
 
+
+.. index::
+   single: string; str (built-in class)
+
+.. class:: str(object='')
+           str(object=b'', encoding='utf-8', errors='strict')
+
+   Return a :ref:`string <textseq>` version of *object*.  If *object* is not
+   provided, returns the empty string.  Otherwise, the behavior of ``str()``
+   depends on whether *encoding* or *errors* is given, as follows.
+
+   If neither *encoding* nor *errors* is given, ``str(object)`` returns
+   :meth:`object.__str__() <object.__str__>`, which is the "informal" or nicely
+   printable string representation of *object*.  For string objects, this is
+   the string itself.  If *object* does not have a :meth:`~object.__str__`
+   method, then :func:`str` falls back to returning
+   :meth:`repr(object) <repr>`.
+
+   .. index::
+      single: buffer protocol; str (built-in class)
+      single: bytes; str (built-in class)
+
+   If at least one of *encoding* or *errors* is given, *object* should be a
+   :class:`bytes` or :class:`bytearray` object, or more generally any object
+   that supports the :ref:`buffer protocol <bufferobjects>`.  In this case, if
+   *object* is a :class:`bytes` (or :class:`bytearray`) object, then
+   ``str(bytes, encoding, errors)`` is equivalent to
+   :meth:`bytes.decode(encoding, errors) <bytes.decode>`.  Otherwise, the bytes
+   object underlying the buffer object is obtained before calling
+   :meth:`bytes.decode`.  See :ref:`binaryseq` and
+   :ref:`bufferobjects` for information on buffer objects.
+
+   Passing a :class:`bytes` object to :func:`str` without the *encoding*
+   or *errors* arguments falls under the first case of returning the informal
+   string representation (see also the :option:`-b` command-line option to
+   Python).  For example::
+
+      >>> str(b'Zoot!')
+      "b'Zoot!'"
+
+   For more information on the ``str`` class and its methods, see
+   :ref:`textseq` and the :ref:`string-methods` section below.  To output
+   formatted strings, see the :ref:`string-formatting` section.  In addition,
+   see the :ref:`stringservices` section.
+
+
+.. index::
+   pair: string; methods
+
 .. _string-methods:
 
 String Methods
 --------------
 
 .. index::
-   pair: string; methods
    module: re
 
 Strings implement all of the :ref:`common <typesseq-common>` sequence
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index b7a6736..7c51068 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -274,11 +274,13 @@ Sequences
 
       The following types are immutable sequences:
 
+      .. index::
+         single: string; immutable sequences
+
       Strings
          .. index::
             builtin: chr
             builtin: ord
-            builtin: str
             single: character
             single: integer
             single: Unicode
@@ -1188,14 +1190,14 @@ Basic customization
    Called by :func:`bytes` to compute a byte-string representation of an
    object. This should return a ``bytes`` object.
 
-
-.. method:: object.__format__(self, format_spec)
-
    .. index::
+      single: string; __format__() (object method)
       pair: string; conversion
-      builtin: str
       builtin: print
 
+
+.. method:: object.__format__(self, format_spec)
+
    Called by the :func:`format` built-in function (and by extension, the
    :meth:`str.format` method of class :class:`str`) to produce a "formatted"
    string representation of an object. The ``format_spec`` argument is
diff --git a/Misc/NEWS b/Misc/NEWS
index 62193b9..cd77da8 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -292,6 +292,9 @@ Tools/Demos
 Documentation
 -------------
 
+- Issue #16209: Move the documentation for the str built-in function to a new
+  str class entry in the "Text Sequence Type" section.
+
 - Issue #13538: Improve str() and object.__str__() documentation.
 
 - Issue #16489: Make it clearer that importlib.find_loader() requires any and