summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorChris Jerdonek <chris.jerdonek@gmail.com>2012-11-28 09:45:15 (GMT)
committerChris Jerdonek <chris.jerdonek@gmail.com>2012-11-28 09:45:15 (GMT)
commit16459e8b16dfa00bd9f0f1a6b1d7989dd1d4b93e (patch)
tree4f86872908d34c6f492e292a88645a69549a8021
parentbff98fe5364452775d8273137c9087ed004deb96 (diff)
parentbb4e941c6d721c2461f7dd30a84565abc350eca3 (diff)
downloadcpython-16459e8b16dfa00bd9f0f1a6b1d7989dd1d4b93e.zip
cpython-16459e8b16dfa00bd9f0f1a6b1d7989dd1d4b93e.tar.gz
cpython-16459e8b16dfa00bd9f0f1a6b1d7989dd1d4b93e.tar.bz2
Merge from 3.3: Add a str class entry to the string 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.
-rw-r--r--Doc/c-api/object.rst4
-rw-r--r--Doc/extending/newtypes.rst8
-rw-r--r--Doc/library/functions.rst51
-rw-r--r--Doc/library/stdtypes.rst56
-rw-r--r--Doc/reference/datamodel.rst12
-rw-r--r--Misc/NEWS3
6 files changed, 78 insertions, 56 deletions
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index e4769b3..02a0d36 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 25ec2d6..9a39eb4 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 eb3a98d..2dff7b1 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -418,6 +418,9 @@ Build
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() needs parent