diff options
author | Chris Jerdonek <chris.jerdonek@gmail.com> | 2012-11-28 09:45:15 (GMT) |
---|---|---|
committer | Chris Jerdonek <chris.jerdonek@gmail.com> | 2012-11-28 09:45:15 (GMT) |
commit | 16459e8b16dfa00bd9f0f1a6b1d7989dd1d4b93e (patch) | |
tree | 4f86872908d34c6f492e292a88645a69549a8021 | |
parent | bff98fe5364452775d8273137c9087ed004deb96 (diff) | |
parent | bb4e941c6d721c2461f7dd30a84565abc350eca3 (diff) | |
download | cpython-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.rst | 4 | ||||
-rw-r--r-- | Doc/extending/newtypes.rst | 8 | ||||
-rw-r--r-- | Doc/library/functions.rst | 51 | ||||
-rw-r--r-- | Doc/library/stdtypes.rst | 56 | ||||
-rw-r--r-- | Doc/reference/datamodel.rst | 12 | ||||
-rw-r--r-- | Misc/NEWS | 3 |
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 @@ -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 |