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

annotate Doc/library/stdtypes.rst @ 78069:a8aa77458e12 3.2

Add c_size_t and c_ssize_t to the ctypes summary table.

author	Antoine Pitrou <solipsis@pitrou.net>
date	Thu, 12 Jul 2012 20:31:50 +0200
parents	4d9b3a58e208
children	768b188262e7 3bb35ad5d9da

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 .. XXX: reference/datamodel and this have quite a few overlaps!
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 .. _bltin-types:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 **************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 Built-in Types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 **************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 interpreter.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 .. index:: pair: built-in; types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14
57785 aeef2f27f9f0 Merged revisions 76893 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 56894 diff changeset	15 The principal built-in types are numerics, sequences, mappings, classes,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 instances and exceptions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 Some operations are supported by several object types; in particular,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 practically all objects can be compared, tested for truth value, and converted
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 to a string (with the :func:`repr` function or the slightly different
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 :func:`str` function). The latter function is implicitly used when an object is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 written by the :func:`print` function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 .. _truth:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 Truth Value Testing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 ===================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 statement: if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 statement: while
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33 pair: truth; value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 pair: Boolean; operations
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 single: false
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 Any object can be tested for truth value, for use in an :keyword:`if` or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 :keyword:`while` condition or as operand of the Boolean operations below. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 following values are considered false:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 .. index:: single: None (Built-in object)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 * ``None``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 .. index:: single: False (Built-in object)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 * ``False``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48
48391 913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	49 * zero of any numeric type, for example, ``0``, ``0.0``, ``0j``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 * any empty sequence, for example, ``''``, ``()``, ``[]``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 * any empty mapping, for example, ``{}``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 * instances of user-defined classes, if the class defines a :meth:`__bool__` or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 :meth:`__len__` method, when that method returns the integer zero or
71870 16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	57 :class:`bool` value ``False``. [1]_
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 .. index:: single: true
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61 All other values are considered true --- so objects of many types are always
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 true.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 operator: or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 operator: and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 single: False
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 single: True
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 Operations and built-in functions that have a Boolean result always return ``0``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 or ``False`` for false and ``1`` or ``True`` for true, unless otherwise stated.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 (Important exception: the Boolean operations ``or`` and ``and`` always return
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 one of their operands.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 .. _boolean:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 Boolean Operations --- :keyword:`and`, :keyword:`or`, :keyword:`not`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 ====================================================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 .. index:: pair: Boolean; operations
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83 These are the Boolean operations, ordered by ascending priority:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 +-------------+---------------------------------+-------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 \| Operation \| Result \| Notes \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 +=============+=================================+=======+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 \| ``x or y`` \| if x is false, then y, else \| \(1) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 \| \| x \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90 +-------------+---------------------------------+-------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 \| ``x and y`` \| if x is false, then x, else \| \(2) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 \| \| y \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 +-------------+---------------------------------+-------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 \| ``not x`` \| if x is false, then ``True``, \| \(3) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 \| \| else ``False`` \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96 +-------------+---------------------------------+-------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 operator: and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 operator: or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 operator: not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 Notes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 (1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 This is a short-circuit operator, so it only evaluates the second
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 argument if the first one is :const:`False`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 (2)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 This is a short-circuit operator, so it only evaluates the second
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 argument if the first one is :const:`True`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 (3)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 ``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118 .. _stdcomparisons:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 Comparisons
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 ===========
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	123 .. index::
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	124 pair: chaining; comparisons
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	125 pair: operator; comparison
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	126 operator: ==
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	127 operator: <
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	128 operator: <=
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	129 operator: >
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	130 operator: >=
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	131 operator: !=
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	132 operator: is
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	133 operator: is not
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	135 There are eight comparison operations in Python. They all have the same
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	136 priority (which is higher than that of the Boolean operations). Comparisons can
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 y <= z``, except that y is evaluated only once (but in both cases z is not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 evaluated at all when ``x < y`` is found to be false).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 This table summarizes the comparison operations:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142
44554 6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	143 +------------+-------------------------+
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	144 \| Operation \| Meaning \|
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	145 +============+=========================+
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	146 \| ``<`` \| strictly less than \|
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	147 +------------+-------------------------+
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	148 \| ``<=`` \| less than or equal \|
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	149 +------------+-------------------------+
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	150 \| ``>`` \| strictly greater than \|
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	151 +------------+-------------------------+
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	152 \| ``>=`` \| greater than or equal \|
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	153 +------------+-------------------------+
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	154 \| ``==`` \| equal \|
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	155 +------------+-------------------------+
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	156 \| ``!=`` \| not equal \|
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	157 +------------+-------------------------+
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	158 \| ``is`` \| object identity \|
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	159 +------------+-------------------------+
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	160 \| ``is not`` \| negated object identity \|
6c4b0cc9f6c9 Remove obsolete note. Georg Brandl <georg@python.org> parents: 44539 diff changeset	161 +------------+-------------------------+
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44349 diff changeset	162
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44349 diff changeset	163 .. index::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 pair: object; numeric
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 pair: objects; comparing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	167 Objects of different types, except different numeric types, never compare equal.
57785 aeef2f27f9f0 Merged revisions 76893 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 56894 diff changeset	168 Furthermore, some types (for example, function objects) support only a degenerate
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	169 notion of comparison where any two objects of that type are unequal. The ``<``,
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	170 ``<=``, ``>`` and ``>=`` operators will raise a :exc:`TypeError` exception when
59563 f65977dcf21a Issue #7845: Make 1j.__le__(2j) return NotImplemented rather than raising TypeError. Mark Dickinson <dickinsm@gmail.com> parents: 58228 diff changeset	171 comparing a complex number with another built-in numeric type, when the objects
f65977dcf21a Issue #7845: Make 1j.__le__(2j) return NotImplemented rather than raising TypeError. Mark Dickinson <dickinsm@gmail.com> parents: 58228 diff changeset	172 are of different types that cannot be compared, or in other cases where there is
f65977dcf21a Issue #7845: Make 1j.__le__(2j) return NotImplemented rather than raising TypeError. Mark Dickinson <dickinsm@gmail.com> parents: 58228 diff changeset	173 no defined ordering.
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	174
50514 c3d3b760d8bf Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50323 diff changeset	175 .. index::
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	176 single: __eq__() (instance method)
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	177 single: __ne__() (instance method)
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	178 single: __lt__() (instance method)
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	179 single: __le__() (instance method)
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	180 single: __gt__() (instance method)
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	181 single: __ge__() (instance method)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182
49285 b3c29da934f5 Remove references to __cmp__. Georg Brandl <georg@python.org> parents: 49178 diff changeset	183 Non-identical instances of a class normally compare as non-equal unless the
b3c29da934f5 Remove references to __cmp__. Georg Brandl <georg@python.org> parents: 49178 diff changeset	184 class defines the :meth:`__eq__` method.
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	185
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	186 Instances of a class cannot be ordered with respect to other instances of the
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	187 same class, or other types of object, unless the class defines enough of the
49285 b3c29da934f5 Remove references to __cmp__. Georg Brandl <georg@python.org> parents: 49178 diff changeset	188 methods :meth:`__lt__`, :meth:`__le__`, :meth:`__gt__`, and :meth:`__ge__` (in
b3c29da934f5 Remove references to __cmp__. Georg Brandl <georg@python.org> parents: 49178 diff changeset	189 general, :meth:`__lt__` and :meth:`__eq__` are sufficient, if you want the
b3c29da934f5 Remove references to __cmp__. Georg Brandl <georg@python.org> parents: 49178 diff changeset	190 conventional meanings of the comparison operators).
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	191
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	192 The behavior of the :keyword:`is` and :keyword:`is not` operators cannot be
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	193 customized; also they can be applied to any two objects and never raise an
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	194 exception.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 operator: in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 operator: not in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199
67619 9076e4220fa4 Fix a few doc errors, mostly undefined keywords. Georg Brandl <georg@python.org> parents: 67461 diff changeset	200 Two more operations with the same syntactic priority, :keyword:`in` and
9076e4220fa4 Fix a few doc errors, mostly undefined keywords. Georg Brandl <georg@python.org> parents: 67461 diff changeset	201 :keyword:`not in`, are supported only by sequence types (below).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 .. _typesnumeric:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	206 Numeric Types --- :class:`int`, :class:`float`, :class:`complex`
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	207 ================================================================
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 object: numeric
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211 object: Boolean
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 object: integer
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 object: floating point
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 object: complex number
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215 pair: C; language
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216
48391 913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	217 There are three distinct numeric types: :dfn:`integers`, :dfn:`floating
913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	218 point numbers`, and :dfn:`complex numbers`. In addition, Booleans are a
913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	219 subtype of integers. Integers have unlimited precision. Floating point
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65049 diff changeset	220 numbers are usually implemented using :c:type:`double` in C; information
63747 95fd4fc27b9b Merged revisions 83732 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62992 diff changeset	221 about the precision and internal representation of floating point
95fd4fc27b9b Merged revisions 83732 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62992 diff changeset	222 numbers for the machine on which your program is running is available
95fd4fc27b9b Merged revisions 83732 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62992 diff changeset	223 in :data:`sys.float_info`. Complex numbers have a real and imaginary
95fd4fc27b9b Merged revisions 83732 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62992 diff changeset	224 part, which are each a floating point number. To extract these parts
95fd4fc27b9b Merged revisions 83732 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62992 diff changeset	225 from a complex number z, use ``z.real`` and ``z.imag``. (The standard
95fd4fc27b9b Merged revisions 83732 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62992 diff changeset	226 library includes additional numeric types, :mod:`fractions` that hold
95fd4fc27b9b Merged revisions 83732 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62992 diff changeset	227 rationals, and :mod:`decimal` that hold floating-point numbers with
95fd4fc27b9b Merged revisions 83732 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 62992 diff changeset	228 user-definable precision.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231 pair: numeric; literals
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 pair: integer; literals
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 pair: floating point; literals
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 pair: complex number; literals
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 pair: hexadecimal; literals
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 pair: octal; literals
43453 a1ca4ea41e7e Get the doc to build. Neal Norwitz <nnorwitz@gmail.com> parents: 43450 diff changeset	237 pair: binary; literals
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 Numbers are created by numeric literals or as the result of built-in functions
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	240 and operators. Unadorned integer literals (including hex, octal and binary
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	241 numbers) yield integers. Numeric literals containing a decimal point or an
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	242 exponent sign yield floating point numbers. Appending ``'j'`` or ``'J'`` to a
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	243 numeric literal yields an imaginary number (a complex number with a zero real
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	244 part) which you can add to an integer or float to get a complex number with real
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	245 and imaginary parts.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248 single: arithmetic
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249 builtin: int
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 builtin: float
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 builtin: complex
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	252 operator: +
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	253 operator: -
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	254 operator: *
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	255 operator: /
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	256 operator: //
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	257 operator: %
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	258 operator: **
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 Python fully supports mixed arithmetic: when a binary arithmetic operator has
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261 operands of different numeric types, the operand with the "narrower" type is
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	262 widened to that of the other, where integer is narrower than floating point,
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	263 which is narrower than complex. Comparisons between numbers of mixed type use
71870 16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	264 the same rule. [2]_ The constructors :func:`int`, :func:`float`, and
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	265 :func:`complex` can be used to produce numbers of a specific type.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267 All numeric types (except complex) support the following operations, sorted by
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268 ascending priority (operations in the same box have the same priority; all
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 numeric operations have a higher priority than comparison operations):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270
68852 6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	271 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	272 \| Operation \| Result \| Notes \| Full documentation \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	273 +=====================+=================================+=========+====================+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	274 \| ``x + y`` \| sum of x and y \| \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	275 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	276 \| ``x - y`` \| difference of x and y \| \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	277 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	278 \| ``x * y`` \| product of x and y \| \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	279 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	280 \| ``x / y`` \| quotient of x and y \| \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	281 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	282 \| ``x // y`` \| floored quotient of x and \| \(1) \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	283 \| \| y \| \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	284 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	285 \| ``x % y`` \| remainder of ``x / y`` \| \(2) \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	286 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	287 \| ``-x`` \| x negated \| \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	288 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	289 \| ``+x`` \| x unchanged \| \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	290 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	291 \| ``abs(x)`` \| absolute value or magnitude of \| \| :func:`abs` \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	292 \| \| x \| \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	293 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	294 \| ``int(x)`` \| x converted to integer \| \(3)\(6)\| :func:`int` \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	295 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	296 \| ``float(x)`` \| x converted to floating point \| \(4)\(6)\| :func:`float` \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	297 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	298 \| ``complex(re, im)`` \| a complex number with real part \| \(6) \| :func:`complex` \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	299 \| \| re, imaginary part im. \| \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	300 \| \| im defaults to zero. \| \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	301 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	302 \| ``c.conjugate()`` \| conjugate of the complex number \| \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	303 \| \| c \| \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	304 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	305 \| ``divmod(x, y)`` \| the pair ``(x // y, x % y)`` \| \(2) \| :func:`divmod` \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	306 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	307 \| ``pow(x, y)`` \| x to the power y \| \(5) \| :func:`pow` \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	308 +---------------------+---------------------------------+---------+--------------------+
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	309 \| ``x ** y`` \| x to the power y \| \(5) \| \|
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	310 +---------------------+---------------------------------+---------+--------------------+
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 triple: operations on; numeric; types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314 single: conjugate() (complex number method)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316 Notes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 (1)
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	319 Also referred to as integer division. The resultant value is a whole
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	320 integer, though the result's type is not necessarily int. The result is
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	321 always rounded towards minus infinity: ``1//2`` is ``0``, ``(-1)//2`` is
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	322 ``-1``, ``1//(-2)`` is ``-1``, and ``(-1)//(-2)`` is ``0``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 (2)
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	325 Not for complex numbers. Instead convert to floats using :func:`abs` if
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	326 appropriate.
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	327
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	328 (3)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330 module: math
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 single: floor() (in module math)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332 single: ceil() (in module math)
50645 5f292debd24c Merged revisions 68288-68291,68325-68326,68338,68388,68393,68423 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50573 diff changeset	333 single: trunc() (in module math)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 pair: numeric; conversions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 pair: C; language
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336
44052 e6ca92b18cf4 Remove mentions of "long integer" in the docs. Georg Brandl <georg@python.org> parents: 44039 diff changeset	337 Conversion from floating point to integer may round or truncate
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 as in C; see functions :func:`floor` and :func:`ceil` in the :mod:`math` module
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339 for well-defined conversions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340
44539 fa250a58099f Use consistent note numbers. Georg Brandl <georg@python.org> parents: 44536 diff changeset	341 (4)
50514 c3d3b760d8bf Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50323 diff changeset	342 float also accepts the strings "nan" and "inf" with an optional prefix "+"
44349 4dc01402d78a Merged revisions 59541-59561 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44329 diff changeset	343 or "-" for Not a Number (NaN) and positive or negative infinity.
44536 ac7deb1c1d3c Merged revisions 59774-59783 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	344
44539 fa250a58099f Use consistent note numbers. Georg Brandl <georg@python.org> parents: 44536 diff changeset	345 (5)
44536 ac7deb1c1d3c Merged revisions 59774-59783 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	346 Python defines ``pow(0, 0)`` and ``0 ** 0`` to be ``1``, as is common for
ac7deb1c1d3c Merged revisions 59774-59783 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	347 programming languages.
ac7deb1c1d3c Merged revisions 59774-59783 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44535 diff changeset	348
68852 6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	349 (6)
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	350 The numeric literals accepted include the digits ``0`` to ``9`` or any
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	351 Unicode equivalent (code points with the ``Nd`` property).
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	352
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	353 See http://www.unicode.org/Public/6.0.0/ucd/extracted/DerivedNumericType.txt
6853b480e388 Issue #10610: Document that int(), float(), and complex() accept numeric literals with the Nd property. Raymond Hettinger <python@rcn.com> parents: 68286 diff changeset	354 for a complete list of code points with the ``Nd`` property.
50514 c3d3b760d8bf Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50323 diff changeset	355
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44349 diff changeset	356
69749 dc65d1b99dff note abcs of int and float (closes #11977) Benjamin Peterson <benjamin@python.org> parents: 68852 diff changeset	357 All :class:`numbers.Real` types (:class:`int` and :class:`float`) also include
dc65d1b99dff note abcs of int and float (closes #11977) Benjamin Peterson <benjamin@python.org> parents: 68852 diff changeset	358 the following operations:
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44500 diff changeset	359
50885 9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	360 +--------------------+------------------------------------+--------+
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	361 \| Operation \| Result \| Notes \|
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	362 +====================+====================================+========+
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	363 \| ``math.trunc(x)`` \| x truncated to Integral \| \|
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	364 +--------------------+------------------------------------+--------+
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	365 \| ``round(x[, n])`` \| x rounded to n digits, \| \|
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	366 \| \| rounding half to even. If n is \| \|
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	367 \| \| omitted, it defaults to 0. \| \|
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	368 +--------------------+------------------------------------+--------+
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	369 \| ``math.floor(x)`` \| the greatest integral float <= x \| \|
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	370 +--------------------+------------------------------------+--------+
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	371 \| ``math.ceil(x)`` \| the least integral float >= x \| \|
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	372 +--------------------+------------------------------------+--------+
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44500 diff changeset	373
48391 913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	374 For additional numeric operations see the :mod:`math` and :mod:`cmath`
913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	375 modules.
913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	376
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44349 diff changeset	377 .. XXXJH exceptions: overflow (when? what operations?) zerodivision
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380 .. _bitstring-ops:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381
74616 3e55733fc534 say bitwise (because I have no idea what a bit-string is) Benjamin Peterson <benjamin@python.org> parents: 74582 diff changeset	382 Bitwise Operations on Integer Types
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 --------------------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	385 .. index::
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	386 triple: operations on; integer; types
74616 3e55733fc534 say bitwise (because I have no idea what a bit-string is) Benjamin Peterson <benjamin@python.org> parents: 74582 diff changeset	387 pair: bitwise; operations
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	388 pair: shifting; operations
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	389 pair: masking; operations
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	390 operator: ^
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	391 operator: &
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	392 operator: <<
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	393 operator: >>
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394
74617 2790c3ff475b kill extra word Benjamin Peterson <benjamin@python.org> parents: 74616 diff changeset	395 Bitwise operations only make sense for integers. Negative numbers are treated
2790c3ff475b kill extra word Benjamin Peterson <benjamin@python.org> parents: 74616 diff changeset	396 as their 2's complement value (this assumes a sufficiently large number of bits
2790c3ff475b kill extra word Benjamin Peterson <benjamin@python.org> parents: 74616 diff changeset	397 that no overflow occurs during the operation).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44500 diff changeset	399 The priorities of the binary bitwise operations are all lower than the numeric
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 operations and higher than the comparisons; the unary operation ``~`` has the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401 same priority as the other unary numeric operations (``+`` and ``-``).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402
74616 3e55733fc534 say bitwise (because I have no idea what a bit-string is) Benjamin Peterson <benjamin@python.org> parents: 74582 diff changeset	403 This table lists the bitwise operations sorted in ascending priority
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 (operations in the same box have the same priority):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 +------------+--------------------------------+----------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 \| Operation \| Result \| Notes \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 +============+================================+==========+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409 \| ``x \| y`` \| bitwise :dfn:`or` of x and \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 \| \| y \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 +------------+--------------------------------+----------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 \| ``x ^ y`` \| bitwise :dfn:`exclusive or` of \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 \| \| x and y \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 +------------+--------------------------------+----------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415 \| ``x & y`` \| bitwise :dfn:`and` of x and \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 \| \| y \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 +------------+--------------------------------+----------+
44568 305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44556 diff changeset	418 \| ``x << n`` \| x shifted left by n bits \| (1)(2) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419 +------------+--------------------------------+----------+
44568 305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44556 diff changeset	420 \| ``x >> n`` \| x shifted right by n bits \| (1)(3) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421 +------------+--------------------------------+----------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422 \| ``~x`` \| the bits of x inverted \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423 +------------+--------------------------------+----------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425 Notes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427 (1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 Negative shift counts are illegal and cause a :exc:`ValueError` to be raised.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430 (2)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 A left shift by n bits is equivalent to multiplication by ``pow(2, n)``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432 without overflow check.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434 (3)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435 A right shift by n bits is equivalent to division by ``pow(2, n)`` without
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	436 overflow check.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	437
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	438
50207 92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	439 Additional Methods on Integer Types
92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	440 -----------------------------------
92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	441
69757 22fb7ff4e6d9 Fix spelling. Raymond Hettinger <python@rcn.com> parents: 69749 diff changeset	442 The int type implements the :class:`numbers.Integral` :term:`abstract base
69761 4dabb605c50c Add missing colon Éric Araujo <merwok@netwok.org> parents: 69757 diff changeset	443 class`. In addition, it provides one more method:
69749 dc65d1b99dff note abcs of int and float (closes #11977) Benjamin Peterson <benjamin@python.org> parents: 68852 diff changeset	444
50207 92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	445 .. method:: int.bit_length()
92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	446
50223 0db907a70723 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50207 diff changeset	447 Return the number of bits necessary to represent an integer in binary,
0db907a70723 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50207 diff changeset	448 excluding the sign and leading zeros::
0db907a70723 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50207 diff changeset	449
0db907a70723 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50207 diff changeset	450 >>> n = -37
50207 92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	451 >>> bin(n)
50223 0db907a70723 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50207 diff changeset	452 '-0b100101'
50207 92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	453 >>> n.bit_length()
92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	454 6
50223 0db907a70723 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50207 diff changeset	455
0db907a70723 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50207 diff changeset	456 More precisely, if ``x`` is nonzero, then ``x.bit_length()`` is the
0db907a70723 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50207 diff changeset	457 unique positive integer ``k`` such that ``2(k-1) <= abs(x) < 2k``.
0db907a70723 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50207 diff changeset	458 Equivalently, when ``abs(x)`` is small enough to have a correctly
0db907a70723 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50207 diff changeset	459 rounded logarithm, then ``k = 1 + int(log(abs(x), 2))``.
0db907a70723 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50207 diff changeset	460 If ``x`` is zero, then ``x.bit_length()`` returns ``0``.
50207 92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	461
92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	462 Equivalent to::
92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	463
92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	464 def bit_length(self):
62433 0afd760e7c76 Merged revisions 82146 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 61042 diff changeset	465 s = bin(self) # binary representation: bin(-37) --> '-0b100101'
50223 0db907a70723 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50207 diff changeset	466 s = s.lstrip('-0b') # remove leading zeros and minus sign
0db907a70723 Fix-up and clean-up docs for int.bit_length(). Raymond Hettinger <python@rcn.com> parents: 50207 diff changeset	467 return len(s) # len('100101') --> 6
50207 92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	468
92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	469 .. versionadded:: 3.1
92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	470
64112 990a766ff983 Consistency check for versionadded/changed directives. Georg Brandl <georg@python.org> parents: 64009 diff changeset	471 .. method:: int.to_bytes(length, byteorder, \*, signed=False)
58223 f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	472
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	473 Return an array of bytes representing an integer.
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	474
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	475 >>> (1024).to_bytes(2, byteorder='big')
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	476 b'\x04\x00'
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	477 >>> (1024).to_bytes(10, byteorder='big')
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	478 b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00'
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	479 >>> (-1024).to_bytes(10, byteorder='big', signed=True)
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	480 b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00'
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	481 >>> x = 1000
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	482 >>> x.to_bytes((x.bit_length() // 8) + 1, byteorder='little')
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	483 b'\xe8\x03'
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	484
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	485 The integer is represented using length bytes. An :exc:`OverflowError`
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	486 is raised if the integer is not representable with the given number of
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	487 bytes.
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	488
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	489 The byteorder argument determines the byte order used to represent the
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	490 integer. If byteorder is ``"big"``, the most significant byte is at the
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	491 beginning of the byte array. If byteorder is ``"little"``, the most
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	492 significant byte is at the end of the byte array. To request the native
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	493 byte order of the host system, use :data:`sys.byteorder` as the byte order
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	494 value.
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	495
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	496 The signed argument determines whether two's complement is used to
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	497 represent the integer. If signed is ``False`` and a negative integer is
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	498 given, an :exc:`OverflowError` is raised. The default value for signed
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	499 is ``False``.
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	500
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	501 .. versionadded:: 3.2
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	502
64112 990a766ff983 Consistency check for versionadded/changed directives. Georg Brandl <georg@python.org> parents: 64009 diff changeset	503 .. classmethod:: int.from_bytes(bytes, byteorder, \*, signed=False)
58223 f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	504
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	505 Return the integer represented by the given array of bytes.
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	506
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	507 >>> int.from_bytes(b'\x00\x10', byteorder='big')
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	508 16
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	509 >>> int.from_bytes(b'\x00\x10', byteorder='little')
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	510 4096
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	511 >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=True)
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	512 -1024
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	513 >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=False)
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	514 64512
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	515 >>> int.from_bytes([255, 0, 0], byteorder='big')
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	516 16711680
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	517
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	518 The argument bytes must either support the buffer protocol or be an
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	519 iterable producing bytes. :class:`bytes` and :class:`bytearray` are
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	520 examples of built-in objects that support the buffer protocol.
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	521
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	522 The byteorder argument determines the byte order used to represent the
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	523 integer. If byteorder is ``"big"``, the most significant byte is at the
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	524 beginning of the byte array. If byteorder is ``"little"``, the most
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	525 significant byte is at the end of the byte array. To request the native
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	526 byte order of the host system, use :data:`sys.byteorder` as the byte order
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	527 value.
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	528
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	529 The signed argument indicates whether two's complement is used to
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	530 represent the integer.
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	531
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	532 .. versionadded:: 3.2
f9c0c411f80c Issue #1023290: Added API for the conversion of longs to bytes and vice-versa. Alexandre Vassalotti <alexandre@peadrop.com> parents: 58165 diff changeset	533
50207 92e21652f2f4 Forward merge of r67822 to py3k: add bit_length method to int. Mark Dickinson <dickinsm@gmail.com> parents: 50540 diff changeset	534
48497 2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	535 Additional Methods on Float
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	536 ---------------------------
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	537
69749 dc65d1b99dff note abcs of int and float (closes #11977) Benjamin Peterson <benjamin@python.org> parents: 68852 diff changeset	538 The float type implements the :class:`numbers.Real` :term:`abstract base
dc65d1b99dff note abcs of int and float (closes #11977) Benjamin Peterson <benjamin@python.org> parents: 68852 diff changeset	539 class`. float also has the following additional methods.
49178 8f886acaa142 Merged revisions 66394,66404,66412,66414,66424-66436 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49136 diff changeset	540
8f886acaa142 Merged revisions 66394,66404,66412,66414,66424-66436 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49136 diff changeset	541 .. method:: float.as_integer_ratio()
8f886acaa142 Merged revisions 66394,66404,66412,66414,66424-66436 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49136 diff changeset	542
66059 c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	543 Return a pair of integers whose ratio is exactly equal to the
c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	544 original float and with a positive denominator. Raises
c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	545 :exc:`OverflowError` on infinities and a :exc:`ValueError` on
c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	546 NaNs.
c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	547
c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	548 .. method:: float.is_integer()
c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	549
c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	550 Return ``True`` if the float instance is finite with integral
c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	551 value, and ``False`` otherwise::
c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	552
c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	553 >>> (-2.0).is_integer()
c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	554 True
c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	555 >>> (3.2).is_integer()
c08f7d6a0231 Merged revisions 86293 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 65121 diff changeset	556 False
50514 c3d3b760d8bf Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50323 diff changeset	557
49178 8f886acaa142 Merged revisions 66394,66404,66412,66414,66424-66436 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49136 diff changeset	558 Two methods support conversion to
48497 2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	559 and from hexadecimal strings. Since Python's floats are stored
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	560 internally as binary numbers, converting a float to or from a
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	561 decimal string usually involves a small rounding error. In
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	562 contrast, hexadecimal strings allow exact representation and
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	563 specification of floating-point numbers. This can be useful when
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	564 debugging, and in numerical work.
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	565
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	566
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	567 .. method:: float.hex()
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	568
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	569 Return a representation of a floating-point number as a hexadecimal
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	570 string. For finite floating-point numbers, this representation
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	571 will always include a leading ``0x`` and a trailing ``p`` and
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	572 exponent.
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	573
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	574
53094 4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	575 .. classmethod:: float.fromhex(s)
48497 2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	576
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	577 Class method to return the float represented by a hexadecimal
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	578 string s. The string s may have leading and trailing
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	579 whitespace.
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	580
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	581
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	582 Note that :meth:`float.hex` is an instance method, while
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	583 :meth:`float.fromhex` is a class method.
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	584
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	585 A hexadecimal string takes the form::
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	586
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	587 [sign] ['0x'] integer ['.' fraction] ['p' exponent]
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	588
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	589 where the optional ``sign`` may by either ``+`` or ``-``, ``integer``
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	590 and ``fraction`` are strings of hexadecimal digits, and ``exponent``
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	591 is a decimal integer with an optional leading sign. Case is not
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	592 significant, and there must be at least one hexadecimal digit in
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	593 either the integer or the fraction. This syntax is similar to the
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	594 syntax specified in section 6.4.4.2 of the C99 standard, and also to
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	595 the syntax used in Java 1.5 onwards. In particular, the output of
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	596 :meth:`float.hex` is usable as a hexadecimal floating-point literal in
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	597 C or Java code, and hexadecimal strings produced by C's ``%a`` format
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	598 character or Java's ``Double.toHexString`` are accepted by
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	599 :meth:`float.fromhex`.
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	600
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	601
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	602 Note that the exponent is written in decimal rather than hexadecimal,
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	603 and that it gives the power of 2 by which to multiply the coefficient.
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	604 For example, the hexadecimal string ``0x3.a7p10`` represents the
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	605 floating-point number ``(3 + 10./16 + 7./16*2) 2.0**10``, or
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	606 ``3740.0``::
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	607
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	608 >>> float.fromhex('0x3.a7p10')
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	609 3740.0
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	610
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	611
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	612 Applying the reverse conversion to ``3740.0`` gives a different
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	613 hexadecimal string representing the same number::
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	614
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	615 >>> float.hex(3740.0)
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	616 '0x1.d380000000000p+11'
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	617
2bb866d282ba Merged revisions 64974 via svnmerge from Mark Dickinson <dickinsm@gmail.com> parents: 48494 diff changeset	618
61873 0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	619 .. _numeric-hash:
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	620
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	621 Hashing of numeric types
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	622 ------------------------
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	623
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	624 For numbers ``x`` and ``y``, possibly of different types, it's a requirement
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	625 that ``hash(x) == hash(y)`` whenever ``x == y`` (see the :meth:`__hash__`
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	626 method documentation for more details). For ease of implementation and
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	627 efficiency across a variety of numeric types (including :class:`int`,
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	628 :class:`float`, :class:`decimal.Decimal` and :class:`fractions.Fraction`)
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	629 Python's hash for numeric types is based on a single mathematical function
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	630 that's defined for any rational number, and hence applies to all instances of
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	631 :class:`int` and :class:`fraction.Fraction`, and all finite instances of
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	632 :class:`float` and :class:`decimal.Decimal`. Essentially, this function is
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	633 given by reduction modulo ``P`` for a fixed prime ``P``. The value of ``P`` is
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	634 made available to Python as the :attr:`modulus` attribute of
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	635 :data:`sys.hash_info`.
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	636
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	637 .. impl-detail::
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	638
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	639 Currently, the prime used is ``P = 2**31 - 1`` on machines with 32-bit C
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	640 longs and ``P = 2**61 - 1`` on machines with 64-bit C longs.
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	641
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	642 Here are the rules in detail:
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	643
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	644 - If ``x = m / n`` is a nonnegative rational number and ``n`` is not divisible
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	645 by ``P``, define ``hash(x)`` as ``m * invmod(n, P) % P``, where ``invmod(n,
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	646 P)`` gives the inverse of ``n`` modulo ``P``.
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	647
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	648 - If ``x = m / n`` is a nonnegative rational number and ``n`` is
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	649 divisible by ``P`` (but ``m`` is not) then ``n`` has no inverse
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	650 modulo ``P`` and the rule above doesn't apply; in this case define
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	651 ``hash(x)`` to be the constant value ``sys.hash_info.inf``.
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	652
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	653 - If ``x = m / n`` is a negative rational number define ``hash(x)``
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	654 as ``-hash(-x)``. If the resulting hash is ``-1``, replace it with
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	655 ``-2``.
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	656
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	657 - The particular values ``sys.hash_info.inf``, ``-sys.hash_info.inf``
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	658 and ``sys.hash_info.nan`` are used as hash values for positive
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	659 infinity, negative infinity, or nans (respectively). (All hashable
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	660 nans have the same hash value.)
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	661
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	662 - For a :class:`complex` number ``z``, the hash values of the real
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	663 and imaginary parts are combined by computing ``hash(z.real) +
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	664 sys.hash_info.imag * hash(z.imag)``, reduced modulo
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	665 ``2**sys.hash_info.width`` so that it lies in
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	666 ``range(-2(sys.hash_info.width - 1), 2(sys.hash_info.width -
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	667 1))``. Again, if the result is ``-1``, it's replaced with ``-2``.
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	668
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	669
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	670 To clarify the above rules, here's some example Python code,
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	671 equivalent to the builtin hash, for computing the hash of a rational
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	672 number, :class:`float`, or :class:`complex`::
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	673
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	674
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	675 import sys, math
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	676
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	677 def hash_fraction(m, n):
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	678 """Compute the hash of a rational number m / n.
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	679
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	680 Assumes m and n are integers, with n positive.
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	681 Equivalent to hash(fractions.Fraction(m, n)).
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	682
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	683 """
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	684 P = sys.hash_info.modulus
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	685 # Remove common factors of P. (Unnecessary if m and n already coprime.)
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	686 while m % P == n % P == 0:
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	687 m, n = m // P, n // P
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	688
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	689 if n % P == 0:
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	690 hash_ = sys.hash_info.inf
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	691 else:
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	692 # Fermat's Little Theorem: pow(n, P-1, P) is 1, so
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	693 # pow(n, P-2, P) gives the inverse of n modulo P.
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	694 hash_ = (abs(m) % P) * pow(n, P - 2, P) % P
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	695 if m < 0:
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	696 hash_ = -hash_
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	697 if hash_ == -1:
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	698 hash_ = -2
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	699 return hash_
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	700
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	701 def hash_float(x):
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	702 """Compute the hash of a float x."""
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	703
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	704 if math.isnan(x):
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	705 return sys.hash_info.nan
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	706 elif math.isinf(x):
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	707 return sys.hash_info.inf if x > 0 else -sys.hash_info.inf
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	708 else:
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	709 return hash_fraction(*x.as_integer_ratio())
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	710
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	711 def hash_complex(z):
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	712 """Compute the hash of a complex number z."""
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	713
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	714 hash_ = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	715 # do a signed reduction modulo 2**sys.hash_info.width
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	716 M = 2**(sys.hash_info.width - 1)
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	717 hash_ = (hash_ & (M - 1)) - (hash & M)
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	718 if hash_ == -1:
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	719 hash_ == -2
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	720 return hash_
0bc8ffe6ba9a Issue #8188: Introduce a new scheme for computing hashes of numbers Mark Dickinson <dickinsm@gmail.com> parents: 61037 diff changeset	721
48500 4f6edea4b558 Merged revisions 64982-64983,65004 via svnmerge from Georg Brandl <georg@python.org> parents: 48499 diff changeset	722 .. _typeiter:
4f6edea4b558 Merged revisions 64982-64983,65004 via svnmerge from Georg Brandl <georg@python.org> parents: 48499 diff changeset	723
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	724 Iterator Types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	725 ==============
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	726
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	727 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	728 single: iterator protocol
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	729 single: protocol; iterator
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	730 single: sequence; iteration
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731 single: container; iteration over
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	733 Python supports a concept of iteration over containers. This is implemented
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	734 using two distinct methods; these are used to allow user-defined classes to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	735 support iteration. Sequences, described below in more detail, always support
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	736 the iteration methods.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	737
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	738 One method needs to be defined for container objects to provide iteration
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	739 support:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	740
44587 fb5a6330f71b Merged revisions 59822-59841 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44568 diff changeset	741 .. XXX duplicated in reference/datamodel!
fb5a6330f71b Merged revisions 59822-59841 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44568 diff changeset	742
fb5a6330f71b Merged revisions 59822-59841 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44568 diff changeset	743 .. method:: container.__iter__()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	744
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	745 Return an iterator object. The object is required to support the iterator
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	746 protocol described below. If a container supports different types of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	747 iteration, additional methods can be provided to specifically request
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	748 iterators for those iteration types. (An example of an object supporting
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749 multiple forms of iteration would be a tree structure which supports both
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	750 breadth-first and depth-first traversal.) This method corresponds to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	751 :attr:`tp_iter` slot of the type structure for Python objects in the Python/C
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	752 API.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	753
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	754 The iterator objects themselves are required to support the following two
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	755 methods, which together form the :dfn:`iterator protocol`:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	756
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	757
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	758 .. method:: iterator.__iter__()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	759
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	760 Return the iterator object itself. This is required to allow both containers
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	761 and iterators to be used with the :keyword:`for` and :keyword:`in` statements.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	762 This method corresponds to the :attr:`tp_iter` slot of the type structure for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	763 Python objects in the Python/C API.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	764
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	765
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	766 .. method:: iterator.__next__()
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	767
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	768 Return the next item from the container. If there are no further items, raise
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	769 the :exc:`StopIteration` exception. This method corresponds to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	770 :attr:`tp_iternext` slot of the type structure for Python objects in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	771 Python/C API.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	772
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	773 Python defines several iterator objects to support iteration over general and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	774 specific sequence types, dictionaries, and other more specialized forms. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775 specific types are not important beyond their implementation of the iterator
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776 protocol.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	778 Once an iterator's :meth:`__next__` method raises :exc:`StopIteration`, it must
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	779 continue to do so on subsequent calls. Implementations that do not obey this
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	780 property are deemed broken.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781
54917 f94c09aa4444 Merged revisions 73623-73624 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 54820 diff changeset	782
f94c09aa4444 Merged revisions 73623-73624 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 54820 diff changeset	783 .. _generator-types:
f94c09aa4444 Merged revisions 73623-73624 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 54820 diff changeset	784
f94c09aa4444 Merged revisions 73623-73624 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 54820 diff changeset	785 Generator Types
f94c09aa4444 Merged revisions 73623-73624 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 54820 diff changeset	786 ---------------
f94c09aa4444 Merged revisions 73623-73624 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 54820 diff changeset	787
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	788 Python's :term:`generator`\s provide a convenient way to implement the iterator
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	789 protocol. If a container object's :meth:`__iter__` method is implemented as a
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	790 generator, it will automatically return an iterator object (technically, a
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	791 generator object) supplying the :meth:`__iter__` and :meth:`__next__` methods.
54917 f94c09aa4444 Merged revisions 73623-73624 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 54820 diff changeset	792 More information about generators can be found in :ref:`the documentation for
f94c09aa4444 Merged revisions 73623-73624 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 54820 diff changeset	793 the yield expression <yieldexpr>`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	794
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796 .. _typesseq:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797
43971 72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	798 Sequence Types --- :class:`str`, :class:`bytes`, :class:`bytearray`, :class:`list`, :class:`tuple`, :class:`range`
72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	799 ==================================================================================================================
72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	800
50860 44424957eadf #4983: clarify what "byte sequence" is. Georg Brandl <georg@python.org> parents: 50859 diff changeset	801 There are six sequence types: strings, byte sequences (:class:`bytes` objects),
50885 9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	802 byte arrays (:class:`bytearray` objects), lists, tuples, and range objects. For
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	803 other containers see the built in :class:`dict` and :class:`set` classes, and
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	804 the :mod:`collections` module.
9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	805
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	806
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	808 object: sequence
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809 object: string
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	810 object: bytes
50860 44424957eadf #4983: clarify what "byte sequence" is. Georg Brandl <georg@python.org> parents: 50859 diff changeset	811 object: bytearray
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	812 object: tuple
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813 object: list
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	814 object: range
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815
43646 cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	816 Strings contain Unicode characters. Their literals are written in single or
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	817 double quotes: ``'xyzzy'``, ``"frobozz"``. See :ref:`strings` for more about
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	818 string literals. In addition to the functionality described here, there are
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	819 also string-specific methods described in the :ref:`string-methods` section.
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	820
43971 72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	821 Bytes and bytearray objects contain single bytes -- the former is immutable
76896 e0dcd732055f Issue #14793: fix grammar in bytes object paragraph; patch by Tshepang Lekhonkhobe Sandro Tosi <sandro.tosi@gmail.com> parents: 76856 diff changeset	822 while the latter is a mutable sequence.
e0dcd732055f Issue #14793: fix grammar in bytes object paragraph; patch by Tshepang Lekhonkhobe Sandro Tosi <sandro.tosi@gmail.com> parents: 76856 diff changeset	823 Bytes objects can be constructed by using the
48398 7e299ab35d95 #3220: improve bytes docs a bit. Georg Brandl <georg@python.org> parents: 48391 diff changeset	824 constructor, :func:`bytes`, and from literals; use a ``b`` prefix with normal
7e299ab35d95 #3220: improve bytes docs a bit. Georg Brandl <georg@python.org> parents: 48391 diff changeset	825 string syntax: ``b'xyzzy'``. To construct byte arrays, use the
7e299ab35d95 #3220: improve bytes docs a bit. Georg Brandl <georg@python.org> parents: 48391 diff changeset	826 :func:`bytearray` function.
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	827
65923 f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	828 While string objects are sequences of characters (represented by strings of
f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	829 length 1), bytes and bytearray objects are sequences of integers (between 0
f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	830 and 255), representing the ASCII value of single bytes. That means that for
f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	831 a bytes or bytearray object b, ``b[0]`` will be an integer, while
f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	832 ``b[0:1]`` will be a bytes or bytearray object of length 1. The
f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	833 representation of bytes objects uses the literal format (``b'...'``) since it
f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	834 is generally more useful than e.g. ``bytes([50, 19, 100])``. You can always
f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	835 convert a bytes object into a list of integers using ``list(b)``.
f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	836
f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	837 Also, while in previous Python versions, byte strings and Unicode strings
f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	838 could be exchanged for each other rather freely (barring encoding issues),
f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	839 strings and bytes are now completely separate concepts. There's no implicit
f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	840 en-/decoding if you pass an object of the wrong type. A string always
f29f62c357e1 Put warning block in the main flow of text. Raymond Hettinger <python@rcn.com> parents: 65469 diff changeset	841 compares unequal to a bytes or bytearray object.
43173 bf3c94213d5d Add a warning text about mixing bytes and strings. Georg Brandl <georg@python.org> parents: 43157 diff changeset	842
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	843 Lists are constructed with square brackets, separating items with commas: ``[a,
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	844 b, c]``. Tuples are constructed by the comma operator (not within square
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	845 brackets), with or without enclosing parentheses, but an empty tuple must have
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	846 the enclosing parentheses, such as ``a, b, c`` or ``()``. A single item tuple
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	847 must have a trailing comma, such as ``(d,)``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	848
43971 72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	849 Objects of type range are created using the :func:`range` function. They don't
66994 3a2953e21f78 Issue2690: Update docs to reflect the change made by issue2690. Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 66853 diff changeset	850 support concatenation or repetition, and using :func:`min` or :func:`max` on
3a2953e21f78 Issue2690: Update docs to reflect the change made by issue2690. Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 66853 diff changeset	851 them is inefficient.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	852
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	853 Most sequence types support the following operations. The ``in`` and ``not in``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	854 operations have the same priorities as the comparison operations. The ``+`` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	855 ``*`` operations have the same priority as the corresponding numeric operations.
71870 16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	856 [3]_ Additional methods are provided for :ref:`typesseq-mutable`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	857
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	858 This table lists the sequence operations sorted in ascending priority
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	859 (operations in the same box have the same priority). In the table, s and t
66365 7b14f1ff602b Issue 3292: Fixup to the Sequence docs. Raymond Hettinger <python@rcn.com> parents: 66337 diff changeset	860 are sequences of the same type; n, i, j and k are integers.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	861
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	862 +------------------+--------------------------------+----------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	863 \| Operation \| Result \| Notes \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	864 +==================+================================+==========+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	865 \| ``x in s`` \| ``True`` if an item of s is \| \(1) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	866 \| \| equal to x, else ``False`` \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	867 +------------------+--------------------------------+----------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	868 \| ``x not in s`` \| ``False`` if an item of s is \| \(1) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	869 \| \| equal to x, else ``True`` \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	870 +------------------+--------------------------------+----------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	871 \| ``s + t`` \| the concatenation of s and \| \(6) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	872 \| \| t \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	873 +------------------+--------------------------------+----------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	874 \| ``s * n, n * s`` \| n shallow copies of s \| \(2) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	875 \| \| concatenated \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	876 +------------------+--------------------------------+----------+
74582 a72ca8b23cdf #13816: fix two minor style issues. Thanks to Justin Wehnes for the patch. Georg Brandl <georg@python.org> parents: 74331 diff changeset	877 \| ``s[i]`` \| i\ th item of s, origin 0 \| \(3) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	878 +------------------+--------------------------------+----------+
44568 305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44556 diff changeset	879 \| ``s[i:j]`` \| slice of s from i to j \| (3)(4) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	880 +------------------+--------------------------------+----------+
44568 305d7d2ce047 Copied doc for reload() from trunk's function.rst to imp.rst Christian Heimes <christian@cheimes.de> parents: 44556 diff changeset	881 \| ``s[i:j:k]`` \| slice of s from i to j \| (3)(5) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	882 \| \| with step k \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	883 +------------------+--------------------------------+----------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	884 \| ``len(s)`` \| length of s \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	885 +------------------+--------------------------------+----------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	886 \| ``min(s)`` \| smallest item of s \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	887 +------------------+--------------------------------+----------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	888 \| ``max(s)`` \| largest item of s \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	889 +------------------+--------------------------------+----------+
66338 07cadc2c6438 Merged revisions 86625 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 66059 diff changeset	890 \| ``s.index(i)`` \| index of the first occurence \| \|
07cadc2c6438 Merged revisions 86625 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 66059 diff changeset	891 \| \| of i in s \| \|
07cadc2c6438 Merged revisions 86625 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 66059 diff changeset	892 +------------------+--------------------------------+----------+
07cadc2c6438 Merged revisions 86625 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 66059 diff changeset	893 \| ``s.count(i)`` \| total number of occurences of \| \|
07cadc2c6438 Merged revisions 86625 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 66059 diff changeset	894 \| \| i in s \| \|
07cadc2c6438 Merged revisions 86625 via svnmerge from Éric Araujo <merwok@netwok.org> parents: 66059 diff changeset	895 +------------------+--------------------------------+----------+
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	896
43646 cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	897 Sequence types also support comparisons. In particular, tuples and lists are
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	898 compared lexicographically by comparing corresponding elements. This means that
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	899 to compare equal, every element must compare equal and the two sequences must be
43646 cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	900 of the same type and have the same length. (For full details see
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	901 :ref:`comparisons` in the language reference.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	902
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	903 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	904 triple: operations on; sequence; types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	905 builtin: len
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	906 builtin: min
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	907 builtin: max
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	908 pair: concatenation; operation
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	909 pair: repetition; operation
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	910 pair: subscript; operation
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	911 pair: slice; operation
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	912 operator: in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	913 operator: not in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	914
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	915 Notes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	916
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	917 (1)
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	918 When s is a string object, the ``in`` and ``not in`` operations act like a
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	919 substring test.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	920
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	921 (2)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	922 Values of n less than ``0`` are treated as ``0`` (which yields an empty
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	923 sequence of the same type as s). Note also that the copies are shallow;
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	924 nested structures are not copied. This often haunts new Python programmers;
46034 0a485593ae1c Merged revisions 61724-61725,61731-61735,61737,61739,61741,61743-61744,61753,61761,61765-61767,61769,61773,61776-61778,61780-61783,61788,61793,61796,61807,61813 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45979 diff changeset	925 consider:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	926
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	927 >>> lists = [[]] * 3
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	928 >>> lists
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	929 [[], [], []]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	930 >>> lists[0].append(3)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	931 >>> lists
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	932 [[3], [3], [3]]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	933
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	934 What has happened is that ``[[]]`` is a one-element list containing an empty
46034 0a485593ae1c Merged revisions 61724-61725,61731-61735,61737,61739,61741,61743-61744,61753,61761,61765-61767,61769,61773,61776-61778,61780-61783,61788,61793,61796,61807,61813 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45979 diff changeset	935 list, so all three elements of ``[[]] * 3`` are (pointers to) this single empty
0a485593ae1c Merged revisions 61724-61725,61731-61735,61737,61739,61741,61743-61744,61753,61761,61765-61767,61769,61773,61776-61778,61780-61783,61788,61793,61796,61807,61813 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45979 diff changeset	936 list. Modifying any of the elements of ``lists`` modifies this single list.
0a485593ae1c Merged revisions 61724-61725,61731-61735,61737,61739,61741,61743-61744,61753,61761,61765-61767,61769,61773,61776-61778,61780-61783,61788,61793,61796,61807,61813 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45979 diff changeset	937 You can create a list of different lists this way:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	938
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	939 >>> lists = [[] for i in range(3)]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	940 >>> lists[0].append(3)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	941 >>> lists[1].append(5)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	942 >>> lists[2].append(7)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	943 >>> lists
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	944 [[3], [5], [7]]
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	945
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	946 (3)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	947 If i or j is negative, the index is relative to the end of the string:
43646 cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	948 ``len(s) + i`` or ``len(s) + j`` is substituted. But note that ``-0`` is
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	949 still ``0``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	950
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	951 (4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	952 The slice of s from i to j is defined as the sequence of items with index
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	953 k such that ``i <= k < j``. If i or j is greater than ``len(s)``, use
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	954 ``len(s)``. If i is omitted or ``None``, use ``0``. If j is omitted or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	955 ``None``, use ``len(s)``. If i is greater than or equal to j, the slice is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	956 empty.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	957
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	958 (5)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	959 The slice of s from i to j with step k is defined as the sequence of
44329 75c6bfd3b1f3 Merged revisions 59512-59540 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44115 diff changeset	960 items with index ``x = i + n*k`` such that ``0 <= n < (j-i)/k``. In other words,
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	961 the indices are ``i``, ``i+k``, ``i+2k``, ``i+3k`` and so on, stopping when
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	962 j is reached (but never including j). If i or j is greater than
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	963 ``len(s)``, use ``len(s)``. If i or j are omitted or ``None``, they become
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	964 "end" values (which end depends on the sign of k). Note, k cannot be zero.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	965 If k is ``None``, it is treated like ``1``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	966
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	967 (6)
73735 2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 73491 diff changeset	968 Concatenating immutable strings always results in a new object. This means
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 73491 diff changeset	969 that building up a string by repeated concatenation will have a quadratic
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 73491 diff changeset	970 runtime cost in the total string length. To get a linear runtime cost,
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 73491 diff changeset	971 you must switch to one of the alternatives below:
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 73491 diff changeset	972
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 73491 diff changeset	973 * if concatenating :class:`str` objects, you can build a list and use
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 73491 diff changeset	974 :meth:`str.join` at the end;
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 73491 diff changeset	975
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 73491 diff changeset	976 * if concatenating :class:`bytes` objects, you can similarly use
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 73491 diff changeset	977 :meth:`bytes.join`, or you can do in-place concatenation with a
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 73491 diff changeset	978 :class:`bytearray` object. :class:`bytearray` objects are mutable and
2d6f0e2fe034 Clarify concatenation behaviour of immutable strings, and remove explicit Antoine Pitrou <solipsis@pitrou.net> parents: 73491 diff changeset	979 have an efficient overallocation mechanism.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	980
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	981
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	982 .. _string-methods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	983
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	984 String Methods
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	985 --------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	986
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	987 .. index:: pair: string; methods
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	988
56099 1b7bdae02179 Merged revisions 74929 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55911 diff changeset	989 String objects support the methods listed below.
1b7bdae02179 Merged revisions 74929 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55911 diff changeset	990
1b7bdae02179 Merged revisions 74929 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55911 diff changeset	991 In addition, Python's strings support the sequence type methods described in the
1b7bdae02179 Merged revisions 74929 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55911 diff changeset	992 :ref:`typesseq` section. To output formatted strings, see the
43418 0c8fec76111c Merged revisions 58211-58220 via svnmerge from Thomas Wouters <thomas@python.org> parents: 43236 diff changeset	993 :ref:`string-formatting` section. Also, see the :mod:`re` module for string
0c8fec76111c Merged revisions 58211-58220 via svnmerge from Thomas Wouters <thomas@python.org> parents: 43236 diff changeset	994 functions based on regular expressions.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	995
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	996 .. method:: str.capitalize()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	997
62801 e1f48eb014c7 Merged revisions 82570 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 62784 diff changeset	998 Return a copy of the string with its first character capitalized and the
62826 86890446a47b Merged revisions 82601 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 62801 diff changeset	999 rest lowercased.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1000
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1001
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1002 .. method:: str.center(width[, fillchar])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1003
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1004 Return centered in a string of length width. Padding is done using the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1005 specified fillchar (default is a space).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1006
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1007
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1008 .. method:: str.count(sub[, start[, end]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1009
51868 e99b56da432a Merged revisions 69803-69805,69840,69901,69905,69907,69924,69927,69987 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 51579 diff changeset	1010 Return the number of non-overlapping occurrences of substring sub in the
e99b56da432a Merged revisions 69803-69805,69840,69901,69905,69907,69924,69927,69987 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 51579 diff changeset	1011 range [start, end]. Optional arguments start and end are
e99b56da432a Merged revisions 69803-69805,69840,69901,69905,69907,69924,69927,69987 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 51579 diff changeset	1012 interpreted as in slice notation.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1013
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1014
66069 8154db8a1593 Fix encode/decode method doc of str, bytes, bytearray types Victor Stinner <victor.stinner@haypocalc.com> parents: 66058 diff changeset	1015 .. method:: str.encode(encoding="utf-8", errors="strict")
8154db8a1593 Fix encode/decode method doc of str, bytes, bytearray types Victor Stinner <victor.stinner@haypocalc.com> parents: 66058 diff changeset	1016
8154db8a1593 Fix encode/decode method doc of str, bytes, bytearray types Victor Stinner <victor.stinner@haypocalc.com> parents: 66058 diff changeset	1017 Return an encoded version of the string as a bytes object. Default encoding
8154db8a1593 Fix encode/decode method doc of str, bytes, bytearray types Victor Stinner <victor.stinner@haypocalc.com> parents: 66058 diff changeset	1018 is ``'utf-8'``. errors may be given to set a different error handling scheme.
8154db8a1593 Fix encode/decode method doc of str, bytes, bytearray types Victor Stinner <victor.stinner@haypocalc.com> parents: 66058 diff changeset	1019 The default for errors is ``'strict'``, meaning that encoding errors raise
8154db8a1593 Fix encode/decode method doc of str, bytes, bytearray types Victor Stinner <victor.stinner@haypocalc.com> parents: 66058 diff changeset	1020 a :exc:`UnicodeError`. Other possible
53751 c2d107e07839 Add missing documentation for bytes.decode(). Georg Brandl <georg@python.org> parents: 53642 diff changeset	1021 values are ``'ignore'``, ``'replace'``, ``'xmlcharrefreplace'``,
c2d107e07839 Add missing documentation for bytes.decode(). Georg Brandl <georg@python.org> parents: 53642 diff changeset	1022 ``'backslashreplace'`` and any other name registered via
c2d107e07839 Add missing documentation for bytes.decode(). Georg Brandl <georg@python.org> parents: 53642 diff changeset	1023 :func:`codecs.register_error`, see section :ref:`codec-base-classes`. For a
c2d107e07839 Add missing documentation for bytes.decode(). Georg Brandl <georg@python.org> parents: 53642 diff changeset	1024 list of possible encodings, see section :ref:`standard-encodings`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1025
65117 2de8323bd4eb Merged revisions 84142 via svnmerge from Georg Brandl <georg@python.org> parents: 65111 diff changeset	1026 .. versionchanged:: 3.1
2de8323bd4eb Merged revisions 84142 via svnmerge from Georg Brandl <georg@python.org> parents: 65111 diff changeset	1027 Support for keyword arguments added.
2de8323bd4eb Merged revisions 84142 via svnmerge from Georg Brandl <georg@python.org> parents: 65111 diff changeset	1028
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1029
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1030 .. method:: str.endswith(suffix[, start[, end]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1031
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1032 Return ``True`` if the string ends with the specified suffix, otherwise return
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1033 ``False``. suffix can also be a tuple of suffixes to look for. With optional
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1034 start, test beginning at that position. With optional end, stop comparing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1035 at that position.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1036
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1037
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1038 .. method:: str.expandtabs([tabsize])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1039
73491 84f803fdc0d2 Issue #13365: correct an error in the documentation of str.expandtabs Eli Bendersky <eliben@gmail.com> parents: 73153 diff changeset	1040 Return a copy of the string where all tab characters are replaced by zero or
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1041 more spaces, depending on the current column and the given tab size. The
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1042 column number is reset to zero after each newline occurring in the string.
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1043 If tabsize is not given, a tab size of ``8`` characters is assumed. This
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1044 doesn't understand other non-printing characters or escape sequences.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1045
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1046
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1047 .. method:: str.find(sub[, start[, end]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1048
61042 b0f342ab5095 Merged revisions 80562 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 58031 diff changeset	1049 Return the lowest index in the string where substring sub is found, such
b0f342ab5095 Merged revisions 80562 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 58031 diff changeset	1050 that sub is contained in the slice ``s[start:end]``. Optional arguments
b0f342ab5095 Merged revisions 80562 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 58031 diff changeset	1051 start and end are interpreted as in slice notation. Return ``-1`` if
b0f342ab5095 Merged revisions 80562 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 58031 diff changeset	1052 sub is not found.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1053
69950 e4acbe2c8164 Add a note to the str.find doc to suggest the use of the "in" operator. Ezio Melotti <ezio.melotti@gmail.com> parents: 69761 diff changeset	1054 .. note::
e4acbe2c8164 Add a note to the str.find doc to suggest the use of the "in" operator. Ezio Melotti <ezio.melotti@gmail.com> parents: 69761 diff changeset	1055
e4acbe2c8164 Add a note to the str.find doc to suggest the use of the "in" operator. Ezio Melotti <ezio.melotti@gmail.com> parents: 69761 diff changeset	1056 The :meth:`~str.find` method should be used only if you need to know the
e4acbe2c8164 Add a note to the str.find doc to suggest the use of the "in" operator. Ezio Melotti <ezio.melotti@gmail.com> parents: 69761 diff changeset	1057 position of sub. To check if sub is a substring or not, use the
e4acbe2c8164 Add a note to the str.find doc to suggest the use of the "in" operator. Ezio Melotti <ezio.melotti@gmail.com> parents: 69761 diff changeset	1058 :keyword:`in` operator::
e4acbe2c8164 Add a note to the str.find doc to suggest the use of the "in" operator. Ezio Melotti <ezio.melotti@gmail.com> parents: 69761 diff changeset	1059
e4acbe2c8164 Add a note to the str.find doc to suggest the use of the "in" operator. Ezio Melotti <ezio.melotti@gmail.com> parents: 69761 diff changeset	1060 >>> 'Py' in 'Python'
e4acbe2c8164 Add a note to the str.find doc to suggest the use of the "in" operator. Ezio Melotti <ezio.melotti@gmail.com> parents: 69761 diff changeset	1061 True
e4acbe2c8164 Add a note to the str.find doc to suggest the use of the "in" operator. Ezio Melotti <ezio.melotti@gmail.com> parents: 69761 diff changeset	1062
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1063
51868 e99b56da432a Merged revisions 69803-69805,69840,69901,69905,69907,69924,69927,69987 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 51579 diff changeset	1064 .. method:: str.format(args, *kwargs)
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1065
59789 10bd1d0f62de Merged revisions 79168-79169 via svnmerge from Georg Brandl <georg@python.org> parents: 59563 diff changeset	1066 Perform a string formatting operation. The string on which this method is
10bd1d0f62de Merged revisions 79168-79169 via svnmerge from Georg Brandl <georg@python.org> parents: 59563 diff changeset	1067 called can contain literal text or replacement fields delimited by braces
10bd1d0f62de Merged revisions 79168-79169 via svnmerge from Georg Brandl <georg@python.org> parents: 59563 diff changeset	1068 ``{}``. Each replacement field contains either the numeric index of a
10bd1d0f62de Merged revisions 79168-79169 via svnmerge from Georg Brandl <georg@python.org> parents: 59563 diff changeset	1069 positional argument, or the name of a keyword argument. Returns a copy of
10bd1d0f62de Merged revisions 79168-79169 via svnmerge from Georg Brandl <georg@python.org> parents: 59563 diff changeset	1070 the string where each replacement field is replaced with the string value of
10bd1d0f62de Merged revisions 79168-79169 via svnmerge from Georg Brandl <georg@python.org> parents: 59563 diff changeset	1071 the corresponding argument.
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1072
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1073 >>> "The sum of 1 + 2 is {0}".format(1+2)
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1074 'The sum of 1 + 2 is 3'
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1075
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1076 See :ref:`formatstrings` for a description of the various formatting options
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1077 that can be specified in format strings.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1078
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1079
65940 05eed9f0ce01 Issue #6081: Add str.format_map. str.format_map(mapping) is similar to str.format(*mapping), except mapping does not get converted to a dict. Eric Smith <eric@trueblade.com>* parents: 65923 diff changeset	1080 .. method:: str.format_map(mapping)
05eed9f0ce01 Issue #6081: Add str.format_map. str.format_map(mapping) is similar to str.format(*mapping), except mapping does not get converted to a dict. Eric Smith <eric@trueblade.com>* parents: 65923 diff changeset	1081
66017 fc48375079a6 Fix typo from r86170. Éric Araujo <merwok@netwok.org> parents: 65940 diff changeset	1082 Similar to ``str.format(**mapping)``, except that ``mapping`` is
65940 05eed9f0ce01 Issue #6081: Add str.format_map. str.format_map(mapping) is similar to str.format(*mapping), except mapping does not get converted to a dict. Eric Smith <eric@trueblade.com>* parents: 65923 diff changeset	1083 used directly and not copied to a :class:`dict` . This is useful
66029 be5469808ce9 Added example for str.format_map(). Eric Smith <eric@trueblade.com> parents: 66017 diff changeset	1084 if for example ``mapping`` is a dict subclass:
be5469808ce9 Added example for str.format_map(). Eric Smith <eric@trueblade.com> parents: 66017 diff changeset	1085
be5469808ce9 Added example for str.format_map(). Eric Smith <eric@trueblade.com> parents: 66017 diff changeset	1086 >>> class Default(dict):
be5469808ce9 Added example for str.format_map(). Eric Smith <eric@trueblade.com> parents: 66017 diff changeset	1087 ... def __missing__(self, key):
be5469808ce9 Added example for str.format_map(). Eric Smith <eric@trueblade.com> parents: 66017 diff changeset	1088 ... return key
be5469808ce9 Added example for str.format_map(). Eric Smith <eric@trueblade.com> parents: 66017 diff changeset	1089 ...
be5469808ce9 Added example for str.format_map(). Eric Smith <eric@trueblade.com> parents: 66017 diff changeset	1090 >>> '{name} was born in {country}'.format_map(Default(name='Guido'))
be5469808ce9 Added example for str.format_map(). Eric Smith <eric@trueblade.com> parents: 66017 diff changeset	1091 'Guido was born in country'
be5469808ce9 Added example for str.format_map(). Eric Smith <eric@trueblade.com> parents: 66017 diff changeset	1092
be5469808ce9 Added example for str.format_map(). Eric Smith <eric@trueblade.com> parents: 66017 diff changeset	1093 .. versionadded:: 3.2
be5469808ce9 Added example for str.format_map(). Eric Smith <eric@trueblade.com> parents: 66017 diff changeset	1094
65940 05eed9f0ce01 Issue #6081: Add str.format_map. str.format_map(mapping) is similar to str.format(*mapping), except mapping does not get converted to a dict. Eric Smith <eric@trueblade.com>* parents: 65923 diff changeset	1095
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1096 .. method:: str.index(sub[, start[, end]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1097
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1098 Like :meth:`find`, but raise :exc:`ValueError` when the substring is not found.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1099
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1100
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1101 .. method:: str.isalnum()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1102
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1103 Return true if all characters in the string are alphanumeric and there is at
67090 4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1104 least one character, false otherwise. A character ``c`` is alphanumeric if one
4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1105 of the following returns ``True``: ``c.isalpha()``, ``c.isdecimal()``,
4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1106 ``c.isdigit()``, or ``c.isnumeric()``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1107
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1108
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1109 .. method:: str.isalpha()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1110
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1111 Return true if all characters in the string are alphabetic and there is at least
67090 4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1112 one character, false otherwise. Alphabetic characters are those characters defined
4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1113 in the Unicode character database as "Letter", i.e., those with general category
4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1114 property being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note that this is different
4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1115 from the "Alphabetic" property defined in the Unicode Standard.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1116
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1117
48391 913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	1118 .. method:: str.isdecimal()
913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	1119
913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	1120 Return true if all characters in the string are decimal
913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	1121 characters and there is at least one character, false
67090 4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1122 otherwise. Decimal characters are those from general category "Nd". This category
4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1123 includes digit characters, and all characters
72985 e19ccbbe70dd Remove duplication. Ezio Melotti <ezio.melotti@gmail.com> parents: 72189 diff changeset	1124 that can be used to form decimal-radix numbers, e.g. U+0660,
48391 913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	1125 ARABIC-INDIC DIGIT ZERO.
50514 c3d3b760d8bf Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50323 diff changeset	1126
48391 913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	1127
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1128 .. method:: str.isdigit()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1129
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1130 Return true if all characters in the string are digits and there is at least one
67090 4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1131 character, false otherwise. Digits include decimal characters and digits that need
4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1132 special handling, such as the compatibility superscript digits. Formally, a digit
4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1133 is a character that has the property value Numeric_Type=Digit or Numeric_Type=Decimal.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1134
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1135
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1136 .. method:: str.isidentifier()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1137
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1138 Return true if the string is a valid identifier according to the language
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1139 definition, section :ref:`identifiers`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1140
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1141
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1142 .. method:: str.islower()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1143
71870 16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	1144 Return true if all cased characters [4]_ in the string are lowercase and
16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	1145 there is at least one cased character, false otherwise.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1146
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1147
48391 913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	1148 .. method:: str.isnumeric()
913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	1149
913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	1150 Return true if all characters in the string are numeric
913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	1151 characters, and there is at least one character, false
913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	1152 otherwise. Numeric characters include digit characters, and all characters
913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	1153 that have the Unicode numeric value property, e.g. U+2155,
67090 4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1154 VULGAR FRACTION ONE FIFTH. Formally, numeric characters are those with the property
4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1155 value Numeric_Type=Digit, Numeric_Type=Decimal or Numeric_Type=Numeric.
48391 913aa274ed77 - No more 0L or similar. Mark Summerfield <list@qtrac.plus.com> parents: 47750 diff changeset	1156
50514 c3d3b760d8bf Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50323 diff changeset	1157
47611 da47e7e135ae #2630: Implement PEP 3138. Georg Brandl <georg@python.org> parents: 47562 diff changeset	1158 .. method:: str.isprintable()
da47e7e135ae #2630: Implement PEP 3138. Georg Brandl <georg@python.org> parents: 47562 diff changeset	1159
da47e7e135ae #2630: Implement PEP 3138. Georg Brandl <georg@python.org> parents: 47562 diff changeset	1160 Return true if all characters in the string are printable or the string is
da47e7e135ae #2630: Implement PEP 3138. Georg Brandl <georg@python.org> parents: 47562 diff changeset	1161 empty, false otherwise. Nonprintable characters are those characters defined
da47e7e135ae #2630: Implement PEP 3138. Georg Brandl <georg@python.org> parents: 47562 diff changeset	1162 in the Unicode character database as "Other" or "Separator", excepting the
da47e7e135ae #2630: Implement PEP 3138. Georg Brandl <georg@python.org> parents: 47562 diff changeset	1163 ASCII space (0x20) which is considered printable. (Note that printable
da47e7e135ae #2630: Implement PEP 3138. Georg Brandl <georg@python.org> parents: 47562 diff changeset	1164 characters in this context are those which should not be escaped when
da47e7e135ae #2630: Implement PEP 3138. Georg Brandl <georg@python.org> parents: 47562 diff changeset	1165 :func:`repr` is invoked on a string. It has no bearing on the handling of
da47e7e135ae #2630: Implement PEP 3138. Georg Brandl <georg@python.org> parents: 47562 diff changeset	1166 strings written to :data:`sys.stdout` or :data:`sys.stderr`.)
da47e7e135ae #2630: Implement PEP 3138. Georg Brandl <georg@python.org> parents: 47562 diff changeset	1167
da47e7e135ae #2630: Implement PEP 3138. Georg Brandl <georg@python.org> parents: 47562 diff changeset	1168
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1169 .. method:: str.isspace()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1170
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1171 Return true if there are only whitespace characters in the string and there is
67090 4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1172 at least one character, false otherwise. Whitespace characters are those
4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1173 characters defined in the Unicode character database as "Other" or "Separator"
4dc248ac264f Merged revisions 87443 via svnmerge from Alexander Belopolsky <alexander.belopolsky@gmail.com> parents: 66860 diff changeset	1174 and those with bidirectional property being one of "WS", "B", or "S".
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1175
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1176 .. method:: str.istitle()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1177
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1178 Return true if the string is a titlecased string and there is at least one
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1179 character, for example uppercase characters may only follow uncased characters
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1180 and lowercase characters only cased ones. Return false otherwise.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1181
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1182
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1183 .. method:: str.isupper()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1184
71870 16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	1185 Return true if all cased characters [4]_ in the string are uppercase and
16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	1186 there is at least one cased character, false otherwise.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1187
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1188
56894 b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56370 diff changeset	1189 .. method:: str.join(iterable)
b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56370 diff changeset	1190
b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56370 diff changeset	1191 Return a string which is the concatenation of the strings in the
b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56370 diff changeset	1192 :term:`iterable` iterable. A :exc:`TypeError` will be raised if there are
74331 3f2e5fd17b76 #13754 String returned if less than or equal to x 3 Terry Jan Reedy <tjreedy@udel.edu> parents: 73813 diff changeset	1193 any non-string values in iterable, including :class:`bytes` objects. The
56894 b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56370 diff changeset	1194 separator between elements is the string providing this method.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1195
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1196
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1197 .. method:: str.ljust(width[, fillchar])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1198
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1199 Return the string left justified in a string of length width. Padding is done
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1200 using the specified fillchar (default is a space). The original string is
74331 3f2e5fd17b76 #13754 String returned if less than or equal to x 3 Terry Jan Reedy <tjreedy@udel.edu> parents: 73813 diff changeset	1201 returned if width is less than or equal to ``len(s)``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1202
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1203
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1204 .. method:: str.lower()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1205
71870 16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	1206 Return a copy of the string with all the cased characters [4]_ converted to
16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	1207 lowercase.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1208
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1209
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1210 .. method:: str.lstrip([chars])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1211
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1212 Return a copy of the string with leading characters removed. The chars
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1213 argument is a string specifying the set of characters to be removed. If omitted
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1214 or ``None``, the chars argument defaults to removing whitespace. The chars
46034 0a485593ae1c Merged revisions 61724-61725,61731-61735,61737,61739,61741,61743-61744,61753,61761,61765-61767,61769,61773,61776-61778,61780-61783,61788,61793,61796,61807,61813 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45979 diff changeset	1215 argument is not a prefix; rather, all combinations of its values are stripped:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1216
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1217 >>> ' spacious '.lstrip()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1218 'spacious '
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1219 >>> 'www.example.com'.lstrip('cmowz.')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1220 'example.com'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1221
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1222
53094 4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1223 .. staticmethod:: str.maketrans(x[, y[, z]])
44039 12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1224
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1225 This static method returns a translation table usable for :meth:`str.translate`.
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1226
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1227 If there is only one argument, it must be a dictionary mapping Unicode
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1228 ordinals (integers) or characters (strings of length 1) to Unicode ordinals,
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1229 strings (of arbitrary lengths) or None. Character keys will then be
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1230 converted to ordinals.
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1231
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1232 If there are two arguments, they must be strings of equal length, and in the
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1233 resulting dictionary, each character in x will be mapped to the character at
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1234 the same position in y. If there is a third argument, it must be a string,
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1235 whose characters will be mapped to None in the result.
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1236
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1237
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1238 .. method:: str.partition(sep)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1239
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1240 Split the string at the first occurrence of sep, and return a 3-tuple
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1241 containing the part before the separator, the separator itself, and the part
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1242 after the separator. If the separator is not found, return a 3-tuple containing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1243 the string itself, followed by two empty strings.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1244
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1245
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1246 .. method:: str.replace(old, new[, count])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1247
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1248 Return a copy of the string with all occurrences of substring old replaced by
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1249 new. If the optional argument count is given, only the first count
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1250 occurrences are replaced.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1251
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1252
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1253 .. method:: str.rfind(sub[, start[, end]])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1254
61042 b0f342ab5095 Merged revisions 80562 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 58031 diff changeset	1255 Return the highest index in the string where substring sub is found, such
b0f342ab5095 Merged revisions 80562 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 58031 diff changeset	1256 that sub is contained within ``s[start:end]``. Optional arguments start
b0f342ab5095 Merged revisions 80562 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 58031 diff changeset	1257 and end are interpreted as in slice notation. Return ``-1`` on failure.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1258
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1259
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1260 .. method:: str.rindex(sub[, start[, end]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1261
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1262 Like :meth:`rfind` but raises :exc:`ValueError` when the substring sub is not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1263 found.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1264
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1265
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1266 .. method:: str.rjust(width[, fillchar])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1267
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1268 Return the string right justified in a string of length width. Padding is done
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1269 using the specified fillchar (default is a space). The original string is
74331 3f2e5fd17b76 #13754 String returned if less than or equal to x 3 Terry Jan Reedy <tjreedy@udel.edu> parents: 73813 diff changeset	1270 returned if width is less than or equal to ``len(s)``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1271
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1272
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1273 .. method:: str.rpartition(sep)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1274
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1275 Split the string at the last occurrence of sep, and return a 3-tuple
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1276 containing the part before the separator, the separator itself, and the part
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1277 after the separator. If the separator is not found, return a 3-tuple containing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1278 two empty strings, followed by the string itself.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1279
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1280
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1281 .. method:: str.rsplit([sep[, maxsplit]])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1282
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1283 Return a list of the words in the string, using sep as the delimiter string.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1284 If maxsplit is given, at most maxsplit splits are done, the rightmost
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1285 ones. If sep is not specified or ``None``, any whitespace string is a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1286 separator. Except for splitting from the right, :meth:`rsplit` behaves like
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1287 :meth:`split` which is described in detail below.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1288
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1289
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1290 .. method:: str.rstrip([chars])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1291
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1292 Return a copy of the string with trailing characters removed. The chars
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1293 argument is a string specifying the set of characters to be removed. If omitted
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1294 or ``None``, the chars argument defaults to removing whitespace. The chars
46034 0a485593ae1c Merged revisions 61724-61725,61731-61735,61737,61739,61741,61743-61744,61753,61761,61765-61767,61769,61773,61776-61778,61780-61783,61788,61793,61796,61807,61813 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45979 diff changeset	1295 argument is not a suffix; rather, all combinations of its values are stripped:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1296
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1297 >>> ' spacious '.rstrip()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1298 ' spacious'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1299 >>> 'mississippi'.rstrip('ipz')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1300 'mississ'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1301
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1302
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1303 .. method:: str.split([sep[, maxsplit]])
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1304
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1305 Return a list of the words in the string, using sep as the delimiter
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1306 string. If maxsplit is given, at most maxsplit splits are done (thus,
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1307 the list will have at most ``maxsplit+1`` elements). If maxsplit is not
76856 62659067f5b6 #14763: document default maxsplit value for str.split. Ezio Melotti <ezio.melotti@gmail.com> parents: 75293 diff changeset	1308 specified or ``-1``, then there is no limit on the number of splits
62659067f5b6 #14763: document default maxsplit value for str.split. Ezio Melotti <ezio.melotti@gmail.com> parents: 75293 diff changeset	1309 (all possible splits are made).
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1310
43756 317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	1311 If sep is given, consecutive delimiters are not grouped together and are
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1312 deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1313 ``['1', '', '2']``). The sep argument may consist of multiple characters
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1314 (for example, ``'1<>2<>3'.split('<>')`` returns ``['1', '2', '3']``).
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1315 Splitting an empty string with a specified separator returns ``['']``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1316
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1317 If sep is not specified or is ``None``, a different splitting algorithm is
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1318 applied: runs of consecutive whitespace are regarded as a single separator,
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1319 and the result will contain no empty strings at the start or end if the
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1320 string has leading or trailing whitespace. Consequently, splitting an empty
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1321 string or a string consisting of just whitespace with a ``None`` separator
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1322 returns ``[]``.
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1323
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1324 For example, ``' 1 2 3 '.split()`` returns ``['1', '2', '3']``, and
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1325 ``' 1 2 3 '.split(None, 1)`` returns ``['1', '2 3 ']``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1326
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1327
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1328 .. method:: str.splitlines([keepends])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1329
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1330 Return a list of the lines in the string, breaking at line boundaries. Line
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1331 breaks are not included in the resulting list unless keepends is given and
77288 24572015e24f #14957: clarify splitlines docs. R David Murray <rdmurray@bitdance.com> parents: 76896 diff changeset	1332 true. This method uses the universal newlines approach to splitting lines.
24572015e24f #14957: clarify splitlines docs. R David Murray <rdmurray@bitdance.com> parents: 76896 diff changeset	1333 Unlike :meth:`~str.split`, if the string ends with line boundary characters
24572015e24f #14957: clarify splitlines docs. R David Murray <rdmurray@bitdance.com> parents: 76896 diff changeset	1334 the returned list does ``not`` have an empty last element.
24572015e24f #14957: clarify splitlines docs. R David Murray <rdmurray@bitdance.com> parents: 76896 diff changeset	1335
24572015e24f #14957: clarify splitlines docs. R David Murray <rdmurray@bitdance.com> parents: 76896 diff changeset	1336 For example, ``'ab c\n\nde fg\rkl\r\n'.splitlines()`` returns
77297 4d9b3a58e208 #14957: fix doc typo. R David Murray <rdmurray@bitdance.com> parents: 77288 diff changeset	1337 ``['ab c', '', 'de fg', 'kl']``, while the same call with ``splitlines(True)``
77288 24572015e24f #14957: clarify splitlines docs. R David Murray <rdmurray@bitdance.com> parents: 76896 diff changeset	1338 returns ``['ab c\n', '\n, 'de fg\r', 'kl\r\n']``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1339
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1340
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1341 .. method:: str.startswith(prefix[, start[, end]])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1342
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1343 Return ``True`` if string starts with the prefix, otherwise return ``False``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1344 prefix can also be a tuple of prefixes to look for. With optional start,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1345 test string beginning at that position. With optional end, stop comparing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1346 string at that position.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1347
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1348
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1349 .. method:: str.strip([chars])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1350
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1351 Return a copy of the string with the leading and trailing characters removed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1352 The chars argument is a string specifying the set of characters to be removed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1353 If omitted or ``None``, the chars argument defaults to removing whitespace.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1354 The chars argument is not a prefix or suffix; rather, all combinations of its
46034 0a485593ae1c Merged revisions 61724-61725,61731-61735,61737,61739,61741,61743-61744,61753,61761,61765-61767,61769,61773,61776-61778,61780-61783,61788,61793,61796,61807,61813 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45979 diff changeset	1355 values are stripped:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1356
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1357 >>> ' spacious '.strip()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1358 'spacious'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1359 >>> 'www.example.com'.strip('cmowz.')
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1360 'example'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1361
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1362
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1363 .. method:: str.swapcase()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1364
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1365 Return a copy of the string with uppercase characters converted to lowercase and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1366 vice versa.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1367
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1368
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1369 .. method:: str.title()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1370
56291 19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1371 Return a titlecased version of the string where words start with an uppercase
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1372 character and the remaining characters are lowercase.
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1373
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1374 The algorithm uses a simple language-independent definition of a word as
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1375 groups of consecutive letters. The definition works in many contexts but
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1376 it means that apostrophes in contractions and possessives form word
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1377 boundaries, which may not be the desired result::
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1378
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1379 >>> "they're bill's friends from the UK".title()
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1380 "They'Re Bill'S Friends From The Uk"
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1381
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1382 A workaround for apostrophes can be constructed using regular expressions::
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1383
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1384 >>> import re
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1385 >>> def titlecase(s):
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1386 return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1387 lambda mo: mo.group(0)[0].upper() +
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1388 mo.group(0)[1:].lower(),
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1389 s)
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1390
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1391 >>> titlecase("they're bill's friends.")
19a4a623d8b7 Issue 7008: Better document str.title and show how to work around the apostrophe problem. Raymond Hettinger <python@rcn.com> parents: 55913 diff changeset	1392 "They're Bill's Friends."
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1393
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1394
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1395 .. method:: str.translate(map)
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1396
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1397 Return a copy of the s where all characters have been mapped through the
50323 8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1398 map which must be a dictionary of Unicode ordinals (integers) to Unicode
44039 12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1399 ordinals, strings or ``None``. Unmapped characters are left untouched.
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1400 Characters mapped to ``None`` are deleted.
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1401
50323 8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1402 You can use :meth:`str.maketrans` to create a translation map from
8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1403 character-to-character mappings in different formats.
46034 0a485593ae1c Merged revisions 61724-61725,61731-61735,61737,61739,61741,61743-61744,61753,61761,61765-61767,61769,61773,61776-61778,61780-61783,61788,61793,61796,61807,61813 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45979 diff changeset	1404
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1405 .. note::
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1406
44039 12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1407 An even more flexible approach is to create a custom character mapping
12e728035e2c #1496: revert str.translate() to the old version, and add Georg Brandl <georg@python.org> parents: 44028 diff changeset	1408 codec using the :mod:`codecs` module (see :mod:`encodings.cp1251` for an
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1409 example).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1410
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1411
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1412 .. method:: str.upper()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1413
71870 16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	1414 Return a copy of the string with all the cased characters [4]_ converted to
16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	1415 uppercase. Note that ``str.upper().isupper()`` might be ``False`` if ``s``
16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	1416 contains uncased characters or if the Unicode category of the resulting
16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	1417 character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter, titlecase).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1418
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1419
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1420 .. method:: str.zfill(width)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1421
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1422 Return the numeric string left filled with zeros in a string of length
3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	1423 width. A sign prefix is handled correctly. The original string is
74331 3f2e5fd17b76 #13754 String returned if less than or equal to x 3 Terry Jan Reedy <tjreedy@udel.edu> parents: 73813 diff changeset	1424 returned if width is less than or equal to ``len(s)``.
45852 30c4e1ca8421 Merged revisions 61431,61433-61436,61439,61444,61449-61450,61453,61458,61465,61468,61471-61474,61480,61483-61484,61488,61495-61496,61498,61503-61504,61507,61509-61510,61515-61518 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45346 diff changeset	1425
30c4e1ca8421 Merged revisions 61431,61433-61436,61439,61444,61449-61450,61453,61458,61465,61468,61471-61474,61480,61483-61484,61488,61495-61496,61498,61503-61504,61507,61509-61510,61515-61518 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45346 diff changeset	1426
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1427
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1428 .. _old-string-formatting:
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1429
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1430 Old String Formatting Operations
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1431 --------------------------------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1432
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1433 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1434 single: formatting, string (%)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1435 single: interpolation, string (%)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1436 single: string; formatting
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1437 single: string; interpolation
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1438 single: printf-style formatting
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1439 single: sprintf-style formatting
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1440 single: % formatting
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1441 single: % interpolation
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1442
43157 8c1c2d5bed32 Address a few XXX comments, other fixes. Georg Brandl <georg@python.org> parents: 43155 diff changeset	1443 .. XXX is the note enough?
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1444
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1445 .. note::
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1446
75293 80069bbae26d Issue #14123: Explicitly mention that old style % string formatting has caveats Gregory P. Smith <greg@krypto.org> parents: 75033 diff changeset	1447 The formatting operations described here are modelled on C's printf()
80069bbae26d Issue #14123: Explicitly mention that old style % string formatting has caveats Gregory P. Smith <greg@krypto.org> parents: 75033 diff changeset	1448 syntax. They only support formatting of certain builtin types. The
80069bbae26d Issue #14123: Explicitly mention that old style % string formatting has caveats Gregory P. Smith <greg@krypto.org> parents: 75033 diff changeset	1449 use of a binary operator means that care may be needed in order to
80069bbae26d Issue #14123: Explicitly mention that old style % string formatting has caveats Gregory P. Smith <greg@krypto.org> parents: 75033 diff changeset	1450 format tuples and dictionaries correctly. As the new
80069bbae26d Issue #14123: Explicitly mention that old style % string formatting has caveats Gregory P. Smith <greg@krypto.org> parents: 75033 diff changeset	1451 :ref:`string-formatting` syntax is more flexible and handles tuples and
80069bbae26d Issue #14123: Explicitly mention that old style % string formatting has caveats Gregory P. Smith <greg@krypto.org> parents: 75033 diff changeset	1452 dictionaries naturally, it is recommended for new code. However, there
80069bbae26d Issue #14123: Explicitly mention that old style % string formatting has caveats Gregory P. Smith <greg@krypto.org> parents: 75033 diff changeset	1453 are no current plans to deprecate printf-style formatting.
43138 a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1454
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1455 String objects have one unique built-in operation: the ``%`` operator (modulo).
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1456 This is also known as the string formatting or interpolation operator.
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1457 Given ``format % values`` (where format is a string), ``%`` conversion
a12a02b9f649 Commit #1068: new docs for PEP 3101. Also document the old string formatting as "old", and begin documenting str/unicode unification. Georg Brandl <georg@python.org> parents: 42604 diff changeset	1458 specifications in format are replaced with zero or more elements of values.
65137 521eac31a893 Migrate to Sphinx 1.0 C language constructs. Georg Brandl <georg@python.org> parents: 65049 diff changeset	1459 The effect is similar to the using :c:func:`sprintf` in the C language.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1460
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1461 If format requires a single argument, values may be a single non-tuple
71870 16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	1462 object. [5]_ Otherwise, values must be a tuple with exactly the number of
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1463 items specified by the format string, or a single mapping object (for example, a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1464 dictionary).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1465
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1466 A conversion specifier contains two or more characters and has the following
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1467 components, which must occur in this order:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1468
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1469 #. The ``'%'`` character, which marks the start of the specifier.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1470
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1471 #. Mapping key (optional), consisting of a parenthesised sequence of characters
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1472 (for example, ``(somename)``).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1473
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1474 #. Conversion flags (optional), which affect the result of some conversion
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1475 types.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1476
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1477 #. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1478 actual width is read from the next element of the tuple in values, and the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1479 object to convert comes after the minimum field width and optional precision.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1480
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1481 #. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If
71544 9846f6463f23 Issue #12644: document the '%a' conversion in the old string formatting operations. Patch prepared together with Ezio Melotti Eli Bendersky <eliben@gmail.com> parents: 71208 diff changeset	1482 specified as ``'*'`` (an asterisk), the actual precision is read from the next
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1483 element of the tuple in values, and the value to convert comes after the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1484 precision.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1485
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1486 #. Length modifier (optional).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1487
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1488 #. Conversion type.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1489
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1490 When the right argument is a dictionary (or other mapping type), then the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1491 formats in the string must include a parenthesised mapping key into that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1492 dictionary inserted immediately after the ``'%'`` character. The mapping key
46034 0a485593ae1c Merged revisions 61724-61725,61731-61735,61737,61739,61741,61743-61744,61753,61761,61765-61767,61769,61773,61776-61778,61780-61783,61788,61793,61796,61807,61813 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45979 diff changeset	1493 selects the value to be formatted from the mapping. For example:
0a485593ae1c Merged revisions 61724-61725,61731-61735,61737,61739,61741,61743-61744,61753,61761,61765-61767,61769,61773,61776-61778,61780-61783,61788,61793,61796,61807,61813 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 45979 diff changeset	1494
66472 a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66470 diff changeset	1495 >>> print('%(language)s has %(number)03d quote types.' %
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66470 diff changeset	1496 ... {'language': "Python", "number": 2})
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1497 Python has 002 quote types.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1498
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1499 In this case no ``*`` specifiers may occur in a format (since they require a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1500 sequential parameter list).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1501
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1502 The conversion flag characters are:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1503
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1504 +---------+---------------------------------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1505 \| Flag \| Meaning \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1506 +=========+=====================================================================+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1507 \| ``'#'`` \| The value conversion will use the "alternate form" (where defined \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1508 \| \| below). \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1509 +---------+---------------------------------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1510 \| ``'0'`` \| The conversion will be zero padded for numeric values. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1511 +---------+---------------------------------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1512 \| ``'-'`` \| The converted value is left adjusted (overrides the ``'0'`` \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1513 \| \| conversion if both are given). \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1514 +---------+---------------------------------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1515 \| ``' '`` \| (a space) A blank should be left before a positive number (or empty \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1516 \| \| string) produced by a signed conversion. \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1517 +---------+---------------------------------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1518 \| ``'+'`` \| A sign character (``'+'`` or ``'-'``) will precede the conversion \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1519 \| \| (overrides a "space" flag). \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1520 +---------+---------------------------------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1521
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1522 A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it
47067 960ade856078 Merged revisions 62998-63003,63005-63006,63009-63012,63014-63017,63019-63020,63022-63024,63026-63029,63031-63041,63043-63045,63047-63054,63056-63062 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 47066 diff changeset	1523 is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1524
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1525 The conversion types are:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1526
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1527 +------------+-----------------------------------------------------+-------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1528 \| Conversion \| Meaning \| Notes \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1529 +============+=====================================================+=======+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1530 \| ``'d'`` \| Signed integer decimal. \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1531 +------------+-----------------------------------------------------+-------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1532 \| ``'i'`` \| Signed integer decimal. \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1533 +------------+-----------------------------------------------------+-------+
47067 960ade856078 Merged revisions 62998-63003,63005-63006,63009-63012,63014-63017,63019-63020,63022-63024,63026-63029,63031-63041,63043-63045,63047-63054,63056-63062 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 47066 diff changeset	1534 \| ``'o'`` \| Signed octal value. \| \(1) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1535 +------------+-----------------------------------------------------+-------+
52103 3b43577e1971 Merged revisions 69998-69999,70002,70022-70023,70025-70026,70061,70086,70145,70171,70183,70188,70235,70244,70275,70281 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 51868 diff changeset	1536 \| ``'u'`` \| Obsolete type -- it is identical to ``'d'``. \| \(7) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1537 +------------+-----------------------------------------------------+-------+
47067 960ade856078 Merged revisions 62998-63003,63005-63006,63009-63012,63014-63017,63019-63020,63022-63024,63026-63029,63031-63041,63043-63045,63047-63054,63056-63062 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 47066 diff changeset	1538 \| ``'x'`` \| Signed hexadecimal (lowercase). \| \(2) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1539 +------------+-----------------------------------------------------+-------+
47067 960ade856078 Merged revisions 62998-63003,63005-63006,63009-63012,63014-63017,63019-63020,63022-63024,63026-63029,63031-63041,63043-63045,63047-63054,63056-63062 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 47066 diff changeset	1540 \| ``'X'`` \| Signed hexadecimal (uppercase). \| \(2) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1541 +------------+-----------------------------------------------------+-------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1542 \| ``'e'`` \| Floating point exponential format (lowercase). \| \(3) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1543 +------------+-----------------------------------------------------+-------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1544 \| ``'E'`` \| Floating point exponential format (uppercase). \| \(3) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1545 +------------+-----------------------------------------------------+-------+
48523 3d526525b3e8 Backed out r65073, pending fixing it in Windows. Eric Smith <eric@trueblade.com> parents: 48522 diff changeset	1546 \| ``'f'`` \| Floating point decimal format. \| \(3) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1547 +------------+-----------------------------------------------------+-------+
48523 3d526525b3e8 Backed out r65073, pending fixing it in Windows. Eric Smith <eric@trueblade.com> parents: 48522 diff changeset	1548 \| ``'F'`` \| Floating point decimal format. \| \(3) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1549 +------------+-----------------------------------------------------+-------+
46708 74b9c85361f8 Merged revisions 62774-62775,62785,62787-62788 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 46336 diff changeset	1550 \| ``'g'`` \| Floating point format. Uses lowercase exponential \| \(4) \|
74b9c85361f8 Merged revisions 62774-62775,62785,62787-62788 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 46336 diff changeset	1551 \| \| format if exponent is less than -4 or not less than \| \|
74b9c85361f8 Merged revisions 62774-62775,62785,62787-62788 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 46336 diff changeset	1552 \| \| precision, decimal format otherwise. \| \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1553 +------------+-----------------------------------------------------+-------+
46708 74b9c85361f8 Merged revisions 62774-62775,62785,62787-62788 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 46336 diff changeset	1554 \| ``'G'`` \| Floating point format. Uses uppercase exponential \| \(4) \|
74b9c85361f8 Merged revisions 62774-62775,62785,62787-62788 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 46336 diff changeset	1555 \| \| format if exponent is less than -4 or not less than \| \|
74b9c85361f8 Merged revisions 62774-62775,62785,62787-62788 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 46336 diff changeset	1556 \| \| precision, decimal format otherwise. \| \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1557 +------------+-----------------------------------------------------+-------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1558 \| ``'c'`` \| Single character (accepts integer or single \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1559 \| \| character string). \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1560 +------------+-----------------------------------------------------+-------+
57798 e23f5ec93315 Merged revisions 76906 via svnmerge from Ezio Melotti <ezio.melotti@gmail.com> parents: 57785 diff changeset	1561 \| ``'r'`` \| String (converts any Python object using \| \(5) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1562 \| \| :func:`repr`). \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1563 +------------+-----------------------------------------------------+-------+
71544 9846f6463f23 Issue #12644: document the '%a' conversion in the old string formatting operations. Patch prepared together with Ezio Melotti Eli Bendersky <eliben@gmail.com> parents: 71208 diff changeset	1564 \| ``'s'`` \| String (converts any Python object using \| \(5) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1565 \| \| :func:`str`). \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1566 +------------+-----------------------------------------------------+-------+
71544 9846f6463f23 Issue #12644: document the '%a' conversion in the old string formatting operations. Patch prepared together with Ezio Melotti Eli Bendersky <eliben@gmail.com> parents: 71208 diff changeset	1567 \| ``'a'`` \| String (converts any Python object using \| \(5) \|
9846f6463f23 Issue #12644: document the '%a' conversion in the old string formatting operations. Patch prepared together with Ezio Melotti Eli Bendersky <eliben@gmail.com> parents: 71208 diff changeset	1568 \| \| :func:`ascii`). \| \|
9846f6463f23 Issue #12644: document the '%a' conversion in the old string formatting operations. Patch prepared together with Ezio Melotti Eli Bendersky <eliben@gmail.com> parents: 71208 diff changeset	1569 +------------+-----------------------------------------------------+-------+
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1570 \| ``'%'`` \| No argument is converted, results in a ``'%'`` \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1571 \| \| character in the result. \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1572 +------------+-----------------------------------------------------+-------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1573
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1574 Notes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1575
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1576 (1)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1577 The alternate form causes a leading zero (``'0'``) to be inserted between
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1578 left-hand padding and the formatting of the number if the leading character
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1579 of the result is not already a zero.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1580
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1581 (2)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1582 The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1583 the ``'x'`` or ``'X'`` format was used) to be inserted between left-hand padding
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1584 and the formatting of the number if the leading character of the result is not
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1585 already a zero.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1586
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1587 (3)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1588 The alternate form causes the result to always contain a decimal point, even if
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1589 no digits follow it.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1590
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1591 The precision determines the number of digits after the decimal point and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1592 defaults to 6.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1593
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1594 (4)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1595 The alternate form causes the result to always contain a decimal point, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1596 trailing zeroes are not removed as they would otherwise be.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1597
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1598 The precision determines the number of significant digits before and after the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1599 decimal point and defaults to 6.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1600
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1601 (5)
71544 9846f6463f23 Issue #12644: document the '%a' conversion in the old string formatting operations. Patch prepared together with Ezio Melotti Eli Bendersky <eliben@gmail.com> parents: 71208 diff changeset	1602 If precision is ``N``, the output is truncated to ``N`` characters.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1603
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1604
47067 960ade856078 Merged revisions 62998-63003,63005-63006,63009-63012,63014-63017,63019-63020,63022-63024,63026-63029,63031-63041,63043-63045,63047-63054,63056-63062 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 47066 diff changeset	1605 (7)
960ade856078 Merged revisions 62998-63003,63005-63006,63009-63012,63014-63017,63019-63020,63022-63024,63026-63029,63031-63041,63043-63045,63047-63054,63056-63062 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 47066 diff changeset	1606 See :pep:`237`.
960ade856078 Merged revisions 62998-63003,63005-63006,63009-63012,63014-63017,63019-63020,63022-63024,63026-63029,63031-63041,63043-63045,63047-63054,63056-63062 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 47066 diff changeset	1607
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1608 Since Python strings have an explicit length, ``%s`` conversions do not assume
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1609 that ``'\0'`` is the end of the string.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1610
44396 6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44349 diff changeset	1611 .. XXX Examples?
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44349 diff changeset	1612
53642 60d0f373a894 Issue #5859: Remove '%f' to '%g' formatting switch for large floats. Mark Dickinson <dickinsm@gmail.com> parents: 53094 diff changeset	1613 .. versionchanged:: 3.1
60d0f373a894 Issue #5859: Remove '%f' to '%g' formatting switch for large floats. Mark Dickinson <dickinsm@gmail.com> parents: 53094 diff changeset	1614 ``%f`` conversions for numbers whose absolute value is over 1e50 are no
60d0f373a894 Issue #5859: Remove '%f' to '%g' formatting switch for large floats. Mark Dickinson <dickinsm@gmail.com> parents: 53094 diff changeset	1615 longer replaced by ``%g`` conversions.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1616
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1617 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1618 module: string
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1619 module: re
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1620
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1621 Additional string operations are defined in standard modules :mod:`string` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1622 :mod:`re`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1623
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1624
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1625 .. _typesseq-range:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1626
43450 e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	1627 Range Type
e88f83c3b25e #1219: py3k cleanup in standard types docs. Georg Brandl <georg@python.org> parents: 43446 diff changeset	1628 ----------
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1629
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1630 .. index:: object: range
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1631
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1632 The :class:`range` type is an immutable sequence which is commonly used for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1633 looping. The advantage of the :class:`range` type is that an :class:`range`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1634 object will always take the same amount of memory, no matter the size of the
66337 62182abc116a Clean-up the description of the range object. Raymond Hettinger <python@rcn.com> parents: 66336 diff changeset	1635 range it represents.
62182abc116a Clean-up the description of the range object. Raymond Hettinger <python@rcn.com> parents: 66336 diff changeset	1636
62182abc116a Clean-up the description of the range object. Raymond Hettinger <python@rcn.com> parents: 66336 diff changeset	1637 Range objects have relatively little behavior: they support indexing, contains,
62182abc116a Clean-up the description of the range object. Raymond Hettinger <python@rcn.com> parents: 66336 diff changeset	1638 iteration, the :func:`len` function, and the following methods:
64725 e2dec9c0d13c Issue #9213: Add index and count methods to range objects, needed to Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 64619 diff changeset	1639
e2dec9c0d13c Issue #9213: Add index and count methods to range objects, needed to Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 64619 diff changeset	1640 .. method:: range.count(x)
e2dec9c0d13c Issue #9213: Add index and count methods to range objects, needed to Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 64619 diff changeset	1641
66337 62182abc116a Clean-up the description of the range object. Raymond Hettinger <python@rcn.com> parents: 66336 diff changeset	1642 Return the number of i's for which ``s[i] == x``.
64725 e2dec9c0d13c Issue #9213: Add index and count methods to range objects, needed to Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 64619 diff changeset	1643
e2dec9c0d13c Issue #9213: Add index and count methods to range objects, needed to Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 64619 diff changeset	1644 .. versionadded:: 3.2
e2dec9c0d13c Issue #9213: Add index and count methods to range objects, needed to Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 64619 diff changeset	1645
e2dec9c0d13c Issue #9213: Add index and count methods to range objects, needed to Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 64619 diff changeset	1646 .. method:: range.index(x)
e2dec9c0d13c Issue #9213: Add index and count methods to range objects, needed to Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 64619 diff changeset	1647
e2dec9c0d13c Issue #9213: Add index and count methods to range objects, needed to Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 64619 diff changeset	1648 Return the smallest i such that ``s[i] == x``. Raises
e2dec9c0d13c Issue #9213: Add index and count methods to range objects, needed to Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 64619 diff changeset	1649 :exc:`ValueError` when x is not in the range.
e2dec9c0d13c Issue #9213: Add index and count methods to range objects, needed to Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 64619 diff changeset	1650
e2dec9c0d13c Issue #9213: Add index and count methods to range objects, needed to Daniel Stutzbach <daniel@stutzbachenterprises.com> parents: 64619 diff changeset	1651 .. versionadded:: 3.2
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1652
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1653 .. _typesseq-mutable:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1654
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1655 Mutable Sequence Types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1656 ----------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1657
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1658 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1659 triple: mutable; sequence; types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1660 object: list
43971 72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	1661 object: bytearray
72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	1662
72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	1663 List and bytearray objects support additional operations that allow in-place
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1664 modification of the object. Other mutable sequence types (when added to the
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1665 language) should also support these operations. Strings and tuples are
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1666 immutable sequence types: such objects cannot be modified once created. The
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1667 following operations are defined on mutable sequence types (where x is an
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1668 arbitrary object).
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1669
43971 72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	1670 Note that while lists allow their items to be of any type, bytearray object
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1671 "items" are all integers in the range 0 <= x < 256.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1672
65050 de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1673 .. index::
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1674 triple: operations on; sequence; types
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1675 triple: operations on; list; type
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1676 pair: subscript; assignment
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1677 pair: slice; assignment
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1678 statement: del
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1679 single: append() (sequence method)
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1680 single: extend() (sequence method)
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1681 single: count() (sequence method)
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1682 single: index() (sequence method)
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1683 single: insert() (sequence method)
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1684 single: pop() (sequence method)
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1685 single: remove() (sequence method)
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1686 single: reverse() (sequence method)
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1687 single: sort() (sequence method)
de418d9dd733 Merged revisions 85156 via svnmerge from Senthil Kumaran <orsenthil@gmail.com> parents: 64767 diff changeset	1688
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1689 +------------------------------+--------------------------------+---------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1690 \| Operation \| Result \| Notes \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1691 +==============================+================================+=====================+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1692 \| ``s[i] = x`` \| item i of s is replaced by \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1693 \| \| x \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1694 +------------------------------+--------------------------------+---------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1695 \| ``s[i:j] = t`` \| slice of s from i to j \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1696 \| \| is replaced by the contents of \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1697 \| \| the iterable t \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1698 +------------------------------+--------------------------------+---------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1699 \| ``del s[i:j]`` \| same as ``s[i:j] = []`` \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1700 +------------------------------+--------------------------------+---------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1701 \| ``s[i:j:k] = t`` \| the elements of ``s[i:j:k]`` \| \(1) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1702 \| \| are replaced by those of t \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1703 +------------------------------+--------------------------------+---------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1704 \| ``del s[i:j:k]`` \| removes the elements of \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1705 \| \| ``s[i:j:k]`` from the list \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1706 +------------------------------+--------------------------------+---------------------+
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1707 \| ``s.append(x)`` \| same as ``s[len(s):len(s)] = \| \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1708 \| \| [x]`` \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1709 +------------------------------+--------------------------------+---------------------+
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1710 \| ``s.extend(x)`` \| same as ``s[len(s):len(s)] = \| \(2) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1711 \| \| x`` \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1712 +------------------------------+--------------------------------+---------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1713 \| ``s.count(x)`` \| return number of i's for \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1714 \| \| which ``s[i] == x`` \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1715 +------------------------------+--------------------------------+---------------------+
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1716 \| ``s.index(x[, i[, j]])`` \| return smallest k such that \| \(3) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1717 \| \| ``s[k] == x`` and ``i <= k < \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1718 \| \| j`` \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1719 +------------------------------+--------------------------------+---------------------+
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1720 \| ``s.insert(i, x)`` \| same as ``s[i:i] = [x]`` \| \(4) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1721 +------------------------------+--------------------------------+---------------------+
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1722 \| ``s.pop([i])`` \| same as ``x = s[i]; del s[i]; \| \(5) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1723 \| \| return x`` \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1724 +------------------------------+--------------------------------+---------------------+
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1725 \| ``s.remove(x)`` \| same as ``del s[s.index(x)]`` \| \(3) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1726 +------------------------------+--------------------------------+---------------------+
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1727 \| ``s.reverse()`` \| reverses the items of s in \| \(6) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1728 \| \| place \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1729 +------------------------------+--------------------------------+---------------------+
45346 167a9fc82844 Note the the sort arguments are required to be keywords. Raymond Hettinger <python@rcn.com> parents: 45345 diff changeset	1730 \| ``s.sort([key[, reverse]])`` \| sort the items of s in place \| (6), (7), (8) \|
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1731 +------------------------------+--------------------------------+---------------------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1732
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1733
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1734 Notes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1735
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1736 (1)
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1737 t must have the same length as the slice it is replacing.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1738
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1739 (2)
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1740 x can be any iterable object.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1741
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1742 (3)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1743 Raises :exc:`ValueError` when x is not found in s. When a negative index is
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1744 passed as the second or third parameter to the :meth:`index` method, the sequence
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1745 length is added, as for slice indices. If it is still negative, it is truncated
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1746 to zero, as for slice indices.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1747
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1748 (4)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1749 When a negative index is passed as the first parameter to the :meth:`insert`
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1750 method, the sequence length is added, as for slice indices. If it is still
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1751 negative, it is truncated to zero, as for slice indices.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1752
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1753 (5)
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1754 The optional argument i defaults to ``-1``, so that by default the last
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1755 item is removed and returned.
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1756
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1757 (6)
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1758 The :meth:`sort` and :meth:`reverse` methods modify the sequence in place for
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1759 economy of space when sorting or reversing a large sequence. To remind you
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1760 that they operate by side effect, they don't return the sorted or reversed
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1761 sequence.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1762
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1763 (7)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1764 The :meth:`sort` method takes optional arguments for controlling the
45346 167a9fc82844 Note the the sort arguments are required to be keywords. Raymond Hettinger <python@rcn.com> parents: 45345 diff changeset	1765 comparisons. Each must be specified as a keyword argument.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1766
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1767 key specifies a function of one argument that is used to extract a comparison
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44500 diff changeset	1768 key from each list element: ``key=str.lower``. The default value is ``None``.
60370 3ce66c6922ab Forward port total_ordering() and cmp_to_key(). Raymond Hettinger <python@rcn.com> parents: 59811 diff changeset	1769 Use :func:`functools.cmp_to_key` to convert an
3ce66c6922ab Forward port total_ordering() and cmp_to_key(). Raymond Hettinger <python@rcn.com> parents: 59811 diff changeset	1770 old-style cmp function to a key function.
3ce66c6922ab Forward port total_ordering() and cmp_to_key(). Raymond Hettinger <python@rcn.com> parents: 59811 diff changeset	1771
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1772
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1773 reverse is a boolean value. If set to ``True``, then the list elements are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1774 sorted as if each comparison were reversed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1775
45345 89ec42b29863 Documentation nit. Raymond Hettinger <python@rcn.com> parents: 45084 diff changeset	1776 The :meth:`sort` method is guaranteed to be stable. A
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1777 sort is stable if it guarantees not to change the relative order of elements
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1778 that compare equal --- this is helpful for sorting in multiple passes (for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1779 example, sort by department, then by salary grade).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1780
56894 b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56370 diff changeset	1781 .. impl-detail::
b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56370 diff changeset	1782
b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56370 diff changeset	1783 While a list is being sorted, the effect of attempting to mutate, or even
b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56370 diff changeset	1784 inspect, the list is undefined. The C implementation of Python makes the
b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56370 diff changeset	1785 list appear empty for the duration, and raises :exc:`ValueError` if it can
b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56370 diff changeset	1786 detect that the list has been mutated during a sort.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1787
45346 167a9fc82844 Note the the sort arguments are required to be keywords. Raymond Hettinger <python@rcn.com> parents: 45345 diff changeset	1788 (8)
167a9fc82844 Note the the sort arguments are required to be keywords. Raymond Hettinger <python@rcn.com> parents: 45345 diff changeset	1789 :meth:`sort` is not supported by :class:`bytearray` objects.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1790
56894 b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 56370 diff changeset	1791
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1792 .. _bytes-methods:
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1793
43971 72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	1794 Bytes and Byte Array Methods
72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	1795 ----------------------------
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1796
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1797 .. index:: pair: bytes; methods
43971 72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	1798 pair: bytearray; methods
72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	1799
72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	1800 Bytes and bytearray objects, being "strings of bytes", have all methods found on
43646 cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1801 strings, with the exception of :func:`encode`, :func:`format` and
43777 0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch. Guido van Rossum <guido@python.org> parents: 43756 diff changeset	1802 :func:`isidentifier`, which do not make sense with these types. For converting
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch. Guido van Rossum <guido@python.org> parents: 43756 diff changeset	1803 the objects to strings, they have a :func:`decode` method.
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch. Guido van Rossum <guido@python.org> parents: 43756 diff changeset	1804
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch. Guido van Rossum <guido@python.org> parents: 43756 diff changeset	1805 Wherever one of these methods needs to interpret the bytes as characters
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch. Guido van Rossum <guido@python.org> parents: 43756 diff changeset	1806 (e.g. the :func:`is...` methods), the ASCII character set is assumed.
43646 cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1807
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1808 .. note::
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1809
43971 72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	1810 The methods on bytes and bytearray objects don't accept strings as their
43646 cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1811 arguments, just as the methods on strings don't accept bytes as their
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1812 arguments. For example, you have to write ::
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1813
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1814 a = "abc"
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1815 b = a.replace("a", "f")
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1816
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1817 and ::
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1818
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1819 a = b"abc"
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1820 b = a.replace(b"a", b"f")
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1821
cd5b383a397e Update w.r.t. PEP 3137. Georg Brandl <georg@python.org> parents: 43645 diff changeset	1822
66069 8154db8a1593 Fix encode/decode method doc of str, bytes, bytearray types Victor Stinner <victor.stinner@haypocalc.com> parents: 66058 diff changeset	1823 .. method:: bytes.decode(encoding="utf-8", errors="strict")
8154db8a1593 Fix encode/decode method doc of str, bytes, bytearray types Victor Stinner <victor.stinner@haypocalc.com> parents: 66058 diff changeset	1824 bytearray.decode(encoding="utf-8", errors="strict")
8154db8a1593 Fix encode/decode method doc of str, bytes, bytearray types Victor Stinner <victor.stinner@haypocalc.com> parents: 66058 diff changeset	1825
8154db8a1593 Fix encode/decode method doc of str, bytes, bytearray types Victor Stinner <victor.stinner@haypocalc.com> parents: 66058 diff changeset	1826 Return a string decoded from the given bytes. Default encoding is
8154db8a1593 Fix encode/decode method doc of str, bytes, bytearray types Victor Stinner <victor.stinner@haypocalc.com> parents: 66058 diff changeset	1827 ``'utf-8'``. errors may be given to set a different
53751 c2d107e07839 Add missing documentation for bytes.decode(). Georg Brandl <georg@python.org> parents: 53642 diff changeset	1828 error handling scheme. The default for errors is ``'strict'``, meaning
c2d107e07839 Add missing documentation for bytes.decode(). Georg Brandl <georg@python.org> parents: 53642 diff changeset	1829 that encoding errors raise a :exc:`UnicodeError`. Other possible values are
c2d107e07839 Add missing documentation for bytes.decode(). Georg Brandl <georg@python.org> parents: 53642 diff changeset	1830 ``'ignore'``, ``'replace'`` and any other name registered via
c2d107e07839 Add missing documentation for bytes.decode(). Georg Brandl <georg@python.org> parents: 53642 diff changeset	1831 :func:`codecs.register_error`, see section :ref:`codec-base-classes`. For a
c2d107e07839 Add missing documentation for bytes.decode(). Georg Brandl <georg@python.org> parents: 53642 diff changeset	1832 list of possible encodings, see section :ref:`standard-encodings`.
c2d107e07839 Add missing documentation for bytes.decode(). Georg Brandl <georg@python.org> parents: 53642 diff changeset	1833
56099 1b7bdae02179 Merged revisions 74929 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55911 diff changeset	1834 .. versionchanged:: 3.1
1b7bdae02179 Merged revisions 74929 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55911 diff changeset	1835 Added support for keyword arguments.
1b7bdae02179 Merged revisions 74929 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55911 diff changeset	1836
53751 c2d107e07839 Add missing documentation for bytes.decode(). Georg Brandl <georg@python.org> parents: 53642 diff changeset	1837
43971 72962abd90a1 Update docs for buffer -> bytearray rename. Georg Brandl <georg@python.org> parents: 43815 diff changeset	1838 The bytes and bytearray types have an additional class method:
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1839
53094 4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1840 .. classmethod:: bytes.fromhex(string)
4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1841 bytearray.fromhex(string)
48398 7e299ab35d95 #3220: improve bytes docs a bit. Georg Brandl <georg@python.org> parents: 48391 diff changeset	1842
7e299ab35d95 #3220: improve bytes docs a bit. Georg Brandl <georg@python.org> parents: 48391 diff changeset	1843 This :class:`bytes` class method returns a bytes or bytearray object,
7e299ab35d95 #3220: improve bytes docs a bit. Georg Brandl <georg@python.org> parents: 48391 diff changeset	1844 decoding the given string object. The string must contain two hexadecimal
7e299ab35d95 #3220: improve bytes docs a bit. Georg Brandl <georg@python.org> parents: 48391 diff changeset	1845 digits per byte, spaces are ignored.
7e299ab35d95 #3220: improve bytes docs a bit. Georg Brandl <georg@python.org> parents: 48391 diff changeset	1846
7e299ab35d95 #3220: improve bytes docs a bit. Georg Brandl <georg@python.org> parents: 48391 diff changeset	1847 >>> bytes.fromhex('f0 f1f2 ')
7e299ab35d95 #3220: improve bytes docs a bit. Georg Brandl <georg@python.org> parents: 48391 diff changeset	1848 b'\xf0\xf1\xf2'
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1849
53094 4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1850
4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1851 The maketrans and translate methods differ in semantics from the versions
4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1852 available on strings:
50514 c3d3b760d8bf Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50323 diff changeset	1853
50323 8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1854 .. method:: bytes.translate(table[, delete])
54476 52d258eb0176 #5675 followup: bytearray also has translate and maketrans. Georg Brandl <georg@python.org> parents: 54137 diff changeset	1855 bytearray.translate(table[, delete])
50323 8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1856
8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1857 Return a copy of the bytes or bytearray object where all bytes occurring in
8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1858 the optional argument delete are removed, and the remaining bytes have been
8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1859 mapped through the given translation table, which must be a bytes object of
8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1860 length 256.
8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1861
53094 4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1862 You can use the :func:`bytes.maketrans` method to create a translation table.
50323 8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1863
8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1864 Set the table argument to ``None`` for translations that only delete
8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1865 characters::
8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1866
8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1867 >>> b'read this short text'.translate(None, b'aeiou')
8bfb466414ac Document bytes.translate(). Georg Brandl <georg@python.org> parents: 50248 diff changeset	1868 b'rd ths shrt txt'
43143 77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1869
77000f2641ee Add bytes methods documentation. Georg Brandl <georg@python.org> parents: 43138 diff changeset	1870
53094 4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1871 .. staticmethod:: bytes.maketrans(from, to)
54476 52d258eb0176 #5675 followup: bytearray also has translate and maketrans. Georg Brandl <georg@python.org> parents: 54137 diff changeset	1872 bytearray.maketrans(from, to)
53094 4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1873
4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1874 This static method returns a translation table usable for
4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1875 :meth:`bytes.translate` that will map each character in from into the
4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1876 character at the same position in to; from and to must be bytes objects
4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1877 and have the same length.
4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1878
4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1879 .. versionadded:: 3.1
4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1880
4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	1881
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1882 .. _types-set:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1883
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1884 Set Types --- :class:`set`, :class:`frozenset`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1885 ==============================================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1886
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1887 .. index:: object: set
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1888
43756 317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	1889 A :dfn:`set` object is an unordered collection of distinct :term:`hashable` objects.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1890 Common uses include membership testing, removing duplicates from a sequence, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1891 computing mathematical operations such as intersection, union, difference, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1892 symmetric difference.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1893 (For other containers see the built in :class:`dict`, :class:`list`,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1894 and :class:`tuple` classes, and the :mod:`collections` module.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1895
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1896 Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1897 set``. Being an unordered collection, sets do not record element position or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1898 order of insertion. Accordingly, sets do not support indexing, slicing, or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1899 other sequence-like behavior.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1900
55580 7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from Georg Brandl <georg@python.org> parents: 54917 diff changeset	1901 There are currently two built-in set types, :class:`set` and :class:`frozenset`.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1902 The :class:`set` type is mutable --- the contents can be changed using methods
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1903 like :meth:`add` and :meth:`remove`. Since it is mutable, it has no hash value
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1904 and cannot be used as either a dictionary key or as an element of another set.
43756 317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	1905 The :class:`frozenset` type is immutable and :term:`hashable` --- its contents cannot be
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1906 altered after it is created; it can therefore be used as a dictionary key or as
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1907 an element of another set.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1908
65111 a4c9746cb03c Merged revisions 78959,79170,79175,79177,79180,79183,79186,79193,79581 via svnmerge from Georg Brandl <georg@python.org> parents: 65050 diff changeset	1909 Non-empty sets (not frozensets) can be created by placing a comma-separated list
a4c9746cb03c Merged revisions 78959,79170,79175,79177,79180,79183,79186,79193,79581 via svnmerge from Georg Brandl <georg@python.org> parents: 65050 diff changeset	1910 of elements within braces, for example: ``{'jack', 'sjoerd'}``, in addition to the
a4c9746cb03c Merged revisions 78959,79170,79175,79177,79180,79183,79186,79193,79581 via svnmerge from Georg Brandl <georg@python.org> parents: 65050 diff changeset	1911 :class:`set` constructor.
a4c9746cb03c Merged revisions 78959,79170,79175,79177,79180,79183,79186,79193,79581 via svnmerge from Georg Brandl <georg@python.org> parents: 65050 diff changeset	1912
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1913 The constructors for both classes work the same:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1914
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1915 .. class:: set([iterable])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1916 frozenset([iterable])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1917
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1918 Return a new set or frozenset object whose elements are taken from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1919 iterable. The elements of a set must be hashable. To represent sets of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1920 sets, the inner sets must be :class:`frozenset` objects. If iterable is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1921 not specified, a new empty set is returned.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1922
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1923 Instances of :class:`set` and :class:`frozenset` provide the following
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1924 operations:
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1925
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1926 .. describe:: len(s)
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1927
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1928 Return the cardinality of set s.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1929
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1930 .. describe:: x in s
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1931
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1932 Test x for membership in s.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1933
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1934 .. describe:: x not in s
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1935
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1936 Test x for non-membership in s.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1937
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1938 .. method:: isdisjoint(other)
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1939
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1940 Return True if the set has no elements in common with other. Sets are
48499 de0bf60f1245 Merged revisions 64722,64729,64753,64845-64846,64849,64871,64880-64882,64885,64888,64897,64900-64901,64915,64926-64929,64938-64941,64944,64961,64966,64973 via svnmerge from Georg Brandl <georg@python.org> parents: 48497 diff changeset	1941 disjoint if and only if their intersection is the empty set.
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1942
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1943 .. method:: issubset(other)
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1944 set <= other
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1945
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1946 Test whether every element in the set is in other.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1947
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1948 .. method:: set < other
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1949
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1950 Test whether the set is a true subset of other, that is,
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1951 ``set <= other and set != other``.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1952
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1953 .. method:: issuperset(other)
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1954 set >= other
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1955
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1956 Test whether every element in other is in the set.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1957
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1958 .. method:: set > other
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1959
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1960 Test whether the set is a true superset of other, that is, ``set >=
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1961 other and set != other``.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1962
47562 bd584f121c4b Merged revisions 64002-64003,64012,64036-64037,64047,64050-64052,64054-64055,64066,64071 via svnmerge from Georg Brandl <georg@python.org> parents: 47463 diff changeset	1963 .. method:: union(other, ...)
bd584f121c4b Merged revisions 64002-64003,64012,64036-64037,64047,64050-64052,64054-64055,64066,64071 via svnmerge from Georg Brandl <georg@python.org> parents: 47463 diff changeset	1964 set \| other \| ...
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1965
50885 9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	1966 Return a new set with elements from the set and all others.
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1967
47562 bd584f121c4b Merged revisions 64002-64003,64012,64036-64037,64047,64050-64052,64054-64055,64066,64071 via svnmerge from Georg Brandl <georg@python.org> parents: 47463 diff changeset	1968 .. method:: intersection(other, ...)
bd584f121c4b Merged revisions 64002-64003,64012,64036-64037,64047,64050-64052,64054-64055,64066,64071 via svnmerge from Georg Brandl <georg@python.org> parents: 47463 diff changeset	1969 set & other & ...
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1970
50885 9f45fa27b838 Merged revisions 68633,68648,68667,68706,68718,68720-68721,68724-68727,68739 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 50860 diff changeset	1971 Return a new set with elements common to the set and all others.
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1972
47750 f64996760984 Merged revisions 64089,64098,64100-64102,64113,64115-64116,64118,64120,64132,64342 via svnmerge from Amaury Forgeot d'Arc <amauryfa@gmail.com> parents: 47611 diff changeset	1973 .. method:: difference(other, ...)
f64996760984 Merged revisions 64089,64098,64100-64102,64113,64115-64116,64118,64120,64132,64342 via svnmerge from Amaury Forgeot d'Arc <amauryfa@gmail.com> parents: 47611 diff changeset	1974 set - other - ...
f64996760984 Merged revisions 64089,64098,64100-64102,64113,64115-64116,64118,64120,64132,64342 via svnmerge from Amaury Forgeot d'Arc <amauryfa@gmail.com> parents: 47611 diff changeset	1975
f64996760984 Merged revisions 64089,64098,64100-64102,64113,64115-64116,64118,64120,64132,64342 via svnmerge from Amaury Forgeot d'Arc <amauryfa@gmail.com> parents: 47611 diff changeset	1976 Return a new set with elements in the set that are not in the others.
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1977
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1978 .. method:: symmetric_difference(other)
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1979 set ^ other
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1980
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1981 Return a new set with elements in either the set or other but not both.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1982
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1983 .. method:: copy()
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1984
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1985 Return a new set with a shallow copy of s.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1986
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1987
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1988 Note, the non-operator versions of :meth:`union`, :meth:`intersection`,
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1989 :meth:`difference`, and :meth:`symmetric_difference`, :meth:`issubset`, and
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1990 :meth:`issuperset` methods will accept any iterable as an argument. In
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1991 contrast, their operator based counterparts require their arguments to be
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1992 sets. This precludes error-prone constructions like ``set('abc') & 'cbs'``
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1993 in favor of the more readable ``set('abc').intersection('cbs')``.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1994
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1995 Both :class:`set` and :class:`frozenset` support set to set comparisons. Two
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1996 sets are equal if and only if every element of each set is contained in the
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1997 other (each is a subset of the other). A set is less than another set if and
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1998 only if the first set is a proper subset of the second set (is a subset, but
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	1999 is not equal). A set is greater than another set if and only if the first set
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2000 is a proper superset of the second set (is a superset, but is not equal).
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2001
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2002 Instances of :class:`set` are compared to instances of :class:`frozenset`
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2003 based on their members. For example, ``set('abc') == frozenset('abc')``
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2004 returns ``True`` and so does ``set('abc') in set([frozenset('abc')])``.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2005
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2006 The subset and equality comparisons do not generalize to a complete ordering
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2007 function. For example, any two disjoint sets are not equal and are not
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2008 subsets of each other, so all of the following return ``False``: ``a<b``,
49285 b3c29da934f5 Remove references to __cmp__. Georg Brandl <georg@python.org> parents: 49178 diff changeset	2009 ``a==b``, or ``a>b``.
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2010
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2011 Since sets only define partial ordering (subset relationships), the output of
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2012 the :meth:`list.sort` method is undefined for lists of sets.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2013
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2014 Set elements, like dictionary keys, must be :term:`hashable`.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2015
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2016 Binary operations that mix :class:`set` instances with :class:`frozenset`
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2017 return the type of the first operand. For example: ``frozenset('ab') \|
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2018 set('bc')`` returns an instance of :class:`frozenset`.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2019
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2020 The following table lists operations available for :class:`set` that do not
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2021 apply to immutable instances of :class:`frozenset`:
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2022
47562 bd584f121c4b Merged revisions 64002-64003,64012,64036-64037,64047,64050-64052,64054-64055,64066,64071 via svnmerge from Georg Brandl <georg@python.org> parents: 47463 diff changeset	2023 .. method:: update(other, ...)
bd584f121c4b Merged revisions 64002-64003,64012,64036-64037,64047,64050-64052,64054-64055,64066,64071 via svnmerge from Georg Brandl <georg@python.org> parents: 47463 diff changeset	2024 set \|= other \| ...
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2025
55797 afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55580 diff changeset	2026 Update the set, adding elements from all others.
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2027
47562 bd584f121c4b Merged revisions 64002-64003,64012,64036-64037,64047,64050-64052,64054-64055,64066,64071 via svnmerge from Georg Brandl <georg@python.org> parents: 47463 diff changeset	2028 .. method:: intersection_update(other, ...)
bd584f121c4b Merged revisions 64002-64003,64012,64036-64037,64047,64050-64052,64054-64055,64066,64071 via svnmerge from Georg Brandl <georg@python.org> parents: 47463 diff changeset	2029 set &= other & ...
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2030
55797 afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from Georg Brandl <georg@python.org> parents: 55580 diff changeset	2031 Update the set, keeping only elements found in it and all others.
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2032
47750 f64996760984 Merged revisions 64089,64098,64100-64102,64113,64115-64116,64118,64120,64132,64342 via svnmerge from Amaury Forgeot d'Arc <amauryfa@gmail.com> parents: 47611 diff changeset	2033 .. method:: difference_update(other, ...)
f64996760984 Merged revisions 64089,64098,64100-64102,64113,64115-64116,64118,64120,64132,64342 via svnmerge from Amaury Forgeot d'Arc <amauryfa@gmail.com> parents: 47611 diff changeset	2034 set -= other \| ...
f64996760984 Merged revisions 64089,64098,64100-64102,64113,64115-64116,64118,64120,64132,64342 via svnmerge from Amaury Forgeot d'Arc <amauryfa@gmail.com> parents: 47611 diff changeset	2035
f64996760984 Merged revisions 64089,64098,64100-64102,64113,64115-64116,64118,64120,64132,64342 via svnmerge from Amaury Forgeot d'Arc <amauryfa@gmail.com> parents: 47611 diff changeset	2036 Update the set, removing elements found in others.
f64996760984 Merged revisions 64089,64098,64100-64102,64113,64115-64116,64118,64120,64132,64342 via svnmerge from Amaury Forgeot d'Arc <amauryfa@gmail.com> parents: 47611 diff changeset	2037
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2038 .. method:: symmetric_difference_update(other)
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2039 set ^= other
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2040
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2041 Update the set, keeping only elements found in either set, but not in both.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2042
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2043 .. method:: add(elem)
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2044
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2045 Add element elem to the set.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2046
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2047 .. method:: remove(elem)
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2048
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2049 Remove element elem from the set. Raises :exc:`KeyError` if elem is
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2050 not contained in the set.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2051
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2052 .. method:: discard(elem)
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2053
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2054 Remove element elem from the set if it is present.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2055
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2056 .. method:: pop()
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2057
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2058 Remove and return an arbitrary element from the set. Raises
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2059 :exc:`KeyError` if the set is empty.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2060
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2061 .. method:: clear()
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2062
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2063 Remove all elements from the set.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2064
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2065
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2066 Note, the non-operator versions of the :meth:`update`,
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2067 :meth:`intersection_update`, :meth:`difference_update`, and
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2068 :meth:`symmetric_difference_update` methods will accept any iterable as an
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2069 argument.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2070
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2071 Note, the elem argument to the :meth:`__contains__`, :meth:`remove`, and
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2072 :meth:`discard` methods may be a set. To support searching for an equivalent
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2073 frozenset, the elem set is temporarily mutated during the search and then
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2074 restored. During the search, the elem set should not be read or mutated
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2075 since it does not have a meaningful value.
46769 5d15a8bcc445 Merged revisions 62873,62887,62892-62896,62904 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 46708 diff changeset	2076
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2077
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2078 .. _typesmapping:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2079
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2080 Mapping Types --- :class:`dict`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2081 ===============================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2082
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2083 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2084 object: mapping
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2085 object: dictionary
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2086 triple: operations on; mapping; types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2087 triple: operations on; dictionary; type
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2088 statement: del
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2089 builtin: len
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2090
43756 317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2091 A :dfn:`mapping` object maps :term:`hashable` values to arbitrary objects.
317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2092 Mappings are mutable objects. There is currently only one standard mapping
317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2093 type, the :dfn:`dictionary`. (For other containers see the built in
317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2094 :class:`list`, :class:`set`, and :class:`tuple` classes, and the
317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2095 :mod:`collections` module.)
317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2096
317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2097 A dictionary's keys are almost arbitrary values. Values that are not
317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2098 :term:`hashable`, that is, values containing lists, dictionaries or other
317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2099 mutable types (that are compared by value rather than by object identity) may
317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2100 not be used as keys. Numeric types used for keys obey the normal rules for
317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2101 numeric comparison: if two numbers compare equal (such as ``1`` and ``1.0``)
317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2102 then they can be used interchangeably to index the same dictionary entry. (Note
317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2103 however, that since computers store floating-point numbers as approximations it
317ba53cd45c Merged revisions 58742-58816 via svnmerge from Guido van Rossum <guido@python.org> parents: 43737 diff changeset	2104 is usually unwise to use them as dictionary keys.)
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2105
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2106 Dictionaries can be created by placing a comma-separated list of ``key: value``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2107 pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2108 'jack', 4127: 'sjoerd'}``, or by the :class:`dict` constructor.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2109
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2110 .. class:: dict([arg])
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2111
43234 49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2112 Return a new dictionary initialized from an optional positional argument or
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2113 from a set of keyword arguments. If no arguments are given, return a new
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2114 empty dictionary. If the positional argument arg is a mapping object,
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2115 return a dictionary mapping the same keys to the same values as does the
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2116 mapping object. Otherwise the positional argument must be a sequence, a
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2117 container that supports iteration, or an iterator object. The elements of
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2118 the argument must each also be of one of those kinds, and each must in turn
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2119 contain exactly two objects. The first is used as a key in the new
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2120 dictionary, and the second as the key's value. If a given key is seen more
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2121 than once, the last value associated with it is retained in the new
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2122 dictionary.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2123
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2124 If keyword arguments are given, the keywords themselves with their associated
43234 49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2125 values are added as items to the dictionary. If a key is specified both in
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2126 the positional argument and as a keyword argument, the value associated with
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2127 the keyword is retained in the dictionary. For example, these all return a
66472 a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66470 diff changeset	2128 dictionary equal to ``{"one": 1, "two": 2}``:
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66470 diff changeset	2129
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66470 diff changeset	2130 * ``dict(one=1, two=2)``
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66470 diff changeset	2131 * ``dict({'one': 1, 'two': 2})``
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66470 diff changeset	2132 * ``dict(zip(('one', 'two'), (1, 2)))``
a9f0ec604c8a Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from Georg Brandl <georg@python.org> parents: 66470 diff changeset	2133 * ``dict([['two', 2], ['one', 1]])``
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2134
43234 49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2135 The first example only works for keys that are valid Python identifiers; the
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2136 others work with any valid keys.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2137
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2138
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2139 These are the operations that dictionaries support (and therefore, custom
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2140 mapping types should support too):
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2141
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2142 .. describe:: len(d)
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2143
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2144 Return the number of items in the dictionary d.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2145
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2146 .. describe:: d[key]
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2147
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2148 Return the item of d with key key. Raises a :exc:`KeyError` if key is
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2149 not in the map.
50514 c3d3b760d8bf Remove trailing whitespace. Georg Brandl <georg@python.org> parents: 50323 diff changeset	2150
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2151 If a subclass of dict defines a method :meth:`__missing__`, if the key key
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2152 is not present, the ``d[key]`` operation calls that method with the key key
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2153 as argument. The ``d[key]`` operation then returns or raises whatever is
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2154 returned or raised by the ``__missing__(key)`` call if the key is not
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2155 present. No other operations or methods invoke :meth:`__missing__`. If
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2156 :meth:`__missing__` is not defined, :exc:`KeyError` is raised.
67461 d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2157 :meth:`__missing__` must be a method; it cannot be an instance variable::
d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2158
d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2159 >>> class Counter(dict):
d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2160 ... def __missing__(self, key):
d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2161 ... return 0
d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2162 >>> c = Counter()
d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2163 >>> c['red']
d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2164 0
d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2165 >>> c['red'] += 1
d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2166 >>> c['red']
d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2167 1
d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2168
d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2169 See :class:`collections.Counter` for a complete implementation including
d6566a70caa0 Issue 10533: Need example of using __missing__. Raymond Hettinger <python@rcn.com> parents: 67175 diff changeset	2170 other methods helpful for accumulating and managing tallies.
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2171
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2172 .. describe:: d[key] = value
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2173
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2174 Set ``d[key]`` to value.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2175
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2176 .. describe:: del d[key]
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2177
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2178 Remove ``d[key]`` from d. Raises a :exc:`KeyError` if key is not in the
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2179 map.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2180
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2181 .. describe:: key in d
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2182
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2183 Return ``True`` if d has a key key, else ``False``.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2184
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2185 .. describe:: key not in d
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2186
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2187 Equivalent to ``not key in d``.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2188
52892 792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2189 .. describe:: iter(d)
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2190
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2191 Return an iterator over the keys of the dictionary. This is a shortcut
62784 3b15486608f0 Merged revisions 77316 via svnmerge from Georg Brandl <georg@python.org> parents: 62433 diff changeset	2192 for ``iter(d.keys())``.
52892 792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2193
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2194 .. method:: clear()
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2195
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2196 Remove all items from the dictionary.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2197
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2198 .. method:: copy()
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2199
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2200 Return a shallow copy of the dictionary.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2201
53094 4407e4d07084 Add bytes/bytearray.maketrans() to mirror str.maketrans(), and deprecate Georg Brandl <georg@python.org> parents: 52892 diff changeset	2202 .. classmethod:: fromkeys(seq[, value])
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2203
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2204 Create a new dictionary with keys from seq and values set to value.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2205
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2206 :meth:`fromkeys` is a class method that returns a new dictionary. value
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2207 defaults to ``None``.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2208
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2209 .. method:: get(key[, default])
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2210
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2211 Return the value for key if key is in the dictionary, else default.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2212 If default is not given, it defaults to ``None``, so that this method
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2213 never raises a :exc:`KeyError`.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2214
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2215 .. method:: items()
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2216
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2217 Return a new view of the dictionary's items (``(key, value)`` pairs). See
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2218 below for documentation of view objects.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2219
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2220 .. method:: keys()
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2221
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2222 Return a new view of the dictionary's keys. See below for documentation of
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2223 view objects.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2224
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2225 .. method:: pop(key[, default])
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2226
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2227 If key is in the dictionary, remove it and return its value, else return
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2228 default. If default is not given and key is not in the dictionary,
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2229 a :exc:`KeyError` is raised.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2230
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2231 .. method:: popitem()
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2232
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2233 Remove and return an arbitrary ``(key, value)`` pair from the dictionary.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2234
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2235 :meth:`popitem` is useful to destructively iterate over a dictionary, as
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2236 often used in set algorithms. If the dictionary is empty, calling
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2237 :meth:`popitem` raises a :exc:`KeyError`.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2238
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2239 .. method:: setdefault(key[, default])
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2240
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2241 If key is in the dictionary, return its value. If not, insert key
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2242 with a value of default and return default. default defaults to
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2243 ``None``.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2244
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2245 .. method:: update([other])
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2246
64159 4f831d45125f Manually merge r84187 Éric Araujo <merwok@netwok.org> parents: 64010 diff changeset	2247 Update the dictionary with the key/value pairs from other, overwriting
4f831d45125f Manually merge r84187 Éric Araujo <merwok@netwok.org> parents: 64010 diff changeset	2248 existing keys. Return ``None``.
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2249
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2250 :meth:`update` accepts either another dictionary object or an iterable of
65121 6f9d15fccfa4 Merged revisions 85008,85011,85228,85240 via svnmerge from Georg Brandl <georg@python.org> parents: 65117 diff changeset	2251 key/value pairs (as tuples or other iterables of length two). If keyword
55913 3fb1c1fbe26c Merged revisions 74745 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 55797 diff changeset	2252 arguments are specified, the dictionary is then updated with those
47066 31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2253 key/value pairs: ``d.update(red=1, blue=2)``.
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2254
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2255 .. method:: values()
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2256
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2257 Return a new view of the dictionary's values. See below for documentation of
31cc8e1a8fdf Merged revisions 62954-62959,62961,62963-62967,62969-62970,62972-62973,62975-62976,62978-62982,62984,62987-62996 via svnmerge from Alexandre Vassalotti <alexandre@peadrop.com> parents: 46963 diff changeset	2258 view objects.
43234 49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2259
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2260
49800 6aef28ebbd6c make FileIO.mode always include 'b' Benjamin Peterson <benjamin@python.org> parents: 49738 diff changeset	2261 .. _dict-views:
6aef28ebbd6c make FileIO.mode always include 'b' Benjamin Peterson <benjamin@python.org> parents: 49738 diff changeset	2262
43234 49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2263 Dictionary view objects
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2264 -----------------------
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2265
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2266 The objects returned by :meth:`dict.keys`, :meth:`dict.values` and
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2267 :meth:`dict.items` are view objects. They provide a dynamic view on the
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2268 dictionary's entries, which means that when the dictionary changes, the view
49738 674ef4a7cd73 rephrase dict view docs Benjamin Peterson <benjamin@python.org> parents: 49285 diff changeset	2269 reflects these changes.
43234 49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2270
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2271 Dictionary views can be iterated over to yield their respective data, and
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2272 support membership tests:
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2273
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2274 .. describe:: len(dictview)
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2275
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2276 Return the number of entries in the dictionary.
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2277
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2278 .. describe:: iter(dictview)
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2279
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2280 Return an iterator over the keys, values or items (represented as tuples of
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2281 ``(key, value)``) in the dictionary.
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2282
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2283 Keys and values are iterated over in an arbitrary order which is non-random,
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2284 varies across Python implementations, and depends on the dictionary's history
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2285 of insertions and deletions. If keys, values and items views are iterated
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2286 over with no intervening modifications to the dictionary, the order of items
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2287 will directly correspond. This allows the creation of ``(value, key)`` pairs
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2288 using :func:`zip`: ``pairs = zip(d.values(), d.keys())``. Another way to
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2289 create the same list is ``pairs = [(v, k) for (k, v) in d.items()]``.
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2290
54137 f43fc1193c2a Recorded merge of revisions 72708 via svnmerge from Georg Brandl <georg@python.org> parents: 53751 diff changeset	2291 Iterating views while adding or deleting entries in the dictionary may raise
f43fc1193c2a Recorded merge of revisions 72708 via svnmerge from Georg Brandl <georg@python.org> parents: 53751 diff changeset	2292 a :exc:`RuntimeError` or fail to iterate over all entries.
52892 792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2293
43234 49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2294 .. describe:: x in dictview
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2295
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2296 Return ``True`` if x is in the underlying dictionary's keys, values or
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2297 items (in the latter case, x should be a ``(key, value)`` tuple).
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2298
49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2299
49738 674ef4a7cd73 rephrase dict view docs Benjamin Peterson <benjamin@python.org> parents: 49285 diff changeset	2300 Keys views are set-like since their entries are unique and hashable. If all
66470 45e49269e0d8 Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from Georg Brandl <georg@python.org> parents: 66338 diff changeset	2301 values are hashable, so that ``(key, value)`` pairs are unique and hashable,
45e49269e0d8 Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from Georg Brandl <georg@python.org> parents: 66338 diff changeset	2302 then the items view is also set-like. (Values views are not treated as set-like
45e49269e0d8 Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from Georg Brandl <georg@python.org> parents: 66338 diff changeset	2303 since the entries are generally not unique.) For set-like views, all of the
45e49269e0d8 Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from Georg Brandl <georg@python.org> parents: 66338 diff changeset	2304 operations defined for the abstract base class :class:`collections.Set` are
45e49269e0d8 Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from Georg Brandl <georg@python.org> parents: 66338 diff changeset	2305 available (for example, ``==``, ``<``, or ``^``).
43234 49d6fa98dc78 Docs on dictviews. Georg Brandl <georg@python.org> parents: 43233 diff changeset	2306
43236 3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2307 An example of dictionary view usage::
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2308
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2309 >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500}
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2310 >>> keys = dishes.keys()
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2311 >>> values = dishes.values()
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2312
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2313 >>> # iteration
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2314 >>> n = 0
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2315 >>> for val in values:
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2316 ... n += val
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2317 >>> print(n)
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2318 504
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2319
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2320 >>> # keys and values are iterated over in the same order
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2321 >>> list(keys)
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2322 ['eggs', 'bacon', 'sausage', 'spam']
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2323 >>> list(values)
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2324 [2, 1, 1, 500]
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2325
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2326 >>> # view objects are dynamic and reflect dict changes
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2327 >>> del dishes['eggs']
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2328 >>> del dishes['sausage']
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2329 >>> list(keys)
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2330 ['spam', 'bacon']
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2331
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2332 >>> # set operations
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2333 >>> keys & {'eggs', 'bacon', 'salad'}
49005 14249bcb93d0 correct an example Gregory P. Smith <greg@mad-scientist.com> parents: 48701 diff changeset	2334 {'bacon'}
66470 45e49269e0d8 Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from Georg Brandl <georg@python.org> parents: 66338 diff changeset	2335 >>> keys ^ {'sausage', 'juice'}
71697 a70cdec027e7 #12665: Dictionary view example has error in set operation Sandro Tosi <sandro.tosi@gmail.com> parents: 71634 diff changeset	2336 {'juice', 'sausage', 'bacon', 'spam'}
43236 3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2337
3484350a4f69 Add a dict view usage example. Georg Brandl <georg@python.org> parents: 43234 diff changeset	2338
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2339 .. _typememoryview:
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2340
60504 a65f91bbc2fb Merged revisions 79307,79408,79430,79533,79542,79579-79580,79585-79587,79607-79608,79622,79717,79820,79822,79828,79862,79875,79923-79924,79941-79943,79945,79947,79951-79952 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 60370 diff changeset	2341 memoryview type
a65f91bbc2fb Merged revisions 79307,79408,79430,79533,79542,79579-79580,79585-79587,79607-79608,79622,79717,79820,79822,79828,79862,79875,79923-79924,79941-79943,79945,79947,79951-79952 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 60370 diff changeset	2342 ===============
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2343
66860 99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66472 diff changeset	2344 :class:`memoryview` objects allow Python code to access the internal data
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66472 diff changeset	2345 of an object that supports the :ref:`buffer protocol <bufferobjects>` without
99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66472 diff changeset	2346 copying. Memory is generally interpreted as simple bytes.
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2347
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2348 .. class:: memoryview(obj)
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2349
49123 e90a3f0a9928 Some typos. Georg Brandl <georg@python.org> parents: 49121 diff changeset	2350 Create a :class:`memoryview` that references obj. obj must support the
68286 13bc0511b3d3 #11373: fix spelling. Georg Brandl <georg@python.org> parents: 68008 diff changeset	2351 buffer protocol. Built-in objects that support the buffer protocol include
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2352 :class:`bytes` and :class:`bytearray`.
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2353
62992 64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2354 A :class:`memoryview` has the notion of an element, which is the
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2355 atomic memory unit handled by the originating object obj. For many
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2356 simple types such as :class:`bytes` and :class:`bytearray`, an element
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2357 is a single byte, but other types such as :class:`array.array` may have
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2358 bigger elements.
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2359
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2360 ``len(view)`` returns the total number of elements in the memoryview,
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2361 view. The :class:`~memoryview.itemsize` attribute will give you the
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2362 number of bytes in a single element.
49136 348a33048ebf kill memoryview.size in favor of len(view) Benjamin Peterson <benjamin@python.org> parents: 49135 diff changeset	2363
49123 e90a3f0a9928 Some typos. Georg Brandl <georg@python.org> parents: 49121 diff changeset	2364 A :class:`memoryview` supports slicing to expose its data. Taking a single
62992 64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2365 index will return a single element as a :class:`bytes` object. Full
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2366 slicing will result in a subview::
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2367
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2368 >>> v = memoryview(b'abcefg')
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2369 >>> v[1]
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2370 b'b'
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2371 >>> v[-1]
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2372 b'g'
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2373 >>> v[1:4]
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2374 <memory at 0x77ab28>
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2375 >>> bytes(v[1:4])
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2376 b'bce'
62992 64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2377
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2378 If the object the memoryview is over supports changing its data, the
49123 e90a3f0a9928 Some typos. Georg Brandl <georg@python.org> parents: 49121 diff changeset	2379 memoryview supports slice assignment::
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2380
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2381 >>> data = bytearray(b'abcefg')
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2382 >>> v = memoryview(data)
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2383 >>> v.readonly
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2384 False
54820 1732a54a0272 must be bytes Benjamin Peterson <benjamin@python.org> parents: 54476 diff changeset	2385 >>> v[0] = b'z'
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2386 >>> data
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2387 bytearray(b'zbcefg')
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2388 >>> v[1:4] = b'123'
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2389 >>> data
75019 9ce5d456138b fix error in memoryview example; thanks to kan lianlian from docs@ Sandro Tosi <sandro.tosi@gmail.com> parents: 74617 diff changeset	2390 bytearray(b'z123fg')
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2391 >>> v[2] = b'spam'
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2392 Traceback (most recent call last):
75033 c3e0a0c79696 Indent 'File' in memoryview example, so it is correctly highlighted Sandro Tosi <sandro.tosi@gmail.com> parents: 75019 diff changeset	2393 File "<stdin>", line 1, in <module>
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2394 ValueError: cannot modify size of memoryview object
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2395
62962 365eeab4a350 Merged revisions 82301 via svnmerge from Georg Brandl <georg@python.org> parents: 62826 diff changeset	2396 Notice how the size of the memoryview object cannot be changed.
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2397
64584 ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2398 :class:`memoryview` has several methods:
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2399
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2400 .. method:: tobytes()
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2401
62992 64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2402 Return the data in the buffer as a bytestring. This is equivalent to
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2403 calling the :class:`bytes` constructor on the memoryview. ::
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2404
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2405 >>> m = memoryview(b"abc")
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2406 >>> m.tobytes()
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2407 b'abc'
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2408 >>> bytes(m)
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2409 b'abc'
49134 af40238a68b9 endow memoryview.tolist() with docs Benjamin Peterson <benjamin@python.org> parents: 49123 diff changeset	2410
af40238a68b9 endow memoryview.tolist() with docs Benjamin Peterson <benjamin@python.org> parents: 49123 diff changeset	2411 .. method:: tolist()
af40238a68b9 endow memoryview.tolist() with docs Benjamin Peterson <benjamin@python.org> parents: 49123 diff changeset	2412
af40238a68b9 endow memoryview.tolist() with docs Benjamin Peterson <benjamin@python.org> parents: 49123 diff changeset	2413 Return the data in the buffer as a list of integers. ::
af40238a68b9 endow memoryview.tolist() with docs Benjamin Peterson <benjamin@python.org> parents: 49123 diff changeset	2414
af40238a68b9 endow memoryview.tolist() with docs Benjamin Peterson <benjamin@python.org> parents: 49123 diff changeset	2415 >>> memoryview(b'abc').tolist()
af40238a68b9 endow memoryview.tolist() with docs Benjamin Peterson <benjamin@python.org> parents: 49123 diff changeset	2416 [97, 98, 99]
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2417
64584 ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2418 .. method:: release()
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2419
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2420 Release the underlying buffer exposed by the memoryview object. Many
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2421 objects take special actions when a view is held on them (for example,
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2422 a :class:`bytearray` would temporarily forbid resizing); therefore,
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2423 calling release() is handy to remove these restrictions (and free any
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2424 dangling resources) as soon as possible.
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2425
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2426 After this method has been called, any further operation on the view
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2427 raises a :class:`ValueError` (except :meth:`release()` itself which can
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2428 be called multiple times)::
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2429
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2430 >>> m = memoryview(b'abc')
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2431 >>> m.release()
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2432 >>> m[0]
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2433 Traceback (most recent call last):
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2434 File "<stdin>", line 1, in <module>
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2435 ValueError: operation forbidden on released memoryview object
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2436
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2437 The context management protocol can be used for a similar effect,
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2438 using the ``with`` statement::
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2439
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2440 >>> with memoryview(b'abc') as m:
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2441 ... m[0]
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2442 ...
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2443 b'a'
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2444 >>> m[0]
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2445 Traceback (most recent call last):
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2446 File "<stdin>", line 1, in <module>
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2447 ValueError: operation forbidden on released memoryview object
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2448
ba54096b7a42 Issue #9757: memoryview objects get a release() method to release the Antoine Pitrou <solipsis@pitrou.net> parents: 64377 diff changeset	2449 .. versionadded:: 3.2
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2450
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2451 There are also several readonly attributes available:
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2452
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2453 .. attribute:: format
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2454
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2455 A string containing the format (in :mod:`struct` module style) for each
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2456 element in the view. This defaults to ``'B'``, a simple bytestring.
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2457
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2458 .. attribute:: itemsize
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2459
62992 64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2460 The size in bytes of each element of the memoryview::
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2461
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2462 >>> m = memoryview(array.array('H', [1,2,3]))
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2463 >>> m.itemsize
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2464 2
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2465 >>> m[0]
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2466 b'\x01\x00'
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2467 >>> len(m[0]) == m.itemsize
64caa748a28e Merged revisions 82842 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 62962 diff changeset	2468 True
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2469
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2470 .. attribute:: shape
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2471
49123 e90a3f0a9928 Some typos. Georg Brandl <georg@python.org> parents: 49121 diff changeset	2472 A tuple of integers the length of :attr:`ndim` giving the shape of the
e90a3f0a9928 Some typos. Georg Brandl <georg@python.org> parents: 49121 diff changeset	2473 memory as a N-dimensional array.
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2474
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2475 .. attribute:: ndim
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2476
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2477 An integer indicating how many dimensions of a multi-dimensional array the
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2478 memory represents.
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2479
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2480 .. attribute:: strides
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2481
49135 589073cee0ae make use of shorter attribute access Benjamin Peterson <benjamin@python.org> parents: 49134 diff changeset	2482 A tuple of integers the length of :attr:`ndim` giving the size in bytes to
589073cee0ae make use of shorter attribute access Benjamin Peterson <benjamin@python.org> parents: 49134 diff changeset	2483 access each element for each dimension of the array.
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2484
68008 c79665fb267a Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from Georg Brandl <georg@python.org> parents: 67090 diff changeset	2485 .. attribute:: readonly
c79665fb267a Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from Georg Brandl <georg@python.org> parents: 67090 diff changeset	2486
c79665fb267a Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from Georg Brandl <georg@python.org> parents: 67090 diff changeset	2487 A bool indicating whether the memory is read only.
c79665fb267a Merged revisions 87101,87146,87156,87172,87175,87371,87378,87522-87524,87526-87528,87530-87536,87581 via svnmerge from Georg Brandl <georg@python.org> parents: 67090 diff changeset	2488
49121 dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2489 .. memoryview.suboffsets isn't documented because it only seems useful for C
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2490
dc19a1b7c5a6 document the memoryview object a little Benjamin Peterson <benjamin@python.org> parents: 49005 diff changeset	2491
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2492 .. _typecontextmanager:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2493
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2494 Context Manager Types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2495 =====================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2496
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2497 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2498 single: context manager
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2499 single: context management protocol
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2500 single: protocol; context management
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2501
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2502 Python's :keyword:`with` statement supports the concept of a runtime context
66860 99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66472 diff changeset	2503 defined by a context manager. This is implemented using a pair of methods
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2504 that allow user-defined classes to define a runtime context that is entered
66860 99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66472 diff changeset	2505 before the statement body is executed and exited when the statement ends:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2506
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2507
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2508 .. method:: contextmanager.__enter__()
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2509
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2510 Enter the runtime context and return either this object or another object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2511 related to the runtime context. The value returned by this method is bound to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2512 the identifier in the :keyword:`as` clause of :keyword:`with` statements using
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2513 this context manager.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2514
64767 61dfc79657d7 Merged revisions 84827-84829 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64159 diff changeset	2515 An example of a context manager that returns itself is a :term:`file object`.
61dfc79657d7 Merged revisions 84827-84829 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64159 diff changeset	2516 File objects return themselves from __enter__() to allow :func:`open` to be
61dfc79657d7 Merged revisions 84827-84829 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 64159 diff changeset	2517 used as the context expression in a :keyword:`with` statement.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2518
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2519 An example of a context manager that returns a related object is the one
44535 420fe6d7d5f4 Merged revisions 59703-59773 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44500 diff changeset	2520 returned by :func:`decimal.localcontext`. These managers set the active
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2521 decimal context to a copy of the original decimal context and then return the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2522 copy. This allows changes to be made to the current decimal context in the body
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2523 of the :keyword:`with` statement without affecting code outside the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2524 :keyword:`with` statement.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2525
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2526
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2527 .. method:: contextmanager.__exit__(exc_type, exc_val, exc_tb)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2528
43737 3d866579117d #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Georg Brandl <georg@python.org> parents: 43646 diff changeset	2529 Exit the runtime context and return a Boolean flag indicating if any exception
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2530 that occurred should be suppressed. If an exception occurred while executing the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2531 body of the :keyword:`with` statement, the arguments contain the exception type,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2532 value and traceback information. Otherwise, all three arguments are ``None``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2533
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2534 Returning a true value from this method will cause the :keyword:`with` statement
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2535 to suppress the exception and continue execution with the statement immediately
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2536 following the :keyword:`with` statement. Otherwise the exception continues
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2537 propagating after this method has finished executing. Exceptions that occur
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2538 during execution of this method will replace any exception that occurred in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2539 body of the :keyword:`with` statement.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2540
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2541 The exception passed in should never be reraised explicitly - instead, this
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2542 method should return a false value to indicate that the method completed
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2543 successfully and does not want to suppress the raised exception. This allows
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2544 context management code (such as ``contextlib.nested``) to easily detect whether
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2545 or not an :meth:`__exit__` method has actually failed.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2546
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2547 Python defines several context managers to support easy thread synchronisation,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2548 prompt closure of files or other objects, and simpler manipulation of the active
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2549 decimal arithmetic context. The specific types are not treated specially beyond
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2550 their implementation of the context management protocol. See the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2551 :mod:`contextlib` module for some examples.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2552
66860 99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66472 diff changeset	2553 Python's :term:`generator`\s and the :class:`contextlib.contextmanager` decorator
44104 ff1766eb2fce Merged revisions 59259-59274 via svnmerge from Christian Heimes <christian@cheimes.de> parents: 44052 diff changeset	2554 provide a convenient way to implement these protocols. If a generator function is
66860 99eca62d6919 Merged revisions 87188-87190,87192-87194 via svnmerge from Antoine Pitrou <solipsis@pitrou.net> parents: 66472 diff changeset	2555 decorated with the :class:`contextlib.contextmanager` decorator, it will return a
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2556 context manager implementing the necessary :meth:`__enter__` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2557 :meth:`__exit__` methods, rather than the iterator produced by an undecorated
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2558 generator function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2559
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2560 Note that there is no specific slot for any of these methods in the type
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2561 structure for Python objects in the Python/C API. Extension types wanting to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2562 define these methods must provide them as a normal Python accessible method.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2563 Compared to the overhead of setting up the runtime context, the overhead of a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2564 single class dictionary lookup is negligible.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2565
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2566
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2567 .. _typesother:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2568
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2569 Other Built-in Types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2570 ====================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2571
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2572 The interpreter supports several other kinds of objects. Most of these support
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2573 only one or two operations.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2574
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2575
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2576 .. _typesmodules:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2577
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2578 Modules
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2579 -------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2580
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2581 The only special operation on a module is attribute access: ``m.name``, where
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2582 m is a module and name accesses a name defined in m's symbol table.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2583 Module attributes can be assigned to. (Note that the :keyword:`import`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2584 statement is not, strictly speaking, an operation on a module object; ``import
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2585 foo`` does not require a module object named foo to exist, rather it requires
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2586 an (external) definition for a module named foo somewhere.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2587
71208 d442c313536b issue10403 - Let's not use members anymore. Use 'attribute' where it denotes attribute and 'methods' where it denotes methods. Context should clarify usage. Senthil Kumaran <senthil@uthcode.com> parents: 69951 diff changeset	2588 A special attribute of every module is :attr:`__dict__`. This is the dictionary
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2589 containing the module's symbol table. Modifying this dictionary will actually
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2590 change the module's symbol table, but direct assignment to the :attr:`__dict__`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2591 attribute is not possible (you can write ``m.__dict__['a'] = 1``, which defines
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2592 ``m.a`` to be ``1``, but you can't write ``m.__dict__ = {}``). Modifying
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2593 :attr:`__dict__` directly is not recommended.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2594
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2595 Modules built into the interpreter are written like this: ``<module 'sys'
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2596 (built-in)>``. If loaded from a file, they are written as ``<module 'os' from
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2597 '/usr/local/lib/pythonX.Y/os.pyc'>``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2598
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2599
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2600 .. _typesobjects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2601
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2602 Classes and Class Instances
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2603 ---------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2604
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2605 See :ref:`objects` and :ref:`class` for these.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2606
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2607
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2608 .. _typesfunctions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2609
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2610 Functions
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2611 ---------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2612
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2613 Function objects are created by function definitions. The only operation on a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2614 function object is to call it: ``func(argument-list)``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2615
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2616 There are really two flavors of function objects: built-in functions and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2617 user-defined functions. Both support the same operation (to call the function),
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2618 but the implementation is different, hence the different object types.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2619
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2620 See :ref:`function` for more information.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2621
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2622
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2623 .. _typesmethods:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2624
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2625 Methods
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2626 -------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2627
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2628 .. index:: object: method
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2629
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2630 Methods are functions that are called using the attribute notation. There are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2631 two flavors: built-in methods (such as :meth:`append` on lists) and class
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2632 instance methods. Built-in methods are described with the types that support
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2633 them.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2634
44028 0476457ffb39 Futher update docs after unbound method removal. Georg Brandl <georg@python.org> parents: 44026 diff changeset	2635 If you access a method (a function defined in a class namespace) through an
0476457ffb39 Futher update docs after unbound method removal. Georg Brandl <georg@python.org> parents: 44026 diff changeset	2636 instance, you get a special object: a :dfn:`bound method` (also called
0476457ffb39 Futher update docs after unbound method removal. Georg Brandl <georg@python.org> parents: 44026 diff changeset	2637 :dfn:`instance method`) object. When called, it will add the ``self`` argument
0476457ffb39 Futher update docs after unbound method removal. Georg Brandl <georg@python.org> parents: 44026 diff changeset	2638 to the argument list. Bound methods have two special read-only attributes:
0476457ffb39 Futher update docs after unbound method removal. Georg Brandl <georg@python.org> parents: 44026 diff changeset	2639 ``m.__self__`` is the object on which the method operates, and ``m.__func__`` is
0476457ffb39 Futher update docs after unbound method removal. Georg Brandl <georg@python.org> parents: 44026 diff changeset	2640 the function implementing the method. Calling ``m(arg-1, arg-2, ..., arg-n)``
0476457ffb39 Futher update docs after unbound method removal. Georg Brandl <georg@python.org> parents: 44026 diff changeset	2641 is completely equivalent to calling ``m.__func__(m.__self__, arg-1, arg-2, ...,
0476457ffb39 Futher update docs after unbound method removal. Georg Brandl <georg@python.org> parents: 44026 diff changeset	2642 arg-n)``.
0476457ffb39 Futher update docs after unbound method removal. Georg Brandl <georg@python.org> parents: 44026 diff changeset	2643
0476457ffb39 Futher update docs after unbound method removal. Georg Brandl <georg@python.org> parents: 44026 diff changeset	2644 Like function objects, bound method objects support getting arbitrary
0476457ffb39 Futher update docs after unbound method removal. Georg Brandl <georg@python.org> parents: 44026 diff changeset	2645 attributes. However, since method attributes are actually stored on the
0476457ffb39 Futher update docs after unbound method removal. Georg Brandl <georg@python.org> parents: 44026 diff changeset	2646 underlying function object (``meth.__func__``), setting method attributes on
0476457ffb39 Futher update docs after unbound method removal. Georg Brandl <georg@python.org> parents: 44026 diff changeset	2647 bound methods is disallowed. Attempting to set a method attribute results in a
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2648 :exc:`TypeError` being raised. In order to set a method attribute, you need to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2649 explicitly set it on the underlying function object::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2650
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2651 class C:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2652 def method(self):
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2653 pass
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2654
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2655 c = C()
44026 48af6375207e Removed the API to create unbound methods and simplified the API for bound methods. The signature is PyMethod_New(func, instance). Christian Heimes <christian@cheimes.de> parents: 43971 diff changeset	2656 c.method.__func__.whoami = 'my name is c'
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2657
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2658 See :ref:`types` for more information.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2659
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2660
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2661 .. _bltin-code-objects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2662
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2663 Code Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2664 ------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2665
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2666 .. index:: object: code
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2667
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2668 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2669 builtin: compile
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2670 single: __code__ (function object attribute)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2671
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2672 Code objects are used by the implementation to represent "pseudo-compiled"
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2673 executable Python code such as a function body. They differ from function
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2674 objects because they don't contain a reference to their global execution
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2675 environment. Code objects are returned by the built-in :func:`compile` function
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2676 and can be extracted from function objects through their :attr:`__code__`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2677 attribute. See also the :mod:`code` module.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2678
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2679 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2680 builtin: exec
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2681 builtin: eval
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2682
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2683 A code object can be executed or evaluated by passing it (instead of a source
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2684 string) to the :func:`exec` or :func:`eval` built-in functions.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2685
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2686 See :ref:`types` for more information.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2687
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2688
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2689 .. _bltin-type-objects:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2690
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2691 Type Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2692 ------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2693
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2694 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2695 builtin: type
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2696 module: types
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2697
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2698 Type objects represent the various object types. An object's type is accessed
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2699 by the built-in function :func:`type`. There are no special operations on
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2700 types. The standard module :mod:`types` defines names for all standard built-in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2701 types.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2702
46336 56e49952d1a4 Bug #2565: The repr() of type objects now calls them 'class', Martin v. Löwis <martin@v.loewis.de> parents: 46034 diff changeset	2703 Types are written like this: ``<class 'int'>``.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2704
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2705
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2706 .. _bltin-null-object:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2707
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2708 The Null Object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2709 ---------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2710
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2711 This object is returned by functions that don't explicitly return a value. It
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2712 supports no special operations. There is exactly one null object, named
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2713 ``None`` (a built-in name).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2714
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2715 It is written as ``None``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2716
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2717
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2718 .. _bltin-ellipsis-object:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2719
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2720 The Ellipsis Object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2721 -------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2722
43217 3436daf45516 Doc update for __xslice__ removal. Georg Brandl <georg@python.org> parents: 43197 diff changeset	2723 This object is commonly used by slicing (see :ref:`slicings`). It supports no
3436daf45516 Doc update for __xslice__ removal. Georg Brandl <georg@python.org> parents: 43197 diff changeset	2724 special operations. There is exactly one ellipsis object, named
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2725 :const:`Ellipsis` (a built-in name).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2726
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2727 It is written as ``Ellipsis`` or ``...``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2728
71634 99e9816b7d8b add space Benjamin Peterson <benjamin@python.org> parents: 71633 diff changeset	2729
72189 58dd7addef3a Add links from library/functions to other docs. Éric Araujo <merwok@netwok.org> parents: 71870 diff changeset	2730 .. _bltin-notimplemented-object:
58dd7addef3a Add links from library/functions to other docs. Éric Araujo <merwok@netwok.org> parents: 71870 diff changeset	2731
71633 1707b7d7da51 document NotImplemented Benjamin Peterson <benjamin@python.org> parents: 71544 diff changeset	2732 The NotImplemented Object
1707b7d7da51 document NotImplemented Benjamin Peterson <benjamin@python.org> parents: 71544 diff changeset	2733 -------------------------
1707b7d7da51 document NotImplemented Benjamin Peterson <benjamin@python.org> parents: 71544 diff changeset	2734
1707b7d7da51 document NotImplemented Benjamin Peterson <benjamin@python.org> parents: 71544 diff changeset	2735 This object is returned from comparisons and binary operations when they are
1707b7d7da51 document NotImplemented Benjamin Peterson <benjamin@python.org> parents: 71544 diff changeset	2736 asked to operate on types they don't support. See :ref:`comparisons` for more
1707b7d7da51 document NotImplemented Benjamin Peterson <benjamin@python.org> parents: 71544 diff changeset	2737 information.
1707b7d7da51 document NotImplemented Benjamin Peterson <benjamin@python.org> parents: 71544 diff changeset	2738
1707b7d7da51 document NotImplemented Benjamin Peterson <benjamin@python.org> parents: 71544 diff changeset	2739 It is written as ``NotImplemented``.
1707b7d7da51 document NotImplemented Benjamin Peterson <benjamin@python.org> parents: 71544 diff changeset	2740
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2741
72189 58dd7addef3a Add links from library/functions to other docs. Éric Araujo <merwok@netwok.org> parents: 71870 diff changeset	2742 .. _bltin-boolean-values:
58dd7addef3a Add links from library/functions to other docs. Éric Araujo <merwok@netwok.org> parents: 71870 diff changeset	2743
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2744 Boolean Values
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2745 --------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2746
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2747 Boolean values are the two constant objects ``False`` and ``True``. They are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2748 used to represent truth values (although other values can also be considered
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2749 false or true). In numeric contexts (for example when used as the argument to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2750 an arithmetic operator), they behave like the integers 0 and 1, respectively.
73813 69369fd3514b #13494: s/cast/convert/. Also add a link. Ezio Melotti <ezio.melotti@gmail.com> parents: 73735 diff changeset	2751 The built-in function :func:`bool` can be used to convert any value to a
69369fd3514b #13494: s/cast/convert/. Also add a link. Ezio Melotti <ezio.melotti@gmail.com> parents: 73735 diff changeset	2752 Boolean, if the value can be interpreted as a truth value (see section
69369fd3514b #13494: s/cast/convert/. Also add a link. Ezio Melotti <ezio.melotti@gmail.com> parents: 73735 diff changeset	2753 :ref:`truth` above).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2754
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2755 .. index::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2756 single: False
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2757 single: True
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2758 pair: Boolean; values
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2759
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2760 They are written as ``False`` and ``True``, respectively.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2761
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2762
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2763 .. _typesinternal:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2764
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2765 Internal Objects
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2766 ----------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2767
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2768 See :ref:`types` for this information. It describes stack frame objects,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2769 traceback objects, and slice objects.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2770
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2771
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2772 .. _specialattrs:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2773
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2774 Special Attributes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2775 ==================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2776
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2777 The implementation adds a few special read-only attributes to several object
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2778 types, where they are relevant. Some of these are not reported by the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2779 :func:`dir` built-in function.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2780
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2781
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2782 .. attribute:: object.__dict__
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2783
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2784 A dictionary or other mapping object used to store an object's (writable)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2785 attributes.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2786
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2787
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2788 .. attribute:: instance.__class__
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2789
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2790 The class to which a class instance belongs.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2791
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2792
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2793 .. attribute:: class.__bases__
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2794
58026 e078579984a4 Merged revisions 77167 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 57798 diff changeset	2795 The tuple of base classes of a class object.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2796
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2797
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2798 .. attribute:: class.__name__
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2799
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2800 The name of the class or type.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2801
52378 bb90ec67f314 Merged revisions 70648 via svnmerge from Georg Brandl <georg@python.org> parents: 52103 diff changeset	2802
52892 792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2803 .. attribute:: class.__mro__
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2804
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2805 This attribute is a tuple of classes that are considered when looking for
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2806 base classes during method resolution.
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2807
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2808
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2809 .. method:: class.mro()
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2810
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2811 This method can be overridden by a metaclass to customize the method
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2812 resolution order for its instances. It is called at class instantiation, and
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2813 its result is stored in :attr:`__mro__`.
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2814
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2815
52378 bb90ec67f314 Merged revisions 70648 via svnmerge from Georg Brandl <georg@python.org> parents: 52103 diff changeset	2816 .. method:: class.__subclasses__
bb90ec67f314 Merged revisions 70648 via svnmerge from Georg Brandl <georg@python.org> parents: 52103 diff changeset	2817
73153 54abca0ab03b Fixes #13270: obsolete reference to old-style/new-style classes. Florent Xicluna <florent.xicluna@gmail.com> parents: 72985 diff changeset	2818 Each class keeps a list of weak references to its immediate subclasses. This
54abca0ab03b Fixes #13270: obsolete reference to old-style/new-style classes. Florent Xicluna <florent.xicluna@gmail.com> parents: 72985 diff changeset	2819 method returns a list of all those references still alive.
52892 792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 52406 diff changeset	2820 Example::
52378 bb90ec67f314 Merged revisions 70648 via svnmerge from Georg Brandl <georg@python.org> parents: 52103 diff changeset	2821
bb90ec67f314 Merged revisions 70648 via svnmerge from Georg Brandl <georg@python.org> parents: 52103 diff changeset	2822 >>> int.__subclasses__()
73153 54abca0ab03b Fixes #13270: obsolete reference to old-style/new-style classes. Florent Xicluna <florent.xicluna@gmail.com> parents: 72985 diff changeset	2823 [<class 'bool'>]
52378 bb90ec67f314 Merged revisions 70648 via svnmerge from Georg Brandl <georg@python.org> parents: 52103 diff changeset	2824
bb90ec67f314 Merged revisions 70648 via svnmerge from Georg Brandl <georg@python.org> parents: 52103 diff changeset	2825
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2826 .. rubric:: Footnotes
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2827
71870 16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	2828 .. [1] Additional information on these special methods may be found in the Python
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2829 Reference Manual (:ref:`customization`).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2830
71870 16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	2831 .. [2] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0]``, and
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2832 similarly for tuples.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2833
71870 16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	2834 .. [3] They must have since the parser can't tell the type of the operands.
16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	2835
16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	2836 .. [4] Cased characters are those with general category property being one of
16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	2837 "Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecase).
16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	2838
16edc5cf4a79 #12204: document that str.upper().isupper() might be False and add a note about cased characters. Ezio Melotti <ezio.melotti@gmail.com> parents: 71697 diff changeset	2839 .. [5] To format only a tuple you should therefore provide a singleton tuple whose only
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2840 element is the tuple to be formatted.

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/stdtypes.rst @ 78069:a8aa77458e12 3.2