[Python-3000-checkins] r57834 - in python/branches/py3k/Doc: library/codecs.rst library/stdtypes.rst reference/expressions.rst
georg.brandl
python-3000-checkins at python.org
Fri Aug 31 12:15:40 CEST 2007
Author: georg.brandl
Date: Fri Aug 31 12:15:37 2007
New Revision: 57834
Modified:
python/branches/py3k/Doc/library/codecs.rst
python/branches/py3k/Doc/library/stdtypes.rst
python/branches/py3k/Doc/reference/expressions.rst
Log:
Add bytes methods documentation.
Modified: python/branches/py3k/Doc/library/codecs.rst
==============================================================================
--- python/branches/py3k/Doc/library/codecs.rst (original)
+++ python/branches/py3k/Doc/library/codecs.rst Fri Aug 31 12:15:37 2007
@@ -1117,6 +1117,8 @@
byte string. The result of the "decoding" direction is listed as operand type in
the table.
+.. XXX fix here, should be in above table
+
+--------------------+---------+----------------+---------------------------+
| Codec | Aliases | Operand type | Purpose |
+====================+=========+================+===========================+
Modified: python/branches/py3k/Doc/library/stdtypes.rst
==============================================================================
--- python/branches/py3k/Doc/library/stdtypes.rst (original)
+++ python/branches/py3k/Doc/library/stdtypes.rst Fri Aug 31 12:15:37 2007
@@ -504,7 +504,7 @@
constructed from literals too; use a ``b`` prefix with normal string syntax:
``b'xyzzy'``.
-.. caveat::
+.. warning::
While string objects are sequences of characters (represented by strings of
length 1), bytes objects are sequences of *integers* (between 0 and 255),
@@ -649,8 +649,6 @@
Formerly, string concatenation never occurred in-place.
-.. XXX add bytes methods
-
.. _string-methods:
String Methods
@@ -687,7 +685,7 @@
.. XXX what about str.decode???
.. method:: str.decode([encoding[, errors]])
- Decodes the string using the codec registered for *encoding*. *encoding*
+ Decode the string using the codec registered for *encoding*. *encoding*
defaults to the default string encoding. *errors* may be given to set a
different error handling scheme. The default is ``'strict'``, meaning that
encoding errors raise :exc:`UnicodeError`. Other possible values are
@@ -700,7 +698,7 @@
Support for other error handling schemes added.
-.. method:: str.encode([encoding[,errors]])
+.. method:: str.encode([encoding[, errors]])
Return an encoded version of the string. Default encoding is the current
default string encoding. *errors* may be given to set a different error
@@ -869,7 +867,7 @@
occurrences are replaced.
-.. method:: str.rfind(sub [,start [,end]])
+.. method:: str.rfind(sub[, start[, end]])
Return the highest index in the string where substring *sub* is found, such that
*sub* is contained within s[start,end]. Optional arguments *start* and *end*
@@ -902,7 +900,7 @@
.. versionadded:: 2.5
-.. method:: str.rsplit([sep [,maxsplit]])
+.. method:: str.rsplit([sep[, maxsplit]])
Return a list of the words in the string, using *sep* as the delimiter string.
If *maxsplit* is given, at most *maxsplit* splits are done, the *rightmost*
@@ -929,17 +927,17 @@
Support for the *chars* argument.
-.. method:: str.split([sep [,maxsplit]])
+.. method:: str.split([sep[, maxsplit]])
- Return a list of the words in the string, using *sep* as the delimiter string.
- If *maxsplit* is given, at most *maxsplit* splits are done. (thus, the list will
- have at most ``maxsplit+1`` elements). If *maxsplit* is not specified, then
- there is no limit on the number of splits (all possible splits are made).
- Consecutive delimiters are not grouped together and are deemed to delimit empty
- strings (for example, ``'1,,2'.split(',')`` returns ``['1', '', '2']``). The
- *sep* argument may consist of multiple characters (for example, ``'1, 2,
- 3'.split(', ')`` returns ``['1', '2', '3']``). Splitting an empty string with a
- specified separator returns ``['']``.
+ Return a list of the words in the string, using *sep* as the delimiter
+ string. If *maxsplit* is given, at most *maxsplit* splits are done (thus,
+ the list will have at most ``maxsplit+1`` elements). If *maxsplit* is not
+ specified, then there is no limit on the number of splits (all possible
+ splits are made). Consecutive delimiters are not grouped together and are
+ deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns
+ ``['1', '', '2']``). The *sep* argument may consist of multiple characters
+ (for example, ``'1, 2, 3'.split(', ')`` returns ``['1', '2', '3']``).
+ Splitting an empty string with a specified separator returns ``['']``.
If *sep* is not specified or is ``None``, a different splitting algorithm is
applied. First, whitespace characters (spaces, tabs, newlines, returns, and
@@ -999,7 +997,7 @@
.. method:: str.translate(map)
- Returns a copy of the *s* where all characters have been mapped through the
+ Return a copy of the *s* where all characters have been mapped through the
*map* which must be a mapping of Unicode ordinals (integers) to Unicode
ordinals, strings or ``None``. Unmapped characters are left
untouched. Characters mapped to ``None`` are deleted.
@@ -1043,7 +1041,7 @@
.. note::
- The formatting operations described here are obsolete and my go away in future
+ 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.
String objects have one unique built-in operation: the ``%`` operator (modulo).
@@ -1238,12 +1236,17 @@
.. index::
triple: mutable; sequence; types
object: list
+ object: bytes
+
+List and bytes objects support additional operations that allow in-place
+modification of the object. Other mutable sequence types (when added to the
+language) should also support these operations. Strings and tuples are
+immutable sequence types: such objects cannot be modified once created. The
+following operations are defined on mutable sequence types (where *x* is an
+arbitrary object).
-List objects support additional operations that allow in-place modification of
-the object. Other mutable sequence types (when added to the language) should
-also support these operations. Strings and tuples are immutable sequence types:
-such objects cannot be modified once created. The following operations are
-defined on mutable sequence types (where *x* is an arbitrary object):
+Note that while lists allow their items to be of any type, bytes object
+"items" are all integers in the range 0 <= x < 256.
+------------------------------+--------------------------------+---------------------+
| Operation | Result | Notes |
@@ -1263,30 +1266,30 @@
| ``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)] = | \(2) |
+| ``s.append(x)`` | same as ``s[len(s):len(s)] = | |
| | [x]`` | |
+------------------------------+--------------------------------+---------------------+
-| ``s.extend(x)`` | same as ``s[len(s):len(s)] = | \(3) |
+| ``s.extend(x)`` | same as ``s[len(s):len(s)] = | \(2) |
| | x`` | |
+------------------------------+--------------------------------+---------------------+
| ``s.count(x)`` | return number of *i*'s for | |
| | which ``s[i] == x`` | |
+------------------------------+--------------------------------+---------------------+
-| ``s.index(x[, i[, j]])`` | return smallest *k* such that | \(4) |
+| ``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]`` | \(5) |
+| ``s.insert(i, x)`` | same as ``s[i:i] = [x]`` | \(4) |
+------------------------------+--------------------------------+---------------------+
-| ``s.pop([i])`` | same as ``x = s[i]; del s[i]; | \(6) |
+| ``s.pop([i])`` | same as ``x = s[i]; del s[i]; | \(5) |
| | return x`` | |
+------------------------------+--------------------------------+---------------------+
-| ``s.remove(x)`` | same as ``del s[s.index(x)]`` | \(4) |
+| ``s.remove(x)`` | same as ``del s[s.index(x)]`` | \(3) |
+------------------------------+--------------------------------+---------------------+
-| ``s.reverse()`` | reverses the items of *s* in | \(7) |
+| ``s.reverse()`` | reverses the items of *s* in | \(6) |
| | place | |
+------------------------------+--------------------------------+---------------------+
-| ``s.sort([cmp[, key[, | sort the items of *s* in place | (7), (8), (9), (10) |
+| ``s.sort([cmp[, key[, | sort the items of *s* in place | (6), (7) |
| reverse]]])`` | | |
+------------------------------+--------------------------------+---------------------+
@@ -1297,32 +1300,27 @@
pair: slice; assignment
pair: extended slice; assignment
statement: del
- single: append() (list method)
- single: extend() (list method)
- single: count() (list method)
- single: index() (list method)
- single: insert() (list method)
- single: pop() (list method)
- single: remove() (list method)
- single: reverse() (list method)
- single: sort() (list method)
+ single: append() (sequence method)
+ single: extend() (sequence method)
+ single: count() (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)
Notes:
(1)
- *t* must have the same length as the slice it is replacing.
+ *t* must have the same length as the slice it is replacing.
(2)
- The C implementation of Python has historically accepted multiple parameters and
- implicitly joined them into a tuple; this no longer works in Python 2.0. Use of
- this misfeature has been deprecated since Python 1.4.
-
-(3)
*x* can be any iterable object.
-(4)
+(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 list
+ 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.
@@ -1330,25 +1328,27 @@
Previously, :meth:`index` didn't have arguments for specifying start and stop
positions.
-(5)
+(4)
When a negative index is passed as the first parameter to the :meth:`insert`
- method, the list length is added, as for slice indices. If it is still
+ method, the sequence length is added, as for slice indices. If it is still
negative, it is truncated to zero, as for slice indices.
.. versionchanged:: 2.3
Previously, all negative indices were truncated to zero.
+(5)
+ The optional argument *i* defaults to ``-1``, so that by default the last
+ item is removed and returned.
+
(6)
- The :meth:`pop` method is only supported by the list and array types. The
- optional argument *i* defaults to ``-1``, so that by default the last item is
- removed and returned.
+ 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` and :meth:`reverse` methods modify the list in place for
- economy of space when sorting or reversing a large list. To remind you that
- they operate by side effect, they don't return the sorted or reversed list.
+ :meth:`sort` is not supported by bytes objects.
-(8)
The :meth:`sort` method takes optional arguments for controlling the
comparisons.
@@ -1374,19 +1374,199 @@
.. versionchanged:: 2.4
Support for *key* and *reverse* was added.
-(9)
Starting with Python 2.3, 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).
-(10)
While a list is being sorted, the effect of attempting to mutate, or even
inspect, the list is undefined. The C implementation of Python 2.3 and newer
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.
+.. _bytes-methods:
+
+Bytes Methods
+-------------
+
+.. index:: pair: bytes; methods
+
+In addition to the operations on mutable sequence types (see
+:ref:`typesseq-mutable`), bytes objects, being "mutable ASCII strings" have
+further useful methods also found on strings.
+
+.. XXX documented "count" differently above
+
+.. method:: bytes.count(sub[, start[, end]])
+
+ In contrast to the standard sequence ``count`` method, this returns the
+ number of occurrences of substring (not item) *sub* in the slice
+ ``[start:end]``. Optional arguments *start* and *end* are interpreted as in
+ slice notation.
+
+
+.. method:: bytes.decode([encoding[, errors]])
+
+ Decode the bytes using the codec registered for *encoding*. *encoding*
+ defaults to the default string encoding. *errors* may be given to set a
+ different error handling scheme. The default is ``'strict'``, meaning that
+ encoding errors raise :exc:`UnicodeError`. Other possible values are
+ ``'ignore'``, ``'replace'`` and any other name registered via
+ :func:`codecs.register_error`, see section :ref:`codec-base-classes`.
+
+
+.. method:: bytes.endswith(suffix[, start[, end]])
+
+ Return ``True`` if the bytes object ends with the specified *suffix*,
+ otherwise return ``False``. *suffix* can also be a tuple of suffixes to look
+ for. With optional *start*, test beginning at that position. With optional
+ *end*, stop comparing at that position.
+
+
+.. method:: bytes.find(sub[, start[, end]])
+
+ Return the lowest index in the string where substring *sub* is found, such that
+ *sub* is contained in the range [*start*, *end*]. Optional arguments *start*
+ and *end* are interpreted as in slice notation. Return ``-1`` if *sub* is not
+ found.
+
+
+.. method:: bytes.fromhex(string)
+
+ This :class:`bytes` class method returns a bytes object, decoding the given
+ string object. The string must contain two hexadecimal digits per byte, spaces
+ are ignored.
+
+ Example::
+
+ >>> bytes.fromhex('f0 f1f2 ')
+ b'\xf0\xf1\xf2'
+
+
+.. method:: bytes.index(sub[, start[, end]])
+
+ Like :meth:`find`, but raise :exc:`ValueError` when the substring is not found.
+
+
+.. method:: bytes.join(seq)
+
+ Return a bytes object which is the concatenation of the bytes objects in the
+ sequence *seq*. The separator between elements is the bytes object providing
+ this method.
+
+
+.. method:: bytes.lstrip(which)
+
+ Return a copy of the bytes object with leading bytes removed. The *which*
+ argument is a bytes object specifying the set of bytes to be removed. As
+ with :meth:`str.lstrip`, the *which* argument is not a prefix; rather, all
+ combinations of its values are stripped.
+
+
+.. method:: bytes.partition(sep)
+
+ Split the bytes object at the first occurrence of *sep*, and return a 3-tuple
+ containing the part before the separator, the separator itself, and the part
+ after the separator. If the separator is not found, return a 3-tuple
+ containing the bytes object itself, followed by two empty strings.
+
+
+.. method:: bytes.replace(old, new[, count])
+
+ Return a copy of the bytes object with all occurrences of substring *old*
+ replaced by *new*. If the optional argument *count* is given, only the first
+ *count* occurrences are replaced.
+
+
+.. method:: bytes.rfind(sub[, start[, end]])
+
+ Return the highest index in the string where substring *sub* is found, such
+ that *sub* is contained within the slice ``[start:end]``. Optional arguments
+ *start* and *end* are interpreted as in slice notation. Return ``-1`` on
+ failure.
+
+
+.. method:: bytes.rindex(sub[, start[, end]])
+
+ Like :meth:`rfind` but raises :exc:`ValueError` when the substring *sub* is
+ not found.
+
+
+.. method:: bytes.rpartition(sep)
+
+ Split the bytes object at the last occurrence of *sep*, and return a 3-tuple
+ containing the part before the separator, the separator itself, and the part
+ after the separator. If the separator is not found, return a 3-tuple
+ containing two empty strings, followed by the string itself.
+
+
+.. method:: bytes.rsplit(sep[, maxsplit])
+
+ Return a list of substrings, using *sep* as the delimiter. If *maxsplit* is
+ given, at most *maxsplit* splits are done, the *rightmost* ones. Except for
+ splitting from the right, :meth:`rsplit` behaves like :meth:`split` which is
+ described in detail below.
+
+
+.. method:: bytes.rstrip(which)
+
+ Return a copy of the bytes object with trailing bytes removed. The *which*
+ argument is a bytes object specifying the set of bytes to be removed. As
+ with :meth:`str.rstrip`, The *chars* argument is not a suffix; rather, all
+ combinations of its values are stripped.
+
+
+.. method:: bytes.split(sep[, maxsplit])
+
+ Return a list of substrings, using *sep* as the delimiter. If *maxsplit* is
+ given, at most *maxsplit* splits are done (thus, the list will have at most
+ ``maxsplit+1`` elements). If *maxsplit* is not specified, then there is no
+ limit on the number of splits (all possible splits are made). Consecutive
+ delimiters are not grouped together and are deemed to delimit empty strings
+ (for example, ``b'1,,2'.split(b',')`` returns ``[b'1', b'', b'2']``). The
+ *sep* argument may consist of multiple bytes (for example, ``b'1, 2,
+ 3'.split(b', ')`` returns ``[b'1', b'2', b'3']``). Splitting an empty string
+ with a specified separator returns ``[b'']``.
+
+
+.. method:: bytes.startswith(prefix[, start[, end]])
+
+ Return ``True`` if the bytes object starts with the *prefix*, otherwise
+ return ``False``. *prefix* can also be a tuple of prefixes to look for.
+ With optional *start*, test string beginning at that position. With optional
+ *end*, stop comparing string at that position.
+
+
+.. method:: bytes.strip(which)
+
+ Return a copy of the bytes object with leading and trailing bytes found in
+ *which* removed. The *which* argument is a bytes object specifying the set
+ of characters to be removed. The *which* argument is not a prefix or suffix;
+ rather, all combinations of its values are stripped::
+
+ >>> b'www.example.com'.strip(b'cmowz.')
+ b'example'
+
+
+.. method:: bytes.translate(table[, deletechars])
+
+ Return a copy of the bytes object where all bytes occurring in the optional
+ argument *deletechars* are removed, and the remaining bytes have been mapped
+ through the given translation table, which must be a bytes object of length
+ 256.
+
+ You can use the :func:`maketrans` helper function in the :mod:`string` module to
+ create a translation table.
+
+ .. XXX a None table doesn't seem to be supported
+ For string objects, set the *table* argument to
+ ``None`` for translations that only delete characters::
+
+ >>> 'read this short text'.translate(None, 'aeiou')
+ 'rd ths shrt txt'
+
+
.. _types-set:
Set Types --- :class:`set`, :class:`frozenset`
Modified: python/branches/py3k/Doc/reference/expressions.rst
==============================================================================
--- python/branches/py3k/Doc/reference/expressions.rst (original)
+++ python/branches/py3k/Doc/reference/expressions.rst Fri Aug 31 12:15:37 2007
@@ -1272,7 +1272,7 @@
.. [#] While comparisons between strings make sense at the byte
level, they may be counter-intuitive to users. For example, the
- strings ``u"\u00C7"`` and ``u"\u0327\u0043"`` compare differently,
+ strings ``"\u00C7"`` and ``"\u0327\u0043"`` compare differently,
even though they both represent the same unicode character (LATIN
CAPTITAL LETTER C WITH CEDILLA).
More information about the Python-3000-checkins
mailing list