Mercurial > cpython-lru_cache-weakref

annotate Doc/library/stdtypes.rst @ 79675:c0a2294de787 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16199: Backport 2to3 typo fix from 3.2.
author Chris Jerdonek <chris.jerdonek@gmail.com>
date Thu, 11 Oct 2012 16:15:46 -0700
parents 8795cd3b4c8c
children 5fc6f47974db
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. XXX: reference/datamodel and this have quite a few overlaps!
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 .. _bltin-types:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 **************
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7 Built-in Types
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 **************
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 The following sections describe the standard types that are built into the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 interpreter.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 Historically (until release 2.2), Python's built-in types have differed from
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16 user-defined types because it was not possible to use the built-in types as the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 basis for object-oriented inheritance. This limitation no longer
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 exists.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 .. index:: pair: built-in; types
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 The principal built-in types are numerics, sequences, mappings, files, classes,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 instances and exceptions.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 .. index:: statement: print
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 Some operations are supported by several object types; in particular,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 practically all objects can be compared, tested for truth value, and converted
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 to a string (with the :func:`repr` function or the slightly different
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 :func:`str` function). The latter function is implicitly used when an object is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 written by the :func:`print` function.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 .. _truth:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 Truth Value Testing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 ===================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 statement: if
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 statement: while
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 pair: truth; value
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 pair: Boolean; operations
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 single: false
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 Any object can be tested for truth value, for use in an :keyword:`if` or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 :keyword:`while` condition or as operand of the Boolean operations below. The
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 following values are considered false:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 .. index:: single: None (Built-in object)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 * ``None``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
54 .. index:: single: False (Built-in object)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 * ``False``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 * zero of any numeric type, for example, ``0``, ``0L``, ``0.0``, ``0j``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 * any empty sequence, for example, ``''``, ``()``, ``[]``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 * any empty mapping, for example, ``{}``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 * instances of user-defined classes, if the class defines a :meth:`__nonzero__`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 or :meth:`__len__` method, when that method returns the integer zero or
71871
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
66 :class:`bool` value ``False``. [1]_
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68 .. index:: single: true
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 All other values are considered true --- so objects of many types are always
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 true.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 operator: or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 operator: and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 single: False
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 single: True
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 Operations and built-in functions that have a Boolean result always return ``0``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 or ``False`` for false and ``1`` or ``True`` for true, unless otherwise stated.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 (Important exception: the Boolean operations ``or`` and ``and`` always return
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 one of their operands.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 .. _boolean:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 Boolean Operations --- :keyword:`and`, :keyword:`or`, :keyword:`not`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 ====================================================================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 .. index:: pair: Boolean; operations
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 These are the Boolean operations, ordered by ascending priority:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 +-------------+---------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 | Operation | Result | Notes |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 +=============+=================================+=======+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 | ``x or y`` | if *x* is false, then *y*, else | \(1) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 | | *x* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 +-------------+---------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 | ``x and y`` | if *x* is false, then *x*, else | \(2) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 | | *y* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 +-------------+---------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 | ``not x`` | if *x* is false, then ``True``, | \(3) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 | | else ``False`` | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 +-------------+---------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 operator: and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109 operator: or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
110 operator: not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
111
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
112 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 This is a short-circuit operator, so it only evaluates the second
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 argument if the first one is :const:`False`.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 This is a short-circuit operator, so it only evaluates the second
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 argument if the first one is :const:`True`.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 ``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
126
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 .. _stdcomparisons:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
129 Comparisons
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
130 ===========
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131
56816
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
132 .. index::
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
133 pair: chaining; comparisons
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
134 pair: operator; comparison
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
135 operator: ==
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
136 operator: <
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
137 operator: <=
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
138 operator: >
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
139 operator: >=
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
140 operator: !=
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
141 operator: is
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
142 operator: is not
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
143
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 Comparison operations are supported by all objects. They all have the same
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
145 priority (which is higher than that of the Boolean operations). Comparisons can
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
146 be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
147 y <= z``, except that *y* is evaluated only once (but in both cases *z* is not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 evaluated at all when ``x < y`` is found to be false).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
150 This table summarizes the comparison operations:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
151
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
152 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
153 | Operation | Meaning | Notes |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 +============+=========================+=======+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
155 | ``<`` | strictly less than | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
156 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
157 | ``<=`` | less than or equal | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
159 | ``>`` | strictly greater than | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
160 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
161 | ``>=`` | greater than or equal | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
163 | ``==`` | equal | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
164 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
165 | ``!=`` | not equal | \(1) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
166 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
167 | ``is`` | object identity | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
169 | ``is not`` | negated object identity | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
170 +------------+-------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
171
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
172 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175 ``!=`` can also be written ``<>``, but this is an obsolete usage
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 kept for backwards compatibility only. New code should always use
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177 ``!=``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 pair: object; numeric
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 pair: objects; comparing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
182
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
183 Objects of different types, except different numeric types and different string
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
184 types, never compare equal; such objects are ordered consistently but
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185 arbitrarily (so that sorting a heterogeneous array yields a consistent result).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 Furthermore, some types (for example, file objects) support only a degenerate
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 notion of comparison where any two objects of that type are unequal. Again,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 such objects are ordered arbitrarily but consistently. The ``<``, ``<=``, ``>``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 and ``>=`` operators will raise a :exc:`TypeError` exception when any operand is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 a complex number.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
191
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192 .. index:: single: __cmp__() (instance method)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
194 Instances of a class normally compare as non-equal unless the class defines the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
195 :meth:`__cmp__` method. Refer to :ref:`customization`) for information on the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
196 use of this method to effect object comparisons.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
197
56824
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
198 .. impl-detail::
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
199
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
200 Objects of different types except numbers are ordered by their type names;
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
201 objects of the same types that don't support proper comparison are ordered by
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
202 their address.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
203
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
204 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
205 operator: in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 operator: not in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
207
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
208 Two more operations with the same syntactic priority, ``in`` and ``not in``, are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 supported only by sequence types (below).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
210
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
211
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
212 .. _typesnumeric:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
213
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
214 Numeric Types --- :class:`int`, :class:`float`, :class:`long`, :class:`complex`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 ===============================================================================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
217 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
218 object: numeric
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
219 object: Boolean
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220 object: integer
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
221 object: long integer
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 object: floating point
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
223 object: complex number
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
224 pair: C; language
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226 There are four distinct numeric types: :dfn:`plain integers`, :dfn:`long
63748
56ab9e111c1c Merged revisions 83732 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 63103
diff changeset
227 integers`, :dfn:`floating point numbers`, and :dfn:`complex numbers`. In
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228 addition, Booleans are a subtype of plain integers. Plain integers (also just
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74330
diff changeset
229 called :dfn:`integers`) are implemented using :c:type:`long` in C, which gives
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 them at least 32 bits of precision (``sys.maxint`` is always set to the maximum
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 plain integer value for the current platform, the minimum value is
63748
56ab9e111c1c Merged revisions 83732 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 63103
diff changeset
232 ``-sys.maxint - 1``). Long integers have unlimited precision. Floating point
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74330
diff changeset
233 numbers are usually implemented using :c:type:`double` in C; information about
63748
56ab9e111c1c Merged revisions 83732 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 63103
diff changeset
234 the precision and internal representation of floating point numbers for the
56ab9e111c1c Merged revisions 83732 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 63103
diff changeset
235 machine on which your program is running is available in
56ab9e111c1c Merged revisions 83732 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 63103
diff changeset
236 :data:`sys.float_info`. Complex numbers have a real and imaginary part, which
56ab9e111c1c Merged revisions 83732 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 63103
diff changeset
237 are each a floating point number. To extract these parts from a complex number
56ab9e111c1c Merged revisions 83732 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 63103
diff changeset
238 *z*, use ``z.real`` and ``z.imag``. (The standard library includes additional
56ab9e111c1c Merged revisions 83732 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 63103
diff changeset
239 numeric types, :mod:`fractions` that hold rationals, and :mod:`decimal` that
56ab9e111c1c Merged revisions 83732 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 63103
diff changeset
240 hold floating-point numbers with user-definable precision.)
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
241
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
242 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
243 pair: numeric; literals
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
244 pair: integer; literals
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
245 triple: long; integer; literals
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
246 pair: floating point; literals
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
247 pair: complex number; literals
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
248 pair: hexadecimal; literals
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
249 pair: octal; literals
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
250
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
251 Numbers are created by numeric literals or as the result of built-in functions
49619
06cf2cea387b Merged revisions 67060-67061 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 49171
diff changeset
252 and operators. Unadorned integer literals (including binary, hex, and octal
06cf2cea387b Merged revisions 67060-67061 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 49171
diff changeset
253 numbers) yield plain integers unless the value they denote is too large to be
06cf2cea387b Merged revisions 67060-67061 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 49171
diff changeset
254 represented as a plain integer, in which case they yield a long integer.
06cf2cea387b Merged revisions 67060-67061 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 49171
diff changeset
255 Integer literals with an ``'L'`` or ``'l'`` suffix yield long integers (``'L'``
06cf2cea387b Merged revisions 67060-67061 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 49171
diff changeset
256 is preferred because ``1l`` looks too much like eleven!). Numeric literals
06cf2cea387b Merged revisions 67060-67061 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 49171
diff changeset
257 containing a decimal point or an exponent sign yield floating point numbers.
06cf2cea387b Merged revisions 67060-67061 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 49171
diff changeset
258 Appending ``'j'`` or ``'J'`` to a numeric literal yields a complex number with a
06cf2cea387b Merged revisions 67060-67061 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 49171
diff changeset
259 zero real part. A complex numeric literal is the sum of a real and an imaginary
06cf2cea387b Merged revisions 67060-67061 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 49171
diff changeset
260 part.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
261
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
262 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
263 single: arithmetic
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
264 builtin: int
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 builtin: long
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
266 builtin: float
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
267 builtin: complex
56816
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
268 operator: +
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
269 operator: -
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
270 operator: *
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
271 operator: /
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
272 operator: //
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
273 operator: %
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
274 operator: **
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
275
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
276 Python fully supports mixed arithmetic: when a binary arithmetic operator has
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
277 operands of different numeric types, the operand with the "narrower" type is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
278 widened to that of the other, where plain integer is narrower than long integer
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
279 is narrower than floating point is narrower than complex. Comparisons between
71871
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
280 numbers of mixed type use the same rule. [2]_ The constructors :func:`int`,
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
281 :func:`long`, :func:`float`, and :func:`complex` can be used to produce numbers
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
282 of a specific type.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
283
56818
3e15a07a32fa Merged revisions 74209 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56817
diff changeset
284 All built-in numeric types support the following operations. See
44432
4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44383
diff changeset
285 :ref:`power` and later sections for the operators' priorities.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
286
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
287 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
288 | Operation | Result | Notes |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
289 +====================+=================================+========+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
290 | ``x + y`` | sum of *x* and *y* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
291 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
292 | ``x - y`` | difference of *x* and *y* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
293 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
294 | ``x * y`` | product of *x* and *y* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
295 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
296 | ``x / y`` | quotient of *x* and *y* | \(1) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
297 +--------------------+---------------------------------+--------+
44432
4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44383
diff changeset
298 | ``x // y`` | (floored) quotient of *x* and | (4)(5) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
299 | | *y* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
300 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
301 | ``x % y`` | remainder of ``x / y`` | \(4) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
302 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
303 | ``-x`` | *x* negated | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
304 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
305 | ``+x`` | *x* unchanged | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
306 +--------------------+---------------------------------+--------+
44432
4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44383
diff changeset
307 | ``abs(x)`` | absolute value or magnitude of | \(3) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
308 | | *x* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
309 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
310 | ``int(x)`` | *x* converted to integer | \(2) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
311 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
312 | ``long(x)`` | *x* converted to long integer | \(2) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
313 +--------------------+---------------------------------+--------+
44344
1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms).
Christian Heimes <christian@cheimes.de>
parents: 44320
diff changeset
314 | ``float(x)`` | *x* converted to floating point | \(6) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
315 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
316 | ``complex(re,im)`` | a complex number with real part | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
317 | | *re*, imaginary part *im*. | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
318 | | *im* defaults to zero. | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
319 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
320 | ``c.conjugate()`` | conjugate of the complex number | |
44432
4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44383
diff changeset
321 | | *c*. (Identity on real numbers) | |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
322 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
323 | ``divmod(x, y)`` | the pair ``(x // y, x % y)`` | (3)(4) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
324 +--------------------+---------------------------------+--------+
44526
507e76d7fcdd #1501: document that 0**0 == 1.
Georg Brandl <georg@python.org>
parents: 44525
diff changeset
325 | ``pow(x, y)`` | *x* to the power *y* | (3)(7) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
326 +--------------------+---------------------------------+--------+
44526
507e76d7fcdd #1501: document that 0**0 == 1.
Georg Brandl <georg@python.org>
parents: 44525
diff changeset
327 | ``x ** y`` | *x* to the power *y* | \(7) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
328 +--------------------+---------------------------------+--------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
329
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
330 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
331 triple: operations on; numeric; types
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
332 single: conjugate() (complex number method)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
333
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
334 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
335
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
336 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
337 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
338 pair: integer; division
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
339 triple: long; integer; division
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
340
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
341 For (plain or long) integer division, the result is an integer. The result is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
342 always rounded towards minus infinity: 1/2 is 0, (-1)/2 is -1, 1/(-2) is -1, and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
343 (-1)/(-2) is 0. Note that the result is a long integer if either operand is a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
344 long integer, regardless of the numeric value.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
345
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
346 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
347 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
348 module: math
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
349 single: floor() (in module math)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
350 single: ceil() (in module math)
50646
e496fdb927fa Merged revisions 68288-68291,68325-68326,68338,68388,68393,68423 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 50522
diff changeset
351 single: trunc() (in module math)
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
352 pair: numeric; conversions
50240
edb2eefb6856 Clarify the round-off behavior of int().
Raymond Hettinger <python@rcn.com>
parents: 49677
diff changeset
353
edb2eefb6856 Clarify the round-off behavior of int().
Raymond Hettinger <python@rcn.com>
parents: 49677
diff changeset
354 Conversion from floats using :func:`int` or :func:`long` truncates toward
edb2eefb6856 Clarify the round-off behavior of int().
Raymond Hettinger <python@rcn.com>
parents: 49677
diff changeset
355 zero like the related function, :func:`math.trunc`. Use the function
edb2eefb6856 Clarify the round-off behavior of int().
Raymond Hettinger <python@rcn.com>
parents: 49677
diff changeset
356 :func:`math.floor` to round downward and :func:`math.ceil` to round
edb2eefb6856 Clarify the round-off behavior of int().
Raymond Hettinger <python@rcn.com>
parents: 49677
diff changeset
357 upward.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
358
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
359 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
360 See :ref:`built-in-funcs` for a full description.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
361
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
362 (4)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
363 .. deprecated:: 2.3
66831
207ea9a05062 #10676: fix bad wording in parallel with the lang ref.
Georg Brandl <georg@python.org>
parents: 66824
diff changeset
364 The floor division operator, the modulo operator, and the :func:`divmod`
207ea9a05062 #10676: fix bad wording in parallel with the lang ref.
Georg Brandl <georg@python.org>
parents: 66824
diff changeset
365 function are no longer defined for complex numbers. Instead, convert to
207ea9a05062 #10676: fix bad wording in parallel with the lang ref.
Georg Brandl <georg@python.org>
parents: 66824
diff changeset
366 a floating point number using the :func:`abs` function if appropriate.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
367
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
368 (5)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
369 Also referred to as integer division. The resultant value is a whole integer,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
370 though the result's type is not necessarily int.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
371
44344
1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms).
Christian Heimes <christian@cheimes.de>
parents: 44320
diff changeset
372 (6)
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50240
diff changeset
373 float also accepts the strings "nan" and "inf" with an optional prefix "+"
44344
1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms).
Christian Heimes <christian@cheimes.de>
parents: 44320
diff changeset
374 or "-" for Not a Number (NaN) and positive or negative infinity.
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50240
diff changeset
375
44344
1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms).
Christian Heimes <christian@cheimes.de>
parents: 44320
diff changeset
376 .. versionadded:: 2.6
1d69aabf6f7f Applied patch #1635: Float patch for inf and nan on Windows (and other platforms).
Christian Heimes <christian@cheimes.de>
parents: 44320
diff changeset
377
44526
507e76d7fcdd #1501: document that 0**0 == 1.
Georg Brandl <georg@python.org>
parents: 44525
diff changeset
378 (7)
507e76d7fcdd #1501: document that 0**0 == 1.
Georg Brandl <georg@python.org>
parents: 44525
diff changeset
379 Python defines ``pow(0, 0)`` and ``0 ** 0`` to be ``1``, as is common for
507e76d7fcdd #1501: document that 0**0 == 1.
Georg Brandl <georg@python.org>
parents: 44525
diff changeset
380 programming languages.
507e76d7fcdd #1501: document that 0**0 == 1.
Georg Brandl <georg@python.org>
parents: 44525
diff changeset
381
44432
4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44383
diff changeset
382 All :class:`numbers.Real` types (:class:`int`, :class:`long`, and
4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44383
diff changeset
383 :class:`float`) also include the following operations:
4f9723d9ca32 Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44383
diff changeset
384
44488
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44432
diff changeset
385 +--------------------+------------------------------------+--------+
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44432
diff changeset
386 | Operation | Result | Notes |
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44432
diff changeset
387 +====================+====================================+========+
51809
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50646
diff changeset
388 | ``math.trunc(x)`` | *x* truncated to Integral | |
44488
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44432
diff changeset
389 +--------------------+------------------------------------+--------+
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44432
diff changeset
390 | ``round(x[, n])`` | *x* rounded to n digits, | |
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44432
diff changeset
391 | | rounding half to even. If n is | |
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44432
diff changeset
392 | | omitted, it defaults to 0. | |
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44432
diff changeset
393 +--------------------+------------------------------------+--------+
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44432
diff changeset
394 | ``math.floor(x)`` | the greatest integral float <= *x* | |
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44432
diff changeset
395 +--------------------+------------------------------------+--------+
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44432
diff changeset
396 | ``math.ceil(x)`` | the least integral float >= *x* | |
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44432
diff changeset
397 +--------------------+------------------------------------+--------+
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44344
diff changeset
398
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44344
diff changeset
399 .. XXXJH exceptions: overflow (when? what operations?) zerodivision
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
400
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
401
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
402 .. _bitstring-ops:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
403
74618
6af7eb71cd49 say bitwise (because I have no idea what a bit-string is)
Benjamin Peterson <benjamin@python.org>
parents: 74584
diff changeset
404 Bitwise Operations on Integer Types
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
405 --------------------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
406
56816
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
407 .. index::
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
408 triple: operations on; integer; types
74618
6af7eb71cd49 say bitwise (because I have no idea what a bit-string is)
Benjamin Peterson <benjamin@python.org>
parents: 74584
diff changeset
409 pair: bitwise; operations
56816
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
410 pair: shifting; operations
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
411 pair: masking; operations
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
412 operator: ^
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
413 operator: &
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
414 operator: <<
66de7111230a Merged revisions 74008,74021-74022,74074-74075,74077,74148,74179,74188,74192-74194,74200,74205 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56814
diff changeset
415 operator: >>
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
416
74619
ed6d9249da0c kill extra word
Benjamin Peterson <benjamin@python.org>
parents: 74618
diff changeset
417 Bitwise operations only make sense for integers. Negative numbers are treated
ed6d9249da0c kill extra word
Benjamin Peterson <benjamin@python.org>
parents: 74618
diff changeset
418 as their 2's complement value (this assumes a sufficiently large number of bits
ed6d9249da0c kill extra word
Benjamin Peterson <benjamin@python.org>
parents: 74618
diff changeset
419 that no overflow occurs during the operation).
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
420
44497
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
421 The priorities of the binary bitwise operations are all lower than the numeric
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
422 operations and higher than the comparisons; the unary operation ``~`` has the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
423 same priority as the other unary numeric operations (``+`` and ``-``).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
424
74618
6af7eb71cd49 say bitwise (because I have no idea what a bit-string is)
Benjamin Peterson <benjamin@python.org>
parents: 74584
diff changeset
425 This table lists the bitwise operations sorted in ascending priority
6af7eb71cd49 say bitwise (because I have no idea what a bit-string is)
Benjamin Peterson <benjamin@python.org>
parents: 74584
diff changeset
426 (operations in the same box have the same priority):
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
427
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
428 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
429 | Operation | Result | Notes |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
430 +============+================================+==========+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
431 | ``x | y`` | bitwise :dfn:`or` of *x* and | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
432 | | *y* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
433 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
434 | ``x ^ y`` | bitwise :dfn:`exclusive or` of | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
435 | | *x* and *y* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
436 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
437 | ``x & y`` | bitwise :dfn:`and` of *x* and | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
438 | | *y* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
439 +------------+--------------------------------+----------+
44555
7ea231578b02 Consistency nit.
Georg Brandl <georg@python.org>
parents: 44553
diff changeset
440 | ``x << n`` | *x* shifted left by *n* bits | (1)(2) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
441 +------------+--------------------------------+----------+
44555
7ea231578b02 Consistency nit.
Georg Brandl <georg@python.org>
parents: 44553
diff changeset
442 | ``x >> n`` | *x* shifted right by *n* bits | (1)(3) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
443 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
444 | ``~x`` | the bits of *x* inverted | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
445 +------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
446
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
447 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
448
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
449 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
450 Negative shift counts are illegal and cause a :exc:`ValueError` to be raised.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
451
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
452 (2)
46876
f4e61dcdb6f8 #2147: PEP 237 changes to overflow behavior.
Georg Brandl <georg@python.org>
parents: 46870
diff changeset
453 A left shift by *n* bits is equivalent to multiplication by ``pow(2, n)``. A
f4e61dcdb6f8 #2147: PEP 237 changes to overflow behavior.
Georg Brandl <georg@python.org>
parents: 46870
diff changeset
454 long integer is returned if the result exceeds the range of plain integers.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
455
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
456 (3)
46876
f4e61dcdb6f8 #2147: PEP 237 changes to overflow behavior.
Georg Brandl <georg@python.org>
parents: 46870
diff changeset
457 A right shift by *n* bits is equivalent to division by ``pow(2, n)``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
458
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
459
50205
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
460 Additional Methods on Integer Types
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
461 -----------------------------------
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
462
69773
d7cd797842c0 Fix grammar to include both integer types in 2.x
Éric Araujo <merwok@netwok.org>
parents: 69756
diff changeset
463 The integer types implement the :class:`numbers.Integral` :term:`abstract base
d7cd797842c0 Fix grammar to include both integer types in 2.x
Éric Araujo <merwok@netwok.org>
parents: 69756
diff changeset
464 class`. In addition, they provide one more method:
69750
5b315145e525 note abcs of int and float (closes #11977)
Benjamin Peterson <benjamin@python.org>
parents: 68761
diff changeset
465
50205
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
466 .. method:: int.bit_length()
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
467 .. method:: long.bit_length()
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
468
50222
9a1890982489 Fix-up and clean-up docs for int.bit_length().
Raymond Hettinger <python@rcn.com>
parents: 50205
diff changeset
469 Return the number of bits necessary to represent an integer in binary,
9a1890982489 Fix-up and clean-up docs for int.bit_length().
Raymond Hettinger <python@rcn.com>
parents: 50205
diff changeset
470 excluding the sign and leading zeros::
9a1890982489 Fix-up and clean-up docs for int.bit_length().
Raymond Hettinger <python@rcn.com>
parents: 50205
diff changeset
471
9a1890982489 Fix-up and clean-up docs for int.bit_length().
Raymond Hettinger <python@rcn.com>
parents: 50205
diff changeset
472 >>> n = -37
50205
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
473 >>> bin(n)
50222
9a1890982489 Fix-up and clean-up docs for int.bit_length().
Raymond Hettinger <python@rcn.com>
parents: 50205
diff changeset
474 '-0b100101'
50205
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
475 >>> n.bit_length()
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
476 6
50222
9a1890982489 Fix-up and clean-up docs for int.bit_length().
Raymond Hettinger <python@rcn.com>
parents: 50205
diff changeset
477
9a1890982489 Fix-up and clean-up docs for int.bit_length().
Raymond Hettinger <python@rcn.com>
parents: 50205
diff changeset
478 More precisely, if ``x`` is nonzero, then ``x.bit_length()`` is the
9a1890982489 Fix-up and clean-up docs for int.bit_length().
Raymond Hettinger <python@rcn.com>
parents: 50205
diff changeset
479 unique positive integer ``k`` such that ``2**(k-1) <= abs(x) < 2**k``.
9a1890982489 Fix-up and clean-up docs for int.bit_length().
Raymond Hettinger <python@rcn.com>
parents: 50205
diff changeset
480 Equivalently, when ``abs(x)`` is small enough to have a correctly
9a1890982489 Fix-up and clean-up docs for int.bit_length().
Raymond Hettinger <python@rcn.com>
parents: 50205
diff changeset
481 rounded logarithm, then ``k = 1 + int(log(abs(x), 2))``.
9a1890982489 Fix-up and clean-up docs for int.bit_length().
Raymond Hettinger <python@rcn.com>
parents: 50205
diff changeset
482 If ``x`` is zero, then ``x.bit_length()`` returns ``0``.
50205
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
483
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
484 Equivalent to::
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
485
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
486 def bit_length(self):
50229
496dff47bc7e Fix typo in Python equivalent for bit_length.
Mark Dickinson <dickinsm@gmail.com>
parents: 50222
diff changeset
487 s = bin(self) # binary representation: bin(-37) --> '-0b100101'
50222
9a1890982489 Fix-up and clean-up docs for int.bit_length().
Raymond Hettinger <python@rcn.com>
parents: 50205
diff changeset
488 s = s.lstrip('-0b') # remove leading zeros and minus sign
9a1890982489 Fix-up and clean-up docs for int.bit_length().
Raymond Hettinger <python@rcn.com>
parents: 50205
diff changeset
489 return len(s) # len('100101') --> 6
50205
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
490
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
491 .. versionadded:: 2.7
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
492
f0db06f49a4e Issue #3439: add bit_length method to int and long.
Mark Dickinson <dickinsm@gmail.com>
parents: 49677
diff changeset
493
47966
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
494 Additional Methods on Float
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
495 ---------------------------
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
496
69750
5b315145e525 note abcs of int and float (closes #11977)
Benjamin Peterson <benjamin@python.org>
parents: 68761
diff changeset
497 The float type implements the :class:`numbers.Real` :term:`abstract base
5b315145e525 note abcs of int and float (closes #11977)
Benjamin Peterson <benjamin@python.org>
parents: 68761
diff changeset
498 class`. float also has the following additional methods.
49171
52ef95bdd801 #3288: Document as_integer_ratio
Andrew M. Kuchling <amk@amk.ca>
parents: 48097
diff changeset
499
52ef95bdd801 #3288: Document as_integer_ratio
Andrew M. Kuchling <amk@amk.ca>
parents: 48097
diff changeset
500 .. method:: float.as_integer_ratio()
52ef95bdd801 #3288: Document as_integer_ratio
Andrew M. Kuchling <amk@amk.ca>
parents: 48097
diff changeset
501
66060
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
502 Return a pair of integers whose ratio is exactly equal to the
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
503 original float and with a positive denominator. Raises
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
504 :exc:`OverflowError` on infinities and a :exc:`ValueError` on
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
505 NaNs.
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
506
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
507 .. versionadded:: 2.6
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
508
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
509 .. method:: float.is_integer()
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
510
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
511 Return ``True`` if the float instance is finite with integral
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
512 value, and ``False`` otherwise::
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
513
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
514 >>> (-2.0).is_integer()
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
515 True
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
516 >>> (3.2).is_integer()
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
517 False
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
518
5384e4e46374 Merged revisions 86293 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 65704
diff changeset
519 .. versionadded:: 2.6
49171
52ef95bdd801 #3288: Document as_integer_ratio
Andrew M. Kuchling <amk@amk.ca>
parents: 48097
diff changeset
520
52ef95bdd801 #3288: Document as_integer_ratio
Andrew M. Kuchling <amk@amk.ca>
parents: 48097
diff changeset
521 Two methods support conversion to
47966
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
522 and from hexadecimal strings. Since Python's floats are stored
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
523 internally as binary numbers, converting a float to or from a
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
524 *decimal* string usually involves a small rounding error. In
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
525 contrast, hexadecimal strings allow exact representation and
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
526 specification of floating-point numbers. This can be useful when
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
527 debugging, and in numerical work.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
528
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
529
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
530 .. method:: float.hex()
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
531
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
532 Return a representation of a floating-point number as a hexadecimal
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
533 string. For finite floating-point numbers, this representation
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
534 will always include a leading ``0x`` and a trailing ``p`` and
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
535 exponent.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
536
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
537 .. versionadded:: 2.6
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
538
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
539
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
540 .. method:: float.fromhex(s)
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
541
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
542 Class method to return the float represented by a hexadecimal
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
543 string *s*. The string *s* may have leading and trailing
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
544 whitespace.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
545
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
546 .. versionadded:: 2.6
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
547
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
548
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
549 Note that :meth:`float.hex` is an instance method, while
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
550 :meth:`float.fromhex` is a class method.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
551
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
552 A hexadecimal string takes the form::
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
553
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
554 [sign] ['0x'] integer ['.' fraction] ['p' exponent]
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
555
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
556 where the optional ``sign`` may by either ``+`` or ``-``, ``integer``
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
557 and ``fraction`` are strings of hexadecimal digits, and ``exponent``
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
558 is a decimal integer with an optional leading sign. Case is not
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
559 significant, and there must be at least one hexadecimal digit in
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
560 either the integer or the fraction. This syntax is similar to the
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
561 syntax specified in section 6.4.4.2 of the C99 standard, and also to
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
562 the syntax used in Java 1.5 onwards. In particular, the output of
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
563 :meth:`float.hex` is usable as a hexadecimal floating-point literal in
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
564 C or Java code, and hexadecimal strings produced by C's ``%a`` format
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
565 character or Java's ``Double.toHexString`` are accepted by
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
566 :meth:`float.fromhex`.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
567
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
568
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
569 Note that the exponent is written in decimal rather than hexadecimal,
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
570 and that it gives the power of 2 by which to multiply the coefficient.
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
571 For example, the hexadecimal string ``0x3.a7p10`` represents the
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
572 floating-point number ``(3 + 10./16 + 7./16**2) * 2.0**10``, or
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
573 ``3740.0``::
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
574
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
575 >>> float.fromhex('0x3.a7p10')
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
576 3740.0
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
577
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
578
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
579 Applying the reverse conversion to ``3740.0`` gives a different
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
580 hexadecimal string representing the same number::
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
581
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
582 >>> float.hex(3740.0)
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
583 '0x1.d380000000000p+11'
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
584
97ba936e8df8 Issue #3008: add instance method float.hex and class method float.fromhex
Mark Dickinson <dickinsm@gmail.com>
parents: 47937
diff changeset
585
47971
01fbe3fc883e Move label to correct heading.
Georg Brandl <georg@python.org>
parents: 47966
diff changeset
586 .. _typeiter:
01fbe3fc883e Move label to correct heading.
Georg Brandl <georg@python.org>
parents: 47966
diff changeset
587
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
588 Iterator Types
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
589 ==============
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
590
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
591 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
592
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
593 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
594 single: iterator protocol
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
595 single: protocol; iterator
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
596 single: sequence; iteration
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
597 single: container; iteration over
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
598
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
599 Python supports a concept of iteration over containers. This is implemented
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
600 using two distinct methods; these are used to allow user-defined classes to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
601 support iteration. Sequences, described below in more detail, always support
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
602 the iteration methods.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
604 One method needs to be defined for container objects to provide iteration
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
605 support:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
606
44578
19e1fa78d330 Fix two further doc build warnings.
Georg Brandl <georg@python.org>
parents: 44563
diff changeset
607 .. XXX duplicated in reference/datamodel!
19e1fa78d330 Fix two further doc build warnings.
Georg Brandl <georg@python.org>
parents: 44563
diff changeset
608
19e1fa78d330 Fix two further doc build warnings.
Georg Brandl <georg@python.org>
parents: 44563
diff changeset
609 .. method:: container.__iter__()
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
610
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
611 Return an iterator object. The object is required to support the iterator
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
612 protocol described below. If a container supports different types of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
613 iteration, additional methods can be provided to specifically request
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
614 iterators for those iteration types. (An example of an object supporting
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
615 multiple forms of iteration would be a tree structure which supports both
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
616 breadth-first and depth-first traversal.) This method corresponds to the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
617 :attr:`tp_iter` slot of the type structure for Python objects in the Python/C
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
618 API.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
619
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
620 The iterator objects themselves are required to support the following two
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
621 methods, which together form the :dfn:`iterator protocol`:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
622
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
623
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
624 .. method:: iterator.__iter__()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
625
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
626 Return the iterator object itself. This is required to allow both containers
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
627 and iterators to be used with the :keyword:`for` and :keyword:`in` statements.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
628 This method corresponds to the :attr:`tp_iter` slot of the type structure for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
629 Python objects in the Python/C API.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
630
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
631
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
632 .. method:: iterator.next()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
633
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
634 Return the next item from the container. If there are no further items, raise
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
635 the :exc:`StopIteration` exception. This method corresponds to the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
636 :attr:`tp_iternext` slot of the type structure for Python objects in the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
637 Python/C API.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
638
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
639 Python defines several iterator objects to support iteration over general and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
640 specific sequence types, dictionaries, and other more specialized forms. The
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
641 specific types are not important beyond their implementation of the iterator
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
642 protocol.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
643
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
644 The intention of the protocol is that once an iterator's :meth:`next` method
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
645 raises :exc:`StopIteration`, it will continue to do so on subsequent calls.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
646 Implementations that do not obey this property are deemed broken. (This
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
647 constraint was added in Python 2.3; in Python 2.2, various iterators are broken
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
648 according to this rule.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
649
56814
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56803
diff changeset
650
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56803
diff changeset
651 .. _generator-types:
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56803
diff changeset
652
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56803
diff changeset
653 Generator Types
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56803
diff changeset
654 ---------------
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56803
diff changeset
655
43629
4f662ba09f1f Add :term: for generators.
Georg Brandl <georg@python.org>
parents: 43627
diff changeset
656 Python's :term:`generator`\s provide a convenient way to implement the iterator
4f662ba09f1f Add :term: for generators.
Georg Brandl <georg@python.org>
parents: 43627
diff changeset
657 protocol. If a container object's :meth:`__iter__` method is implemented as a
4f662ba09f1f Add :term: for generators.
Georg Brandl <georg@python.org>
parents: 43627
diff changeset
658 generator, it will automatically return an iterator object (technically, a
56814
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56803
diff changeset
659 generator object) supplying the :meth:`__iter__` and :meth:`next` methods. More
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56803
diff changeset
660 information about generators can be found in :ref:`the documentation for the
127d623396ab Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56803
diff changeset
661 yield expression <yieldexpr>`.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
662
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
663
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
664 .. _typesseq:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
665
66313
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
666 Sequence Types --- :class:`str`, :class:`unicode`, :class:`list`, :class:`tuple`, :class:`bytearray`, :class:`buffer`, :class:`xrange`
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
667 ======================================================================================================================================
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
668
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
669 There are seven sequence types: strings, Unicode strings, lists, tuples,
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
670 bytearrays, buffers, and xrange objects.
51809
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50646
diff changeset
671
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50646
diff changeset
672 For other containers see the built in :class:`dict` and :class:`set` classes,
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50646
diff changeset
673 and the :mod:`collections` module.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
674
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
675
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
676 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
677 object: sequence
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
678 object: string
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
679 object: Unicode
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
680 object: tuple
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
681 object: list
66313
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
682 object: bytearray
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
683 object: buffer
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
684 object: xrange
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
685
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
686 String literals are written in single or double quotes: ``'xyzzy'``,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
687 ``"frobozz"``. See :ref:`strings` for more about string literals.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
688 Unicode strings are much like strings, but are specified in the syntax
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
689 using a preceding ``'u'`` character: ``u'abc'``, ``u"def"``. In addition
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
690 to the functionality described here, there are also string-specific
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
691 methods described in the :ref:`string-methods` section. Lists are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
692 constructed with square brackets, separating items with commas: ``[a, b, c]``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
693 Tuples are constructed by the comma operator (not within square
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
694 brackets), with or without enclosing parentheses, but an empty tuple
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
695 must have the enclosing parentheses, such as ``a, b, c`` or ``()``. A
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
696 single item tuple must have a trailing comma, such as ``(d,)``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
697
66313
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
698 Bytearray objects are created with the built-in function :func:`bytearray`.
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
699
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
700 Buffer objects are not directly supported by Python syntax, but can be created
56818
3e15a07a32fa Merged revisions 74209 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56817
diff changeset
701 by calling the built-in function :func:`buffer`. They don't support
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
702 concatenation or repetition.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
703
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
704 Objects of type xrange are similar to buffers in that there is no specific syntax to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
705 create them, but they are created using the :func:`xrange` function. They don't
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
706 support slicing, concatenation or repetition, and using ``in``, ``not in``,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
707 :func:`min` or :func:`max` on them is inefficient.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
708
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
709 Most sequence types support the following operations. The ``in`` and ``not in``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
710 operations have the same priorities as the comparison operations. The ``+`` and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
711 ``*`` operations have the same priority as the corresponding numeric operations.
71871
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
712 [3]_ Additional methods are provided for :ref:`typesseq-mutable`.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
713
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
714 This table lists the sequence operations sorted in ascending priority
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
715 (operations in the same box have the same priority). In the table, *s* and *t*
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
716 are sequences of the same type; *n*, *i* and *j* are integers:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
717
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
718 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
719 | Operation | Result | Notes |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
720 +==================+================================+==========+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
721 | ``x in s`` | ``True`` if an item of *s* is | \(1) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
722 | | equal to *x*, else ``False`` | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
723 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
724 | ``x not in s`` | ``False`` if an item of *s* is | \(1) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
725 | | equal to *x*, else ``True`` | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
726 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
727 | ``s + t`` | the concatenation of *s* and | \(6) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
728 | | *t* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
729 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
730 | ``s * n, n * s`` | *n* shallow copies of *s* | \(2) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
731 | | concatenated | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
732 +------------------+--------------------------------+----------+
74584
f4f9ab2fd51b #13816: fix two minor style issues. Thanks to Justin Wehnes for the patch.
Georg Brandl <georg@python.org>
parents: 74469
diff changeset
733 | ``s[i]`` | *i*\ th item of *s*, origin 0 | \(3) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
734 +------------------+--------------------------------+----------+
44555
7ea231578b02 Consistency nit.
Georg Brandl <georg@python.org>
parents: 44553
diff changeset
735 | ``s[i:j]`` | slice of *s* from *i* to *j* | (3)(4) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
736 +------------------+--------------------------------+----------+
44555
7ea231578b02 Consistency nit.
Georg Brandl <georg@python.org>
parents: 44553
diff changeset
737 | ``s[i:j:k]`` | slice of *s* from *i* to *j* | (3)(5) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
738 | | with step *k* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
739 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
740 | ``len(s)`` | length of *s* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
741 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
742 | ``min(s)`` | smallest item of *s* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
743 +------------------+--------------------------------+----------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
744 | ``max(s)`` | largest item of *s* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
745 +------------------+--------------------------------+----------+
66339
837ad5854fc9 Merged revisions 86625 via svnmerge from
Éric Araujo <merwok@netwok.org>
parents: 66313
diff changeset
746 | ``s.index(i)`` | index of the first occurence | |
837ad5854fc9 Merged revisions 86625 via svnmerge from
Éric Araujo <merwok@netwok.org>
parents: 66313
diff changeset
747 | | of *i* in *s* | |
837ad5854fc9 Merged revisions 86625 via svnmerge from
Éric Araujo <merwok@netwok.org>
parents: 66313
diff changeset
748 +------------------+--------------------------------+----------+
837ad5854fc9 Merged revisions 86625 via svnmerge from
Éric Araujo <merwok@netwok.org>
parents: 66313
diff changeset
749 | ``s.count(i)`` | total number of occurences of | |
837ad5854fc9 Merged revisions 86625 via svnmerge from
Éric Araujo <merwok@netwok.org>
parents: 66313
diff changeset
750 | | *i* in *s* | |
837ad5854fc9 Merged revisions 86625 via svnmerge from
Éric Araujo <merwok@netwok.org>
parents: 66313
diff changeset
751 +------------------+--------------------------------+----------+
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
752
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
753 Sequence types also support comparisons. In particular, tuples and lists
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
754 are compared lexicographically by comparing corresponding
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
755 elements. This means that to compare equal, every element must compare
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
756 equal and the two sequences must be of the same type and have the same
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
757 length. (For full details see :ref:`comparisons` in the language
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
758 reference.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
759
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
760 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
761 triple: operations on; sequence; types
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
762 builtin: len
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
763 builtin: min
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
764 builtin: max
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
765 pair: concatenation; operation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
766 pair: repetition; operation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
767 pair: subscript; operation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
768 pair: slice; operation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
769 pair: extended slice; operation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
770 operator: in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
771 operator: not in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
772
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
773 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
774
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
775 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
776 When *s* is a string or Unicode string object the ``in`` and ``not in``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
777 operations act like a substring test. In Python versions before 2.3, *x* had to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
778 be a string of length 1. In Python 2.3 and beyond, *x* may be a string of any
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
779 length.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
780
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
781 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
782 Values of *n* less than ``0`` are treated as ``0`` (which yields an empty
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
783 sequence of the same type as *s*). Note also that the copies are shallow;
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
784 nested structures are not copied. This often haunts new Python programmers;
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 45800
diff changeset
785 consider:
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
786
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
787 >>> lists = [[]] * 3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
788 >>> lists
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
789 [[], [], []]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
790 >>> lists[0].append(3)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
791 >>> lists
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
792 [[3], [3], [3]]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
793
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
794 What has happened is that ``[[]]`` is a one-element list containing an empty
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
795 list, so all three elements of ``[[]] * 3`` are (pointers to) this single empty
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
796 list. Modifying any of the elements of ``lists`` modifies this single list.
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 45800
diff changeset
797 You can create a list of different lists this way:
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
798
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
799 >>> lists = [[] for i in range(3)]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
800 >>> lists[0].append(3)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
801 >>> lists[1].append(5)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
802 >>> lists[2].append(7)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
803 >>> lists
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
804 [[3], [5], [7]]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
805
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
806 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
807 If *i* or *j* is negative, the index is relative to the end of the string:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
808 ``len(s) + i`` or ``len(s) + j`` is substituted. But note that ``-0`` is still
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
809 ``0``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
810
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
811 (4)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
812 The slice of *s* from *i* to *j* is defined as the sequence of items with index
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
813 *k* such that ``i <= k < j``. If *i* or *j* is greater than ``len(s)``, use
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
814 ``len(s)``. If *i* is omitted or ``None``, use ``0``. If *j* is omitted or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
815 ``None``, use ``len(s)``. If *i* is greater than or equal to *j*, the slice is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
816 empty.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
817
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
818 (5)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
819 The slice of *s* from *i* to *j* with step *k* is defined as the sequence of
44320
211abcfb4928 Remove gratuitous unicode character.
Georg Brandl <georg@python.org>
parents: 44103
diff changeset
820 items with index ``x = i + n*k`` such that ``0 <= n < (j-i)/k``. In other words,
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
821 the indices are ``i``, ``i+k``, ``i+2*k``, ``i+3*k`` and so on, stopping when
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
822 *j* is reached (but never including *j*). If *i* or *j* is greater than
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
823 ``len(s)``, use ``len(s)``. If *i* or *j* are omitted or ``None``, they become
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
824 "end" values (which end depends on the sign of *k*). Note, *k* cannot be zero.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
825 If *k* is ``None``, it is treated like ``1``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
826
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
827 (6)
56824
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
828 .. impl-detail::
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
829
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
830 If *s* and *t* are both strings, some Python implementations such as
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
831 CPython can usually perform an in-place optimization for assignments of
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
832 the form ``s = s + t`` or ``s += t``. When applicable, this optimization
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
833 makes quadratic run-time much less likely. This optimization is both
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
834 version and implementation dependent. For performance sensitive code, it
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
835 is preferable to use the :meth:`str.join` method which assures consistent
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
836 linear concatenation performance across versions and implementations.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
837
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
838 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
839 Formerly, string concatenation never occurred in-place.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
840
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
841
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
842 .. _string-methods:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
843
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
844 String Methods
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
845 --------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
846
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
847 .. index:: pair: string; methods
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
848
56093
f64c0eb8cc62 add keyword arguments support to str/unicode encode and decode #6300
Benjamin Peterson <benjamin@python.org>
parents: 55838
diff changeset
849 Below are listed the string methods which both 8-bit strings and
66313
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
850 Unicode objects support. Some of them are also available on :class:`bytearray`
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
851 objects.
43415
e1c09fa6fc0f #1176: document that string methods don't take keyword args.
Georg Brandl <georg@python.org>
parents: 43181
diff changeset
852
e1c09fa6fc0f #1176: document that string methods don't take keyword args.
Georg Brandl <georg@python.org>
parents: 43181
diff changeset
853 In addition, Python's strings support the sequence type methods
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
854 described in the :ref:`typesseq` section. To output formatted strings
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
855 use template strings or the ``%`` operator described in the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
856 :ref:`string-formatting` section. Also, see the :mod:`re` module for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
857 string functions based on regular expressions.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
858
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
859 .. method:: str.capitalize()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
860
63514
3174d5ba46e3 Merged revisions 82571,82603,82845,82852,82953,82981,83013,83077,83082,83164,83251 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61038
diff changeset
861 Return a copy of the string with its first character capitalized and the
3174d5ba46e3 Merged revisions 82571,82603,82845,82852,82953,82981,83013,83077,83082,83164,83251 via svnmerge from
Georg Brandl <georg@python.org>
parents: 61038
diff changeset
862 rest lowercased.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
863
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
864 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
865
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
866
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
867 .. method:: str.center(width[, fillchar])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
868
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
869 Return centered in a string of length *width*. Padding is done using the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
870 specified *fillchar* (default is a space).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
871
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
872 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
873 Support for the *fillchar* argument.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
874
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
875
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
876 .. method:: str.count(sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
877
51817
0174b93669cd Merged revisions 69905 via svnmerge from
Georg Brandl <georg@python.org>
parents: 51809
diff changeset
878 Return the number of non-overlapping occurrences of substring *sub* in the
0174b93669cd Merged revisions 69905 via svnmerge from
Georg Brandl <georg@python.org>
parents: 51809
diff changeset
879 range [*start*, *end*]. Optional arguments *start* and *end* are
0174b93669cd Merged revisions 69905 via svnmerge from
Georg Brandl <georg@python.org>
parents: 51809
diff changeset
880 interpreted as in slice notation.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
881
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
882
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
883 .. method:: str.decode([encoding[, errors]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
884
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
885 Decodes the string using the codec registered for *encoding*. *encoding*
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
886 defaults to the default string encoding. *errors* may be given to set a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
887 different error handling scheme. The default is ``'strict'``, meaning that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
888 encoding errors raise :exc:`UnicodeError`. Other possible values are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
889 ``'ignore'``, ``'replace'`` and any other name registered via
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
890 :func:`codecs.register_error`, see section :ref:`codec-base-classes`.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
891
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
892 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
893
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
894 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
895 Support for other error handling schemes added.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
896
56093
f64c0eb8cc62 add keyword arguments support to str/unicode encode and decode #6300
Benjamin Peterson <benjamin@python.org>
parents: 55838
diff changeset
897 .. versionchanged:: 2.7
f64c0eb8cc62 add keyword arguments support to str/unicode encode and decode #6300
Benjamin Peterson <benjamin@python.org>
parents: 55838
diff changeset
898 Support for keyword arguments added.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
899
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
900 .. method:: str.encode([encoding[,errors]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
901
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
902 Return an encoded version of the string. Default encoding is the current
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
903 default string encoding. *errors* may be given to set a different error
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
904 handling scheme. The default for *errors* is ``'strict'``, meaning that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
905 encoding errors raise a :exc:`UnicodeError`. Other possible values are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
906 ``'ignore'``, ``'replace'``, ``'xmlcharrefreplace'``, ``'backslashreplace'`` and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
907 any other name registered via :func:`codecs.register_error`, see section
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
908 :ref:`codec-base-classes`. For a list of possible encodings, see section
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
909 :ref:`standard-encodings`.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
910
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
911 .. versionadded:: 2.0
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
912
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
913 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
914 Support for ``'xmlcharrefreplace'`` and ``'backslashreplace'`` and other error
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
915 handling schemes added.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
916
56093
f64c0eb8cc62 add keyword arguments support to str/unicode encode and decode #6300
Benjamin Peterson <benjamin@python.org>
parents: 55838
diff changeset
917 .. versionchanged:: 2.7
f64c0eb8cc62 add keyword arguments support to str/unicode encode and decode #6300
Benjamin Peterson <benjamin@python.org>
parents: 55838
diff changeset
918 Support for keyword arguments added.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
919
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
920 .. method:: str.endswith(suffix[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
921
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
922 Return ``True`` if the string ends with the specified *suffix*, otherwise return
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
923 ``False``. *suffix* can also be a tuple of suffixes to look for. With optional
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
924 *start*, test beginning at that position. With optional *end*, stop comparing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
925 at that position.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
926
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
927 .. versionchanged:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
928 Accept tuples as *suffix*.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
929
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
930
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
931 .. method:: str.expandtabs([tabsize])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
932
43492
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
933 Return a copy of the string where all tab characters are replaced by one or
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
934 more spaces, depending on the current column and the given tab size. The
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
935 column number is reset to zero after each newline occurring in the string.
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
936 If *tabsize* is not given, a tab size of ``8`` characters is assumed. This
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
937 doesn't understand other non-printing characters or escape sequences.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
938
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
939
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
940 .. method:: str.find(sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
941
61038
81d7033d95a3 Merged revisions 80561 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 59845
diff changeset
942 Return the lowest index in the string where substring *sub* is found, such
81d7033d95a3 Merged revisions 80561 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 59845
diff changeset
943 that *sub* is contained in the slice ``s[start:end]``. Optional arguments
81d7033d95a3 Merged revisions 80561 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 59845
diff changeset
944 *start* and *end* are interpreted as in slice notation. Return ``-1`` if
81d7033d95a3 Merged revisions 80561 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 59845
diff changeset
945 *sub* is not found.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
946
69949
85fb264b5922 Add a note to the str.find doc to suggest the use of the "in" operator.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 69773
diff changeset
947 .. note::
85fb264b5922 Add a note to the str.find doc to suggest the use of the "in" operator.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 69773
diff changeset
948
85fb264b5922 Add a note to the str.find doc to suggest the use of the "in" operator.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 69773
diff changeset
949 The :meth:`~str.find` method should be used only if you need to know the
85fb264b5922 Add a note to the str.find doc to suggest the use of the "in" operator.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 69773
diff changeset
950 position of *sub*. To check if *sub* is a substring or not, use the
85fb264b5922 Add a note to the str.find doc to suggest the use of the "in" operator.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 69773
diff changeset
951 :keyword:`in` operator::
85fb264b5922 Add a note to the str.find doc to suggest the use of the "in" operator.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 69773
diff changeset
952
85fb264b5922 Add a note to the str.find doc to suggest the use of the "in" operator.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 69773
diff changeset
953 >>> 'Py' in 'Python'
85fb264b5922 Add a note to the str.find doc to suggest the use of the "in" operator.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 69773
diff changeset
954 True
85fb264b5922 Add a note to the str.find doc to suggest the use of the "in" operator.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 69773
diff changeset
955
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
956
56803
bb8188736a29 Merged revisions 69987,70002,70061 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56801
diff changeset
957 .. method:: str.format(*args, **kwargs)
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
958
59845
f96c8293dd7f Merged revisions 78859-78860,78952,79168-79169,79173,79176,79178-79179,79181,79184-79185,79192,79212 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59831
diff changeset
959 Perform a string formatting operation. The string on which this method is
f96c8293dd7f Merged revisions 78859-78860,78952,79168-79169,79173,79176,79178-79179,79181,79184-79185,79192,79212 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59831
diff changeset
960 called can contain literal text or replacement fields delimited by braces
f96c8293dd7f Merged revisions 78859-78860,78952,79168-79169,79173,79176,79178-79179,79181,79184-79185,79192,79212 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59831
diff changeset
961 ``{}``. Each replacement field contains either the numeric index of a
f96c8293dd7f Merged revisions 78859-78860,78952,79168-79169,79173,79176,79178-79179,79181,79184-79185,79192,79212 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59831
diff changeset
962 positional argument, or the name of a keyword argument. Returns a copy of
f96c8293dd7f Merged revisions 78859-78860,78952,79168-79169,79173,79176,79178-79179,79181,79184-79185,79192,79212 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59831
diff changeset
963 the string where each replacement field is replaced with the string value of
f96c8293dd7f Merged revisions 78859-78860,78952,79168-79169,79173,79176,79178-79179,79181,79184-79185,79192,79212 via svnmerge from
Georg Brandl <georg@python.org>
parents: 59831
diff changeset
964 the corresponding argument.
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
965
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
966 >>> "The sum of 1 + 2 is {0}".format(1+2)
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
967 'The sum of 1 + 2 is 3'
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
968
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
969 See :ref:`formatstrings` for a description of the various formatting options
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
970 that can be specified in format strings.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
971
76732
8aab13719c02 Use Python 3 instead of 3.0.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 76595
diff changeset
972 This method of string formatting is the new standard in Python 3, and
46949
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
973 should be preferred to the ``%`` formatting described in
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
974 :ref:`string-formatting` in new code.
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
975
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
976 .. versionadded:: 2.6
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
977
6a778c0a517e #2836: backport new string formatting docs.
Georg Brandl <georg@python.org>
parents: 46876
diff changeset
978
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
979 .. method:: str.index(sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
980
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
981 Like :meth:`find`, but raise :exc:`ValueError` when the substring is not found.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
982
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
983
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
984 .. method:: str.isalnum()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
985
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
986 Return true if all characters in the string are alphanumeric and there is at
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
987 least one character, false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
988
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
989 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
990
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
991
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
992 .. method:: str.isalpha()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
993
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
994 Return true if all characters in the string are alphabetic and there is at least
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
995 one character, false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
996
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
997 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
998
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
999
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1000 .. method:: str.isdigit()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1001
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1002 Return true if all characters in the string are digits and there is at least one
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1003 character, false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1004
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1005 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1006
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1007
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1008 .. method:: str.islower()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1009
71871
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
1010 Return true if all cased characters [4]_ in the string are lowercase and there is at
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1011 least one cased character, false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1012
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1013 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1014
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1015
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1016 .. method:: str.isspace()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1017
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1018 Return true if there are only whitespace characters in the string and there is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1019 at least one character, false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1020
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1021 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1022
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1023
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1024 .. method:: str.istitle()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1025
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1026 Return true if the string is a titlecased string and there is at least one
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1027 character, for example uppercase characters may only follow uncased characters
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1028 and lowercase characters only cased ones. Return false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1029
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1030 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1031
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1032
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1033 .. method:: str.isupper()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1034
71871
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
1035 Return true if all cased characters [4]_ in the string are uppercase and there is at
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1036 least one cased character, false otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1037
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1038 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1039
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1040
56824
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
1041 .. method:: str.join(iterable)
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
1042
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
1043 Return a string which is the concatenation of the strings in the
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
1044 :term:`iterable` *iterable*. The separator between elements is the string
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
1045 providing this method.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1046
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1047
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1048 .. method:: str.ljust(width[, fillchar])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1049
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1050 Return the string left justified in a string of length *width*. Padding is done
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1051 using the specified *fillchar* (default is a space). The original string is
74330
3aed8787ce5c Closes #13754 String returned if less than *or equal to* x 3
Terry Jan Reedy <tjreedy@udel.edu>
parents: 73812
diff changeset
1052 returned if *width* is less than or equal to ``len(s)``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1053
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1054 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1055 Support for the *fillchar* argument.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1056
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1057
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1058 .. method:: str.lower()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1059
71871
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
1060 Return a copy of the string with all the cased characters [4]_ converted to
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
1061 lowercase.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1062
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1063 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1064
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1065
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1066 .. method:: str.lstrip([chars])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1067
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1068 Return a copy of the string with leading characters removed. The *chars*
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1069 argument is a string specifying the set of characters to be removed. If omitted
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1070 or ``None``, the *chars* argument defaults to removing whitespace. The *chars*
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 45800
diff changeset
1071 argument is not a prefix; rather, all combinations of its values are stripped:
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1072
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1073 >>> ' spacious '.lstrip()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1074 'spacious '
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1075 >>> 'www.example.com'.lstrip('cmowz.')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1076 'example.com'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1077
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1078 .. versionchanged:: 2.2.2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1079 Support for the *chars* argument.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1080
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1081
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1082 .. method:: str.partition(sep)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1083
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1084 Split the string at the first occurrence of *sep*, and return a 3-tuple
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1085 containing the part before the separator, the separator itself, and the part
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1086 after the separator. If the separator is not found, return a 3-tuple containing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1087 the string itself, followed by two empty strings.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1088
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1089 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1090
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1091
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1092 .. method:: str.replace(old, new[, count])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1093
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1094 Return a copy of the string with all occurrences of substring *old* replaced by
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1095 *new*. If the optional argument *count* is given, only the first *count*
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1096 occurrences are replaced.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1097
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1098
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1099 .. method:: str.rfind(sub [,start [,end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1100
61038
81d7033d95a3 Merged revisions 80561 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 59845
diff changeset
1101 Return the highest index in the string where substring *sub* is found, such
81d7033d95a3 Merged revisions 80561 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 59845
diff changeset
1102 that *sub* is contained within ``s[start:end]``. Optional arguments *start*
81d7033d95a3 Merged revisions 80561 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 59845
diff changeset
1103 and *end* are interpreted as in slice notation. Return ``-1`` on failure.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1104
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1105
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1106 .. method:: str.rindex(sub[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1107
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1108 Like :meth:`rfind` but raises :exc:`ValueError` when the substring *sub* is not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1109 found.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1110
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1111
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1112 .. method:: str.rjust(width[, fillchar])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1113
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1114 Return the string right justified in a string of length *width*. Padding is done
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1115 using the specified *fillchar* (default is a space). The original string is
74330
3aed8787ce5c Closes #13754 String returned if less than *or equal to* x 3
Terry Jan Reedy <tjreedy@udel.edu>
parents: 73812
diff changeset
1116 returned if *width* is less than or equal to ``len(s)``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1117
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1118 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1119 Support for the *fillchar* argument.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1120
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1121
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1122 .. method:: str.rpartition(sep)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1123
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1124 Split the string at the last occurrence of *sep*, and return a 3-tuple
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1125 containing the part before the separator, the separator itself, and the part
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1126 after the separator. If the separator is not found, return a 3-tuple containing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1127 two empty strings, followed by the string itself.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1128
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1129 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1130
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1131
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1132 .. method:: str.rsplit([sep [,maxsplit]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1133
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1134 Return a list of the words in the string, using *sep* as the delimiter string.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1135 If *maxsplit* is given, at most *maxsplit* splits are done, the *rightmost*
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1136 ones. If *sep* is not specified or ``None``, any whitespace string is a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1137 separator. Except for splitting from the right, :meth:`rsplit` behaves like
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1138 :meth:`split` which is described in detail below.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1139
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1140 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1141
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1142
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1143 .. method:: str.rstrip([chars])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1144
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1145 Return a copy of the string with trailing characters removed. The *chars*
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1146 argument is a string specifying the set of characters to be removed. If omitted
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1147 or ``None``, the *chars* argument defaults to removing whitespace. The *chars*
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 45800
diff changeset
1148 argument is not a suffix; rather, all combinations of its values are stripped:
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1149
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1150 >>> ' spacious '.rstrip()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1151 ' spacious'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1152 >>> 'mississippi'.rstrip('ipz')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1153 'mississ'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1154
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1155 .. versionchanged:: 2.2.2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1156 Support for the *chars* argument.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1157
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1158
43492
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1159 .. method:: str.split([sep[, maxsplit]])
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1160
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1161 Return a list of the words in the string, using *sep* as the delimiter
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1162 string. If *maxsplit* is given, at most *maxsplit* splits are done (thus,
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1163 the list will have at most ``maxsplit+1`` elements). If *maxsplit* is not
76855
0415ecd7b0e3 #14763: document default maxsplit value for str.split.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 76732
diff changeset
1164 specified or ``-1``, then there is no limit on the number of splits
0415ecd7b0e3 #14763: document default maxsplit value for str.split.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 76732
diff changeset
1165 (all possible splits are made).
43492
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1166
43738
79f5ca9ee154 Fix markup glitch.
Georg Brandl <georg@python.org>
parents: 43629
diff changeset
1167 If *sep* is given, consecutive delimiters are not grouped together and are
43492
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1168 deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1169 ``['1', '', '2']``). The *sep* argument may consist of multiple characters
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1170 (for example, ``'1<>2<>3'.split('<>')`` returns ``['1', '2', '3']``).
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1171 Splitting an empty string with a specified separator returns ``['']``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1172
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1173 If *sep* is not specified or is ``None``, a different splitting algorithm is
43492
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1174 applied: runs of consecutive whitespace are regarded as a single separator,
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1175 and the result will contain no empty strings at the start or end if the
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1176 string has leading or trailing whitespace. Consequently, splitting an empty
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1177 string or a string consisting of just whitespace with a ``None`` separator
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1178 returns ``[]``.
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1179
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1180 For example, ``' 1 2 3 '.split()`` returns ``['1', '2', '3']``, and
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1181 ``' 1 2 3 '.split(None, 1)`` returns ``['1', '2 3 ']``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1182
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1183
78596
8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it.
R David Murray <rdmurray@bitdance.com>
parents: 78521
diff changeset
1184 .. index::
8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it.
R David Murray <rdmurray@bitdance.com>
parents: 78521
diff changeset
1185 single: universal newlines; str.splitlines method
8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it.
R David Murray <rdmurray@bitdance.com>
parents: 78521
diff changeset
1186
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1187 .. method:: str.splitlines([keepends])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1188
78455
e057a7d18fa2 #15554: clarify splitlines/split differences.
R David Murray <rdmurray@bitdance.com>
parents: 77299
diff changeset
1189 Return a list of the lines in the string, breaking at line boundaries.
78596
8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it.
R David Murray <rdmurray@bitdance.com>
parents: 78521
diff changeset
1190 This method uses the :term:`universal newlines` approach to splitting lines.
78455
e057a7d18fa2 #15554: clarify splitlines/split differences.
R David Murray <rdmurray@bitdance.com>
parents: 77299
diff changeset
1191 Line breaks are not included in the resulting list unless *keepends* is
e057a7d18fa2 #15554: clarify splitlines/split differences.
R David Murray <rdmurray@bitdance.com>
parents: 77299
diff changeset
1192 given and true.
77290
0df7594e4ebd #14957: clarify splitlines docs.
R David Murray <rdmurray@bitdance.com>
parents: 76855
diff changeset
1193
0df7594e4ebd #14957: clarify splitlines docs.
R David Murray <rdmurray@bitdance.com>
parents: 76855
diff changeset
1194 For example, ``'ab c\n\nde fg\rkl\r\n'.splitlines()`` returns
77299
48564362b687 #14957: fix doc typo.
R David Murray <rdmurray@bitdance.com>
parents: 77290
diff changeset
1195 ``['ab c', '', 'de fg', 'kl']``, while the same call with ``splitlines(True)``
78521
61f1bf70db95 add missing quote in splitlines() example; thanks to Yevgen Yampolskiy from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 78455
diff changeset
1196 returns ``['ab c\n', '\n', 'de fg\r', 'kl\r\n']``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1197
78455
e057a7d18fa2 #15554: clarify splitlines/split differences.
R David Murray <rdmurray@bitdance.com>
parents: 77299
diff changeset
1198 Unlike :meth:`~str.split` when a delimiter string *sep* is given, this
e057a7d18fa2 #15554: clarify splitlines/split differences.
R David Murray <rdmurray@bitdance.com>
parents: 77299
diff changeset
1199 method returns an empty list for the empty string, and a terminal line
e057a7d18fa2 #15554: clarify splitlines/split differences.
R David Murray <rdmurray@bitdance.com>
parents: 77299
diff changeset
1200 break does not result in an extra line.
e057a7d18fa2 #15554: clarify splitlines/split differences.
R David Murray <rdmurray@bitdance.com>
parents: 77299
diff changeset
1201
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1202
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1203 .. method:: str.startswith(prefix[, start[, end]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1204
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1205 Return ``True`` if string starts with the *prefix*, otherwise return ``False``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1206 *prefix* can also be a tuple of prefixes to look for. With optional *start*,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1207 test string beginning at that position. With optional *end*, stop comparing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1208 string at that position.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1209
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1210 .. versionchanged:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1211 Accept tuples as *prefix*.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1212
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1213
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1214 .. method:: str.strip([chars])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1215
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1216 Return a copy of the string with the leading and trailing characters removed.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1217 The *chars* argument is a string specifying the set of characters to be removed.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1218 If omitted or ``None``, the *chars* argument defaults to removing whitespace.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1219 The *chars* argument is not a prefix or suffix; rather, all combinations of its
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 45800
diff changeset
1220 values are stripped:
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1221
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1222 >>> ' spacious '.strip()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1223 'spacious'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1224 >>> 'www.example.com'.strip('cmowz.')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1225 'example'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1226
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1227 .. versionchanged:: 2.2.2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1228 Support for the *chars* argument.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1229
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1230
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1231 .. method:: str.swapcase()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1232
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1233 Return a copy of the string with uppercase characters converted to lowercase and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1234 vice versa.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1235
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1236 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1237
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1238
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1239 .. method:: str.title()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1240
56289
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1241 Return a titlecased version of the string where words start with an uppercase
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1242 character and the remaining characters are lowercase.
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1243
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1244 The algorithm uses a simple language-independent definition of a word as
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1245 groups of consecutive letters. The definition works in many contexts but
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1246 it means that apostrophes in contractions and possessives form word
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1247 boundaries, which may not be the desired result::
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1248
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1249 >>> "they're bill's friends from the UK".title()
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1250 "They'Re Bill'S Friends From The Uk"
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1251
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1252 A workaround for apostrophes can be constructed using regular expressions::
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1253
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1254 >>> import re
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1255 >>> def titlecase(s):
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1256 return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1257 lambda mo: mo.group(0)[0].upper() +
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1258 mo.group(0)[1:].lower(),
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1259 s)
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1260
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1261 >>> titlecase("they're bill's friends.")
e72a73ad7e29 Issue 7008: Better document str.title and show how to work around the apostrophe problem.
Raymond Hettinger <python@rcn.com>
parents: 55775
diff changeset
1262 "They're Bill's Friends."
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1263
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1264 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1265
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1266
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1267 .. method:: str.translate(table[, deletechars])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1268
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1269 Return a copy of the string where all characters occurring in the optional
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1270 argument *deletechars* are removed, and the remaining characters have been
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1271 mapped through the given translation table, which must be a string of length
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1272 256.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1273
63892
29af9abc76ca Merged revisions 81053,81259,81265 via svnmerge from
Florent Xicluna <florent.xicluna@gmail.com>
parents: 63514
diff changeset
1274 You can use the :func:`~string.maketrans` helper function in the :mod:`string`
29af9abc76ca Merged revisions 81053,81259,81265 via svnmerge from
Florent Xicluna <florent.xicluna@gmail.com>
parents: 63514
diff changeset
1275 module to create a translation table. For string objects, set the *table*
29af9abc76ca Merged revisions 81053,81259,81265 via svnmerge from
Florent Xicluna <florent.xicluna@gmail.com>
parents: 63514
diff changeset
1276 argument to ``None`` for translations that only delete characters:
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1277
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1278 >>> 'read this short text'.translate(None, 'aeiou')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1279 'rd ths shrt txt'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1280
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1281 .. versionadded:: 2.6
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1282 Support for a ``None`` *table* argument.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1283
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1284 For Unicode objects, the :meth:`translate` method does not accept the optional
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1285 *deletechars* argument. Instead, it returns a copy of the *s* where all
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1286 characters have been mapped through the given translation table which must be a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1287 mapping of Unicode ordinals to Unicode ordinals, Unicode strings or ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1288 Unmapped characters are left untouched. Characters mapped to ``None`` are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1289 deleted. Note, a more flexible approach is to create a custom character mapping
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1290 codec using the :mod:`codecs` module (see :mod:`encodings.cp1251` for an
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1291 example).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1292
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1293
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1294 .. method:: str.upper()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1295
71871
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
1296 Return a copy of the string with all the cased characters [4]_ converted to
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
1297 uppercase. Note that ``str.upper().isupper()`` might be ``False`` if ``s``
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
1298 contains uncased characters or if the Unicode category of the resulting
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
1299 character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter, titlecase).
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1300
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1301 For 8-bit strings, this method is locale-dependent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1302
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1303
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1304 .. method:: str.zfill(width)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1305
43492
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1306 Return the numeric string left filled with zeros in a string of length
045952ff08f7 #1123: fix the docs for the str.split(None, sep) case.
Georg Brandl <georg@python.org>
parents: 43415
diff changeset
1307 *width*. A sign prefix is handled correctly. The original string is
74330
3aed8787ce5c Closes #13754 String returned if less than *or equal to* x 3
Terry Jan Reedy <tjreedy@udel.edu>
parents: 73812
diff changeset
1308 returned if *width* is less than or equal to ``len(s)``.
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50240
diff changeset
1309
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1310
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1311 .. versionadded:: 2.2.2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1312
45800
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1313 The following methods are present only on unicode objects:
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1314
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1315 .. method:: unicode.isnumeric()
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1316
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1317 Return ``True`` if there are only numeric characters in S, ``False``
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1318 otherwise. Numeric characters include digit characters, and all characters
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1319 that have the Unicode numeric value property, e.g. U+2155,
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1320 VULGAR FRACTION ONE FIFTH.
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50240
diff changeset
1321
45800
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1322 .. method:: unicode.isdecimal()
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1323
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1324 Return ``True`` if there are only decimal characters in S, ``False``
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1325 otherwise. Decimal characters include digit characters, and all characters
72984
86e3943d0d5b Remove duplication.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71954
diff changeset
1326 that can be used to form decimal-radix numbers, e.g. U+0660,
45800
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1327 ARABIC-INDIC DIGIT ZERO.
7e8ceb39447e Document unicode.isnumeric() and unicode.isdecimal() (issue2326)
Steven Bethard <steven.bethard@gmail.com>
parents: 45180
diff changeset
1328
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1329
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1330 .. _string-formatting:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1331
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1332 String Formatting Operations
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1333 ----------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1334
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1335 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1336 single: formatting, string (%)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1337 single: interpolation, string (%)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1338 single: string; formatting
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1339 single: string; interpolation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1340 single: printf-style formatting
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1341 single: sprintf-style formatting
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1342 single: % formatting
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1343 single: % interpolation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1344
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1345 String and Unicode objects have one unique built-in operation: the ``%``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1346 operator (modulo). This is also known as the string *formatting* or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1347 *interpolation* operator. Given ``format % values`` (where *format* is a string
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1348 or Unicode object), ``%`` conversion specifications in *format* are replaced
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1349 with zero or more elements of *values*. The effect is similar to the using
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74330
diff changeset
1350 :c:func:`sprintf` in the C language. If *format* is a Unicode object, or if any
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1351 of the objects being converted using the ``%s`` conversion are Unicode objects,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1352 the result will also be a Unicode object.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1353
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1354 If *format* requires a single argument, *values* may be a single non-tuple
71871
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
1355 object. [5]_ Otherwise, *values* must be a tuple with exactly the number of
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1356 items specified by the format string, or a single mapping object (for example, a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1357 dictionary).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1358
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1359 A conversion specifier contains two or more characters and has the following
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1360 components, which must occur in this order:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1361
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1362 #. The ``'%'`` character, which marks the start of the specifier.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1363
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1364 #. Mapping key (optional), consisting of a parenthesised sequence of characters
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1365 (for example, ``(somename)``).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1366
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1367 #. Conversion flags (optional), which affect the result of some conversion
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1368 types.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1369
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1370 #. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1371 actual width is read from the next element of the tuple in *values*, and the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1372 object to convert comes after the minimum field width and optional precision.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1373
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1374 #. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1375 specified as ``'*'`` (an asterisk), the actual width is read from the next
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1376 element of the tuple in *values*, and the value to convert comes after the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1377 precision.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1378
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1379 #. Length modifier (optional).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1380
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1381 #. Conversion type.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1382
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1383 When the right argument is a dictionary (or other mapping type), then the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1384 formats in the string *must* include a parenthesised mapping key into that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1385 dictionary inserted immediately after the ``'%'`` character. The mapping key
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 45800
diff changeset
1386 selects the value to be formatted from the mapping. For example:
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1387
66456
77771b085eca Merged revisions 85548,85572-85573,85606,85609-85612,85614-85616 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66339
diff changeset
1388 >>> print '%(language)s has %(number)03d quote types.' % \
77771b085eca Merged revisions 85548,85572-85573,85606,85609-85612,85614-85616 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66339
diff changeset
1389 ... {"language": "Python", "number": 2}
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1390 Python has 002 quote types.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1391
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1392 In this case no ``*`` specifiers may occur in a format (since they require a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1393 sequential parameter list).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1394
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1395 The conversion flag characters are:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1396
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1397 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1398 | Flag | Meaning |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1399 +=========+=====================================================================+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1400 | ``'#'`` | The value conversion will use the "alternate form" (where defined |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1401 | | below). |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1402 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1403 | ``'0'`` | The conversion will be zero padded for numeric values. |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1404 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1405 | ``'-'`` | The converted value is left adjusted (overrides the ``'0'`` |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1406 | | conversion if both are given). |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1407 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1408 | ``' '`` | (a space) A blank should be left before a positive number (or empty |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1409 | | string) produced by a signed conversion. |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1410 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1411 | ``'+'`` | A sign character (``'+'`` or ``'-'``) will precede the conversion |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1412 | | (overrides a "space" flag). |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1413 +---------+---------------------------------------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1414
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1415 A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it
46870
d88507588790 #1153769: document PEP 237 changes to string formatting.
Georg Brandl <georg@python.org>
parents: 46803
diff changeset
1416 is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1417
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1418 The conversion types are:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1419
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1420 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1421 | Conversion | Meaning | Notes |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1422 +============+=====================================================+=======+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1423 | ``'d'`` | Signed integer decimal. | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1424 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1425 | ``'i'`` | Signed integer decimal. | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1426 +------------+-----------------------------------------------------+-------+
46870
d88507588790 #1153769: document PEP 237 changes to string formatting.
Georg Brandl <georg@python.org>
parents: 46803
diff changeset
1427 | ``'o'`` | Signed octal value. | \(1) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1428 +------------+-----------------------------------------------------+-------+
52909
f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge
Georg Brandl <georg@python.org>
parents: 52900
diff changeset
1429 | ``'u'`` | Obsolete type -- it is identical to ``'d'``. | \(7) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1430 +------------+-----------------------------------------------------+-------+
46870
d88507588790 #1153769: document PEP 237 changes to string formatting.
Georg Brandl <georg@python.org>
parents: 46803
diff changeset
1431 | ``'x'`` | Signed hexadecimal (lowercase). | \(2) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1432 +------------+-----------------------------------------------------+-------+
46870
d88507588790 #1153769: document PEP 237 changes to string formatting.
Georg Brandl <georg@python.org>
parents: 46803
diff changeset
1433 | ``'X'`` | Signed hexadecimal (uppercase). | \(2) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1434 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1435 | ``'e'`` | Floating point exponential format (lowercase). | \(3) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1436 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1437 | ``'E'`` | Floating point exponential format (uppercase). | \(3) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1438 +------------+-----------------------------------------------------+-------+
48003
5c33009994b4 Backed out r65069, pending fixing it in Windows.
Eric Smith <eric@trueblade.com>
parents: 48001
diff changeset
1439 | ``'f'`` | Floating point decimal format. | \(3) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1440 +------------+-----------------------------------------------------+-------+
48003
5c33009994b4 Backed out r65069, pending fixing it in Windows.
Eric Smith <eric@trueblade.com>
parents: 48001
diff changeset
1441 | ``'F'`` | Floating point decimal format. | \(3) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1442 +------------+-----------------------------------------------------+-------+
46692
f8468bfd4357 #2773: fix description of 'g' and 'G' formatting spec.
Georg Brandl <georg@python.org>
parents: 46014
diff changeset
1443 | ``'g'`` | Floating point format. Uses lowercase exponential | \(4) |
46693
ddd5f42332b9 > != (!<).
Georg Brandl <georg@python.org>
parents: 46692
diff changeset
1444 | | format if exponent is less than -4 or not less than | |
46692
f8468bfd4357 #2773: fix description of 'g' and 'G' formatting spec.
Georg Brandl <georg@python.org>
parents: 46014
diff changeset
1445 | | precision, decimal format otherwise. | |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1446 +------------+-----------------------------------------------------+-------+
46692
f8468bfd4357 #2773: fix description of 'g' and 'G' formatting spec.
Georg Brandl <georg@python.org>
parents: 46014
diff changeset
1447 | ``'G'`` | Floating point format. Uses uppercase exponential | \(4) |
46693
ddd5f42332b9 > != (!<).
Georg Brandl <georg@python.org>
parents: 46692
diff changeset
1448 | | format if exponent is less than -4 or not less than | |
46692
f8468bfd4357 #2773: fix description of 'g' and 'G' formatting spec.
Georg Brandl <georg@python.org>
parents: 46014
diff changeset
1449 | | precision, decimal format otherwise. | |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1450 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1451 | ``'c'`` | Single character (accepts integer or single | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1452 | | character string). | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1453 +------------+-----------------------------------------------------+-------+
57796
89996755cf39 Merged revisions 76904 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 56824
diff changeset
1454 | ``'r'`` | String (converts any Python object using | \(5) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1455 | | :func:`repr`). | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1456 +------------+-----------------------------------------------------+-------+
57796
89996755cf39 Merged revisions 76904 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 56824
diff changeset
1457 | ``'s'`` | String (converts any Python object using | \(6) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1458 | | :func:`str`). | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1459 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1460 | ``'%'`` | No argument is converted, results in a ``'%'`` | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1461 | | character in the result. | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1462 +------------+-----------------------------------------------------+-------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1463
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1464 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1465
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1466 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1467 The alternate form causes a leading zero (``'0'``) to be inserted between
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1468 left-hand padding and the formatting of the number if the leading character
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1469 of the result is not already a zero.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1470
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1471 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1472 The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1473 the ``'x'`` or ``'X'`` format was used) to be inserted between left-hand padding
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1474 and the formatting of the number if the leading character of the result is not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1475 already a zero.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1476
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1477 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1478 The alternate form causes the result to always contain a decimal point, even if
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1479 no digits follow it.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1480
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1481 The precision determines the number of digits after the decimal point and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1482 defaults to 6.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1483
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1484 (4)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1485 The alternate form causes the result to always contain a decimal point, and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1486 trailing zeroes are not removed as they would otherwise be.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1487
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1488 The precision determines the number of significant digits before and after the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1489 decimal point and defaults to 6.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1490
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1491 (5)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1492 The ``%r`` conversion was added in Python 2.0.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1493
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1494 The precision determines the maximal number of characters used.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1495
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1496 (6)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1497 If the object or format provided is a :class:`unicode` string, the resulting
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1498 string will also be :class:`unicode`.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1499
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1500 The precision determines the maximal number of characters used.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1501
46870
d88507588790 #1153769: document PEP 237 changes to string formatting.
Georg Brandl <georg@python.org>
parents: 46803
diff changeset
1502 (7)
d88507588790 #1153769: document PEP 237 changes to string formatting.
Georg Brandl <georg@python.org>
parents: 46803
diff changeset
1503 See :pep:`237`.
d88507588790 #1153769: document PEP 237 changes to string formatting.
Georg Brandl <georg@python.org>
parents: 46803
diff changeset
1504
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1505 Since Python strings have an explicit length, ``%s`` conversions do not assume
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1506 that ``'\0'`` is the end of the string.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1507
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44344
diff changeset
1508 .. XXX Examples?
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1509
57419
a7eb1ae4e919 Issue #7117, continued: Remove substitution of %g-style formatting for
Mark Dickinson <dickinsm@gmail.com>
parents: 56671
diff changeset
1510 .. versionchanged:: 2.7
a7eb1ae4e919 Issue #7117, continued: Remove substitution of %g-style formatting for
Mark Dickinson <dickinsm@gmail.com>
parents: 56671
diff changeset
1511 ``%f`` conversions for numbers whose absolute value is over 1e50 are no
a7eb1ae4e919 Issue #7117, continued: Remove substitution of %g-style formatting for
Mark Dickinson <dickinsm@gmail.com>
parents: 56671
diff changeset
1512 longer replaced by ``%g`` conversions.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1513
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1514 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1515 module: string
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1516 module: re
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1517
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1518 Additional string operations are defined in standard modules :mod:`string` and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1519 :mod:`re`.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1520
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1521
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1522 .. _typesseq-xrange:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1523
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1524 XRange Type
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1525 -----------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1526
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1527 .. index:: object: xrange
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1528
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1529 The :class:`xrange` type is an immutable sequence which is commonly used for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1530 looping. The advantage of the :class:`xrange` type is that an :class:`xrange`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1531 object will always take the same amount of memory, no matter the size of the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1532 range it represents. There are no consistent performance advantages.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1533
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1534 XRange objects have very little behavior: they only support indexing, iteration,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1535 and the :func:`len` function.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1536
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1537
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1538 .. _typesseq-mutable:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1539
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1540 Mutable Sequence Types
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1541 ----------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1542
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1543 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1544 triple: mutable; sequence; types
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1545 object: list
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1546
66313
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
1547 List and :class:`bytearray` objects support additional operations that allow
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
1548 in-place modification of the object. Other mutable sequence types (when added
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
1549 to the language) should also support these operations. Strings and tuples
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
1550 are immutable sequence types: such objects cannot be modified once created.
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
1551 The following operations are defined on mutable sequence types (where *x* is
44b31219aecd Issue #8340: document bytearray in Python 2.7.
Antoine Pitrou <solipsis@pitrou.net>
parents: 66060
diff changeset
1552 an arbitrary object):
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1553
65051
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1554 .. index::
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1555 triple: operations on; sequence; types
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1556 triple: operations on; list; type
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1557 pair: subscript; assignment
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1558 pair: slice; assignment
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1559 pair: extended slice; assignment
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1560 statement: del
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1561 single: append() (list method)
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1562 single: extend() (list method)
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1563 single: count() (list method)
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1564 single: index() (list method)
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1565 single: insert() (list method)
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1566 single: pop() (list method)
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1567 single: remove() (list method)
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1568 single: reverse() (list method)
ce475d35b50f Merged revisions 85156 via svnmerge from
Senthil Kumaran <orsenthil@gmail.com>
parents: 64951
diff changeset
1569 single: sort() (list method)
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1570
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1571 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1572 | Operation | Result | Notes |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1573 +==============================+================================+=====================+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1574 | ``s[i] = x`` | item *i* of *s* is replaced by | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1575 | | *x* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1576 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1577 | ``s[i:j] = t`` | slice of *s* from *i* to *j* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1578 | | is replaced by the contents of | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1579 | | the iterable *t* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1580 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1581 | ``del s[i:j]`` | same as ``s[i:j] = []`` | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1582 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1583 | ``s[i:j:k] = t`` | the elements of ``s[i:j:k]`` | \(1) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1584 | | are replaced by those of *t* | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1585 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1586 | ``del s[i:j:k]`` | removes the elements of | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1587 | | ``s[i:j:k]`` from the list | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1588 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1589 | ``s.append(x)`` | same as ``s[len(s):len(s)] = | \(2) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1590 | | [x]`` | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1591 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1592 | ``s.extend(x)`` | same as ``s[len(s):len(s)] = | \(3) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1593 | | x`` | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1594 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1595 | ``s.count(x)`` | return number of *i*'s for | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1596 | | which ``s[i] == x`` | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1597 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1598 | ``s.index(x[, i[, j]])`` | return smallest *k* such that | \(4) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1599 | | ``s[k] == x`` and ``i <= k < | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1600 | | j`` | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1601 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1602 | ``s.insert(i, x)`` | same as ``s[i:i] = [x]`` | \(5) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1603 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1604 | ``s.pop([i])`` | same as ``x = s[i]; del s[i]; | \(6) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1605 | | return x`` | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1606 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1607 | ``s.remove(x)`` | same as ``del s[s.index(x)]`` | \(4) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1608 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1609 | ``s.reverse()`` | reverses the items of *s* in | \(7) |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1610 | | place | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1611 +------------------------------+--------------------------------+---------------------+
44555
7ea231578b02 Consistency nit.
Georg Brandl <georg@python.org>
parents: 44553
diff changeset
1612 | ``s.sort([cmp[, key[, | sort the items of *s* in place | (7)(8)(9)(10) |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1613 | reverse]]])`` | | |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1614 +------------------------------+--------------------------------+---------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1615
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1616 Notes:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1617
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1618 (1)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1619 *t* must have the same length as the slice it is replacing.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1620
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1621 (2)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1622 The C implementation of Python has historically accepted multiple parameters and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1623 implicitly joined them into a tuple; this no longer works in Python 2.0. Use of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1624 this misfeature has been deprecated since Python 1.4.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1625
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1626 (3)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1627 *x* can be any iterable object.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1628
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1629 (4)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1630 Raises :exc:`ValueError` when *x* is not found in *s*. When a negative index is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1631 passed as the second or third parameter to the :meth:`index` method, the list
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1632 length is added, as for slice indices. If it is still negative, it is truncated
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1633 to zero, as for slice indices.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1634
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1635 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1636 Previously, :meth:`index` didn't have arguments for specifying start and stop
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1637 positions.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1638
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1639 (5)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1640 When a negative index is passed as the first parameter to the :meth:`insert`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1641 method, the list length is added, as for slice indices. If it is still
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1642 negative, it is truncated to zero, as for slice indices.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1643
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1644 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1645 Previously, all negative indices were truncated to zero.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1646
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1647 (6)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1648 The :meth:`pop` method is only supported by the list and array types. The
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1649 optional argument *i* defaults to ``-1``, so that by default the last item is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1650 removed and returned.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1651
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1652 (7)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1653 The :meth:`sort` and :meth:`reverse` methods modify the list in place for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1654 economy of space when sorting or reversing a large list. To remind you that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1655 they operate by side effect, they don't return the sorted or reversed list.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1656
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1657 (8)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1658 The :meth:`sort` method takes optional arguments for controlling the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1659 comparisons.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1660
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1661 *cmp* specifies a custom comparison function of two arguments (list items) which
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1662 should return a negative, zero or positive number depending on whether the first
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1663 argument is considered smaller than, equal to, or larger than the second
44525
66197f8d0fdf #1755097: document default values for [].sort() and sorted().
Georg Brandl <georg@python.org>
parents: 44524
diff changeset
1664 argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())``. The default value
66197f8d0fdf #1755097: document default values for [].sort() and sorted().
Georg Brandl <georg@python.org>
parents: 44524
diff changeset
1665 is ``None``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1666
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1667 *key* specifies a function of one argument that is used to extract a comparison
44525
66197f8d0fdf #1755097: document default values for [].sort() and sorted().
Georg Brandl <georg@python.org>
parents: 44524
diff changeset
1668 key from each list element: ``key=str.lower``. The default value is ``None``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1669
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1670 *reverse* is a boolean value. If set to ``True``, then the list elements are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1671 sorted as if each comparison were reversed.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1672
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1673 In general, the *key* and *reverse* conversion processes are much faster than
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1674 specifying an equivalent *cmp* function. This is because *cmp* is called
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1675 multiple times for each list element while *key* and *reverse* touch each
60315
5dda3f32a2ce Add tests for cmp_to_key.
Raymond Hettinger <python@rcn.com>
parents: 60281
diff changeset
1676 element only once. Use :func:`functools.cmp_to_key` to convert an
5dda3f32a2ce Add tests for cmp_to_key.
Raymond Hettinger <python@rcn.com>
parents: 60281
diff changeset
1677 old-style *cmp* function to a *key* function.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1678
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1679 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1680 Support for ``None`` as an equivalent to omitting *cmp* was added.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1681
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1682 .. versionchanged:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1683 Support for *key* and *reverse* was added.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1684
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1685 (9)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1686 Starting with Python 2.3, the :meth:`sort` method is guaranteed to be stable. A
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1687 sort is stable if it guarantees not to change the relative order of elements
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1688 that compare equal --- this is helpful for sorting in multiple passes (for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1689 example, sort by department, then by salary grade).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1690
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1691 (10)
56824
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
1692 .. impl-detail::
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
1693
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
1694 While a list is being sorted, the effect of attempting to mutate, or even
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
1695 inspect, the list is undefined. The C implementation of Python 2.3 and
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
1696 newer makes the list appear empty for the duration, and raises
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
1697 :exc:`ValueError` if it can detect that the list has been mutated during a
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
1698 sort.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1699
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1700
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1701 .. _types-set:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1702
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1703 Set Types --- :class:`set`, :class:`frozenset`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1704 ==============================================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1705
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1706 .. index:: object: set
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1707
43753
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1708 A :dfn:`set` object is an unordered collection of distinct :term:`hashable` objects.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1709 Common uses include membership testing, removing duplicates from a sequence, and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1710 computing mathematical operations such as intersection, union, difference, and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1711 symmetric difference.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1712 (For other containers see the built in :class:`dict`, :class:`list`,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1713 and :class:`tuple` classes, and the :mod:`collections` module.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1714
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1715
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1716 .. versionadded:: 2.4
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1717
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1718 Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1719 set``. Being an unordered collection, sets do not record element position or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1720 order of insertion. Accordingly, sets do not support indexing, slicing, or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1721 other sequence-like behavior.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1722
56818
3e15a07a32fa Merged revisions 74209 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56817
diff changeset
1723 There are currently two built-in set types, :class:`set` and :class:`frozenset`.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1724 The :class:`set` type is mutable --- the contents can be changed using methods
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1725 like :meth:`add` and :meth:`remove`. Since it is mutable, it has no hash value
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1726 and cannot be used as either a dictionary key or as an element of another set.
65704
16b92971c2d4 Add version note about set literals.
Georg Brandl <georg@python.org>
parents: 65130
diff changeset
1727 The :class:`frozenset` type is immutable and :term:`hashable` --- its contents
16b92971c2d4 Add version note about set literals.
Georg Brandl <georg@python.org>
parents: 65130
diff changeset
1728 cannot be altered after it is created; it can therefore be used as a dictionary
16b92971c2d4 Add version note about set literals.
Georg Brandl <georg@python.org>
parents: 65130
diff changeset
1729 key or as an element of another set.
16b92971c2d4 Add version note about set literals.
Georg Brandl <georg@python.org>
parents: 65130
diff changeset
1730
16b92971c2d4 Add version note about set literals.
Georg Brandl <georg@python.org>
parents: 65130
diff changeset
1731 As of Python 2.7, non-empty sets (not frozensets) can be created by placing a
16b92971c2d4 Add version note about set literals.
Georg Brandl <georg@python.org>
parents: 65130
diff changeset
1732 comma-separated list of elements within braces, for example: ``{'jack',
16b92971c2d4 Add version note about set literals.
Georg Brandl <georg@python.org>
parents: 65130
diff changeset
1733 'sjoerd'}``, in addition to the :class:`set` constructor.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1734
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1735 The constructors for both classes work the same:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1736
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1737 .. class:: set([iterable])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1738 frozenset([iterable])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1739
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1740 Return a new set or frozenset object whose elements are taken from
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1741 *iterable*. The elements of a set must be hashable. To represent sets of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1742 sets, the inner sets must be :class:`frozenset` objects. If *iterable* is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1743 not specified, a new empty set is returned.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1744
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1745 Instances of :class:`set` and :class:`frozenset` provide the following
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1746 operations:
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1747
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1748 .. describe:: len(s)
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1749
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1750 Return the cardinality of set *s*.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1751
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1752 .. describe:: x in s
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1753
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1754 Test *x* for membership in *s*.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1755
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1756 .. describe:: x not in s
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1757
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1758 Test *x* for non-membership in *s*.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1759
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1760 .. method:: isdisjoint(other)
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1761
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1762 Return True if the set has no elements in common with *other*. Sets are
47937
38d3a50defec fix various doc typos #3320
Benjamin Peterson <benjamin@python.org>
parents: 47881
diff changeset
1763 disjoint if and only if their intersection is the empty set.
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1764
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1765 .. versionadded:: 2.6
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1766
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1767 .. method:: issubset(other)
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1768 set <= other
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1769
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1770 Test whether every element in the set is in *other*.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1771
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1772 .. method:: set < other
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1773
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1774 Test whether the set is a true subset of *other*, that is,
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1775 ``set <= other and set != other``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1776
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1777 .. method:: issuperset(other)
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1778 set >= other
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1779
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1780 Test whether every element in *other* is in the set.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1781
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1782 .. method:: set > other
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1783
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1784 Test whether the set is a true superset of *other*, that is, ``set >=
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1785 other and set != other``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1786
47530
d4cd7223af3b Let set.union() and set.update() accept multiple inputs.
Raymond Hettinger <python@rcn.com>
parents: 47413
diff changeset
1787 .. method:: union(other, ...)
d4cd7223af3b Let set.union() and set.update() accept multiple inputs.
Raymond Hettinger <python@rcn.com>
parents: 47413
diff changeset
1788 set | other | ...
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1789
51809
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50646
diff changeset
1790 Return a new set with elements from the set and all others.
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1791
47530
d4cd7223af3b Let set.union() and set.update() accept multiple inputs.
Raymond Hettinger <python@rcn.com>
parents: 47413
diff changeset
1792 .. versionchanged:: 2.6
d4cd7223af3b Let set.union() and set.update() accept multiple inputs.
Raymond Hettinger <python@rcn.com>
parents: 47413
diff changeset
1793 Accepts multiple input iterables.
d4cd7223af3b Let set.union() and set.update() accept multiple inputs.
Raymond Hettinger <python@rcn.com>
parents: 47413
diff changeset
1794
47533
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments.
Raymond Hettinger <python@rcn.com>
parents: 47530
diff changeset
1795 .. method:: intersection(other, ...)
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments.
Raymond Hettinger <python@rcn.com>
parents: 47530
diff changeset
1796 set & other & ...
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1797
51809
a366688a8f0d Merged revisions 68582,68718,68720-68721,68724-68727,68859,68973,69288-69289,69293,69295,69297-69301,69409,69414,69570,69573,69576,69728-69730,69769,69776,69803-69805,69840,69896 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50646
diff changeset
1798 Return a new set with elements common to the set and all others.
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1799
47533
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments.
Raymond Hettinger <python@rcn.com>
parents: 47530
diff changeset
1800 .. versionchanged:: 2.6
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments.
Raymond Hettinger <python@rcn.com>
parents: 47530
diff changeset
1801 Accepts multiple input iterables.
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments.
Raymond Hettinger <python@rcn.com>
parents: 47530
diff changeset
1802
47588
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1803 .. method:: difference(other, ...)
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1804 set - other - ...
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1805
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1806 Return a new set with elements in the set that are not in the others.
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1807
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1808 .. versionchanged:: 2.6
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1809 Accepts multiple input iterables.
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1810
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1811 .. method:: symmetric_difference(other)
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1812 set ^ other
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1813
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1814 Return a new set with elements in either the set or *other* but not both.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1815
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1816 .. method:: copy()
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1817
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1818 Return a new set with a shallow copy of *s*.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1819
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1820
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1821 Note, the non-operator versions of :meth:`union`, :meth:`intersection`,
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1822 :meth:`difference`, and :meth:`symmetric_difference`, :meth:`issubset`, and
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1823 :meth:`issuperset` methods will accept any iterable as an argument. In
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1824 contrast, their operator based counterparts require their arguments to be
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1825 sets. This precludes error-prone constructions like ``set('abc') & 'cbs'``
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1826 in favor of the more readable ``set('abc').intersection('cbs')``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1827
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1828 Both :class:`set` and :class:`frozenset` support set to set comparisons. Two
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1829 sets are equal if and only if every element of each set is contained in the
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1830 other (each is a subset of the other). A set is less than another set if and
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1831 only if the first set is a proper subset of the second set (is a subset, but
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1832 is not equal). A set is greater than another set if and only if the first set
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1833 is a proper superset of the second set (is a superset, but is not equal).
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1834
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1835 Instances of :class:`set` are compared to instances of :class:`frozenset`
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1836 based on their members. For example, ``set('abc') == frozenset('abc')``
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1837 returns ``True`` and so does ``set('abc') in set([frozenset('abc')])``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1838
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1839 The subset and equality comparisons do not generalize to a complete ordering
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1840 function. For example, any two disjoint sets are not equal and are not
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1841 subsets of each other, so *all* of the following return ``False``: ``a<b``,
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1842 ``a==b``, or ``a>b``. Accordingly, sets do not implement the :meth:`__cmp__`
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1843 method.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1844
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1845 Since sets only define partial ordering (subset relationships), the output of
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1846 the :meth:`list.sort` method is undefined for lists of sets.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1847
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1848 Set elements, like dictionary keys, must be :term:`hashable`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1849
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1850 Binary operations that mix :class:`set` instances with :class:`frozenset`
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1851 return the type of the first operand. For example: ``frozenset('ab') |
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1852 set('bc')`` returns an instance of :class:`frozenset`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1853
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1854 The following table lists operations available for :class:`set` that do not
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1855 apply to immutable instances of :class:`frozenset`:
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1856
47530
d4cd7223af3b Let set.union() and set.update() accept multiple inputs.
Raymond Hettinger <python@rcn.com>
parents: 47413
diff changeset
1857 .. method:: update(other, ...)
d4cd7223af3b Let set.union() and set.update() accept multiple inputs.
Raymond Hettinger <python@rcn.com>
parents: 47413
diff changeset
1858 set |= other | ...
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1859
56820
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56818
diff changeset
1860 Update the set, adding elements from all others.
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1861
47530
d4cd7223af3b Let set.union() and set.update() accept multiple inputs.
Raymond Hettinger <python@rcn.com>
parents: 47413
diff changeset
1862 .. versionchanged:: 2.6
d4cd7223af3b Let set.union() and set.update() accept multiple inputs.
Raymond Hettinger <python@rcn.com>
parents: 47413
diff changeset
1863 Accepts multiple input iterables.
d4cd7223af3b Let set.union() and set.update() accept multiple inputs.
Raymond Hettinger <python@rcn.com>
parents: 47413
diff changeset
1864
47533
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments.
Raymond Hettinger <python@rcn.com>
parents: 47530
diff changeset
1865 .. method:: intersection_update(other, ...)
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments.
Raymond Hettinger <python@rcn.com>
parents: 47530
diff changeset
1866 set &= other & ...
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1867
56820
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56818
diff changeset
1868 Update the set, keeping only elements found in it and all others.
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1869
47533
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments.
Raymond Hettinger <python@rcn.com>
parents: 47530
diff changeset
1870 .. versionchanged:: 2.6
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments.
Raymond Hettinger <python@rcn.com>
parents: 47530
diff changeset
1871 Accepts multiple input iterables.
10577e25f78f Let set.intersection() and set.intersection_update() take multiple input arguments.
Raymond Hettinger <python@rcn.com>
parents: 47530
diff changeset
1872
47588
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1873 .. method:: difference_update(other, ...)
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1874 set -= other | ...
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1875
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1876 Update the set, removing elements found in others.
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1877
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1878 .. versionchanged:: 2.6
8fe47b2c8bfe Multi-arg form for set.difference() and set.difference_update().
Raymond Hettinger <python@rcn.com>
parents: 47533
diff changeset
1879 Accepts multiple input iterables.
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1880
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1881 .. method:: symmetric_difference_update(other)
55775
39bcbf316dba Merged revisions 74590 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55754
diff changeset
1882 set ^= other
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1883
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1884 Update the set, keeping only elements found in either set, but not in both.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1885
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1886 .. method:: add(elem)
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1887
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1888 Add element *elem* to the set.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1889
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1890 .. method:: remove(elem)
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1891
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1892 Remove element *elem* from the set. Raises :exc:`KeyError` if *elem* is
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1893 not contained in the set.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1894
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1895 .. method:: discard(elem)
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1896
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1897 Remove element *elem* from the set if it is present.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1898
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1899 .. method:: pop()
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1900
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1901 Remove and return an arbitrary element from the set. Raises
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1902 :exc:`KeyError` if the set is empty.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1903
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1904 .. method:: clear()
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1905
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1906 Remove all elements from the set.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1907
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1908
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1909 Note, the non-operator versions of the :meth:`update`,
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1910 :meth:`intersection_update`, :meth:`difference_update`, and
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1911 :meth:`symmetric_difference_update` methods will accept any iterable as an
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1912 argument.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1913
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1914 Note, the *elem* argument to the :meth:`__contains__`, :meth:`remove`, and
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1915 :meth:`discard` methods may be a set. To support searching for an equivalent
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1916 frozenset, the *elem* set is temporarily mutated during the search and then
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1917 restored. During the search, the *elem* set should not be read or mutated
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1918 since it does not have a meaningful value.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1919
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1920
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1921 .. seealso::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1922
44050
eccb197044dd Fix reference target.
Georg Brandl <georg@python.org>
parents: 43805
diff changeset
1923 :ref:`comparison-to-builtin-set`
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1924 Differences between the :mod:`sets` module and the built-in set types.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1925
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1926
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1927 .. _typesmapping:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1928
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1929 Mapping Types --- :class:`dict`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1930 ===============================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1931
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1932 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1933 object: mapping
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1934 object: dictionary
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1935 triple: operations on; mapping; types
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1936 triple: operations on; dictionary; type
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1937 statement: del
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1938 builtin: len
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1939
43753
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1940 A :dfn:`mapping` object maps :term:`hashable` values to arbitrary objects.
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1941 Mappings are mutable objects. There is currently only one standard mapping
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1942 type, the :dfn:`dictionary`. (For other containers see the built in
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1943 :class:`list`, :class:`set`, and :class:`tuple` classes, and the
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1944 :mod:`collections` module.)
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1945
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1946 A dictionary's keys are *almost* arbitrary values. Values that are not
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1947 :term:`hashable`, that is, values containing lists, dictionaries or other
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1948 mutable types (that are compared by value rather than by object identity) may
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1949 not be used as keys. Numeric types used for keys obey the normal rules for
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1950 numeric comparison: if two numbers compare equal (such as ``1`` and ``1.0``)
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1951 then they can be used interchangeably to index the same dictionary entry. (Note
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1952 however, that since computers store floating-point numbers as approximations it
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43748
diff changeset
1953 is usually unwise to use them as dictionary keys.)
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1954
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1955 Dictionaries can be created by placing a comma-separated list of ``key: value``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1956 pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1957 'jack', 4127: 'sjoerd'}``, or by the :class:`dict` constructor.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1958
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1959 .. class:: dict([arg])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1960
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1961 Return a new dictionary initialized from an optional positional argument or from
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1962 a set of keyword arguments. If no arguments are given, return a new empty
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1963 dictionary. If the positional argument *arg* is a mapping object, return a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1964 dictionary mapping the same keys to the same values as does the mapping object.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1965 Otherwise the positional argument must be a sequence, a container that supports
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1966 iteration, or an iterator object. The elements of the argument must each also
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1967 be of one of those kinds, and each must in turn contain exactly two objects.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1968 The first is used as a key in the new dictionary, and the second as the key's
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1969 value. If a given key is seen more than once, the last value associated with it
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1970 is retained in the new dictionary.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1971
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1972 If keyword arguments are given, the keywords themselves with their associated
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1973 values are added as items to the dictionary. If a key is specified both in the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1974 positional argument and as a keyword argument, the value associated with the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1975 keyword is retained in the dictionary. For example, these all return a
66457
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66456
diff changeset
1976 dictionary equal to ``{"one": 1, "two": 2}``:
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66456
diff changeset
1977
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66456
diff changeset
1978 * ``dict(one=1, two=2)``
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66456
diff changeset
1979 * ``dict({'one': 1, 'two': 2})``
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66456
diff changeset
1980 * ``dict(zip(('one', 'two'), (1, 2)))``
a803fd841fd1 Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66456
diff changeset
1981 * ``dict([['two', 2], ['one', 1]])``
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1982
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1983 The first example only works for keys that are valid Python
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1984 identifiers; the others work with any valid keys.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1985
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1986 .. versionadded:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1987
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1988 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1989 Support for building a dictionary from keyword arguments added.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1990
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1991
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1992 These are the operations that dictionaries support (and therefore, custom
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1993 mapping types should support too):
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1994
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1995 .. describe:: len(d)
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1996
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1997 Return the number of items in the dictionary *d*.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1998
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
1999 .. describe:: d[key]
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2000
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2001 Return the item of *d* with key *key*. Raises a :exc:`KeyError` if *key*
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2002 is not in the map.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2003
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50240
diff changeset
2004 .. versionadded:: 2.5
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2005 If a subclass of dict defines a method :meth:`__missing__`, if the key
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2006 *key* is not present, the ``d[key]`` operation calls that method with
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2007 the key *key* as argument. The ``d[key]`` operation then returns or
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2008 raises whatever is returned or raised by the ``__missing__(key)`` call
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2009 if the key is not present. No other operations or methods invoke
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2010 :meth:`__missing__`. If :meth:`__missing__` is not defined,
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2011 :exc:`KeyError` is raised. :meth:`__missing__` must be a method; it
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2012 cannot be an instance variable. For an example, see
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2013 :class:`collections.defaultdict`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2014
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2015 .. describe:: d[key] = value
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2016
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2017 Set ``d[key]`` to *value*.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2018
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2019 .. describe:: del d[key]
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2020
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2021 Remove ``d[key]`` from *d*. Raises a :exc:`KeyError` if *key* is not in the
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2022 map.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2023
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2024 .. describe:: key in d
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2025
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2026 Return ``True`` if *d* has a key *key*, else ``False``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2027
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2028 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2029
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2030 .. describe:: key not in d
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2031
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2032 Equivalent to ``not key in d``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2033
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2034 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2035
52854
d90024620568 Merged revisions 71203 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52405
diff changeset
2036 .. describe:: iter(d)
d90024620568 Merged revisions 71203 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52405
diff changeset
2037
d90024620568 Merged revisions 71203 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52405
diff changeset
2038 Return an iterator over the keys of the dictionary. This is a shortcut
d90024620568 Merged revisions 71203 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52405
diff changeset
2039 for :meth:`iterkeys`.
d90024620568 Merged revisions 71203 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52405
diff changeset
2040
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2041 .. method:: clear()
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2042
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2043 Remove all items from the dictionary.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2044
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2045 .. method:: copy()
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2046
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2047 Return a shallow copy of the dictionary.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2048
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2049 .. method:: fromkeys(seq[, value])
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2050
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2051 Create a new dictionary with keys from *seq* and values set to *value*.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2052
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2053 :func:`fromkeys` is a class method that returns a new dictionary. *value*
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2054 defaults to ``None``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2055
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2056 .. versionadded:: 2.3
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2057
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2058 .. method:: get(key[, default])
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2059
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2060 Return the value for *key* if *key* is in the dictionary, else *default*.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2061 If *default* is not given, it defaults to ``None``, so that this method
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2062 never raises a :exc:`KeyError`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2063
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2064 .. method:: has_key(key)
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2065
49677
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49619
diff changeset
2066 Test for the presence of *key* in the dictionary. :meth:`has_key` is
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49619
diff changeset
2067 deprecated in favor of ``key in d``.
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2068
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2069 .. method:: items()
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2070
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2071 Return a copy of the dictionary's list of ``(key, value)`` pairs.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2072
56824
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
2073 .. impl-detail::
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2074
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2075 Keys and values are listed in an arbitrary order which is non-random,
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2076 varies across Python implementations, and depends on the dictionary's
56824
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
2077 history of insertions and deletions.
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
2078
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
2079 If :meth:`items`, :meth:`keys`, :meth:`values`, :meth:`iteritems`,
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
2080 :meth:`iterkeys`, and :meth:`itervalues` are called with no intervening
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
2081 modifications to the dictionary, the lists will directly correspond. This
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
2082 allows the creation of ``(value, key)`` pairs using :func:`zip`: ``pairs =
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
2083 zip(d.values(), d.keys())``. The same relationship holds for the
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
2084 :meth:`iterkeys` and :meth:`itervalues` methods: ``pairs =
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
2085 zip(d.itervalues(), d.iterkeys())`` provides the same value for
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
2086 ``pairs``. Another way to create the same list is ``pairs = [(v, k) for
b7b8970cd5a5 Merged revisions 75363,75365,75376,75392,75394,75403,75418,75484,75572,75580,75590,75592,75594-75596,75600,75602-75603,75605-75607,75610-75613,75616-75617,75623,75627,75647 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56820
diff changeset
2087 (k, v) in d.iteritems()]``.
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2088
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2089 .. method:: iteritems()
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2090
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2091 Return an iterator over the dictionary's ``(key, value)`` pairs. See the
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2092 note for :meth:`dict.items`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2093
52854
d90024620568 Merged revisions 71203 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52405
diff changeset
2094 Using :meth:`iteritems` while adding or deleting entries in the dictionary
54350
acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52909
diff changeset
2095 may raise a :exc:`RuntimeError` or fail to iterate over all entries.
52854
d90024620568 Merged revisions 71203 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52405
diff changeset
2096
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2097 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2098
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2099 .. method:: iterkeys()
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2100
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2101 Return an iterator over the dictionary's keys. See the note for
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2102 :meth:`dict.items`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2103
52854
d90024620568 Merged revisions 71203 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52405
diff changeset
2104 Using :meth:`iterkeys` while adding or deleting entries in the dictionary
54350
acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52909
diff changeset
2105 may raise a :exc:`RuntimeError` or fail to iterate over all entries.
52854
d90024620568 Merged revisions 71203 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52405
diff changeset
2106
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2107 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2108
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2109 .. method:: itervalues()
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2110
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2111 Return an iterator over the dictionary's values. See the note for
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2112 :meth:`dict.items`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2113
52854
d90024620568 Merged revisions 71203 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52405
diff changeset
2114 Using :meth:`itervalues` while adding or deleting entries in the
54350
acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52909
diff changeset
2115 dictionary may raise a :exc:`RuntimeError` or fail to iterate over all
acc07866b233 Merged revisions 72319-72320,72467,72661,72675-72679,72703,72708,72710,72712,72801-72802,72820,72822,72824,72826-72828,72830 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52909
diff changeset
2116 entries.
52854
d90024620568 Merged revisions 71203 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52405
diff changeset
2117
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2118 .. versionadded:: 2.2
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2119
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2120 .. method:: keys()
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2121
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2122 Return a copy of the dictionary's list of keys. See the note for
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2123 :meth:`dict.items`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2124
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2125 .. method:: pop(key[, default])
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2126
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2127 If *key* is in the dictionary, remove it and return its value, else return
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2128 *default*. If *default* is not given and *key* is not in the dictionary,
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2129 a :exc:`KeyError` is raised.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2130
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2131 .. versionadded:: 2.3
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2132
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2133 .. method:: popitem()
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2134
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2135 Remove and return an arbitrary ``(key, value)`` pair from the dictionary.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2136
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2137 :func:`popitem` is useful to destructively iterate over a dictionary, as
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2138 often used in set algorithms. If the dictionary is empty, calling
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2139 :func:`popitem` raises a :exc:`KeyError`.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2140
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2141 .. method:: setdefault(key[, default])
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2142
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2143 If *key* is in the dictionary, return its value. If not, insert *key*
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2144 with a value of *default* and return *default*. *default* defaults to
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2145 ``None``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2146
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2147 .. method:: update([other])
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2148
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2149 Update the dictionary with the key/value pairs from *other*, overwriting
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2150 existing keys. Return ``None``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2151
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2152 :func:`update` accepts either another dictionary object or an iterable of
65130
2c115bf52cff Merged revisions 85008,85011,85240 via svnmerge from
Georg Brandl <georg@python.org>
parents: 65051
diff changeset
2153 key/value pairs (as tuples or other iterables of length two). If keyword
56820
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56818
diff changeset
2154 arguments are specified, the dictionary is then updated with those
46803
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2155 key/value pairs: ``d.update(red=1, blue=2)``.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2156
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2157 .. versionchanged:: 2.4
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2158 Allowed the argument to be an iterable of key/value pairs and allowed
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2159 keyword arguments.
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2160
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2161 .. method:: values()
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2162
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2163 Return a copy of the dictionary's list of values. See the note for
802519f04754 In stdtypes.rst, move methods under class directives where applicable
Benjamin Peterson <benjamin@python.org>
parents: 46744
diff changeset
2164 :meth:`dict.items`.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2165
58256
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2166 .. method:: viewitems()
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2167
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2168 Return a new view of the dictionary's items (``(key, value)`` pairs). See
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2169 below for documentation of view objects.
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2170
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2171 .. versionadded:: 2.7
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2172
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2173 .. method:: viewkeys()
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2174
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2175 Return a new view of the dictionary's keys. See below for documentation of
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2176 view objects.
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2177
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2178 .. versionadded:: 2.7
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2179
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2180 .. method:: viewvalues()
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2181
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2182 Return a new view of the dictionary's values. See below for documentation of
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2183 view objects.
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2184
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2185 .. versionadded:: 2.7
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2186
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2187
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2188 .. _dict-views:
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2189
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2190 Dictionary view objects
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2191 -----------------------
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2192
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2193 The objects returned by :meth:`dict.viewkeys`, :meth:`dict.viewvalues` and
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2194 :meth:`dict.viewitems` are *view objects*. They provide a dynamic view on the
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2195 dictionary's entries, which means that when the dictionary changes, the view
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2196 reflects these changes.
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2197
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2198 Dictionary views can be iterated over to yield their respective data, and
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2199 support membership tests:
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2200
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2201 .. describe:: len(dictview)
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2202
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2203 Return the number of entries in the dictionary.
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2204
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2205 .. describe:: iter(dictview)
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2206
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2207 Return an iterator over the keys, values or items (represented as tuples of
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2208 ``(key, value)``) in the dictionary.
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2209
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2210 Keys and values are iterated over in an arbitrary order which is non-random,
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2211 varies across Python implementations, and depends on the dictionary's history
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2212 of insertions and deletions. If keys, values and items views are iterated
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2213 over with no intervening modifications to the dictionary, the order of items
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2214 will directly correspond. This allows the creation of ``(value, key)`` pairs
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2215 using :func:`zip`: ``pairs = zip(d.values(), d.keys())``. Another way to
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2216 create the same list is ``pairs = [(v, k) for (k, v) in d.items()]``.
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2217
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2218 Iterating views while adding or deleting entries in the dictionary may raise
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2219 a :exc:`RuntimeError` or fail to iterate over all entries.
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2220
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2221 .. describe:: x in dictview
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2222
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2223 Return ``True`` if *x* is in the underlying dictionary's keys, values or
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2224 items (in the latter case, *x* should be a ``(key, value)`` tuple).
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2225
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2226
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2227 Keys views are set-like since their entries are unique and hashable. If all
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2228 values are hashable, so that (key, value) pairs are unique and hashable, then
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2229 the items view is also set-like. (Values views are not treated as set-like
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2230 since the entries are generally not unique.) Then these set operations are
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2231 available ("other" refers either to another view or a set):
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2232
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2233 .. describe:: dictview & other
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2234
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2235 Return the intersection of the dictview and the other object as a new set.
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2236
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2237 .. describe:: dictview | other
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2238
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2239 Return the union of the dictview and the other object as a new set.
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2240
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2241 .. describe:: dictview - other
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2242
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2243 Return the difference between the dictview and the other object (all elements
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2244 in *dictview* that aren't in *other*) as a new set.
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2245
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2246 .. describe:: dictview ^ other
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2247
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2248 Return the symmetric difference (all elements either in *dictview* or
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2249 *other*, but not in both) of the dictview and the other object as a new set.
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2250
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2251
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2252 An example of dictionary view usage::
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2253
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2254 >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500}
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2255 >>> keys = dishes.viewkeys()
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2256 >>> values = dishes.viewvalues()
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2257
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2258 >>> # iteration
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2259 >>> n = 0
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2260 >>> for val in values:
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2261 ... n += val
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2262 >>> print(n)
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2263 504
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2264
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2265 >>> # keys and values are iterated over in the same order
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2266 >>> list(keys)
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2267 ['eggs', 'bacon', 'sausage', 'spam']
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2268 >>> list(values)
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2269 [2, 1, 1, 500]
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2270
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2271 >>> # view objects are dynamic and reflect dict changes
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2272 >>> del dishes['eggs']
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2273 >>> del dishes['sausage']
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2274 >>> list(keys)
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2275 ['spam', 'bacon']
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2276
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2277 >>> # set operations
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2278 >>> keys & {'eggs', 'bacon', 'salad'}
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2279 {'bacon'}
d9805a96351c Issue #1967: Backport dictionary views.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 57795
diff changeset
2280
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2281
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2282 .. _bltin-file-objects:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2283
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2284 File Objects
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2285 ============
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2286
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2287 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2288 object: file
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2289 builtin: file
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2290 module: os
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2291 module: socket
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2292
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2293 File objects are implemented using C's ``stdio`` package and can be
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44344
diff changeset
2294 created with the built-in :func:`open` function. File
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2295 objects are also returned by some other built-in functions and methods,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2296 such as :func:`os.popen` and :func:`os.fdopen` and the :meth:`makefile`
43748
8a40b831ab68 Added more file-handling related cross-references.
Mark Summerfield <list@qtrac.plus.com>
parents: 43738
diff changeset
2297 method of socket objects. Temporary files can be created using the
8a40b831ab68 Added more file-handling related cross-references.
Mark Summerfield <list@qtrac.plus.com>
parents: 43738
diff changeset
2298 :mod:`tempfile` module, and high-level file operations such as copying,
8a40b831ab68 Added more file-handling related cross-references.
Mark Summerfield <list@qtrac.plus.com>
parents: 43738
diff changeset
2299 moving, and deleting files and directories can be achieved with the
8a40b831ab68 Added more file-handling related cross-references.
Mark Summerfield <list@qtrac.plus.com>
parents: 43738
diff changeset
2300 :mod:`shutil` module.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2301
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2302 When a file operation fails for an I/O-related reason, the exception
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2303 :exc:`IOError` is raised. This includes situations where the operation is not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2304 defined for some reason, like :meth:`seek` on a tty device or writing a file
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2305 opened for reading.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2306
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2307 Files have the following methods:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2308
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2309
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2310 .. method:: file.close()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2311
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2312 Close the file. A closed file cannot be read or written any more. Any operation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2313 which requires that the file be open will raise a :exc:`ValueError` after the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2314 file has been closed. Calling :meth:`close` more than once is allowed.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2315
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2316 As of Python 2.5, you can avoid having to call this method explicitly if you use
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2317 the :keyword:`with` statement. For example, the following code will
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44344
diff changeset
2318 automatically close *f* when the :keyword:`with` block is exited::
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2319
48097
0c7fab0b05c0 the from __future__ import with_statement isn't needed in 2.6
Benjamin Peterson <benjamin@python.org>
parents: 48081
diff changeset
2320 from __future__ import with_statement # This isn't required in Python 2.6
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2321
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2322 with open("hello.txt") as f:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2323 for line in f:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2324 print line
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2325
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2326 In older versions of Python, you would have needed to do this to get the same
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2327 effect::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2328
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2329 f = open("hello.txt")
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2330 try:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2331 for line in f:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2332 print line
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2333 finally:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2334 f.close()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2335
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2336 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2337
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2338 Not all "file-like" types in Python support use as a context manager for the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2339 :keyword:`with` statement. If your code is intended to work with any file-like
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2340 object, you can use the function :func:`contextlib.closing` instead of using
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2341 the object directly.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2342
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2343
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2344 .. method:: file.flush()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2345
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74330
diff changeset
2346 Flush the internal buffer, like ``stdio``'s :c:func:`fflush`. This may be a
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2347 no-op on some file-like objects.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2348
56801
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56289
diff changeset
2349 .. note::
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56289
diff changeset
2350
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56289
diff changeset
2351 :meth:`flush` does not necessarily write the file's data to disk. Use
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56289
diff changeset
2352 :meth:`flush` followed by :func:`os.fsync` to ensure this behavior.
e3e53b89c178 Merged revisions 69520,69633,69672,69703-69704,69717,69731 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56289
diff changeset
2353
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2354
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2355 .. method:: file.fileno()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2356
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2357 .. index::
43627
faf5de69e977 Add :term:s for descriptors.
Georg Brandl <georg@python.org>
parents: 43585
diff changeset
2358 pair: file; descriptor
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2359 module: fcntl
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2360
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2361 Return the integer "file descriptor" that is used by the underlying
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2362 implementation to request I/O operations from the operating system. This can be
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2363 useful for other, lower level interfaces that use file descriptors, such as the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2364 :mod:`fcntl` module or :func:`os.read` and friends.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2365
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2366 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2367
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2368 File-like objects which do not have a real file descriptor should *not* provide
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2369 this method!
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2370
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2371
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2372 .. method:: file.isatty()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2373
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2374 Return ``True`` if the file is connected to a tty(-like) device, else ``False``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2375
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2376 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2377
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2378 If a file-like object is not associated with a real file, this method should
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2379 *not* be implemented.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2380
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2381
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2382 .. method:: file.next()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2383
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2384 A file object is its own iterator, for example ``iter(f)`` returns *f* (unless
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2385 *f* is closed). When a file is used as an iterator, typically in a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2386 :keyword:`for` loop (for example, ``for line in f: print line``), the
74469
51e11b4937b7 file.next() doc refers to itself
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74397
diff changeset
2387 :meth:`~file.next` method is called repeatedly. This method returns the next input
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2388 line, or raises :exc:`StopIteration` when EOF is hit when the file is open for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2389 reading (behavior is undefined when the file is open for writing). In order to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2390 make a :keyword:`for` loop the most efficient way of looping over the lines of a
74469
51e11b4937b7 file.next() doc refers to itself
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74397
diff changeset
2391 file (a very common operation), the :meth:`~file.next` method uses a hidden read-ahead
51e11b4937b7 file.next() doc refers to itself
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74397
diff changeset
2392 buffer. As a consequence of using a read-ahead buffer, combining :meth:`~file.next`
76595
707905b3f8df refer to file.readline() in stdtypes doc; thanks to Mihai Capotă from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74625
diff changeset
2393 with other file methods (like :meth:`~file.readline`) does not work right. However,
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2394 using :meth:`seek` to reposition the file to an absolute position will flush the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2395 read-ahead buffer.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2396
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2397 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2398
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2399
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2400 .. method:: file.read([size])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2401
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2402 Read at most *size* bytes from the file (less if the read hits EOF before
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2403 obtaining *size* bytes). If the *size* argument is negative or omitted, read
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2404 all data until EOF is reached. The bytes are returned as a string object. An
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2405 empty string is returned when EOF is encountered immediately. (For certain
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2406 files, like ttys, it makes sense to continue reading after an EOF is hit.) Note
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74330
diff changeset
2407 that this method may call the underlying C function :c:func:`fread` more than
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2408 once in an effort to acquire as close to *size* bytes as possible. Also note
47881
7d1e61492c7d Tweak wording
Andrew M. Kuchling <amk@amk.ca>
parents: 47865
diff changeset
2409 that when in non-blocking mode, less data than was requested may be
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2410 returned, even if no *size* parameter was given.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2411
47865
cda556d23924 #1523853: add note about fread().
Georg Brandl <georg@python.org>
parents: 47787
diff changeset
2412 .. note::
48081
767cc89e3fde This sentence continues to bug me; rewrite it for the second time
Andrew M. Kuchling <amk@amk.ca>
parents: 48003
diff changeset
2413 This function is simply a wrapper for the underlying
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74330
diff changeset
2414 :c:func:`fread` C function, and will behave the same in corner cases,
48081
767cc89e3fde This sentence continues to bug me; rewrite it for the second time
Andrew M. Kuchling <amk@amk.ca>
parents: 48003
diff changeset
2415 such as whether the EOF value is cached.
47865
cda556d23924 #1523853: add note about fread().
Georg Brandl <georg@python.org>
parents: 47787
diff changeset
2416
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2417
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2418 .. method:: file.readline([size])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2419
68409
c017695acf19 clarify condition for readline to return EOF (closes #11312)
Benjamin Peterson <benjamin@python.org>
parents: 68296
diff changeset
2420 Read one entire line from the file. A trailing newline character is kept in
71954
02ceeae05432 Turn last automatic footnote in this file into a manually-numbered one
Éric Araujo <merwok@netwok.org>
parents: 71871
diff changeset
2421 the string (but may be absent when a file ends with an incomplete line). [6]_
68409
c017695acf19 clarify condition for readline to return EOF (closes #11312)
Benjamin Peterson <benjamin@python.org>
parents: 68296
diff changeset
2422 If the *size* argument is present and non-negative, it is a maximum byte
c017695acf19 clarify condition for readline to return EOF (closes #11312)
Benjamin Peterson <benjamin@python.org>
parents: 68296
diff changeset
2423 count (including the trailing newline) and an incomplete line may be
c017695acf19 clarify condition for readline to return EOF (closes #11312)
Benjamin Peterson <benjamin@python.org>
parents: 68296
diff changeset
2424 returned. When *size* is not 0, an empty string is returned *only* when EOF
c017695acf19 clarify condition for readline to return EOF (closes #11312)
Benjamin Peterson <benjamin@python.org>
parents: 68296
diff changeset
2425 is encountered immediately.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2426
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2427 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2428
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74330
diff changeset
2429 Unlike ``stdio``'s :c:func:`fgets`, the returned string contains null characters
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2430 (``'\0'``) if they occurred in the input.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2431
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2432
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2433 .. method:: file.readlines([sizehint])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2434
76595
707905b3f8df refer to file.readline() in stdtypes doc; thanks to Mihai Capotă from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74625
diff changeset
2435 Read until EOF using :meth:`~file.readline` and return a list containing the lines
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2436 thus read. If the optional *sizehint* argument is present, instead of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2437 reading up to EOF, whole lines totalling approximately *sizehint* bytes
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2438 (possibly after rounding up to an internal buffer size) are read. Objects
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2439 implementing a file-like interface may choose to ignore *sizehint* if it
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2440 cannot be implemented, or cannot be implemented efficiently.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2441
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2442
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2443 .. method:: file.xreadlines()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2444
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2445 This method returns the same thing as ``iter(f)``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2446
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2447 .. versionadded:: 2.1
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2448
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2449 .. deprecated:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2450 Use ``for line in file`` instead.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2451
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2452
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2453 .. method:: file.seek(offset[, whence])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2454
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74330
diff changeset
2455 Set the file's current position, like ``stdio``'s :c:func:`fseek`. The *whence*
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2456 argument is optional and defaults to ``os.SEEK_SET`` or ``0`` (absolute file
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2457 positioning); other values are ``os.SEEK_CUR`` or ``1`` (seek relative to the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2458 current position) and ``os.SEEK_END`` or ``2`` (seek relative to the file's
44497
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
2459 end). There is no return value.
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50240
diff changeset
2460
44497
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
2461 For example, ``f.seek(2, os.SEEK_CUR)`` advances the position by two and
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
2462 ``f.seek(-3, os.SEEK_END)`` sets the position to the third to last.
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
2463
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
2464 Note that if the file is opened for appending
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2465 (mode ``'a'`` or ``'a+'``), any :meth:`seek` operations will be undone at the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2466 next write. If the file is only opened for writing in append mode (mode
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2467 ``'a'``), this method is essentially a no-op, but it remains useful for files
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2468 opened in append mode with reading enabled (mode ``'a+'``). If the file is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2469 opened in text mode (without ``'b'``), only offsets returned by :meth:`tell` are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2470 legal. Use of other offsets causes undefined behavior.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2471
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2472 Note that not all file objects are seekable.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2473
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2474 .. versionchanged:: 2.6
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44344
diff changeset
2475 Passing float values as offset has been deprecated.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2476
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2477
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2478 .. method:: file.tell()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2479
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74330
diff changeset
2480 Return the file's current position, like ``stdio``'s :c:func:`ftell`.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2481
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2482 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2483
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74330
diff changeset
2484 On Windows, :meth:`tell` can return illegal values (after an :c:func:`fgets`)
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2485 when reading files with Unix-style line-endings. Use binary mode (``'rb'``) to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2486 circumvent this problem.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2487
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2488
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2489 .. method:: file.truncate([size])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2490
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2491 Truncate the file's size. If the optional *size* argument is present, the file
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2492 is truncated to (at most) that size. The size defaults to the current position.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2493 The current file position is not changed. Note that if a specified size exceeds
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2494 the file's current size, the result is platform-dependent: possibilities
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2495 include that the file may remain unchanged, increase to the specified size as if
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2496 zero-filled, or increase to the specified size with undefined new content.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2497 Availability: Windows, many Unix variants.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2498
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2499
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2500 .. method:: file.write(str)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2501
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2502 Write a string to the file. There is no return value. Due to buffering, the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2503 string may not actually show up in the file until the :meth:`flush` or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2504 :meth:`close` method is called.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2505
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2506
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2507 .. method:: file.writelines(sequence)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2508
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2509 Write a sequence of strings to the file. The sequence can be any iterable
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2510 object producing strings, typically a list of strings. There is no return value.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2511 (The name is intended to match :meth:`readlines`; :meth:`writelines` does not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2512 add line separators.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2513
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2514 Files support the iterator protocol. Each iteration returns the same result as
76595
707905b3f8df refer to file.readline() in stdtypes doc; thanks to Mihai Capotă from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74625
diff changeset
2515 :meth:`~file.readline`, and iteration ends when the :meth:`~file.readline` method returns
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2516 an empty string.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2517
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2518 File objects also offer a number of other interesting attributes. These are not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2519 required for file-like objects, but should be implemented if they make sense for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2520 the particular object.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2521
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2522
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2523 .. attribute:: file.closed
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2524
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2525 bool indicating the current state of the file object. This is a read-only
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2526 attribute; the :meth:`close` method changes the value. It may not be available
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2527 on all file-like objects.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2528
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2529
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2530 .. attribute:: file.encoding
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2531
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2532 The encoding that this file uses. When Unicode strings are written to a file,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2533 they will be converted to byte strings using this encoding. In addition, when
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2534 the file is connected to a terminal, the attribute gives the encoding that the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2535 terminal is likely to use (that information might be incorrect if the user has
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2536 misconfigured the terminal). The attribute is read-only and may not be present
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2537 on all file-like objects. It may also be ``None``, in which case the file uses
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2538 the system default encoding for converting Unicode strings.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2539
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2540 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2541
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2542
47413
1062b7dec95b New environment variable PYTHONIOENCODING.
Martin v. Löwis <martin@v.loewis.de>
parents: 46949
diff changeset
2543 .. attribute:: file.errors
1062b7dec95b New environment variable PYTHONIOENCODING.
Martin v. Löwis <martin@v.loewis.de>
parents: 46949
diff changeset
2544
47787
b32101c19bf8 Grammar fixes
Andrew M. Kuchling <amk@amk.ca>
parents: 47588
diff changeset
2545 The Unicode error handler used along with the encoding.
47413
1062b7dec95b New environment variable PYTHONIOENCODING.
Martin v. Löwis <martin@v.loewis.de>
parents: 46949
diff changeset
2546
1062b7dec95b New environment variable PYTHONIOENCODING.
Martin v. Löwis <martin@v.loewis.de>
parents: 46949
diff changeset
2547 .. versionadded:: 2.6
1062b7dec95b New environment variable PYTHONIOENCODING.
Martin v. Löwis <martin@v.loewis.de>
parents: 46949
diff changeset
2548
1062b7dec95b New environment variable PYTHONIOENCODING.
Martin v. Löwis <martin@v.loewis.de>
parents: 46949
diff changeset
2549
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2550 .. attribute:: file.mode
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2551
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2552 The I/O mode for the file. If the file was created using the :func:`open`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2553 built-in function, this will be the value of the *mode* parameter. This is a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2554 read-only attribute and may not be present on all file-like objects.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2555
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2556
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2557 .. attribute:: file.name
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2558
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2559 If the file object was created using :func:`open`, the name of the file.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2560 Otherwise, some string that indicates the source of the file object, of the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2561 form ``<...>``. This is a read-only attribute and may not be present on all
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2562 file-like objects.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2563
78596
8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it.
R David Murray <rdmurray@bitdance.com>
parents: 78521
diff changeset
2564 .. index::
8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it.
R David Murray <rdmurray@bitdance.com>
parents: 78521
diff changeset
2565 single: universal newlines; file.newlines attribute
8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it.
R David Murray <rdmurray@bitdance.com>
parents: 78521
diff changeset
2566
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2567
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2568 .. attribute:: file.newlines
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2569
78596
8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it.
R David Murray <rdmurray@bitdance.com>
parents: 78521
diff changeset
2570 If Python was built with :term:`universal newlines` enabled (the default) this
68761
5c1a91809821 the name of the option is a bit too low-level
Benjamin Peterson <benjamin@python.org>
parents: 68409
diff changeset
2571 read-only attribute exists, and for files opened in universal newline read
5c1a91809821 the name of the option is a bit too low-level
Benjamin Peterson <benjamin@python.org>
parents: 68409
diff changeset
2572 mode it keeps track of the types of newlines encountered while reading the
5c1a91809821 the name of the option is a bit too low-level
Benjamin Peterson <benjamin@python.org>
parents: 68409
diff changeset
2573 file. The values it can take are ``'\r'``, ``'\n'``, ``'\r\n'``, ``None``
5c1a91809821 the name of the option is a bit too low-level
Benjamin Peterson <benjamin@python.org>
parents: 68409
diff changeset
2574 (unknown, no newlines read yet) or a tuple containing all the newline types
5c1a91809821 the name of the option is a bit too low-level
Benjamin Peterson <benjamin@python.org>
parents: 68409
diff changeset
2575 seen, to indicate that multiple newline conventions were encountered. For
78596
8795cd3b4c8c #15543: glossary entry for and 'universal newlines', and links to it.
R David Murray <rdmurray@bitdance.com>
parents: 78521
diff changeset
2576 files not opened in universal newlines read mode the value of this attribute
68761
5c1a91809821 the name of the option is a bit too low-level
Benjamin Peterson <benjamin@python.org>
parents: 68409
diff changeset
2577 will be ``None``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2578
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2579
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2580 .. attribute:: file.softspace
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2581
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2582 Boolean that indicates whether a space character needs to be printed before
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2583 another value when using the :keyword:`print` statement. Classes that are trying
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2584 to simulate a file object should also have a writable :attr:`softspace`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2585 attribute, which should be initialized to zero. This will be automatic for most
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2586 classes implemented in Python (care may be needed for objects that override
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2587 attribute access); types implemented in C will have to provide a writable
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2588 :attr:`softspace` attribute.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2589
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2590 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2591
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2592 This attribute is not used to control the :keyword:`print` statement, but to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2593 allow the implementation of :keyword:`print` to keep track of its internal
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2594 state.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2595
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2596
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2597 .. _typememoryview:
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2598
60281
82c2034b8095 Fix wording / typography, and a slightly misleading statement
Antoine Pitrou <solipsis@pitrou.net>
parents: 59810
diff changeset
2599 memoryview type
82c2034b8095 Fix wording / typography, and a slightly misleading statement
Antoine Pitrou <solipsis@pitrou.net>
parents: 59810
diff changeset
2600 ===============
82c2034b8095 Fix wording / typography, and a slightly misleading statement
Antoine Pitrou <solipsis@pitrou.net>
parents: 59810
diff changeset
2601
64951
7ac30d58b1d2 versionadded #9956
Benjamin Peterson <benjamin@python.org>
parents: 63748
diff changeset
2602 .. versionadded:: 2.7
7ac30d58b1d2 versionadded #9956
Benjamin Peterson <benjamin@python.org>
parents: 63748
diff changeset
2603
60281
82c2034b8095 Fix wording / typography, and a slightly misleading statement
Antoine Pitrou <solipsis@pitrou.net>
parents: 59810
diff changeset
2604 :class:`memoryview` objects allow Python code to access the internal data
82c2034b8095 Fix wording / typography, and a slightly misleading statement
Antoine Pitrou <solipsis@pitrou.net>
parents: 59810
diff changeset
2605 of an object that supports the buffer protocol without copying. Memory
82c2034b8095 Fix wording / typography, and a slightly misleading statement
Antoine Pitrou <solipsis@pitrou.net>
parents: 59810
diff changeset
2606 is generally interpreted as simple bytes.
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2607
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2608 .. class:: memoryview(obj)
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2609
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2610 Create a :class:`memoryview` that references *obj*. *obj* must support the
68296
aea4a7861390 #11373: fix spelling.
Georg Brandl <georg@python.org>
parents: 68256
diff changeset
2611 buffer protocol. Built-in objects that support the buffer protocol include
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2612 :class:`str` and :class:`bytearray` (but not :class:`unicode`).
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2613
62993
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2614 A :class:`memoryview` has the notion of an *element*, which is the
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2615 atomic memory unit handled by the originating object *obj*. For many
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2616 simple types such as :class:`str` and :class:`bytearray`, an element
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2617 is a single byte, but other third-party types may expose larger elements.
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2618
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2619 ``len(view)`` returns the total number of elements in the memoryview,
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2620 *view*. The :class:`~memoryview.itemsize` attribute will give you the
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2621 number of bytes in a single element.
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2622
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2623 A :class:`memoryview` supports slicing to expose its data. Taking a single
62993
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2624 index will return a single element as a :class:`str` object. Full
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2625 slicing will result in a subview::
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2626
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2627 >>> v = memoryview('abcefg')
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2628 >>> v[1]
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2629 'b'
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2630 >>> v[-1]
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2631 'g'
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2632 >>> v[1:4]
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2633 <memory at 0x77ab28>
63103
e1bc2c8935d2 Issue #9304: fix example in the 2.x memoryview documentation.
Antoine Pitrou <solipsis@pitrou.net>
parents: 62993
diff changeset
2634 >>> v[1:4].tobytes()
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2635 'bce'
62993
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2636
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2637 If the object the memoryview is over supports changing its data, the
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2638 memoryview supports slice assignment::
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2639
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2640 >>> data = bytearray('abcefg')
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2641 >>> v = memoryview(data)
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2642 >>> v.readonly
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2643 False
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2644 >>> v[0] = 'z'
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2645 >>> data
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2646 bytearray(b'zbcefg')
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2647 >>> v[1:4] = '123'
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2648 >>> data
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2649 bytearray(b'z123fg')
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2650 >>> v[2] = 'spam'
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2651 Traceback (most recent call last):
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2652 File "<stdin>", line 1, in <module>
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2653 ValueError: cannot modify size of memoryview object
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2654
61145
82da290ff722 Minor grammar fix
Andrew M. Kuchling <amk@amk.ca>
parents: 61036
diff changeset
2655 Notice how the size of the memoryview object cannot be changed.
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2656
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2657 :class:`memoryview` has two methods:
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2658
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2659 .. method:: tobytes()
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2660
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2661 Return the data in the buffer as a bytestring (an object of class
62993
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2662 :class:`str`). ::
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2663
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2664 >>> m = memoryview("abc")
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2665 >>> m.tobytes()
4ef639f4d810 Merged revisions 82842 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 62827
diff changeset
2666 'abc'
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2667
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2668 .. method:: tolist()
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2669
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2670 Return the data in the buffer as a list of integers. ::
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2671
63103
e1bc2c8935d2 Issue #9304: fix example in the 2.x memoryview documentation.
Antoine Pitrou <solipsis@pitrou.net>
parents: 62993
diff changeset
2672 >>> memoryview("abc").tolist()
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2673 [97, 98, 99]
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2674
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2675 There are also several readonly attributes available:
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2676
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2677 .. attribute:: format
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2678
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2679 A string containing the format (in :mod:`struct` module style) for each
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2680 element in the view. This defaults to ``'B'``, a simple bytestring.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2681
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2682 .. attribute:: itemsize
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2683
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2684 The size in bytes of each element of the memoryview.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2685
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2686 .. attribute:: shape
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2687
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2688 A tuple of integers the length of :attr:`ndim` giving the shape of the
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2689 memory as a N-dimensional array.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2690
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2691 .. attribute:: ndim
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2692
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2693 An integer indicating how many dimensions of a multi-dimensional array the
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2694 memory represents.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2695
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2696 .. attribute:: strides
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2697
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2698 A tuple of integers the length of :attr:`ndim` giving the size in bytes to
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2699 access each element for each dimension of the array.
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2700
68015
8eeee9d6d32b Merged revisions 87050,87101,87146,87156,87172,87175,87371,87378,87522-87524,87526,87530-87535 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66996
diff changeset
2701 .. attribute:: readonly
8eeee9d6d32b Merged revisions 87050,87101,87146,87156,87172,87175,87371,87378,87522-87524,87526,87530-87535 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66996
diff changeset
2702
8eeee9d6d32b Merged revisions 87050,87101,87146,87156,87172,87175,87371,87378,87522-87524,87526,87530-87535 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66996
diff changeset
2703 A bool indicating whether the memory is read only.
8eeee9d6d32b Merged revisions 87050,87101,87146,87156,87172,87175,87371,87378,87522-87524,87526,87530-87535 via svnmerge from
Georg Brandl <georg@python.org>
parents: 66996
diff changeset
2704
52749
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2705 .. memoryview.suboffsets isn't documented because it only seems useful for C
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2706
75efd757434b Issue #2396: backport the memoryview object.
Antoine Pitrou <solipsis@pitrou.net>
parents: 52569
diff changeset
2707
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2708 .. _typecontextmanager:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2709
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2710 Context Manager Types
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2711 =====================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2712
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2713 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2714
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2715 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2716 single: context manager
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2717 single: context management protocol
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2718 single: protocol; context management
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2719
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2720 Python's :keyword:`with` statement supports the concept of a runtime context
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2721 defined by a context manager. This is implemented using two separate methods
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2722 that allow user-defined classes to define a runtime context that is entered
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2723 before the statement body is executed and exited when the statement ends.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2724
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2725 The :dfn:`context management protocol` consists of a pair of methods that need
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2726 to be provided for a context manager object to define a runtime context:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2727
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2728
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2729 .. method:: contextmanager.__enter__()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2730
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2731 Enter the runtime context and return either this object or another object
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2732 related to the runtime context. The value returned by this method is bound to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2733 the identifier in the :keyword:`as` clause of :keyword:`with` statements using
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2734 this context manager.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2735
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2736 An example of a context manager that returns itself is a file object. File
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2737 objects return themselves from __enter__() to allow :func:`open` to be used as
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2738 the context expression in a :keyword:`with` statement.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2739
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2740 An example of a context manager that returns a related object is the one
44524
79a34248a262 #1680: fix context manager example function name.
Georg Brandl <georg@python.org>
parents: 44497
diff changeset
2741 returned by :func:`decimal.localcontext`. These managers set the active
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2742 decimal context to a copy of the original decimal context and then return the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2743 copy. This allows changes to be made to the current decimal context in the body
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2744 of the :keyword:`with` statement without affecting code outside the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2745 :keyword:`with` statement.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2746
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2747
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2748 .. method:: contextmanager.__exit__(exc_type, exc_val, exc_tb)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2749
43585
f1f701c224c1 Issue 1289, just a typo.
Facundo Batista <facundobatista@gmail.com>
parents: 43492
diff changeset
2750 Exit the runtime context and return a Boolean flag indicating if any exception
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2751 that occurred should be suppressed. If an exception occurred while executing the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2752 body of the :keyword:`with` statement, the arguments contain the exception type,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2753 value and traceback information. Otherwise, all three arguments are ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2754
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2755 Returning a true value from this method will cause the :keyword:`with` statement
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2756 to suppress the exception and continue execution with the statement immediately
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2757 following the :keyword:`with` statement. Otherwise the exception continues
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2758 propagating after this method has finished executing. Exceptions that occur
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2759 during execution of this method will replace any exception that occurred in the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2760 body of the :keyword:`with` statement.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2761
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2762 The exception passed in should never be reraised explicitly - instead, this
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2763 method should return a false value to indicate that the method completed
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2764 successfully and does not want to suppress the raised exception. This allows
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2765 context management code (such as ``contextlib.nested``) to easily detect whether
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2766 or not an :meth:`__exit__` method has actually failed.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2767
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2768 Python defines several context managers to support easy thread synchronisation,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2769 prompt closure of files or other objects, and simpler manipulation of the active
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2770 decimal arithmetic context. The specific types are not treated specially beyond
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2771 their implementation of the context management protocol. See the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2772 :mod:`contextlib` module for some examples.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2773
56820
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56818
diff changeset
2774 Python's :term:`generator`\s and the ``contextlib.contextmanager`` :term:`decorator`
44103
1e266015cf5b Add more entries to the glossary.
Georg Brandl <georg@python.org>
parents: 44050
diff changeset
2775 provide a convenient way to implement these protocols. If a generator function is
56820
85aa706f7126 Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56818
diff changeset
2776 decorated with the ``contextlib.contextmanager`` decorator, it will return a
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2777 context manager implementing the necessary :meth:`__enter__` and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2778 :meth:`__exit__` methods, rather than the iterator produced by an undecorated
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2779 generator function.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2780
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2781 Note that there is no specific slot for any of these methods in the type
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2782 structure for Python objects in the Python/C API. Extension types wanting to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2783 define these methods must provide them as a normal Python accessible method.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2784 Compared to the overhead of setting up the runtime context, the overhead of a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2785 single class dictionary lookup is negligible.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2786
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2787
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2788 .. _typesother:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2789
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2790 Other Built-in Types
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2791 ====================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2792
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2793 The interpreter supports several other kinds of objects. Most of these support
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2794 only one or two operations.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2795
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2796
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2797 .. _typesmodules:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2798
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2799 Modules
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2800 -------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2801
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2802 The only special operation on a module is attribute access: ``m.name``, where
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2803 *m* is a module and *name* accesses a name defined in *m*'s symbol table.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2804 Module attributes can be assigned to. (Note that the :keyword:`import`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2805 statement is not, strictly speaking, an operation on a module object; ``import
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2806 foo`` does not require a module object named *foo* to exist, rather it requires
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2807 an (external) *definition* for a module named *foo* somewhere.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2808
71212
b8f5da066782 Fix closes issue10403 - Let's not use members anymore.
Senthil Kumaran <senthil@uthcode.com>
parents: 69949
diff changeset
2809 A special attribute of every module is :attr:`__dict__`. This is the dictionary
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2810 containing the module's symbol table. Modifying this dictionary will actually
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2811 change the module's symbol table, but direct assignment to the :attr:`__dict__`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2812 attribute is not possible (you can write ``m.__dict__['a'] = 1``, which defines
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2813 ``m.a`` to be ``1``, but you can't write ``m.__dict__ = {}``). Modifying
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2814 :attr:`__dict__` directly is not recommended.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2815
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2816 Modules built into the interpreter are written like this: ``<module 'sys'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2817 (built-in)>``. If loaded from a file, they are written as ``<module 'os' from
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2818 '/usr/local/lib/pythonX.Y/os.pyc'>``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2819
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2820
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2821 .. _typesobjects:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2822
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2823 Classes and Class Instances
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2824 ---------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2825
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2826 See :ref:`objects` and :ref:`class` for these.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2827
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2828
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2829 .. _typesfunctions:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2830
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2831 Functions
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2832 ---------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2833
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2834 Function objects are created by function definitions. The only operation on a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2835 function object is to call it: ``func(argument-list)``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2836
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2837 There are really two flavors of function objects: built-in functions and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2838 user-defined functions. Both support the same operation (to call the function),
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2839 but the implementation is different, hence the different object types.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2840
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2841 See :ref:`function` for more information.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2842
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2843
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2844 .. _typesmethods:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2845
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2846 Methods
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2847 -------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2848
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2849 .. index:: object: method
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2850
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2851 Methods are functions that are called using the attribute notation. There are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2852 two flavors: built-in methods (such as :meth:`append` on lists) and class
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2853 instance methods. Built-in methods are described with the types that support
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2854 them.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2855
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2856 The implementation adds two special read-only attributes to class instance
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2857 methods: ``m.im_self`` is the object on which the method operates, and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2858 ``m.im_func`` is the function implementing the method. Calling ``m(arg-1,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2859 arg-2, ..., arg-n)`` is completely equivalent to calling ``m.im_func(m.im_self,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2860 arg-1, arg-2, ..., arg-n)``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2861
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2862 Class instance methods are either *bound* or *unbound*, referring to whether the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2863 method was accessed through an instance or a class, respectively. When a method
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2864 is unbound, its ``im_self`` attribute will be ``None`` and if called, an
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2865 explicit ``self`` object must be passed as the first argument. In this case,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2866 ``self`` must be an instance of the unbound method's class (or a subclass of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2867 that class), otherwise a :exc:`TypeError` is raised.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2868
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2869 Like function objects, methods objects support getting arbitrary attributes.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2870 However, since method attributes are actually stored on the underlying function
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2871 object (``meth.im_func``), setting method attributes on either bound or unbound
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2872 methods is disallowed. Attempting to set a method attribute results in a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2873 :exc:`TypeError` being raised. In order to set a method attribute, you need to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2874 explicitly set it on the underlying function object::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2875
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2876 class C:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2877 def method(self):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2878 pass
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2879
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2880 c = C()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2881 c.method.im_func.whoami = 'my name is c'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2882
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2883 See :ref:`types` for more information.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2884
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2885
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2886 .. _bltin-code-objects:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2887
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2888 Code Objects
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2889 ------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2890
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2891 .. index:: object: code
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2892
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2893 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2894 builtin: compile
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2895 single: func_code (function object attribute)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2896
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2897 Code objects are used by the implementation to represent "pseudo-compiled"
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2898 executable Python code such as a function body. They differ from function
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2899 objects because they don't contain a reference to their global execution
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2900 environment. Code objects are returned by the built-in :func:`compile` function
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2901 and can be extracted from function objects through their :attr:`func_code`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2902 attribute. See also the :mod:`code` module.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2903
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2904 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2905 statement: exec
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2906 builtin: eval
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2907
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2908 A code object can be executed or evaluated by passing it (instead of a source
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2909 string) to the :keyword:`exec` statement or the built-in :func:`eval` function.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2910
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2911 See :ref:`types` for more information.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2912
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2913
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2914 .. _bltin-type-objects:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2915
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2916 Type Objects
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2917 ------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2918
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2919 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2920 builtin: type
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2921 module: types
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2922
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2923 Type objects represent the various object types. An object's type is accessed
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2924 by the built-in function :func:`type`. There are no special operations on
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2925 types. The standard module :mod:`types` defines names for all standard built-in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2926 types.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2927
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2928 Types are written like this: ``<type 'int'>``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2929
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2930
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2931 .. _bltin-null-object:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2932
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2933 The Null Object
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2934 ---------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2935
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2936 This object is returned by functions that don't explicitly return a value. It
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2937 supports no special operations. There is exactly one null object, named
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2938 ``None`` (a built-in name).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2939
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2940 It is written as ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2941
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2942
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2943 .. _bltin-ellipsis-object:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2944
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2945 The Ellipsis Object
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2946 -------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2947
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2948 This object is used by extended slice notation (see :ref:`slicings`). It
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2949 supports no special operations. There is exactly one ellipsis object, named
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2950 :const:`Ellipsis` (a built-in name).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2951
71648
ac2a695ff888 be precise
Benjamin Peterson <benjamin@python.org>
parents: 71637
diff changeset
2952 It is written as ``Ellipsis``. When in a subscript, it can also be written as
ac2a695ff888 be precise
Benjamin Peterson <benjamin@python.org>
parents: 71637
diff changeset
2953 ``...``, for example ``seq[...]``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2954
71636
5a9272785d5f add space
Benjamin Peterson <benjamin@python.org>
parents: 71635
diff changeset
2955
71635
1446c126d6f2 document NotImplemented
Benjamin Peterson <benjamin@python.org>
parents: 71212
diff changeset
2956 The NotImplemented Object
1446c126d6f2 document NotImplemented
Benjamin Peterson <benjamin@python.org>
parents: 71212
diff changeset
2957 -------------------------
1446c126d6f2 document NotImplemented
Benjamin Peterson <benjamin@python.org>
parents: 71212
diff changeset
2958
1446c126d6f2 document NotImplemented
Benjamin Peterson <benjamin@python.org>
parents: 71212
diff changeset
2959 This object is returned from comparisons and binary operations when they are
1446c126d6f2 document NotImplemented
Benjamin Peterson <benjamin@python.org>
parents: 71212
diff changeset
2960 asked to operate on types they don't support. See :ref:`comparisons` for more
1446c126d6f2 document NotImplemented
Benjamin Peterson <benjamin@python.org>
parents: 71212
diff changeset
2961 information.
1446c126d6f2 document NotImplemented
Benjamin Peterson <benjamin@python.org>
parents: 71212
diff changeset
2962
1446c126d6f2 document NotImplemented
Benjamin Peterson <benjamin@python.org>
parents: 71212
diff changeset
2963 It is written as ``NotImplemented``.
1446c126d6f2 document NotImplemented
Benjamin Peterson <benjamin@python.org>
parents: 71212
diff changeset
2964
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2965
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2966 Boolean Values
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2967 --------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2968
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2969 Boolean values are the two constant objects ``False`` and ``True``. They are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2970 used to represent truth values (although other values can also be considered
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2971 false or true). In numeric contexts (for example when used as the argument to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2972 an arithmetic operator), they behave like the integers 0 and 1, respectively.
73812
2f9c986b46cd #13494: s/cast/convert/. Also add a link.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 72984
diff changeset
2973 The built-in function :func:`bool` can be used to convert any value to a
2f9c986b46cd #13494: s/cast/convert/. Also add a link.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 72984
diff changeset
2974 Boolean, if the value can be interpreted as a truth value (see section
2f9c986b46cd #13494: s/cast/convert/. Also add a link.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 72984
diff changeset
2975 :ref:`truth` above).
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2976
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2977 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2978 single: False
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2979 single: True
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2980 pair: Boolean; values
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2981
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2982 They are written as ``False`` and ``True``, respectively.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2983
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2984
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2985 .. _typesinternal:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2986
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2987 Internal Objects
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2988 ----------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2989
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2990 See :ref:`types` for this information. It describes stack frame objects,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2991 traceback objects, and slice objects.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2992
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2993
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2994 .. _specialattrs:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2995
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2996 Special Attributes
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2997 ==================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2998
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2999 The implementation adds a few special read-only attributes to several object
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3000 types, where they are relevant. Some of these are not reported by the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3001 :func:`dir` built-in function.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3002
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3003
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3004 .. attribute:: object.__dict__
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3005
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3006 A dictionary or other mapping object used to store an object's (writable)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3007 attributes.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3008
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3009
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3010 .. attribute:: object.__methods__
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3011
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3012 .. deprecated:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3013 Use the built-in function :func:`dir` to get a list of an object's attributes.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3014 This attribute is no longer available.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3015
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3016
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3017 .. attribute:: object.__members__
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3018
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3019 .. deprecated:: 2.2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3020 Use the built-in function :func:`dir` to get a list of an object's attributes.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3021 This attribute is no longer available.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3022
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3023
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3024 .. attribute:: instance.__class__
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3025
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3026 The class to which a class instance belongs.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3027
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3028
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3029 .. attribute:: class.__bases__
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3030
59831
38e9b9da0164 Merged revisions 76538,76559,76882-76883,76886,76891-76892,76920,76924-76925,77081,77084,77086,77092 via svnmerge from
Georg Brandl <georg@python.org>
parents: 57796
diff changeset
3031 The tuple of base classes of a class object.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3032
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3033
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3034 .. attribute:: class.__name__
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3035
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3036 The name of the class or type.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3037
52898
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52854
diff changeset
3038
52900
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3039 The following attributes are only supported by :term:`new-style class`\ es.
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3040
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3041 .. attribute:: class.__mro__
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3042
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3043 This attribute is a tuple of classes that are considered when looking for
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3044 base classes during method resolution.
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3045
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3046
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3047 .. method:: class.mro()
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3048
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3049 This method can be overridden by a metaclass to customize the method
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3050 resolution order for its instances. It is called at class instantiation, and
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3051 its result is stored in :attr:`__mro__`.
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3052
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3053
52898
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52854
diff changeset
3054 .. method:: class.__subclasses__
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52854
diff changeset
3055
52900
4acbbb3e65e2 Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52898
diff changeset
3056 Each new-style class keeps a list of weak references to its immediate
52898
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52854
diff changeset
3057 subclasses. This method returns a list of all those references still alive.
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52854
diff changeset
3058 Example::
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52854
diff changeset
3059
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52854
diff changeset
3060 >>> int.__subclasses__()
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52854
diff changeset
3061 [<type 'bool'>]
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52854
diff changeset
3062
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52854
diff changeset
3063
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3064 .. rubric:: Footnotes
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3065
71871
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
3066 .. [1] Additional information on these special methods may be found in the Python
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3067 Reference Manual (:ref:`customization`).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3068
71871
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
3069 .. [2] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0]``, and
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3070 similarly for tuples.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3071
71871
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
3072 .. [3] They must have since the parser can't tell the type of the operands.
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
3073
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
3074 .. [4] Cased characters are those with general category property being one of
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
3075 "Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecase).
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
3076
fb49394f75ed #12204: document that str.upper().isupper() might be False and add a note about cased characters.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71648
diff changeset
3077 .. [5] To format only a tuple you should therefore provide a singleton tuple whose only
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3078 element is the tuple to be formatted.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3079
71954
02ceeae05432 Turn last automatic footnote in this file into a manually-numbered one
Éric Araujo <merwok@netwok.org>
parents: 71871
diff changeset
3080 .. [6] The advantage of leaving the newline on is that returning an empty string is
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3081 then an unambiguous EOF indication. It is also possible (in cases where it
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3082 might matter, for example, if you want to make an exact copy of a file while
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3083 scanning its lines) to tell whether the last line of a file ended in a newline
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3084 or not (yes this happens!).