cpython-lru_cache-weakref: Doc/library/stdtypes.rst annotate

annotate Doc/library/stdtypes.rst @ 58925:eecf1bef052d 2.6

Merged revisions 78207 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r78207 | ezio.melotti | 2010-02-17 01:26:09 +0200 (Wed, 17 Feb 2010) | 1 line #7930: fix stripid ........

author	Ezio Melotti <ezio.melotti@gmail.com>
date	Tue, 16 Feb 2010 23:29:44 +0000
parents	89996755cf39
children	38e9b9da0164

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 .. XXX: reference/datamodel and this have quite a few overlaps!
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 .. _bltin-types:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 **************
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 Built-in Types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 **************
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 The following sections describe the standard types that are built into the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 interpreter.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 Historically (until release 2.2), Python's built-in types have differed from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 user-defined types because it was not possible to use the built-in types as the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 basis for object-oriented inheritance. This limitation no longer
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 exists.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 .. index:: pair: built-in; types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 The principal built-in types are numerics, sequences, mappings, files, classes,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 instances and exceptions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 .. index:: statement: print
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 Some operations are supported by several object types; in particular,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 practically all objects can be compared, tested for truth value, and converted
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 to a string (with the :func:`repr` function or the slightly different
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 :func:`str` function). The latter function is implicitly used when an object is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 written by the :func:`print` function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 .. _truth:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 Truth Value Testing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 ===================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 statement: if
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 statement: while
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 pair: truth; value
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 pair: Boolean; operations
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44 single: false
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 Any object can be tested for truth value, for use in an :keyword:`if` or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 :keyword:`while` condition or as operand of the Boolean operations below. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 following values are considered false:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 .. index:: single: None (Built-in object)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 * ``None``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 .. index:: single: False (Built-in object)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 * ``False``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 * zero of any numeric type, for example, ``0``, ``0L``, ``0.0``, ``0j``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 * any empty sequence, for example, ``''``, ``()``, ``[]``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 * any empty mapping, for example, ``{}``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 * instances of user-defined classes, if the class defines a :meth:`__nonzero__`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 or :meth:`__len__` method, when that method returns the integer zero or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 :class:`bool` value ``False``. [#]_
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 .. index:: single: true
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 All other values are considered true --- so objects of many types are always
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 true.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 operator: or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 operator: and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 single: False
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 single: True
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 Operations and built-in functions that have a Boolean result always return ``0``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80 or ``False`` for false and ``1`` or ``True`` for true, unless otherwise stated.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 (Important exception: the Boolean operations ``or`` and ``and`` always return
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 one of their operands.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 .. _boolean:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 Boolean Operations --- :keyword:`and`, :keyword:`or`, :keyword:`not`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 ====================================================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90 .. index:: pair: Boolean; operations
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 These are the Boolean operations, ordered by ascending priority:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 +-------------+---------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 \| Operation \| Result \| Notes \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 +=============+=================================+=======+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 \| ``x or y`` \| if x is false, then y, else \| \(1) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 \| \| x \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 +-------------+---------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 \| ``x and y`` \| if x is false, then x, else \| \(2) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 \| \| y \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 +-------------+---------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 \| ``not x`` \| if x is false, then ``True``, \| \(3) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 \| \| else ``False`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 +-------------+---------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 operator: and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 operator: or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 operator: not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 This is a short-circuit operator, so it only evaluates the second
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116 argument if the first one is :const:`False`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119 This is a short-circuit operator, so it only evaluates the second
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 argument if the first one is :const:`True`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 ``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127 .. _stdcomparisons:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 Comparisons
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 ===========
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131
56816 66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	132 .. index::
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	133 pair: chaining; comparisons
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	134 pair: operator; comparison
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	135 operator: ==
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	136 operator: <
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	137 operator: <=
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	138 operator: >
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	139 operator: >=
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	140 operator: !=
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	141 operator: is
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	142 operator: is not
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 Comparison operations are supported by all objects. They all have the same
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 priority (which is higher than that of the Boolean operations). Comparisons can
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147 y <= z``, except that y is evaluated only once (but in both cases z is not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148 evaluated at all when ``x < y`` is found to be false).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 This table summarizes the comparison operations:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 \| Operation \| Meaning \| Notes \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 +============+=========================+=======+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 \| ``<`` \| strictly less than \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 \| ``<=`` \| less than or equal \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 \| ``>`` \| strictly greater than \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 \| ``>=`` \| greater than or equal \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163 \| ``==`` \| equal \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 \| ``!=`` \| not equal \| \(1) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167 \| ``is`` \| object identity \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 \| ``is not`` \| negated object identity \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175 ``!=`` can also be written ``<>``, but this is an obsolete usage
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 kept for backwards compatibility only. New code should always use
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177 ``!=``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180 pair: object; numeric
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 pair: objects; comparing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 Objects of different types, except different numeric types and different string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 types, never compare equal; such objects are ordered consistently but
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 arbitrarily (so that sorting a heterogeneous array yields a consistent result).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 Furthermore, some types (for example, file objects) support only a degenerate
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187 notion of comparison where any two objects of that type are unequal. Again,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 such objects are ordered arbitrarily but consistently. The ``<``, ``<=``, ``>``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 and ``>=`` operators will raise a :exc:`TypeError` exception when any operand is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190 a complex number.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 .. index:: single: __cmp__() (instance method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194 Instances of a class normally compare as non-equal unless the class defines the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195 :meth:`__cmp__` method. Refer to :ref:`customization`) for information on the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 use of this method to effect object comparisons.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197
56824 b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	198 .. impl-detail::
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	199
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	200 Objects of different types except numbers are ordered by their type names;
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	201 objects of the same types that don't support proper comparison are ordered by
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	202 their address.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 operator: in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 operator: not in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 Two more operations with the same syntactic priority, ``in`` and ``not in``, are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 supported only by sequence types (below).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 .. _typesnumeric:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 Numeric Types --- :class:`int`, :class:`float`, :class:`long`, :class:`complex`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215 ===============================================================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 object: numeric
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 object: Boolean
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 object: integer
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 object: long integer
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 object: floating point
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 object: complex number
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 pair: C; language
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 There are four distinct numeric types: :dfn:`plain integers`, :dfn:`long
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 integers`, :dfn:`floating point numbers`, and :dfn:`complex numbers`. In
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 addition, Booleans are a subtype of plain integers. Plain integers (also just
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 called :dfn:`integers`) are implemented using :ctype:`long` in C, which gives
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 them at least 32 bits of precision (``sys.maxint`` is always set to the maximum
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 plain integer value for the current platform, the minimum value is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 ``-sys.maxint - 1``). Long integers have unlimited precision. Floating point
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 numbers are implemented using :ctype:`double` in C. All bets on their precision
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 are off unless you happen to know the machine you are working with.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 Complex numbers have a real and imaginary part, which are each implemented using
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 :ctype:`double` in C. To extract these parts from a complex number z, use
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238 ``z.real`` and ``z.imag``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 pair: numeric; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 pair: integer; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 triple: long; integer; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 pair: floating point; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 pair: complex number; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 pair: hexadecimal; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 pair: octal; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 Numbers are created by numeric literals or as the result of built-in functions
49619 06cf2cea387b Merged revisions 67060-67061 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49171 diff changeset	250 and operators. Unadorned integer literals (including binary, hex, and octal
06cf2cea387b Merged revisions 67060-67061 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49171 diff changeset	251 numbers) yield plain integers unless the value they denote is too large to be
06cf2cea387b Merged revisions 67060-67061 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49171 diff changeset	252 represented as a plain integer, in which case they yield a long integer.
06cf2cea387b Merged revisions 67060-67061 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49171 diff changeset	253 Integer literals with an ``'L'`` or ``'l'`` suffix yield long integers (``'L'``
06cf2cea387b Merged revisions 67060-67061 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49171 diff changeset	254 is preferred because ``1l`` looks too much like eleven!). Numeric literals
06cf2cea387b Merged revisions 67060-67061 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49171 diff changeset	255 containing a decimal point or an exponent sign yield floating point numbers.
06cf2cea387b Merged revisions 67060-67061 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49171 diff changeset	256 Appending ``'j'`` or ``'J'`` to a numeric literal yields a complex number with a
06cf2cea387b Merged revisions 67060-67061 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49171 diff changeset	257 zero real part. A complex numeric literal is the sum of a real and an imaginary
06cf2cea387b Merged revisions 67060-67061 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49171 diff changeset	258 part.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 single: arithmetic
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 builtin: int
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 builtin: long
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 builtin: float
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265 builtin: complex
56816 66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	266 operator: +
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	267 operator: -
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	268 operator: *
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	269 operator: /
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	270 operator: //
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	271 operator: %
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	272 operator: **
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 Python fully supports mixed arithmetic: when a binary arithmetic operator has
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275 operands of different numeric types, the operand with the "narrower" type is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276 widened to that of the other, where plain integer is narrower than long integer
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 is narrower than floating point is narrower than complex. Comparisons between
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 numbers of mixed type use the same rule. [#]_ The constructors :func:`int`,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 :func:`long`, :func:`float`, and :func:`complex` can be used to produce numbers
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 of a specific type.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281
56818 3e15a07a32fa Merged revisions 74209 via svnmerge from Georg Brandl <georg@python.org> parents: 56817 diff changeset	282 All built-in numeric types support the following operations. See
44432 4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just Jeffrey Yasskin <jyasskin@gmail.com> parents: 44383 diff changeset	283 :ref:`power` and later sections for the operators' priorities.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 \| Operation \| Result \| Notes \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 +====================+=================================+========+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288 \| ``x + y`` \| sum of x and y \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290 \| ``x - y`` \| difference of x and y \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292 \| ``x * y`` \| product of x and y \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 \| ``x / y`` \| quotient of x and y \| \(1) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295 +--------------------+---------------------------------+--------+
44432 4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just Jeffrey Yasskin <jyasskin@gmail.com> parents: 44383 diff changeset	296 \| ``x // y`` \| (floored) quotient of x and \| (4)(5) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297 \| \| y \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 \| ``x % y`` \| remainder of ``x / y`` \| \(4) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301 \| ``-x`` \| x negated \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303 \| ``+x`` \| x unchanged \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 +--------------------+---------------------------------+--------+
44432 4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just Jeffrey Yasskin <jyasskin@gmail.com> parents: 44383 diff changeset	305 \| ``abs(x)`` \| absolute value or magnitude of \| \(3) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306 \| \| x \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308 \| ``int(x)`` \| x converted to integer \| \(2) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 \| ``long(x)`` \| x converted to long integer \| \(2) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 +--------------------+---------------------------------+--------+
44344 1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms). Christian Heimes <christian@cheimes.de> parents: 44320 diff changeset	312 \| ``float(x)`` \| x converted to floating point \| \(6) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314 \| ``complex(re,im)`` \| a complex number with real part \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315 \| \| re, imaginary part im. \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316 \| \| im defaults to zero. \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 \| ``c.conjugate()`` \| conjugate of the complex number \| \|
44432 4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just Jeffrey Yasskin <jyasskin@gmail.com> parents: 44383 diff changeset	319 \| \| c. (Identity on real numbers) \| \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 \| ``divmod(x, y)`` \| the pair ``(x // y, x % y)`` \| (3)(4) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 +--------------------+---------------------------------+--------+
44526 507e76d7fcdd #1501: document that 0*0 == 1. Georg Brandl <georg@python.org>* parents: 44525 diff changeset	323 \| ``pow(x, y)`` \| x to the power y \| (3)(7) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 +--------------------+---------------------------------+--------+
44526 507e76d7fcdd #1501: document that 0*0 == 1. Georg Brandl <georg@python.org>* parents: 44525 diff changeset	325 \| ``x ** y`` \| x to the power y \| \(7) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 triple: operations on; numeric; types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330 single: conjugate() (complex number method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 pair: integer; division
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337 triple: long; integer; division
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339 For (plain or long) integer division, the result is an integer. The result is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340 always rounded towards minus infinity: 1/2 is 0, (-1)/2 is -1, 1/(-2) is -1, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 (-1)/(-2) is 0. Note that the result is a long integer if either operand is a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 long integer, regardless of the numeric value.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346 module: math
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 single: floor() (in module math)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348 single: ceil() (in module math)
50646 e496fdb927fa Merged revisions 68288-68291,68325-68326,68338,68388,68393,68423 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50522 diff changeset	349 single: trunc() (in module math)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350 pair: numeric; conversions
50240 edb2eefb6856 Clarify the round-off behavior of int(). Raymond Hettinger <python@rcn.com> parents: 49677 diff changeset	351
edb2eefb6856 Clarify the round-off behavior of int(). Raymond Hettinger <python@rcn.com> parents: 49677 diff changeset	352 Conversion from floats using :func:`int` or :func:`long` truncates toward
edb2eefb6856 Clarify the round-off behavior of int(). Raymond Hettinger <python@rcn.com> parents: 49677 diff changeset	353 zero like the related function, :func:`math.trunc`. Use the function
edb2eefb6856 Clarify the round-off behavior of int(). Raymond Hettinger <python@rcn.com> parents: 49677 diff changeset	354 :func:`math.floor` to round downward and :func:`math.ceil` to round
edb2eefb6856 Clarify the round-off behavior of int(). Raymond Hettinger <python@rcn.com> parents: 49677 diff changeset	355 upward.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 See :ref:`built-in-funcs` for a full description.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 (4)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361 Complex floor division operator, modulo operator, and :func:`divmod`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363 .. deprecated:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364 Instead convert to float using :func:`abs` if appropriate.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 (5)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367 Also referred to as integer division. The resultant value is a whole integer,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 though the result's type is not necessarily int.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369
44344 1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms). Christian Heimes <christian@cheimes.de> parents: 44320 diff changeset	370 (6)
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50240 diff changeset	371 float also accepts the strings "nan" and "inf" with an optional prefix "+"
44344 1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms). Christian Heimes <christian@cheimes.de> parents: 44320 diff changeset	372 or "-" for Not a Number (NaN) and positive or negative infinity.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50240 diff changeset	373
44344 1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms). Christian Heimes <christian@cheimes.de> parents: 44320 diff changeset	374 .. versionadded:: 2.6
1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms). Christian Heimes <christian@cheimes.de> parents: 44320 diff changeset	375
44526 507e76d7fcdd #1501: document that 0*0 == 1. Georg Brandl <georg@python.org>* parents: 44525 diff changeset	376 (7)
507e76d7fcdd #1501: document that 0*0 == 1. Georg Brandl <georg@python.org>* parents: 44525 diff changeset	377 Python defines ``pow(0, 0)`` and ``0 ** 0`` to be ``1``, as is common for
507e76d7fcdd #1501: document that 0*0 == 1. Georg Brandl <georg@python.org>* parents: 44525 diff changeset	378 programming languages.
507e76d7fcdd #1501: document that 0*0 == 1. Georg Brandl <georg@python.org>* parents: 44525 diff changeset	379
44432 4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just Jeffrey Yasskin <jyasskin@gmail.com> parents: 44383 diff changeset	380 All :class:`numbers.Real` types (:class:`int`, :class:`long`, and
4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just Jeffrey Yasskin <jyasskin@gmail.com> parents: 44383 diff changeset	381 :class:`float`) also include the following operations:
4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just Jeffrey Yasskin <jyasskin@gmail.com> parents: 44383 diff changeset	382
44488 94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	383 +--------------------+------------------------------------+--------+
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	384 \| Operation \| Result \| Notes \|
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	385 +====================+====================================+========+
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50646 diff changeset	386 \| ``math.trunc(x)`` \| x truncated to Integral \| \|
44488 94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	387 +--------------------+------------------------------------+--------+
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	388 \| ``round(x[, n])`` \| x rounded to n digits, \| \|
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	389 \| \| rounding half to even. If n is \| \|
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	390 \| \| omitted, it defaults to 0. \| \|
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	391 +--------------------+------------------------------------+--------+
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	392 \| ``math.floor(x)`` \| the greatest integral float <= x \| \|
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	393 +--------------------+------------------------------------+--------+
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	394 \| ``math.ceil(x)`` \| the least integral float >= x \| \|
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	395 +--------------------+------------------------------------+--------+
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	396
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	397 .. XXXJH exceptions: overflow (when? what operations?) zerodivision
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 .. _bitstring-ops:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 Bit-string Operations on Integer Types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403 --------------------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404
56816 66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	405 .. index::
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	406 triple: operations on; integer; types
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	407 pair: bit-string; operations
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	408 pair: shifting; operations
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	409 pair: masking; operations
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	410 operator: ^
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	411 operator: &
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	412 operator: <<
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from Georg Brandl <georg@python.org> parents: 56814 diff changeset	413 operator: >>
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415 Plain and long integer types support additional operations that make sense only
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 for bit-strings. Negative numbers are treated as their 2's complement value
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 (for long integers, this assumes a sufficiently large number of bits that no
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418 overflow occurs during the operation).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419
44497 01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. Georg Brandl <georg@python.org> parents: 44488 diff changeset	420 The priorities of the binary bitwise operations are all lower than the numeric
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421 operations and higher than the comparisons; the unary operation ``~`` has the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422 same priority as the other unary numeric operations (``+`` and ``-``).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423
46876 f4e61dcdb6f8 #2147: PEP 237 changes to overflow behavior. Georg Brandl <georg@python.org> parents: 46870 diff changeset	424 This table lists the bit-string operations sorted in ascending priority:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427 \| Operation \| Result \| Notes \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 +============+================================+==========+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429 \| ``x \| y`` \| bitwise :dfn:`or` of x and \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 \| \| y \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 \| ``x ^ y`` \| bitwise :dfn:`exclusive or` of \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433 \| \| x and y \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435 \| ``x & y`` \| bitwise :dfn:`and` of x and \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436 \| \| y \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437 +------------+--------------------------------+----------+
44555 7ea231578b02 Consistency nit. Georg Brandl <georg@python.org> parents: 44553 diff changeset	438 \| ``x << n`` \| x shifted left by n bits \| (1)(2) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439 +------------+--------------------------------+----------+
44555 7ea231578b02 Consistency nit. Georg Brandl <georg@python.org> parents: 44553 diff changeset	440 \| ``x >> n`` \| x shifted right by n bits \| (1)(3) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442 \| ``~x`` \| the bits of x inverted \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448 Negative shift counts are illegal and cause a :exc:`ValueError` to be raised.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	449
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450 (2)
46876 f4e61dcdb6f8 #2147: PEP 237 changes to overflow behavior. Georg Brandl <georg@python.org> parents: 46870 diff changeset	451 A left shift by n bits is equivalent to multiplication by ``pow(2, n)``. A
f4e61dcdb6f8 #2147: PEP 237 changes to overflow behavior. Georg Brandl <georg@python.org> parents: 46870 diff changeset	452 long integer is returned if the result exceeds the range of plain integers.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 (3)
46876 f4e61dcdb6f8 #2147: PEP 237 changes to overflow behavior. Georg Brandl <georg@python.org> parents: 46870 diff changeset	455 A right shift by n bits is equivalent to division by ``pow(2, n)``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457
47966 97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	458 Additional Methods on Float
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	459 ---------------------------
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	460
49171 52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	461 The float type has some additional methods.
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	462
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	463 .. method:: float.as_integer_ratio()
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	464
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	465 Return a pair of integers whose ratio is exactly equal to the
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	466 original float and with a positive denominator. Raises
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	467 :exc:`OverflowError` on infinities and a :exc:`ValueError` on
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	468 NaNs.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50240 diff changeset	469
49171 52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	470 .. versionadded:: 2.6
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	471
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	472 Two methods support conversion to
47966 97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	473 and from hexadecimal strings. Since Python's floats are stored
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	474 internally as binary numbers, converting a float to or from a
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	475 decimal string usually involves a small rounding error. In
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	476 contrast, hexadecimal strings allow exact representation and
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	477 specification of floating-point numbers. This can be useful when
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	478 debugging, and in numerical work.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	479
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	480
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	481 .. method:: float.hex()
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	482
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	483 Return a representation of a floating-point number as a hexadecimal
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	484 string. For finite floating-point numbers, this representation
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	485 will always include a leading ``0x`` and a trailing ``p`` and
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	486 exponent.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	487
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	488 .. versionadded:: 2.6
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	489
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	490
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	491 .. method:: float.fromhex(s)
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	492
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	493 Class method to return the float represented by a hexadecimal
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	494 string s. The string s may have leading and trailing
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	495 whitespace.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	496
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	497 .. versionadded:: 2.6
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	498
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	499
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	500 Note that :meth:`float.hex` is an instance method, while
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	501 :meth:`float.fromhex` is a class method.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	502
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	503 A hexadecimal string takes the form::
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	504
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	505 [sign] ['0x'] integer ['.' fraction] ['p' exponent]
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	506
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	507 where the optional ``sign`` may by either ``+`` or ``-``, ``integer``
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	508 and ``fraction`` are strings of hexadecimal digits, and ``exponent``
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	509 is a decimal integer with an optional leading sign. Case is not
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	510 significant, and there must be at least one hexadecimal digit in
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	511 either the integer or the fraction. This syntax is similar to the
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	512 syntax specified in section 6.4.4.2 of the C99 standard, and also to
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	513 the syntax used in Java 1.5 onwards. In particular, the output of
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	514 :meth:`float.hex` is usable as a hexadecimal floating-point literal in
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	515 C or Java code, and hexadecimal strings produced by C's ``%a`` format
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	516 character or Java's ``Double.toHexString`` are accepted by
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	517 :meth:`float.fromhex`.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	518
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	519
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	520 Note that the exponent is written in decimal rather than hexadecimal,
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	521 and that it gives the power of 2 by which to multiply the coefficient.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	522 For example, the hexadecimal string ``0x3.a7p10`` represents the
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	523 floating-point number ``(3 + 10./16 + 7./16*2) 2.0**10``, or
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	524 ``3740.0``::
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	525
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	526 >>> float.fromhex('0x3.a7p10')
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	527 3740.0
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	528
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	529
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	530 Applying the reverse conversion to ``3740.0`` gives a different
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	531 hexadecimal string representing the same number::
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	532
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	533 >>> float.hex(3740.0)
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	534 '0x1.d380000000000p+11'
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	535
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	536
47971 01fbe3fc883e Move label to correct heading. Georg Brandl <georg@python.org> parents: 47966 diff changeset	537 .. _typeiter:
01fbe3fc883e Move label to correct heading. Georg Brandl <georg@python.org> parents: 47966 diff changeset	538
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539 Iterator Types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540 ==============
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 single: iterator protocol
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546 single: protocol; iterator
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547 single: sequence; iteration
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548 single: container; iteration over
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550 Python supports a concept of iteration over containers. This is implemented
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551 using two distinct methods; these are used to allow user-defined classes to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552 support iteration. Sequences, described below in more detail, always support
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 the iteration methods.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555 One method needs to be defined for container objects to provide iteration
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556 support:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557
44578 19e1fa78d330 Fix two further doc build warnings. Georg Brandl <georg@python.org> parents: 44563 diff changeset	558 .. XXX duplicated in reference/datamodel!
19e1fa78d330 Fix two further doc build warnings. Georg Brandl <georg@python.org> parents: 44563 diff changeset	559
19e1fa78d330 Fix two further doc build warnings. Georg Brandl <georg@python.org> parents: 44563 diff changeset	560 .. method:: container.__iter__()
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562 Return an iterator object. The object is required to support the iterator
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563 protocol described below. If a container supports different types of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564 iteration, additional methods can be provided to specifically request
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 iterators for those iteration types. (An example of an object supporting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	566 multiple forms of iteration would be a tree structure which supports both
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567 breadth-first and depth-first traversal.) This method corresponds to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 :attr:`tp_iter` slot of the type structure for Python objects in the Python/C
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569 API.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	570
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571 The iterator objects themselves are required to support the following two
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572 methods, which together form the :dfn:`iterator protocol`:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	574
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575 .. method:: iterator.__iter__()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577 Return the iterator object itself. This is required to allow both containers
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578 and iterators to be used with the :keyword:`for` and :keyword:`in` statements.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579 This method corresponds to the :attr:`tp_iter` slot of the type structure for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580 Python objects in the Python/C API.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583 .. method:: iterator.next()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	584
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 Return the next item from the container. If there are no further items, raise
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586 the :exc:`StopIteration` exception. This method corresponds to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587 :attr:`tp_iternext` slot of the type structure for Python objects in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588 Python/C API.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	590 Python defines several iterator objects to support iteration over general and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591 specific sequence types, dictionaries, and other more specialized forms. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592 specific types are not important beyond their implementation of the iterator
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593 protocol.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	594
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595 The intention of the protocol is that once an iterator's :meth:`next` method
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	596 raises :exc:`StopIteration`, it will continue to do so on subsequent calls.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	597 Implementations that do not obey this property are deemed broken. (This
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598 constraint was added in Python 2.3; in Python 2.2, various iterators are broken
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	599 according to this rule.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600
56814 127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56803 diff changeset	601
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56803 diff changeset	602 .. _generator-types:
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56803 diff changeset	603
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56803 diff changeset	604 Generator Types
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56803 diff changeset	605 ---------------
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56803 diff changeset	606
43629 4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 43627 diff changeset	607 Python's :term:`generator`\s provide a convenient way to implement the iterator
4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 43627 diff changeset	608 protocol. If a container object's :meth:`__iter__` method is implemented as a
4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 43627 diff changeset	609 generator, it will automatically return an iterator object (technically, a
56814 127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56803 diff changeset	610 generator object) supplying the :meth:`__iter__` and :meth:`next` methods. More
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56803 diff changeset	611 information about generators can be found in :ref:`the documentation for the
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from Georg Brandl <georg@python.org> parents: 56803 diff changeset	612 yield expression <yieldexpr>`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	613
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	614
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	615 .. _typesseq:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	616
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	617 Sequence Types --- :class:`str`, :class:`unicode`, :class:`list`, :class:`tuple`, :class:`buffer`, :class:`xrange`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	618 ==================================================================================================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	619
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	620 There are six sequence types: strings, Unicode strings, lists, tuples, buffers,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621 and xrange objects.
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50646 diff changeset	622
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50646 diff changeset	623 For other containers see the built in :class:`dict` and :class:`set` classes,
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50646 diff changeset	624 and the :mod:`collections` module.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	625
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	626
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	627 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	628 object: sequence
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	629 object: string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630 object: Unicode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	631 object: tuple
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632 object: list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	633 object: buffer
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	634 object: xrange
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	635
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	636 String literals are written in single or double quotes: ``'xyzzy'``,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	637 ``"frobozz"``. See :ref:`strings` for more about string literals.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638 Unicode strings are much like strings, but are specified in the syntax
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	639 using a preceding ``'u'`` character: ``u'abc'``, ``u"def"``. In addition
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	640 to the functionality described here, there are also string-specific
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	641 methods described in the :ref:`string-methods` section. Lists are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	642 constructed with square brackets, separating items with commas: ``[a, b, c]``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643 Tuples are constructed by the comma operator (not within square
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	644 brackets), with or without enclosing parentheses, but an empty tuple
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	645 must have the enclosing parentheses, such as ``a, b, c`` or ``()``. A
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	646 single item tuple must have a trailing comma, such as ``(d,)``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	647
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	648 Buffer objects are not directly supported by Python syntax, but can be created
56818 3e15a07a32fa Merged revisions 74209 via svnmerge from Georg Brandl <georg@python.org> parents: 56817 diff changeset	649 by calling the built-in function :func:`buffer`. They don't support
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650 concatenation or repetition.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	652 Objects of type xrange are similar to buffers in that there is no specific syntax to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653 create them, but they are created using the :func:`xrange` function. They don't
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654 support slicing, concatenation or repetition, and using ``in``, ``not in``,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655 :func:`min` or :func:`max` on them is inefficient.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	657 Most sequence types support the following operations. The ``in`` and ``not in``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	658 operations have the same priorities as the comparison operations. The ``+`` and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	659 ``*`` operations have the same priority as the corresponding numeric operations.
44563 76fceb58bcf5 Added a hyperlink from sequence types to mutable sequence types. Mark Summerfield <list@qtrac.plus.com> parents: 44555 diff changeset	660 [#]_ Additional methods are provided for :ref:`typesseq-mutable`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662 This table lists the sequence operations sorted in ascending priority
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663 (operations in the same box have the same priority). In the table, s and t
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664 are sequences of the same type; n, i and j are integers:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	666 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	667 \| Operation \| Result \| Notes \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	668 +==================+================================+==========+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	669 \| ``x in s`` \| ``True`` if an item of s is \| \(1) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670 \| \| equal to x, else ``False`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	671 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672 \| ``x not in s`` \| ``False`` if an item of s is \| \(1) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673 \| \| equal to x, else ``True`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	674 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675 \| ``s + t`` \| the concatenation of s and \| \(6) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	676 \| \| t \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	678 \| ``s * n, n * s`` \| n shallow copies of s \| \(2) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679 \| \| concatenated \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681 \| ``s[i]`` \| i'th item of s, origin 0 \| \(3) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	682 +------------------+--------------------------------+----------+
44555 7ea231578b02 Consistency nit. Georg Brandl <georg@python.org> parents: 44553 diff changeset	683 \| ``s[i:j]`` \| slice of s from i to j \| (3)(4) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	684 +------------------+--------------------------------+----------+
44555 7ea231578b02 Consistency nit. Georg Brandl <georg@python.org> parents: 44553 diff changeset	685 \| ``s[i:j:k]`` \| slice of s from i to j \| (3)(5) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	686 \| \| with step k \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	687 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	688 \| ``len(s)`` \| length of s \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	689 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	690 \| ``min(s)`` \| smallest item of s \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	691 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	692 \| ``max(s)`` \| largest item of s \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	694
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	695 Sequence types also support comparisons. In particular, tuples and lists
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	696 are compared lexicographically by comparing corresponding
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	697 elements. This means that to compare equal, every element must compare
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	698 equal and the two sequences must be of the same type and have the same
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	699 length. (For full details see :ref:`comparisons` in the language
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700 reference.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703 triple: operations on; sequence; types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704 builtin: len
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705 builtin: min
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706 builtin: max
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	707 pair: concatenation; operation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	708 pair: repetition; operation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	709 pair: subscript; operation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	710 pair: slice; operation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	711 pair: extended slice; operation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	712 operator: in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	713 operator: not in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	714
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	715 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718 When s is a string or Unicode string object the ``in`` and ``not in``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719 operations act like a substring test. In Python versions before 2.3, x had to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720 be a string of length 1. In Python 2.3 and beyond, x may be a string of any
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721 length.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724 Values of n less than ``0`` are treated as ``0`` (which yields an empty
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725 sequence of the same type as s). Note also that the copies are shallow;
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726 nested structures are not copied. This often haunts new Python programmers;
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45800 diff changeset	727 consider:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	728
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729 >>> lists = [[]] * 3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730 >>> lists
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 [[], [], []]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732 >>> lists[0].append(3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733 >>> lists
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734 [[3], [3], [3]]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736 What has happened is that ``[[]]`` is a one-element list containing an empty
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737 list, so all three elements of ``[[]] * 3`` are (pointers to) this single empty
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738 list. Modifying any of the elements of ``lists`` modifies this single list.
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45800 diff changeset	739 You can create a list of different lists this way:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741 >>> lists = [[] for i in range(3)]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742 >>> lists[0].append(3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743 >>> lists[1].append(5)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744 >>> lists[2].append(7)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 >>> lists
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746 [[3], [5], [7]]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 If i or j is negative, the index is relative to the end of the string:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750 ``len(s) + i`` or ``len(s) + j`` is substituted. But note that ``-0`` is still
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 ``0``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753 (4)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754 The slice of s from i to j is defined as the sequence of items with index
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755 k such that ``i <= k < j``. If i or j is greater than ``len(s)``, use
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756 ``len(s)``. If i is omitted or ``None``, use ``0``. If j is omitted or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757 ``None``, use ``len(s)``. If i is greater than or equal to j, the slice is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758 empty.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	759
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760 (5)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761 The slice of s from i to j with step k is defined as the sequence of
44320 211abcfb4928 Remove gratuitous unicode character. Georg Brandl <georg@python.org> parents: 44103 diff changeset	762 items with index ``x = i + n*k`` such that ``0 <= n < (j-i)/k``. In other words,
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763 the indices are ``i``, ``i+k``, ``i+2k``, ``i+3k`` and so on, stopping when
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764 j is reached (but never including j). If i or j is greater than
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765 ``len(s)``, use ``len(s)``. If i or j are omitted or ``None``, they become
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766 "end" values (which end depends on the sign of k). Note, k cannot be zero.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767 If k is ``None``, it is treated like ``1``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 (6)
56824 b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	770 .. impl-detail::
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	771
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	772 If s and t are both strings, some Python implementations such as
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	773 CPython can usually perform an in-place optimization for assignments of
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	774 the form ``s = s + t`` or ``s += t``. When applicable, this optimization
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	775 makes quadratic run-time much less likely. This optimization is both
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	776 version and implementation dependent. For performance sensitive code, it
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	777 is preferable to use the :meth:`str.join` method which assures consistent
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	778 linear concatenation performance across versions and implementations.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	780 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781 Formerly, string concatenation never occurred in-place.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784 .. _string-methods:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	785
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786 String Methods
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787 --------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	788
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789 .. index:: pair: string; methods
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	791 Below are listed the string methods which both 8-bit strings and Unicode objects
43415 e1c09fa6fc0f #1176: document that string methods don't take keyword args. Georg Brandl <georg@python.org> parents: 43181 diff changeset	792 support. Note that none of these methods take keyword arguments.
e1c09fa6fc0f #1176: document that string methods don't take keyword args. Georg Brandl <georg@python.org> parents: 43181 diff changeset	793
e1c09fa6fc0f #1176: document that string methods don't take keyword args. Georg Brandl <georg@python.org> parents: 43181 diff changeset	794 In addition, Python's strings support the sequence type methods
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795 described in the :ref:`typesseq` section. To output formatted strings
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796 use template strings or the ``%`` operator described in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797 :ref:`string-formatting` section. Also, see the :mod:`re` module for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	798 string functions based on regular expressions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	799
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	800 .. method:: str.capitalize()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	801
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	802 Return a copy of the string with only its first character capitalized.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	803
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	804 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	805
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	806
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807 .. method:: str.center(width[, fillchar])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	808
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809 Return centered in a string of length width. Padding is done using the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	810 specified fillchar (default is a space).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	811
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	812 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813 Support for the fillchar argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	814
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	816 .. method:: str.count(sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	817
51817 0174b93669cd Merged revisions 69905 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	818 Return the number of non-overlapping occurrences of substring sub in the
0174b93669cd Merged revisions 69905 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	819 range [start, end]. Optional arguments start and end are
0174b93669cd Merged revisions 69905 via svnmerge from Georg Brandl <georg@python.org> parents: 51809 diff changeset	820 interpreted as in slice notation.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	821
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	822
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	823 .. method:: str.decode([encoding[, errors]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	824
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	825 Decodes the string using the codec registered for encoding. encoding
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	826 defaults to the default string encoding. errors may be given to set a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	827 different error handling scheme. The default is ``'strict'``, meaning that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828 encoding errors raise :exc:`UnicodeError`. Other possible values are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	829 ``'ignore'``, ``'replace'`` and any other name registered via
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	830 :func:`codecs.register_error`, see section :ref:`codec-base-classes`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	831
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	833
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	834 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	835 Support for other error handling schemes added.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	836
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	837
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	838 .. method:: str.encode([encoding[,errors]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	839
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	840 Return an encoded version of the string. Default encoding is the current
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	841 default string encoding. errors may be given to set a different error
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	842 handling scheme. The default for errors is ``'strict'``, meaning that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	843 encoding errors raise a :exc:`UnicodeError`. Other possible values are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	844 ``'ignore'``, ``'replace'``, ``'xmlcharrefreplace'``, ``'backslashreplace'`` and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	845 any other name registered via :func:`codecs.register_error`, see section
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	846 :ref:`codec-base-classes`. For a list of possible encodings, see section
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	847 :ref:`standard-encodings`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	848
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	849 .. versionadded:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	850
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	851 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	852 Support for ``'xmlcharrefreplace'`` and ``'backslashreplace'`` and other error
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	853 handling schemes added.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	854
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	855
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	856 .. method:: str.endswith(suffix[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	857
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	858 Return ``True`` if the string ends with the specified suffix, otherwise return
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	859 ``False``. suffix can also be a tuple of suffixes to look for. With optional
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	860 start, test beginning at that position. With optional end, stop comparing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	861 at that position.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	862
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	863 .. versionchanged:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	864 Accept tuples as suffix.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	865
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	866
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	867 .. method:: str.expandtabs([tabsize])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	868
43492 045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	869 Return a copy of the string where all tab characters are replaced by one or
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	870 more spaces, depending on the current column and the given tab size. The
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	871 column number is reset to zero after each newline occurring in the string.
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	872 If tabsize is not given, a tab size of ``8`` characters is assumed. This
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	873 doesn't understand other non-printing characters or escape sequences.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	874
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	875
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	876 .. method:: str.find(sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	877
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	878 Return the lowest index in the string where substring sub is found, such that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	879 sub is contained in the range [start, end]. Optional arguments start
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	880 and end are interpreted as in slice notation. Return ``-1`` if sub is not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	881 found.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	882
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	883
56803 bb8188736a29 Merged revisions 69987,70002,70061 via svnmerge from Georg Brandl <georg@python.org> parents: 56801 diff changeset	884 .. method:: str.format(args, *kwargs)
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	885
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	886 Perform a string formatting operation. The format_string argument can
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	887 contain literal text or replacement fields delimited by braces ``{}``. Each
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	888 replacement field contains either the numeric index of a positional argument,
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	889 or the name of a keyword argument. Returns a copy of format_string where
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	890 each replacement field is replaced with the string value of the corresponding
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	891 argument.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	892
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	893 >>> "The sum of 1 + 2 is {0}".format(1+2)
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	894 'The sum of 1 + 2 is 3'
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	895
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	896 See :ref:`formatstrings` for a description of the various formatting options
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	897 that can be specified in format strings.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	898
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	899 This method of string formatting is the new standard in Python 3.0, and
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	900 should be preferred to the ``%`` formatting described in
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	901 :ref:`string-formatting` in new code.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	902
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	903 .. versionadded:: 2.6
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	904
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	905
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	906 .. method:: str.index(sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	907
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	908 Like :meth:`find`, but raise :exc:`ValueError` when the substring is not found.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	909
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	910
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	911 .. method:: str.isalnum()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	912
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	913 Return true if all characters in the string are alphanumeric and there is at
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	914 least one character, false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	915
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	916 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	917
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	918
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	919 .. method:: str.isalpha()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	920
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	921 Return true if all characters in the string are alphabetic and there is at least
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	922 one character, false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	923
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	924 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	925
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	926
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	927 .. method:: str.isdigit()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	928
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	929 Return true if all characters in the string are digits and there is at least one
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	930 character, false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	931
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	932 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	933
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	934
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	935 .. method:: str.islower()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	936
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	937 Return true if all cased characters in the string are lowercase and there is at
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	938 least one cased character, false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	939
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	940 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	941
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	942
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	943 .. method:: str.isspace()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	944
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	945 Return true if there are only whitespace characters in the string and there is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	946 at least one character, false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	947
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	948 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	949
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	950
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	951 .. method:: str.istitle()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	952
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	953 Return true if the string is a titlecased string and there is at least one
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	954 character, for example uppercase characters may only follow uncased characters
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	955 and lowercase characters only cased ones. Return false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	956
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	957 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	958
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	959
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	960 .. method:: str.isupper()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	961
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	962 Return true if all cased characters in the string are uppercase and there is at
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	963 least one cased character, false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	964
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	965 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	966
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	967
56824 b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	968 .. method:: str.join(iterable)
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	969
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	970 Return a string which is the concatenation of the strings in the
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	971 :term:`iterable` iterable. The separator between elements is the string
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	972 providing this method.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	973
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	974
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	975 .. method:: str.ljust(width[, fillchar])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	976
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	977 Return the string left justified in a string of length width. Padding is done
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	978 using the specified fillchar (default is a space). The original string is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	979 returned if width is less than ``len(s)``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	980
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	981 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	982 Support for the fillchar argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	983
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	984
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	985 .. method:: str.lower()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	986
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	987 Return a copy of the string converted to lowercase.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	988
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	989 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	990
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	991
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	992 .. method:: str.lstrip([chars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	993
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	994 Return a copy of the string with leading characters removed. The chars
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	995 argument is a string specifying the set of characters to be removed. If omitted
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	996 or ``None``, the chars argument defaults to removing whitespace. The chars
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45800 diff changeset	997 argument is not a prefix; rather, all combinations of its values are stripped:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	998
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	999 >>> ' spacious '.lstrip()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1000 'spacious '
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1001 >>> 'www.example.com'.lstrip('cmowz.')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1002 'example.com'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1003
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1004 .. versionchanged:: 2.2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1005 Support for the chars argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1006
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1007
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1008 .. method:: str.partition(sep)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1009
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1010 Split the string at the first occurrence of sep, and return a 3-tuple
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1011 containing the part before the separator, the separator itself, and the part
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1012 after the separator. If the separator is not found, return a 3-tuple containing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1013 the string itself, followed by two empty strings.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1014
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1015 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1016
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1017
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1018 .. method:: str.replace(old, new[, count])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1019
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1020 Return a copy of the string with all occurrences of substring old replaced by
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1021 new. If the optional argument count is given, only the first count
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1022 occurrences are replaced.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1023
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1024
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1025 .. method:: str.rfind(sub [,start [,end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1026
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1027 Return the highest index in the string where substring sub is found, such that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1028 sub is contained within s[start,end]. Optional arguments start and end
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1029 are interpreted as in slice notation. Return ``-1`` on failure.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1030
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1031
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1032 .. method:: str.rindex(sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1033
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1034 Like :meth:`rfind` but raises :exc:`ValueError` when the substring sub is not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1035 found.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1036
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1037
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1038 .. method:: str.rjust(width[, fillchar])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1039
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1040 Return the string right justified in a string of length width. Padding is done
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1041 using the specified fillchar (default is a space). The original string is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1042 returned if width is less than ``len(s)``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1043
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1044 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1045 Support for the fillchar argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1046
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1047
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1048 .. method:: str.rpartition(sep)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1049
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1050 Split the string at the last occurrence of sep, and return a 3-tuple
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1051 containing the part before the separator, the separator itself, and the part
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1052 after the separator. If the separator is not found, return a 3-tuple containing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1053 two empty strings, followed by the string itself.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1054
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1055 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1056
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1057
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1058 .. method:: str.rsplit([sep [,maxsplit]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1059
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1060 Return a list of the words in the string, using sep as the delimiter string.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1061 If maxsplit is given, at most maxsplit splits are done, the rightmost
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1062 ones. If sep is not specified or ``None``, any whitespace string is a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1063 separator. Except for splitting from the right, :meth:`rsplit` behaves like
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1064 :meth:`split` which is described in detail below.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1065
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1066 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1067
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1068
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1069 .. method:: str.rstrip([chars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1070
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1071 Return a copy of the string with trailing characters removed. The chars
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1072 argument is a string specifying the set of characters to be removed. If omitted
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1073 or ``None``, the chars argument defaults to removing whitespace. The chars
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45800 diff changeset	1074 argument is not a suffix; rather, all combinations of its values are stripped:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1075
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1076 >>> ' spacious '.rstrip()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1077 ' spacious'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1078 >>> 'mississippi'.rstrip('ipz')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1079 'mississ'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1080
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1081 .. versionchanged:: 2.2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1082 Support for the chars argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1083
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1084
43492 045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1085 .. method:: str.split([sep[, maxsplit]])
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1086
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1087 Return a list of the words in the string, using sep as the delimiter
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1088 string. If maxsplit is given, at most maxsplit splits are done (thus,
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1089 the list will have at most ``maxsplit+1`` elements). If maxsplit is not
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1090 specified, then there is no limit on the number of splits (all possible
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1091 splits are made).
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1092
43738 79f5ca9ee154 Fix markup glitch. Georg Brandl <georg@python.org> parents: 43629 diff changeset	1093 If sep is given, consecutive delimiters are not grouped together and are
43492 045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1094 deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1095 ``['1', '', '2']``). The sep argument may consist of multiple characters
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1096 (for example, ``'1<>2<>3'.split('<>')`` returns ``['1', '2', '3']``).
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1097 Splitting an empty string with a specified separator returns ``['']``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1098
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1099 If sep is not specified or is ``None``, a different splitting algorithm is
43492 045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1100 applied: runs of consecutive whitespace are regarded as a single separator,
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1101 and the result will contain no empty strings at the start or end if the
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1102 string has leading or trailing whitespace. Consequently, splitting an empty
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1103 string or a string consisting of just whitespace with a ``None`` separator
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1104 returns ``[]``.
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1105
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1106 For example, ``' 1 2 3 '.split()`` returns ``['1', '2', '3']``, and
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1107 ``' 1 2 3 '.split(None, 1)`` returns ``['1', '2 3 ']``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1108
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1109
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1110 .. method:: str.splitlines([keepends])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1111
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1112 Return a list of the lines in the string, breaking at line boundaries. Line
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1113 breaks are not included in the resulting list unless keepends is given and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1114 true.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1115
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1116
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1117 .. method:: str.startswith(prefix[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1118
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1119 Return ``True`` if string starts with the prefix, otherwise return ``False``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1120 prefix can also be a tuple of prefixes to look for. With optional start,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1121 test string beginning at that position. With optional end, stop comparing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1122 string at that position.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1123
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1124 .. versionchanged:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1125 Accept tuples as prefix.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1126
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1127
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1128 .. method:: str.strip([chars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1129
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1130 Return a copy of the string with the leading and trailing characters removed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1131 The chars argument is a string specifying the set of characters to be removed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1132 If omitted or ``None``, the chars argument defaults to removing whitespace.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1133 The chars argument is not a prefix or suffix; rather, all combinations of its
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45800 diff changeset	1134 values are stripped:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1135
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1136 >>> ' spacious '.strip()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1137 'spacious'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1138 >>> 'www.example.com'.strip('cmowz.')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1139 'example'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1140
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1141 .. versionchanged:: 2.2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1142 Support for the chars argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1143
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1144
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1145 .. method:: str.swapcase()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1146
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1147 Return a copy of the string with uppercase characters converted to lowercase and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1148 vice versa.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1149
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1150 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1151
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1152
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1153 .. method:: str.title()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1154
56289 e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1155 Return a titlecased version of the string where words start with an uppercase
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1156 character and the remaining characters are lowercase.
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1157
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1158 The algorithm uses a simple language-independent definition of a word as
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1159 groups of consecutive letters. The definition works in many contexts but
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1160 it means that apostrophes in contractions and possessives form word
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1161 boundaries, which may not be the desired result::
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1162
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1163 >>> "they're bill's friends from the UK".title()
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1164 "They'Re Bill'S Friends From The Uk"
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1165
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1166 A workaround for apostrophes can be constructed using regular expressions::
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1167
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1168 >>> import re
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1169 >>> def titlecase(s):
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1170 return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1171 lambda mo: mo.group(0)[0].upper() +
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1172 mo.group(0)[1:].lower(),
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1173 s)
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1174
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1175 >>> titlecase("they're bill's friends.")
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55775 diff changeset	1176 "They're Bill's Friends."
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1177
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1178 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1179
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1180
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1181 .. method:: str.translate(table[, deletechars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1182
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1183 Return a copy of the string where all characters occurring in the optional
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1184 argument deletechars are removed, and the remaining characters have been
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1185 mapped through the given translation table, which must be a string of length
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1186 256.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1187
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1188 You can use the :func:`maketrans` helper function in the :mod:`string` module to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1189 create a translation table. For string objects, set the table argument to
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45800 diff changeset	1190 ``None`` for translations that only delete characters:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1191
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1192 >>> 'read this short text'.translate(None, 'aeiou')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1193 'rd ths shrt txt'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1194
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1195 .. versionadded:: 2.6
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1196 Support for a ``None`` table argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1197
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1198 For Unicode objects, the :meth:`translate` method does not accept the optional
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1199 deletechars argument. Instead, it returns a copy of the s where all
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1200 characters have been mapped through the given translation table which must be a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1201 mapping of Unicode ordinals to Unicode ordinals, Unicode strings or ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1202 Unmapped characters are left untouched. Characters mapped to ``None`` are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1203 deleted. Note, a more flexible approach is to create a custom character mapping
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1204 codec using the :mod:`codecs` module (see :mod:`encodings.cp1251` for an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1205 example).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1206
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1207
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1208 .. method:: str.upper()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1209
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1210 Return a copy of the string converted to uppercase.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1211
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1212 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1213
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1214
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1215 .. method:: str.zfill(width)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1216
43492 045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1217 Return the numeric string left filled with zeros in a string of length
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1218 width. A sign prefix is handled correctly. The original string is
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1219 returned if width is less than ``len(s)``.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50240 diff changeset	1220
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1221
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1222 .. versionadded:: 2.2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1223
45800 7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1224 The following methods are present only on unicode objects:
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1225
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1226 .. method:: unicode.isnumeric()
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1227
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1228 Return ``True`` if there are only numeric characters in S, ``False``
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1229 otherwise. Numeric characters include digit characters, and all characters
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1230 that have the Unicode numeric value property, e.g. U+2155,
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1231 VULGAR FRACTION ONE FIFTH.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50240 diff changeset	1232
45800 7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1233 .. method:: unicode.isdecimal()
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1234
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1235 Return ``True`` if there are only decimal characters in S, ``False``
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1236 otherwise. Decimal characters include digit characters, and all characters
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1237 that that can be used to form decimal-radix numbers, e.g. U+0660,
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1238 ARABIC-INDIC DIGIT ZERO.
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1239
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1240
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1241 .. _string-formatting:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1242
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1243 String Formatting Operations
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1244 ----------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1245
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1246 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1247 single: formatting, string (%)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1248 single: interpolation, string (%)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1249 single: string; formatting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1250 single: string; interpolation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1251 single: printf-style formatting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1252 single: sprintf-style formatting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1253 single: % formatting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1254 single: % interpolation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1255
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1256 String and Unicode objects have one unique built-in operation: the ``%``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1257 operator (modulo). This is also known as the string formatting or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1258 interpolation operator. Given ``format % values`` (where format is a string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1259 or Unicode object), ``%`` conversion specifications in format are replaced
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1260 with zero or more elements of values. The effect is similar to the using
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1261 :cfunc:`sprintf` in the C language. If format is a Unicode object, or if any
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1262 of the objects being converted using the ``%s`` conversion are Unicode objects,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1263 the result will also be a Unicode object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1264
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1265 If format requires a single argument, values may be a single non-tuple
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1266 object. [#]_ Otherwise, values must be a tuple with exactly the number of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1267 items specified by the format string, or a single mapping object (for example, a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1268 dictionary).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1269
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1270 A conversion specifier contains two or more characters and has the following
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1271 components, which must occur in this order:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1272
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1273 #. The ``'%'`` character, which marks the start of the specifier.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1274
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1275 #. Mapping key (optional), consisting of a parenthesised sequence of characters
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1276 (for example, ``(somename)``).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1277
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1278 #. Conversion flags (optional), which affect the result of some conversion
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1279 types.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1280
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1281 #. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1282 actual width is read from the next element of the tuple in values, and the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1283 object to convert comes after the minimum field width and optional precision.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1284
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1285 #. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1286 specified as ``'*'`` (an asterisk), the actual width is read from the next
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1287 element of the tuple in values, and the value to convert comes after the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1288 precision.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1289
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1290 #. Length modifier (optional).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1291
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1292 #. Conversion type.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1293
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1294 When the right argument is a dictionary (or other mapping type), then the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1295 formats in the string must include a parenthesised mapping key into that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1296 dictionary inserted immediately after the ``'%'`` character. The mapping key
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45800 diff changeset	1297 selects the value to be formatted from the mapping. For example:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1298
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1299 >>> print '%(language)s has %(#)03d quote types.' % \
46014 31cf38bdaac0 Enable doctest running for several other documents. Georg Brandl <georg@python.org> parents: 45800 diff changeset	1300 ... {'language': "Python", "#": 2}
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1301 Python has 002 quote types.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1302
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1303 In this case no ``*`` specifiers may occur in a format (since they require a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1304 sequential parameter list).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1305
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1306 The conversion flag characters are:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1307
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1308 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1309 \| Flag \| Meaning \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1310 +=========+=====================================================================+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1311 \| ``'#'`` \| The value conversion will use the "alternate form" (where defined \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1312 \| \| below). \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1313 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1314 \| ``'0'`` \| The conversion will be zero padded for numeric values. \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1315 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1316 \| ``'-'`` \| The converted value is left adjusted (overrides the ``'0'`` \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1317 \| \| conversion if both are given). \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1318 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1319 \| ``' '`` \| (a space) A blank should be left before a positive number (or empty \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1320 \| \| string) produced by a signed conversion. \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1321 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1322 \| ``'+'`` \| A sign character (``'+'`` or ``'-'``) will precede the conversion \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1323 \| \| (overrides a "space" flag). \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1324 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1325
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1326 A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it
46870 d88507588790 #1153769: document PEP 237 changes to string formatting. Georg Brandl <georg@python.org> parents: 46803 diff changeset	1327 is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1328
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1329 The conversion types are:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1330
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1331 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1332 \| Conversion \| Meaning \| Notes \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1333 +============+=====================================================+=======+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1334 \| ``'d'`` \| Signed integer decimal. \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1335 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1336 \| ``'i'`` \| Signed integer decimal. \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1337 +------------+-----------------------------------------------------+-------+
46870 d88507588790 #1153769: document PEP 237 changes to string formatting. Georg Brandl <georg@python.org> parents: 46803 diff changeset	1338 \| ``'o'`` \| Signed octal value. \| \(1) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1339 +------------+-----------------------------------------------------+-------+
52909 f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge Georg Brandl <georg@python.org> parents: 52900 diff changeset	1340 \| ``'u'`` \| Obsolete type -- it is identical to ``'d'``. \| \(7) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1341 +------------+-----------------------------------------------------+-------+
46870 d88507588790 #1153769: document PEP 237 changes to string formatting. Georg Brandl <georg@python.org> parents: 46803 diff changeset	1342 \| ``'x'`` \| Signed hexadecimal (lowercase). \| \(2) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1343 +------------+-----------------------------------------------------+-------+
46870 d88507588790 #1153769: document PEP 237 changes to string formatting. Georg Brandl <georg@python.org> parents: 46803 diff changeset	1344 \| ``'X'`` \| Signed hexadecimal (uppercase). \| \(2) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1345 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1346 \| ``'e'`` \| Floating point exponential format (lowercase). \| \(3) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1347 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1348 \| ``'E'`` \| Floating point exponential format (uppercase). \| \(3) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1349 +------------+-----------------------------------------------------+-------+
48003 5c33009994b4 Backed out r65069, pending fixing it in Windows. Eric Smith <eric@trueblade.com> parents: 48001 diff changeset	1350 \| ``'f'`` \| Floating point decimal format. \| \(3) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1351 +------------+-----------------------------------------------------+-------+
48003 5c33009994b4 Backed out r65069, pending fixing it in Windows. Eric Smith <eric@trueblade.com> parents: 48001 diff changeset	1352 \| ``'F'`` \| Floating point decimal format. \| \(3) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1353 +------------+-----------------------------------------------------+-------+
46692 f8468bfd4357 #2773: fix description of 'g' and 'G' formatting spec. Georg Brandl <georg@python.org> parents: 46014 diff changeset	1354 \| ``'g'`` \| Floating point format. Uses lowercase exponential \| \(4) \|
46693 ddd5f42332b9 > != (!<). Georg Brandl <georg@python.org> parents: 46692 diff changeset	1355 \| \| format if exponent is less than -4 or not less than \| \|
46692 f8468bfd4357 #2773: fix description of 'g' and 'G' formatting spec. Georg Brandl <georg@python.org> parents: 46014 diff changeset	1356 \| \| precision, decimal format otherwise. \| \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1357 +------------+-----------------------------------------------------+-------+
46692 f8468bfd4357 #2773: fix description of 'g' and 'G' formatting spec. Georg Brandl <georg@python.org> parents: 46014 diff changeset	1358 \| ``'G'`` \| Floating point format. Uses uppercase exponential \| \(4) \|
46693 ddd5f42332b9 > != (!<). Georg Brandl <georg@python.org> parents: 46692 diff changeset	1359 \| \| format if exponent is less than -4 or not less than \| \|
46692 f8468bfd4357 #2773: fix description of 'g' and 'G' formatting spec. Georg Brandl <georg@python.org> parents: 46014 diff changeset	1360 \| \| precision, decimal format otherwise. \| \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1361 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1362 \| ``'c'`` \| Single character (accepts integer or single \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1363 \| \| character string). \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1364 +------------+-----------------------------------------------------+-------+
57796 89996755cf39 Merged revisions 76904 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56824 diff changeset	1365 \| ``'r'`` \| String (converts any Python object using \| \(5) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1366 \| \| :func:`repr`). \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1367 +------------+-----------------------------------------------------+-------+
57796 89996755cf39 Merged revisions 76904 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 56824 diff changeset	1368 \| ``'s'`` \| String (converts any Python object using \| \(6) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1369 \| \| :func:`str`). \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1370 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1371 \| ``'%'`` \| No argument is converted, results in a ``'%'`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1372 \| \| character in the result. \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1373 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1374
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1375 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1376
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1377 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1378 The alternate form causes a leading zero (``'0'``) to be inserted between
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1379 left-hand padding and the formatting of the number if the leading character
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1380 of the result is not already a zero.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1381
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1382 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1383 The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1384 the ``'x'`` or ``'X'`` format was used) to be inserted between left-hand padding
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1385 and the formatting of the number if the leading character of the result is not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1386 already a zero.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1387
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1388 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1389 The alternate form causes the result to always contain a decimal point, even if
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1390 no digits follow it.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1391
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1392 The precision determines the number of digits after the decimal point and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1393 defaults to 6.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1394
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1395 (4)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1396 The alternate form causes the result to always contain a decimal point, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1397 trailing zeroes are not removed as they would otherwise be.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1398
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1399 The precision determines the number of significant digits before and after the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1400 decimal point and defaults to 6.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1401
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1402 (5)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1403 The ``%r`` conversion was added in Python 2.0.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1404
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1405 The precision determines the maximal number of characters used.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1406
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1407 (6)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1408 If the object or format provided is a :class:`unicode` string, the resulting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1409 string will also be :class:`unicode`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1410
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1411 The precision determines the maximal number of characters used.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1412
46870 d88507588790 #1153769: document PEP 237 changes to string formatting. Georg Brandl <georg@python.org> parents: 46803 diff changeset	1413 (7)
d88507588790 #1153769: document PEP 237 changes to string formatting. Georg Brandl <georg@python.org> parents: 46803 diff changeset	1414 See :pep:`237`.
d88507588790 #1153769: document PEP 237 changes to string formatting. Georg Brandl <georg@python.org> parents: 46803 diff changeset	1415
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1416 Since Python strings have an explicit length, ``%s`` conversions do not assume
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1417 that ``'\0'`` is the end of the string.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1418
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	1419 .. XXX Examples?
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1420
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1421 For safety reasons, floating point precisions are clipped to 50; ``%f``
52405 423c9477d6ef Merged revisions 70678 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 51817 diff changeset	1422 conversions for numbers whose absolute value is over 1e50 are replaced by ``%g``
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1423 conversions. [#]_ All other errors raise exceptions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1424
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1425 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1426 module: string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1427 module: re
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1428
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1429 Additional string operations are defined in standard modules :mod:`string` and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1430 :mod:`re`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1431
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1432
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1433 .. _typesseq-xrange:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1434
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1435 XRange Type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1436 -----------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1437
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1438 .. index:: object: xrange
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1439
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1440 The :class:`xrange` type is an immutable sequence which is commonly used for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1441 looping. The advantage of the :class:`xrange` type is that an :class:`xrange`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1442 object will always take the same amount of memory, no matter the size of the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1443 range it represents. There are no consistent performance advantages.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1444
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1445 XRange objects have very little behavior: they only support indexing, iteration,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1446 and the :func:`len` function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1447
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1448
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1449 .. _typesseq-mutable:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1450
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1451 Mutable Sequence Types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1452 ----------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1453
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1454 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1455 triple: mutable; sequence; types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1456 object: list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1457
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1458 List objects support additional operations that allow in-place modification of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1459 the object. Other mutable sequence types (when added to the language) should
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1460 also support these operations. Strings and tuples are immutable sequence types:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1461 such objects cannot be modified once created. The following operations are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1462 defined on mutable sequence types (where x is an arbitrary object):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1463
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1464 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1465 \| Operation \| Result \| Notes \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1466 +==============================+================================+=====================+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1467 \| ``s[i] = x`` \| item i of s is replaced by \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1468 \| \| x \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1469 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1470 \| ``s[i:j] = t`` \| slice of s from i to j \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1471 \| \| is replaced by the contents of \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1472 \| \| the iterable t \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1473 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1474 \| ``del s[i:j]`` \| same as ``s[i:j] = []`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1475 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1476 \| ``s[i:j:k] = t`` \| the elements of ``s[i:j:k]`` \| \(1) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1477 \| \| are replaced by those of t \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1478 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1479 \| ``del s[i:j:k]`` \| removes the elements of \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1480 \| \| ``s[i:j:k]`` from the list \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1481 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1482 \| ``s.append(x)`` \| same as ``s[len(s):len(s)] = \| \(2) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1483 \| \| [x]`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1484 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1485 \| ``s.extend(x)`` \| same as ``s[len(s):len(s)] = \| \(3) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1486 \| \| x`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1487 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1488 \| ``s.count(x)`` \| return number of i's for \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1489 \| \| which ``s[i] == x`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1490 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1491 \| ``s.index(x[, i[, j]])`` \| return smallest k such that \| \(4) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1492 \| \| ``s[k] == x`` and ``i <= k < \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1493 \| \| j`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1494 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1495 \| ``s.insert(i, x)`` \| same as ``s[i:i] = [x]`` \| \(5) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1496 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1497 \| ``s.pop([i])`` \| same as ``x = s[i]; del s[i]; \| \(6) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1498 \| \| return x`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1499 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1500 \| ``s.remove(x)`` \| same as ``del s[s.index(x)]`` \| \(4) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1501 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1502 \| ``s.reverse()`` \| reverses the items of s in \| \(7) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1503 \| \| place \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1504 +------------------------------+--------------------------------+---------------------+
44555 7ea231578b02 Consistency nit. Georg Brandl <georg@python.org> parents: 44553 diff changeset	1505 \| ``s.sort([cmp[, key[, \| sort the items of s in place \| (7)(8)(9)(10) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1506 \| reverse]]])`` \| \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1507 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1508
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1509 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1510 triple: operations on; sequence; types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1511 triple: operations on; list; type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1512 pair: subscript; assignment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1513 pair: slice; assignment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1514 pair: extended slice; assignment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1515 statement: del
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1516 single: append() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1517 single: extend() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1518 single: count() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1519 single: index() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1520 single: insert() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1521 single: pop() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1522 single: remove() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1523 single: reverse() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1524 single: sort() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1525
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1526 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1527
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1528 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1529 t must have the same length as the slice it is replacing.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1530
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1531 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1532 The C implementation of Python has historically accepted multiple parameters and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1533 implicitly joined them into a tuple; this no longer works in Python 2.0. Use of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1534 this misfeature has been deprecated since Python 1.4.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1535
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1536 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1537 x can be any iterable object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1538
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1539 (4)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1540 Raises :exc:`ValueError` when x is not found in s. When a negative index is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1541 passed as the second or third parameter to the :meth:`index` method, the list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1542 length is added, as for slice indices. If it is still negative, it is truncated
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1543 to zero, as for slice indices.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1544
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1545 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1546 Previously, :meth:`index` didn't have arguments for specifying start and stop
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1547 positions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1548
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1549 (5)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1550 When a negative index is passed as the first parameter to the :meth:`insert`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1551 method, the list length is added, as for slice indices. If it is still
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1552 negative, it is truncated to zero, as for slice indices.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1553
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1554 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1555 Previously, all negative indices were truncated to zero.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1556
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1557 (6)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1558 The :meth:`pop` method is only supported by the list and array types. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1559 optional argument i defaults to ``-1``, so that by default the last item is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1560 removed and returned.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1561
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1562 (7)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1563 The :meth:`sort` and :meth:`reverse` methods modify the list in place for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1564 economy of space when sorting or reversing a large list. To remind you that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1565 they operate by side effect, they don't return the sorted or reversed list.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1566
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1567 (8)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1568 The :meth:`sort` method takes optional arguments for controlling the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1569 comparisons.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1570
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1571 cmp specifies a custom comparison function of two arguments (list items) which
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1572 should return a negative, zero or positive number depending on whether the first
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1573 argument is considered smaller than, equal to, or larger than the second
44525 66197f8d0fdf #1755097: document default values for [].sort() and sorted(). Georg Brandl <georg@python.org> parents: 44524 diff changeset	1574 argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())``. The default value
66197f8d0fdf #1755097: document default values for [].sort() and sorted(). Georg Brandl <georg@python.org> parents: 44524 diff changeset	1575 is ``None``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1576
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1577 key specifies a function of one argument that is used to extract a comparison
44525 66197f8d0fdf #1755097: document default values for [].sort() and sorted(). Georg Brandl <georg@python.org> parents: 44524 diff changeset	1578 key from each list element: ``key=str.lower``. The default value is ``None``.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1579
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1580 reverse is a boolean value. If set to ``True``, then the list elements are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1581 sorted as if each comparison were reversed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1582
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1583 In general, the key and reverse conversion processes are much faster than
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1584 specifying an equivalent cmp function. This is because cmp is called
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1585 multiple times for each list element while key and reverse touch each
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1586 element only once.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1587
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1588 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1589 Support for ``None`` as an equivalent to omitting cmp was added.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1590
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1591 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1592 Support for key and reverse was added.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1593
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1594 (9)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1595 Starting with Python 2.3, the :meth:`sort` method is guaranteed to be stable. A
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1596 sort is stable if it guarantees not to change the relative order of elements
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1597 that compare equal --- this is helpful for sorting in multiple passes (for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1598 example, sort by department, then by salary grade).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1599
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1600 (10)
56824 b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1601 .. impl-detail::
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1602
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1603 While a list is being sorted, the effect of attempting to mutate, or even
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1604 inspect, the list is undefined. The C implementation of Python 2.3 and
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1605 newer makes the list appear empty for the duration, and raises
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1606 :exc:`ValueError` if it can detect that the list has been mutated during a
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1607 sort.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1608
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1609
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1610 .. _types-set:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1611
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1612 Set Types --- :class:`set`, :class:`frozenset`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1613 ==============================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1614
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1615 .. index:: object: set
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1616
43753 4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1617 A :dfn:`set` object is an unordered collection of distinct :term:`hashable` objects.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1618 Common uses include membership testing, removing duplicates from a sequence, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1619 computing mathematical operations such as intersection, union, difference, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1620 symmetric difference.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1621 (For other containers see the built in :class:`dict`, :class:`list`,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1622 and :class:`tuple` classes, and the :mod:`collections` module.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1623
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1624
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1625 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1626
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1627 Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1628 set``. Being an unordered collection, sets do not record element position or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1629 order of insertion. Accordingly, sets do not support indexing, slicing, or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1630 other sequence-like behavior.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1631
56818 3e15a07a32fa Merged revisions 74209 via svnmerge from Georg Brandl <georg@python.org> parents: 56817 diff changeset	1632 There are currently two built-in set types, :class:`set` and :class:`frozenset`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1633 The :class:`set` type is mutable --- the contents can be changed using methods
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1634 like :meth:`add` and :meth:`remove`. Since it is mutable, it has no hash value
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1635 and cannot be used as either a dictionary key or as an element of another set.
43753 4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1636 The :class:`frozenset` type is immutable and :term:`hashable` --- its contents cannot be
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1637 altered after it is created; it can therefore be used as a dictionary key or as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1638 an element of another set.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1639
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1640 The constructors for both classes work the same:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1641
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1642 .. class:: set([iterable])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1643 frozenset([iterable])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1644
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1645 Return a new set or frozenset object whose elements are taken from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1646 iterable. The elements of a set must be hashable. To represent sets of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1647 sets, the inner sets must be :class:`frozenset` objects. If iterable is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1648 not specified, a new empty set is returned.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1649
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1650 Instances of :class:`set` and :class:`frozenset` provide the following
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1651 operations:
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1652
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1653 .. describe:: len(s)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1654
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1655 Return the cardinality of set s.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1656
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1657 .. describe:: x in s
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1658
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1659 Test x for membership in s.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1660
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1661 .. describe:: x not in s
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1662
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1663 Test x for non-membership in s.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1664
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1665 .. method:: isdisjoint(other)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1666
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1667 Return True if the set has no elements in common with other. Sets are
47937 38d3a50defec fix various doc typos #3320 Benjamin Peterson <benjamin@python.org> parents: 47881 diff changeset	1668 disjoint if and only if their intersection is the empty set.
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1669
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1670 .. versionadded:: 2.6
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1671
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1672 .. method:: issubset(other)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1673 set <= other
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1674
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1675 Test whether every element in the set is in other.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1676
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1677 .. method:: set < other
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1678
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1679 Test whether the set is a true subset of other, that is,
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1680 ``set <= other and set != other``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1681
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1682 .. method:: issuperset(other)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1683 set >= other
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1684
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1685 Test whether every element in other is in the set.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1686
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1687 .. method:: set > other
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1688
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1689 Test whether the set is a true superset of other, that is, ``set >=
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1690 other and set != other``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1691
47530 d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1692 .. method:: union(other, ...)
d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1693 set \| other \| ...
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1694
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50646 diff changeset	1695 Return a new set with elements from the set and all others.
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1696
47530 d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1697 .. versionchanged:: 2.6
d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1698 Accepts multiple input iterables.
d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1699
47533 10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1700 .. method:: intersection(other, ...)
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1701 set & other & ...
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1702
51809 a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from Georg Brandl <georg@python.org> parents: 50646 diff changeset	1703 Return a new set with elements common to the set and all others.
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1704
47533 10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1705 .. versionchanged:: 2.6
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1706 Accepts multiple input iterables.
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1707
47588 8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1708 .. method:: difference(other, ...)
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1709 set - other - ...
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1710
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1711 Return a new set with elements in the set that are not in the others.
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1712
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1713 .. versionchanged:: 2.6
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1714 Accepts multiple input iterables.
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1715
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1716 .. method:: symmetric_difference(other)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1717 set ^ other
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1718
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1719 Return a new set with elements in either the set or other but not both.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1720
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1721 .. method:: copy()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1722
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1723 Return a new set with a shallow copy of s.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1724
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1725
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1726 Note, the non-operator versions of :meth:`union`, :meth:`intersection`,
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1727 :meth:`difference`, and :meth:`symmetric_difference`, :meth:`issubset`, and
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1728 :meth:`issuperset` methods will accept any iterable as an argument. In
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1729 contrast, their operator based counterparts require their arguments to be
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1730 sets. This precludes error-prone constructions like ``set('abc') & 'cbs'``
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1731 in favor of the more readable ``set('abc').intersection('cbs')``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1732
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1733 Both :class:`set` and :class:`frozenset` support set to set comparisons. Two
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1734 sets are equal if and only if every element of each set is contained in the
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1735 other (each is a subset of the other). A set is less than another set if and
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1736 only if the first set is a proper subset of the second set (is a subset, but
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1737 is not equal). A set is greater than another set if and only if the first set
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1738 is a proper superset of the second set (is a superset, but is not equal).
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1739
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1740 Instances of :class:`set` are compared to instances of :class:`frozenset`
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1741 based on their members. For example, ``set('abc') == frozenset('abc')``
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1742 returns ``True`` and so does ``set('abc') in set([frozenset('abc')])``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1743
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1744 The subset and equality comparisons do not generalize to a complete ordering
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1745 function. For example, any two disjoint sets are not equal and are not
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1746 subsets of each other, so all of the following return ``False``: ``a<b``,
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1747 ``a==b``, or ``a>b``. Accordingly, sets do not implement the :meth:`__cmp__`
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1748 method.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1749
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1750 Since sets only define partial ordering (subset relationships), the output of
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1751 the :meth:`list.sort` method is undefined for lists of sets.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1752
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1753 Set elements, like dictionary keys, must be :term:`hashable`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1754
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1755 Binary operations that mix :class:`set` instances with :class:`frozenset`
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1756 return the type of the first operand. For example: ``frozenset('ab') \|
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1757 set('bc')`` returns an instance of :class:`frozenset`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1758
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1759 The following table lists operations available for :class:`set` that do not
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1760 apply to immutable instances of :class:`frozenset`:
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1761
47530 d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1762 .. method:: update(other, ...)
d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1763 set \|= other \| ...
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1764
56820 85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	1765 Update the set, adding elements from all others.
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1766
47530 d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1767 .. versionchanged:: 2.6
d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1768 Accepts multiple input iterables.
d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1769
47533 10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1770 .. method:: intersection_update(other, ...)
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1771 set &= other & ...
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1772
56820 85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	1773 Update the set, keeping only elements found in it and all others.
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1774
47533 10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1775 .. versionchanged:: 2.6
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1776 Accepts multiple input iterables.
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1777
47588 8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1778 .. method:: difference_update(other, ...)
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1779 set -= other \| ...
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1780
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1781 Update the set, removing elements found in others.
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1782
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1783 .. versionchanged:: 2.6
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1784 Accepts multiple input iterables.
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1785
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1786 .. method:: symmetric_difference_update(other)
55775 39bcbf316dba Merged revisions 74590 via svnmerge from Georg Brandl <georg@python.org> parents: 55754 diff changeset	1787 set ^= other
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1788
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1789 Update the set, keeping only elements found in either set, but not in both.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1790
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1791 .. method:: add(elem)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1792
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1793 Add element elem to the set.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1794
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1795 .. method:: remove(elem)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1796
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1797 Remove element elem from the set. Raises :exc:`KeyError` if elem is
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1798 not contained in the set.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1799
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1800 .. method:: discard(elem)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1801
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1802 Remove element elem from the set if it is present.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1803
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1804 .. method:: pop()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1805
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1806 Remove and return an arbitrary element from the set. Raises
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1807 :exc:`KeyError` if the set is empty.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1808
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1809 .. method:: clear()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1810
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1811 Remove all elements from the set.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1812
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1813
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1814 Note, the non-operator versions of the :meth:`update`,
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1815 :meth:`intersection_update`, :meth:`difference_update`, and
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1816 :meth:`symmetric_difference_update` methods will accept any iterable as an
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1817 argument.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1818
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1819 Note, the elem argument to the :meth:`__contains__`, :meth:`remove`, and
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1820 :meth:`discard` methods may be a set. To support searching for an equivalent
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1821 frozenset, the elem set is temporarily mutated during the search and then
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1822 restored. During the search, the elem set should not be read or mutated
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1823 since it does not have a meaningful value.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1824
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1825
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1826 .. seealso::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1827
44050 eccb197044dd Fix reference target. Georg Brandl <georg@python.org> parents: 43805 diff changeset	1828 :ref:`comparison-to-builtin-set`
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1829 Differences between the :mod:`sets` module and the built-in set types.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1830
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1831
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1832 .. _typesmapping:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1833
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1834 Mapping Types --- :class:`dict`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1835 ===============================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1836
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1837 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1838 object: mapping
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1839 object: dictionary
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1840 triple: operations on; mapping; types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1841 triple: operations on; dictionary; type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1842 statement: del
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1843 builtin: len
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1844
43753 4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1845 A :dfn:`mapping` object maps :term:`hashable` values to arbitrary objects.
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1846 Mappings are mutable objects. There is currently only one standard mapping
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1847 type, the :dfn:`dictionary`. (For other containers see the built in
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1848 :class:`list`, :class:`set`, and :class:`tuple` classes, and the
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1849 :mod:`collections` module.)
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1850
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1851 A dictionary's keys are almost arbitrary values. Values that are not
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1852 :term:`hashable`, that is, values containing lists, dictionaries or other
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1853 mutable types (that are compared by value rather than by object identity) may
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1854 not be used as keys. Numeric types used for keys obey the normal rules for
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1855 numeric comparison: if two numbers compare equal (such as ``1`` and ``1.0``)
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1856 then they can be used interchangeably to index the same dictionary entry. (Note
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1857 however, that since computers store floating-point numbers as approximations it
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1858 is usually unwise to use them as dictionary keys.)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1859
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1860 Dictionaries can be created by placing a comma-separated list of ``key: value``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1861 pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1862 'jack', 4127: 'sjoerd'}``, or by the :class:`dict` constructor.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1863
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1864 .. class:: dict([arg])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1865
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1866 Return a new dictionary initialized from an optional positional argument or from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1867 a set of keyword arguments. If no arguments are given, return a new empty
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1868 dictionary. If the positional argument arg is a mapping object, return a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1869 dictionary mapping the same keys to the same values as does the mapping object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1870 Otherwise the positional argument must be a sequence, a container that supports
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1871 iteration, or an iterator object. The elements of the argument must each also
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1872 be of one of those kinds, and each must in turn contain exactly two objects.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1873 The first is used as a key in the new dictionary, and the second as the key's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1874 value. If a given key is seen more than once, the last value associated with it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1875 is retained in the new dictionary.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1876
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1877 If keyword arguments are given, the keywords themselves with their associated
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1878 values are added as items to the dictionary. If a key is specified both in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1879 positional argument and as a keyword argument, the value associated with the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1880 keyword is retained in the dictionary. For example, these all return a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1881 dictionary equal to ``{"one": 2, "two": 3}``:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1882
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1883 * ``dict(one=2, two=3)``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1884
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1885 * ``dict({'one': 2, 'two': 3})``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1886
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1887 * ``dict(zip(('one', 'two'), (2, 3)))``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1888
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1889 * ``dict([['two', 3], ['one', 2]])``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1890
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1891 The first example only works for keys that are valid Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1892 identifiers; the others work with any valid keys.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1893
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1894 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1895
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1896 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1897 Support for building a dictionary from keyword arguments added.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1898
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1899
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1900 These are the operations that dictionaries support (and therefore, custom
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1901 mapping types should support too):
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1902
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1903 .. describe:: len(d)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1904
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1905 Return the number of items in the dictionary d.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1906
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1907 .. describe:: d[key]
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1908
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1909 Return the item of d with key key. Raises a :exc:`KeyError` if key
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1910 is not in the map.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1911
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50240 diff changeset	1912 .. versionadded:: 2.5
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1913 If a subclass of dict defines a method :meth:`__missing__`, if the key
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1914 key is not present, the ``d[key]`` operation calls that method with
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1915 the key key as argument. The ``d[key]`` operation then returns or
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1916 raises whatever is returned or raised by the ``__missing__(key)`` call
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1917 if the key is not present. No other operations or methods invoke
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1918 :meth:`__missing__`. If :meth:`__missing__` is not defined,
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1919 :exc:`KeyError` is raised. :meth:`__missing__` must be a method; it
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1920 cannot be an instance variable. For an example, see
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1921 :class:`collections.defaultdict`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1922
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1923 .. describe:: d[key] = value
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1924
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1925 Set ``d[key]`` to value.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1926
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1927 .. describe:: del d[key]
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1928
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1929 Remove ``d[key]`` from d. Raises a :exc:`KeyError` if key is not in the
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1930 map.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1931
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1932 .. describe:: key in d
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1933
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1934 Return ``True`` if d has a key key, else ``False``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1935
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1936 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1937
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1938 .. describe:: key not in d
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1939
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1940 Equivalent to ``not key in d``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1941
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1942 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1943
52854 d90024620568 Merged revisions 71203 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52405 diff changeset	1944 .. describe:: iter(d)
d90024620568 Merged revisions 71203 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52405 diff changeset	1945
d90024620568 Merged revisions 71203 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52405 diff changeset	1946 Return an iterator over the keys of the dictionary. This is a shortcut
d90024620568 Merged revisions 71203 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52405 diff changeset	1947 for :meth:`iterkeys`.
d90024620568 Merged revisions 71203 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52405 diff changeset	1948
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1949 .. method:: clear()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1950
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1951 Remove all items from the dictionary.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1952
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1953 .. method:: copy()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1954
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1955 Return a shallow copy of the dictionary.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1956
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1957 .. method:: fromkeys(seq[, value])
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1958
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1959 Create a new dictionary with keys from seq and values set to value.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1960
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1961 :func:`fromkeys` is a class method that returns a new dictionary. value
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1962 defaults to ``None``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1963
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1964 .. versionadded:: 2.3
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1965
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1966 .. method:: get(key[, default])
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1967
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1968 Return the value for key if key is in the dictionary, else default.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1969 If default is not given, it defaults to ``None``, so that this method
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1970 never raises a :exc:`KeyError`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1971
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1972 .. method:: has_key(key)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1973
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49619 diff changeset	1974 Test for the presence of key in the dictionary. :meth:`has_key` is
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49619 diff changeset	1975 deprecated in favor of ``key in d``.
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1976
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1977 .. method:: items()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1978
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1979 Return a copy of the dictionary's list of ``(key, value)`` pairs.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1980
56824 b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1981 .. impl-detail::
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1982
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1983 Keys and values are listed in an arbitrary order which is non-random,
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1984 varies across Python implementations, and depends on the dictionary's
56824 b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1985 history of insertions and deletions.
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1986
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1987 If :meth:`items`, :meth:`keys`, :meth:`values`, :meth:`iteritems`,
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1988 :meth:`iterkeys`, and :meth:`itervalues` are called with no intervening
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1989 modifications to the dictionary, the lists will directly correspond. This
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1990 allows the creation of ``(value, key)`` pairs using :func:`zip`: ``pairs =
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1991 zip(d.values(), d.keys())``. The same relationship holds for the
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1992 :meth:`iterkeys` and :meth:`itervalues` methods: ``pairs =
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1993 zip(d.itervalues(), d.iterkeys())`` provides the same value for
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1994 ``pairs``. Another way to create the same list is ``pairs = [(v, k) for
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from Georg Brandl <georg@python.org> parents: 56820 diff changeset	1995 (k, v) in d.iteritems()]``.
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1996
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1997 .. method:: iteritems()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1998
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1999 Return an iterator over the dictionary's ``(key, value)`` pairs. See the
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2000 note for :meth:`dict.items`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2001
52854 d90024620568 Merged revisions 71203 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52405 diff changeset	2002 Using :meth:`iteritems` while adding or deleting entries in the dictionary
54350 acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 52909 diff changeset	2003 may raise a :exc:`RuntimeError` or fail to iterate over all entries.
52854 d90024620568 Merged revisions 71203 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52405 diff changeset	2004
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2005 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2006
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2007 .. method:: iterkeys()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2008
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2009 Return an iterator over the dictionary's keys. See the note for
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2010 :meth:`dict.items`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2011
52854 d90024620568 Merged revisions 71203 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52405 diff changeset	2012 Using :meth:`iterkeys` while adding or deleting entries in the dictionary
54350 acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 52909 diff changeset	2013 may raise a :exc:`RuntimeError` or fail to iterate over all entries.
52854 d90024620568 Merged revisions 71203 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52405 diff changeset	2014
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2015 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2016
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2017 .. method:: itervalues()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2018
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2019 Return an iterator over the dictionary's values. See the note for
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2020 :meth:`dict.items`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2021
52854 d90024620568 Merged revisions 71203 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52405 diff changeset	2022 Using :meth:`itervalues` while adding or deleting entries in the
54350 acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 52909 diff changeset	2023 dictionary may raise a :exc:`RuntimeError` or fail to iterate over all
acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from Georg Brandl <georg@python.org> parents: 52909 diff changeset	2024 entries.
52854 d90024620568 Merged revisions 71203 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52405 diff changeset	2025
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2026 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2027
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2028 .. method:: keys()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2029
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2030 Return a copy of the dictionary's list of keys. See the note for
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2031 :meth:`dict.items`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2032
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2033 .. method:: pop(key[, default])
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2034
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2035 If key is in the dictionary, remove it and return its value, else return
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2036 default. If default is not given and key is not in the dictionary,
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2037 a :exc:`KeyError` is raised.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2038
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2039 .. versionadded:: 2.3
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2040
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2041 .. method:: popitem()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2042
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2043 Remove and return an arbitrary ``(key, value)`` pair from the dictionary.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2044
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2045 :func:`popitem` is useful to destructively iterate over a dictionary, as
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2046 often used in set algorithms. If the dictionary is empty, calling
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2047 :func:`popitem` raises a :exc:`KeyError`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2048
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2049 .. method:: setdefault(key[, default])
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2050
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2051 If key is in the dictionary, return its value. If not, insert key
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2052 with a value of default and return default. default defaults to
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2053 ``None``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2054
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2055 .. method:: update([other])
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2056
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2057 Update the dictionary with the key/value pairs from other, overwriting
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2058 existing keys. Return ``None``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2059
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2060 :func:`update` accepts either another dictionary object or an iterable of
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2061 key/value pairs (as a tuple or other iterable of length two). If keyword
56820 85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	2062 arguments are specified, the dictionary is then updated with those
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2063 key/value pairs: ``d.update(red=1, blue=2)``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2064
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2065 .. versionchanged:: 2.4
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2066 Allowed the argument to be an iterable of key/value pairs and allowed
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2067 keyword arguments.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2068
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2069 .. method:: values()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2070
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2071 Return a copy of the dictionary's list of values. See the note for
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2072 :meth:`dict.items`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2073
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2074
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2075 .. _bltin-file-objects:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2076
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2077 File Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2078 ============
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2079
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2080 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2081 object: file
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2082 builtin: file
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2083 module: os
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2084 module: socket
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2085
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2086 File objects are implemented using C's ``stdio`` package and can be
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	2087 created with the built-in :func:`open` function. File
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2088 objects are also returned by some other built-in functions and methods,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2089 such as :func:`os.popen` and :func:`os.fdopen` and the :meth:`makefile`
43748 8a40b831ab68 Added more file-handling related cross-references. Mark Summerfield <list@qtrac.plus.com> parents: 43738 diff changeset	2090 method of socket objects. Temporary files can be created using the
8a40b831ab68 Added more file-handling related cross-references. Mark Summerfield <list@qtrac.plus.com> parents: 43738 diff changeset	2091 :mod:`tempfile` module, and high-level file operations such as copying,
8a40b831ab68 Added more file-handling related cross-references. Mark Summerfield <list@qtrac.plus.com> parents: 43738 diff changeset	2092 moving, and deleting files and directories can be achieved with the
8a40b831ab68 Added more file-handling related cross-references. Mark Summerfield <list@qtrac.plus.com> parents: 43738 diff changeset	2093 :mod:`shutil` module.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2094
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2095 When a file operation fails for an I/O-related reason, the exception
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2096 :exc:`IOError` is raised. This includes situations where the operation is not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2097 defined for some reason, like :meth:`seek` on a tty device or writing a file
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2098 opened for reading.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2099
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2100 Files have the following methods:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2101
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2102
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2103 .. method:: file.close()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2104
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2105 Close the file. A closed file cannot be read or written any more. Any operation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2106 which requires that the file be open will raise a :exc:`ValueError` after the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2107 file has been closed. Calling :meth:`close` more than once is allowed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2108
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2109 As of Python 2.5, you can avoid having to call this method explicitly if you use
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2110 the :keyword:`with` statement. For example, the following code will
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	2111 automatically close f when the :keyword:`with` block is exited::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2112
48097 0c7fab0b05c0 the from __future__ import with_statement isn't needed in 2.6 Benjamin Peterson <benjamin@python.org> parents: 48081 diff changeset	2113 from __future__ import with_statement # This isn't required in Python 2.6
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2114
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2115 with open("hello.txt") as f:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2116 for line in f:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2117 print line
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2118
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2119 In older versions of Python, you would have needed to do this to get the same
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2120 effect::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2121
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2122 f = open("hello.txt")
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2123 try:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2124 for line in f:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2125 print line
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2126 finally:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2127 f.close()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2128
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2129 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2130
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2131 Not all "file-like" types in Python support use as a context manager for the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2132 :keyword:`with` statement. If your code is intended to work with any file-like
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2133 object, you can use the function :func:`contextlib.closing` instead of using
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2134 the object directly.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2135
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2136
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2137 .. method:: file.flush()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2138
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2139 Flush the internal buffer, like ``stdio``'s :cfunc:`fflush`. This may be a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2140 no-op on some file-like objects.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2141
56801 e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from Georg Brandl <georg@python.org> parents: 56289 diff changeset	2142 .. note::
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from Georg Brandl <georg@python.org> parents: 56289 diff changeset	2143
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from Georg Brandl <georg@python.org> parents: 56289 diff changeset	2144 :meth:`flush` does not necessarily write the file's data to disk. Use
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from Georg Brandl <georg@python.org> parents: 56289 diff changeset	2145 :meth:`flush` followed by :func:`os.fsync` to ensure this behavior.
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from Georg Brandl <georg@python.org> parents: 56289 diff changeset	2146
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2147
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2148 .. method:: file.fileno()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2149
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2150 .. index::
43627 faf5de69e977 Add :term:s for descriptors. Georg Brandl <georg@python.org> parents: 43585 diff changeset	2151 pair: file; descriptor
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2152 module: fcntl
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2153
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2154 Return the integer "file descriptor" that is used by the underlying
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2155 implementation to request I/O operations from the operating system. This can be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2156 useful for other, lower level interfaces that use file descriptors, such as the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2157 :mod:`fcntl` module or :func:`os.read` and friends.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2158
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2159 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2160
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2161 File-like objects which do not have a real file descriptor should not provide
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2162 this method!
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2163
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2164
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2165 .. method:: file.isatty()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2166
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2167 Return ``True`` if the file is connected to a tty(-like) device, else ``False``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2168
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2169 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2170
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2171 If a file-like object is not associated with a real file, this method should
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2172 not be implemented.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2173
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2174
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2175 .. method:: file.next()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2176
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2177 A file object is its own iterator, for example ``iter(f)`` returns f (unless
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2178 f is closed). When a file is used as an iterator, typically in a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2179 :keyword:`for` loop (for example, ``for line in f: print line``), the
56817 6b05d48cca28 Merged revisions 74207 via svnmerge from Georg Brandl <georg@python.org> parents: 56816 diff changeset	2180 :meth:`.next` method is called repeatedly. This method returns the next input
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2181 line, or raises :exc:`StopIteration` when EOF is hit when the file is open for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2182 reading (behavior is undefined when the file is open for writing). In order to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2183 make a :keyword:`for` loop the most efficient way of looping over the lines of a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2184 file (a very common operation), the :meth:`next` method uses a hidden read-ahead
56817 6b05d48cca28 Merged revisions 74207 via svnmerge from Georg Brandl <georg@python.org> parents: 56816 diff changeset	2185 buffer. As a consequence of using a read-ahead buffer, combining :meth:`.next`
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2186 with other file methods (like :meth:`readline`) does not work right. However,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2187 using :meth:`seek` to reposition the file to an absolute position will flush the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2188 read-ahead buffer.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2189
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2190 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2191
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2192
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2193 .. method:: file.read([size])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2194
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2195 Read at most size bytes from the file (less if the read hits EOF before
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2196 obtaining size bytes). If the size argument is negative or omitted, read
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2197 all data until EOF is reached. The bytes are returned as a string object. An
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2198 empty string is returned when EOF is encountered immediately. (For certain
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2199 files, like ttys, it makes sense to continue reading after an EOF is hit.) Note
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2200 that this method may call the underlying C function :cfunc:`fread` more than
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2201 once in an effort to acquire as close to size bytes as possible. Also note
47881 7d1e61492c7d Tweak wording Andrew M. Kuchling <amk@amk.ca> parents: 47865 diff changeset	2202 that when in non-blocking mode, less data than was requested may be
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2203 returned, even if no size parameter was given.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2204
47865 cda556d23924 #1523853: add note about fread(). Georg Brandl <georg@python.org> parents: 47787 diff changeset	2205 .. note::
48081 767cc89e3fde This sentence continues to bug me; rewrite it for the second time Andrew M. Kuchling <amk@amk.ca> parents: 48003 diff changeset	2206 This function is simply a wrapper for the underlying
767cc89e3fde This sentence continues to bug me; rewrite it for the second time Andrew M. Kuchling <amk@amk.ca> parents: 48003 diff changeset	2207 :cfunc:`fread` C function, and will behave the same in corner cases,
767cc89e3fde This sentence continues to bug me; rewrite it for the second time Andrew M. Kuchling <amk@amk.ca> parents: 48003 diff changeset	2208 such as whether the EOF value is cached.
47865 cda556d23924 #1523853: add note about fread(). Georg Brandl <georg@python.org> parents: 47787 diff changeset	2209
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2210
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2211 .. method:: file.readline([size])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2212
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2213 Read one entire line from the file. A trailing newline character is kept in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2214 string (but may be absent when a file ends with an incomplete line). [#]_ If
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2215 the size argument is present and non-negative, it is a maximum byte count
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2216 (including the trailing newline) and an incomplete line may be returned. An
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2217 empty string is returned only when EOF is encountered immediately.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2218
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2219 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2220
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2221 Unlike ``stdio``'s :cfunc:`fgets`, the returned string contains null characters
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2222 (``'\0'``) if they occurred in the input.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2223
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2224
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2225 .. method:: file.readlines([sizehint])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2226
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2227 Read until EOF using :meth:`readline` and return a list containing the lines
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2228 thus read. If the optional sizehint argument is present, instead of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2229 reading up to EOF, whole lines totalling approximately sizehint bytes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2230 (possibly after rounding up to an internal buffer size) are read. Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2231 implementing a file-like interface may choose to ignore sizehint if it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2232 cannot be implemented, or cannot be implemented efficiently.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2233
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2234
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2235 .. method:: file.xreadlines()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2236
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2237 This method returns the same thing as ``iter(f)``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2238
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2239 .. versionadded:: 2.1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2240
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2241 .. deprecated:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2242 Use ``for line in file`` instead.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2243
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2244
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2245 .. method:: file.seek(offset[, whence])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2246
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2247 Set the file's current position, like ``stdio``'s :cfunc:`fseek`. The whence
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2248 argument is optional and defaults to ``os.SEEK_SET`` or ``0`` (absolute file
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2249 positioning); other values are ``os.SEEK_CUR`` or ``1`` (seek relative to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2250 current position) and ``os.SEEK_END`` or ``2`` (seek relative to the file's
44497 01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. Georg Brandl <georg@python.org> parents: 44488 diff changeset	2251 end). There is no return value.
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 50240 diff changeset	2252
44497 01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. Georg Brandl <georg@python.org> parents: 44488 diff changeset	2253 For example, ``f.seek(2, os.SEEK_CUR)`` advances the position by two and
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. Georg Brandl <georg@python.org> parents: 44488 diff changeset	2254 ``f.seek(-3, os.SEEK_END)`` sets the position to the third to last.
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. Georg Brandl <georg@python.org> parents: 44488 diff changeset	2255
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. Georg Brandl <georg@python.org> parents: 44488 diff changeset	2256 Note that if the file is opened for appending
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2257 (mode ``'a'`` or ``'a+'``), any :meth:`seek` operations will be undone at the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2258 next write. If the file is only opened for writing in append mode (mode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2259 ``'a'``), this method is essentially a no-op, but it remains useful for files
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2260 opened in append mode with reading enabled (mode ``'a+'``). If the file is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2261 opened in text mode (without ``'b'``), only offsets returned by :meth:`tell` are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2262 legal. Use of other offsets causes undefined behavior.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2263
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2264 Note that not all file objects are seekable.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2265
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2266 .. versionchanged:: 2.6
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	2267 Passing float values as offset has been deprecated.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2268
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2269
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2270 .. method:: file.tell()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2271
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2272 Return the file's current position, like ``stdio``'s :cfunc:`ftell`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2273
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2274 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2275
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2276 On Windows, :meth:`tell` can return illegal values (after an :cfunc:`fgets`)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2277 when reading files with Unix-style line-endings. Use binary mode (``'rb'``) to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2278 circumvent this problem.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2279
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2280
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2281 .. method:: file.truncate([size])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2282
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2283 Truncate the file's size. If the optional size argument is present, the file
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2284 is truncated to (at most) that size. The size defaults to the current position.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2285 The current file position is not changed. Note that if a specified size exceeds
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2286 the file's current size, the result is platform-dependent: possibilities
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2287 include that the file may remain unchanged, increase to the specified size as if
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2288 zero-filled, or increase to the specified size with undefined new content.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2289 Availability: Windows, many Unix variants.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2290
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2291
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2292 .. method:: file.write(str)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2293
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2294 Write a string to the file. There is no return value. Due to buffering, the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2295 string may not actually show up in the file until the :meth:`flush` or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2296 :meth:`close` method is called.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2297
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2298
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2299 .. method:: file.writelines(sequence)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2300
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2301 Write a sequence of strings to the file. The sequence can be any iterable
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2302 object producing strings, typically a list of strings. There is no return value.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2303 (The name is intended to match :meth:`readlines`; :meth:`writelines` does not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2304 add line separators.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2305
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2306 Files support the iterator protocol. Each iteration returns the same result as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2307 ``file.readline()``, and iteration ends when the :meth:`readline` method returns
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2308 an empty string.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2309
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2310 File objects also offer a number of other interesting attributes. These are not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2311 required for file-like objects, but should be implemented if they make sense for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2312 the particular object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2313
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2314
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2315 .. attribute:: file.closed
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2316
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2317 bool indicating the current state of the file object. This is a read-only
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2318 attribute; the :meth:`close` method changes the value. It may not be available
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2319 on all file-like objects.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2320
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2321
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2322 .. attribute:: file.encoding
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2323
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2324 The encoding that this file uses. When Unicode strings are written to a file,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2325 they will be converted to byte strings using this encoding. In addition, when
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2326 the file is connected to a terminal, the attribute gives the encoding that the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2327 terminal is likely to use (that information might be incorrect if the user has
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2328 misconfigured the terminal). The attribute is read-only and may not be present
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2329 on all file-like objects. It may also be ``None``, in which case the file uses
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2330 the system default encoding for converting Unicode strings.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2331
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2332 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2333
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2334
47413 1062b7dec95b New environment variable PYTHONIOENCODING. Martin v. Löwis <martin@v.loewis.de> parents: 46949 diff changeset	2335 .. attribute:: file.errors
1062b7dec95b New environment variable PYTHONIOENCODING. Martin v. Löwis <martin@v.loewis.de> parents: 46949 diff changeset	2336
47787 b32101c19bf8 Grammar fixes Andrew M. Kuchling <amk@amk.ca> parents: 47588 diff changeset	2337 The Unicode error handler used along with the encoding.
47413 1062b7dec95b New environment variable PYTHONIOENCODING. Martin v. Löwis <martin@v.loewis.de> parents: 46949 diff changeset	2338
1062b7dec95b New environment variable PYTHONIOENCODING. Martin v. Löwis <martin@v.loewis.de> parents: 46949 diff changeset	2339 .. versionadded:: 2.6
1062b7dec95b New environment variable PYTHONIOENCODING. Martin v. Löwis <martin@v.loewis.de> parents: 46949 diff changeset	2340
1062b7dec95b New environment variable PYTHONIOENCODING. Martin v. Löwis <martin@v.loewis.de> parents: 46949 diff changeset	2341
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2342 .. attribute:: file.mode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2343
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2344 The I/O mode for the file. If the file was created using the :func:`open`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2345 built-in function, this will be the value of the mode parameter. This is a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2346 read-only attribute and may not be present on all file-like objects.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2347
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2348
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2349 .. attribute:: file.name
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2350
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2351 If the file object was created using :func:`open`, the name of the file.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2352 Otherwise, some string that indicates the source of the file object, of the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2353 form ``<...>``. This is a read-only attribute and may not be present on all
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2354 file-like objects.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2355
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2356
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2357 .. attribute:: file.newlines
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2358
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2359 If Python was built with the :option:`--with-universal-newlines` option to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2360 :program:`configure` (the default) this read-only attribute exists, and for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2361 files opened in universal newline read mode it keeps track of the types of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2362 newlines encountered while reading the file. The values it can take are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2363 ``'\r'``, ``'\n'``, ``'\r\n'``, ``None`` (unknown, no newlines read yet) or a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2364 tuple containing all the newline types seen, to indicate that multiple newline
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2365 conventions were encountered. For files not opened in universal newline read
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2366 mode the value of this attribute will be ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2367
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2368
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2369 .. attribute:: file.softspace
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2370
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2371 Boolean that indicates whether a space character needs to be printed before
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2372 another value when using the :keyword:`print` statement. Classes that are trying
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2373 to simulate a file object should also have a writable :attr:`softspace`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2374 attribute, which should be initialized to zero. This will be automatic for most
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2375 classes implemented in Python (care may be needed for objects that override
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2376 attribute access); types implemented in C will have to provide a writable
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2377 :attr:`softspace` attribute.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2378
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2379 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2380
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2381 This attribute is not used to control the :keyword:`print` statement, but to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2382 allow the implementation of :keyword:`print` to keep track of its internal
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2383 state.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2384
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2385
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2386 .. _typecontextmanager:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2387
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2388 Context Manager Types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2389 =====================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2390
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2391 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2392
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2393 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2394 single: context manager
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2395 single: context management protocol
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2396 single: protocol; context management
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2397
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2398 Python's :keyword:`with` statement supports the concept of a runtime context
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2399 defined by a context manager. This is implemented using two separate methods
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2400 that allow user-defined classes to define a runtime context that is entered
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2401 before the statement body is executed and exited when the statement ends.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2402
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2403 The :dfn:`context management protocol` consists of a pair of methods that need
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2404 to be provided for a context manager object to define a runtime context:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2405
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2406
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2407 .. method:: contextmanager.__enter__()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2408
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2409 Enter the runtime context and return either this object or another object
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2410 related to the runtime context. The value returned by this method is bound to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2411 the identifier in the :keyword:`as` clause of :keyword:`with` statements using
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2412 this context manager.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2413
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2414 An example of a context manager that returns itself is a file object. File
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2415 objects return themselves from __enter__() to allow :func:`open` to be used as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2416 the context expression in a :keyword:`with` statement.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2417
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2418 An example of a context manager that returns a related object is the one
44524 79a34248a262 #1680: fix context manager example function name. Georg Brandl <georg@python.org> parents: 44497 diff changeset	2419 returned by :func:`decimal.localcontext`. These managers set the active
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2420 decimal context to a copy of the original decimal context and then return the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2421 copy. This allows changes to be made to the current decimal context in the body
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2422 of the :keyword:`with` statement without affecting code outside the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2423 :keyword:`with` statement.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2424
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2425
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2426 .. method:: contextmanager.__exit__(exc_type, exc_val, exc_tb)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2427
43585 f1f701c224c1 Issue 1289, just a typo. Facundo Batista <facundobatista@gmail.com> parents: 43492 diff changeset	2428 Exit the runtime context and return a Boolean flag indicating if any exception
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2429 that occurred should be suppressed. If an exception occurred while executing the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2430 body of the :keyword:`with` statement, the arguments contain the exception type,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2431 value and traceback information. Otherwise, all three arguments are ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2432
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2433 Returning a true value from this method will cause the :keyword:`with` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2434 to suppress the exception and continue execution with the statement immediately
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2435 following the :keyword:`with` statement. Otherwise the exception continues
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2436 propagating after this method has finished executing. Exceptions that occur
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2437 during execution of this method will replace any exception that occurred in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2438 body of the :keyword:`with` statement.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2439
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2440 The exception passed in should never be reraised explicitly - instead, this
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2441 method should return a false value to indicate that the method completed
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2442 successfully and does not want to suppress the raised exception. This allows
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2443 context management code (such as ``contextlib.nested``) to easily detect whether
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2444 or not an :meth:`__exit__` method has actually failed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2445
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2446 Python defines several context managers to support easy thread synchronisation,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2447 prompt closure of files or other objects, and simpler manipulation of the active
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2448 decimal arithmetic context. The specific types are not treated specially beyond
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2449 their implementation of the context management protocol. See the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2450 :mod:`contextlib` module for some examples.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2451
56820 85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	2452 Python's :term:`generator`\s and the ``contextlib.contextmanager`` :term:`decorator`
44103 1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 44050 diff changeset	2453 provide a convenient way to implement these protocols. If a generator function is
56820 85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from Georg Brandl <georg@python.org> parents: 56818 diff changeset	2454 decorated with the ``contextlib.contextmanager`` decorator, it will return a
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2455 context manager implementing the necessary :meth:`__enter__` and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2456 :meth:`__exit__` methods, rather than the iterator produced by an undecorated
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2457 generator function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2458
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2459 Note that there is no specific slot for any of these methods in the type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2460 structure for Python objects in the Python/C API. Extension types wanting to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2461 define these methods must provide them as a normal Python accessible method.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2462 Compared to the overhead of setting up the runtime context, the overhead of a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2463 single class dictionary lookup is negligible.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2464
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2465
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2466 .. _typesother:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2467
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2468 Other Built-in Types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2469 ====================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2470
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2471 The interpreter supports several other kinds of objects. Most of these support
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2472 only one or two operations.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2473
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2474
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2475 .. _typesmodules:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2476
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2477 Modules
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2478 -------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2479
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2480 The only special operation on a module is attribute access: ``m.name``, where
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2481 m is a module and name accesses a name defined in m's symbol table.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2482 Module attributes can be assigned to. (Note that the :keyword:`import`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2483 statement is not, strictly speaking, an operation on a module object; ``import
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2484 foo`` does not require a module object named foo to exist, rather it requires
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2485 an (external) definition for a module named foo somewhere.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2486
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2487 A special member of every module is :attr:`__dict__`. This is the dictionary
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2488 containing the module's symbol table. Modifying this dictionary will actually
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2489 change the module's symbol table, but direct assignment to the :attr:`__dict__`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2490 attribute is not possible (you can write ``m.__dict__['a'] = 1``, which defines
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2491 ``m.a`` to be ``1``, but you can't write ``m.__dict__ = {}``). Modifying
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2492 :attr:`__dict__` directly is not recommended.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2493
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2494 Modules built into the interpreter are written like this: ``<module 'sys'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2495 (built-in)>``. If loaded from a file, they are written as ``<module 'os' from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2496 '/usr/local/lib/pythonX.Y/os.pyc'>``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2497
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2498
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2499 .. _typesobjects:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2500
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2501 Classes and Class Instances
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2502 ---------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2503
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2504 See :ref:`objects` and :ref:`class` for these.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2505
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2506
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2507 .. _typesfunctions:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2508
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2509 Functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2510 ---------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2511
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2512 Function objects are created by function definitions. The only operation on a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2513 function object is to call it: ``func(argument-list)``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2514
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2515 There are really two flavors of function objects: built-in functions and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2516 user-defined functions. Both support the same operation (to call the function),
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2517 but the implementation is different, hence the different object types.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2518
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2519 See :ref:`function` for more information.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2520
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2521
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2522 .. _typesmethods:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2523
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2524 Methods
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2525 -------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2526
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2527 .. index:: object: method
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2528
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2529 Methods are functions that are called using the attribute notation. There are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2530 two flavors: built-in methods (such as :meth:`append` on lists) and class
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2531 instance methods. Built-in methods are described with the types that support
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2532 them.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2533
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2534 The implementation adds two special read-only attributes to class instance
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2535 methods: ``m.im_self`` is the object on which the method operates, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2536 ``m.im_func`` is the function implementing the method. Calling ``m(arg-1,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2537 arg-2, ..., arg-n)`` is completely equivalent to calling ``m.im_func(m.im_self,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2538 arg-1, arg-2, ..., arg-n)``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2539
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2540 Class instance methods are either bound or unbound, referring to whether the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2541 method was accessed through an instance or a class, respectively. When a method
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2542 is unbound, its ``im_self`` attribute will be ``None`` and if called, an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2543 explicit ``self`` object must be passed as the first argument. In this case,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2544 ``self`` must be an instance of the unbound method's class (or a subclass of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2545 that class), otherwise a :exc:`TypeError` is raised.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2546
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2547 Like function objects, methods objects support getting arbitrary attributes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2548 However, since method attributes are actually stored on the underlying function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2549 object (``meth.im_func``), setting method attributes on either bound or unbound
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2550 methods is disallowed. Attempting to set a method attribute results in a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2551 :exc:`TypeError` being raised. In order to set a method attribute, you need to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2552 explicitly set it on the underlying function object::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2553
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2554 class C:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2555 def method(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2556 pass
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2557
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2558 c = C()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2559 c.method.im_func.whoami = 'my name is c'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2560
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2561 See :ref:`types` for more information.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2562
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2563
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2564 .. _bltin-code-objects:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2565
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2566 Code Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2567 ------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2568
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2569 .. index:: object: code
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2570
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2571 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2572 builtin: compile
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2573 single: func_code (function object attribute)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2574
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2575 Code objects are used by the implementation to represent "pseudo-compiled"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2576 executable Python code such as a function body. They differ from function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2577 objects because they don't contain a reference to their global execution
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2578 environment. Code objects are returned by the built-in :func:`compile` function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2579 and can be extracted from function objects through their :attr:`func_code`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2580 attribute. See also the :mod:`code` module.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2581
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2582 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2583 statement: exec
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2584 builtin: eval
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2585
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2586 A code object can be executed or evaluated by passing it (instead of a source
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2587 string) to the :keyword:`exec` statement or the built-in :func:`eval` function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2588
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2589 See :ref:`types` for more information.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2590
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2591
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2592 .. _bltin-type-objects:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2593
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2594 Type Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2595 ------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2596
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2597 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2598 builtin: type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2599 module: types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2600
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2601 Type objects represent the various object types. An object's type is accessed
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2602 by the built-in function :func:`type`. There are no special operations on
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2603 types. The standard module :mod:`types` defines names for all standard built-in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2604 types.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2605
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2606 Types are written like this: ``<type 'int'>``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2607
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2608
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2609 .. _bltin-null-object:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2610
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2611 The Null Object
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2612 ---------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2613
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2614 This object is returned by functions that don't explicitly return a value. It
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2615 supports no special operations. There is exactly one null object, named
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2616 ``None`` (a built-in name).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2617
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2618 It is written as ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2619
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2620
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2621 .. _bltin-ellipsis-object:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2622
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2623 The Ellipsis Object
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2624 -------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2625
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2626 This object is used by extended slice notation (see :ref:`slicings`). It
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2627 supports no special operations. There is exactly one ellipsis object, named
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2628 :const:`Ellipsis` (a built-in name).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2629
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2630 It is written as ``Ellipsis``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2631
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2632
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2633 Boolean Values
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2634 --------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2635
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2636 Boolean values are the two constant objects ``False`` and ``True``. They are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2637 used to represent truth values (although other values can also be considered
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2638 false or true). In numeric contexts (for example when used as the argument to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2639 an arithmetic operator), they behave like the integers 0 and 1, respectively.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2640 The built-in function :func:`bool` can be used to cast any value to a Boolean,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2641 if the value can be interpreted as a truth value (see section Truth Value
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2642 Testing above).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2643
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2644 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2645 single: False
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2646 single: True
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2647 pair: Boolean; values
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2648
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2649 They are written as ``False`` and ``True``, respectively.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2650
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2651
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2652 .. _typesinternal:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2653
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2654 Internal Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2655 ----------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2656
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2657 See :ref:`types` for this information. It describes stack frame objects,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2658 traceback objects, and slice objects.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2659
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2660
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2661 .. _specialattrs:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2662
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2663 Special Attributes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2664 ==================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2665
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2666 The implementation adds a few special read-only attributes to several object
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2667 types, where they are relevant. Some of these are not reported by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2668 :func:`dir` built-in function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2669
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2670
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2671 .. attribute:: object.__dict__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2672
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2673 A dictionary or other mapping object used to store an object's (writable)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2674 attributes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2675
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2676
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2677 .. attribute:: object.__methods__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2678
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2679 .. deprecated:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2680 Use the built-in function :func:`dir` to get a list of an object's attributes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2681 This attribute is no longer available.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2682
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2683
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2684 .. attribute:: object.__members__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2685
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2686 .. deprecated:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2687 Use the built-in function :func:`dir` to get a list of an object's attributes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2688 This attribute is no longer available.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2689
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2690
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2691 .. attribute:: instance.__class__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2692
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2693 The class to which a class instance belongs.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2694
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2695
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2696 .. attribute:: class.__bases__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2697
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2698 The tuple of base classes of a class object. If there are no base classes, this
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2699 will be an empty tuple.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2700
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2701
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2702 .. attribute:: class.__name__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2703
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2704 The name of the class or type.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2705
52898 fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from Georg Brandl <georg@python.org> parents: 52854 diff changeset	2706
52900 4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2707 The following attributes are only supported by :term:`new-style class`\ es.
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2708
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2709 .. attribute:: class.__mro__
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2710
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2711 This attribute is a tuple of classes that are considered when looking for
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2712 base classes during method resolution.
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2713
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2714
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2715 .. method:: class.mro()
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2716
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2717 This method can be overridden by a metaclass to customize the method
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2718 resolution order for its instances. It is called at class instantiation, and
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2719 its result is stored in :attr:`__mro__`.
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2720
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2721
52898 fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from Georg Brandl <georg@python.org> parents: 52854 diff changeset	2722 .. method:: class.__subclasses__
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from Georg Brandl <georg@python.org> parents: 52854 diff changeset	2723
52900 4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from Georg Brandl <georg@python.org> parents: 52898 diff changeset	2724 Each new-style class keeps a list of weak references to its immediate
52898 fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from Georg Brandl <georg@python.org> parents: 52854 diff changeset	2725 subclasses. This method returns a list of all those references still alive.
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from Georg Brandl <georg@python.org> parents: 52854 diff changeset	2726 Example::
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from Georg Brandl <georg@python.org> parents: 52854 diff changeset	2727
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from Georg Brandl <georg@python.org> parents: 52854 diff changeset	2728 >>> int.__subclasses__()
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from Georg Brandl <georg@python.org> parents: 52854 diff changeset	2729 [<type 'bool'>]
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from Georg Brandl <georg@python.org> parents: 52854 diff changeset	2730
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from Georg Brandl <georg@python.org> parents: 52854 diff changeset	2731
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2732 .. rubric:: Footnotes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2733
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2734 .. [#] Additional information on these special methods may be found in the Python
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2735 Reference Manual (:ref:`customization`).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2736
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2737 .. [#] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0]``, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2738 similarly for tuples.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2739
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2740 .. [#] They must have since the parser can't tell the type of the operands.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2741
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2742 .. [#] To format only a tuple you should therefore provide a singleton tuple whose only
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2743 element is the tuple to be formatted.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2744
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2745 .. [#] These numbers are fairly arbitrary. They are intended to avoid printing endless
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2746 strings of meaningless digits without hampering correct use and without having
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2747 to know the exact precision of floating point values on a particular machine.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2748
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2749 .. [#] The advantage of leaving the newline on is that returning an empty string is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2750 then an unambiguous EOF indication. It is also possible (in cases where it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2751 might matter, for example, if you want to make an exact copy of a file while
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2752 scanning its lines) to tell whether the last line of a file ended in a newline
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2753 or not (yes this happens!).

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/stdtypes.rst @ 58925:eecf1bef052d 2.6