[Python-checkins] cpython: Address most of Ezio's comments. str/bytes/bytearray docs still need
nick.coghlan
python-checkins at python.org
Tue Aug 21 09:43:10 CEST 2012
http://hg.python.org/cpython/rev/28f424022c6e
changeset: 78694:28f424022c6e
user: Nick Coghlan <ncoghlan at gmail.com>
date: Tue Aug 21 17:42:52 2012 +1000
summary:
Address most of Ezio's comments. str/bytes/bytearray docs still need consolidation
files:
Doc/library/functions.rst | 109 +------
Doc/library/stdtypes.rst | 365 +++++++++++++++++--------
2 files changed, 266 insertions(+), 208 deletions(-)
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -17,9 +17,9 @@
: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`
+:func:`bytes` :func:`float` :func:`iter` :func:`print` |func-tuple|_
:func:`callable` :func:`format` :func:`len` :func:`property` :func:`type`
-:func:`chr` |func-frozenset|_ :func:`list` :func:`range` :func:`vars`
+:func:`chr` |func-frozenset|_ |func-list|_ |func-range|_ :func:`vars`
:func:`classmethod` :func:`getattr` :func:`locals` :func:`repr` :func:`zip`
:func:`compile` :func:`globals` :func:`map` :func:`reversed` :func:`__import__`
:func:`complex` :func:`hasattr` :func:`max` :func:`round`
@@ -33,6 +33,9 @@
.. |func-frozenset| replace:: ``frozenset()``
.. |func-memoryview| replace:: ``memoryview()``
.. |func-set| replace:: ``set()``
+.. |func-list| replace:: ``list()``
+.. |func-tuple| replace:: ``tuple()``
+.. |func-range| replace:: ``range()``
.. function:: abs(x)
@@ -93,6 +96,7 @@
.. index:: pair: Boolean; type
+.. _func-bytearray:
.. function:: bytearray([source[, encoding[, errors]]])
Return a new array of bytes. The :class:`bytearray` type is a mutable
@@ -119,6 +123,7 @@
Without an argument, an array of size 0 is created.
+.. _func-bytes:
.. function:: bytes([source[, encoding[, errors]]])
Return a new "bytes" object, which is an immutable sequence of integers in
@@ -692,16 +697,12 @@
sequence (string, tuple or list) or a mapping (dictionary).
+.. _func-list:
.. function:: list([iterable])
+ :noindex:
- Return a list whose items are the same and in the same order as *iterable*'s
- items. *iterable* may be either a sequence, a container that supports
- iteration, or an iterator object. If *iterable* is already a list, a copy is
- made and returned, similar to ``iterable[:]``. For instance, ``list('abc')``
- returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``.
- If no argument is given, returns a new empty list, ``[]``.
-
- :class:`list` is a mutable sequence type, as documented in :ref:`typesseq`.
+ Rather than being a function, :class:`list` is actually a mutable
+ sequence type, as documented in :ref:`typesseq`.
.. function:: locals()
@@ -1059,79 +1060,12 @@
``fdel`` corresponding to the constructor arguments.
-.. XXX does accept objects with __index__ too
+.. _func-range:
.. function:: range([start,] stop[, step])
+ :noindex:
- This is a versatile function to create iterables yielding arithmetic
- progressions. It is most often used in :keyword:`for` loops. The arguments
- must be integers. If the *step* argument is omitted, it defaults to ``1``.
- If the *start* argument is omitted, it defaults to ``0``. The full form
- returns an iterable of integers ``[start, start + step, start + 2 * step,
- ...]``. If *step* is positive, the last element is the largest ``start + i *
- step`` less than *stop*; if *step* is negative, the last element is the
- smallest ``start + i * step`` greater than *stop*. *step* must not be zero
- (or else :exc:`ValueError` is raised). Range objects have read-only data
- attributes :attr:`start`, :attr:`stop` and :attr:`step` which return the
- argument values (or their default). Example:
-
- >>> list(range(10))
- [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
- >>> list(range(1, 11))
- [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
- >>> list(range(0, 30, 5))
- [0, 5, 10, 15, 20, 25]
- >>> list(range(0, 10, 3))
- [0, 3, 6, 9]
- >>> list(range(0, -10, -1))
- [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
- >>> list(range(0))
- []
- >>> list(range(1, 0))
- []
-
- Range objects implement the :class:`collections.Sequence` ABC, and provide
- features such as containment tests, element index lookup, slicing and
- support for negative indices (see :ref:`typesseq`):
-
- >>> r = range(0, 20, 2)
- >>> r
- range(0, 20, 2)
- >>> 11 in r
- False
- >>> 10 in r
- True
- >>> r.index(10)
- 5
- >>> r[5]
- 10
- >>> r[:5]
- range(0, 10, 2)
- >>> r[-1]
- 18
-
- Testing range objects for equality with ``==`` and ``!=`` compares
- them as sequences. That is, two range objects are considered equal if
- they represent the same sequence of values. (Note that two range
- objects that compare equal might have different :attr:`start`,
- :attr:`stop` and :attr:`step` attributes, for example ``range(0) ==
- range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.)
-
- Ranges containing absolute values larger than :data:`sys.maxsize` are permitted
- but some features (such as :func:`len`) will raise :exc:`OverflowError`.
-
- .. versionchanged:: 3.2
- Implement the Sequence ABC.
- Support slicing and negative indices.
- Test integers for membership in constant time instead of iterating
- through all items.
-
- .. versionchanged:: 3.3
- Define '==' and '!=' to compare range objects based on the
- sequence of values they define (instead of comparing based on
- object identity).
-
- .. versionadded:: 3.3
- The :attr:`start`, :attr:`stop` and :attr:`step` attributes.
+ Rather than being a function, :class:`range` is actually an immutable
+ sequence type, as documented in :ref:`typesseq`.
.. function:: repr(object)
@@ -1251,6 +1185,7 @@
standard type hierarchy in :ref:`types`.
+.. _func-str:
.. function:: str([object[, encoding[, errors]]])
Return a string version of an object, using one of the following modes:
@@ -1352,16 +1287,12 @@
<http://rhettinger.wordpress.com/2011/05/26/super-considered-super/>`_.
+.. _func-tuple:
.. function:: tuple([iterable])
+ :noindex:
- Return a tuple whose items are the same and in the same order as *iterable*'s
- items. *iterable* may be a sequence, a container that supports iteration, or an
- iterator object. If *iterable* is already a tuple, it is returned unchanged.
- For instance, ``tuple('abc')`` returns ``('a', 'b', 'c')`` and ``tuple([1, 2,
- 3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty
- tuple, ``()``.
-
- :class:`tuple` is an immutable sequence type, as documented in :ref:`typesseq`.
+ Rather than being a function, :class:`tuple` is actually an immutable
+ sequence type, as documented in :ref:`typesseq`.
.. function:: type(object)
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -829,6 +829,20 @@
comparison operations. The ``+`` (concatenation) and ``*`` (repetition)
operations have the same priority as the corresponding numeric operations.
+.. index::
+ triple: operations on; sequence; types
+ builtin: len
+ builtin: min
+ builtin: max
+ pair: concatenation; operation
+ pair: repetition; operation
+ pair: subscript; operation
+ pair: slice; operation
+ operator: in
+ operator: not in
+ single: count() (sequence method)
+ single: index() (sequence method)
+
+--------------------------+--------------------------------+----------+
| Operation | Result | Notes |
+==========================+================================+==========+
@@ -841,8 +855,8 @@
| ``s + t`` | the concatenation of *s* and | (6)(7) |
| | *t* | |
+--------------------------+--------------------------------+----------+
-| ``s * n, n * s`` | *n* shallow copies of *s* | (2)(7) |
-| | concatenated | |
+| ``s * n`` or | *n* shallow copies of *s* | (2)(7) |
+| ``n * s`` | concatenated | |
+--------------------------+--------------------------------+----------+
| ``s[i]`` | *i*\ th item of *s*, origin 0 | \(3) |
+--------------------------+--------------------------------+----------+
@@ -857,7 +871,7 @@
+--------------------------+--------------------------------+----------+
| ``max(s)`` | largest item of *s* | |
+--------------------------+--------------------------------+----------+
-| ``s.index(x, [i[, j]])`` | index of the first occurence | \(8) |
+| ``s.index(x[, i[, j]])`` | index of the first occurence | \(8) |
| | of *x* in *s* (at or after | |
| | index *i* and before index *j*)| |
+--------------------------+--------------------------------+----------+
@@ -871,18 +885,6 @@
two sequences must be of the same type and have the same length. (For full
details see :ref:`comparisons` in the language reference.)
-.. index::
- triple: operations on; sequence; types
- builtin: len
- builtin: min
- builtin: max
- pair: concatenation; operation
- pair: repetition; operation
- pair: subscript; operation
- pair: slice; operation
- operator: in
- operator: not in
-
Notes:
(1)
@@ -948,14 +950,14 @@
* if concatenating :class:`str` objects, you can build a list and use
:meth:`str.join` at the end or else write to a :class:`io.StringIO`
- instance and retrieve its value when complete;
+ instance and retrieve its value when complete
* if concatenating :class:`bytes` objects, you can similarly use
:meth:`bytes.join` or :class:`io.BytesIO`, or you can do in-place
concatenation with a :class:`bytearray` object. :class:`bytearray`
- objects are mutable and have an efficient overallocation mechanism.
-
- * if concatenating :class:`tuple` objects, extend a :class:`list` instead.
+ objects are mutable and have an efficient overallocation mechanism
+
+ * if concatenating :class:`tuple` objects, extend a :class:`list` instead
* for other types, investigate the relevant class documentation
@@ -982,6 +984,7 @@
.. index::
triple: immutable; sequence; types
object: tuple
+ builtin: hash
The only operation that immutable sequence types generally implement that is
not also implemented by mutable sequence types is support for the :func:`hash`
@@ -1022,9 +1025,9 @@
pair: slice; assignment
statement: del
single: append() (sequence method)
+ single: clear() (sequence method)
+ single: copy() (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)
@@ -1048,24 +1051,29 @@
| ``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.append(x)`` | appends *x* to the end of the | |
+| | sequence (same as | |
+| | ``s[len(s):len(s)] = [x]``) | |
+------------------------------+--------------------------------+---------------------+
-| ``s.clear()`` | remove all items from ``s`` | \(5) |
+| ``s.clear()`` | removes all items from ``s`` | \(5) |
| | (same as ``del s[:]``) | |
+------------------------------+--------------------------------+---------------------+
-| ``s.copy()`` | return a shallow copy of ``s`` | \(5) |
+| ``s.copy()`` | creates a shallow copy of ``s``| \(5) |
| | (same as ``s[:]``) | |
+------------------------------+--------------------------------+---------------------+
-| ``s.extend(t)`` | same as ``s[len(s):len(s)] = | |
-| | t`` | |
+| ``s.extend(t)`` | extends *s* with the | |
+| | contents of *t* (same as | |
+| | ``s[len(s):len(s)] = t``) | |
+------------------------------+--------------------------------+---------------------+
-| ``s.insert(i, x)`` | same as ``s[i:i] = [x]`` | |
+| ``s.insert(i, x)`` | inserts *x* into *s* at the | |
+| | index given by *i* | |
+| | (same as ``s[i:i] = [x]``) | |
+------------------------------+--------------------------------+---------------------+
-| ``s.pop([i])`` | same as ``x = s[i]; del s[i]; | \(2) |
-| | return x`` | |
+| ``s.pop([i])`` | retrieves the item at *i* and | \(2) |
+| | also removes it from *s* | |
+------------------------------+--------------------------------+---------------------+
-| ``s.remove(x)`` | same as ``del s[s.index(x)]`` | \(3) |
+| ``s.remove(x)`` | remove the first item from *s* | \(3) |
+| | where ``s[i] == x`` | |
+------------------------------+--------------------------------+---------------------+
| ``s.reverse()`` | reverses the items of *s* in | \(4) |
| | place | |
@@ -1109,55 +1117,67 @@
homogeneous items (where the precise degree of similarity will vary by
application).
-Lists may be constructed in several ways:
-
-* Using a pair of square brackets to denote the empty list: ``[]``
-* Using square brackets, separating items with commas: ``[a]``, ``[a, b, c]``
-* Using a list comprehension: ``[x for x in iterable]``
-* Using the :func:`list` built-in: ``list()`` or ``list(iterable)``
-
-Many other operations also produce lists, including the :func:`sorted` built-in.
-
-Lists implement all of the :ref:`common <typesseq-common>` and
-:ref:`mutable <typesseq-mutable>` sequence operations. Lists also provide the
-following additional method:
-
-.. method:: list.sort(*, key=None, reverse=None)
-
- This method sorts the list in place, using only ``<`` comparisons
- between items. Exceptions are not suppressed - if any comparison operations
- fail, the entire sort operation will fail (and the list will likely be left
- in a partially modified state).
-
- *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 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.
-
- This method modifies the sequence in place for economy of space when
- sorting a large sequence. To remind users that it operates by side
- effect, it does not return the sorted sequence (use :func:`sorted` to
- explicitly request a new sorted list instance).
-
- 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.
+.. class:: list([iterable])
+
+ Lists may be constructed in several ways:
+
+ * Using a pair of square brackets to denote the empty list: ``[]``
+ * Using square brackets, separating items with commas: ``[a]``, ``[a, b, c]``
+ * Using a list comprehension: ``[x for x in iterable]``
+ * Using the type constructor: ``list()`` or ``list(iterable)``
+
+ The constructor builds a list whose items are the same and in the same
+ order as *iterable*'s items. *iterable* may be either a sequence, a
+ container that supports iteration, or an iterator object. If *iterable*
+ is already a list, a copy is made and returned, similar to ``iterable[:]``.
+ For example, ``list('abc')`` returns ``['a', 'b', 'c']`` and
+ ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``.
+ If no argument is given, the constructor creates a new empty list, ``[]``.
+
+
+ Many other operations also produce lists, including the :func:`sorted`
+ built-in.
+
+ Lists implement all of the :ref:`common <typesseq-common>` and
+ :ref:`mutable <typesseq-mutable>` sequence operations. Lists also provide the
+ following additional method:
+
+ .. method:: list.sort(*, key=None, reverse=None)
+
+ This method sorts the list in place, using only ``<`` comparisons
+ between items. Exceptions are not suppressed - if any comparison operations
+ fail, the entire sort operation will fail (and the list will likely be left
+ in a partially modified state).
+
+ *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 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.
+
+ This method modifies the sequence in place for economy of space when
+ sorting a large sequence. To remind users that it operates by side
+ effect, it does not return the sorted sequence (use :func:`sorted` to
+ explicitly request a new sorted list instance).
+
+ 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.
.. _typesseq-tuple:
@@ -1173,22 +1193,35 @@
homogeneous data is needed (such as allowing storage in a :class:`set` or
:class:`dict` instance).
-Tuples may be constructed in a number of ways:
-
-* Using a pair of parentheses to denote the empty tuple: ``()``
-* Using a trailing comma for a singleton tuple: ``a,`` or ``(a,)``
-* Separating items with commas: ``a, b, c`` or ``(a, b, c)``
-* Using the :func:`tuple` built-in: ``tuple()`` or ``tuple(iterable)``
-
-Note that the parentheses are optional (except in the empty tuple case, or
-when needed to avoid syntactic ambiguity). It is actually the comma which
-makes a tuple, not the parentheses.
-
-Tuples implement all of the :ref:`common <typesseq-common>` sequence
-operations.
-
-For heterogeneous collections of data, :func:`collections.namedtuple` may
-be more appropriate than a simple tuple object.
+.. class:: tuple([iterable])
+
+ Tuples may be constructed in a number of ways:
+
+ * Using a pair of parentheses to denote the empty tuple: ``()``
+ * Using a trailing comma for a singleton tuple: ``a,`` or ``(a,)``
+ * Separating items with commas: ``a, b, c`` or ``(a, b, c)``
+ * Using the :func:`tuple` built-in: ``tuple()`` or ``tuple(iterable)``
+
+ The constructor builds a tuple whose items are the same and in the same
+ order as *iterable*'s items. *iterable* may be either a sequence, a
+ container that supports iteration, or an iterator object. If *iterable*
+ is already a tuple, it is returned unchanged. For example,
+ ``tuple('abc')`` returns ``('a', 'b', 'c')`` and
+ ``tuple( [1, 2, 3] )`` returns ``(1, 2, 3)``.
+ If no argument is given, the constructor creates a new empty tuple, ``()``.
+
+ Note that it is actually the comma which makes a tuple, not the parentheses.
+ The parentheses are optional, except in the empty tuple case, or
+ when they are needed to avoid syntactic ambiguity. For example,
+ ``f(a, b, c)`` is a function call with three arguments, while
+ ``f((a, b, c))`` is a function call with a 3-tuple as the sole argument.
+
+ Tuples implement all of the :ref:`common <typesseq-common>` sequence
+ operations.
+
+For heterogeneous collections of data where access by name is clearer than
+access by index, :func:`collections.namedtuple` may be a more appropriate
+choice than a simple tuple object.
.. _typesseq-range:
@@ -1199,17 +1232,69 @@
.. index:: object: range
The :class:`range` type represents an immutable sequence of numbers and is
-commonly used for looping a specific number of times. Instances are created
-using the :func:`range` built-in.
-
-For positive indices with results between the defined ``start`` and ``stop``
-values, integers within the range are determined by the formula:
-``r[i] = start + step*i``
-
-For negative indices and slicing operations, a range instance determines the
-appropriate result for the corresponding tuple and returns either the
-appropriate integer (for negative indices) or an appropriate range object
-(for slicing operations) .
+commonly used for looping a specific number of times in :keyword:`for`
+loops.
+
+.. class:: range([start, ]stop[, step])
+
+ The arguments to the range constructor must be integers (either built-in
+ :class:`int` or any object that implements the ``__index__`` special
+ method). If the *step* argument is omitted, it defaults to ``1``.
+ If the *start* argument is omitted, it defaults to ``0``.
+ If *step* is zero, :exc:`ValueError` is raised.
+
+ For a positive *step*, the contents of a range ``r`` are determined by the
+ formula ``r[i] = start + step*i`` where ``i >= 0`` and
+ ``r[i] < stop``.
+
+ For a negative *step*, the contents of the range are still determined by
+ the formula ``r[i] = start + step*i``, but the constraints are ``i >= 0``
+ and ``r[i] > stop``.
+
+ A range object will be empty if ``r[0]`` does not meant the value
+ constraint. Ranges do support negative indices, but these are interpreted
+ as indexing from the end of the sequence determined by the positive
+ indices.
+
+ Ranges containing absolute values larger than :data:`sys.maxsize` are
+ permitted but some features (such as :func:`len`) may raise
+ :exc:`OverflowError`.
+
+ Range examples::
+
+ >>> list(range(10))
+ [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+ >>> list(range(1, 11))
+ [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ >>> list(range(0, 30, 5))
+ [0, 5, 10, 15, 20, 25]
+ >>> list(range(0, 10, 3))
+ [0, 3, 6, 9]
+ >>> list(range(0, -10, -1))
+ [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
+ >>> list(range(0))
+ []
+ >>> list(range(1, 0))
+ []
+
+ 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 and repetition and
+ concatenation will usually violate that pattern).
+
+ .. data: start
+
+ The value of the *start* parameter (or ``0`` if the parameter was
+ not supplied)
+
+ .. data: stop
+
+ The value of the *stop* parameter
+
+ .. data: step
+
+ The value of the *step* parameter (or ``1`` if the parameter was
+ not supplied)
The advantage of the :class:`range` type over a regular :class:`list` or
:class:`tuple` is that a :class:`range` object will always take the same
@@ -1217,10 +1302,46 @@
only stores the ``start``, ``stop`` and ``step`` values, calculating individual
items and subranges as needed).
-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 and repetition and
-concatenation will usually violate that pattern).
+Range objects implement the :class:`collections.Sequence` ABC, and provide
+features such as containment tests, element index lookup, slicing and
+support for negative indices (see :ref:`typesseq`):
+
+ >>> r = range(0, 20, 2)
+ >>> r
+ range(0, 20, 2)
+ >>> 11 in r
+ False
+ >>> 10 in r
+ True
+ >>> r.index(10)
+ 5
+ >>> r[5]
+ 10
+ >>> r[:5]
+ range(0, 10, 2)
+ >>> r[-1]
+ 18
+
+Testing range objects for equality with ``==`` and ``!=`` compares
+them as sequences. That is, two range objects are considered equal if
+they represent the same sequence of values. (Note that two range
+objects that compare equal might have different :attr:`start`,
+:attr:`stop` and :attr:`step` attributes, for example ``range(0) ==
+range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.)
+
+.. versionchanged:: 3.2
+ Implement the Sequence ABC.
+ Support slicing and negative indices.
+ Test :class:`int` objects for membership in constant time instead of
+ iterating through all items.
+
+.. versionchanged:: 3.3
+ Define '==' and '!=' to compare range objects based on the
+ sequence of values they define (instead of comparing based on
+ object identity).
+
+.. versionadded:: 3.3
+ The :attr:`start`, :attr:`stop` and :attr:`step` attributes.
.. _textseq:
@@ -1247,13 +1368,15 @@
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.
+between them will be implicitly converted to a single string literal. That
+is, ``("spam " "eggs") == "spam eggs"``.
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 :func:`str` built-in.
+Strings may also be created from other objects with the :ref:`str <func-str>`
+built-in.
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]``.
@@ -2002,6 +2125,8 @@
* From an iterable of integers: ``bytes(range(20))``
* Copying existing binary data via the buffer protocol: ``bytes(obj)``
+Also see the :ref:`bytes <func-bytes>` built-in.
+
Since bytes objects are sequences of integers, for a bytes object *b*,
``b[0]`` will be an integer, while ``b[0:1]`` will be a bytes object of
length 1. (This contrasts with text strings, where both indexing and
@@ -2043,6 +2168,8 @@
:ref:`mutable <typesseq-mutable>` sequence operations in addition to the
common bytes and bytearray operations described in :ref:`bytes-methods`.
+Also see the :ref:`bytearray <func-bytearray>` built-in.
+
.. _bytes-methods:
@@ -2097,15 +2224,15 @@
The search operations (:keyword:`in`, :meth:`count`, :meth:`find`,
:meth:`index`, :meth:`rfind` and :meth:`rindex`) all accept both integers
-in the range 0 to 255 as well as bytes and byte array sequences.
+in the range 0 to 255 (inclusive) as well as bytes and byte array sequences.
.. versionchanged:: 3.3
- All of the search methods also accept an integer in range 0 to 255
- (a byte) as their first argument.
+ All of the search methods also accept an integer in the range 0 to 255
+ (inclusive) as their first argument.
Each bytes and bytearray instance provides a :meth:`decode` convenience
-method that is the inverse of "meth:`str.encode`:
+method that is the inverse of :meth:`str.encode`:
.. method:: bytes.decode(encoding="utf-8", errors="strict")
bytearray.decode(encoding="utf-8", errors="strict")
@@ -2563,7 +2690,7 @@
Common uses include membership testing, removing duplicates from a sequence, and
computing mathematical operations such as intersection, union, difference, and
symmetric difference.
-(For other containers see the built in :class:`dict`, :class:`list`,
+(For other containers see the built-in :class:`dict`, :class:`list`,
and :class:`tuple` classes, and the :mod:`collections` module.)
Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in
@@ -2763,7 +2890,7 @@
A :dfn:`mapping` object maps :term:`hashable` values to arbitrary objects.
Mappings are mutable objects. There is currently only one standard mapping
-type, the :dfn:`dictionary`. (For other containers see the built in
+type, the :dfn:`dictionary`. (For other containers see the built-in
:class:`list`, :class:`set`, and :class:`tuple` classes, and the
:mod:`collections` module.)
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list