Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | |
| 2 | .. _expressions: |
| 3 | |
| 4 | *********** |
| 5 | Expressions |
| 6 | *********** |
| 7 | |
Georg Brandl | 4b49131 | 2007-08-31 09:22:56 +0000 | [diff] [blame] | 8 | .. index:: expression, BNF |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 9 | |
| 10 | This chapter explains the meaning of the elements of expressions in Python. |
| 11 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 12 | **Syntax Notes:** In this and the following chapters, extended BNF notation will |
| 13 | be used to describe syntax, not lexical analysis. When (one alternative of) a |
| 14 | syntax rule has the form |
| 15 | |
| 16 | .. productionlist:: * |
| 17 | name: `othername` |
| 18 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 19 | and no semantics are given, the semantics of this form of ``name`` are the same |
| 20 | as for ``othername``. |
| 21 | |
| 22 | |
| 23 | .. _conversions: |
| 24 | |
| 25 | Arithmetic conversions |
| 26 | ====================== |
| 27 | |
| 28 | .. index:: pair: arithmetic; conversion |
| 29 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | When a description of an arithmetic operator below uses the phrase "the numeric |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 31 | arguments are converted to a common type," this means that the operator |
| 32 | implementation for built-in types works that way: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 33 | |
| 34 | * If either argument is a complex number, the other is converted to complex; |
| 35 | |
| 36 | * otherwise, if either argument is a floating point number, the other is |
| 37 | converted to floating point; |
| 38 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 39 | * otherwise, both must be integers and no conversion is necessary. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 40 | |
| 41 | Some additional rules apply for certain operators (e.g., a string left argument |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 42 | to the '%' operator). Extensions must define their own conversion behavior. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | |
| 44 | |
| 45 | .. _atoms: |
| 46 | |
| 47 | Atoms |
| 48 | ===== |
| 49 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 50 | .. index:: atom |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 51 | |
| 52 | Atoms are the most basic elements of expressions. The simplest atoms are |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 53 | identifiers or literals. Forms enclosed in parentheses, brackets or braces are |
| 54 | also categorized syntactically as atoms. The syntax for atoms is: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 55 | |
| 56 | .. productionlist:: |
| 57 | atom: `identifier` | `literal` | `enclosure` |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 58 | enclosure: `parenth_form` | `list_display` | `dict_display` | `set_display` |
| 59 | : | `generator_expression` | `yield_atom` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
| 61 | |
| 62 | .. _atom-identifiers: |
| 63 | |
| 64 | Identifiers (Names) |
| 65 | ------------------- |
| 66 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 67 | .. index:: name, identifier |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 68 | |
| 69 | An identifier occurring as an atom is a name. See section :ref:`identifiers` |
| 70 | for lexical definition and section :ref:`naming` for documentation of naming and |
| 71 | binding. |
| 72 | |
| 73 | .. index:: exception: NameError |
| 74 | |
| 75 | When the name is bound to an object, evaluation of the atom yields that object. |
| 76 | When a name is not bound, an attempt to evaluate it raises a :exc:`NameError` |
| 77 | exception. |
| 78 | |
| 79 | .. index:: |
| 80 | pair: name; mangling |
| 81 | pair: private; names |
| 82 | |
| 83 | **Private name mangling:** When an identifier that textually occurs in a class |
| 84 | definition begins with two or more underscore characters and does not end in two |
| 85 | or more underscores, it is considered a :dfn:`private name` of that class. |
| 86 | Private names are transformed to a longer form before code is generated for |
| 87 | them. The transformation inserts the class name in front of the name, with |
| 88 | leading underscores removed, and a single underscore inserted in front of the |
| 89 | class name. For example, the identifier ``__spam`` occurring in a class named |
| 90 | ``Ham`` will be transformed to ``_Ham__spam``. This transformation is |
| 91 | independent of the syntactical context in which the identifier is used. If the |
| 92 | transformed name is extremely long (longer than 255 characters), implementation |
| 93 | defined truncation may happen. If the class name consists only of underscores, |
| 94 | no transformation is done. |
| 95 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 96 | |
| 97 | .. _atom-literals: |
| 98 | |
| 99 | Literals |
| 100 | -------- |
| 101 | |
| 102 | .. index:: single: literal |
| 103 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 104 | Python supports string and bytes literals and various numeric literals: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | |
| 106 | .. productionlist:: |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 107 | literal: `stringliteral` | `bytesliteral` |
| 108 | : | `integer` | `floatnumber` | `imagnumber` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 109 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 110 | Evaluation of a literal yields an object of the given type (string, bytes, |
| 111 | integer, floating point number, complex number) with the given value. The value |
| 112 | may be approximated in the case of floating point and imaginary (complex) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 113 | literals. See section :ref:`literals` for details. |
| 114 | |
| 115 | .. index:: |
| 116 | triple: immutable; data; type |
| 117 | pair: immutable; object |
| 118 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 119 | With the exception of bytes literals, these all correspond to immutable data |
| 120 | types, and hence the object's identity is less important than its value. |
| 121 | Multiple evaluations of literals with the same value (either the same occurrence |
| 122 | in the program text or a different occurrence) may obtain the same object or a |
| 123 | different object with the same value. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 124 | |
| 125 | |
| 126 | .. _parenthesized: |
| 127 | |
| 128 | Parenthesized forms |
| 129 | ------------------- |
| 130 | |
| 131 | .. index:: single: parenthesized form |
| 132 | |
| 133 | A parenthesized form is an optional expression list enclosed in parentheses: |
| 134 | |
| 135 | .. productionlist:: |
| 136 | parenth_form: "(" [`expression_list`] ")" |
| 137 | |
| 138 | A parenthesized expression list yields whatever that expression list yields: if |
| 139 | the list contains at least one comma, it yields a tuple; otherwise, it yields |
| 140 | the single expression that makes up the expression list. |
| 141 | |
| 142 | .. index:: pair: empty; tuple |
| 143 | |
| 144 | An empty pair of parentheses yields an empty tuple object. Since tuples are |
| 145 | immutable, the rules for literals apply (i.e., two occurrences of the empty |
| 146 | tuple may or may not yield the same object). |
| 147 | |
| 148 | .. index:: |
| 149 | single: comma |
| 150 | pair: tuple; display |
| 151 | |
| 152 | Note that tuples are not formed by the parentheses, but rather by use of the |
| 153 | comma operator. The exception is the empty tuple, for which parentheses *are* |
| 154 | required --- allowing unparenthesized "nothing" in expressions would cause |
| 155 | ambiguities and allow common typos to pass uncaught. |
| 156 | |
| 157 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 158 | .. _comprehensions: |
| 159 | |
| 160 | Displays for lists, sets and dictionaries |
| 161 | ----------------------------------------- |
| 162 | |
| 163 | For constructing a list, a set or a dictionary Python provides special syntax |
| 164 | called "displays", each of them in two flavors: |
| 165 | |
| 166 | * either the container contents are listed explicitly, or |
| 167 | |
| 168 | * they are computed via a set of looping and filtering instructions, called a |
| 169 | :dfn:`comprehension`. |
| 170 | |
| 171 | Common syntax elements for comprehensions are: |
| 172 | |
| 173 | .. productionlist:: |
| 174 | comprehension: `expression` `comp_for` |
| 175 | comp_for: "for" `target_list` "in" `or_test` [`comp_iter`] |
| 176 | comp_iter: `comp_for` | `comp_if` |
| 177 | comp_if: "if" `expression_nocond` [`comp_iter`] |
| 178 | |
| 179 | The comprehension consists of a single expression followed by at least one |
| 180 | :keyword:`for` clause and zero or more :keyword:`for` or :keyword:`if` clauses. |
| 181 | In this case, the elements of the new container are those that would be produced |
| 182 | by considering each of the :keyword:`for` or :keyword:`if` clauses a block, |
| 183 | nesting from left to right, and evaluating the expression to produce an element |
| 184 | each time the innermost block is reached. |
| 185 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 186 | Note that the comprehension is executed in a separate scope, so names assigned |
| 187 | to in the target list don't "leak" in the enclosing scope. |
| 188 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 189 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 190 | .. _lists: |
| 191 | |
| 192 | List displays |
| 193 | ------------- |
| 194 | |
| 195 | .. index:: |
| 196 | pair: list; display |
| 197 | pair: list; comprehensions |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 198 | pair: empty; list |
| 199 | object: list |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 200 | |
| 201 | A list display is a possibly empty series of expressions enclosed in square |
| 202 | brackets: |
| 203 | |
| 204 | .. productionlist:: |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 205 | list_display: "[" [`expression_list` | `comprehension`] "]" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 206 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 207 | A list display yields a new list object, the contents being specified by either |
| 208 | a list of expressions or a comprehension. When a comma-separated list of |
| 209 | expressions is supplied, its elements are evaluated from left to right and |
| 210 | placed into the list object in that order. When a comprehension is supplied, |
| 211 | the list is constructed from the elements resulting from the comprehension. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 212 | |
| 213 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 214 | .. _set: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 215 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 216 | Set displays |
| 217 | ------------ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 218 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 219 | .. index:: pair: set; display |
| 220 | object: set |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 221 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 222 | A set display is denoted by curly braces and distinguishable from dictionary |
| 223 | displays by the lack of colons separating keys and values: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 224 | |
| 225 | .. productionlist:: |
Georg Brandl | 528cdb1 | 2008-09-21 07:09:51 +0000 | [diff] [blame] | 226 | set_display: "{" (`expression_list` | `comprehension`) "}" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 227 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 228 | A set display yields a new mutable set object, the contents being specified by |
| 229 | either a sequence of expressions or a comprehension. When a comma-separated |
| 230 | list of expressions is supplied, its elements are evaluated from left to right |
| 231 | and added to the set object. When a comprehension is supplied, the set is |
| 232 | constructed from the elements resulting from the comprehension. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 233 | |
Georg Brandl | 528cdb1 | 2008-09-21 07:09:51 +0000 | [diff] [blame] | 234 | An empty set cannot be constructed with ``{}``; this literal constructs an empty |
| 235 | dictionary. |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 236 | |
| 237 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 238 | .. _dict: |
| 239 | |
| 240 | Dictionary displays |
| 241 | ------------------- |
| 242 | |
| 243 | .. index:: pair: dictionary; display |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 244 | key, datum, key/datum pair |
| 245 | object: dictionary |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 246 | |
| 247 | A dictionary display is a possibly empty series of key/datum pairs enclosed in |
| 248 | curly braces: |
| 249 | |
| 250 | .. productionlist:: |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 251 | dict_display: "{" [`key_datum_list` | `dict_comprehension`] "}" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 252 | key_datum_list: `key_datum` ("," `key_datum`)* [","] |
| 253 | key_datum: `expression` ":" `expression` |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 254 | dict_comprehension: `expression` ":" `expression` `comp_for` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 255 | |
| 256 | A dictionary display yields a new dictionary object. |
| 257 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 258 | If a comma-separated sequence of key/datum pairs is given, they are evaluated |
| 259 | from left to right to define the entries of the dictionary: each key object is |
| 260 | used as a key into the dictionary to store the corresponding datum. This means |
| 261 | that you can specify the same key multiple times in the key/datum list, and the |
| 262 | final dictionary's value for that key will be the last one given. |
| 263 | |
| 264 | A dict comprehension, in contrast to list and set comprehensions, needs two |
| 265 | expressions separated with a colon followed by the usual "for" and "if" clauses. |
| 266 | When the comprehension is run, the resulting key and value elements are inserted |
| 267 | in the new dictionary in the order they are produced. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 268 | |
| 269 | .. index:: pair: immutable; object |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 270 | hashable |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 271 | |
| 272 | Restrictions on the types of the key values are listed earlier in section |
Guido van Rossum | 2cc30da | 2007-11-02 23:46:40 +0000 | [diff] [blame] | 273 | :ref:`types`. (To summarize, the key type should be :term:`hashable`, which excludes |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 274 | all mutable objects.) Clashes between duplicate keys are not detected; the last |
| 275 | datum (textually rightmost in the display) stored for a given key value |
| 276 | prevails. |
| 277 | |
| 278 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 279 | .. _genexpr: |
| 280 | |
| 281 | Generator expressions |
| 282 | --------------------- |
| 283 | |
| 284 | .. index:: pair: generator; expression |
| 285 | object: generator |
| 286 | |
| 287 | A generator expression is a compact generator notation in parentheses: |
| 288 | |
| 289 | .. productionlist:: |
| 290 | generator_expression: "(" `expression` `comp_for` ")" |
| 291 | |
| 292 | A generator expression yields a new generator object. Its syntax is the same as |
| 293 | for comprehensions, except that it is enclosed in parentheses instead of |
| 294 | brackets or curly braces. |
| 295 | |
| 296 | Variables used in the generator expression are evaluated lazily when the |
| 297 | :meth:`__next__` method is called for generator object (in the same fashion as |
| 298 | normal generators). However, the leftmost :keyword:`for` clause is immediately |
| 299 | evaluated, so that an error produced by it can be seen before any other possible |
| 300 | error in the code that handles the generator expression. Subsequent |
| 301 | :keyword:`for` clauses cannot be evaluated immediately since they may depend on |
| 302 | the previous :keyword:`for` loop. For example: ``(x*y for x in range(10) for y |
| 303 | in bar(x))``. |
| 304 | |
| 305 | The parentheses can be omitted on calls with only one argument. See section |
| 306 | :ref:`calls` for the detail. |
| 307 | |
| 308 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 309 | .. _yieldexpr: |
| 310 | |
| 311 | Yield expressions |
| 312 | ----------------- |
| 313 | |
| 314 | .. index:: |
| 315 | keyword: yield |
| 316 | pair: yield; expression |
| 317 | pair: generator; function |
| 318 | |
| 319 | .. productionlist:: |
| 320 | yield_atom: "(" `yield_expression` ")" |
| 321 | yield_expression: "yield" [`expression_list`] |
| 322 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 323 | The :keyword:`yield` expression is only used when defining a generator function, |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 324 | and can only be used in the body of a function definition. Using a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 325 | :keyword:`yield` expression in a function definition is sufficient to cause that |
| 326 | definition to create a generator function instead of a normal function. |
| 327 | |
| 328 | When a generator function is called, it returns an iterator known as a |
| 329 | generator. That generator then controls the execution of a generator function. |
| 330 | The execution starts when one of the generator's methods is called. At that |
| 331 | time, the execution proceeds to the first :keyword:`yield` expression, where it |
| 332 | is suspended again, returning the value of :token:`expression_list` to |
| 333 | generator's caller. By suspended we mean that all local state is retained, |
| 334 | including the current bindings of local variables, the instruction pointer, and |
| 335 | the internal evaluation stack. When the execution is resumed by calling one of |
| 336 | the generator's methods, the function can proceed exactly as if the |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 337 | :keyword:`yield` expression was just another external call. The value of the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 338 | :keyword:`yield` expression after resuming depends on the method which resumed |
| 339 | the execution. |
| 340 | |
| 341 | .. index:: single: coroutine |
| 342 | |
| 343 | All of this makes generator functions quite similar to coroutines; they yield |
| 344 | multiple times, they have more than one entry point and their execution can be |
| 345 | suspended. The only difference is that a generator function cannot control |
| 346 | where should the execution continue after it yields; the control is always |
| 347 | transfered to the generator's caller. |
| 348 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 349 | The :keyword:`yield` statement is allowed in the :keyword:`try` clause of a |
| 350 | :keyword:`try` ... :keyword:`finally` construct. If the generator is not |
| 351 | resumed before it is finalized (by reaching a zero reference count or by being |
| 352 | garbage collected), the generator-iterator's :meth:`close` method will be |
| 353 | called, allowing any pending :keyword:`finally` clauses to execute. |
| 354 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 355 | .. index:: object: generator |
| 356 | |
| 357 | The following generator's methods can be used to control the execution of a |
| 358 | generator function: |
| 359 | |
| 360 | .. index:: exception: StopIteration |
| 361 | |
| 362 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 363 | .. method:: generator.__next__() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 364 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 365 | Starts the execution of a generator function or resumes it at the last |
| 366 | executed :keyword:`yield` expression. When a generator function is resumed |
Benjamin Peterson | e7c78b2 | 2008-07-03 20:28:26 +0000 | [diff] [blame] | 367 | with a :meth:`__next__` method, the current :keyword:`yield` expression |
| 368 | always evaluates to :const:`None`. The execution then continues to the next |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 369 | :keyword:`yield` expression, where the generator is suspended again, and the |
| 370 | value of the :token:`expression_list` is returned to :meth:`next`'s caller. |
| 371 | If the generator exits without yielding another value, a :exc:`StopIteration` |
| 372 | exception is raised. |
| 373 | |
| 374 | This method is normally called implicitly, e.g. by a :keyword:`for` loop, or |
| 375 | by the built-in :func:`next` function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 376 | |
| 377 | |
| 378 | .. method:: generator.send(value) |
| 379 | |
| 380 | Resumes the execution and "sends" a value into the generator function. The |
| 381 | ``value`` argument becomes the result of the current :keyword:`yield` |
| 382 | expression. The :meth:`send` method returns the next value yielded by the |
| 383 | generator, or raises :exc:`StopIteration` if the generator exits without |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 384 | yielding another value. When :meth:`send` is called to start the generator, |
| 385 | it must be called with :const:`None` as the argument, because there is no |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 386 | :keyword:`yield` expression that could receive the value. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 387 | |
| 388 | |
| 389 | .. method:: generator.throw(type[, value[, traceback]]) |
| 390 | |
| 391 | Raises an exception of type ``type`` at the point where generator was paused, |
| 392 | and returns the next value yielded by the generator function. If the generator |
| 393 | exits without yielding another value, a :exc:`StopIteration` exception is |
| 394 | raised. If the generator function does not catch the passed-in exception, or |
| 395 | raises a different exception, then that exception propagates to the caller. |
| 396 | |
| 397 | .. index:: exception: GeneratorExit |
| 398 | |
| 399 | |
| 400 | .. method:: generator.close() |
| 401 | |
| 402 | Raises a :exc:`GeneratorExit` at the point where the generator function was |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 403 | paused. If the generator function then raises :exc:`StopIteration` (by |
| 404 | exiting normally, or due to already being closed) or :exc:`GeneratorExit` (by |
| 405 | not catching the exception), close returns to its caller. If the generator |
| 406 | yields a value, a :exc:`RuntimeError` is raised. If the generator raises any |
| 407 | other exception, it is propagated to the caller. :meth:`close` does nothing |
| 408 | if the generator has already exited due to an exception or normal exit. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 409 | |
| 410 | Here is a simple example that demonstrates the behavior of generators and |
| 411 | generator functions:: |
| 412 | |
| 413 | >>> def echo(value=None): |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 414 | ... print("Execution starts when 'next()' is called for the first time.") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 415 | ... try: |
| 416 | ... while True: |
| 417 | ... try: |
| 418 | ... value = (yield value) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 419 | ... except Exception, e: |
| 420 | ... value = e |
| 421 | ... finally: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 422 | ... print("Don't forget to clean up when 'close()' is called.") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 423 | ... |
| 424 | >>> generator = echo(1) |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 425 | >>> print(next(generator)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 426 | Execution starts when 'next()' is called for the first time. |
| 427 | 1 |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 428 | >>> print(next(generator)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 429 | None |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 430 | >>> print(generator.send(2)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 431 | 2 |
| 432 | >>> generator.throw(TypeError, "spam") |
| 433 | TypeError('spam',) |
| 434 | >>> generator.close() |
| 435 | Don't forget to clean up when 'close()' is called. |
| 436 | |
| 437 | |
| 438 | .. seealso:: |
| 439 | |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 440 | :pep:`0255` - Simple Generators |
| 441 | The proposal for adding generators and the :keyword:`yield` statement to Python. |
| 442 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 443 | :pep:`0342` - Coroutines via Enhanced Generators |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 444 | The proposal to enhance the API and syntax of generators, making them |
| 445 | usable as simple coroutines. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 446 | |
| 447 | |
| 448 | .. _primaries: |
| 449 | |
| 450 | Primaries |
| 451 | ========= |
| 452 | |
| 453 | .. index:: single: primary |
| 454 | |
| 455 | Primaries represent the most tightly bound operations of the language. Their |
| 456 | syntax is: |
| 457 | |
| 458 | .. productionlist:: |
| 459 | primary: `atom` | `attributeref` | `subscription` | `slicing` | `call` |
| 460 | |
| 461 | |
| 462 | .. _attribute-references: |
| 463 | |
| 464 | Attribute references |
| 465 | -------------------- |
| 466 | |
| 467 | .. index:: pair: attribute; reference |
| 468 | |
| 469 | An attribute reference is a primary followed by a period and a name: |
| 470 | |
| 471 | .. productionlist:: |
| 472 | attributeref: `primary` "." `identifier` |
| 473 | |
| 474 | .. index:: |
| 475 | exception: AttributeError |
| 476 | object: module |
| 477 | object: list |
| 478 | |
| 479 | The primary must evaluate to an object of a type that supports attribute |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 480 | references, which most objects do. This object is then asked to produce the |
| 481 | attribute whose name is the identifier (which can be customized by overriding |
| 482 | the :meth:`__getattr__` method). If this attribute is not available, the |
| 483 | exception :exc:`AttributeError` is raised. Otherwise, the type and value of the |
| 484 | object produced is determined by the object. Multiple evaluations of the same |
| 485 | attribute reference may yield different objects. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 486 | |
| 487 | |
| 488 | .. _subscriptions: |
| 489 | |
| 490 | Subscriptions |
| 491 | ------------- |
| 492 | |
| 493 | .. index:: single: subscription |
| 494 | |
| 495 | .. index:: |
| 496 | object: sequence |
| 497 | object: mapping |
| 498 | object: string |
| 499 | object: tuple |
| 500 | object: list |
| 501 | object: dictionary |
| 502 | pair: sequence; item |
| 503 | |
| 504 | A subscription selects an item of a sequence (string, tuple or list) or mapping |
| 505 | (dictionary) object: |
| 506 | |
| 507 | .. productionlist:: |
| 508 | subscription: `primary` "[" `expression_list` "]" |
| 509 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 510 | The primary must evaluate to an object that supports subscription, e.g. a list |
| 511 | or dictionary. User-defined objects can support subscription by defining a |
| 512 | :meth:`__getitem__` method. |
| 513 | |
| 514 | For built-in objects, there are two types of objects that support subscription: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 515 | |
| 516 | If the primary is a mapping, the expression list must evaluate to an object |
| 517 | whose value is one of the keys of the mapping, and the subscription selects the |
| 518 | value in the mapping that corresponds to that key. (The expression list is a |
| 519 | tuple except if it has exactly one item.) |
| 520 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 521 | If the primary is a sequence, the expression (list) must evaluate to an integer. |
| 522 | If this value is negative, the length of the sequence is added to it (so that, |
| 523 | e.g., ``x[-1]`` selects the last item of ``x``.) The resulting value must be a |
| 524 | nonnegative integer less than the number of items in the sequence, and the |
| 525 | subscription selects the item whose index is that value (counting from zero). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 526 | |
| 527 | .. index:: |
| 528 | single: character |
| 529 | pair: string; item |
| 530 | |
| 531 | A string's items are characters. A character is not a separate data type but a |
| 532 | string of exactly one character. |
| 533 | |
| 534 | |
| 535 | .. _slicings: |
| 536 | |
| 537 | Slicings |
| 538 | -------- |
| 539 | |
| 540 | .. index:: |
| 541 | single: slicing |
| 542 | single: slice |
| 543 | |
| 544 | .. index:: |
| 545 | object: sequence |
| 546 | object: string |
| 547 | object: tuple |
| 548 | object: list |
| 549 | |
| 550 | A slicing selects a range of items in a sequence object (e.g., a string, tuple |
| 551 | or list). Slicings may be used as expressions or as targets in assignment or |
| 552 | :keyword:`del` statements. The syntax for a slicing: |
| 553 | |
| 554 | .. productionlist:: |
Thomas Wouters | 53de190 | 2007-09-04 09:03:59 +0000 | [diff] [blame] | 555 | slicing: `primary` "[" `slice_list` "]" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 556 | slice_list: `slice_item` ("," `slice_item`)* [","] |
Georg Brandl | cb8ecb1 | 2007-09-04 06:35:14 +0000 | [diff] [blame] | 557 | slice_item: `expression` | `proper_slice` |
Thomas Wouters | 53de190 | 2007-09-04 09:03:59 +0000 | [diff] [blame] | 558 | proper_slice: [`lower_bound`] ":" [`upper_bound`] [ ":" [`stride`] ] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 559 | lower_bound: `expression` |
| 560 | upper_bound: `expression` |
| 561 | stride: `expression` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 562 | |
| 563 | There is ambiguity in the formal syntax here: anything that looks like an |
| 564 | expression list also looks like a slice list, so any subscription can be |
| 565 | interpreted as a slicing. Rather than further complicating the syntax, this is |
| 566 | disambiguated by defining that in this case the interpretation as a subscription |
| 567 | takes priority over the interpretation as a slicing (this is the case if the |
Thomas Wouters | 53de190 | 2007-09-04 09:03:59 +0000 | [diff] [blame] | 568 | slice list contains no proper slice). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 569 | |
| 570 | .. index:: |
| 571 | single: start (slice object attribute) |
| 572 | single: stop (slice object attribute) |
| 573 | single: step (slice object attribute) |
| 574 | |
Thomas Wouters | 53de190 | 2007-09-04 09:03:59 +0000 | [diff] [blame] | 575 | The semantics for a slicing are as follows. The primary must evaluate to a |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 576 | mapping object, and it is indexed (using the same :meth:`__getitem__` method as |
| 577 | normal subscription) with a key that is constructed from the slice list, as |
| 578 | follows. If the slice list contains at least one comma, the key is a tuple |
| 579 | containing the conversion of the slice items; otherwise, the conversion of the |
| 580 | lone slice item is the key. The conversion of a slice item that is an |
| 581 | expression is that expression. The conversion of a proper slice is a slice |
| 582 | object (see section :ref:`types`) whose :attr:`start`, :attr:`stop` and |
| 583 | :attr:`step` attributes are the values of the expressions given as lower bound, |
| 584 | upper bound and stride, respectively, substituting ``None`` for missing |
| 585 | expressions. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 586 | |
| 587 | |
| 588 | .. _calls: |
| 589 | |
| 590 | Calls |
| 591 | ----- |
| 592 | |
| 593 | .. index:: single: call |
| 594 | |
| 595 | .. index:: object: callable |
| 596 | |
| 597 | A call calls a callable object (e.g., a function) with a possibly empty series |
| 598 | of arguments: |
| 599 | |
| 600 | .. productionlist:: |
| 601 | call: `primary` "(" [`argument_list` [","] |
| 602 | : | `expression` `genexpr_for`] ")" |
| 603 | argument_list: `positional_arguments` ["," `keyword_arguments`] |
Benjamin Peterson | 2d735bc | 2008-08-19 20:57:10 +0000 | [diff] [blame] | 604 | : ["," "*" `expression`] ["," `keyword_arguments`] |
| 605 | : ["," "**" `expression`] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 606 | : | `keyword_arguments` ["," "*" `expression`] |
Benjamin Peterson | 2d735bc | 2008-08-19 20:57:10 +0000 | [diff] [blame] | 607 | : ["," `keyword_arguments`] ["," "**" `expression`] |
| 608 | : | "*" `expression` ["," `keyword_arguments`] ["," "**" `expression`] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 609 | : | "**" `expression` |
| 610 | positional_arguments: `expression` ("," `expression`)* |
| 611 | keyword_arguments: `keyword_item` ("," `keyword_item`)* |
| 612 | keyword_item: `identifier` "=" `expression` |
| 613 | |
| 614 | A trailing comma may be present after the positional and keyword arguments but |
| 615 | does not affect the semantics. |
| 616 | |
| 617 | The primary must evaluate to a callable object (user-defined functions, built-in |
| 618 | functions, methods of built-in objects, class objects, methods of class |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 619 | instances, and all objects having a :meth:`__call__` method are callable). All |
| 620 | argument expressions are evaluated before the call is attempted. Please refer |
| 621 | to section :ref:`function` for the syntax of formal parameter lists. |
| 622 | |
| 623 | .. XXX update with kwonly args PEP |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 624 | |
| 625 | If keyword arguments are present, they are first converted to positional |
| 626 | arguments, as follows. First, a list of unfilled slots is created for the |
| 627 | formal parameters. If there are N positional arguments, they are placed in the |
| 628 | first N slots. Next, for each keyword argument, the identifier is used to |
| 629 | determine the corresponding slot (if the identifier is the same as the first |
| 630 | formal parameter name, the first slot is used, and so on). If the slot is |
| 631 | already filled, a :exc:`TypeError` exception is raised. Otherwise, the value of |
| 632 | the argument is placed in the slot, filling it (even if the expression is |
| 633 | ``None``, it fills the slot). When all arguments have been processed, the slots |
| 634 | that are still unfilled are filled with the corresponding default value from the |
| 635 | function definition. (Default values are calculated, once, when the function is |
| 636 | defined; thus, a mutable object such as a list or dictionary used as default |
| 637 | value will be shared by all calls that don't specify an argument value for the |
| 638 | corresponding slot; this should usually be avoided.) If there are any unfilled |
| 639 | slots for which no default value is specified, a :exc:`TypeError` exception is |
| 640 | raised. Otherwise, the list of filled slots is used as the argument list for |
| 641 | the call. |
| 642 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 643 | .. note:: |
| 644 | |
| 645 | An implementation may provide builtin functions whose positional parameters do |
| 646 | not have names, even if they are 'named' for the purpose of documentation, and |
| 647 | which therefore cannot be supplied by keyword. In CPython, this is the case for |
| 648 | functions implemented in C that use :cfunc:`PyArg_ParseTuple` to parse their |
| 649 | arguments. |
| 650 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 651 | If there are more positional arguments than there are formal parameter slots, a |
| 652 | :exc:`TypeError` exception is raised, unless a formal parameter using the syntax |
| 653 | ``*identifier`` is present; in this case, that formal parameter receives a tuple |
| 654 | containing the excess positional arguments (or an empty tuple if there were no |
| 655 | excess positional arguments). |
| 656 | |
| 657 | If any keyword argument does not correspond to a formal parameter name, a |
| 658 | :exc:`TypeError` exception is raised, unless a formal parameter using the syntax |
| 659 | ``**identifier`` is present; in this case, that formal parameter receives a |
| 660 | dictionary containing the excess keyword arguments (using the keywords as keys |
| 661 | and the argument values as corresponding values), or a (new) empty dictionary if |
| 662 | there were no excess keyword arguments. |
| 663 | |
| 664 | If the syntax ``*expression`` appears in the function call, ``expression`` must |
| 665 | evaluate to a sequence. Elements from this sequence are treated as if they were |
Benjamin Peterson | 2d735bc | 2008-08-19 20:57:10 +0000 | [diff] [blame] | 666 | additional positional arguments; if there are positional arguments *x1*,..., |
| 667 | *xN*, and ``expression`` evaluates to a sequence *y1*, ..., *yM*, this is |
| 668 | equivalent to a call with M+N positional arguments *x1*, ..., *xN*, *y1*, ..., |
| 669 | *yM*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 670 | |
Benjamin Peterson | 2d735bc | 2008-08-19 20:57:10 +0000 | [diff] [blame] | 671 | A consequence of this is that although the ``*expression`` syntax may appear |
| 672 | *after* some keyword arguments, it is processed *before* the keyword arguments |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 673 | (and the ``**expression`` argument, if any -- see below). So:: |
| 674 | |
| 675 | >>> def f(a, b): |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 676 | ... print(a, b) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 677 | ... |
| 678 | >>> f(b=1, *(2,)) |
| 679 | 2 1 |
| 680 | >>> f(a=1, *(2,)) |
| 681 | Traceback (most recent call last): |
| 682 | File "<stdin>", line 1, in ? |
| 683 | TypeError: f() got multiple values for keyword argument 'a' |
| 684 | >>> f(1, *(2,)) |
| 685 | 1 2 |
| 686 | |
| 687 | It is unusual for both keyword arguments and the ``*expression`` syntax to be |
| 688 | used in the same call, so in practice this confusion does not arise. |
| 689 | |
| 690 | If the syntax ``**expression`` appears in the function call, ``expression`` must |
| 691 | evaluate to a mapping, the contents of which are treated as additional keyword |
| 692 | arguments. In the case of a keyword appearing in both ``expression`` and as an |
| 693 | explicit keyword argument, a :exc:`TypeError` exception is raised. |
| 694 | |
| 695 | Formal parameters using the syntax ``*identifier`` or ``**identifier`` cannot be |
| 696 | used as positional argument slots or as keyword argument names. |
| 697 | |
| 698 | A call always returns some value, possibly ``None``, unless it raises an |
| 699 | exception. How this value is computed depends on the type of the callable |
| 700 | object. |
| 701 | |
| 702 | If it is--- |
| 703 | |
| 704 | a user-defined function: |
| 705 | .. index:: |
| 706 | pair: function; call |
| 707 | triple: user-defined; function; call |
| 708 | object: user-defined function |
| 709 | object: function |
| 710 | |
| 711 | The code block for the function is executed, passing it the argument list. The |
| 712 | first thing the code block will do is bind the formal parameters to the |
| 713 | arguments; this is described in section :ref:`function`. When the code block |
| 714 | executes a :keyword:`return` statement, this specifies the return value of the |
| 715 | function call. |
| 716 | |
| 717 | a built-in function or method: |
| 718 | .. index:: |
| 719 | pair: function; call |
| 720 | pair: built-in function; call |
| 721 | pair: method; call |
| 722 | pair: built-in method; call |
| 723 | object: built-in method |
| 724 | object: built-in function |
| 725 | object: method |
| 726 | object: function |
| 727 | |
| 728 | The result is up to the interpreter; see :ref:`built-in-funcs` for the |
| 729 | descriptions of built-in functions and methods. |
| 730 | |
| 731 | a class object: |
| 732 | .. index:: |
| 733 | object: class |
| 734 | pair: class object; call |
| 735 | |
| 736 | A new instance of that class is returned. |
| 737 | |
| 738 | a class instance method: |
| 739 | .. index:: |
| 740 | object: class instance |
| 741 | object: instance |
| 742 | pair: class instance; call |
| 743 | |
| 744 | The corresponding user-defined function is called, with an argument list that is |
| 745 | one longer than the argument list of the call: the instance becomes the first |
| 746 | argument. |
| 747 | |
| 748 | a class instance: |
| 749 | .. index:: |
| 750 | pair: instance; call |
| 751 | single: __call__() (object method) |
| 752 | |
| 753 | The class must define a :meth:`__call__` method; the effect is then the same as |
| 754 | if that method was called. |
| 755 | |
| 756 | |
| 757 | .. _power: |
| 758 | |
| 759 | The power operator |
| 760 | ================== |
| 761 | |
| 762 | The power operator binds more tightly than unary operators on its left; it binds |
| 763 | less tightly than unary operators on its right. The syntax is: |
| 764 | |
| 765 | .. productionlist:: |
| 766 | power: `primary` ["**" `u_expr`] |
| 767 | |
| 768 | Thus, in an unparenthesized sequence of power and unary operators, the operators |
| 769 | are evaluated from right to left (this does not constrain the evaluation order |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 770 | for the operands): ``-1**2`` results in ``-1``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 771 | |
| 772 | The power operator has the same semantics as the built-in :func:`pow` function, |
| 773 | when called with two arguments: it yields its left argument raised to the power |
| 774 | of its right argument. The numeric arguments are first converted to a common |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 775 | type, and the result is of that type. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 776 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 777 | For int operands, the result has the same type as the operands unless the second |
| 778 | argument is negative; in that case, all arguments are converted to float and a |
| 779 | float result is delivered. For example, ``10**2`` returns ``100``, but |
| 780 | ``10**-2`` returns ``0.01``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 781 | |
| 782 | Raising ``0.0`` to a negative power results in a :exc:`ZeroDivisionError`. |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 783 | Raising a negative number to a fractional power results in a :class:`complex` |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 784 | number. (In earlier versions it raised a :exc:`ValueError`.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 785 | |
| 786 | |
| 787 | .. _unary: |
| 788 | |
| 789 | Unary arithmetic operations |
| 790 | =========================== |
| 791 | |
| 792 | .. index:: |
| 793 | triple: unary; arithmetic; operation |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 794 | triple: unary; bitwise; operation |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 795 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 796 | All unary arithmetic (and bitwise) operations have the same priority: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 797 | |
| 798 | .. productionlist:: |
| 799 | u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr` |
| 800 | |
| 801 | .. index:: |
| 802 | single: negation |
| 803 | single: minus |
| 804 | |
| 805 | The unary ``-`` (minus) operator yields the negation of its numeric argument. |
| 806 | |
| 807 | .. index:: single: plus |
| 808 | |
| 809 | The unary ``+`` (plus) operator yields its numeric argument unchanged. |
| 810 | |
| 811 | .. index:: single: inversion |
| 812 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 813 | |
Georg Brandl | 95817b3 | 2008-05-11 14:30:18 +0000 | [diff] [blame] | 814 | The unary ``~`` (invert) operator yields the bitwise inversion of its integer |
| 815 | argument. The bitwise inversion of ``x`` is defined as ``-(x+1)``. It only |
| 816 | applies to integral numbers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 817 | |
| 818 | .. index:: exception: TypeError |
| 819 | |
| 820 | In all three cases, if the argument does not have the proper type, a |
| 821 | :exc:`TypeError` exception is raised. |
| 822 | |
| 823 | |
| 824 | .. _binary: |
| 825 | |
| 826 | Binary arithmetic operations |
| 827 | ============================ |
| 828 | |
| 829 | .. index:: triple: binary; arithmetic; operation |
| 830 | |
| 831 | The binary arithmetic operations have the conventional priority levels. Note |
| 832 | that some of these operations also apply to certain non-numeric types. Apart |
| 833 | from the power operator, there are only two levels, one for multiplicative |
| 834 | operators and one for additive operators: |
| 835 | |
| 836 | .. productionlist:: |
| 837 | m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr` |
| 838 | : | `m_expr` "%" `u_expr` |
| 839 | a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr` |
| 840 | |
| 841 | .. index:: single: multiplication |
| 842 | |
| 843 | The ``*`` (multiplication) operator yields the product of its arguments. The |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 844 | arguments must either both be numbers, or one argument must be an integer and |
| 845 | the other must be a sequence. In the former case, the numbers are converted to a |
| 846 | common type and then multiplied together. In the latter case, sequence |
| 847 | repetition is performed; a negative repetition factor yields an empty sequence. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 848 | |
| 849 | .. index:: |
| 850 | exception: ZeroDivisionError |
| 851 | single: division |
| 852 | |
| 853 | The ``/`` (division) and ``//`` (floor division) operators yield the quotient of |
| 854 | their arguments. The numeric arguments are first converted to a common type. |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 855 | Integer division yields a float, while floor division of integers results in an |
| 856 | integer; the result is that of mathematical division with the 'floor' function |
| 857 | applied to the result. Division by zero raises the :exc:`ZeroDivisionError` |
| 858 | exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 859 | |
| 860 | .. index:: single: modulo |
| 861 | |
| 862 | The ``%`` (modulo) operator yields the remainder from the division of the first |
| 863 | argument by the second. The numeric arguments are first converted to a common |
| 864 | type. A zero right argument raises the :exc:`ZeroDivisionError` exception. The |
| 865 | arguments may be floating point numbers, e.g., ``3.14%0.7`` equals ``0.34`` |
| 866 | (since ``3.14`` equals ``4*0.7 + 0.34``.) The modulo operator always yields a |
| 867 | result with the same sign as its second operand (or zero); the absolute value of |
| 868 | the result is strictly smaller than the absolute value of the second operand |
| 869 | [#]_. |
| 870 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 871 | The floor division and modulo operators are connected by the following |
| 872 | identity: ``x == (x//y)*y + (x%y)``. Floor division and modulo are also |
| 873 | connected with the built-in function :func:`divmod`: ``divmod(x, y) == (x//y, |
| 874 | x%y)``. [#]_. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 875 | |
| 876 | In addition to performing the modulo operation on numbers, the ``%`` operator is |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 877 | also overloaded by string objects to perform old-style string formatting (also |
| 878 | known as interpolation). The syntax for string formatting is described in the |
Georg Brandl | 4b49131 | 2007-08-31 09:22:56 +0000 | [diff] [blame] | 879 | Python Library Reference, section :ref:`old-string-formatting`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 880 | |
| 881 | The floor division operator, the modulo operator, and the :func:`divmod` |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 882 | function are not defined for complex numbers. Instead, convert to a floating |
| 883 | point number using the :func:`abs` function if appropriate. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 884 | |
| 885 | .. index:: single: addition |
| 886 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 887 | The ``+`` (addition) operator yields the sum of its arguments. The arguments |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 888 | must either both be numbers or both sequences of the same type. In the former |
| 889 | case, the numbers are converted to a common type and then added together. In |
| 890 | the latter case, the sequences are concatenated. |
| 891 | |
| 892 | .. index:: single: subtraction |
| 893 | |
| 894 | The ``-`` (subtraction) operator yields the difference of its arguments. The |
| 895 | numeric arguments are first converted to a common type. |
| 896 | |
| 897 | |
| 898 | .. _shifting: |
| 899 | |
| 900 | Shifting operations |
| 901 | =================== |
| 902 | |
| 903 | .. index:: pair: shifting; operation |
| 904 | |
| 905 | The shifting operations have lower priority than the arithmetic operations: |
| 906 | |
| 907 | .. productionlist:: |
| 908 | shift_expr: `a_expr` | `shift_expr` ( "<<" | ">>" ) `a_expr` |
| 909 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 910 | These operators accept integers as arguments. They shift the first argument to |
| 911 | the left or right by the number of bits given by the second argument. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 912 | |
| 913 | .. index:: exception: ValueError |
| 914 | |
| 915 | A right shift by *n* bits is defined as division by ``pow(2,n)``. A left shift |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 916 | by *n* bits is defined as multiplication with ``pow(2,n)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 917 | |
| 918 | |
| 919 | .. _bitwise: |
| 920 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 921 | Binary bitwise operations |
| 922 | ========================= |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 923 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 924 | .. index:: triple: binary; bitwise; operation |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 925 | |
| 926 | Each of the three bitwise operations has a different priority level: |
| 927 | |
| 928 | .. productionlist:: |
| 929 | and_expr: `shift_expr` | `and_expr` "&" `shift_expr` |
| 930 | xor_expr: `and_expr` | `xor_expr` "^" `and_expr` |
| 931 | or_expr: `xor_expr` | `or_expr` "|" `xor_expr` |
| 932 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 933 | .. index:: pair: bitwise; and |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 934 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 935 | The ``&`` operator yields the bitwise AND of its arguments, which must be |
| 936 | integers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 937 | |
| 938 | .. index:: |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 939 | pair: bitwise; xor |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 940 | pair: exclusive; or |
| 941 | |
| 942 | The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 943 | must be integers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 944 | |
| 945 | .. index:: |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 946 | pair: bitwise; or |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 947 | pair: inclusive; or |
| 948 | |
| 949 | The ``|`` operator yields the bitwise (inclusive) OR of its arguments, which |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 950 | must be integers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 951 | |
| 952 | |
| 953 | .. _comparisons: |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 954 | .. _is: |
| 955 | .. _isnot: |
| 956 | .. _in: |
| 957 | .. _notin: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 958 | |
| 959 | Comparisons |
| 960 | =========== |
| 961 | |
| 962 | .. index:: single: comparison |
| 963 | |
| 964 | .. index:: pair: C; language |
| 965 | |
| 966 | Unlike C, all comparison operations in Python have the same priority, which is |
| 967 | lower than that of any arithmetic, shifting or bitwise operation. Also unlike |
| 968 | C, expressions like ``a < b < c`` have the interpretation that is conventional |
| 969 | in mathematics: |
| 970 | |
| 971 | .. productionlist:: |
| 972 | comparison: `or_expr` ( `comp_operator` `or_expr` )* |
| 973 | comp_operator: "<" | ">" | "==" | ">=" | "<=" | "!=" |
| 974 | : | "is" ["not"] | ["not"] "in" |
| 975 | |
| 976 | Comparisons yield boolean values: ``True`` or ``False``. |
| 977 | |
| 978 | .. index:: pair: chaining; comparisons |
| 979 | |
| 980 | Comparisons can be chained arbitrarily, e.g., ``x < y <= z`` is equivalent to |
| 981 | ``x < y and y <= z``, except that ``y`` is evaluated only once (but in both |
| 982 | cases ``z`` is not evaluated at all when ``x < y`` is found to be false). |
| 983 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 984 | Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and *op1*, *op2*, ..., |
| 985 | *opN* are comparison operators, then ``a op1 b op2 c ... y opN z`` is equivalent |
| 986 | to ``a op1 b and b op2 c and ... y opN z``, except that each expression is |
| 987 | evaluated at most once. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 988 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 989 | Note that ``a op1 b op2 c`` doesn't imply any kind of comparison between *a* and |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 990 | *c*, so that, e.g., ``x < y > z`` is perfectly legal (though perhaps not |
| 991 | pretty). |
| 992 | |
| 993 | The operators ``<``, ``>``, ``==``, ``>=``, ``<=``, and ``!=`` compare the |
| 994 | values of two objects. The objects need not have the same type. If both are |
Georg Brandl | 9609cea | 2008-09-09 19:31:57 +0000 | [diff] [blame] | 995 | numbers, they are converted to a common type. Otherwise, the ``==`` and ``!=`` |
| 996 | operators *always* consider objects of different types to be unequal, while the |
| 997 | ``<``, ``>``, ``>=`` and ``<=`` operators raise a :exc:`TypeError` when |
| 998 | comparing objects of different types that do not implement these operators for |
| 999 | the given pair of types. You can control comparison behavior of objects of |
| 1000 | non-builtin types by defining rich comparison methods like :meth:`__gt__`, |
| 1001 | described in section :ref:`customization`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1002 | |
| 1003 | Comparison of objects of the same type depends on the type: |
| 1004 | |
| 1005 | * Numbers are compared arithmetically. |
| 1006 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1007 | * Bytes objects are compared lexicographically using the numeric values of their |
| 1008 | elements. |
Georg Brandl | 4b49131 | 2007-08-31 09:22:56 +0000 | [diff] [blame] | 1009 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1010 | * Strings are compared lexicographically using the numeric equivalents (the |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1011 | result of the built-in function :func:`ord`) of their characters. [#]_ String |
| 1012 | and bytes object can't be compared! |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1013 | |
| 1014 | * Tuples and lists are compared lexicographically using comparison of |
| 1015 | corresponding elements. This means that to compare equal, each element must |
| 1016 | compare equal and the two sequences must be of the same type and have the same |
| 1017 | length. |
| 1018 | |
| 1019 | If not equal, the sequences are ordered the same as their first differing |
| 1020 | elements. For example, ``cmp([1,2,x], [1,2,y])`` returns the same as |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1021 | ``cmp(x,y)``. If the corresponding element does not exist, the shorter |
| 1022 | sequence is ordered first (for example, ``[1,2] < [1,2,3]``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1023 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1024 | * Mappings (dictionaries) compare equal if and only if their sorted ``(key, |
| 1025 | value)`` lists compare equal. [#]_ Outcomes other than equality are resolved |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1026 | consistently, but are not otherwise defined. [#]_ |
| 1027 | |
| 1028 | * Most other objects of builtin types compare unequal unless they are the same |
| 1029 | object; the choice whether one object is considered smaller or larger than |
| 1030 | another one is made arbitrarily but consistently within one execution of a |
| 1031 | program. |
| 1032 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1033 | The operators :keyword:`in` and :keyword:`not in` test for membership. ``x in |
| 1034 | s`` evaluates to true if *x* is a member of *s*, and false otherwise. ``x not |
| 1035 | in s`` returns the negation of ``x in s``. All built-in sequences and set types |
| 1036 | support this as well as dictionary, for which :keyword:`in` tests whether a the |
| 1037 | dictionary has a given key. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1038 | |
| 1039 | For the list and tuple types, ``x in y`` is true if and only if there exists an |
| 1040 | index *i* such that ``x == y[i]`` is true. |
| 1041 | |
Georg Brandl | 4b49131 | 2007-08-31 09:22:56 +0000 | [diff] [blame] | 1042 | For the string and bytes types, ``x in y`` is true if and only if *x* is a |
| 1043 | substring of *y*. An equivalent test is ``y.find(x) != -1``. Empty strings are |
| 1044 | always considered to be a substring of any other string, so ``"" in "abc"`` will |
| 1045 | return ``True``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1046 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1047 | For user-defined classes which define the :meth:`__contains__` method, ``x in |
| 1048 | y`` is true if and only if ``y.__contains__(x)`` is true. |
| 1049 | |
| 1050 | For user-defined classes which do not define :meth:`__contains__` and do define |
| 1051 | :meth:`__getitem__`, ``x in y`` is true if and only if there is a non-negative |
| 1052 | integer index *i* such that ``x == y[i]``, and all lower integer indices do not |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1053 | raise :exc:`IndexError` exception. (If any other exception is raised, it is as |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1054 | if :keyword:`in` raised that exception). |
| 1055 | |
| 1056 | .. index:: |
| 1057 | operator: in |
| 1058 | operator: not in |
| 1059 | pair: membership; test |
| 1060 | object: sequence |
| 1061 | |
| 1062 | The operator :keyword:`not in` is defined to have the inverse true value of |
| 1063 | :keyword:`in`. |
| 1064 | |
| 1065 | .. index:: |
| 1066 | operator: is |
| 1067 | operator: is not |
| 1068 | pair: identity; test |
| 1069 | |
| 1070 | The operators :keyword:`is` and :keyword:`is not` test for object identity: ``x |
| 1071 | is y`` is true if and only if *x* and *y* are the same object. ``x is not y`` |
Benjamin Peterson | 4118174 | 2008-07-02 20:22:54 +0000 | [diff] [blame] | 1072 | yields the inverse truth value. [#]_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1073 | |
| 1074 | |
| 1075 | .. _booleans: |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 1076 | .. _and: |
| 1077 | .. _or: |
| 1078 | .. _not: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1079 | |
| 1080 | Boolean operations |
| 1081 | ================== |
| 1082 | |
| 1083 | .. index:: |
| 1084 | pair: Conditional; expression |
| 1085 | pair: Boolean; operation |
| 1086 | |
| 1087 | Boolean operations have the lowest priority of all Python operations: |
| 1088 | |
| 1089 | .. productionlist:: |
| 1090 | expression: `conditional_expression` | `lambda_form` |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1091 | expression_nocond: `or_test` | `lambda_form_nocond` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1092 | conditional_expression: `or_test` ["if" `or_test` "else" `expression`] |
| 1093 | or_test: `and_test` | `or_test` "or" `and_test` |
| 1094 | and_test: `not_test` | `and_test` "and" `not_test` |
| 1095 | not_test: `comparison` | "not" `not_test` |
| 1096 | |
| 1097 | In the context of Boolean operations, and also when expressions are used by |
| 1098 | control flow statements, the following values are interpreted as false: |
| 1099 | ``False``, ``None``, numeric zero of all types, and empty strings and containers |
| 1100 | (including strings, tuples, lists, dictionaries, sets and frozensets). All |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1101 | other values are interpreted as true. User-defined objects can customize their |
| 1102 | truth value by providing a :meth:`__bool__` method. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1103 | |
| 1104 | .. index:: operator: not |
| 1105 | |
| 1106 | The operator :keyword:`not` yields ``True`` if its argument is false, ``False`` |
| 1107 | otherwise. |
| 1108 | |
| 1109 | The expression ``x if C else y`` first evaluates *C* (*not* *x*); if *C* is |
| 1110 | true, *x* is evaluated and its value is returned; otherwise, *y* is evaluated |
| 1111 | and its value is returned. |
| 1112 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1113 | .. index:: operator: and |
| 1114 | |
| 1115 | The expression ``x and y`` first evaluates *x*; if *x* is false, its value is |
| 1116 | returned; otherwise, *y* is evaluated and the resulting value is returned. |
| 1117 | |
| 1118 | .. index:: operator: or |
| 1119 | |
| 1120 | The expression ``x or y`` first evaluates *x*; if *x* is true, its value is |
| 1121 | returned; otherwise, *y* is evaluated and the resulting value is returned. |
| 1122 | |
| 1123 | (Note that neither :keyword:`and` nor :keyword:`or` restrict the value and type |
| 1124 | they return to ``False`` and ``True``, but rather return the last evaluated |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1125 | argument. This is sometimes useful, e.g., if ``s`` is a string that should be |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1126 | replaced by a default value if it is empty, the expression ``s or 'foo'`` yields |
| 1127 | the desired value. Because :keyword:`not` has to invent a value anyway, it does |
| 1128 | not bother to return a value of the same type as its argument, so e.g., ``not |
| 1129 | 'foo'`` yields ``False``, not ``''``.) |
| 1130 | |
| 1131 | |
| 1132 | .. _lambdas: |
| 1133 | |
| 1134 | Lambdas |
| 1135 | ======= |
| 1136 | |
| 1137 | .. index:: |
| 1138 | pair: lambda; expression |
| 1139 | pair: lambda; form |
| 1140 | pair: anonymous; function |
| 1141 | |
| 1142 | .. productionlist:: |
| 1143 | lambda_form: "lambda" [`parameter_list`]: `expression` |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1144 | lambda_form_nocond: "lambda" [`parameter_list`]: `expression_nocond` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1145 | |
| 1146 | Lambda forms (lambda expressions) have the same syntactic position as |
| 1147 | expressions. They are a shorthand to create anonymous functions; the expression |
| 1148 | ``lambda arguments: expression`` yields a function object. The unnamed object |
| 1149 | behaves like a function object defined with :: |
| 1150 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1151 | def <lambda>(arguments): |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1152 | return expression |
| 1153 | |
| 1154 | See section :ref:`function` for the syntax of parameter lists. Note that |
| 1155 | functions created with lambda forms cannot contain statements or annotations. |
| 1156 | |
| 1157 | .. _lambda: |
| 1158 | |
| 1159 | |
| 1160 | .. _exprlists: |
| 1161 | |
| 1162 | Expression lists |
| 1163 | ================ |
| 1164 | |
| 1165 | .. index:: pair: expression; list |
| 1166 | |
| 1167 | .. productionlist:: |
| 1168 | expression_list: `expression` ( "," `expression` )* [","] |
| 1169 | |
| 1170 | .. index:: object: tuple |
| 1171 | |
| 1172 | An expression list containing at least one comma yields a tuple. The length of |
| 1173 | the tuple is the number of expressions in the list. The expressions are |
| 1174 | evaluated from left to right. |
| 1175 | |
| 1176 | .. index:: pair: trailing; comma |
| 1177 | |
| 1178 | The trailing comma is required only to create a single tuple (a.k.a. a |
| 1179 | *singleton*); it is optional in all other cases. A single expression without a |
| 1180 | trailing comma doesn't create a tuple, but rather yields the value of that |
| 1181 | expression. (To create an empty tuple, use an empty pair of parentheses: |
| 1182 | ``()``.) |
| 1183 | |
| 1184 | |
| 1185 | .. _evalorder: |
| 1186 | |
| 1187 | Evaluation order |
| 1188 | ================ |
| 1189 | |
| 1190 | .. index:: pair: evaluation; order |
| 1191 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1192 | Python evaluates expressions from left to right. Notice that while evaluating |
| 1193 | an assignment, the right-hand side is evaluated before the left-hand side. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1194 | |
| 1195 | In the following lines, expressions will be evaluated in the arithmetic order of |
| 1196 | their suffixes:: |
| 1197 | |
| 1198 | expr1, expr2, expr3, expr4 |
| 1199 | (expr1, expr2, expr3, expr4) |
| 1200 | {expr1: expr2, expr3: expr4} |
| 1201 | expr1 + expr2 * (expr3 - expr4) |
Georg Brandl | 734e268 | 2008-08-12 08:18:18 +0000 | [diff] [blame] | 1202 | expr1(expr2, expr3, *expr4, **expr5) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1203 | expr3, expr4 = expr1, expr2 |
| 1204 | |
| 1205 | |
| 1206 | .. _operator-summary: |
| 1207 | |
| 1208 | Summary |
| 1209 | ======= |
| 1210 | |
| 1211 | .. index:: pair: operator; precedence |
| 1212 | |
| 1213 | The following table summarizes the operator precedences in Python, from lowest |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1214 | precedence (least binding) to highest precedence (most binding). Operators in |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1215 | the same box have the same precedence. Unless the syntax is explicitly given, |
| 1216 | operators are binary. Operators in the same box group left to right (except for |
| 1217 | comparisons, including tests, which all have the same precedence and chain from |
| 1218 | left to right --- see section :ref:`comparisons` --- and exponentiation, which |
| 1219 | groups from right to left). |
| 1220 | |
| 1221 | +----------------------------------------------+-------------------------------------+ |
| 1222 | | Operator | Description | |
| 1223 | +==============================================+=====================================+ |
| 1224 | | :keyword:`lambda` | Lambda expression | |
| 1225 | +----------------------------------------------+-------------------------------------+ |
| 1226 | | :keyword:`or` | Boolean OR | |
| 1227 | +----------------------------------------------+-------------------------------------+ |
| 1228 | | :keyword:`and` | Boolean AND | |
| 1229 | +----------------------------------------------+-------------------------------------+ |
| 1230 | | :keyword:`not` *x* | Boolean NOT | |
| 1231 | +----------------------------------------------+-------------------------------------+ |
| 1232 | | :keyword:`in`, :keyword:`not` :keyword:`in` | Membership tests | |
| 1233 | +----------------------------------------------+-------------------------------------+ |
| 1234 | | :keyword:`is`, :keyword:`is not` | Identity tests | |
| 1235 | +----------------------------------------------+-------------------------------------+ |
| 1236 | | ``<``, ``<=``, ``>``, ``>=``, ``!=``, ``==`` | Comparisons | |
| 1237 | +----------------------------------------------+-------------------------------------+ |
| 1238 | | ``|`` | Bitwise OR | |
| 1239 | +----------------------------------------------+-------------------------------------+ |
| 1240 | | ``^`` | Bitwise XOR | |
| 1241 | +----------------------------------------------+-------------------------------------+ |
| 1242 | | ``&`` | Bitwise AND | |
| 1243 | +----------------------------------------------+-------------------------------------+ |
| 1244 | | ``<<``, ``>>`` | Shifts | |
| 1245 | +----------------------------------------------+-------------------------------------+ |
| 1246 | | ``+``, ``-`` | Addition and subtraction | |
| 1247 | +----------------------------------------------+-------------------------------------+ |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1248 | | ``*``, ``/``, ``//``, ``%`` | Multiplication, division, remainder | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1249 | +----------------------------------------------+-------------------------------------+ |
| 1250 | | ``+x``, ``-x`` | Positive, negative | |
| 1251 | +----------------------------------------------+-------------------------------------+ |
| 1252 | | ``~x`` | Bitwise not | |
| 1253 | +----------------------------------------------+-------------------------------------+ |
| 1254 | | ``**`` | Exponentiation | |
| 1255 | +----------------------------------------------+-------------------------------------+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1256 | | ``x[index]`` | Subscription | |
| 1257 | +----------------------------------------------+-------------------------------------+ |
| 1258 | | ``x[index:index]`` | Slicing | |
| 1259 | +----------------------------------------------+-------------------------------------+ |
Benjamin Peterson | 4cd6a95 | 2008-08-17 20:23:46 +0000 | [diff] [blame] | 1260 | | ``x(arguments...)`` | Call | |
Benjamin Peterson | 38679e2 | 2008-08-17 20:34:29 +0000 | [diff] [blame] | 1261 | +----------------------------------------------+-------------------------------------+ |
Benjamin Peterson | 4cd6a95 | 2008-08-17 20:23:46 +0000 | [diff] [blame] | 1262 | | ``x.attribute`` | Attribute reference | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1263 | +----------------------------------------------+-------------------------------------+ |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1264 | | ``(expressions...)`` | Binding, tuple display, generator | |
| 1265 | | | expressions | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1266 | +----------------------------------------------+-------------------------------------+ |
| 1267 | | ``[expressions...]`` | List display | |
| 1268 | +----------------------------------------------+-------------------------------------+ |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1269 | | ``{expressions...}`` | Dictionary or set display | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1270 | +----------------------------------------------+-------------------------------------+ |
| 1271 | |
| 1272 | .. rubric:: Footnotes |
| 1273 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1274 | .. [#] While ``abs(x%y) < abs(y)`` is true mathematically, for floats it may not be |
| 1275 | true numerically due to roundoff. For example, and assuming a platform on which |
| 1276 | a Python float is an IEEE 754 double-precision number, in order that ``-1e-100 % |
| 1277 | 1e100`` have the same sign as ``1e100``, the computed result is ``-1e-100 + |
| 1278 | 1e100``, which is numerically exactly equal to ``1e100``. Function :func:`fmod` |
| 1279 | in the :mod:`math` module returns a result whose sign matches the sign of the |
| 1280 | first argument instead, and so returns ``-1e-100`` in this case. Which approach |
| 1281 | is more appropriate depends on the application. |
| 1282 | |
| 1283 | .. [#] If x is very close to an exact integer multiple of y, it's possible for |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1284 | ``x//y`` to be one larger than ``(x-x%y)//y`` due to rounding. In such |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1285 | cases, Python returns the latter result, in order to preserve that |
| 1286 | ``divmod(x,y)[0] * y + x % y`` be very close to ``x``. |
| 1287 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1288 | .. [#] While comparisons between strings make sense at the byte level, they may |
| 1289 | be counter-intuitive to users. For example, the strings ``"\u00C7"`` and |
| 1290 | ``"\u0327\u0043"`` compare differently, even though they both represent the |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 1291 | same unicode character (LATIN CAPTITAL LETTER C WITH CEDILLA). To compare |
| 1292 | strings in a human recognizable way, compare using |
| 1293 | :func:`unicodedata.normalize`. |
Guido van Rossum | da27fd2 | 2007-08-17 00:24:54 +0000 | [diff] [blame] | 1294 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1295 | .. [#] The implementation computes this efficiently, without constructing lists |
| 1296 | or sorting. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1297 | |
| 1298 | .. [#] Earlier versions of Python used lexicographic comparison of the sorted (key, |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1299 | value) lists, but this was very expensive for the common case of comparing |
| 1300 | for equality. An even earlier version of Python compared dictionaries by |
| 1301 | identity only, but this caused surprises because people expected to be able |
| 1302 | to test a dictionary for emptiness by comparing it to ``{}``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1303 | |
Benjamin Peterson | 4118174 | 2008-07-02 20:22:54 +0000 | [diff] [blame] | 1304 | .. [#] Due to automatic garbage-collection, free lists, and the dynamic nature of |
| 1305 | descriptors, you may notice seemingly unusual behaviour in certain uses of |
| 1306 | the :keyword:`is` operator, like those involving comparisons between instance |
| 1307 | methods, or constants. Check their documentation for more info. |