Mercurial > cpython-lru_cache-weakref

annotate Doc/reference/expressions.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 a62309ae88a2
children a0f6c68ea12f
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2 .. _expressions:
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 ***********
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Expressions
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. index:: single: expression
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 This chapter explains the meaning of the elements of expressions in Python.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 .. index:: single: BNF
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 **Syntax Notes:** In this and the following chapters, extended BNF notation will
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 be used to describe syntax, not lexical analysis. When (one alternative of) a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16 syntax rule has the form
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 .. productionlist:: *
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 name: `othername`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 .. index:: single: syntax
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 and no semantics are given, the semantics of this form of ``name`` are the same
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24 as for ``othername``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
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 .. _conversions:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 Arithmetic conversions
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 ======================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 .. index:: pair: arithmetic; conversion
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 When a description of an arithmetic operator below uses the phrase "the numeric
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 arguments are converted to a common type," the arguments are coerced using the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 coercion rules listed at :ref:`coercion-rules`. If both arguments are standard
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 numeric types, the following coercions are applied:
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 * If either argument is a complex number, the other is converted to complex;
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 * otherwise, if either argument is a floating point number, the other is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 converted to floating point;
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 * otherwise, if either argument is a long integer, the other is converted to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 long integer;
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 * otherwise, both must be plain integers and no conversion is necessary.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 Some additional rules apply for certain operators (e.g., a string left argument
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 to the '%' operator). Extensions can define their own coercions.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 .. _atoms:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
54
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 Atoms
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 =====
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 .. index:: single: atom
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 Atoms are the most basic elements of expressions. The simplest atoms are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 identifiers or literals. Forms enclosed in reverse quotes or in parentheses,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 brackets or braces are also categorized syntactically as atoms. The syntax for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 atoms is:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 atom: `identifier` | `literal` | `enclosure`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 enclosure: `parenth_form` | `list_display`
58229
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
68 : | `generator_expression` | `dict_display` | `set_display`
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 : | `string_conversion` | `yield_atom`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 .. _atom-identifiers:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 Identifiers (Names)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 -------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 single: name
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 single: identifier
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 An identifier occurring as an atom is a name. See section :ref:`identifiers`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 for lexical definition and section :ref:`naming` for documentation of naming and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 binding.
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 .. index:: exception: NameError
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 When the name is bound to an object, evaluation of the atom yields that object.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 When a name is not bound, an attempt to evaluate it raises a :exc:`NameError`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 exception.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 pair: name; mangling
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 pair: private; names
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 **Private name mangling:** When an identifier that textually occurs in a class
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 definition begins with two or more underscore characters and does not end in two
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 or more underscores, it is considered a :dfn:`private name` of that class.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 Private names are transformed to a longer form before code is generated for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 them. The transformation inserts the class name in front of the name, with
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 leading underscores removed, and a single underscore inserted in front of the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 class name. For example, the identifier ``__spam`` occurring in a class named
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 ``Ham`` will be transformed to ``_Ham__spam``. This transformation is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 independent of the syntactical context in which the identifier is used. If the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 transformed name is extremely long (longer than 255 characters), implementation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 defined truncation may happen. If the class name consists only of underscores,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 no transformation is done.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
107
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
110 .. _atom-literals:
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 Literals
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 .. index:: single: literal
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 Python supports string literals and various numeric literals:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 literal: `stringliteral` | `integer` | `longinteger`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 : | `floatnumber` | `imagnumber`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 Evaluation of a literal yields an object of the given type (string, integer,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 long integer, floating point number, complex number) with the given value. The
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 value may be approximated in the case of floating point and imaginary (complex)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
126 literals. See section :ref:`literals` for details.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
129 triple: immutable; data; type
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
130 pair: immutable; object
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 All literals correspond to immutable data types, and hence the object's identity
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 is less important than its value. Multiple evaluations of literals with the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134 same value (either the same occurrence in the program text or a different
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
135 occurrence) may obtain the same object or a different object with the same
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 value.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
137
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
138
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
139 .. _parenthesized:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
140
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
141 Parenthesized forms
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
142 -------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
143
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 .. index:: single: parenthesized form
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
145
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
146 A parenthesized form is an optional expression list enclosed in parentheses:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
147
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149 parenth_form: "(" [`expression_list`] ")"
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
150
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
151 A parenthesized expression list yields whatever that expression list yields: if
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
152 the list contains at least one comma, it yields a tuple; otherwise, it yields
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
153 the single expression that makes up the expression list.
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 .. index:: pair: empty; tuple
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 An empty pair of parentheses yields an empty tuple object. Since tuples are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 immutable, the rules for literals apply (i.e., two occurrences of the empty
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
159 tuple may or may not yield the same object).
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 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162 single: comma
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
163 pair: tuple; display
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 Note that tuples are not formed by the parentheses, but rather by use of the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
166 comma operator. The exception is the empty tuple, for which parentheses *are*
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
167 required --- allowing unparenthesized "nothing" in expressions would cause
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 ambiguities and allow common typos to pass uncaught.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
169
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 .. _lists:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 List displays
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174 -------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177 pair: list; display
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178 pair: list; comprehensions
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 A list display is a possibly empty series of expressions enclosed in square
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 brackets:
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 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
184 list_display: "[" [`expression_list` | `list_comprehension`] "]"
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185 list_comprehension: `expression` `list_for`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 list_for: "for" `target_list` "in" `old_expression_list` [`list_iter`]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 old_expression_list: `old_expression` [("," `old_expression`)+ [","]]
59841
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
188 old_expression: `or_test` | `old_lambda_form`
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 list_iter: `list_for` | `list_if`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 list_if: "if" `old_expression` [`list_iter`]
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::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 pair: list; comprehensions
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
194 object: list
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
195 pair: empty; list
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
196
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
197 A list display yields a new list object. Its contents are specified by
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
198 providing either a list of expressions or a list comprehension. When a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 comma-separated list of expressions is supplied, its elements are evaluated from
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
200 left to right and placed into the list object in that order. When a list
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
201 comprehension is supplied, it consists of a single expression followed by at
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
202 least one :keyword:`for` clause and zero or more :keyword:`for` or :keyword:`if`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
203 clauses. In this case, the elements of the new list are those that would be
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
204 produced by considering each of the :keyword:`for` or :keyword:`if` clauses a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
205 block, nesting from left to right, and evaluating the expression to produce a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 list element each time the innermost block is reached [#]_.
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
58250
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
209 .. _comprehensions:
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
210
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
211 Displays for sets and dictionaries
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
212 ----------------------------------
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
213
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
214 For constructing a set or a dictionary Python provides special syntax
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
215 called "displays", each of them in two flavors:
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
216
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
217 * either the container contents are listed explicitly, or
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
218
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
219 * they are computed via a set of looping and filtering instructions, called a
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
220 :dfn:`comprehension`.
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
221
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
222 Common syntax elements for comprehensions are:
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
223
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
224 .. productionlist::
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
225 comprehension: `expression` `comp_for`
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
226 comp_for: "for" `target_list` "in" `or_test` [`comp_iter`]
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
227 comp_iter: `comp_for` | `comp_if`
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
228 comp_if: "if" `expression_nocond` [`comp_iter`]
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
229
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
230 The comprehension consists of a single expression followed by at least one
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
231 :keyword:`for` clause and zero or more :keyword:`for` or :keyword:`if` clauses.
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
232 In this case, the elements of the new container are those that would be produced
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
233 by considering each of the :keyword:`for` or :keyword:`if` clauses a block,
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
234 nesting from left to right, and evaluating the expression to produce an element
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
235 each time the innermost block is reached.
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
236
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
237 Note that the comprehension is executed in a separate scope, so names assigned
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
238 to in the target list don't "leak" in the enclosing scope.
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
239
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
240
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
241 .. _genexpr:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
242
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
243 Generator expressions
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
244 ---------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
245
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
246 .. index:: pair: generator; expression
58250
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
247 object: generator
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
248
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
249 A generator expression is a compact generator notation in parentheses:
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 .. productionlist::
58250
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
252 generator_expression: "(" `expression` `comp_for` ")"
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
253
58250
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
254 A generator expression yields a new generator object. Its syntax is the same as
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
255 for comprehensions, except that it is enclosed in parentheses instead of
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
256 brackets or curly braces.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
257
58250
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
258 Variables used in the generator expression are evaluated lazily when the
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
259 :meth:`__next__` method is called for generator object (in the same fashion as
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
260 normal generators). However, the leftmost :keyword:`for` clause is immediately
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
261 evaluated, so that an error produced by it can be seen before any other possible
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
262 error in the code that handles the generator expression. Subsequent
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
263 :keyword:`for` clauses cannot be evaluated immediately since they may depend on
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
264 the previous :keyword:`for` loop. For example: ``(x*y for x in range(10) for y
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
265 in bar(x))``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
266
58250
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
267 The parentheses can be omitted on calls with only one argument. See section
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
268 :ref:`calls` for the detail.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
269
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
270 .. _dict:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
271
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
272 Dictionary displays
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
273 -------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
274
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
275 .. index:: pair: dictionary; display
58250
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
276 key, datum, key/datum pair
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
277 object: dictionary
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
278
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
279 A dictionary display is a possibly empty series of key/datum pairs enclosed in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
280 curly braces:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
281
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
282 .. productionlist::
58250
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
283 dict_display: "{" [`key_datum_list` | `dict_comprehension`] "}"
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
284 key_datum_list: `key_datum` ("," `key_datum`)* [","]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
285 key_datum: `expression` ":" `expression`
58250
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
286 dict_comprehension: `expression` ":" `expression` `comp_for`
42603
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 A dictionary display yields a new dictionary object.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
289
58250
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
290 If a comma-separated sequence of key/datum pairs is given, they are evaluated
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
291 from left to right to define the entries of the dictionary: each key object is
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
292 used as a key into the dictionary to store the corresponding datum. This means
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
293 that you can specify the same key multiple times in the key/datum list, and the
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
294 final dictionary's value for that key will be the last one given.
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
295
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
296 A dict comprehension, in contrast to list and set comprehensions, needs two
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
297 expressions separated with a colon followed by the usual "for" and "if" clauses.
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
298 When the comprehension is run, the resulting key and value elements are inserted
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
299 in the new dictionary in the order they are produced.
42603
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 .. index:: pair: immutable; object
58250
edfed0e32ced Issue #2333: Backport set and dict comprehensions syntax.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 58229
diff changeset
302 hashable
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
303
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
304 Restrictions on the types of the key values are listed earlier in section
43753
4b3623568e6c Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
Georg Brandl <georg@python.org>
parents: 43456
diff changeset
305 :ref:`types`. (To summarize, the key type should be :term:`hashable`, which excludes
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
306 all mutable objects.) Clashes between duplicate keys are not detected; the last
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
307 datum (textually rightmost in the display) stored for a given key value
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
308 prevails.
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
58229
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
311 .. _set:
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
312
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
313 Set displays
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
314 ------------
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
315
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
316 .. index:: pair: set; display
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
317 object: set
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
318
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
319 A set display is denoted by curly braces and distinguishable from dictionary
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
320 displays by the lack of colons separating keys and values:
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
321
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
322 .. productionlist::
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
323 set_display: "{" (`expression_list` | `comprehension`) "}"
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
324
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
325 A set display yields a new mutable set object, the contents being specified by
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
326 either a sequence of expressions or a comprehension. When a comma-separated
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
327 list of expressions is supplied, its elements are evaluated from left to right
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
328 and added to the set object. When a comprehension is supplied, the set is
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
329 constructed from the elements resulting from the comprehension.
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
330
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
331 An empty set cannot be constructed with ``{}``; this literal constructs an empty
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
332 dictionary.
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
333
c2fdf25329ff Issue #2335: Backport set literals syntax from Python 3.x.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 56672
diff changeset
334
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
335 .. _string-conversions:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
336
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
337 String conversions
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
338 ------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
339
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
340 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
341 pair: string; conversion
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
342 pair: reverse; quotes
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
343 pair: backward; quotes
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
344 single: back-quotes
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 A string conversion is an expression list enclosed in reverse (a.k.a. backward)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
347 quotes:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
348
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
349 .. productionlist::
73259
3a126a459b6f really use backticks in string conversion definition; thanks to Jonathan Blakes from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 71643
diff changeset
350 string_conversion: "`" `expression_list` "`"
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
351
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
352 A string conversion evaluates the contained expression list and converts the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
353 resulting object into a string according to rules specific to its type.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
354
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
355 If the object is a string, a number, ``None``, or a tuple, list or dictionary
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
356 containing only objects whose type is one of these, the resulting string is a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
357 valid Python expression which can be passed to the built-in function
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
358 :func:`eval` to yield an expression with the same value (or an approximation, if
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
359 floating point numbers are involved).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
360
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
361 (In particular, converting a string adds quotes around it and converts "funny"
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
362 characters to escape sequences that are safe to print.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
363
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
364 .. index:: object: recursive
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
365
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
366 Recursive objects (for example, lists or dictionaries that contain a reference
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
367 to themselves, directly or indirectly) use ``...`` to indicate a recursive
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
368 reference, and the result cannot be passed to :func:`eval` to get an equal value
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
369 (:exc:`SyntaxError` will be raised instead).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
370
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
371 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
372 builtin: repr
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
373 builtin: str
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
374
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
375 The built-in function :func:`repr` performs exactly the same conversion in its
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
376 argument as enclosing it in parentheses and reverse quotes does. The built-in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
377 function :func:`str` performs a similar but more user-friendly conversion.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
378
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
379
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
380 .. _yieldexpr:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
381
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
382 Yield expressions
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
383 -----------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
384
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
385 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
386 keyword: yield
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
387 pair: yield; expression
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
388 pair: generator; function
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
389
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
390 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
391 yield_atom: "(" `yield_expression` ")"
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
392 yield_expression: "yield" [`expression_list`]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
393
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
394 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
395
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
396 The :keyword:`yield` expression is only used when defining a generator function,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
397 and can only be used in the body of a function definition. Using a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
398 :keyword:`yield` expression in a function definition is sufficient to cause that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
399 definition to create a generator function instead of a normal function.
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 When a generator function is called, it returns an iterator known as a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
402 generator. That generator then controls the execution of a generator function.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
403 The execution starts when one of the generator's methods is called. At that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
404 time, the execution proceeds to the first :keyword:`yield` expression, where it
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
405 is suspended again, returning the value of :token:`expression_list` to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
406 generator's caller. By suspended we mean that all local state is retained,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
407 including the current bindings of local variables, the instruction pointer, and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
408 the internal evaluation stack. When the execution is resumed by calling one of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
409 the generator's methods, the function can proceed exactly as if the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
410 :keyword:`yield` expression was just another external call. The value of the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
411 :keyword:`yield` expression after resuming depends on the method which resumed
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
412 the execution.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
413
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
414 .. index:: single: coroutine
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
415
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
416 All of this makes generator functions quite similar to coroutines; they yield
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
417 multiple times, they have more than one entry point and their execution can be
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
418 suspended. The only difference is that a generator function cannot control
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
419 where should the execution continue after it yields; the control is always
65129
baa98ba85fd4 Merged revisions 84945 via svnmerge from
Georg Brandl <georg@python.org>
parents: 65127
diff changeset
420 transferred to the generator's caller.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
421
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
422 .. index:: object: generator
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
423
78632
a62309ae88a2 #15355: Mention already-executing Exception in generator docs.
R David Murray <rdmurray@bitdance.com>
parents: 76732
diff changeset
424
a62309ae88a2 #15355: Mention already-executing Exception in generator docs.
R David Murray <rdmurray@bitdance.com>
parents: 76732
diff changeset
425 Generator-iterator methods
a62309ae88a2 #15355: Mention already-executing Exception in generator docs.
R David Murray <rdmurray@bitdance.com>
parents: 76732
diff changeset
426 ^^^^^^^^^^^^^^^^^^^^^^^^^^
a62309ae88a2 #15355: Mention already-executing Exception in generator docs.
R David Murray <rdmurray@bitdance.com>
parents: 76732
diff changeset
427
a62309ae88a2 #15355: Mention already-executing Exception in generator docs.
R David Murray <rdmurray@bitdance.com>
parents: 76732
diff changeset
428 This subsection describes the methods of a generator iterator. They can
a62309ae88a2 #15355: Mention already-executing Exception in generator docs.
R David Murray <rdmurray@bitdance.com>
parents: 76732
diff changeset
429 be used to control the execution of a generator function.
a62309ae88a2 #15355: Mention already-executing Exception in generator docs.
R David Murray <rdmurray@bitdance.com>
parents: 76732
diff changeset
430
a62309ae88a2 #15355: Mention already-executing Exception in generator docs.
R David Murray <rdmurray@bitdance.com>
parents: 76732
diff changeset
431 Note that calling any of the generator methods below when the generator
a62309ae88a2 #15355: Mention already-executing Exception in generator docs.
R David Murray <rdmurray@bitdance.com>
parents: 76732
diff changeset
432 is already executing raises a :exc:`ValueError` exception.
42603
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 .. index:: exception: StopIteration
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
435
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 .. method:: generator.next()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
438
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
439 Starts the execution of a generator function or resumes it at the last executed
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
440 :keyword:`yield` expression. When a generator function is resumed with a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
441 :meth:`next` method, the current :keyword:`yield` expression always evaluates to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
442 :const:`None`. The execution then continues to the next :keyword:`yield`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
443 expression, where the generator is suspended again, and the value of the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
444 :token:`expression_list` is returned to :meth:`next`'s caller. If the generator
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
445 exits without yielding another value, a :exc:`StopIteration` exception is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
446 raised.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
447
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 .. method:: generator.send(value)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
450
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
451 Resumes the execution and "sends" a value into the generator function. The
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
452 ``value`` argument becomes the result of the current :keyword:`yield`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
453 expression. The :meth:`send` method returns the next value yielded by the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
454 generator, or raises :exc:`StopIteration` if the generator exits without
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
455 yielding another value. When :meth:`send` is called to start the generator, it
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
456 must be called with :const:`None` as the argument, because there is no
45429
853af5bbb497 A lot more typo fixes by Ori Avtalion.
Georg Brandl <georg@python.org>
parents: 44497
diff changeset
457 :keyword:`yield` expression that could receive the value.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
460 .. method:: generator.throw(type[, value[, traceback]])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
461
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
462 Raises an exception of type ``type`` at the point where generator was paused,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
463 and returns the next value yielded by the generator function. If the generator
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
464 exits without yielding another value, a :exc:`StopIteration` exception is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
465 raised. If the generator function does not catch the passed-in exception, or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
466 raises a different exception, then that exception propagates to the caller.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
467
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
468 .. index:: exception: GeneratorExit
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
469
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
470
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
471 .. method:: generator.close()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
472
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
473 Raises a :exc:`GeneratorExit` at the point where the generator function was
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
474 paused. If the generator function then raises :exc:`StopIteration` (by exiting
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
475 normally, or due to already being closed) or :exc:`GeneratorExit` (by not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
476 catching the exception), close returns to its caller. If the generator yields a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
477 value, a :exc:`RuntimeError` is raised. If the generator raises any other
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
478 exception, it is propagated to the caller. :meth:`close` does nothing if the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
479 generator has already exited due to an exception or normal exit.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
480
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
481 Here is a simple example that demonstrates the behavior of generators and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
482 generator functions::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
483
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
484 >>> def echo(value=None):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
485 ... print "Execution starts when 'next()' is called for the first time."
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
486 ... try:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
487 ... while True:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
488 ... try:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
489 ... value = (yield value)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
490 ... except Exception, e:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
491 ... value = e
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
492 ... finally:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
493 ... print "Don't forget to clean up when 'close()' is called."
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
494 ...
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
495 >>> generator = echo(1)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
496 >>> print generator.next()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
497 Execution starts when 'next()' is called for the first time.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
498 1
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
499 >>> print generator.next()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
500 None
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
501 >>> print generator.send(2)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
502 2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
503 >>> generator.throw(TypeError, "spam")
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
504 TypeError('spam',)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
505 >>> generator.close()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
506 Don't forget to clean up when 'close()' is called.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
507
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
508
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
509 .. seealso::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
510
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
511 :pep:`0342` - Coroutines via Enhanced Generators
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
512 The proposal to enhance the API and syntax of generators, making them usable as
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
513 simple coroutines.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
514
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
515
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
516 .. _primaries:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
517
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
518 Primaries
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
519 =========
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
520
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
521 .. index:: single: primary
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
522
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
523 Primaries represent the most tightly bound operations of the language. Their
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
524 syntax is:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
525
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
526 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
527 primary: `atom` | `attributeref` | `subscription` | `slicing` | `call`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
528
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
529
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
530 .. _attribute-references:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
531
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
532 Attribute references
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
533 --------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
534
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
535 .. index:: pair: attribute; reference
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
536
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
537 An attribute reference is a primary followed by a period and a name:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
538
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
539 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
540 attributeref: `primary` "." `identifier`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
541
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
542 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
543 exception: AttributeError
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
544 object: module
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
545 object: list
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
546
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
547 The primary must evaluate to an object of a type that supports attribute
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
548 references, e.g., a module, list, or an instance. This object is then asked to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
549 produce the attribute whose name is the identifier. If this attribute is not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
550 available, the exception :exc:`AttributeError` is raised. Otherwise, the type
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
551 and value of the object produced is determined by the object. Multiple
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
552 evaluations of the same attribute reference may yield different objects.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
553
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
554
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
555 .. _subscriptions:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
556
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
557 Subscriptions
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
558 -------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
559
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
560 .. index:: single: subscription
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
561
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
562 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
563 object: sequence
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
564 object: mapping
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
565 object: string
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
566 object: tuple
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
567 object: list
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
568 object: dictionary
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
569 pair: sequence; item
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
570
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
571 A subscription selects an item of a sequence (string, tuple or list) or mapping
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
572 (dictionary) object:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
573
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
574 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
575 subscription: `primary` "[" `expression_list` "]"
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
576
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
577 The primary must evaluate to an object of a sequence or mapping type.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
578
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
579 If the primary is a mapping, the expression list must evaluate to an object
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
580 whose value is one of the keys of the mapping, and the subscription selects the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
581 value in the mapping that corresponds to that key. (The expression list is a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
582 tuple except if it has exactly one item.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
583
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
584 If the primary is a sequence, the expression (list) must evaluate to a plain
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
585 integer. If this value is negative, the length of the sequence is added to it
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
586 (so that, e.g., ``x[-1]`` selects the last item of ``x``.) The resulting value
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
587 must be a nonnegative integer less than the number of items in the sequence, and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
588 the subscription selects the item whose index is that value (counting from
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
589 zero).
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 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
592 single: character
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
593 pair: string; item
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
594
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
595 A string's items are characters. A character is not a separate data type but a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
596 string of exactly one character.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
597
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
598
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
599 .. _slicings:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
600
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
601 Slicings
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
602 --------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
604 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
605 single: slicing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
606 single: slice
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
607
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
608 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
609 object: sequence
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
610 object: string
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
611 object: tuple
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
612 object: list
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
613
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
614 A slicing selects a range of items in a sequence object (e.g., a string, tuple
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
615 or list). Slicings may be used as expressions or as targets in assignment or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
616 :keyword:`del` statements. The syntax for a slicing:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
617
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
618 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
619 slicing: `simple_slicing` | `extended_slicing`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
620 simple_slicing: `primary` "[" `short_slice` "]"
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: 49278
diff changeset
621 extended_slicing: `primary` "[" `slice_list` "]"
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
622 slice_list: `slice_item` ("," `slice_item`)* [","]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
623 slice_item: `expression` | `proper_slice` | `ellipsis`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
624 proper_slice: `short_slice` | `long_slice`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
625 short_slice: [`lower_bound`] ":" [`upper_bound`]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
626 long_slice: `short_slice` ":" [`stride`]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
627 lower_bound: `expression`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
628 upper_bound: `expression`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
629 stride: `expression`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
630 ellipsis: "..."
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 .. index:: pair: extended; slicing
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 There is ambiguity in the formal syntax here: anything that looks like an
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
635 expression list also looks like a slice list, so any subscription can be
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
636 interpreted as a slicing. Rather than further complicating the syntax, this is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
637 disambiguated by defining that in this case the interpretation as a subscription
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
638 takes priority over the interpretation as a slicing (this is the case if the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
639 slice list contains no proper slice nor ellipses). Similarly, when the slice
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
640 list has exactly one short slice and no trailing comma, the interpretation as a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
641 simple slicing takes priority over that as an extended slicing.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
642
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
643 The semantics for a simple slicing are as follows. The primary must evaluate to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
644 a sequence object. The lower and upper bound expressions, if present, must
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
645 evaluate to plain integers; defaults are zero and the ``sys.maxint``,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
646 respectively. If either bound is negative, the sequence's length is added to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
647 it. The slicing now selects all items with index *k* such that ``i <= k < j``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
648 where *i* and *j* are the specified lower and upper bounds. This may be an
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
649 empty sequence. It is not an error if *i* or *j* lie outside the range of valid
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
650 indexes (such items don't exist so they aren't selected).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
651
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
652 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
653 single: start (slice object attribute)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
654 single: stop (slice object attribute)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
655 single: step (slice object attribute)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
656
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
657 The semantics for an extended slicing are as follows. The primary must evaluate
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
658 to a mapping object, and it is indexed with a key that is constructed from the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
659 slice list, as follows. If the slice list contains at least one comma, the key
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
660 is a tuple containing the conversion of the slice items; otherwise, the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
661 conversion of the lone slice item is the key. The conversion of a slice item
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
662 that is an expression is that expression. The conversion of an ellipsis slice
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
663 item is the built-in ``Ellipsis`` object. The conversion of a proper slice is a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
664 slice object (see section :ref:`types`) whose :attr:`start`, :attr:`stop` and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
665 :attr:`step` attributes are the values of the expressions given as lower bound,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
666 upper bound and stride, respectively, substituting ``None`` for missing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
667 expressions.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
668
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
669
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
670 .. _calls:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
671
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
672 Calls
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
673 -----
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 .. index:: single: call
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
676
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
677 .. index:: object: callable
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
678
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
679 A call calls a callable object (e.g., a function) with a possibly empty series
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
680 of arguments:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
681
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
682 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
683 call: `primary` "(" [`argument_list` [","]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
684 : | `expression` `genexpr_for`] ")"
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
685 argument_list: `positional_arguments` ["," `keyword_arguments`]
48307
49f52e285a64 allow keyword args to be passed in after *args #3473
Benjamin Peterson <benjamin@python.org>
parents: 48239
diff changeset
686 : ["," "*" `expression`] ["," `keyword_arguments`]
49f52e285a64 allow keyword args to be passed in after *args #3473
Benjamin Peterson <benjamin@python.org>
parents: 48239
diff changeset
687 : ["," "**" `expression`]
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
688 : | `keyword_arguments` ["," "*" `expression`]
48307
49f52e285a64 allow keyword args to be passed in after *args #3473
Benjamin Peterson <benjamin@python.org>
parents: 48239
diff changeset
689 : ["," "**" `expression`]
49f52e285a64 allow keyword args to be passed in after *args #3473
Benjamin Peterson <benjamin@python.org>
parents: 48239
diff changeset
690 : | "*" `expression` ["," "*" `expression`] ["," "**" `expression`]
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
691 : | "**" `expression`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
692 positional_arguments: `expression` ("," `expression`)*
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
693 keyword_arguments: `keyword_item` ("," `keyword_item`)*
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
694 keyword_item: `identifier` "=" `expression`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
695
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
696 A trailing comma may be present after the positional and keyword arguments but
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
697 does not affect the semantics.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
698
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
699 The primary must evaluate to a callable object (user-defined functions, built-in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
700 functions, methods of built-in objects, class objects, methods of class
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
701 instances, and certain class instances themselves are callable; extensions may
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
702 define additional callable object types). All argument expressions are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
703 evaluated before the call is attempted. Please refer to section :ref:`function`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
704 for the syntax of formal parameter lists.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
705
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
706 If keyword arguments are present, they are first converted to positional
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
707 arguments, as follows. First, a list of unfilled slots is created for the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
708 formal parameters. If there are N positional arguments, they are placed in the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
709 first N slots. Next, for each keyword argument, the identifier is used to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
710 determine the corresponding slot (if the identifier is the same as the first
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
711 formal parameter name, the first slot is used, and so on). If the slot is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
712 already filled, a :exc:`TypeError` exception is raised. Otherwise, the value of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
713 the argument is placed in the slot, filling it (even if the expression is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
714 ``None``, it fills the slot). When all arguments have been processed, the slots
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
715 that are still unfilled are filled with the corresponding default value from the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
716 function definition. (Default values are calculated, once, when the function is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
717 defined; thus, a mutable object such as a list or dictionary used as default
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
718 value will be shared by all calls that don't specify an argument value for the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
719 corresponding slot; this should usually be avoided.) If there are any unfilled
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
720 slots for which no default value is specified, a :exc:`TypeError` exception is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
721 raised. Otherwise, the list of filled slots is used as the argument list for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
722 the call.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
723
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: 56818
diff changeset
724 .. impl-detail::
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: 49278
diff changeset
725
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: 56818
diff changeset
726 An implementation may provide built-in functions whose positional parameters
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: 56818
diff changeset
727 do not have names, even if they are 'named' for the purpose of documentation,
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: 56818
diff changeset
728 and which therefore cannot be supplied by keyword. In CPython, this is the
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 73259
diff changeset
729 case for functions implemented in C that use :c:func:`PyArg_ParseTuple` to
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: 56818
diff changeset
730 parse their arguments.
46575
dad88cb6ef1f #2677: add note that not all functions may accept keyword args.
Georg Brandl <georg@python.org>
parents: 46397
diff changeset
731
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
732 If there are more positional arguments than there are formal parameter slots, a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
733 :exc:`TypeError` exception is raised, unless a formal parameter using the syntax
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
734 ``*identifier`` is present; in this case, that formal parameter receives a tuple
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
735 containing the excess positional arguments (or an empty tuple if there were no
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
736 excess positional arguments).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
737
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
738 If any keyword argument does not correspond to a formal parameter name, a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
739 :exc:`TypeError` exception is raised, unless a formal parameter using the syntax
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
740 ``**identifier`` is present; in this case, that formal parameter receives a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
741 dictionary containing the excess keyword arguments (using the keywords as keys
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
742 and the argument values as corresponding values), or a (new) empty dictionary if
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
743 there were no excess keyword arguments.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
744
71549
8328fe952303 Issue #12531: add index entries to documentation of * and ** in function calls
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
745 .. index::
8328fe952303 Issue #12531: add index entries to documentation of * and ** in function calls
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
746 single: *; in function calls
8328fe952303 Issue #12531: add index entries to documentation of * and ** in function calls
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
747
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
748 If the syntax ``*expression`` appears in the function call, ``expression`` must
71549
8328fe952303 Issue #12531: add index entries to documentation of * and ** in function calls
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
749 evaluate to an iterable. Elements from this iterable are treated as if they
8328fe952303 Issue #12531: add index entries to documentation of * and ** in function calls
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
750 were additional positional arguments; if there are positional arguments
71643
952e83a8bc78 #12531: Fix spaces.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71549
diff changeset
751 *x1*, ..., *xN*, and ``expression`` evaluates to a sequence *y1*, ..., *yM*, this
71549
8328fe952303 Issue #12531: add index entries to documentation of * and ** in function calls
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
752 is equivalent to a call with M+N positional arguments *x1*, ..., *xN*, *y1*,
8328fe952303 Issue #12531: add index entries to documentation of * and ** in function calls
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
753 ..., *yM*.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
754
48307
49f52e285a64 allow keyword args to be passed in after *args #3473
Benjamin Peterson <benjamin@python.org>
parents: 48239
diff changeset
755 A consequence of this is that although the ``*expression`` syntax may appear
49f52e285a64 allow keyword args to be passed in after *args #3473
Benjamin Peterson <benjamin@python.org>
parents: 48239
diff changeset
756 *after* some keyword arguments, it is processed *before* the keyword arguments
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
757 (and the ``**expression`` argument, if any -- see below). So::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
758
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
759 >>> def f(a, b):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
760 ... print a, b
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
761 ...
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
762 >>> f(b=1, *(2,))
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
763 2 1
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
764 >>> f(a=1, *(2,))
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
765 Traceback (most recent call last):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
766 File "<stdin>", line 1, in ?
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
767 TypeError: f() got multiple values for keyword argument 'a'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
768 >>> f(1, *(2,))
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
769 1 2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
770
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
771 It is unusual for both keyword arguments and the ``*expression`` syntax to be
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
772 used in the same call, so in practice this confusion does not arise.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
773
71549
8328fe952303 Issue #12531: add index entries to documentation of * and ** in function calls
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
774 .. index::
8328fe952303 Issue #12531: add index entries to documentation of * and ** in function calls
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
775 single: **; in function calls
8328fe952303 Issue #12531: add index entries to documentation of * and ** in function calls
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
776
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
777 If the syntax ``**expression`` appears in the function call, ``expression`` must
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
778 evaluate to a mapping, the contents of which are treated as additional keyword
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
779 arguments. In the case of a keyword appearing in both ``expression`` and as an
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
780 explicit keyword argument, a :exc:`TypeError` exception is raised.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
781
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
782 Formal parameters using the syntax ``*identifier`` or ``**identifier`` cannot be
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
783 used as positional argument slots or as keyword argument names. Formal
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
784 parameters using the syntax ``(sublist)`` cannot be used as keyword argument
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
785 names; the outermost sublist corresponds to a single unnamed argument slot, and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
786 the argument value is assigned to the sublist using the usual tuple assignment
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
787 rules after all other parameter processing is done.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
788
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
789 A call always returns some value, possibly ``None``, unless it raises an
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
790 exception. How this value is computed depends on the type of the callable
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
791 object.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
792
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
793 If it is---
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
794
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
795 a user-defined function:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
796 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
797 pair: function; call
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
798 triple: user-defined; function; call
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
799 object: user-defined function
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
800 object: function
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
801
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
802 The code block for the function is executed, passing it the argument list. The
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
803 first thing the code block will do is bind the formal parameters to the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
804 arguments; this is described in section :ref:`function`. When the code block
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
805 executes a :keyword:`return` statement, this specifies the return value of the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
806 function call.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
807
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
808 a built-in function or method:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
809 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
810 pair: function; call
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
811 pair: built-in function; call
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
812 pair: method; call
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
813 pair: built-in method; call
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
814 object: built-in method
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
815 object: built-in function
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
816 object: method
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
817 object: function
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
818
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
819 The result is up to the interpreter; see :ref:`built-in-funcs` for the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
820 descriptions of built-in functions and methods.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
821
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
822 a class object:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
823 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
824 object: class
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
825 pair: class object; call
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 A new instance of that class is returned.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
828
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
829 a class instance method:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
830 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
831 object: class instance
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
832 object: instance
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
833 pair: class instance; call
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
834
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
835 The corresponding user-defined function is called, with an argument list that is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
836 one longer than the argument list of the call: the instance becomes the first
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
837 argument.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
838
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
839 a class instance:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
840 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
841 pair: instance; call
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
842 single: __call__() (object method)
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 The class must define a :meth:`__call__` method; the effect is then the same as
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
845 if that method was called.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
848 .. _power:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
849
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
850 The power operator
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
851 ==================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
852
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
853 The power operator binds more tightly than unary operators on its left; it binds
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
854 less tightly than unary operators on its right. The syntax is:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
855
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
856 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
857 power: `primary` ["**" `u_expr`]
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 Thus, in an unparenthesized sequence of power and unary operators, the operators
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
860 are evaluated from right to left (this does not constrain the evaluation order
42689
1efe9b10c4a6 Bug #1777160: mention explicitly that e.g. -1**2 is -1.
Georg Brandl <georg@python.org>
parents: 42617
diff changeset
861 for the operands): ``-1**2`` results in ``-1``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
862
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
863 The power operator has the same semantics as the built-in :func:`pow` function,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
864 when called with two arguments: it yields its left argument raised to the power
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
865 of its right argument. The numeric arguments are first converted to a common
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
866 type. The result type is that of the arguments after coercion.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
867
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
868 With mixed operand types, the coercion rules for binary arithmetic operators
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
869 apply. For int and long int operands, the result has the same type as the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
870 operands (after coercion) unless the second argument is negative; in that case,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
871 all arguments are converted to float and a float result is delivered. For
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
872 example, ``10**2`` returns ``100``, but ``10**-2`` returns ``0.01``. (This last
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
873 feature was added in Python 2.2. In Python 2.1 and before, if both arguments
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
874 were of integer types and the second argument was negative, an exception was
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
875 raised).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
876
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
877 Raising ``0.0`` to a negative power results in a :exc:`ZeroDivisionError`.
44488
94eeaeeb3ce9 Continue rolling back pep-3141 changes that changed behavior from 2.5. This
Jeffrey Yasskin <jyasskin@gmail.com>
parents: 44432
diff changeset
878 Raising a negative number to a fractional power results in a :exc:`ValueError`.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
879
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
880
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
881 .. _unary:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
882
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: 50522
diff changeset
883 Unary arithmetic and bitwise operations
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: 50522
diff changeset
884 =======================================
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
885
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
886 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
887 triple: unary; arithmetic; operation
44497
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
888 triple: unary; bitwise; operation
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
889
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: 50522
diff changeset
890 All unary arithmetic and bitwise operations have the same priority:
42603
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 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
893 u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
894
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
895 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
896 single: negation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
897 single: minus
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
898
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
899 The unary ``-`` (minus) operator yields the negation of its numeric argument.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
900
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
901 .. index:: single: plus
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
902
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
903 The unary ``+`` (plus) operator yields its numeric argument unchanged.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
904
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
905 .. index:: single: inversion
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
906
44497
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
907 The unary ``~`` (invert) operator yields the bitwise inversion of its plain or
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
908 long integer argument. The bitwise inversion of ``x`` is defined as
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
909 ``-(x+1)``. It only applies to integral numbers.
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 .. index:: exception: TypeError
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 In all three cases, if the argument does not have the proper type, a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
914 :exc:`TypeError` exception is raised.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
915
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
916
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
917 .. _binary:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
918
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
919 Binary arithmetic operations
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
920 ============================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
921
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
922 .. index:: triple: binary; arithmetic; operation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
923
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
924 The binary arithmetic operations have the conventional priority levels. Note
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
925 that some of these operations also apply to certain non-numeric types. Apart
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
926 from the power operator, there are only two levels, one for multiplicative
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
927 operators and one for additive operators:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
928
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
929 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
930 m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
931 : | `m_expr` "%" `u_expr`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
932 a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
933
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
934 .. index:: single: multiplication
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
935
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
936 The ``*`` (multiplication) operator yields the product of its arguments. The
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
937 arguments must either both be numbers, or one argument must be an integer (plain
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
938 or long) and the other must be a sequence. In the former case, the numbers are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
939 converted to a common type and then multiplied together. In the latter case,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
940 sequence repetition is performed; a negative repetition factor yields an empty
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
941 sequence.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
942
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
943 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
944 exception: ZeroDivisionError
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
945 single: division
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
946
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
947 The ``/`` (division) and ``//`` (floor division) operators yield the quotient of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
948 their arguments. The numeric arguments are first converted to a common type.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
949 Plain or long integer division yields an integer of the same type; the result is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
950 that of mathematical division with the 'floor' function applied to the result.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
951 Division by zero raises the :exc:`ZeroDivisionError` exception.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
952
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
953 .. index:: single: modulo
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
954
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
955 The ``%`` (modulo) operator yields the remainder from the division of the first
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
956 argument by the second. The numeric arguments are first converted to a common
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
957 type. A zero right argument raises the :exc:`ZeroDivisionError` exception. The
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
958 arguments may be floating point numbers, e.g., ``3.14%0.7`` equals ``0.34``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
959 (since ``3.14`` equals ``4*0.7 + 0.34``.) The modulo operator always yields a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
960 result with the same sign as its second operand (or zero); the absolute value of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
961 the result is strictly smaller than the absolute value of the second operand
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
962 [#]_.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
963
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
964 The integer division and modulo operators are connected by the following
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
965 identity: ``x == (x/y)*y + (x%y)``. Integer division and modulo are also
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
966 connected with the built-in function :func:`divmod`: ``divmod(x, y) == (x/y,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
967 x%y)``. These identities don't hold for floating point numbers; there similar
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
968 identities hold approximately where ``x/y`` is replaced by ``floor(x/y)`` or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
969 ``floor(x/y) - 1`` [#]_.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
970
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
971 In addition to performing the modulo operation on numbers, the ``%`` operator is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
972 also overloaded by string and unicode objects to perform string formatting (also
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
973 known as interpolation). The syntax for string formatting is described in the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
974 Python Library Reference, section :ref:`string-formatting`.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
975
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
976 .. deprecated:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
977 The floor division operator, the modulo operator, and the :func:`divmod`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
978 function are no longer defined for complex numbers. Instead, convert to a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
979 floating point number using the :func:`abs` function if appropriate.
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 .. index:: single: addition
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 The ``+`` (addition) operator yields the sum of its arguments. The arguments
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
984 must either both be numbers or both sequences of the same type. In the former
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
985 case, the numbers are converted to a common type and then added together. In
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
986 the latter case, the sequences are concatenated.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
987
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
988 .. index:: single: subtraction
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
989
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
990 The ``-`` (subtraction) operator yields the difference of its arguments. The
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
991 numeric arguments are first converted to a common type.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
992
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 .. _shifting:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
995
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
996 Shifting operations
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
997 ===================
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 .. index:: pair: shifting; operation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1000
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1001 The shifting operations have lower priority than the arithmetic operations:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1002
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1003 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1004 shift_expr: `a_expr` | `shift_expr` ( "<<" | ">>" ) `a_expr`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1005
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1006 These operators accept plain or long integers as arguments. The arguments are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1007 converted to a common type. They shift the first argument to the left or right
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1008 by the number of bits given by the second argument.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1009
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1010 .. index:: exception: ValueError
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1011
46876
f4e61dcdb6f8 #2147: PEP 237 changes to overflow behavior.
Georg Brandl <georg@python.org>
parents: 46575
diff changeset
1012 A right shift by *n* bits is defined as division by ``pow(2, n)``. A left shift
f4e61dcdb6f8 #2147: PEP 237 changes to overflow behavior.
Georg Brandl <georg@python.org>
parents: 46575
diff changeset
1013 by *n* bits is defined as multiplication with ``pow(2, n)``. Negative shift
f4e61dcdb6f8 #2147: PEP 237 changes to overflow behavior.
Georg Brandl <georg@python.org>
parents: 46575
diff changeset
1014 counts raise a :exc:`ValueError` exception.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1015
60419
9c48ab728ce0 Fix syntax.
Georg Brandl <georg@python.org>
parents: 60409
diff changeset
1016 .. note::
9c48ab728ce0 Fix syntax.
Georg Brandl <georg@python.org>
parents: 60409
diff changeset
1017
9c48ab728ce0 Fix syntax.
Georg Brandl <georg@python.org>
parents: 60409
diff changeset
1018 In the current implementation, the right-hand operand is required
60409
5b0f1d5bd55a Issue #8259: Clarify that there's an upper bound on the right-hand operand of a shift operator.
Mark Dickinson <dickinsm@gmail.com>
parents: 60150
diff changeset
1019 to be at most :attr:`sys.maxsize`. If the right-hand operand is larger than
5b0f1d5bd55a Issue #8259: Clarify that there's an upper bound on the right-hand operand of a shift operator.
Mark Dickinson <dickinsm@gmail.com>
parents: 60150
diff changeset
1020 :attr:`sys.maxsize` an :exc:`OverflowError` exception is raised.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1021
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1022 .. _bitwise:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1023
44497
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
1024 Binary bitwise operations
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
1025 =========================
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1026
44497
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
1027 .. index:: triple: binary; bitwise; operation
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1028
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1029 Each of the three bitwise operations has a different priority level:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1030
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1031 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1032 and_expr: `shift_expr` | `and_expr` "&" `shift_expr`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1033 xor_expr: `and_expr` | `xor_expr` "^" `and_expr`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1034 or_expr: `xor_expr` | `or_expr` "|" `xor_expr`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1035
44497
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
1036 .. index:: pair: bitwise; and
42603
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 The ``&`` operator yields the bitwise AND of its arguments, which must be plain
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1039 or long integers. The arguments are converted to a common type.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1040
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1041 .. index::
44497
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
1042 pair: bitwise; xor
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1043 pair: exclusive; or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1044
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1045 The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1046 must be plain or long integers. The arguments are converted to a common type.
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 .. index::
44497
01d5b8e7d121 Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst.
Georg Brandl <georg@python.org>
parents: 44488
diff changeset
1049 pair: bitwise; or
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1050 pair: inclusive; or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1051
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1052 The ``|`` operator yields the bitwise (inclusive) OR of its arguments, which
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1053 must be plain or long integers. The arguments are converted to a common type.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1054
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1055
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1056 .. _comparisons:
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44127
diff changeset
1057 .. _is:
74401
f72b171c5050 Fix label names.
Georg Brandl <georg@python.org>
parents: 74395
diff changeset
1058 .. _is not:
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44127
diff changeset
1059 .. _in:
74401
f72b171c5050 Fix label names.
Georg Brandl <georg@python.org>
parents: 74395
diff changeset
1060 .. _not in:
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1061
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1062 Comparisons
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1063 ===========
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 .. index:: single: comparison
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1066
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1067 .. index:: pair: C; language
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1068
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1069 Unlike C, all comparison operations in Python have the same priority, which is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1070 lower than that of any arithmetic, shifting or bitwise operation. Also unlike
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1071 C, expressions like ``a < b < c`` have the interpretation that is conventional
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1072 in mathematics:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1073
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1074 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1075 comparison: `or_expr` ( `comp_operator` `or_expr` )*
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1076 comp_operator: "<" | ">" | "==" | ">=" | "<=" | "<>" | "!="
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1077 : | "is" ["not"] | ["not"] "in"
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1078
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1079 Comparisons yield boolean values: ``True`` or ``False``.
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 .. index:: pair: chaining; comparisons
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1082
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1083 Comparisons can be chained arbitrarily, e.g., ``x < y <= z`` is equivalent to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1084 ``x < y and y <= z``, except that ``y`` is evaluated only once (but in both
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1085 cases ``z`` is not 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
1086
42690
facdd74a0bdd Bug #1777168: replace operator names "opa"... with "op1"... and mark everything up as literal,
Georg Brandl <georg@python.org>
parents: 42689
diff changeset
1087 Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and *op1*, *op2*, ...,
facdd74a0bdd Bug #1777168: replace operator names "opa"... with "op1"... and mark everything up as literal,
Georg Brandl <georg@python.org>
parents: 42689
diff changeset
1088 *opN* are comparison operators, then ``a op1 b op2 c ... y opN z`` is equivalent
facdd74a0bdd Bug #1777168: replace operator names "opa"... with "op1"... and mark everything up as literal,
Georg Brandl <georg@python.org>
parents: 42689
diff changeset
1089 to ``a op1 b and b op2 c and ... y opN z``, except that each expression is
facdd74a0bdd Bug #1777168: replace operator names "opa"... with "op1"... and mark everything up as literal,
Georg Brandl <georg@python.org>
parents: 42689
diff changeset
1090 evaluated at most once.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1091
42690
facdd74a0bdd Bug #1777168: replace operator names "opa"... with "op1"... and mark everything up as literal,
Georg Brandl <georg@python.org>
parents: 42689
diff changeset
1092 Note that ``a op1 b op2 c`` doesn't imply any kind of comparison between *a* and
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1093 *c*, so that, e.g., ``x < y > z`` is perfectly legal (though perhaps not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1094 pretty).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1095
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1096 The forms ``<>`` and ``!=`` are equivalent; for consistency with C, ``!=`` is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1097 preferred; where ``!=`` is mentioned below ``<>`` is also accepted. The ``<>``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1098 spelling is considered obsolescent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1099
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1100 The operators ``<``, ``>``, ``==``, ``>=``, ``<=``, and ``!=`` compare the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1101 values of two objects. The objects need not have the same type. If both are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1102 numbers, they are converted to a common type. Otherwise, objects of different
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1103 types *always* compare unequal, and are ordered consistently but arbitrarily.
56818
3e15a07a32fa Merged revisions 74209 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53564
diff changeset
1104 You can control comparison behavior of objects of non-built-in types by defining
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1105 a ``__cmp__`` method or rich comparison methods like ``__gt__``, described in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1106 section :ref:`specialnames`.
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 (This unusual definition of comparison was used to simplify the definition of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1109 operations like sorting and the :keyword:`in` and :keyword:`not in` operators.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1110 In the future, the comparison rules for objects of different types are likely to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1111 change.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1112
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1113 Comparison of objects of the same type depends on the type:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1114
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1115 * Numbers are compared arithmetically.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1116
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1117 * Strings are compared lexicographically using the numeric equivalents (the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1118 result of the built-in function :func:`ord`) of their characters. Unicode and
42617
603dc53c4716 Added a note in each regarding the fact that unicode strings that look the same
Mark Summerfield <list@qtrac.plus.com>
parents: 42603
diff changeset
1119 8-bit strings are fully interoperable in this behavior. [#]_
42603
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 * Tuples and lists are compared lexicographically using comparison of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1122 corresponding elements. This means that to compare equal, each element must
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1123 compare 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
1124 length.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1125
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1126 If not equal, the sequences are ordered the same as their first differing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1127 elements. For example, ``cmp([1,2,x], [1,2,y])`` returns the same as
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1128 ``cmp(x,y)``. If the corresponding element does not exist, the shorter sequence
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1129 is ordered first (for example, ``[1,2] < [1,2,3]``).
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 * Mappings (dictionaries) compare equal if and only if their sorted (key, value)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1132 lists compare equal. [#]_ Outcomes other than equality are resolved
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1133 consistently, but are not otherwise defined. [#]_
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1134
56818
3e15a07a32fa Merged revisions 74209 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53564
diff changeset
1135 * Most other objects of built-in types compare unequal unless they are the same
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1136 object; the choice whether one object is considered smaller or larger than
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1137 another one is made arbitrarily but consistently within one execution of a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1138 program.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1139
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: 56818
diff changeset
1140 .. _membership-test-details:
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: 56818
diff changeset
1141
46164
09fa8cb2bfe8 Don't use the confusing term "set membership".
Georg Brandl <georg@python.org>
parents: 45642
diff changeset
1142 The operators :keyword:`in` and :keyword:`not in` test for collection
09fa8cb2bfe8 Don't use the confusing term "set membership".
Georg Brandl <georg@python.org>
parents: 45642
diff changeset
1143 membership. ``x in s`` evaluates to true if *x* is a member of the collection
09fa8cb2bfe8 Don't use the confusing term "set membership".
Georg Brandl <georg@python.org>
parents: 45642
diff changeset
1144 *s*, and false otherwise. ``x not in s`` returns the negation of ``x in s``.
09fa8cb2bfe8 Don't use the confusing term "set membership".
Georg Brandl <georg@python.org>
parents: 45642
diff changeset
1145 The collection membership test has traditionally been bound to sequences; an
09fa8cb2bfe8 Don't use the confusing term "set membership".
Georg Brandl <georg@python.org>
parents: 45642
diff changeset
1146 object is a member of a collection if the collection is a sequence and contains
09fa8cb2bfe8 Don't use the confusing term "set membership".
Georg Brandl <georg@python.org>
parents: 45642
diff changeset
1147 an element equal to that object. However, it make sense for many other object
09fa8cb2bfe8 Don't use the confusing term "set membership".
Georg Brandl <georg@python.org>
parents: 45642
diff changeset
1148 types to support membership tests without being a sequence. In particular,
09fa8cb2bfe8 Don't use the confusing term "set membership".
Georg Brandl <georg@python.org>
parents: 45642
diff changeset
1149 dictionaries (for keys) and sets support membership testing.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1150
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1151 For the list and tuple types, ``x in y`` is true if and only if there exists an
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1152 index *i* such that ``x == y[i]`` is true.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1153
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1154 For the Unicode and string types, ``x in y`` is true if and only if *x* is a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1155 substring of *y*. An equivalent test is ``y.find(x) != -1``. Note, *x* and *y*
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1156 need not be the same type; consequently, ``u'ab' in 'abc'`` will return
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1157 ``True``. Empty strings are always considered to be a substring of any other
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1158 string, so ``"" in "abc"`` will return ``True``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1159
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1160 .. versionchanged:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1161 Previously, *x* was required to be a string of length ``1``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1162
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1163 For user-defined classes which define the :meth:`__contains__` method, ``x in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1164 y`` is true if and only if ``y.__contains__(x)`` is true.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1165
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: 56818
diff changeset
1166 For user-defined classes which do not define :meth:`__contains__` but do define
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: 56818
diff changeset
1167 :meth:`__iter__`, ``x in y`` is true if some value ``z`` with ``x == z`` is
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: 56818
diff changeset
1168 produced while iterating over ``y``. If an exception is raised during 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: 56818
diff changeset
1169 iteration, it is as if :keyword:`in` raised that exception.
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: 56818
diff changeset
1170
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: 56818
diff changeset
1171 Lastly, the old-style iteration protocol is tried: if a class defines
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1172 :meth:`__getitem__`, ``x in y`` is true if and only if there is a non-negative
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1173 integer index *i* such that ``x == y[i]``, and all lower integer indices do not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1174 raise :exc:`IndexError` exception. (If any other exception is raised, it is as
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1175 if :keyword:`in` raised that exception).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1176
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1177 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1178 operator: in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1179 operator: not in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1180 pair: membership; test
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1181 object: sequence
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 The operator :keyword:`not in` is defined to have the inverse true value of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1184 :keyword:`in`.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1185
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1186 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1187 operator: is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1188 operator: is not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1189 pair: identity; test
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1190
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1191 The operators :keyword:`is` and :keyword:`is not` test for object identity: ``x
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1192 is y`` is true if and only if *x* and *y* are the same object. ``x is not y``
47866
a06a0e1132ee #1410739: add a footnote about "is" and "unusual" behavior.
Georg Brandl <georg@python.org>
parents: 47233
diff changeset
1193 yields the inverse truth value. [#]_
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1194
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1195
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1196 .. _booleans:
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44127
diff changeset
1197 .. _and:
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44127
diff changeset
1198 .. _or:
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44127
diff changeset
1199 .. _not:
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1200
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1201 Boolean operations
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1204 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1205 pair: Conditional; expression
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1206 pair: Boolean; operation
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1207
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1208 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1209 or_test: `and_test` | `or_test` "or" `and_test`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1210 and_test: `not_test` | `and_test` "and" `not_test`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1211 not_test: `comparison` | "not" `not_test`
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 In the context of Boolean operations, and also when expressions are used by
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1214 control flow statements, the following values are interpreted as false:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1215 ``False``, ``None``, numeric zero of all types, and empty strings and containers
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1216 (including strings, tuples, lists, dictionaries, sets and frozensets). All
49278
f6df567ccd62 mention how to override boolean evaluation
Benjamin Peterson <benjamin@python.org>
parents: 48307
diff changeset
1217 other values are interpreted as true. (See the :meth:`~object.__nonzero__`
f6df567ccd62 mention how to override boolean evaluation
Benjamin Peterson <benjamin@python.org>
parents: 48307
diff changeset
1218 special method for a way to change this.)
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1219
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1220 .. index:: operator: not
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 The operator :keyword:`not` yields ``True`` if its argument is false, ``False``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1223 otherwise.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1224
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1225 .. index:: operator: and
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 The expression ``x and y`` first evaluates *x*; if *x* is false, its value is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1228 returned; otherwise, *y* is evaluated and the resulting value is returned.
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 .. index:: operator: or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1231
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1232 The expression ``x or y`` first evaluates *x*; if *x* is true, its value is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1233 returned; otherwise, *y* is evaluated and the resulting value is returned.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1234
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1235 (Note that neither :keyword:`and` nor :keyword:`or` restrict the value and type
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1236 they return to ``False`` and ``True``, but rather return the last evaluated
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1237 argument. This is sometimes useful, e.g., if ``s`` is a string that should be
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1238 replaced by a default value if it is empty, the expression ``s or 'foo'`` yields
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1239 the desired value. Because :keyword:`not` has to invent a value anyway, it does
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1240 not bother to return a value of the same type as its argument, so e.g., ``not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1241 'foo'`` yields ``False``, not ``''``.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1242
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1243
59841
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1244 Conditional Expressions
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1245 =======================
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1246
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1247 .. versionadded:: 2.5
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1248
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1249 .. index::
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1250 pair: conditional; expression
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1251 pair: ternary; operator
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1252
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1253 .. productionlist::
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1254 conditional_expression: `or_test` ["if" `or_test` "else" `expression`]
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1255 expression: `conditional_expression` | `lambda_form`
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1256
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1257 Conditional expressions (sometimes called a "ternary operator") have the lowest
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1258 priority of all Python operations.
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1259
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1260 The expression ``x if C else y`` first evaluates the condition, *C* (*not* *x*);
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1261 if *C* is true, *x* is evaluated and its value is returned; otherwise, *y* is
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1262 evaluated and its value is returned.
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1263
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1264 See :pep:`308` for more details about conditional expressions.
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1265
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1266
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1267 .. _lambdas:
53564
dcbc2203bdf3 Merged revisions 71397-71398,71441 via svnmerge from
Georg Brandl <georg@python.org>
parents: 51809
diff changeset
1268 .. _lambda:
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1269
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1270 Lambdas
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1271 =======
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1272
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1273 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1274 pair: lambda; expression
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1275 pair: lambda; form
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1276 pair: anonymous; function
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 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1279 lambda_form: "lambda" [`parameter_list`]: `expression`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1280 old_lambda_form: "lambda" [`parameter_list`]: `old_expression`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1281
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1282 Lambda forms (lambda expressions) have the same syntactic position as
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1283 expressions. They are a shorthand to create anonymous functions; the expression
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1284 ``lambda arguments: expression`` yields a function object. The unnamed object
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1285 behaves like a function object defined with ::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1286
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1287 def name(arguments):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1288 return expression
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1289
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1290 See section :ref:`function` for the syntax of parameter lists. Note that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1291 functions created with lambda forms cannot contain statements.
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 .. _exprlists:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1295
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1296 Expression lists
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1297 ================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1298
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1299 .. index:: pair: expression; list
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 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1302 expression_list: `expression` ( "," `expression` )* [","]
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 .. index:: object: tuple
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1305
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1306 An expression list containing at least one comma yields a tuple. The length of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1307 the tuple is the number of expressions in the list. The expressions are
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1308 evaluated from left to right.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1309
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1310 .. index:: pair: trailing; comma
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1311
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1312 The trailing comma is required only to create a single tuple (a.k.a. a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1313 *singleton*); it is optional in all other cases. A single expression without a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1314 trailing comma doesn't create a tuple, but rather yields the value of that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1315 expression. (To create an empty tuple, use an empty pair of parentheses:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1316 ``()``.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1317
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1318
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1319 .. _evalorder:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1320
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1321 Evaluation order
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1322 ================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1323
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1324 .. index:: pair: evaluation; order
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1325
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1326 Python evaluates expressions from left to right. Notice that while evaluating an
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1327 assignment, the right-hand side is evaluated before the left-hand side.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1328
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1329 In the following lines, expressions will be evaluated in the arithmetic order of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1330 their suffixes::
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 expr1, expr2, expr3, expr4
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1333 (expr1, expr2, expr3, expr4)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1334 {expr1: expr2, expr3: expr4}
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1335 expr1 + expr2 * (expr3 - expr4)
48196
e6fe83c2e262 #3519: callee is an expression too.
Georg Brandl <georg@python.org>
parents: 47866
diff changeset
1336 expr1(expr2, expr3, *expr4, **expr5)
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1337 expr3, expr4 = expr1, expr2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1338
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1339
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1340 .. _operator-summary:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1341
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1342 Summary
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1343 =======
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 .. index:: pair: operator; precedence
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1346
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1347 The following table summarizes the operator precedences in Python, from lowest
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1348 precedence (least binding) to highest precedence (most binding). Operators in
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1349 the same box have the same precedence. Unless the syntax is explicitly given,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1350 operators are binary. Operators in the same box group left to right (except for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1351 comparisons, including tests, which all have the same precedence and chain from
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1352 left to right --- see section :ref:`comparisons` --- and exponentiation, which
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1353 groups from right to left).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1354
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1355 +-----------------------------------------------+-------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1356 | Operator | Description |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1357 +===============================================+=====================================+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1358 | :keyword:`lambda` | Lambda expression |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1359 +-----------------------------------------------+-------------------------------------+
59841
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1360 | :keyword:`if` -- :keyword:`else` | Conditional expression |
d1398ff01a07 Merged revisions 77593,77702-77703,77858,77887,78113-78115,78117,78245,78385-78386,78496,78760,78771-78773,78802 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56824
diff changeset
1361 +-----------------------------------------------+-------------------------------------+
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1362 | :keyword:`or` | Boolean OR |
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 | :keyword:`and` | Boolean AND |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1365 +-----------------------------------------------+-------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1366 | :keyword:`not` *x* | Boolean NOT |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1367 +-----------------------------------------------+-------------------------------------+
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: 50522
diff changeset
1368 | :keyword:`in`, :keyword:`not` :keyword:`in`, | Comparisons, including membership |
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: 50522
diff changeset
1369 | :keyword:`is`, :keyword:`is not`, ``<``, | tests and identity tests, |
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: 50522
diff changeset
1370 | ``<=``, ``>``, ``>=``, ``<>``, ``!=``, ``==`` | |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1371 +-----------------------------------------------+-------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1372 | ``|`` | Bitwise OR |
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 | ``^`` | Bitwise XOR |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1375 +-----------------------------------------------+-------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1376 | ``&`` | Bitwise AND |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1377 +-----------------------------------------------+-------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1378 | ``<<``, ``>>`` | Shifts |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1379 +-----------------------------------------------+-------------------------------------+
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1380 | ``+``, ``-`` | Addition and subtraction |
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1381 +-----------------------------------------------+-------------------------------------+
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: 50522
diff changeset
1382 | ``*``, ``/``, ``//``, ``%`` | Multiplication, division, remainder |
65127
ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents: 60419
diff changeset
1383 | | [#]_ |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1384 +-----------------------------------------------+-------------------------------------+
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: 50522
diff changeset
1385 | ``+x``, ``-x``, ``~x`` | Positive, negative, bitwise NOT |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1386 +-----------------------------------------------+-------------------------------------+
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: 50522
diff changeset
1387 | ``**`` | Exponentiation [#]_ |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1388 +-----------------------------------------------+-------------------------------------+
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: 50522
diff changeset
1389 | ``x[index]``, ``x[index:index]``, | Subscription, slicing, |
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: 50522
diff changeset
1390 | ``x(arguments...)``, ``x.attribute`` | call, attribute reference |
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1391 +-----------------------------------------------+-------------------------------------+
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: 50522
diff changeset
1392 | ``(expressions...)``, | Binding or tuple display, |
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: 50522
diff changeset
1393 | ``[expressions...]``, | list display, |
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: 50522
diff changeset
1394 | ``{key:datum...}``, | dictionary display, |
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: 50522
diff changeset
1395 | ```expressions...``` | string conversion |
42603
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 .. rubric:: Footnotes
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1399
47233
27c0d7351ea8 Mention that the leaking of variables from list comprehensions
Martin v. Löwis <martin@v.loewis.de>
parents: 46876
diff changeset
1400 .. [#] In Python 2.3 and later releases, a list comprehension "leaks" the control
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: 49278
diff changeset
1401 variables of each ``for`` it contains into the containing scope. However, this
76732
8aab13719c02 Use Python 3 instead of 3.0.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 74401
diff changeset
1402 behavior is deprecated, and relying on it will not work in Python 3.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1403
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1404 .. [#] While ``abs(x%y) < abs(y)`` is true mathematically, for floats it may not be
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1405 true numerically due to roundoff. For example, and assuming a platform on which
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1406 a Python float is an IEEE 754 double-precision number, in order that ``-1e-100 %
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1407 1e100`` have the same sign as ``1e100``, the computed result is ``-1e-100 +
68014
d356649504f9 Merged revisions 86881,86887,86913-86915,86933,86943,86960,86964,86974,86980,86996,87008 via svnmerge from
Georg Brandl <georg@python.org>
parents: 65129
diff changeset
1408 1e100``, which is numerically exactly equal to ``1e100``. The function
d356649504f9 Merged revisions 86881,86887,86913-86915,86933,86943,86960,86964,86974,86980,86996,87008 via svnmerge from
Georg Brandl <georg@python.org>
parents: 65129
diff changeset
1409 :func:`math.fmod` returns a result whose sign matches the sign of the
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1410 first argument instead, and so returns ``-1e-100`` in this case. Which approach
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1411 is more appropriate depends on the application.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1412
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1413 .. [#] If x is very close to an exact integer multiple of y, it's possible for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1414 ``floor(x/y)`` to be one larger than ``(x-x%y)/y`` due to rounding. In such
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1415 cases, Python returns the latter result, in order to preserve that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1416 ``divmod(x,y)[0] * y + x % y`` be very close to ``x``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1417
42617
603dc53c4716 Added a note in each regarding the fact that unicode strings that look the same
Mark Summerfield <list@qtrac.plus.com>
parents: 42603
diff changeset
1418 .. [#] While comparisons between unicode strings make sense at the byte
603dc53c4716 Added a note in each regarding the fact that unicode strings that look the same
Mark Summerfield <list@qtrac.plus.com>
parents: 42603
diff changeset
1419 level, they may be counter-intuitive to users. For example, the
43456
c9bf6e70308e Added note in footnote about string comparisons about
Mark Summerfield <list@qtrac.plus.com>
parents: 42690
diff changeset
1420 strings ``u"\u00C7"`` and ``u"\u0043\u0327"`` compare differently,
42617
603dc53c4716 Added a note in each regarding the fact that unicode strings that look the same
Mark Summerfield <list@qtrac.plus.com>
parents: 42603
diff changeset
1421 even though they both represent the same unicode character (LATIN
60191
f0bb10ce05c7 Merged revisions 79582 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 59841
diff changeset
1422 CAPITAL LETTER C WITH CEDILLA). To compare strings in a human
43456
c9bf6e70308e Added note in footnote about string comparisons about
Mark Summerfield <list@qtrac.plus.com>
parents: 42690
diff changeset
1423 recognizable way, compare using :func:`unicodedata.normalize`.
42617
603dc53c4716 Added a note in each regarding the fact that unicode strings that look the same
Mark Summerfield <list@qtrac.plus.com>
parents: 42603
diff changeset
1424
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1425 .. [#] The implementation computes this efficiently, without constructing lists or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1426 sorting.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1427
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1428 .. [#] Earlier versions of Python used lexicographic comparison of the sorted (key,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1429 value) lists, but this was very expensive for the common case of comparing for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1430 equality. An even earlier version of Python compared dictionaries by identity
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1431 only, but this caused surprises because people expected to be able to test a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1432 dictionary for emptiness by comparing it to ``{}``.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1433
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: 49278
diff changeset
1434 .. [#] Due to automatic garbage-collection, free lists, and the dynamic nature of
47866
a06a0e1132ee #1410739: add a footnote about "is" and "unusual" behavior.
Georg Brandl <georg@python.org>
parents: 47233
diff changeset
1435 descriptors, you may notice seemingly unusual behaviour in certain uses of
a06a0e1132ee #1410739: add a footnote about "is" and "unusual" behavior.
Georg Brandl <georg@python.org>
parents: 47233
diff changeset
1436 the :keyword:`is` operator, like those involving comparisons between instance
a06a0e1132ee #1410739: add a footnote about "is" and "unusual" behavior.
Georg Brandl <georg@python.org>
parents: 47233
diff changeset
1437 methods, or constants. Check their documentation for more info.
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: 50522
diff changeset
1438
68014
d356649504f9 Merged revisions 86881,86887,86913-86915,86933,86943,86960,86964,86974,86980,86996,87008 via svnmerge from
Georg Brandl <georg@python.org>
parents: 65129
diff changeset
1439 .. [#] The ``%`` operator is also used for string formatting; the same
d356649504f9 Merged revisions 86881,86887,86913-86915,86933,86943,86960,86964,86974,86980,86996,87008 via svnmerge from
Georg Brandl <georg@python.org>
parents: 65129
diff changeset
1440 precedence applies.
65127
ff734f225b47 Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from
Georg Brandl <georg@python.org>
parents: 60419
diff changeset
1441
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: 50522
diff changeset
1442 .. [#] The power operator ``**`` binds less tightly than an arithmetic or
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: 50522
diff changeset
1443 bitwise unary operator on its right, that is, ``2**-1`` is ``0.5``.