Improve str() and object.__str__() documentation (issue #13538).

1 files changed, 42 insertions, 29 deletions

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 024ef0f..f027bac 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -534,7 +534,7 @@ are always available.  They are listed here in alphabetical order.
    is used by most built-in types: :ref:`formatspec`.
 
    The default *format_spec* is an empty string which usually gives the same
-   effect as calling ``str(value)``.
+   effect as calling :func:`str(value) <str>`.
 
    A call to ``format(value, format_spec)`` is translated to
    ``type(value).__format__(format_spec)`` which bypasses the instance
@@ -1249,37 +1249,50 @@ are always available.  They are listed here in alphabetical order.
    For more information on static methods, consult the documentation on the
    standard type hierarchy in :ref:`types`.
 
+   .. index::
+      single: string; str() (built-in function)
+
 
 .. _func-str:
 .. function:: str(object='')
-              str(object[, encoding[, errors]])
-
-   Return a :ref:`string <textseq>` version of an object, using one of the
-   following modes:
-
-   If *encoding* and/or *errors* are given, :func:`str` will decode the
-   *object* which can either be a byte string or a character buffer using
-   the codec for *encoding*. The *encoding* parameter is a string giving
-   the name of an encoding; if the encoding is not known, :exc:`LookupError`
-   is raised.  Error handling is done according to *errors*; this specifies the
-   treatment of characters which are invalid in the input encoding. If
-   *errors* is ``'strict'`` (the default), a :exc:`ValueError` is raised on
-   errors, while a value of ``'ignore'`` causes errors to be silently ignored,
-   and a value of ``'replace'`` causes the official Unicode replacement character,
-   U+FFFD, to be used to replace input characters which cannot be decoded.
-   See also the :mod:`codecs` module.
-
-   When only *object* is given, this returns its nicely printable representation.
-   For strings, this is the string itself.  The difference with ``repr(object)``
-   is that ``str(object)`` does not always attempt to return a string that is
-   acceptable to :func:`eval`; its goal is to return a printable string.
-   With no arguments, this returns the empty string.
-
-   Objects can specify what ``str(object)`` returns by defining a :meth:`__str__`
-   special method.
-
-   For more information on strings and string methods, see the :ref:`textseq`
-   section.  To output formatted strings, see the :ref:`string-formatting`
+              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 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.