Commits

Nick Coghlan committed 46b30b5

Update new text sequence section, and split some modules out of the 'String Services' section to a separate 'Binary Data Services' section

  • Participants
  • Parent commits cbc161e
  • Branches seq_docs_update

Comments (0)

Files changed (4)

File Doc/library/binary.rst

+.. _binaryservices:
+
+********************
+Binary Data Services
+********************
+
+The modules described in this chapter provide some basic leve operations for
+manipulation of binary data. Other operations on binary data, specifically
+in relation to file formats and network protocols, are described in the
+relevant sections.
+
+Some libraries described under :ref:`stringservices` also work with either
+ASCII-compatible binary formats (for example, :mod:`re`) or all binary data
+(for example, :mod:`difflib`).
+
+In addition, see the documentation for Python's built-in binary data types in
+:ref:`binaryseq`.
+
+.. toctree::
+
+   struct.rst
+   codecs.rst
+

File Doc/library/index.rst

    exceptions.rst
 
    strings.rst
+   binary.rst
    datatypes.rst
    numeric.rst
    functional.rst

File Doc/library/stdtypes.rst

 
 This table lists the sequence operations sorted in ascending priority
 (operations in the same box have the same priority).  In the table, *s* and *t*
-are sequences of the same type; *n*, *i*, *j* and *k* are integers.
+are sequences of the same type, *n*, *i*, *j* and *k* are integers and *x* is
+an arbitrary object that meets any type and value restrictions imposed by *s*.
 
 The ``in`` and ``not in`` operations have the same priorities as the
 comparison operations. The ``+`` (concatenation) and ``*`` (repetition)
 operations have the same priority as the corresponding numeric operations.
 
-+------------------+--------------------------------+----------+
-| Operation        | Result                         | Notes    |
-+==================+================================+==========+
-| ``x in s``       | ``True`` if an item of *s* is  | \(1)     |
-|                  | equal to *x*, else ``False``   |          |
-+------------------+--------------------------------+----------+
-| ``x not in s``   | ``False`` if an item of *s* is | \(1)     |
-|                  | equal to *x*, else ``True``    |          |
-+------------------+--------------------------------+----------+
-| ``s + t``        | the concatenation of *s* and   | (6)(7)   |
-|                  | *t*                            |          |
-+------------------+--------------------------------+----------+
-| ``s * n, n * s`` | *n* shallow copies of *s*      | (2)(7)   |
-|                  | concatenated                   |          |
-+------------------+--------------------------------+----------+
-| ``s[i]``         | *i*\ th item of *s*, origin 0  | \(3)     |
-+------------------+--------------------------------+----------+
-| ``s[i:j]``       | slice of *s* from *i* to *j*   | (3)(4)   |
-+------------------+--------------------------------+----------+
-| ``s[i:j:k]``     | slice of *s* from *i* to *j*   | (3)(5)   |
-|                  | with step *k*                  |          |
-+------------------+--------------------------------+----------+
-| ``len(s)``       | length of *s*                  |          |
-+------------------+--------------------------------+----------+
-| ``min(s)``       | smallest item of *s*           |          |
-+------------------+--------------------------------+----------+
-| ``max(s)``       | largest item of *s*            |          |
-+------------------+--------------------------------+----------+
-| ``s.index(i)``   | index of the first occurence   |\(8)      |
-|                  | of *i* in *s*                  |          |
-+------------------+--------------------------------+----------+
-| ``s.count(i)``   | total number of occurences of  |          |
-|                  | *i* in *s*                     |          |
-+------------------+--------------------------------+----------+
++--------------------------+--------------------------------+----------+
+| Operation                | Result                         | Notes    |
++==========================+================================+==========+
+| ``x in s``               | ``True`` if an item of *s* is  | \(1)     |
+|                          | equal to *x*, else ``False``   |          |
++--------------------------+--------------------------------+----------+
+| ``x not in s``           | ``False`` if an item of *s* is | \(1)     |
+|                          | equal to *x*, else ``True``    |          |
++--------------------------+--------------------------------+----------+
+| ``s + t``                | the concatenation of *s* and   | (6)(7)   |
+|                          | *t*                            |          |
++--------------------------+--------------------------------+----------+
+| ``s * n, n * s``         | *n* shallow copies of *s*      | (2)(7)   |
+|                          | concatenated                   |          |
++--------------------------+--------------------------------+----------+
+| ``s[i]``                 | *i*\ th item of *s*, origin 0  | \(3)     |
++--------------------------+--------------------------------+----------+
+| ``s[i:j]``               | slice of *s* from *i* to *j*   | (3)(4)   |
++--------------------------+--------------------------------+----------+
+| ``s[i:j:k]``             | slice of *s* from *i* to *j*   | (3)(5)   |
+|                          | with step *k*                  |          |
++--------------------------+--------------------------------+----------+
+| ``len(s)``               | length of *s*                  |          |
++--------------------------+--------------------------------+----------+
+| ``min(s)``               | smallest item of *s*           |          |
++--------------------------+--------------------------------+----------+
+| ``max(s)``               | largest item of *s*            |          |
++--------------------------+--------------------------------+----------+
+| ``s.index(x, [i[, j]])`` | index of the first occurence   | \(8)     |
+|                          | of *x* in *s* (at or after     |          |
+|                          | index *i* and before index *j*)|          |
++--------------------------+--------------------------------+----------+
+| ``s.count(x)``           | total number of occurences of  |          |
+|                          | *x* in *s*                     |          |
++--------------------------+--------------------------------+----------+
 
 Sequences of the same type also support comparisons.  In particular, tuples
 and lists are compared lexicographically by comparing corresponding elements.
 
 (8)
    ``index`` raises :exc:`ValueError` when *x* is not found in *s*.
+   When supported, the additional arguments to the index method allow
+   efficient searching of subsections of the sequence. Passing the extra
+   arguments is roughly equivalent to using ``s[i:j].index(x)``, only
+   without copying any data and with the returned index being relative to
+   the start of the sequence rather than the start of the slice.
 
 
 .. _typesseq-immutable:
 generally expected to support these operations (although leaving output
 ``sort()`` is a common exception).
 
-The operations in following table are defined on mutable sequence types. The
-:class:`collections.MutableSequence` ABC is provided to make it easier to
+The operations in the following table are defined on mutable sequence types.
+The :class:`collections.MutableSequence` ABC is provided to make it easier to
 correctly implement these operations on custom sequence types.
 
 In the table *s* is an instance of a mutable sequence type, *t* is any
 | ``s.append(x)``              | same as ``s[len(s):len(s)] =   |                     |
 |                              | [x]``                          |                     |
 +------------------------------+--------------------------------+---------------------+
+| ``s.clear()``                | remove all items from ``s``    | \(5)                |
+|                              | (same as ``del s[:]``)         |                     |
++------------------------------+--------------------------------+---------------------+
+| ``s.copy()``                 | return a shallow copy of ``s`` | \(5)                |
+|                              | (same as ``s[:]``)             |                     |
++------------------------------+--------------------------------+---------------------+
 | ``s.extend(t)``              | same as ``s[len(s):len(s)] =   |                     |
 |                              | t``                            |                     |
 +------------------------------+--------------------------------+---------------------+
    space when reversing a large sequence.  To remind users that it operates by
    side effect, it does not return the reversed sequence.
 
+(5)
+   :meth:`clear` and :meth:`!copy` are included for consistency with the
+   interfaces of mutable containers that don't support slicing operations
+   (such as :class:`dict` and :class:`set`)
+
+   .. versionadded:: 3.3
+      :meth:`clear` and :meth:`!copy` methods.
+
 
 .. _typesseq-list:
 
 
 Lists implement all of the :ref:`common <typesseq-common>` and
 :ref:`mutable <typesseq-mutable>` sequence operations. Lists also provide the
-following additional features:
-
-.. method:: list.index(x[, start[, stop]])
-    
-   While ``s.index(x)`` is specified as a common sequence operation, lists
-   permit additional arguments to the index method to allow efficient
-   searching of subsections of the list. Passing the extra arguments is
-   roughly equivalent to using ``s[start:stop].index(x)``, only without
-   copying any data and with the returned index being relative to the start
-   of the list rather than the start of the slice.
+following additional method:
 
 .. method:: list.sort(*, key=None, reverse=None)
 
 
    *key* specifies a function of one argument that is used to extract a
    comparison key from each list element (for example, ``key=str.lower``).
-   The default value of ``None`` means that list items are sorted directly.
-
+   The key corresponding to each item in the list is calculated once and
+   then used for the entire sorting process. The default value of ``None``
+   means that list items are sorted directly without calculating a separate
+   key value.
+ 
    The :func:`functools.cmp_to_key` utility is available to convert a 2.x
    style *cmp* function to a *key* function.
 
-   *reverse* is a boolean value.  If set to ``True``, then the list elements are
-   sorted as if each comparison were reversed.
+   *reverse* is a boolean value.  If set to ``True``, then the list elements
+   are sorted as if each comparison were reversed.
 
    This method modifies the sequence in place for economy of space when
    sorting a large sequence.  To remind users that it operates by side
 
 Ranges implement all of the :ref:`common <typesseq-common>` sequence operations
 except concatenation and repetition (due to the fact that range objects can
-only represent sequences that follow a strict pattern).
+only represent sequences that follow a strict pattern and repetition and
+concatenation will usually violate that pattern).
 
 
 .. _textseq:
    object: string
    object: bytes
    object: bytearray
-
-Strings contain Unicode characters.  Their literals are written in single or
-double quotes: ``'xyzzy'``, ``"frobozz"``.  See :ref:`strings` for more about
-string literals.  In addition to the functionality described here, there are
-also string-specific methods described in the :ref:`string-methods` section.
-
-Bytes and bytearray objects contain single bytes -- the former is immutable
-while the latter is a mutable sequence.  Bytes objects can be constructed the
-constructor, :func:`bytes`, and from literals; use a ``b`` prefix with normal
-string syntax: ``b'xyzzy'``.  To construct byte arrays, use the
-:func:`bytearray` function.
-
-While string objects are sequences of characters (represented by strings of
-length 1), bytes and bytearray objects are sequences of *integers* (between 0
-and 255), representing the ASCII value of single bytes.  That means that for
-a bytes or bytearray object *b*, ``b[0]`` will be an integer, while
-``b[0:1]`` will be a bytes or bytearray object of length 1.  The
-representation of bytes objects uses the literal format (``b'...'``) since it
-is generally more useful than e.g. ``bytes([50, 19, 100])``.  You can always
-convert a bytes object into a list of integers using ``list(b)``.
-
-Also, while in previous Python versions, byte strings and Unicode strings
-could be exchanged for each other rather freely (barring encoding issues),
-strings and bytes are now completely separate concepts.  There's no implicit
-en-/decoding if you pass an object of the wrong type.  A string always
-compares unequal to a bytes or bytearray object.
+   object: io.StringIO
+
+
+Textual data in Python is handled with :class:`str` objects, which are
+immutable sequences of Unicode code points.  String literals are
+written in a variety of ways:
+
+* Single quotes: ``'allows embedded "double" quotes'``
+* Double quotes: ``"allows embedded 'single' quotes"``.
+* Triple quoted: ``'''Three single quotes'''``, ``"""Three double quotes"""``
+
+Triple quoted strings may span multiple lines - all associated whitespace will
+be included in the string literal.
+
+String literals that are part of a single expression and have only whitespace
+between them will be implicitly converted to a single string literal. 
+
+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.
+
+There is no mutable string type, but :class:`io.StringIO` can be used to
+efficiently construct strings from multiple fragments.
+
 
 .. _string-methods:
 
 String Methods
 --------------
 
-.. index:: pair: string; methods
-
-String objects support the methods listed below.
-
-In addition, Python's strings support the sequence type methods described in the
-:ref:`typesseq` section. To output formatted strings, see the
-:ref:`string-formatting` section. Also, see the :mod:`re` module for string
-functions based on regular expressions.
+.. index::
+   pair: string; methods
+   module: re
+
+Strings implement all of the :ref:`common <typesseq-common>` sequence
+operations, along with the additional methods described below.
+
+Strings also support two styles of string formatting, one providing a large
+degree of flexibility and customization (see :meth:`str.format`,
+:ref:`formatstrings` and :ref:`string-formatting`) and the other based on C
+``printf`` style formatting that handles a narrower range of types and is
+slightly harder to use correctly, but is often faster for the cases it can
+handle (:ref:`old-string-formatting`).
+
+The :ref:`stringservices` section of the standard library covers a number of
+other modules that provide various text related utilities (including regular
+expression support in the :mod:`re` module).
 
 .. method:: str.capitalize()
 
 
 .. _old-string-formatting:
 
-Old String Formatting Operations
---------------------------------
+``printf``-style String Formatting
+----------------------------------
 
 .. index::
    single: formatting, string (%)
    single: % formatting
    single: % interpolation
 
-.. XXX is the note enough?
-
 .. note::
 
-   The formatting operations described here are obsolete and may go away in future
-   versions of Python.  Use the new :ref:`string-formatting` in new code.
+   The formatting operations described here exhibit a variety of quirks that
+   lead to a number of common errors (such as failing to display tuples and
+   dictionaries correctly).  Using the newer :meth:`str.format` interface
+   helps avoid these errors, and also provides a generally more powerful,
+   flexible and extensible approach to formatting text.
 
 String objects have one unique built-in operation: the ``%`` operator (modulo).
 This is also known as the string *formatting* or *interpolation* operator.
 Given ``format % values`` (where *format* is a string), ``%`` conversion
 specifications in *format* are replaced with zero or more elements of *values*.
-The effect is similar to the using :c:func:`sprintf` in the C language.
+The effect is similar to using the :c:func:`sprintf` in the C language.
 
 If *format* requires a single argument, *values* may be a single non-tuple
 object. [5]_  Otherwise, *values* must be a tuple with exactly the number of
    ``%f`` conversions for numbers whose absolute value is over 1e50 are no
    longer replaced by ``%g`` conversions.
 
-.. index::
-   module: string
-   module: re
-
-Additional string operations are defined in standard modules :mod:`string` and
-:mod:`re`.
-
 
 .. _binaryseq:
 
 
 .. TODO: clean up this section based on the restructure
 
+
+Bytes and bytearray objects contain single bytes -- the former is immutable
+while the latter is a mutable sequence.  Bytes objects can be constructed the
+constructor, :func:`bytes`, and from literals; use a ``b`` prefix with normal
+string syntax: ``b'xyzzy'``.  To construct byte arrays, use the
+:func:`bytearray` function.
+
+While string objects are sequences of characters (represented by strings of
+length 1), bytes and bytearray objects are sequences of *integers* (between 0
+and 255), representing the ASCII value of single bytes.  That means that for
+a bytes or bytearray object *b*, ``b[0]`` will be an integer, while
+``b[0:1]`` will be a bytes or bytearray object of length 1.  The
+representation of bytes objects uses the literal format (``b'...'``) since it
+is generally more useful than e.g. ``bytes([50, 19, 100])``.  You can always
+convert a bytes object into a list of integers using ``list(b)``.
+
+Also, while in previous Python versions, byte strings and Unicode strings
+could be exchanged for each other rather freely (barring encoding issues),
+strings and bytes are now completely separate concepts.  There's no implicit
+en-/decoding if you pass an object of the wrong type.  A string always
+compares unequal to a bytes or bytearray object.
+
+
 .. index:: object: bytearray
 
 List and bytearray objects support additional operations that allow in-place
 Note that while lists allow their items to be of any type, bytearray object
 "items" are all integers in the range 0 <= x < 256.
 
-<<<<<<< local
-=======
-.. index::
-   triple: operations on; sequence; types
-   triple: operations on; list; type
-   pair: subscript; assignment
-   pair: slice; assignment
-   statement: del
-   single: append() (sequence method)
-   single: extend() (sequence method)
-   single: count() (sequence method)
-   single: clear() (sequence method)
-   single: copy() (sequence method)
-   single: index() (sequence method)
-   single: insert() (sequence method)
-   single: pop() (sequence method)
-   single: remove() (sequence method)
-   single: reverse() (sequence method)
-   single: sort() (sequence method)
-
-+------------------------------+--------------------------------+---------------------+
-| Operation                    | Result                         | Notes               |
-+==============================+================================+=====================+
-| ``s[i] = x``                 | item *i* of *s* is replaced by |                     |
-|                              | *x*                            |                     |
-+------------------------------+--------------------------------+---------------------+
-| ``s[i:j] = t``               | slice of *s* from *i* to *j*   |                     |
-|                              | is replaced by the contents of |                     |
-|                              | the iterable *t*               |                     |
-+------------------------------+--------------------------------+---------------------+
-| ``del s[i:j]``               | same as ``s[i:j] = []``        |                     |
-+------------------------------+--------------------------------+---------------------+
-| ``s[i:j:k] = t``             | the elements of ``s[i:j:k]``   | \(1)                |
-|                              | are replaced by those of *t*   |                     |
-+------------------------------+--------------------------------+---------------------+
-| ``del s[i:j:k]``             | removes the elements of        |                     |
-|                              | ``s[i:j:k]`` from the list     |                     |
-+------------------------------+--------------------------------+---------------------+
-| ``s.append(x)``              | same as ``s[len(s):len(s)] =   |                     |
-|                              | [x]``                          |                     |
-+------------------------------+--------------------------------+---------------------+
-| ``s.extend(x)``              | same as ``s[len(s):len(s)] =   | \(2)                |
-|                              | x``                            |                     |
-+------------------------------+--------------------------------+---------------------+
-| ``s.clear()``                | remove all items from ``s``    |                     |
-|                              |                                |                     |
-+------------------------------+--------------------------------+---------------------+
-| ``s.copy()``                 | return a shallow copy of ``s`` |                     |
-|                              |                                |                     |
-+------------------------------+--------------------------------+---------------------+
-| ``s.count(x)``               | return number of *i*'s for     |                     |
-|                              | which ``s[i] == x``            |                     |
-+------------------------------+--------------------------------+---------------------+
-| ``s.index(x[, i[, j]])``     | return smallest *k* such that  | \(3)                |
-|                              | ``s[k] == x`` and ``i <= k <   |                     |
-|                              | j``                            |                     |
-+------------------------------+--------------------------------+---------------------+
-| ``s.insert(i, x)``           | same as ``s[i:i] = [x]``       | \(4)                |
-+------------------------------+--------------------------------+---------------------+
-| ``s.pop([i])``               | same as ``x = s[i]; del s[i];  | \(5)                |
-|                              | return x``                     |                     |
-+------------------------------+--------------------------------+---------------------+
-| ``s.remove(x)``              | same as ``del s[s.index(x)]``  | \(3)                |
-+------------------------------+--------------------------------+---------------------+
-| ``s.reverse()``              | reverses the items of *s* in   | \(6)                |
-|                              | place                          |                     |
-+------------------------------+--------------------------------+---------------------+
-| ``s.sort([key[, reverse]])`` | sort the items of *s* in place | (6), (7), (8)       |
-+------------------------------+--------------------------------+---------------------+
-
-
-Notes:
-
-(1)
-   *t* must have the same length as the slice it is replacing.
-
-(2)
-   *x* can be any iterable object.
-
-(3)
-   Raises :exc:`ValueError` when *x* is not found in *s*. When a negative index is
-   passed as the second or third parameter to the :meth:`index` method, the sequence
-   length is added, as for slice indices.  If it is still negative, it is truncated
-   to zero, as for slice indices.
-
-(4)
-   When a negative index is passed as the first parameter to the :meth:`insert`
-   method, the sequence length is added, as for slice indices.  If it is still
-   negative, it is truncated to zero, as for slice indices.
-
-(5)
-   The optional argument *i* defaults to ``-1``, so that by default the last
-   item is removed and returned.
-
-(6)
-   The :meth:`sort` and :meth:`reverse` methods modify the sequence in place for
-   economy of space when sorting or reversing a large sequence.  To remind you
-   that they operate by side effect, they don't return the sorted or reversed
-   sequence.
-
-(7)
-   The :meth:`sort` method takes optional arguments for controlling the
-   comparisons.  Each must be specified as a keyword argument.
-
-   *key* specifies a function of one argument that is used to extract a comparison
-   key from each list element: ``key=str.lower``.  The default value is ``None``.
-   Use :func:`functools.cmp_to_key` to convert an
-   old-style *cmp* function to a *key* function.
-
-
-   *reverse* is a boolean value.  If set to ``True``, then the list elements are
-   sorted as if each comparison were reversed.
-
-   The :meth:`sort` method is guaranteed to be stable.  A
-   sort is stable if it guarantees not to change the relative order of elements
-   that compare equal --- this is helpful for sorting in multiple passes (for
-   example, sort by department, then by salary grade).
-
-   .. impl-detail::
-
-      While a list is being sorted, the effect of attempting to mutate, or even
-      inspect, the list is undefined.  The C implementation of Python makes the
-      list appear empty for the duration, and raises :exc:`ValueError` if it can
-      detect that the list has been mutated during a sort.
-
-(8)
-   :meth:`sort` is not supported by :class:`bytearray` objects.
-
-    .. versionadded:: 3.3
-       :meth:`clear` and :meth:`!copy` methods.
-
->>>>>>> other
 
 .. _bytes-methods:
 

File Doc/library/strings.rst

 The modules described in this chapter provide a wide range of string
 manipulation operations.
 
-In addition, Python's built-in string classes support the sequence type methods
-described in the :ref:`typesseq` section, and also the string-specific methods
-described in the :ref:`string-methods` section.  To output formatted strings,
-see the :ref:`string-formatting` section. Also, see the :mod:`re` module for
-string functions based on regular expressions.
+The :mod:`codecs` module described under :ref:`binaryservices` is also
+highly relevant to text processing. In addition, see the documentation for
+Python's built-in string type in :ref:`textseq`.
 
 
 .. toctree::
 
    string.rst
    re.rst
-   struct.rst
    difflib.rst
    textwrap.rst
-   codecs.rst
    unicodedata.rst
    stringprep.rst