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

annotate Doc/library/stdtypes.rst @ 54294:dba767bc3155 legacy-trunk

remove mention of old ctypes version

author	Benjamin Peterson <benjamin@python.org>
date	Sat, 23 May 2009 20:59:09 +0000
parents	b52b92f31fa8
children	9d00fd0087ff

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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 .. index:: pair: chaining; comparisons
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 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	135 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	136 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	137 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	138 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	139
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 This table summarizes the comparison operations:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 \| Operation \| Meaning \| Notes \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 +============+=========================+=======+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 \| ``<`` \| strictly less than \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	147 \| ``<=`` \| less than or equal \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 \| ``>`` \| strictly greater than \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 \| ``>=`` \| greater than or equal \| \|
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 \| ``==`` \| equal \| \|
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 \| ``!=`` \| not equal \| \(1) \|
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 \| ``is`` \| object identity \| \|
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 \| ``is not`` \| negated object identity \| \|
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163 pair: operator; comparison
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 operator: ==
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	165 operator: <
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	166 operator: <=
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	167 operator: >
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	168 operator: >=
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	169 operator: !=
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 operator: is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 operator: is not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 ``!=`` 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	177 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	178 ``!=``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 pair: object; numeric
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182 pair: objects; comparing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 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	185 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	186 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	187 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	188 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	189 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	190 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	191 a complex number.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193 .. index:: single: __cmp__() (instance method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195 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	196 :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	197 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	198
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 Implementation note: Objects of different types except numbers are ordered
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 by their type names; objects of the same types that don't support proper
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 comparison are ordered by their address.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 operator: in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 operator: not in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 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	208 supported only by sequence types (below).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209
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 .. _typesnumeric:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 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	214 ===============================================================================
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 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217 object: numeric
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 object: Boolean
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219 object: integer
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 object: long integer
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 object: floating point
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222 object: complex number
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 pair: C; language
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 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	226 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	227 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	228 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	229 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	230 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	231 ``-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	232 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	233 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	234
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 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	236 :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	237 ``z.real`` and ``z.imag``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 pair: numeric; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 pair: integer; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 triple: long; integer; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243 pair: floating point; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 pair: complex number; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 pair: hexadecimal; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 pair: octal; literals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248 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	249 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	250 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	251 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	252 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	253 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	254 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	255 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	256 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	257 part.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 single: arithmetic
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 builtin: int
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 builtin: long
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 builtin: float
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 builtin: complex
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266 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	267 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	268 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	269 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	270 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	271 :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	272 of a specific type.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273
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	274 All builtin numeric types support the following operations. See
4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just Jeffrey Yasskin <jyasskin@gmail.com> parents: 44383 diff changeset	275 :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	276
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 \| Operation \| Result \| Notes \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 +====================+=================================+========+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280 \| ``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	281 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282 \| ``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	283 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 \| ``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	285 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 \| ``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	287 +--------------------+---------------------------------+--------+
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	288 \| ``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	289 \| \| y \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 \| ``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	292 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 \| ``-x`` \| x negated \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295 \| ``+x`` \| x unchanged \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296 +--------------------+---------------------------------+--------+
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	297 \| ``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	298 \| \| x \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300 \| ``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	301 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302 \| ``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	303 +--------------------+---------------------------------+--------+
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	304 \| ``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	305 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306 \| ``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	307 \| \| re, imaginary part im. \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308 \| \| im defaults to zero. \| \|
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 \| ``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	311 \| \| c. (Identity on real numbers) \| \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 \| ``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	314 +--------------------+---------------------------------+--------+
44526 507e76d7fcdd #1501: document that 0*0 == 1. Georg Brandl <georg@python.org>* parents: 44525 diff changeset	315 \| ``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	316 +--------------------+---------------------------------+--------+
44526 507e76d7fcdd #1501: document that 0*0 == 1. Georg Brandl <georg@python.org>* parents: 44525 diff changeset	317 \| ``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	318 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 triple: operations on; numeric; types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 single: conjugate() (complex number method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 pair: integer; division
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 triple: long; integer; division
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 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	332 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	333 (-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	334 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	335
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 module: math
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339 single: floor() (in module math)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340 single: ceil() (in module math)
50579 54a5affb6af0 Fix two issues found by the suspicious builder. Georg Brandl <georg@python.org> parents: 50528 diff changeset	341 single: trunc() (in module math)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 pair: numeric; conversions
50528 b5639d245ad5 Manually merge r67868 from 2.6 branch. Georg Brandl <georg@python.org> parents: 50508 diff changeset	343
b5639d245ad5 Manually merge r67868 from 2.6 branch. Georg Brandl <georg@python.org> parents: 50508 diff changeset	344 Conversion from floats using :func:`int` or :func:`long` truncates toward
b5639d245ad5 Manually merge r67868 from 2.6 branch. Georg Brandl <georg@python.org> parents: 50508 diff changeset	345 zero like the related function, :func:`math.trunc`. Use the function
b5639d245ad5 Manually merge r67868 from 2.6 branch. Georg Brandl <georg@python.org> parents: 50508 diff changeset	346 :func:`math.floor` to round downward and :func:`math.ceil` to round
b5639d245ad5 Manually merge r67868 from 2.6 branch. Georg Brandl <georg@python.org> parents: 50508 diff changeset	347 upward.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350 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	351
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352 (4)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353 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	354
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 .. deprecated:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 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	357
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 (5)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359 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	360 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	361
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	362 (6)
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50229 diff changeset	363 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	364 or "-" for Not a Number (NaN) and positive or negative infinity.
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50229 diff changeset	365
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	366 .. 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	367
44526 507e76d7fcdd #1501: document that 0*0 == 1. Georg Brandl <georg@python.org>* parents: 44525 diff changeset	368 (7)
507e76d7fcdd #1501: document that 0*0 == 1. Georg Brandl <georg@python.org>* parents: 44525 diff changeset	369 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	370 programming languages.
507e76d7fcdd #1501: document that 0*0 == 1. Georg Brandl <georg@python.org>* parents: 44525 diff changeset	371
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	372 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	373 :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	374
44488 94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	375 +--------------------+------------------------------------+--------+
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	376 \| 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	377 +====================+====================================+========+
50864 bbda31dd9797 #4914: trunc is in math. Georg Brandl <georg@python.org> parents: 50863 diff changeset	378 \| ``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	379 +--------------------+------------------------------------+--------+
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	380 \| ``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	381 \| \| 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	382 \| \| 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	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 \| ``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	385 +--------------------+------------------------------------+--------+
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This Jeffrey Yasskin <jyasskin@gmail.com> parents: 44432 diff changeset	386 \| ``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	387 +--------------------+------------------------------------+--------+
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	388
3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	389 .. 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	390
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	391
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	392 .. _bitstring-ops:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 Bit-string Operations on Integer Types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395 --------------------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 .. _bit-string-operations:
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 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	400 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	401 (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	402 overflow occurs during the operation).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403
44497 01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. Georg Brandl <georg@python.org> parents: 44488 diff changeset	404 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	405 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	406 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	407
46876 f4e61dcdb6f8 #2147: PEP 237 changes to overflow behavior. Georg Brandl <georg@python.org> parents: 46870 diff changeset	408 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	409
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 \| Operation \| Result \| Notes \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 +============+================================+==========+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 \| ``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	414 \| \| y \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 \| ``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	417 \| \| x and y \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419 \| ``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	420 \| \| y \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421 +------------+--------------------------------+----------+
44555 7ea231578b02 Consistency nit. Georg Brandl <georg@python.org> parents: 44553 diff changeset	422 \| ``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	423 +------------+--------------------------------+----------+
44555 7ea231578b02 Consistency nit. Georg Brandl <georg@python.org> parents: 44553 diff changeset	424 \| ``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	425 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 \| ``~x`` \| the bits of x inverted \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427 +------------+--------------------------------+----------+
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 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 triple: operations on; integer; types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 pair: bit-string; operations
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 pair: shifting; operations
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433 pair: masking; operations
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 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438 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	439
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440 (2)
46876 f4e61dcdb6f8 #2147: PEP 237 changes to overflow behavior. Georg Brandl <georg@python.org> parents: 46870 diff changeset	441 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	442 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	443
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444 (3)
46876 f4e61dcdb6f8 #2147: PEP 237 changes to overflow behavior. Georg Brandl <georg@python.org> parents: 46870 diff changeset	445 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	446
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447
50205 f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	448 Additional Methods on Integer Types
f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	449 -----------------------------------
f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	450
f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	451 .. method:: int.bit_length()
f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	452 .. method:: long.bit_length()
f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	453
50222 9a1890982489 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50205 diff changeset	454 Return the number of bits necessary to represent an integer in binary,
9a1890982489 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50205 diff changeset	455 excluding the sign and leading zeros::
9a1890982489 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50205 diff changeset	456
9a1890982489 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50205 diff changeset	457 >>> n = -37
50205 f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	458 >>> bin(n)
50222 9a1890982489 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50205 diff changeset	459 '-0b100101'
50205 f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	460 >>> n.bit_length()
f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	461 6
50222 9a1890982489 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50205 diff changeset	462
9a1890982489 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50205 diff changeset	463 More precisely, if ``x`` is nonzero, then ``x.bit_length()`` is the
9a1890982489 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50205 diff changeset	464 unique positive integer ``k`` such that ``2(k-1) <= abs(x) < 2k``.
9a1890982489 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50205 diff changeset	465 Equivalently, when ``abs(x)`` is small enough to have a correctly
9a1890982489 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50205 diff changeset	466 rounded logarithm, then ``k = 1 + int(log(abs(x), 2))``.
9a1890982489 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50205 diff changeset	467 If ``x`` is zero, then ``x.bit_length()`` returns ``0``.
50205 f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	468
f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	469 Equivalent to::
f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	470
f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	471 def bit_length(self):
50229 496dff47bc7e Fix typo in Python equivalent for bit_length. Mark Dickinson <dickinsm@gmail.com> parents: 50222 diff changeset	472 s = bin(self) # binary representation: bin(-37) --> '-0b100101'
50222 9a1890982489 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50205 diff changeset	473 s = s.lstrip('-0b') # remove leading zeros and minus sign
9a1890982489 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50205 diff changeset	474 return len(s) # len('100101') --> 6
50205 f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	475
f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	476 .. versionadded:: 2.7
f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	477
f0db06f49a4e Issue #3439: add bit_length method to int and long. Mark Dickinson <dickinsm@gmail.com> parents: 49677 diff changeset	478
47966 97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	479 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	480 ---------------------------
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	481
49171 52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	482 The float type has some additional methods.
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	483
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	484 .. method:: float.as_integer_ratio()
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	485
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	486 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	487 original float and with a positive denominator. Raises
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	488 :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	489 NaNs.
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50229 diff changeset	490
49171 52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	491 .. versionadded:: 2.6
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	492
52ef95bdd801 #3288: Document as_integer_ratio Andrew M. Kuchling <amk@amk.ca> parents: 48097 diff changeset	493 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	494 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	495 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	496 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	497 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	498 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	499 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	500
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	501
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	502 .. 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	503
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	504 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	505 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	506 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	507 exponent.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	508
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	509 .. 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	510
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	511
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	512 .. 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	513
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	514 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	515 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	516 whitespace.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	517
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	518 .. 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	519
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	520
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	521 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	522 :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	523
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	524 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	525
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	526 [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	527
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	528 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	529 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	530 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	531 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	532 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	533 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	534 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	535 :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	536 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	537 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	538 :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	539
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	540
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	541 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	542 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	543 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	544 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	545 ``3740.0``::
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	546
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	547 >>> 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	548 3740.0
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	549
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	550
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	551 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	552 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	553
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	554 >>> 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	555 '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	556
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex Mark Dickinson <dickinsm@gmail.com> parents: 47937 diff changeset	557
47971 01fbe3fc883e Move label to correct heading. Georg Brandl <georg@python.org> parents: 47966 diff changeset	558 .. _typeiter:
01fbe3fc883e Move label to correct heading. Georg Brandl <georg@python.org> parents: 47966 diff changeset	559
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	560 Iterator Types
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	566 single: iterator protocol
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567 single: protocol; iterator
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 single: sequence; iteration
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569 single: container; iteration over
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 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	572 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	573 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	574 the iteration methods.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576 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	577 support:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578
44578 19e1fa78d330 Fix two further doc build warnings. Georg Brandl <georg@python.org> parents: 44563 diff changeset	579 .. XXX duplicated in reference/datamodel!
19e1fa78d330 Fix two further doc build warnings. Georg Brandl <georg@python.org> parents: 44563 diff changeset	580
19e1fa78d330 Fix two further doc build warnings. Georg Brandl <georg@python.org> parents: 44563 diff changeset	581 .. method:: container.__iter__()
42603 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 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	584 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	585 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	586 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	587 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	588 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	589 :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	590 API.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592 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	593 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	594
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	596 .. method:: iterator.__iter__()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	597
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598 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	599 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	600 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	601 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	602
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	604 .. method:: iterator.next()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	605
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	606 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	607 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	608 :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	609 Python/C API.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	610
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	611 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	612 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	613 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	614 protocol.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	615
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	616 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	617 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	618 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	619 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	620 according to this rule.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	621
43629 4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 43627 diff changeset	622 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	623 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	624 generator, it will automatically return an iterator object (technically, a
4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 43627 diff changeset	625 generator object) supplying the :meth:`__iter__` and :meth:`next` methods.
42603 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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	628 .. _typesseq:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	629
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630 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	631 ==================================================================================================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	633 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	634 and xrange objects.
50863 d2dc6d043c21 #4974: fix redundant mention of lists and tuples. Georg Brandl <georg@python.org> parents: 50861 diff changeset	635
d2dc6d043c21 #4974: fix redundant mention of lists and tuples. Georg Brandl <georg@python.org> parents: 50861 diff changeset	636 For other containers see the built in :class:`dict` and :class:`set` classes,
d2dc6d043c21 #4974: fix redundant mention of lists and tuples. Georg Brandl <georg@python.org> parents: 50861 diff changeset	637 and the :mod:`collections` module.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	639
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	640 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	641 object: sequence
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	642 object: string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643 object: Unicode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	644 object: tuple
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	645 object: list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	646 object: buffer
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	647 object: xrange
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	648
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649 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	650 ``"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	651 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	652 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	653 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	654 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	655 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	656 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	657 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	658 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	659 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	660
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	661 Buffer objects are not directly supported by Python syntax, but can be created
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	662 by calling the builtin function :func:`buffer`. They don't support
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	663 concatenation or repetition.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	664
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	665 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	666 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	667 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	668 :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	669
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	670 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	671 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	672 ``*`` 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	673 [#]_ 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	674
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	675 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	676 (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	677 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	678
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	679 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	680 \| Operation \| Result \| Notes \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	681 +==================+================================+==========+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	682 \| ``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	683 \| \| equal to x, else ``False`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	684 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	685 \| ``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	686 \| \| equal to x, else ``True`` \| \|
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 \| ``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	689 \| \| t \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	690 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	691 \| ``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	692 \| \| concatenated \| \|
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 \| ``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	695 +------------------+--------------------------------+----------+
44555 7ea231578b02 Consistency nit. Georg Brandl <georg@python.org> parents: 44553 diff changeset	696 \| ``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	697 +------------------+--------------------------------+----------+
44555 7ea231578b02 Consistency nit. Georg Brandl <georg@python.org> parents: 44553 diff changeset	698 \| ``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	699 \| \| with step k \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701 \| ``len(s)`` \| length of s \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	702 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	703 \| ``min(s)`` \| smallest item of s \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	704 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	705 \| ``max(s)`` \| largest item of s \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	706 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	707
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	708 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	709 are compared lexicographically by comparing corresponding
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	710 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	711 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	712 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	713 reference.)
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 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	716 triple: operations on; sequence; types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	717 builtin: len
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	718 builtin: min
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	719 builtin: max
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	720 pair: concatenation; operation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	721 pair: repetition; operation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	722 pair: subscript; operation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	723 pair: slice; operation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724 pair: extended slice; operation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725 operator: in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726 operator: not in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	728 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 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	732 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	733 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	734 length.
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 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737 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	738 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	739 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	740 consider:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	741
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	742 >>> lists = [[]] * 3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	743 >>> lists
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744 [[], [], []]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 >>> lists[0].append(3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746 >>> lists
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747 [[3], [3], [3]]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 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	750 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	751 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	752 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	753
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754 >>> lists = [[] for i in range(3)]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755 >>> lists[0].append(3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756 >>> lists[1].append(5)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757 >>> lists[2].append(7)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758 >>> lists
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	759 [[3], [5], [7]]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762 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	763 ``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	764 ``0``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	766 (4)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767 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	768 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	769 ``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	770 ``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	771 empty.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773 (5)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774 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	775 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	776 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	777 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	778 ``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	779 "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	780 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	781
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782 (6)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783 If s and t are both strings, some Python implementations such as CPython can
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784 usually perform an in-place optimization for assignments of the form ``s=s+t``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	785 or ``s+=t``. When applicable, this optimization makes quadratic run-time much
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786 less likely. This optimization is both version and implementation dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787 For performance sensitive code, it is preferable to use the :meth:`str.join`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	788 method which assures consistent linear concatenation performance across versions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789 and implementations.
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 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	792 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	793
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	794
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795 .. _string-methods:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797 String Methods
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	798 --------------
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 .. index:: pair: string; methods
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 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	803 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	804
e1c09fa6fc0f #1176: document that string methods don't take keyword args. Georg Brandl <georg@python.org> parents: 43181 diff changeset	805 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	806 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	807 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	808 :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	809 string functions based on regular expressions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	810
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	811 .. method:: str.capitalize()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	812
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813 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	814
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815 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	816
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	817
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	818 .. method:: str.center(width[, fillchar])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	819
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	820 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	821 specified fillchar (default is a space).
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 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	824 Support for the fillchar argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	825
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	826
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	827 .. method:: str.count(sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	828
51816 0a598dbed679 #5352: str.count() counts non-overlapping instances. Georg Brandl <georg@python.org> parents: 51539 diff changeset	829 Return the number of non-overlapping occurrences of substring sub in the
0a598dbed679 #5352: str.count() counts non-overlapping instances. Georg Brandl <georg@python.org> parents: 51539 diff changeset	830 range [start, end]. Optional arguments start and end are
0a598dbed679 #5352: str.count() counts non-overlapping instances. Georg Brandl <georg@python.org> parents: 51539 diff changeset	831 interpreted as in slice notation.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832
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 .. method:: str.decode([encoding[, errors]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	835
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	836 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	837 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	838 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	839 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	840 ``'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	841 :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	842
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	843 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	844
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	845 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	846 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	847
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 .. method:: str.encode([encoding[,errors]])
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 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	852 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	853 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	854 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	855 ``'ignore'``, ``'replace'``, ``'xmlcharrefreplace'``, ``'backslashreplace'`` and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	856 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	857 :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	858 :ref:`standard-encodings`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	859
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	860 .. versionadded:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	861
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	862 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	863 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	864 handling schemes added.
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.endswith(suffix[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	868
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	869 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	870 ``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	871 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	872 at that position.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	873
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	874 .. versionchanged:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	875 Accept tuples as suffix.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	876
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 .. method:: str.expandtabs([tabsize])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	879
43492 045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	880 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	881 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	882 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	883 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	884 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	885
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	886
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	887 .. method:: str.find(sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	888
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	889 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	890 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	891 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	892 found.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	893
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	894
51866 3ecd484756b0 fix str.format()'s first arg #5371 Benjamin Peterson <benjamin@python.org> parents: 51816 diff changeset	895 .. method:: str.format(args, *kwargs)
46949 6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	896
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	897 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	898 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	899 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	900 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	901 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	902 argument.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	903
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	904 >>> "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	905 'The sum of 1 + 2 is 3'
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	906
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	907 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	908 that can be specified in format strings.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	909
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	910 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	911 should be preferred to the ``%`` formatting described in
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	912 :ref:`string-formatting` in new code.
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	913
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	914 .. versionadded:: 2.6
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	915
6a778c0a517e #2836: backport new string formatting docs. Georg Brandl <georg@python.org> parents: 46876 diff changeset	916
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	917 .. method:: str.index(sub[, start[, end]])
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 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	920
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	921
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	922 .. method:: str.isalnum()
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 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	925 least one character, false otherwise.
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 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	928
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	929
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	930 .. method:: str.isalpha()
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 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	933 one character, false otherwise.
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 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	936
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	937
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	938 .. method:: str.isdigit()
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 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	941 character, false otherwise.
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 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	944
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	945
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	946 .. method:: str.islower()
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 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	949 least one cased character, false otherwise.
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 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	952
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	953
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	954 .. method:: str.isspace()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	955
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	956 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	957 at least one character, false otherwise.
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 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	960
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 .. method:: str.istitle()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	963
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	964 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	965 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	966 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	967
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	968 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	969
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	970
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	971 .. method:: str.isupper()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	972
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	973 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	974 least one cased character, false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	975
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	976 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	977
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	978
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	979 .. method:: str.join(seq)
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 Return a string which is the concatenation of the strings in the sequence seq.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	982 The separator between elements is the string providing this method.
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.ljust(width[, fillchar])
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 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	988 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	989 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	990
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	991 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	992 Support for the fillchar argument.
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	995 .. method:: str.lower()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	996
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	997 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	998
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	999 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	1000
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1001
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1002 .. method:: str.lstrip([chars])
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 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	1005 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	1006 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	1007 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	1008
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1009 >>> ' spacious '.lstrip()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1010 'spacious '
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1011 >>> 'www.example.com'.lstrip('cmowz.')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1012 'example.com'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1013
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1014 .. versionchanged:: 2.2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1015 Support for the chars argument.
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.partition(sep)
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 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	1021 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	1022 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	1023 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	1024
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1025 .. versionadded:: 2.5
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1028 .. method:: str.replace(old, new[, count])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1029
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1030 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	1031 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	1032 occurrences are replaced.
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1035 .. method:: str.rfind(sub [,start [,end]])
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 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	1038 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	1039 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	1040
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1041
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1042 .. method:: str.rindex(sub[, start[, end]])
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 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	1045 found.
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.rjust(width[, fillchar])
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 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	1051 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	1052 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	1053
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1054 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1055 Support for the fillchar argument.
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.rpartition(sep)
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 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	1061 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	1062 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	1063 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	1064
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1065 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1066
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 .. method:: str.rsplit([sep [,maxsplit]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1069
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1070 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	1071 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	1072 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	1073 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	1074 :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	1075
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1076 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1077
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1078
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1079 .. method:: str.rstrip([chars])
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 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	1082 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	1083 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	1084 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	1085
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1086 >>> ' spacious '.rstrip()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1087 ' spacious'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1088 >>> 'mississippi'.rstrip('ipz')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1089 'mississ'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1090
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1091 .. versionchanged:: 2.2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1092 Support for the chars argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1093
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1094
43492 045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1095 .. 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	1096
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1097 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	1098 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	1099 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	1100 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	1101 splits are made).
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1102
43738 79f5ca9ee154 Fix markup glitch. Georg Brandl <georg@python.org> parents: 43629 diff changeset	1103 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	1104 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	1105 ``['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	1106 (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	1107 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	1108
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1109 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	1110 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	1111 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	1112 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	1113 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	1114 returns ``[]``.
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1115
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1116 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	1117 ``' 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	1118
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1119
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1120 .. method:: str.splitlines([keepends])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1121
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1122 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	1123 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	1124 true.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1125
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 .. method:: str.startswith(prefix[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1128
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1129 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	1130 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	1131 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	1132 string at that position.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1133
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1134 .. versionchanged:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1135 Accept tuples as prefix.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1136
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1137
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1138 .. method:: str.strip([chars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1139
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1140 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	1141 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	1142 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	1143 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	1144 values are stripped:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1145
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1146 >>> ' spacious '.strip()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1147 'spacious'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1148 >>> 'www.example.com'.strip('cmowz.')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1149 'example'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1150
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1151 .. versionchanged:: 2.2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1152 Support for the chars argument.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1153
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1154
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1155 .. method:: str.swapcase()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1156
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1157 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	1158 vice versa.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1159
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1160 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	1161
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1162
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1163 .. method:: str.title()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1164
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1165 Return a titlecased version of the string: words start with uppercase
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1166 characters, all remaining cased characters are lowercase.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1167
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1168 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	1169
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1170
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1171 .. method:: str.translate(table[, deletechars])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1172
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1173 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	1174 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	1175 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	1176 256.
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 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	1179 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	1180 ``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	1181
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1182 >>> '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	1183 'rd ths shrt txt'
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1184
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1185 .. versionadded:: 2.6
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1186 Support for a ``None`` table argument.
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 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	1189 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	1190 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	1191 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	1192 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	1193 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	1194 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	1195 example).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1196
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 .. method:: str.upper()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1199
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1200 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	1201
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1202 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	1203
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1204
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1205 .. method:: str.zfill(width)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1206
43492 045952ff08f7 #1123: fix the docs for the str.split(None, sep) case. Georg Brandl <georg@python.org> parents: 43415 diff changeset	1207 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	1208 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	1209 returned if width is less than ``len(s)``.
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50229 diff changeset	1210
42603 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 .. versionadded:: 2.2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1213
45800 7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1214 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	1215
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1216 .. method:: unicode.isnumeric()
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1217
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1218 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	1219 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	1220 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	1221 VULGAR FRACTION ONE FIFTH.
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50229 diff changeset	1222
45800 7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1223 .. method:: unicode.isdecimal()
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1224
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1225 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	1226 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	1227 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	1228 ARABIC-INDIC DIGIT ZERO.
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326) Steven Bethard <steven.bethard@gmail.com> parents: 45180 diff changeset	1229
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1230
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1231 .. _string-formatting:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1232
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1233 String Formatting Operations
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1234 ----------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1235
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1236 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1237 single: formatting, string (%)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1238 single: interpolation, string (%)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1239 single: string; formatting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1240 single: string; interpolation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1241 single: printf-style formatting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1242 single: sprintf-style formatting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1243 single: % formatting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1244 single: % interpolation
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 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	1247 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	1248 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	1249 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	1250 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	1251 :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	1252 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	1253 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	1254
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1255 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	1256 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	1257 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	1258 dictionary).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1259
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1260 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	1261 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	1262
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1263 #. 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	1264
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1265 #. 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	1266 (for example, ``(somename)``).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1267
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1268 #. 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	1269 types.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1270
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1271 #. 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	1272 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	1273 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	1274
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1275 #. 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	1276 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	1277 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	1278 precision.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1279
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1280 #. Length modifier (optional).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1281
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1282 #. Conversion type.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1283
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1284 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	1285 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	1286 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	1287 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	1288
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1289 >>> 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	1290 ... {'language': "Python", "#": 2}
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1291 Python has 002 quote types.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1292
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1293 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	1294 sequential parameter list).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1295
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1296 The conversion flag characters are:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1297
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 \| Flag \| Meaning \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1300 +=========+=====================================================================+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1301 \| ``'#'`` \| 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	1302 \| \| below). \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1303 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1304 \| ``'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	1305 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1306 \| ``'-'`` \| 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	1307 \| \| conversion if both are given). \|
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 \| ``' '`` \| (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	1310 \| \| string) produced by a signed conversion. \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1311 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1312 \| ``'+'`` \| 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	1313 \| \| (overrides a "space" flag). \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1314 +---------+---------------------------------------------------------------------+
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 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	1317 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	1318
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1319 The conversion types are:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1320
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 \| Conversion \| Meaning \| Notes \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1323 +============+=====================================================+=======+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1324 \| ``'d'`` \| Signed integer decimal. \| \|
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 \| ``'i'`` \| Signed integer decimal. \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1327 +------------+-----------------------------------------------------+-------+
46870 d88507588790 #1153769: document PEP 237 changes to string formatting. Georg Brandl <georg@python.org> parents: 46803 diff changeset	1328 \| ``'o'`` \| Signed octal value. \| \(1) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1329 +------------+-----------------------------------------------------+-------+
51894 866f747c196f #5361: fix typo. Georg Brandl <georg@python.org> parents: 51866 diff changeset	1330 \| ``'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	1331 +------------+-----------------------------------------------------+-------+
46870 d88507588790 #1153769: document PEP 237 changes to string formatting. Georg Brandl <georg@python.org> parents: 46803 diff changeset	1332 \| ``'x'`` \| Signed hexadecimal (lowercase). \| \(2) \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1333 +------------+-----------------------------------------------------+-------+
46870 d88507588790 #1153769: document PEP 237 changes to string formatting. Georg Brandl <georg@python.org> parents: 46803 diff changeset	1334 \| ``'X'`` \| Signed hexadecimal (uppercase). \| \(2) \|
42603 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 \| ``'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	1337 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1338 \| ``'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	1339 +------------+-----------------------------------------------------+-------+
48003 5c33009994b4 Backed out r65069, pending fixing it in Windows. Eric Smith <eric@trueblade.com> parents: 48001 diff changeset	1340 \| ``'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	1341 +------------+-----------------------------------------------------+-------+
48003 5c33009994b4 Backed out r65069, pending fixing it in Windows. Eric Smith <eric@trueblade.com> parents: 48001 diff changeset	1342 \| ``'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	1343 +------------+-----------------------------------------------------+-------+
46692 f8468bfd4357 #2773: fix description of 'g' and 'G' formatting spec. Georg Brandl <georg@python.org> parents: 46014 diff changeset	1344 \| ``'g'`` \| Floating point format. Uses lowercase exponential \| \(4) \|
46693 ddd5f42332b9 > != (!<). Georg Brandl <georg@python.org> parents: 46692 diff changeset	1345 \| \| 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	1346 \| \| precision, decimal format otherwise. \| \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1347 +------------+-----------------------------------------------------+-------+
46692 f8468bfd4357 #2773: fix description of 'g' and 'G' formatting spec. Georg Brandl <georg@python.org> parents: 46014 diff changeset	1348 \| ``'G'`` \| Floating point format. Uses uppercase exponential \| \(4) \|
46693 ddd5f42332b9 > != (!<). Georg Brandl <georg@python.org> parents: 46692 diff changeset	1349 \| \| 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	1350 \| \| precision, decimal format otherwise. \| \|
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1351 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1352 \| ``'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	1353 \| \| character string). \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1354 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1355 \| ``'r'`` \| String (converts any python object using \| \(5) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1356 \| \| :func:`repr`). \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1357 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1358 \| ``'s'`` \| String (converts any python object using \| \(6) \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1359 \| \| :func:`str`). \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1360 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1361 \| ``'%'`` \| 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	1362 \| \| character in the result. \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1363 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1364
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1365 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1366
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1367 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1368 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	1369 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	1370 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	1371
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1372 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1373 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	1374 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	1375 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	1376 already a zero.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1377
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1378 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1379 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	1380 no digits follow it.
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 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	1383 defaults to 6.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1384
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1385 (4)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1386 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	1387 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	1388
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1389 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	1390 decimal point and defaults to 6.
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 (5)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1393 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	1394
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1395 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	1396
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1397 (6)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1398 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	1399 string will also be :class:`unicode`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1400
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1401 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	1402
46870 d88507588790 #1153769: document PEP 237 changes to string formatting. Georg Brandl <georg@python.org> parents: 46803 diff changeset	1403 (7)
d88507588790 #1153769: document PEP 237 changes to string formatting. Georg Brandl <georg@python.org> parents: 46803 diff changeset	1404 See :pep:`237`.
d88507588790 #1153769: document PEP 237 changes to string formatting. Georg Brandl <georg@python.org> parents: 46803 diff changeset	1405
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1406 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	1407 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	1408
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	1409 .. XXX Examples?
42603 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 For safety reasons, floating point precisions are clipped to 50; ``%f``
52404 019815bc37ea Issue #532631: Replace confusing fabs(x)/1e25 >= 1e25 test Mark Dickinson <dickinsm@gmail.com> parents: 52377 diff changeset	1412 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	1413 conversions. [#]_ All other errors raise exceptions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1414
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1415 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1416 module: string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1417 module: re
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1418
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1419 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	1420 :mod:`re`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1421
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1422
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1423 .. _typesseq-xrange:
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 XRange Type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1426 -----------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1427
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1428 .. index:: object: xrange
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1429
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1430 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	1431 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	1432 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	1433 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	1434
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1435 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	1436 and the :func:`len` function.
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1439 .. _typesseq-mutable:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1440
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1441 Mutable Sequence Types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1442 ----------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1443
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1444 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1445 triple: mutable; sequence; types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1446 object: list
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 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	1449 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	1450 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	1451 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	1452 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	1453
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1454 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1455 \| Operation \| Result \| Notes \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1456 +==============================+================================+=====================+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1457 \| ``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	1458 \| \| x \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1459 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1460 \| ``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	1461 \| \| is replaced by the contents of \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1462 \| \| the iterable t \| \|
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 \| ``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	1465 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1466 \| ``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	1467 \| \| are replaced by those of t \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1468 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1469 \| ``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	1470 \| \| ``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	1471 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1472 \| ``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	1473 \| \| [x]`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1474 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1475 \| ``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	1476 \| \| x`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1477 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1478 \| ``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	1479 \| \| which ``s[i] == x`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1480 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1481 \| ``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	1482 \| \| ``s[k] == x`` and ``i <= k < \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1483 \| \| j`` \| \|
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.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	1486 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1487 \| ``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	1488 \| \| return x`` \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1489 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1490 \| ``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	1491 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1492 \| ``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	1493 \| \| place \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1494 +------------------------------+--------------------------------+---------------------+
44555 7ea231578b02 Consistency nit. Georg Brandl <georg@python.org> parents: 44553 diff changeset	1495 \| ``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	1496 \| reverse]]])`` \| \| \|
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1497 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1498
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1499 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1500 triple: operations on; sequence; types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1501 triple: operations on; list; type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1502 pair: subscript; assignment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1503 pair: slice; assignment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1504 pair: extended slice; assignment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1505 statement: del
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1506 single: append() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1507 single: extend() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1508 single: count() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1509 single: index() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1510 single: insert() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1511 single: pop() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1512 single: remove() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1513 single: reverse() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1514 single: sort() (list method)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1515
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1516 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1517
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1518 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1519 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	1520
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1521 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1522 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	1523 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	1524 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	1525
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1526 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1527 x can be any iterable object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1528
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1529 (4)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1530 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	1531 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	1532 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	1533 to zero, as for slice indices.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1534
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1535 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1536 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	1537 positions.
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 (5)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1540 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	1541 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	1542 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	1543
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1544 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1545 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	1546
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1547 (6)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1548 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	1549 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	1550 removed and returned.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1551
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1552 (7)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1553 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	1554 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	1555 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	1556
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1557 (8)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1558 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	1559 comparisons.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1560
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1561 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	1562 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	1563 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	1564 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	1565 is ``None``.
42603 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 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	1568 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	1569
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1570 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	1571 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	1572
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1573 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	1574 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	1575 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	1576 element only once.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1577
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1578 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1579 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	1580
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1581 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1582 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	1583
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1584 (9)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1585 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	1586 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	1587 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	1588 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	1589
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1590 (10)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1591 While a list is being sorted, the effect of attempting to mutate, or even
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1592 inspect, the list is undefined. The C implementation of Python 2.3 and newer
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1593 makes the list appear empty for the duration, and raises :exc:`ValueError` if it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1594 can detect that the list has been mutated during a sort.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1595
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1596
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1597 .. _types-set:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1598
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1599 Set Types --- :class:`set`, :class:`frozenset`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1600 ==============================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1601
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1602 .. index:: object: set
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1603
43753 4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1604 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	1605 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	1606 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	1607 symmetric difference.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1608 (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	1609 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	1610
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 .. versionadded:: 2.4
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 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	1615 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	1616 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	1617 other sequence-like behavior.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1618
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1619 There are currently two builtin set types, :class:`set` and :class:`frozenset`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1620 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	1621 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	1622 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	1623 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	1624 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	1625 an element of another set.
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 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	1628
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1629 .. class:: set([iterable])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1630 frozenset([iterable])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1631
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1632 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	1633 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	1634 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	1635 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	1636
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1637 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	1638 operations:
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1639
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1640 .. describe:: len(s)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1641
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1642 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	1643
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1644 .. describe:: x in s
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1645
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1646 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	1647
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1648 .. 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	1649
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1650 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	1651
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1652 .. method:: isdisjoint(other)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1653
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1654 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	1655 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	1656
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1657 .. versionadded:: 2.6
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 .. method:: issubset(other)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1660 set <= other
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1661
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1662 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	1663
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1664 .. method:: set < other
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1665
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1666 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	1667 ``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	1668
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1669 .. method:: issuperset(other)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1670 set >= other
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 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	1673
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1674 .. method:: set > other
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1675
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1676 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	1677 other and set != other``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1678
47530 d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1679 .. method:: union(other, ...)
d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1680 set \| other \| ...
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1681
50861 189d50830297 #4976: union() and intersection() take multiple args, but talk about "the other". Georg Brandl <georg@python.org> parents: 50579 diff changeset	1682 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	1683
47530 d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1684 .. versionchanged:: 2.6
d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1685 Accepts multiple input iterables.
d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1686
47533 10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1687 .. method:: intersection(other, ...)
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1688 set & other & ...
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1689
50861 189d50830297 #4976: union() and intersection() take multiple args, but talk about "the other". Georg Brandl <georg@python.org> parents: 50579 diff changeset	1690 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	1691
47533 10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1692 .. versionchanged:: 2.6
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1693 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	1694
47588 8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1695 .. method:: difference(other, ...)
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1696 set - other - ...
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1697
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1698 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	1699
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1700 .. versionchanged:: 2.6
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1701 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	1702
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1703 .. method:: symmetric_difference(other)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1704 set ^ other
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1705
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1706 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	1707
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1708 .. method:: copy()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1709
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1710 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	1711
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1712
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1713 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	1714 :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	1715 :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	1716 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	1717 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	1718 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	1719
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1720 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	1721 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	1722 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	1723 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	1724 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	1725 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	1726
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1727 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	1728 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	1729 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	1730
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1731 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	1732 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	1733 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	1734 ``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	1735 method.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1736
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1737 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	1738 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	1739
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1740 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	1741
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1742 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	1743 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	1744 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	1745
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1746 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	1747 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	1748
47530 d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1749 .. method:: update(other, ...)
d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1750 set \|= other \| ...
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1751
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1752 Update the set, adding elements from other.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1753
47530 d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1754 .. versionchanged:: 2.6
d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1755 Accepts multiple input iterables.
d4cd7223af3b Let set.union() and set.update() accept multiple inputs. Raymond Hettinger <python@rcn.com> parents: 47413 diff changeset	1756
47533 10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1757 .. 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	1758 set &= other & ...
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1759
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1760 Update the set, keeping only elements found in it and other.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1761
47533 10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1762 .. versionchanged:: 2.6
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments. Raymond Hettinger <python@rcn.com> parents: 47530 diff changeset	1763 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	1764
47588 8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1765 .. method:: difference_update(other, ...)
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1766 set -= other \| ...
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1767
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1768 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	1769
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1770 .. versionchanged:: 2.6
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update(). Raymond Hettinger <python@rcn.com> parents: 47533 diff changeset	1771 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	1772
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1773 .. method:: symmetric_difference_update(other)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1774 set ^= other
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1775
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1776 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	1777
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1778 .. method:: add(elem)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1779
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1780 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	1781
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1782 .. method:: remove(elem)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1783
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1784 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	1785 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	1786
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1787 .. method:: discard(elem)
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 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	1790
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1791 .. method:: pop()
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 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	1794 :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	1795
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1796 .. method:: clear()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1797
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1798 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	1799
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1800
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1801 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	1802 :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	1803 :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	1804 argument.
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 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	1807 :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	1808 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	1809 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	1810 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	1811
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1812
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1813 .. seealso::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1814
44050 eccb197044dd Fix reference target. Georg Brandl <georg@python.org> parents: 43805 diff changeset	1815 :ref:`comparison-to-builtin-set`
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1816 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	1817
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1818
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1819 .. _typesmapping:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1820
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1821 Mapping Types --- :class:`dict`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1822 ===============================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1823
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1824 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1825 object: mapping
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1826 object: dictionary
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1827 triple: operations on; mapping; types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1828 triple: operations on; dictionary; type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1829 statement: del
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1830 builtin: len
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1831
43753 4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1832 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	1833 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	1834 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	1835 :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	1836 :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	1837
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. Georg Brandl <georg@python.org> parents: 43748 diff changeset	1838 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	1839 :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	1840 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	1841 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	1842 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	1843 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	1844 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	1845 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	1846
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1847 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	1848 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	1849 '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	1850
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1851 .. class:: dict([arg])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1852
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1853 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	1854 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	1855 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	1856 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	1857 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	1858 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	1859 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	1860 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	1861 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	1862 is retained in the new dictionary.
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 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	1865 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	1866 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	1867 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	1868 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	1869
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1870 * ``dict(one=2, two=3)``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1871
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1872 * ``dict({'one': 2, 'two': 3})``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1873
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1874 * ``dict(zip(('one', 'two'), (2, 3)))``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1875
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1876 * ``dict([['two', 3], ['one', 2]])``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1877
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1878 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	1879 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	1880
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1881 .. versionadded:: 2.2
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 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1884 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	1885
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1886
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1887 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	1888 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	1889
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1890 .. describe:: len(d)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1891
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1892 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	1893
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1894 .. describe:: d[key]
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1895
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1896 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	1897 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	1898
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50229 diff changeset	1899 .. versionadded:: 2.5
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1900 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	1901 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	1902 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	1903 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	1904 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	1905 :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	1906 :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	1907 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	1908 :class:`collections.defaultdict`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1909
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1910 .. describe:: d[key] = value
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1911
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1912 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	1913
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1914 .. describe:: del d[key]
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1915
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1916 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	1917 map.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1918
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1919 .. describe:: key in d
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1920
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1921 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	1922
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1923 .. versionadded:: 2.2
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 .. 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	1926
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1927 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	1928
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1929 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1930
52853 19b0db1354f7 note how using iter* are unsafe while mutating and document iter(dict) Benjamin Peterson <benjamin@python.org> parents: 52749 diff changeset	1931 .. describe:: iter(d)
19b0db1354f7 note how using iter* are unsafe while mutating and document iter(dict) Benjamin Peterson <benjamin@python.org> parents: 52749 diff changeset	1932
19b0db1354f7 note how using iter* are unsafe while mutating and document iter(dict) Benjamin Peterson <benjamin@python.org> parents: 52749 diff changeset	1933 Return an iterator over the keys of the dictionary. This is a shortcut
19b0db1354f7 note how using iter* are unsafe while mutating and document iter(dict) Benjamin Peterson <benjamin@python.org> parents: 52749 diff changeset	1934 for :meth:`iterkeys`.
19b0db1354f7 note how using iter* are unsafe while mutating and document iter(dict) Benjamin Peterson <benjamin@python.org> parents: 52749 diff changeset	1935
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1936 .. method:: clear()
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 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	1939
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1940 .. method:: copy()
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 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	1943
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1944 .. method:: fromkeys(seq[, value])
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1945
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1946 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	1947
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1948 :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	1949 defaults to ``None``.
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 .. versionadded:: 2.3
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:: get(key[, default])
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 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	1956 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	1957 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	1958
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1959 .. method:: has_key(key)
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1960
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	1961 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	1962 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	1963
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1964 .. method:: items()
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 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	1967
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1968 .. note::
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1969
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1970 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	1971 varies across Python implementations, and depends on the dictionary's
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1972 history of insertions and deletions. If :meth:`items`, :meth:`keys`,
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1973 :meth:`values`, :meth:`iteritems`, :meth:`iterkeys`, and
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1974 :meth:`itervalues` are called with no intervening modifications to the
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1975 dictionary, the lists will directly correspond. This allows the
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1976 creation of ``(value, key)`` pairs using :func:`zip`: ``pairs =
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1977 zip(d.values(), d.keys())``. The same relationship holds for the
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1978 :meth:`iterkeys` and :meth:`itervalues` methods: ``pairs =
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1979 zip(d.itervalues(), d.iterkeys())`` provides the same value for
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1980 ``pairs``. Another way to create the same list is ``pairs = [(v, k) for
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1981 (k, v) in d.iteritems()]``.
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 .. method:: iteritems()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1984
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1985 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	1986 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	1987
52853 19b0db1354f7 note how using iter* are unsafe while mutating and document iter(dict) Benjamin Peterson <benjamin@python.org> parents: 52749 diff changeset	1988 Using :meth:`iteritems` while adding or deleting entries in the dictionary
54136 b52b92f31fa8 #6017: better document behavior of dictiterators when the dict is changed. Georg Brandl <georg@python.org> parents: 52853 diff changeset	1989 may raise a :exc:`RuntimeError` or fail to iterate over all entries.
52853 19b0db1354f7 note how using iter* are unsafe while mutating and document iter(dict) Benjamin Peterson <benjamin@python.org> parents: 52749 diff changeset	1990
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1991 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1992
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1993 .. method:: iterkeys()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1994
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1995 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	1996 :meth:`dict.items`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	1997
52853 19b0db1354f7 note how using iter* are unsafe while mutating and document iter(dict) Benjamin Peterson <benjamin@python.org> parents: 52749 diff changeset	1998 Using :meth:`iterkeys` while adding or deleting entries in the dictionary
54136 b52b92f31fa8 #6017: better document behavior of dictiterators when the dict is changed. Georg Brandl <georg@python.org> parents: 52853 diff changeset	1999 may raise a :exc:`RuntimeError` or fail to iterate over all entries.
52853 19b0db1354f7 note how using iter* are unsafe while mutating and document iter(dict) Benjamin Peterson <benjamin@python.org> parents: 52749 diff changeset	2000
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2001 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2002
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2003 .. method:: itervalues()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2004
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2005 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	2006 :meth:`dict.items`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2007
52853 19b0db1354f7 note how using iter* are unsafe while mutating and document iter(dict) Benjamin Peterson <benjamin@python.org> parents: 52749 diff changeset	2008 Using :meth:`itervalues` while adding or deleting entries in the
54136 b52b92f31fa8 #6017: better document behavior of dictiterators when the dict is changed. Georg Brandl <georg@python.org> parents: 52853 diff changeset	2009 dictionary may raise a :exc:`RuntimeError` or fail to iterate over all
b52b92f31fa8 #6017: better document behavior of dictiterators when the dict is changed. Georg Brandl <georg@python.org> parents: 52853 diff changeset	2010 entries.
52853 19b0db1354f7 note how using iter* are unsafe while mutating and document iter(dict) Benjamin Peterson <benjamin@python.org> parents: 52749 diff changeset	2011
46803 802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2012 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2013
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2014 .. method:: keys()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2015
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2016 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	2017 :meth:`dict.items`.
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 .. method:: pop(key[, default])
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2020
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2021 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	2022 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	2023 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	2024
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2025 .. versionadded:: 2.3
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2026
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2027 .. method:: popitem()
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2028
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2029 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	2030
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2031 :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	2032 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	2033 :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	2034
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2035 .. method:: setdefault(key[, default])
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2036
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2037 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	2038 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	2039 ``None``.
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:: update([other])
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 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	2044 existing keys. Return ``None``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2045
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2046 :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	2047 key/value pairs (as a tuple or other iterable of length two). If keyword
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2048 arguments are specified, the dictionary is then is updated with those
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2049 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	2050
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2051 .. versionchanged:: 2.4
802519f04754 In stdtypes.rst, move methods under class directives where applicable Benjamin Peterson <benjamin@python.org> parents: 46744 diff changeset	2052 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	2053 keyword arguments.
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:: values()
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 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	2058 :meth:`dict.items`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2059
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2060
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2061 .. _bltin-file-objects:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2062
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2063 File Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2064 ============
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2065
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2066 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2067 object: file
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2068 builtin: file
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2069 module: os
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2070 module: socket
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2071
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2072 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	2073 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	2074 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	2075 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	2076 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	2077 :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	2078 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	2079 :mod:`shutil` module.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2080
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2081 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	2082 :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	2083 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	2084 opened for reading.
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 Files have the following methods:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2087
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2088
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2089 .. method:: file.close()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2090
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2091 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	2092 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	2093 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	2094
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2095 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	2096 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	2097 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	2098
48097 0c7fab0b05c0 the from __future__ import with_statement isn't needed in 2.6 Benjamin Peterson <benjamin@python.org> parents: 48081 diff changeset	2099 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	2100
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2101 with open("hello.txt") as f:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2102 for line in f:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2103 print line
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 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	2106 effect::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2107
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2108 f = open("hello.txt")
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2109 try:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2110 for line in f:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2111 print line
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2112 finally:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2113 f.close()
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 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2116
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2117 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	2118 :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	2119 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	2120 the object directly.
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2123 .. method:: file.flush()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2124
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2125 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	2126 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	2127
51539 29a9e85f30bf os.fsync() should be used to ensure that data is written to disk Benjamin Peterson <benjamin@python.org> parents: 50864 diff changeset	2128 .. note::
29a9e85f30bf os.fsync() should be used to ensure that data is written to disk Benjamin Peterson <benjamin@python.org> parents: 50864 diff changeset	2129
29a9e85f30bf os.fsync() should be used to ensure that data is written to disk Benjamin Peterson <benjamin@python.org> parents: 50864 diff changeset	2130 :meth:`flush` does not necessarily write the file's data to disk. Use
29a9e85f30bf os.fsync() should be used to ensure that data is written to disk Benjamin Peterson <benjamin@python.org> parents: 50864 diff changeset	2131 :meth:`flush` followed by :func:`os.fsync` to ensure this behavior.
29a9e85f30bf os.fsync() should be used to ensure that data is written to disk Benjamin Peterson <benjamin@python.org> parents: 50864 diff changeset	2132
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2133
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2134 .. method:: file.fileno()
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 .. index::
43627 faf5de69e977 Add :term:s for descriptors. Georg Brandl <georg@python.org> parents: 43585 diff changeset	2137 pair: file; descriptor
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2138 module: fcntl
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2139
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2140 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	2141 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	2142 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	2143 :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	2144
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2145 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2146
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2147 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	2148 this method!
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2151 .. method:: file.isatty()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2152
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2153 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	2154
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2155 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2156
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2157 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	2158 not be implemented.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2159
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 .. method:: file.next()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2162
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2163 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	2164 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	2165 :keyword:`for` loop (for example, ``for line in f: print line``), the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2166 :meth:`next` method is called repeatedly. This method returns the next input
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2167 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	2168 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	2169 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	2170 file (a very common operation), the :meth:`next` method uses a hidden read-ahead
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2171 buffer. As a consequence of using a read-ahead buffer, combining :meth:`next`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2172 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	2173 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	2174 read-ahead buffer.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2175
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2176 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2177
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2178
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2179 .. method:: file.read([size])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2180
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2181 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	2182 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	2183 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	2184 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	2185 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	2186 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	2187 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	2188 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	2189 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	2190
47865 cda556d23924 #1523853: add note about fread(). Georg Brandl <georg@python.org> parents: 47787 diff changeset	2191 .. 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	2192 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	2193 :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	2194 such as whether the EOF value is cached.
47865 cda556d23924 #1523853: add note about fread(). Georg Brandl <georg@python.org> parents: 47787 diff changeset	2195
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2196
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2197 .. method:: file.readline([size])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2198
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2199 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	2200 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	2201 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	2202 (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	2203 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	2204
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2205 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2206
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2207 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	2208 (``'\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	2209
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.readlines([sizehint])
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 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	2214 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	2215 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	2216 (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	2217 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	2218 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	2219
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 .. method:: file.xreadlines()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2222
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2223 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	2224
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2225 .. versionadded:: 2.1
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 .. deprecated:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2228 Use ``for line in file`` instead.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2229
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2230
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2231 .. method:: file.seek(offset[, whence])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2232
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2233 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	2234 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	2235 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	2236 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	2237 end). There is no return value.
50508 c52177f36852 Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50229 diff changeset	2238
44497 01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. Georg Brandl <georg@python.org> parents: 44488 diff changeset	2239 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	2240 ``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	2241
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. Georg Brandl <georg@python.org> parents: 44488 diff changeset	2242 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	2243 (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	2244 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	2245 ``'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	2246 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	2247 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	2248 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	2249
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2250 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	2251
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2252 .. versionchanged:: 2.6
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 44344 diff changeset	2253 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	2254
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2255
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2256 .. method:: file.tell()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2257
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2258 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	2259
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2260 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2261
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2262 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	2263 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	2264 circumvent this problem.
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2267 .. method:: file.truncate([size])
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 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	2270 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	2271 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	2272 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	2273 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	2274 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	2275 Availability: Windows, many Unix variants.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2276
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2277
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2278 .. method:: file.write(str)
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 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	2281 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	2282 :meth:`close` method is called.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2283
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2284
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2285 .. method:: file.writelines(sequence)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2286
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2287 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	2288 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	2289 (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	2290 add line separators.)
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 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	2293 ``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	2294 an empty string.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2295
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2296 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	2297 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	2298 the particular object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2299
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 .. attribute:: file.closed
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2302
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2303 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	2304 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	2305 on all file-like objects.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2306
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2307
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2308 .. attribute:: file.encoding
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 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	2311 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	2312 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	2313 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	2314 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	2315 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	2316 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	2317
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2318 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2319
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2320
47413 1062b7dec95b New environment variable PYTHONIOENCODING. Martin v. Löwis <martin@v.loewis.de> parents: 46949 diff changeset	2321 .. attribute:: file.errors
1062b7dec95b New environment variable PYTHONIOENCODING. Martin v. Löwis <martin@v.loewis.de> parents: 46949 diff changeset	2322
47787 b32101c19bf8 Grammar fixes Andrew M. Kuchling <amk@amk.ca> parents: 47588 diff changeset	2323 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	2324
1062b7dec95b New environment variable PYTHONIOENCODING. Martin v. Löwis <martin@v.loewis.de> parents: 46949 diff changeset	2325 .. versionadded:: 2.6
1062b7dec95b New environment variable PYTHONIOENCODING. Martin v. Löwis <martin@v.loewis.de> parents: 46949 diff changeset	2326
1062b7dec95b New environment variable PYTHONIOENCODING. Martin v. Löwis <martin@v.loewis.de> parents: 46949 diff changeset	2327
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2328 .. attribute:: file.mode
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2329
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2330 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	2331 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	2332 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	2333
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2334
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2335 .. attribute:: file.name
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2336
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2337 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	2338 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	2339 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	2340 file-like objects.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2341
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2342
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2343 .. attribute:: file.newlines
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2344
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2345 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	2346 :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	2347 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	2348 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	2349 ``'\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	2350 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	2351 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	2352 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	2353
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2354
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2355 .. attribute:: file.softspace
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 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	2358 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	2359 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	2360 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	2361 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	2362 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	2363 :attr:`softspace` attribute.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2364
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2365 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2366
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2367 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	2368 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	2369 state.
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
52749 75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2372 .. _typememoryview:
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2373
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2374 memoryview Types
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2375 ================
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2376
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2377 :class:`memoryview`\s allow Python code to access the internal data of an object
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2378 that supports the buffer protocol without copying. Memory can be interpreted as
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2379 simple bytes or complex data structures.
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2380
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2381 .. class:: memoryview(obj)
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2382
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2383 Create a :class:`memoryview` that references obj. obj must support the
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2384 buffer protocol. Builtin objects that support the buffer protocol include
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2385 :class:`str` and :class:`bytearray` (but not :class:`unicode`).
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2386
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2387 ``len(view)`` returns the total number of bytes in the memoryview, view.
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2388
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2389 A :class:`memoryview` supports slicing to expose its data. Taking a single
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2390 index will return a single byte. Full slicing will result in a subview::
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2391
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2392 >>> v = memoryview('abcefg')
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2393 >>> v[1]
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2394 'b'
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2395 >>> v[-1]
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2396 'g'
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2397 >>> v[1:4]
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2398 <memory at 0x77ab28>
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2399 >>> str(v[1:4])
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2400 'bce'
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2401 >>> v[3:-1]
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2402 <memory at 0x744f18>
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2403 >>> str(v[4:-1])
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2404 'f'
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2405
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2406 If the object the memory view is over supports changing its data, the
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2407 memoryview supports slice assignment::
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2408
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2409 >>> data = bytearray('abcefg')
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2410 >>> v = memoryview(data)
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2411 >>> v.readonly
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2412 False
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2413 >>> v[0] = 'z'
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2414 >>> data
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2415 bytearray(b'zbcefg')
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2416 >>> v[1:4] = '123'
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2417 >>> data
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2418 bytearray(b'z123fg')
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2419 >>> v[2] = 'spam'
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2420 Traceback (most recent call last):
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2421 File "<stdin>", line 1, in <module>
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2422 ValueError: cannot modify size of memoryview object
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2423
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2424 Notice how the size of the memoryview object can not be changed.
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2425
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2426
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2427 :class:`memoryview` has two methods:
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2428
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2429 .. method:: tobytes()
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2430
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2431 Return the data in the buffer as a bytestring (an object of class
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2432 :class:`str`).
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2433
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2434 .. method:: tolist()
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2435
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2436 Return the data in the buffer as a list of integers. ::
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2437
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2438 >>> memoryview(b'abc').tolist()
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2439 [97, 98, 99]
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2440
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2441 There are also several readonly attributes available:
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2442
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2443 .. attribute:: format
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2444
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2445 A string containing the format (in :mod:`struct` module style) for each
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2446 element in the view. This defaults to ``'B'``, a simple bytestring.
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2447
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2448 .. attribute:: itemsize
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2449
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2450 The size in bytes of each element of the memoryview.
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2451
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2452 .. attribute:: shape
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2453
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2454 A tuple of integers the length of :attr:`ndim` giving the shape of the
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2455 memory as a N-dimensional array.
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2456
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2457 .. attribute:: ndim
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2458
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2459 An integer indicating how many dimensions of a multi-dimensional array the
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2460 memory represents.
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2461
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2462 .. attribute:: strides
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2463
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2464 A tuple of integers the length of :attr:`ndim` giving the size in bytes to
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2465 access each element for each dimension of the array.
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2466
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2467 .. memoryview.suboffsets isn't documented because it only seems useful for C
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2468
75efd757434b Issue #2396: backport the memoryview object. Antoine Pitrou <solipsis@pitrou.net> parents: 52569 diff changeset	2469
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2470 .. _typecontextmanager:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2471
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2472 Context Manager Types
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 .. versionadded:: 2.5
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 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2478 single: context manager
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2479 single: context management protocol
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2480 single: protocol; context management
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2481
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2482 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	2483 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	2484 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	2485 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	2486
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2487 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	2488 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	2489
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2490
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2491 .. method:: contextmanager.__enter__()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2492
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2493 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	2494 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	2495 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	2496 this context manager.
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 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	2499 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	2500 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	2501
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2502 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	2503 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	2504 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	2505 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	2506 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	2507 :keyword:`with` statement.
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2510 .. 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	2511
43585 f1f701c224c1 Issue 1289, just a typo. Facundo Batista <facundobatista@gmail.com> parents: 43492 diff changeset	2512 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	2513 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	2514 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	2515 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	2516
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2517 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	2518 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	2519 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	2520 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	2521 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	2522 body of the :keyword:`with` statement.
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 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	2525 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	2526 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	2527 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	2528 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	2529
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2530 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	2531 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	2532 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	2533 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	2534 :mod:`contextlib` module for some examples.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2535
44103 1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 44050 diff changeset	2536 Python's :term:`generator`\s and the ``contextlib.contextfactory`` :term:`decorator`
1e266015cf5b Add more entries to the glossary. Georg Brandl <georg@python.org> parents: 44050 diff changeset	2537 provide a convenient way to implement these protocols. If a generator function is
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2538 decorated with the ``contextlib.contextfactory`` decorator, it will return a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2539 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	2540 :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	2541 generator function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2542
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2543 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	2544 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	2545 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	2546 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	2547 single class dictionary lookup is negligible.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2548
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2549
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2550 .. _typesother:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2551
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2552 Other Built-in Types
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2555 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	2556 only one or two operations.
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2559 .. _typesmodules:
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 Modules
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 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	2565 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	2566 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	2567 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	2568 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	2569 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	2570
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2571 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	2572 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	2573 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	2574 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	2575 ``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	2576 :attr:`__dict__` directly is not recommended.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2577
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2578 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	2579 (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	2580 '/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	2581
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2582
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2583 .. _typesobjects:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2584
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2585 Classes and Class Instances
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2586 ---------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2587
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2588 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	2589
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 .. _typesfunctions:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2592
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2593 Functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2594 ---------
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 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	2597 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	2598
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2599 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	2600 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	2601 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	2602
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2603 See :ref:`function` for more information.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2604
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 .. _typesmethods:
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 Methods
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2609 -------
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 .. index:: object: method
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 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	2614 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	2615 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	2616 them.
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 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	2619 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	2620 ``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	2621 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	2622 arg-1, arg-2, ..., arg-n)``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2623
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2624 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	2625 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	2626 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	2627 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	2628 ``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	2629 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	2630
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2631 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	2632 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	2633 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	2634 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	2635 :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	2636 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	2637
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2638 class C:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2639 def method(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2640 pass
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2641
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2642 c = C()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2643 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	2644
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2645 See :ref:`types` for more information.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2646
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2647
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2648 .. _bltin-code-objects:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2649
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2650 Code Objects
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2653 .. index:: object: code
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2654
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2655 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2656 builtin: compile
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2657 single: func_code (function object attribute)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2658
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2659 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	2660 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	2661 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	2662 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	2663 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	2664 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	2665
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2666 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2667 statement: exec
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2668 builtin: eval
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 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	2671 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	2672
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2673 See :ref:`types` for more information.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2674
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 .. _bltin-type-objects:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2677
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2678 Type Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2679 ------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2680
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2681 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2682 builtin: type
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2683 module: types
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2684
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2685 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	2686 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	2687 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	2688 types.
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 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	2691
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 .. _bltin-null-object:
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 The Null Object
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2696 ---------------
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 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	2699 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	2700 ``None`` (a built-in name).
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 It is written as ``None``.
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2705 .. _bltin-ellipsis-object:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2706
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2707 The Ellipsis Object
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2708 -------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2709
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2710 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	2711 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	2712 :const:`Ellipsis` (a built-in name).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2713
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2714 It is written as ``Ellipsis``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2715
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2716
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2717 Boolean Values
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2718 --------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2719
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2720 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	2721 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	2722 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	2723 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	2724 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	2725 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	2726 Testing above).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2727
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2728 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2729 single: False
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2730 single: True
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2731 pair: Boolean; values
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2732
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2733 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	2734
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2735
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2736 .. _typesinternal:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2737
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2738 Internal Objects
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2741 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	2742 traceback objects, and slice objects.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2743
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 .. _specialattrs:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2746
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2747 Special Attributes
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
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2750 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	2751 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	2752 :func:`dir` built-in function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2753
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2754
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2755 .. attribute:: object.__dict__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2756
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2757 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	2758 attributes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2759
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2760
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2761 .. attribute:: object.__methods__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2762
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2763 .. deprecated:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2764 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	2765 This attribute is no longer available.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2766
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2767
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2768 .. attribute:: object.__members__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2769
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2770 .. deprecated:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2771 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	2772 This attribute is no longer available.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2773
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2774
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2775 .. attribute:: instance.__class__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2776
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2777 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	2778
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2779
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2780 .. attribute:: class.__bases__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2781
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2782 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	2783 will be an empty tuple.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2784
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2785
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2786 .. attribute:: class.__name__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2787
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2788 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	2789
52377 b73cdac6a0c3 #5324: document __subclasses__(). Georg Brandl <georg@python.org> parents: 51894 diff changeset	2790
52569 02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2791 The following attributes are only supported by :term:`new-style class`\ es.
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2792
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2793 .. attribute:: class.__mro__
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2794
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2795 This attribute is a tuple of classes that are considered when looking for
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2796 base classes during method resolution.
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2797
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2798
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2799 .. method:: class.mro()
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2800
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2801 This method can be overridden by a metaclass to customize the method
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2802 resolution order for its instances. It is called at class instantiation, and
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2803 its result is stored in :attr:`__mro__`.
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2804
02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2805
52377 b73cdac6a0c3 #5324: document __subclasses__(). Georg Brandl <georg@python.org> parents: 51894 diff changeset	2806 .. method:: class.__subclasses__
b73cdac6a0c3 #5324: document __subclasses__(). Georg Brandl <georg@python.org> parents: 51894 diff changeset	2807
52569 02db2d340133 #4411: document mro() and __mro__. (I hope I got it right.) Georg Brandl <georg@python.org> parents: 52404 diff changeset	2808 Each new-style class keeps a list of weak references to its immediate
52377 b73cdac6a0c3 #5324: document __subclasses__(). Georg Brandl <georg@python.org> parents: 51894 diff changeset	2809 subclasses. This method returns a list of all those references still alive.
b73cdac6a0c3 #5324: document __subclasses__(). Georg Brandl <georg@python.org> parents: 51894 diff changeset	2810 Example::
b73cdac6a0c3 #5324: document __subclasses__(). Georg Brandl <georg@python.org> parents: 51894 diff changeset	2811
b73cdac6a0c3 #5324: document __subclasses__(). Georg Brandl <georg@python.org> parents: 51894 diff changeset	2812 >>> int.__subclasses__()
b73cdac6a0c3 #5324: document __subclasses__(). Georg Brandl <georg@python.org> parents: 51894 diff changeset	2813 [<type 'bool'>]
b73cdac6a0c3 #5324: document __subclasses__(). Georg Brandl <georg@python.org> parents: 51894 diff changeset	2814
b73cdac6a0c3 #5324: document __subclasses__(). Georg Brandl <georg@python.org> parents: 51894 diff changeset	2815
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2816 .. rubric:: Footnotes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2817
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2818 .. [#] 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	2819 Reference Manual (:ref:`customization`).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2820
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2821 .. [#] 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	2822 similarly for tuples.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2823
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2824 .. [#] 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	2825
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2826 .. [#] 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	2827 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	2828
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2829 .. [#] 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	2830 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	2831 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	2832
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2833 .. [#] 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	2834 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	2835 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	2836 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	2837 or not (yes this happens!).

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/stdtypes.rst @ 54294:dba767bc3155 legacy-trunk