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 | |
Brett Cannon | 7603fa0 | 2011-01-06 23:08:16 +0000 | [diff] [blame] | 10 | This chapter explains the meaning of the elements of expressions in Python. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 32 | implementation for built-in types works as follows: |
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 | |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 41 | Some additional rules apply for certain operators (e.g., a string as a left |
| 42 | argument to the '%' operator). Extensions must define their own conversion |
| 43 | behavior. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 44 | |
| 45 | |
| 46 | .. _atoms: |
| 47 | |
| 48 | Atoms |
| 49 | ===== |
| 50 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 51 | .. index:: atom |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 52 | |
| 53 | Atoms are the most basic elements of expressions. The simplest atoms are |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 54 | identifiers or literals. Forms enclosed in parentheses, brackets or braces are |
| 55 | also categorized syntactically as atoms. The syntax for atoms is: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | |
| 57 | .. productionlist:: |
| 58 | atom: `identifier` | `literal` | `enclosure` |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 59 | enclosure: `parenth_form` | `list_display` | `dict_display` | `set_display` |
| 60 | : | `generator_expression` | `yield_atom` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 61 | |
| 62 | |
| 63 | .. _atom-identifiers: |
| 64 | |
| 65 | Identifiers (Names) |
| 66 | ------------------- |
| 67 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 68 | .. index:: name, identifier |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
| 70 | An identifier occurring as an atom is a name. See section :ref:`identifiers` |
| 71 | for lexical definition and section :ref:`naming` for documentation of naming and |
| 72 | binding. |
| 73 | |
| 74 | .. index:: exception: NameError |
| 75 | |
| 76 | When the name is bound to an object, evaluation of the atom yields that object. |
| 77 | When a name is not bound, an attempt to evaluate it raises a :exc:`NameError` |
| 78 | exception. |
| 79 | |
| 80 | .. index:: |
| 81 | pair: name; mangling |
| 82 | pair: private; names |
| 83 | |
| 84 | **Private name mangling:** When an identifier that textually occurs in a class |
| 85 | definition begins with two or more underscore characters and does not end in two |
| 86 | or more underscores, it is considered a :dfn:`private name` of that class. |
| 87 | Private names are transformed to a longer form before code is generated for |
Georg Brandl | dec3b3f | 2013-04-14 10:13:42 +0200 | [diff] [blame] | 88 | them. The transformation inserts the class name, with leading underscores |
| 89 | removed and a single underscore inserted, in front of the name. For example, |
| 90 | the identifier ``__spam`` occurring in a class named ``Ham`` will be transformed |
| 91 | to ``_Ham__spam``. This transformation is independent of the syntactical |
| 92 | context in which the identifier is used. If the transformed name is extremely |
| 93 | long (longer than 255 characters), implementation defined truncation may happen. |
| 94 | If the class name consists only of underscores, no transformation is done. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Terry Jan Reedy | ead1de2 | 2012-02-17 19:56:58 -0500 | [diff] [blame] | 119 | All literals correspond to immutable data types, and hence the object's identity |
| 120 | is less important than its value. Multiple evaluations of literals with the |
| 121 | same value (either the same occurrence in the program text or a different |
| 122 | occurrence) may obtain the same object or a different object with the same |
| 123 | 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:: |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 136 | parenth_form: "(" [`starred_expression`] ")" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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` |
Yury Selivanov | 0366004 | 2016-12-15 17:36:05 -0500 | [diff] [blame] | 175 | comp_for: [ASYNC] "for" `target_list` "in" `or_test` [`comp_iter`] |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 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 |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 187 | to in the target list don't "leak" into the enclosing scope. |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 188 | |
Yury Selivanov | 0366004 | 2016-12-15 17:36:05 -0500 | [diff] [blame] | 189 | Since Python 3.6, in an :keyword:`async def` function, an :keyword:`async for` |
| 190 | clause may be used to iterate over a :term:`asynchronous iterator`. |
| 191 | A comprehension in an :keyword:`async def` function may consist of either a |
| 192 | :keyword:`for` or :keyword:`async for` clause following the leading |
Mariatta | f28db60 | 2017-02-24 16:39:30 -0800 | [diff] [blame^] | 193 | expression, may contain additional :keyword:`for` or :keyword:`async for` |
Yury Selivanov | 0366004 | 2016-12-15 17:36:05 -0500 | [diff] [blame] | 194 | clauses, and may also use :keyword:`await` expressions. |
| 195 | If a comprehension contains either :keyword:`async for` clauses |
| 196 | or :keyword:`await` expressions it is called an |
| 197 | :dfn:`asynchronous comprehension`. An asynchronous comprehension may |
| 198 | suspend the execution of the coroutine function in which it appears. |
| 199 | See also :pep:`530`. |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 200 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 201 | .. _lists: |
| 202 | |
| 203 | List displays |
| 204 | ------------- |
| 205 | |
| 206 | .. index:: |
| 207 | pair: list; display |
| 208 | pair: list; comprehensions |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 209 | pair: empty; list |
| 210 | object: list |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 211 | |
| 212 | A list display is a possibly empty series of expressions enclosed in square |
| 213 | brackets: |
| 214 | |
| 215 | .. productionlist:: |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 216 | list_display: "[" [`starred_list` | `comprehension`] "]" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 217 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 218 | A list display yields a new list object, the contents being specified by either |
| 219 | a list of expressions or a comprehension. When a comma-separated list of |
| 220 | expressions is supplied, its elements are evaluated from left to right and |
| 221 | placed into the list object in that order. When a comprehension is supplied, |
| 222 | the list is constructed from the elements resulting from the comprehension. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 223 | |
| 224 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 225 | .. _set: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 226 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 227 | Set displays |
| 228 | ------------ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 229 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 230 | .. index:: pair: set; display |
| 231 | object: set |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 232 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 233 | A set display is denoted by curly braces and distinguishable from dictionary |
| 234 | displays by the lack of colons separating keys and values: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 235 | |
| 236 | .. productionlist:: |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 237 | set_display: "{" (`starred_list` | `comprehension`) "}" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 238 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 239 | A set display yields a new mutable set object, the contents being specified by |
| 240 | either a sequence of expressions or a comprehension. When a comma-separated |
| 241 | list of expressions is supplied, its elements are evaluated from left to right |
| 242 | and added to the set object. When a comprehension is supplied, the set is |
| 243 | constructed from the elements resulting from the comprehension. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 244 | |
Georg Brandl | 528cdb1 | 2008-09-21 07:09:51 +0000 | [diff] [blame] | 245 | An empty set cannot be constructed with ``{}``; this literal constructs an empty |
| 246 | dictionary. |
Christian Heimes | 7864476 | 2008-03-04 23:39:23 +0000 | [diff] [blame] | 247 | |
| 248 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 249 | .. _dict: |
| 250 | |
| 251 | Dictionary displays |
| 252 | ------------------- |
| 253 | |
| 254 | .. index:: pair: dictionary; display |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 255 | key, datum, key/datum pair |
| 256 | object: dictionary |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 257 | |
| 258 | A dictionary display is a possibly empty series of key/datum pairs enclosed in |
| 259 | curly braces: |
| 260 | |
| 261 | .. productionlist:: |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 262 | dict_display: "{" [`key_datum_list` | `dict_comprehension`] "}" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 263 | key_datum_list: `key_datum` ("," `key_datum`)* [","] |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 264 | key_datum: `expression` ":" `expression` | "**" `or_expr` |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 265 | dict_comprehension: `expression` ":" `expression` `comp_for` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 266 | |
| 267 | A dictionary display yields a new dictionary object. |
| 268 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 269 | If a comma-separated sequence of key/datum pairs is given, they are evaluated |
| 270 | from left to right to define the entries of the dictionary: each key object is |
| 271 | used as a key into the dictionary to store the corresponding datum. This means |
| 272 | that you can specify the same key multiple times in the key/datum list, and the |
| 273 | final dictionary's value for that key will be the last one given. |
| 274 | |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 275 | .. index:: unpacking; dictionary, **; in dictionary displays |
| 276 | |
| 277 | A double asterisk ``**`` denotes :dfn:`dictionary unpacking`. |
| 278 | Its operand must be a :term:`mapping`. Each mapping item is added |
| 279 | to the new dictionary. Later values replace values already set by |
| 280 | earlier key/datum pairs and earlier dictionary unpackings. |
| 281 | |
| 282 | .. versionadded:: 3.5 |
| 283 | Unpacking into dictionary displays, originally proposed by :pep:`448`. |
| 284 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 285 | A dict comprehension, in contrast to list and set comprehensions, needs two |
| 286 | expressions separated with a colon followed by the usual "for" and "if" clauses. |
| 287 | When the comprehension is run, the resulting key and value elements are inserted |
| 288 | in the new dictionary in the order they are produced. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 289 | |
| 290 | .. index:: pair: immutable; object |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 291 | hashable |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 292 | |
| 293 | 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] | 294 | :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] | 295 | all mutable objects.) Clashes between duplicate keys are not detected; the last |
| 296 | datum (textually rightmost in the display) stored for a given key value |
| 297 | prevails. |
| 298 | |
| 299 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 300 | .. _genexpr: |
| 301 | |
| 302 | Generator expressions |
| 303 | --------------------- |
| 304 | |
| 305 | .. index:: pair: generator; expression |
| 306 | object: generator |
| 307 | |
| 308 | A generator expression is a compact generator notation in parentheses: |
| 309 | |
| 310 | .. productionlist:: |
| 311 | generator_expression: "(" `expression` `comp_for` ")" |
| 312 | |
| 313 | A generator expression yields a new generator object. Its syntax is the same as |
| 314 | for comprehensions, except that it is enclosed in parentheses instead of |
| 315 | brackets or curly braces. |
| 316 | |
| 317 | Variables used in the generator expression are evaluated lazily when the |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 318 | :meth:`~generator.__next__` method is called for the generator object (in the same |
Ezio Melotti | 7fa8222 | 2012-10-12 13:42:08 +0300 | [diff] [blame] | 319 | fashion as normal generators). However, the leftmost :keyword:`for` clause is |
| 320 | immediately evaluated, so that an error produced by it can be seen before any |
| 321 | other possible error in the code that handles the generator expression. |
| 322 | Subsequent :keyword:`for` clauses cannot be evaluated immediately since they |
| 323 | may depend on the previous :keyword:`for` loop. For example: ``(x*y for x in |
| 324 | range(10) for y in bar(x))``. |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 325 | |
| 326 | The parentheses can be omitted on calls with only one argument. See section |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 327 | :ref:`calls` for details. |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 328 | |
Yury Selivanov | 0366004 | 2016-12-15 17:36:05 -0500 | [diff] [blame] | 329 | Since Python 3.6, if the generator appears in an :keyword:`async def` function, |
| 330 | then :keyword:`async for` clauses and :keyword:`await` expressions are permitted |
| 331 | as with an asynchronous comprehension. If a generator expression |
| 332 | contains either :keyword:`async for` clauses or :keyword:`await` expressions |
| 333 | it is called an :dfn:`asynchronous generator expression`. |
| 334 | An asynchronous generator expression yields a new asynchronous |
| 335 | generator object, which is an asynchronous iterator |
| 336 | (see :ref:`async-iterators`). |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 337 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 338 | .. _yieldexpr: |
| 339 | |
| 340 | Yield expressions |
| 341 | ----------------- |
| 342 | |
| 343 | .. index:: |
| 344 | keyword: yield |
| 345 | pair: yield; expression |
| 346 | pair: generator; function |
| 347 | |
| 348 | .. productionlist:: |
| 349 | yield_atom: "(" `yield_expression` ")" |
Nick Coghlan | 1f7ce62 | 2012-01-13 21:43:40 +1000 | [diff] [blame] | 350 | yield_expression: "yield" [`expression_list` | "from" `expression`] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 351 | |
Yury Selivanov | 0366004 | 2016-12-15 17:36:05 -0500 | [diff] [blame] | 352 | The yield expression is used when defining a :term:`generator` function |
| 353 | or an :term:`asynchronous generator` function and |
Benjamin Peterson | d1c85fd | 2014-01-26 22:52:08 -0500 | [diff] [blame] | 354 | thus can only be used in the body of a function definition. Using a yield |
Yury Selivanov | 0366004 | 2016-12-15 17:36:05 -0500 | [diff] [blame] | 355 | expression in a function's body causes that function to be a generator, |
| 356 | and using it in an :keyword:`async def` function's body causes that |
| 357 | coroutine function to be an asynchronous generator. For example:: |
| 358 | |
| 359 | def gen(): # defines a generator function |
| 360 | yield 123 |
| 361 | |
| 362 | async def agen(): # defines an asynchronous generator function (PEP 525) |
| 363 | yield 123 |
| 364 | |
| 365 | Generator functions are described below, while asynchronous generator |
| 366 | functions are described separately in section |
| 367 | :ref:`asynchronous-generator-functions`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 368 | |
| 369 | When a generator function is called, it returns an iterator known as a |
Guido van Rossum | d0150ad | 2015-05-05 12:02:01 -0700 | [diff] [blame] | 370 | generator. That generator then controls the execution of the generator function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 371 | The execution starts when one of the generator's methods is called. At that |
Benjamin Peterson | d1c85fd | 2014-01-26 22:52:08 -0500 | [diff] [blame] | 372 | time, the execution proceeds to the first yield expression, where it is |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 373 | suspended again, returning the value of :token:`expression_list` to the generator's |
Benjamin Peterson | d1c85fd | 2014-01-26 22:52:08 -0500 | [diff] [blame] | 374 | caller. By suspended, we mean that all local state is retained, including the |
Ethan Furman | 2f825af | 2015-01-14 22:25:27 -0800 | [diff] [blame] | 375 | current bindings of local variables, the instruction pointer, the internal |
| 376 | evaluation stack, and the state of any exception handling. When the execution |
| 377 | is resumed by calling one of the |
Benjamin Peterson | d1c85fd | 2014-01-26 22:52:08 -0500 | [diff] [blame] | 378 | generator's methods, the function can proceed exactly as if the yield expression |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 379 | were just another external call. The value of the yield expression after |
Benjamin Peterson | d1c85fd | 2014-01-26 22:52:08 -0500 | [diff] [blame] | 380 | resuming depends on the method which resumed the execution. If |
| 381 | :meth:`~generator.__next__` is used (typically via either a :keyword:`for` or |
| 382 | the :func:`next` builtin) then the result is :const:`None`. Otherwise, if |
| 383 | :meth:`~generator.send` is used, then the result will be the value passed in to |
| 384 | that method. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 385 | |
| 386 | .. index:: single: coroutine |
| 387 | |
| 388 | All of this makes generator functions quite similar to coroutines; they yield |
| 389 | multiple times, they have more than one entry point and their execution can be |
| 390 | suspended. The only difference is that a generator function cannot control |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 391 | where the execution should continue after it yields; the control is always |
Georg Brandl | 6faee4e | 2010-09-21 14:48:28 +0000 | [diff] [blame] | 392 | transferred to the generator's caller. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 393 | |
Ethan Furman | 2f825af | 2015-01-14 22:25:27 -0800 | [diff] [blame] | 394 | Yield expressions are allowed anywhere in a :keyword:`try` construct. If the |
| 395 | generator is not resumed before it is |
Benjamin Peterson | d1c85fd | 2014-01-26 22:52:08 -0500 | [diff] [blame] | 396 | finalized (by reaching a zero reference count or by being garbage collected), |
| 397 | the generator-iterator's :meth:`~generator.close` method will be called, |
| 398 | allowing any pending :keyword:`finally` clauses to execute. |
Georg Brandl | 02c3056 | 2007-09-07 17:52:53 +0000 | [diff] [blame] | 399 | |
Nick Coghlan | 0ed8019 | 2012-01-14 14:43:24 +1000 | [diff] [blame] | 400 | When ``yield from <expr>`` is used, it treats the supplied expression as |
Nick Coghlan | 1f7ce62 | 2012-01-13 21:43:40 +1000 | [diff] [blame] | 401 | a subiterator. All values produced by that subiterator are passed directly |
| 402 | to the caller of the current generator's methods. Any values passed in with |
Serhiy Storchaka | 0d196ed | 2013-10-09 14:02:31 +0300 | [diff] [blame] | 403 | :meth:`~generator.send` and any exceptions passed in with |
| 404 | :meth:`~generator.throw` are passed to the underlying iterator if it has the |
| 405 | appropriate methods. If this is not the case, then :meth:`~generator.send` |
| 406 | will raise :exc:`AttributeError` or :exc:`TypeError`, while |
| 407 | :meth:`~generator.throw` will just raise the passed in exception immediately. |
Nick Coghlan | 1f7ce62 | 2012-01-13 21:43:40 +1000 | [diff] [blame] | 408 | |
| 409 | When the underlying iterator is complete, the :attr:`~StopIteration.value` |
| 410 | attribute of the raised :exc:`StopIteration` instance becomes the value of |
| 411 | the yield expression. It can be either set explicitly when raising |
| 412 | :exc:`StopIteration`, or automatically when the sub-iterator is a generator |
| 413 | (by returning a value from the sub-generator). |
| 414 | |
Nick Coghlan | 0ed8019 | 2012-01-14 14:43:24 +1000 | [diff] [blame] | 415 | .. versionchanged:: 3.3 |
Martin Panter | d21e0b5 | 2015-10-10 10:36:22 +0000 | [diff] [blame] | 416 | Added ``yield from <expr>`` to delegate control flow to a subiterator. |
Nick Coghlan | 0ed8019 | 2012-01-14 14:43:24 +1000 | [diff] [blame] | 417 | |
Benjamin Peterson | d1c85fd | 2014-01-26 22:52:08 -0500 | [diff] [blame] | 418 | The parentheses may be omitted when the yield expression is the sole expression |
| 419 | on the right hand side of an assignment statement. |
| 420 | |
| 421 | .. seealso:: |
| 422 | |
Serhiy Storchaka | e4ba872 | 2016-03-31 15:30:54 +0300 | [diff] [blame] | 423 | :pep:`255` - Simple Generators |
Benjamin Peterson | d1c85fd | 2014-01-26 22:52:08 -0500 | [diff] [blame] | 424 | The proposal for adding generators and the :keyword:`yield` statement to Python. |
| 425 | |
Serhiy Storchaka | e4ba872 | 2016-03-31 15:30:54 +0300 | [diff] [blame] | 426 | :pep:`342` - Coroutines via Enhanced Generators |
Benjamin Peterson | d1c85fd | 2014-01-26 22:52:08 -0500 | [diff] [blame] | 427 | The proposal to enhance the API and syntax of generators, making them |
| 428 | usable as simple coroutines. |
| 429 | |
Serhiy Storchaka | e4ba872 | 2016-03-31 15:30:54 +0300 | [diff] [blame] | 430 | :pep:`380` - Syntax for Delegating to a Subgenerator |
Benjamin Peterson | d1c85fd | 2014-01-26 22:52:08 -0500 | [diff] [blame] | 431 | The proposal to introduce the :token:`yield_from` syntax, making delegation |
| 432 | to sub-generators easy. |
Nick Coghlan | 1f7ce62 | 2012-01-13 21:43:40 +1000 | [diff] [blame] | 433 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 434 | .. index:: object: generator |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 435 | .. _generator-methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 436 | |
R David Murray | 2c1d1d6 | 2012-08-17 20:48:59 -0400 | [diff] [blame] | 437 | Generator-iterator methods |
| 438 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 439 | |
| 440 | This subsection describes the methods of a generator iterator. They can |
| 441 | be used to control the execution of a generator function. |
| 442 | |
| 443 | Note that calling any of the generator methods below when the generator |
| 444 | is already executing raises a :exc:`ValueError` exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 445 | |
| 446 | .. index:: exception: StopIteration |
| 447 | |
| 448 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 449 | .. method:: generator.__next__() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 450 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 451 | Starts the execution of a generator function or resumes it at the last |
Benjamin Peterson | d1c85fd | 2014-01-26 22:52:08 -0500 | [diff] [blame] | 452 | executed yield expression. When a generator function is resumed with a |
| 453 | :meth:`~generator.__next__` method, the current yield expression always |
| 454 | evaluates to :const:`None`. The execution then continues to the next yield |
| 455 | expression, where the generator is suspended again, and the value of the |
Serhiy Storchaka | 848c8b2 | 2014-09-05 23:27:36 +0300 | [diff] [blame] | 456 | :token:`expression_list` is returned to :meth:`__next__`'s caller. If the |
Benjamin Peterson | d1c85fd | 2014-01-26 22:52:08 -0500 | [diff] [blame] | 457 | generator exits without yielding another value, a :exc:`StopIteration` |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 458 | exception is raised. |
| 459 | |
| 460 | This method is normally called implicitly, e.g. by a :keyword:`for` loop, or |
| 461 | by the built-in :func:`next` function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 462 | |
| 463 | |
| 464 | .. method:: generator.send(value) |
| 465 | |
| 466 | Resumes the execution and "sends" a value into the generator function. The |
Benjamin Peterson | d1c85fd | 2014-01-26 22:52:08 -0500 | [diff] [blame] | 467 | *value* argument becomes the result of the current yield expression. The |
| 468 | :meth:`send` method returns the next value yielded by the generator, or |
| 469 | raises :exc:`StopIteration` if the generator exits without yielding another |
| 470 | value. When :meth:`send` is called to start the generator, it must be called |
| 471 | with :const:`None` as the argument, because there is no yield expression that |
| 472 | could receive the value. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 473 | |
| 474 | |
| 475 | .. method:: generator.throw(type[, value[, traceback]]) |
| 476 | |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 477 | Raises an exception of type ``type`` at the point where the generator was paused, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 478 | and returns the next value yielded by the generator function. If the generator |
| 479 | exits without yielding another value, a :exc:`StopIteration` exception is |
| 480 | raised. If the generator function does not catch the passed-in exception, or |
| 481 | raises a different exception, then that exception propagates to the caller. |
| 482 | |
| 483 | .. index:: exception: GeneratorExit |
| 484 | |
| 485 | |
| 486 | .. method:: generator.close() |
| 487 | |
| 488 | Raises a :exc:`GeneratorExit` at the point where the generator function was |
Yury Selivanov | 8170e8c | 2015-05-09 11:44:30 -0400 | [diff] [blame] | 489 | paused. If the generator function then exits gracefully, is already closed, |
| 490 | or raises :exc:`GeneratorExit` (by not catching the exception), close |
| 491 | returns to its caller. If the generator yields a value, a |
| 492 | :exc:`RuntimeError` is raised. If the generator raises any other exception, |
| 493 | it is propagated to the caller. :meth:`close` does nothing if the generator |
| 494 | has already exited due to an exception or normal exit. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 495 | |
Chris Jerdonek | 2654b86 | 2012-12-23 15:31:57 -0800 | [diff] [blame] | 496 | .. index:: single: yield; examples |
| 497 | |
| 498 | Examples |
| 499 | ^^^^^^^^ |
| 500 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 501 | Here is a simple example that demonstrates the behavior of generators and |
| 502 | generator functions:: |
| 503 | |
| 504 | >>> def echo(value=None): |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 505 | ... print("Execution starts when 'next()' is called for the first time.") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 506 | ... try: |
| 507 | ... while True: |
| 508 | ... try: |
| 509 | ... value = (yield value) |
Georg Brandl | fe800a3 | 2009-08-03 17:50:20 +0000 | [diff] [blame] | 510 | ... except Exception as e: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 511 | ... value = e |
| 512 | ... finally: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 513 | ... print("Don't forget to clean up when 'close()' is called.") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 514 | ... |
| 515 | >>> generator = echo(1) |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 516 | >>> print(next(generator)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 517 | Execution starts when 'next()' is called for the first time. |
| 518 | 1 |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 519 | >>> print(next(generator)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 520 | None |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 521 | >>> print(generator.send(2)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 522 | 2 |
| 523 | >>> generator.throw(TypeError, "spam") |
| 524 | TypeError('spam',) |
| 525 | >>> generator.close() |
| 526 | Don't forget to clean up when 'close()' is called. |
| 527 | |
Chris Jerdonek | 2654b86 | 2012-12-23 15:31:57 -0800 | [diff] [blame] | 528 | For examples using ``yield from``, see :ref:`pep-380` in "What's New in |
| 529 | Python." |
| 530 | |
Yury Selivanov | 0366004 | 2016-12-15 17:36:05 -0500 | [diff] [blame] | 531 | .. _asynchronous-generator-functions: |
| 532 | |
| 533 | Asynchronous generator functions |
| 534 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 535 | |
| 536 | The presence of a yield expression in a function or method defined using |
| 537 | :keyword:`async def` further defines the function as a |
| 538 | :term:`asynchronous generator` function. |
| 539 | |
| 540 | When an asynchronous generator function is called, it returns an |
| 541 | asynchronous iterator known as an asynchronous generator object. |
| 542 | That object then controls the execution of the generator function. |
| 543 | An asynchronous generator object is typically used in an |
| 544 | :keyword:`async for` statement in a coroutine function analogously to |
| 545 | how a generator object would be used in a :keyword:`for` statement. |
| 546 | |
| 547 | Calling one of the asynchronous generator's methods returns an |
| 548 | :term:`awaitable` object, and the execution starts when this object |
| 549 | is awaited on. At that time, the execution proceeds to the first yield |
| 550 | expression, where it is suspended again, returning the value of |
| 551 | :token:`expression_list` to the awaiting coroutine. As with a generator, |
| 552 | suspension means that all local state is retained, including the |
| 553 | current bindings of local variables, the instruction pointer, the internal |
| 554 | evaluation stack, and the state of any exception handling. When the execution |
| 555 | is resumed by awaiting on the next object returned by the asynchronous |
| 556 | generator's methods, the function can proceed exactly as if the yield |
| 557 | expression were just another external call. The value of the yield expression |
| 558 | after resuming depends on the method which resumed the execution. If |
| 559 | :meth:`~agen.__anext__` is used then the result is :const:`None`. Otherwise, if |
| 560 | :meth:`~agen.asend` is used, then the result will be the value passed in to |
| 561 | that method. |
| 562 | |
| 563 | In an asynchronous generator function, yield expressions are allowed anywhere |
| 564 | in a :keyword:`try` construct. However, if an asynchronous generator is not |
| 565 | resumed before it is finalized (by reaching a zero reference count or by |
| 566 | being garbage collected), then a yield expression within a :keyword:`try` |
| 567 | construct could result in a failure to execute pending :keyword:`finally` |
| 568 | clauses. In this case, it is the responsibility of the event loop or |
| 569 | scheduler running the asynchronous generator to call the asynchronous |
| 570 | generator-iterator's :meth:`~agen.aclose` method and run the resulting |
| 571 | coroutine object, thus allowing any pending :keyword:`finally` clauses |
| 572 | to execute. |
| 573 | |
| 574 | To take care of finalization, an event loop should define |
| 575 | a *finalizer* function which takes an asynchronous generator-iterator |
| 576 | and presumably calls :meth:`~agen.aclose` and executes the coroutine. |
| 577 | This *finalizer* may be registered by calling :func:`sys.set_asyncgen_hooks`. |
| 578 | When first iterated over, an asynchronous generator-iterator will store the |
| 579 | registered *finalizer* to be called upon finalization. For a reference example |
| 580 | of a *finalizer* method see the implementation of |
| 581 | ``asyncio.Loop.shutdown_asyncgens`` in :source:`Lib/asyncio/base_events.py`. |
| 582 | |
| 583 | The expression ``yield from <expr>`` is a syntax error when used in an |
| 584 | asynchronous generator function. |
| 585 | |
| 586 | .. index:: object: asynchronous-generator |
| 587 | .. _asynchronous-generator-methods: |
| 588 | |
| 589 | Asynchronous generator-iterator methods |
| 590 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 591 | |
| 592 | This subsection describes the methods of an asynchronous generator iterator, |
| 593 | which are used to control the execution of a generator function. |
| 594 | |
| 595 | |
| 596 | .. index:: exception: StopAsyncIteration |
| 597 | |
| 598 | .. coroutinemethod:: agen.__anext__() |
| 599 | |
| 600 | Returns an awaitable which when run starts to execute the asynchronous |
| 601 | generator or resumes it at the last executed yield expression. When an |
| 602 | asynchronous generator function is resumed with a :meth:`~agen.__anext__` |
| 603 | method, the current yield expression always evaluates to :const:`None` in |
| 604 | the returned awaitable, which when run will continue to the next yield |
| 605 | expression. The value of the :token:`expression_list` of the yield |
| 606 | expression is the value of the :exc:`StopIteration` exception raised by |
| 607 | the completing coroutine. If the asynchronous generator exits without |
| 608 | yielding another value, the awaitable instead raises an |
| 609 | :exc:`StopAsyncIteration` exception, signalling that the asynchronous |
| 610 | iteration has completed. |
| 611 | |
| 612 | This method is normally called implicitly by a :keyword:`async for` loop. |
| 613 | |
| 614 | |
| 615 | .. coroutinemethod:: agen.asend(value) |
| 616 | |
| 617 | Returns an awaitable which when run resumes the execution of the |
| 618 | asynchronous generator. As with the :meth:`~generator.send()` method for a |
| 619 | generator, this "sends" a value into the asynchronous generator function, |
| 620 | and the *value* argument becomes the result of the current yield expression. |
| 621 | The awaitable returned by the :meth:`asend` method will return the next |
| 622 | value yielded by the generator as the value of the raised |
| 623 | :exc:`StopIteration`, or raises :exc:`StopAsyncIteration` if the |
| 624 | asynchronous generator exits without yielding another value. When |
| 625 | :meth:`asend` is called to start the asynchronous |
| 626 | generator, it must be called with :const:`None` as the argument, |
| 627 | because there is no yield expression that could receive the value. |
| 628 | |
| 629 | |
| 630 | .. coroutinemethod:: agen.athrow(type[, value[, traceback]]) |
| 631 | |
| 632 | Returns an awaitable that raises an exception of type ``type`` at the point |
| 633 | where the asynchronous generator was paused, and returns the next value |
| 634 | yielded by the generator function as the value of the raised |
| 635 | :exc:`StopIteration` exception. If the asynchronous generator exits |
| 636 | without yielding another value, an :exc:`StopAsyncIteration` exception is |
| 637 | raised by the awaitable. |
| 638 | If the generator function does not catch the passed-in exception, or |
| 639 | raises a different exception, then when the awaitalbe is run that exception |
| 640 | propagates to the caller of the awaitable. |
| 641 | |
| 642 | .. index:: exception: GeneratorExit |
| 643 | |
| 644 | |
| 645 | .. coroutinemethod:: agen.aclose() |
| 646 | |
| 647 | Returns an awaitable that when run will throw a :exc:`GeneratorExit` into |
| 648 | the asynchronous generator function at the point where it was paused. |
| 649 | If the asynchronous generator function then exits gracefully, is already |
| 650 | closed, or raises :exc:`GeneratorExit` (by not catching the exception), |
| 651 | then the returned awaitable will raise a :exc:`StopIteration` exception. |
| 652 | Any further awaitables returned by subsequent calls to the asynchronous |
| 653 | generator will raise a :exc:`StopAsyncIteration` exception. If the |
| 654 | asynchronous generator yields a value, a :exc:`RuntimeError` is raised |
| 655 | by the awaitable. If the asynchronous generator raises any other exception, |
| 656 | it is propagated to the caller of the awaitable. If the asynchronous |
| 657 | generator has already exited due to an exception or normal exit, then |
| 658 | further calls to :meth:`aclose` will return an awaitable that does nothing. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 659 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 660 | .. _primaries: |
| 661 | |
| 662 | Primaries |
| 663 | ========= |
| 664 | |
| 665 | .. index:: single: primary |
| 666 | |
| 667 | Primaries represent the most tightly bound operations of the language. Their |
| 668 | syntax is: |
| 669 | |
| 670 | .. productionlist:: |
| 671 | primary: `atom` | `attributeref` | `subscription` | `slicing` | `call` |
| 672 | |
| 673 | |
| 674 | .. _attribute-references: |
| 675 | |
| 676 | Attribute references |
| 677 | -------------------- |
| 678 | |
| 679 | .. index:: pair: attribute; reference |
| 680 | |
| 681 | An attribute reference is a primary followed by a period and a name: |
| 682 | |
| 683 | .. productionlist:: |
| 684 | attributeref: `primary` "." `identifier` |
| 685 | |
| 686 | .. index:: |
| 687 | exception: AttributeError |
| 688 | object: module |
| 689 | object: list |
| 690 | |
| 691 | 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] | 692 | references, which most objects do. This object is then asked to produce the |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 693 | attribute whose name is the identifier. This production can be customized by |
Zachary Ware | 2f78b84 | 2014-06-03 09:32:40 -0500 | [diff] [blame] | 694 | overriding the :meth:`__getattr__` method. If this attribute is not available, |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 695 | the exception :exc:`AttributeError` is raised. Otherwise, the type and value of |
| 696 | the object produced is determined by the object. Multiple evaluations of the |
| 697 | same attribute reference may yield different objects. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 698 | |
| 699 | |
| 700 | .. _subscriptions: |
| 701 | |
| 702 | Subscriptions |
| 703 | ------------- |
| 704 | |
| 705 | .. index:: single: subscription |
| 706 | |
| 707 | .. index:: |
| 708 | object: sequence |
| 709 | object: mapping |
| 710 | object: string |
| 711 | object: tuple |
| 712 | object: list |
| 713 | object: dictionary |
| 714 | pair: sequence; item |
| 715 | |
| 716 | A subscription selects an item of a sequence (string, tuple or list) or mapping |
| 717 | (dictionary) object: |
| 718 | |
| 719 | .. productionlist:: |
| 720 | subscription: `primary` "[" `expression_list` "]" |
| 721 | |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 722 | The primary must evaluate to an object that supports subscription (lists or |
| 723 | dictionaries for example). User-defined objects can support subscription by |
| 724 | defining a :meth:`__getitem__` method. |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 725 | |
| 726 | 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] | 727 | |
| 728 | If the primary is a mapping, the expression list must evaluate to an object |
| 729 | whose value is one of the keys of the mapping, and the subscription selects the |
| 730 | value in the mapping that corresponds to that key. (The expression list is a |
| 731 | tuple except if it has exactly one item.) |
| 732 | |
Raymond Hettinger | f77c1d6 | 2010-09-15 00:09:26 +0000 | [diff] [blame] | 733 | If the primary is a sequence, the expression (list) must evaluate to an integer |
| 734 | or a slice (as discussed in the following section). |
| 735 | |
| 736 | The formal syntax makes no special provision for negative indices in |
| 737 | sequences; however, built-in sequences all provide a :meth:`__getitem__` |
| 738 | method that interprets negative indices by adding the length of the sequence |
| 739 | to the index (so that ``x[-1]`` selects the last item of ``x``). The |
| 740 | resulting value must be a nonnegative integer less than the number of items in |
| 741 | the sequence, and the subscription selects the item whose index is that value |
| 742 | (counting from zero). Since the support for negative indices and slicing |
| 743 | occurs in the object's :meth:`__getitem__` method, subclasses overriding |
| 744 | this method will need to explicitly add that support. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 745 | |
| 746 | .. index:: |
| 747 | single: character |
| 748 | pair: string; item |
| 749 | |
| 750 | A string's items are characters. A character is not a separate data type but a |
| 751 | string of exactly one character. |
| 752 | |
| 753 | |
| 754 | .. _slicings: |
| 755 | |
| 756 | Slicings |
| 757 | -------- |
| 758 | |
| 759 | .. index:: |
| 760 | single: slicing |
| 761 | single: slice |
| 762 | |
| 763 | .. index:: |
| 764 | object: sequence |
| 765 | object: string |
| 766 | object: tuple |
| 767 | object: list |
| 768 | |
| 769 | A slicing selects a range of items in a sequence object (e.g., a string, tuple |
| 770 | or list). Slicings may be used as expressions or as targets in assignment or |
| 771 | :keyword:`del` statements. The syntax for a slicing: |
| 772 | |
| 773 | .. productionlist:: |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 774 | slicing: `primary` "[" `slice_list` "]" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 775 | slice_list: `slice_item` ("," `slice_item`)* [","] |
Georg Brandl | cb8ecb1 | 2007-09-04 06:35:14 +0000 | [diff] [blame] | 776 | slice_item: `expression` | `proper_slice` |
Thomas Wouters | 53de190 | 2007-09-04 09:03:59 +0000 | [diff] [blame] | 777 | proper_slice: [`lower_bound`] ":" [`upper_bound`] [ ":" [`stride`] ] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 778 | lower_bound: `expression` |
| 779 | upper_bound: `expression` |
| 780 | stride: `expression` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 781 | |
| 782 | There is ambiguity in the formal syntax here: anything that looks like an |
| 783 | expression list also looks like a slice list, so any subscription can be |
| 784 | interpreted as a slicing. Rather than further complicating the syntax, this is |
| 785 | disambiguated by defining that in this case the interpretation as a subscription |
| 786 | 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] | 787 | slice list contains no proper slice). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 788 | |
| 789 | .. index:: |
| 790 | single: start (slice object attribute) |
| 791 | single: stop (slice object attribute) |
| 792 | single: step (slice object attribute) |
| 793 | |
Georg Brandl | a4c8c47 | 2014-10-31 10:38:49 +0100 | [diff] [blame] | 794 | The semantics for a slicing are as follows. The primary is indexed (using the |
| 795 | same :meth:`__getitem__` method as |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 796 | normal subscription) with a key that is constructed from the slice list, as |
| 797 | follows. If the slice list contains at least one comma, the key is a tuple |
| 798 | containing the conversion of the slice items; otherwise, the conversion of the |
| 799 | lone slice item is the key. The conversion of a slice item that is an |
| 800 | expression is that expression. The conversion of a proper slice is a slice |
Serhiy Storchaka | 0d196ed | 2013-10-09 14:02:31 +0300 | [diff] [blame] | 801 | object (see section :ref:`types`) whose :attr:`~slice.start`, |
| 802 | :attr:`~slice.stop` and :attr:`~slice.step` attributes are the values of the |
| 803 | expressions given as lower bound, upper bound and stride, respectively, |
| 804 | substituting ``None`` for missing expressions. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 805 | |
| 806 | |
Chris Jerdonek | b430994 | 2012-12-25 14:54:44 -0800 | [diff] [blame] | 807 | .. index:: |
| 808 | object: callable |
| 809 | single: call |
| 810 | single: argument; call semantics |
| 811 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 812 | .. _calls: |
| 813 | |
| 814 | Calls |
| 815 | ----- |
| 816 | |
Chris Jerdonek | b430994 | 2012-12-25 14:54:44 -0800 | [diff] [blame] | 817 | A call calls a callable object (e.g., a :term:`function`) with a possibly empty |
| 818 | series of :term:`arguments <argument>`: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 819 | |
| 820 | .. productionlist:: |
Georg Brandl | dc529c1 | 2008-09-21 17:03:29 +0000 | [diff] [blame] | 821 | call: `primary` "(" [`argument_list` [","] | `comprehension`] ")" |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 822 | argument_list: `positional_arguments` ["," `starred_and_keywords`] |
| 823 | : ["," `keywords_arguments`] |
| 824 | : | `starred_and_keywords` ["," `keywords_arguments`] |
| 825 | : | `keywords_arguments` |
| 826 | positional_arguments: ["*"] `expression` ("," ["*"] `expression`)* |
| 827 | starred_and_keywords: ("*" `expression` | `keyword_item`) |
| 828 | : ("," "*" `expression` | "," `keyword_item`)* |
| 829 | keywords_arguments: (`keyword_item` | "**" `expression`) |
Martin Panter | 7106a51 | 2016-12-24 10:20:38 +0000 | [diff] [blame] | 830 | : ("," `keyword_item` | "," "**" `expression`)* |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 831 | keyword_item: `identifier` "=" `expression` |
| 832 | |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 833 | An optional trailing comma may be present after the positional and keyword arguments |
| 834 | but does not affect the semantics. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 835 | |
Chris Jerdonek | b430994 | 2012-12-25 14:54:44 -0800 | [diff] [blame] | 836 | .. index:: |
| 837 | single: parameter; call semantics |
| 838 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 839 | The primary must evaluate to a callable object (user-defined functions, built-in |
| 840 | functions, methods of built-in objects, class objects, methods of class |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 841 | instances, and all objects having a :meth:`__call__` method are callable). All |
| 842 | argument expressions are evaluated before the call is attempted. Please refer |
Chris Jerdonek | b430994 | 2012-12-25 14:54:44 -0800 | [diff] [blame] | 843 | to section :ref:`function` for the syntax of formal :term:`parameter` lists. |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 844 | |
| 845 | .. XXX update with kwonly args PEP |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 846 | |
| 847 | If keyword arguments are present, they are first converted to positional |
| 848 | arguments, as follows. First, a list of unfilled slots is created for the |
| 849 | formal parameters. If there are N positional arguments, they are placed in the |
| 850 | first N slots. Next, for each keyword argument, the identifier is used to |
| 851 | determine the corresponding slot (if the identifier is the same as the first |
| 852 | formal parameter name, the first slot is used, and so on). If the slot is |
| 853 | already filled, a :exc:`TypeError` exception is raised. Otherwise, the value of |
| 854 | the argument is placed in the slot, filling it (even if the expression is |
| 855 | ``None``, it fills the slot). When all arguments have been processed, the slots |
| 856 | that are still unfilled are filled with the corresponding default value from the |
| 857 | function definition. (Default values are calculated, once, when the function is |
| 858 | defined; thus, a mutable object such as a list or dictionary used as default |
| 859 | value will be shared by all calls that don't specify an argument value for the |
| 860 | corresponding slot; this should usually be avoided.) If there are any unfilled |
| 861 | slots for which no default value is specified, a :exc:`TypeError` exception is |
| 862 | raised. Otherwise, the list of filled slots is used as the argument list for |
| 863 | the call. |
| 864 | |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 865 | .. impl-detail:: |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 866 | |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 867 | An implementation may provide built-in functions whose positional parameters |
| 868 | do not have names, even if they are 'named' for the purpose of documentation, |
| 869 | and which therefore cannot be supplied by keyword. In CPython, this is the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 870 | case for functions implemented in C that use :c:func:`PyArg_ParseTuple` to |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 871 | parse their arguments. |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 872 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 873 | If there are more positional arguments than there are formal parameter slots, a |
| 874 | :exc:`TypeError` exception is raised, unless a formal parameter using the syntax |
| 875 | ``*identifier`` is present; in this case, that formal parameter receives a tuple |
| 876 | containing the excess positional arguments (or an empty tuple if there were no |
| 877 | excess positional arguments). |
| 878 | |
| 879 | If any keyword argument does not correspond to a formal parameter name, a |
| 880 | :exc:`TypeError` exception is raised, unless a formal parameter using the syntax |
| 881 | ``**identifier`` is present; in this case, that formal parameter receives a |
| 882 | dictionary containing the excess keyword arguments (using the keywords as keys |
| 883 | and the argument values as corresponding values), or a (new) empty dictionary if |
| 884 | there were no excess keyword arguments. |
| 885 | |
Eli Bendersky | 7bd081c | 2011-07-30 07:05:16 +0300 | [diff] [blame] | 886 | .. index:: |
| 887 | single: *; in function calls |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 888 | single: unpacking; in function calls |
Eli Bendersky | 7bd081c | 2011-07-30 07:05:16 +0300 | [diff] [blame] | 889 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 890 | If the syntax ``*expression`` appears in the function call, ``expression`` must |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 891 | evaluate to an :term:`iterable`. Elements from these iterables are |
| 892 | treated as if they were additional positional arguments. For the call |
| 893 | ``f(x1, x2, *y, x3, x4)``, if *y* evaluates to a sequence *y1*, ..., *yM*, |
| 894 | this is equivalent to a call with M+4 positional arguments *x1*, *x2*, |
| 895 | *y1*, ..., *yM*, *x3*, *x4*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 896 | |
Benjamin Peterson | 2d735bc | 2008-08-19 20:57:10 +0000 | [diff] [blame] | 897 | A consequence of this is that although the ``*expression`` syntax may appear |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 898 | *after* explicit keyword arguments, it is processed *before* the |
| 899 | keyword arguments (and any ``**expression`` arguments -- see below). So:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 900 | |
| 901 | >>> def f(a, b): |
Serhiy Storchaka | dba9039 | 2016-05-10 12:01:23 +0300 | [diff] [blame] | 902 | ... print(a, b) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 903 | ... |
| 904 | >>> f(b=1, *(2,)) |
| 905 | 2 1 |
| 906 | >>> f(a=1, *(2,)) |
| 907 | Traceback (most recent call last): |
| 908 | File "<stdin>", line 1, in ? |
| 909 | TypeError: f() got multiple values for keyword argument 'a' |
| 910 | >>> f(1, *(2,)) |
| 911 | 1 2 |
| 912 | |
| 913 | It is unusual for both keyword arguments and the ``*expression`` syntax to be |
| 914 | used in the same call, so in practice this confusion does not arise. |
| 915 | |
Eli Bendersky | 7bd081c | 2011-07-30 07:05:16 +0300 | [diff] [blame] | 916 | .. index:: |
| 917 | single: **; in function calls |
| 918 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 919 | If the syntax ``**expression`` appears in the function call, ``expression`` must |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 920 | evaluate to a :term:`mapping`, the contents of which are treated as |
| 921 | additional keyword arguments. If a keyword is already present |
| 922 | (as an explicit keyword argument, or from another unpacking), |
| 923 | a :exc:`TypeError` exception is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 924 | |
| 925 | Formal parameters using the syntax ``*identifier`` or ``**identifier`` cannot be |
| 926 | used as positional argument slots or as keyword argument names. |
| 927 | |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 928 | .. versionchanged:: 3.5 |
| 929 | Function calls accept any number of ``*`` and ``**`` unpackings, |
| 930 | positional arguments may follow iterable unpackings (``*``), |
| 931 | and keyword arguments may follow dictionary unpackings (``**``). |
| 932 | Originally proposed by :pep:`448`. |
| 933 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 934 | A call always returns some value, possibly ``None``, unless it raises an |
| 935 | exception. How this value is computed depends on the type of the callable |
| 936 | object. |
| 937 | |
| 938 | If it is--- |
| 939 | |
| 940 | a user-defined function: |
| 941 | .. index:: |
| 942 | pair: function; call |
| 943 | triple: user-defined; function; call |
| 944 | object: user-defined function |
| 945 | object: function |
| 946 | |
| 947 | The code block for the function is executed, passing it the argument list. The |
| 948 | first thing the code block will do is bind the formal parameters to the |
| 949 | arguments; this is described in section :ref:`function`. When the code block |
| 950 | executes a :keyword:`return` statement, this specifies the return value of the |
| 951 | function call. |
| 952 | |
| 953 | a built-in function or method: |
| 954 | .. index:: |
| 955 | pair: function; call |
| 956 | pair: built-in function; call |
| 957 | pair: method; call |
| 958 | pair: built-in method; call |
| 959 | object: built-in method |
| 960 | object: built-in function |
| 961 | object: method |
| 962 | object: function |
| 963 | |
| 964 | The result is up to the interpreter; see :ref:`built-in-funcs` for the |
| 965 | descriptions of built-in functions and methods. |
| 966 | |
| 967 | a class object: |
| 968 | .. index:: |
| 969 | object: class |
| 970 | pair: class object; call |
| 971 | |
| 972 | A new instance of that class is returned. |
| 973 | |
| 974 | a class instance method: |
| 975 | .. index:: |
| 976 | object: class instance |
| 977 | object: instance |
| 978 | pair: class instance; call |
| 979 | |
| 980 | The corresponding user-defined function is called, with an argument list that is |
| 981 | one longer than the argument list of the call: the instance becomes the first |
| 982 | argument. |
| 983 | |
| 984 | a class instance: |
| 985 | .. index:: |
| 986 | pair: instance; call |
| 987 | single: __call__() (object method) |
| 988 | |
| 989 | The class must define a :meth:`__call__` method; the effect is then the same as |
| 990 | if that method was called. |
| 991 | |
| 992 | |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 993 | .. _await: |
| 994 | |
| 995 | Await expression |
| 996 | ================ |
| 997 | |
| 998 | Suspend the execution of :term:`coroutine` on an :term:`awaitable` object. |
| 999 | Can only be used inside a :term:`coroutine function`. |
| 1000 | |
| 1001 | .. productionlist:: |
Serhiy Storchaka | c7cc985 | 2016-05-08 21:59:46 +0300 | [diff] [blame] | 1002 | await_expr: "await" `primary` |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 1003 | |
| 1004 | .. versionadded:: 3.5 |
| 1005 | |
| 1006 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1007 | .. _power: |
| 1008 | |
| 1009 | The power operator |
| 1010 | ================== |
| 1011 | |
| 1012 | The power operator binds more tightly than unary operators on its left; it binds |
| 1013 | less tightly than unary operators on its right. The syntax is: |
| 1014 | |
| 1015 | .. productionlist:: |
Serhiy Storchaka | c7cc985 | 2016-05-08 21:59:46 +0300 | [diff] [blame] | 1016 | power: ( `await_expr` | `primary` ) ["**" `u_expr`] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1017 | |
| 1018 | Thus, in an unparenthesized sequence of power and unary operators, the operators |
| 1019 | 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] | 1020 | for the operands): ``-1**2`` results in ``-1``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1021 | |
| 1022 | The power operator has the same semantics as the built-in :func:`pow` function, |
| 1023 | when called with two arguments: it yields its left argument raised to the power |
| 1024 | 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] | 1025 | type, and the result is of that type. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1026 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1027 | For int operands, the result has the same type as the operands unless the second |
| 1028 | argument is negative; in that case, all arguments are converted to float and a |
| 1029 | float result is delivered. For example, ``10**2`` returns ``100``, but |
| 1030 | ``10**-2`` returns ``0.01``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1031 | |
| 1032 | Raising ``0.0`` to a negative power results in a :exc:`ZeroDivisionError`. |
Christian Heimes | 072c0f1 | 2008-01-03 23:01:04 +0000 | [diff] [blame] | 1033 | 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] | 1034 | number. (In earlier versions it raised a :exc:`ValueError`.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1035 | |
| 1036 | |
| 1037 | .. _unary: |
| 1038 | |
Benjamin Peterson | ba01dd9 | 2009-02-20 04:02:38 +0000 | [diff] [blame] | 1039 | Unary arithmetic and bitwise operations |
| 1040 | ======================================= |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1041 | |
| 1042 | .. index:: |
| 1043 | triple: unary; arithmetic; operation |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 1044 | triple: unary; bitwise; operation |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1045 | |
Benjamin Peterson | ba01dd9 | 2009-02-20 04:02:38 +0000 | [diff] [blame] | 1046 | All unary arithmetic and bitwise operations have the same priority: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1047 | |
| 1048 | .. productionlist:: |
| 1049 | u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr` |
| 1050 | |
| 1051 | .. index:: |
| 1052 | single: negation |
| 1053 | single: minus |
| 1054 | |
| 1055 | The unary ``-`` (minus) operator yields the negation of its numeric argument. |
| 1056 | |
| 1057 | .. index:: single: plus |
| 1058 | |
| 1059 | The unary ``+`` (plus) operator yields its numeric argument unchanged. |
| 1060 | |
| 1061 | .. index:: single: inversion |
| 1062 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 1063 | |
Georg Brandl | 95817b3 | 2008-05-11 14:30:18 +0000 | [diff] [blame] | 1064 | The unary ``~`` (invert) operator yields the bitwise inversion of its integer |
| 1065 | argument. The bitwise inversion of ``x`` is defined as ``-(x+1)``. It only |
| 1066 | applies to integral numbers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1067 | |
| 1068 | .. index:: exception: TypeError |
| 1069 | |
| 1070 | In all three cases, if the argument does not have the proper type, a |
| 1071 | :exc:`TypeError` exception is raised. |
| 1072 | |
| 1073 | |
| 1074 | .. _binary: |
| 1075 | |
| 1076 | Binary arithmetic operations |
| 1077 | ============================ |
| 1078 | |
| 1079 | .. index:: triple: binary; arithmetic; operation |
| 1080 | |
| 1081 | The binary arithmetic operations have the conventional priority levels. Note |
| 1082 | that some of these operations also apply to certain non-numeric types. Apart |
| 1083 | from the power operator, there are only two levels, one for multiplicative |
| 1084 | operators and one for additive operators: |
| 1085 | |
| 1086 | .. productionlist:: |
Benjamin Peterson | d51374e | 2014-04-09 23:55:56 -0400 | [diff] [blame] | 1087 | m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "@" `m_expr` | |
| 1088 | : `m_expr` "//" `u_expr`| `m_expr` "/" `u_expr` | |
| 1089 | : `m_expr` "%" `u_expr` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1090 | a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr` |
| 1091 | |
| 1092 | .. index:: single: multiplication |
| 1093 | |
| 1094 | The ``*`` (multiplication) operator yields the product of its arguments. The |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1095 | arguments must either both be numbers, or one argument must be an integer and |
| 1096 | the other must be a sequence. In the former case, the numbers are converted to a |
| 1097 | common type and then multiplied together. In the latter case, sequence |
| 1098 | repetition is performed; a negative repetition factor yields an empty sequence. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1099 | |
Benjamin Peterson | d51374e | 2014-04-09 23:55:56 -0400 | [diff] [blame] | 1100 | .. index:: single: matrix multiplication |
| 1101 | |
| 1102 | The ``@`` (at) operator is intended to be used for matrix multiplication. No |
| 1103 | builtin Python types implement this operator. |
| 1104 | |
| 1105 | .. versionadded:: 3.5 |
| 1106 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1107 | .. index:: |
| 1108 | exception: ZeroDivisionError |
| 1109 | single: division |
| 1110 | |
| 1111 | The ``/`` (division) and ``//`` (floor division) operators yield the quotient of |
| 1112 | their arguments. The numeric arguments are first converted to a common type. |
Georg Brandl | 0aaae26 | 2013-10-08 21:47:18 +0200 | [diff] [blame] | 1113 | Division of integers yields a float, while floor division of integers results in an |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1114 | integer; the result is that of mathematical division with the 'floor' function |
| 1115 | applied to the result. Division by zero raises the :exc:`ZeroDivisionError` |
| 1116 | exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1117 | |
| 1118 | .. index:: single: modulo |
| 1119 | |
| 1120 | The ``%`` (modulo) operator yields the remainder from the division of the first |
| 1121 | argument by the second. The numeric arguments are first converted to a common |
| 1122 | type. A zero right argument raises the :exc:`ZeroDivisionError` exception. The |
| 1123 | arguments may be floating point numbers, e.g., ``3.14%0.7`` equals ``0.34`` |
| 1124 | (since ``3.14`` equals ``4*0.7 + 0.34``.) The modulo operator always yields a |
| 1125 | result with the same sign as its second operand (or zero); the absolute value of |
| 1126 | the result is strictly smaller than the absolute value of the second operand |
| 1127 | [#]_. |
| 1128 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1129 | The floor division and modulo operators are connected by the following |
| 1130 | identity: ``x == (x//y)*y + (x%y)``. Floor division and modulo are also |
| 1131 | connected with the built-in function :func:`divmod`: ``divmod(x, y) == (x//y, |
| 1132 | x%y)``. [#]_. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1133 | |
| 1134 | In addition to performing the modulo operation on numbers, the ``%`` operator is |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1135 | also overloaded by string objects to perform old-style string formatting (also |
| 1136 | known as interpolation). The syntax for string formatting is described in the |
Georg Brandl | 4b49131 | 2007-08-31 09:22:56 +0000 | [diff] [blame] | 1137 | Python Library Reference, section :ref:`old-string-formatting`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1138 | |
| 1139 | The floor division operator, the modulo operator, and the :func:`divmod` |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1140 | function are not defined for complex numbers. Instead, convert to a floating |
| 1141 | point number using the :func:`abs` function if appropriate. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1142 | |
| 1143 | .. index:: single: addition |
| 1144 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1145 | The ``+`` (addition) operator yields the sum of its arguments. The arguments |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 1146 | must either both be numbers or both be sequences of the same type. In the |
| 1147 | former case, the numbers are converted to a common type and then added together. |
| 1148 | In the latter case, the sequences are concatenated. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1149 | |
| 1150 | .. index:: single: subtraction |
| 1151 | |
| 1152 | The ``-`` (subtraction) operator yields the difference of its arguments. The |
| 1153 | numeric arguments are first converted to a common type. |
| 1154 | |
| 1155 | |
| 1156 | .. _shifting: |
| 1157 | |
| 1158 | Shifting operations |
| 1159 | =================== |
| 1160 | |
| 1161 | .. index:: pair: shifting; operation |
| 1162 | |
| 1163 | The shifting operations have lower priority than the arithmetic operations: |
| 1164 | |
| 1165 | .. productionlist:: |
| 1166 | shift_expr: `a_expr` | `shift_expr` ( "<<" | ">>" ) `a_expr` |
| 1167 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1168 | These operators accept integers as arguments. They shift the first argument to |
| 1169 | 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] | 1170 | |
| 1171 | .. index:: exception: ValueError |
| 1172 | |
Georg Brandl | 0aaae26 | 2013-10-08 21:47:18 +0200 | [diff] [blame] | 1173 | A right shift by *n* bits is defined as floor division by ``pow(2,n)``. A left |
| 1174 | shift by *n* bits is defined as multiplication with ``pow(2,n)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1175 | |
Benjamin Peterson | 08bf91c | 2010-04-11 16:12:57 +0000 | [diff] [blame] | 1176 | .. note:: |
| 1177 | |
| 1178 | In the current implementation, the right-hand operand is required |
Mark Dickinson | 505add3 | 2010-04-06 18:22:06 +0000 | [diff] [blame] | 1179 | to be at most :attr:`sys.maxsize`. If the right-hand operand is larger than |
| 1180 | :attr:`sys.maxsize` an :exc:`OverflowError` exception is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1181 | |
| 1182 | .. _bitwise: |
| 1183 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 1184 | Binary bitwise operations |
| 1185 | ========================= |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1186 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 1187 | .. index:: triple: binary; bitwise; operation |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1188 | |
| 1189 | Each of the three bitwise operations has a different priority level: |
| 1190 | |
| 1191 | .. productionlist:: |
| 1192 | and_expr: `shift_expr` | `and_expr` "&" `shift_expr` |
| 1193 | xor_expr: `and_expr` | `xor_expr` "^" `and_expr` |
| 1194 | or_expr: `xor_expr` | `or_expr` "|" `xor_expr` |
| 1195 | |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 1196 | .. index:: pair: bitwise; and |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1197 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1198 | The ``&`` operator yields the bitwise AND of its arguments, which must be |
| 1199 | integers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1200 | |
| 1201 | .. index:: |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 1202 | pair: bitwise; xor |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1203 | pair: exclusive; or |
| 1204 | |
| 1205 | The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1206 | must be integers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1207 | |
| 1208 | .. index:: |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 1209 | pair: bitwise; or |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1210 | pair: inclusive; or |
| 1211 | |
| 1212 | The ``|`` operator yields the bitwise (inclusive) OR of its arguments, which |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1213 | must be integers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1214 | |
| 1215 | |
| 1216 | .. _comparisons: |
| 1217 | |
| 1218 | Comparisons |
| 1219 | =========== |
| 1220 | |
| 1221 | .. index:: single: comparison |
| 1222 | |
| 1223 | .. index:: pair: C; language |
| 1224 | |
| 1225 | Unlike C, all comparison operations in Python have the same priority, which is |
| 1226 | lower than that of any arithmetic, shifting or bitwise operation. Also unlike |
| 1227 | C, expressions like ``a < b < c`` have the interpretation that is conventional |
| 1228 | in mathematics: |
| 1229 | |
| 1230 | .. productionlist:: |
| 1231 | comparison: `or_expr` ( `comp_operator` `or_expr` )* |
| 1232 | comp_operator: "<" | ">" | "==" | ">=" | "<=" | "!=" |
| 1233 | : | "is" ["not"] | ["not"] "in" |
| 1234 | |
| 1235 | Comparisons yield boolean values: ``True`` or ``False``. |
| 1236 | |
| 1237 | .. index:: pair: chaining; comparisons |
| 1238 | |
| 1239 | Comparisons can be chained arbitrarily, e.g., ``x < y <= z`` is equivalent to |
| 1240 | ``x < y and y <= z``, except that ``y`` is evaluated only once (but in both |
| 1241 | cases ``z`` is not evaluated at all when ``x < y`` is found to be false). |
| 1242 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 1243 | Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and *op1*, *op2*, ..., |
| 1244 | *opN* are comparison operators, then ``a op1 b op2 c ... y opN z`` is equivalent |
| 1245 | to ``a op1 b and b op2 c and ... y opN z``, except that each expression is |
| 1246 | evaluated at most once. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1247 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 1248 | 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] | 1249 | *c*, so that, e.g., ``x < y > z`` is perfectly legal (though perhaps not |
| 1250 | pretty). |
| 1251 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1252 | Value comparisons |
| 1253 | ----------------- |
| 1254 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1255 | The operators ``<``, ``>``, ``==``, ``>=``, ``<=``, and ``!=`` compare the |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1256 | values of two objects. The objects do not need to have the same type. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1257 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1258 | Chapter :ref:`objects` states that objects have a value (in addition to type |
| 1259 | and identity). The value of an object is a rather abstract notion in Python: |
| 1260 | For example, there is no canonical access method for an object's value. Also, |
| 1261 | there is no requirement that the value of an object should be constructed in a |
| 1262 | particular way, e.g. comprised of all its data attributes. Comparison operators |
| 1263 | implement a particular notion of what the value of an object is. One can think |
| 1264 | of them as defining the value of an object indirectly, by means of their |
| 1265 | comparison implementation. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1266 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1267 | Because all types are (direct or indirect) subtypes of :class:`object`, they |
| 1268 | inherit the default comparison behavior from :class:`object`. Types can |
| 1269 | customize their comparison behavior by implementing |
| 1270 | :dfn:`rich comparison methods` like :meth:`__lt__`, described in |
| 1271 | :ref:`customization`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1272 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1273 | The default behavior for equality comparison (``==`` and ``!=``) is based on |
| 1274 | the identity of the objects. Hence, equality comparison of instances with the |
| 1275 | same identity results in equality, and equality comparison of instances with |
| 1276 | different identities results in inequality. A motivation for this default |
| 1277 | behavior is the desire that all objects should be reflexive (i.e. ``x is y`` |
| 1278 | implies ``x == y``). |
| 1279 | |
| 1280 | A default order comparison (``<``, ``>``, ``<=``, and ``>=``) is not provided; |
| 1281 | an attempt raises :exc:`TypeError`. A motivation for this default behavior is |
| 1282 | the lack of a similar invariant as for equality. |
| 1283 | |
| 1284 | The behavior of the default equality comparison, that instances with different |
| 1285 | identities are always unequal, may be in contrast to what types will need that |
| 1286 | have a sensible definition of object value and value-based equality. Such |
| 1287 | types will need to customize their comparison behavior, and in fact, a number |
| 1288 | of built-in types have done that. |
| 1289 | |
| 1290 | The following list describes the comparison behavior of the most important |
| 1291 | built-in types. |
| 1292 | |
| 1293 | * Numbers of built-in numeric types (:ref:`typesnumeric`) and of the standard |
| 1294 | library types :class:`fractions.Fraction` and :class:`decimal.Decimal` can be |
| 1295 | compared within and across their types, with the restriction that complex |
| 1296 | numbers do not support order comparison. Within the limits of the types |
| 1297 | involved, they compare mathematically (algorithmically) correct without loss |
| 1298 | of precision. |
| 1299 | |
| 1300 | The not-a-number values :const:`float('NaN')` and :const:`Decimal('NaN')` |
| 1301 | are special. They are identical to themselves (``x is x`` is true) but |
| 1302 | are not equal to themselves (``x == x`` is false). Additionally, |
| 1303 | comparing any number to a not-a-number value |
Raymond Hettinger | a2a08fb | 2008-11-17 22:55:16 +0000 | [diff] [blame] | 1304 | will return ``False``. For example, both ``3 < float('NaN')`` and |
| 1305 | ``float('NaN') < 3`` will return ``False``. |
| 1306 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1307 | * Binary sequences (instances of :class:`bytes` or :class:`bytearray`) can be |
| 1308 | compared within and across their types. They compare lexicographically using |
| 1309 | the numeric values of their elements. |
Georg Brandl | 4b49131 | 2007-08-31 09:22:56 +0000 | [diff] [blame] | 1310 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1311 | * Strings (instances of :class:`str`) compare lexicographically using the |
| 1312 | numerical Unicode code points (the result of the built-in function |
| 1313 | :func:`ord`) of their characters. [#]_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1314 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1315 | Strings and binary sequences cannot be directly compared. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1316 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1317 | * Sequences (instances of :class:`tuple`, :class:`list`, or :class:`range`) can |
| 1318 | be compared only within each of their types, with the restriction that ranges |
| 1319 | do not support order comparison. Equality comparison across these types |
Mariatta | f28db60 | 2017-02-24 16:39:30 -0800 | [diff] [blame^] | 1320 | results in inequality, and ordering comparison across these types raises |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1321 | :exc:`TypeError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1322 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1323 | Sequences compare lexicographically using comparison of corresponding |
| 1324 | elements, whereby reflexivity of the elements is enforced. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1325 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1326 | In enforcing reflexivity of elements, the comparison of collections assumes |
| 1327 | that for a collection element ``x``, ``x == x`` is always true. Based on |
| 1328 | that assumption, element identity is compared first, and element comparison |
| 1329 | is performed only for distinct elements. This approach yields the same |
| 1330 | result as a strict element comparison would, if the compared elements are |
| 1331 | reflexive. For non-reflexive elements, the result is different than for |
| 1332 | strict element comparison, and may be surprising: The non-reflexive |
| 1333 | not-a-number values for example result in the following comparison behavior |
| 1334 | when used in a list:: |
| 1335 | |
| 1336 | >>> nan = float('NaN') |
| 1337 | >>> nan is nan |
| 1338 | True |
| 1339 | >>> nan == nan |
| 1340 | False <-- the defined non-reflexive behavior of NaN |
| 1341 | >>> [nan] == [nan] |
| 1342 | True <-- list enforces reflexivity and tests identity first |
| 1343 | |
| 1344 | Lexicographical comparison between built-in collections works as follows: |
| 1345 | |
| 1346 | - For two collections to compare equal, they must be of the same type, have |
| 1347 | the same length, and each pair of corresponding elements must compare |
| 1348 | equal (for example, ``[1,2] == (1,2)`` is false because the type is not the |
| 1349 | same). |
| 1350 | |
| 1351 | - Collections that support order comparison are ordered the same as their |
| 1352 | first unequal elements (for example, ``[1,2,x] <= [1,2,y]`` has the same |
| 1353 | value as ``x <= y``). If a corresponding element does not exist, the |
| 1354 | shorter collection is ordered first (for example, ``[1,2] < [1,2,3]`` is |
| 1355 | true). |
| 1356 | |
| 1357 | * Mappings (instances of :class:`dict`) compare equal if and only if they have |
| 1358 | equal `(key, value)` pairs. Equality comparison of the keys and elements |
| 1359 | enforces reflexivity. |
| 1360 | |
| 1361 | Order comparisons (``<``, ``>``, ``<=``, and ``>=``) raise :exc:`TypeError`. |
| 1362 | |
| 1363 | * Sets (instances of :class:`set` or :class:`frozenset`) can be compared within |
| 1364 | and across their types. |
| 1365 | |
| 1366 | They define order |
| 1367 | comparison operators to mean subset and superset tests. Those relations do |
| 1368 | not define total orderings (for example, the two sets ``{1,2}`` and ``{2,3}`` |
| 1369 | are not equal, nor subsets of one another, nor supersets of one |
Raymond Hettinger | a2a08fb | 2008-11-17 22:55:16 +0000 | [diff] [blame] | 1370 | another). Accordingly, sets are not appropriate arguments for functions |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1371 | which depend on total ordering (for example, :func:`min`, :func:`max`, and |
| 1372 | :func:`sorted` produce undefined results given a list of sets as inputs). |
Raymond Hettinger | a2a08fb | 2008-11-17 22:55:16 +0000 | [diff] [blame] | 1373 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1374 | Comparison of sets enforces reflexivity of its elements. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1375 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1376 | * Most other built-in types have no comparison methods implemented, so they |
| 1377 | inherit the default comparison behavior. |
Raymond Hettinger | a2a08fb | 2008-11-17 22:55:16 +0000 | [diff] [blame] | 1378 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1379 | User-defined classes that customize their comparison behavior should follow |
| 1380 | some consistency rules, if possible: |
| 1381 | |
| 1382 | * Equality comparison should be reflexive. |
| 1383 | In other words, identical objects should compare equal: |
| 1384 | |
| 1385 | ``x is y`` implies ``x == y`` |
| 1386 | |
| 1387 | * Comparison should be symmetric. |
| 1388 | In other words, the following expressions should have the same result: |
| 1389 | |
| 1390 | ``x == y`` and ``y == x`` |
| 1391 | |
| 1392 | ``x != y`` and ``y != x`` |
| 1393 | |
| 1394 | ``x < y`` and ``y > x`` |
| 1395 | |
| 1396 | ``x <= y`` and ``y >= x`` |
| 1397 | |
| 1398 | * Comparison should be transitive. |
| 1399 | The following (non-exhaustive) examples illustrate that: |
| 1400 | |
| 1401 | ``x > y and y > z`` implies ``x > z`` |
| 1402 | |
| 1403 | ``x < y and y <= z`` implies ``x < z`` |
| 1404 | |
| 1405 | * Inverse comparison should result in the boolean negation. |
| 1406 | In other words, the following expressions should have the same result: |
| 1407 | |
| 1408 | ``x == y`` and ``not x != y`` |
| 1409 | |
| 1410 | ``x < y`` and ``not x >= y`` (for total ordering) |
| 1411 | |
| 1412 | ``x > y`` and ``not x <= y`` (for total ordering) |
| 1413 | |
| 1414 | The last two expressions apply to totally ordered collections (e.g. to |
| 1415 | sequences, but not to sets or mappings). See also the |
| 1416 | :func:`~functools.total_ordering` decorator. |
| 1417 | |
Martin Panter | 8dbb0ca | 2017-01-29 10:00:23 +0000 | [diff] [blame] | 1418 | * The :func:`hash` result should be consistent with equality. |
| 1419 | Objects that are equal should either have the same hash value, |
| 1420 | or be marked as unhashable. |
| 1421 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1422 | Python does not enforce these consistency rules. In fact, the not-a-number |
| 1423 | values are an example for not following these rules. |
| 1424 | |
| 1425 | |
| 1426 | .. _in: |
| 1427 | .. _not in: |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 1428 | .. _membership-test-details: |
| 1429 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1430 | Membership test operations |
| 1431 | -------------------------- |
| 1432 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1433 | The operators :keyword:`in` and :keyword:`not in` test for membership. ``x in |
| 1434 | s`` evaluates to true if *x* is a member of *s*, and false otherwise. ``x not |
| 1435 | in s`` returns the negation of ``x in s``. All built-in sequences and set types |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 1436 | support this as well as dictionary, for which :keyword:`in` tests whether the |
Raymond Hettinger | a2a08fb | 2008-11-17 22:55:16 +0000 | [diff] [blame] | 1437 | dictionary has a given key. For container types such as list, tuple, set, |
Raymond Hettinger | 0cc818f | 2008-11-21 10:40:51 +0000 | [diff] [blame] | 1438 | frozenset, dict, or collections.deque, the expression ``x in y`` is equivalent |
Stefan Krah | c8bdc01 | 2010-04-01 10:34:09 +0000 | [diff] [blame] | 1439 | to ``any(x is e or x == e for e in y)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1440 | |
Georg Brandl | 4b49131 | 2007-08-31 09:22:56 +0000 | [diff] [blame] | 1441 | For the string and bytes types, ``x in y`` is true if and only if *x* is a |
| 1442 | substring of *y*. An equivalent test is ``y.find(x) != -1``. Empty strings are |
| 1443 | always considered to be a substring of any other string, so ``"" in "abc"`` will |
| 1444 | return ``True``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1445 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1446 | For user-defined classes which define the :meth:`__contains__` method, ``x in |
| 1447 | y`` is true if and only if ``y.__contains__(x)`` is true. |
| 1448 | |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 1449 | For user-defined classes which do not define :meth:`__contains__` but do define |
| 1450 | :meth:`__iter__`, ``x in y`` is true if some value ``z`` with ``x == z`` is |
| 1451 | produced while iterating over ``y``. If an exception is raised during the |
| 1452 | iteration, it is as if :keyword:`in` raised that exception. |
| 1453 | |
| 1454 | Lastly, the old-style iteration protocol is tried: if a class defines |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1455 | :meth:`__getitem__`, ``x in y`` is true if and only if there is a non-negative |
| 1456 | 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] | 1457 | 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] | 1458 | if :keyword:`in` raised that exception). |
| 1459 | |
| 1460 | .. index:: |
| 1461 | operator: in |
| 1462 | operator: not in |
| 1463 | pair: membership; test |
| 1464 | object: sequence |
| 1465 | |
| 1466 | The operator :keyword:`not in` is defined to have the inverse true value of |
| 1467 | :keyword:`in`. |
| 1468 | |
| 1469 | .. index:: |
| 1470 | operator: is |
| 1471 | operator: is not |
| 1472 | pair: identity; test |
| 1473 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1474 | |
| 1475 | .. _is: |
| 1476 | .. _is not: |
| 1477 | |
| 1478 | Identity comparisons |
| 1479 | -------------------- |
| 1480 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1481 | The operators :keyword:`is` and :keyword:`is not` test for object identity: ``x |
Raymond Hettinger | 06e18a7 | 2016-09-11 17:23:49 -0700 | [diff] [blame] | 1482 | is y`` is true if and only if *x* and *y* are the same object. Object identity |
| 1483 | is determined using the :meth:`id` function. ``x is not y`` yields the inverse |
| 1484 | truth value. [#]_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1485 | |
| 1486 | |
| 1487 | .. _booleans: |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 1488 | .. _and: |
| 1489 | .. _or: |
| 1490 | .. _not: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1491 | |
| 1492 | Boolean operations |
| 1493 | ================== |
| 1494 | |
| 1495 | .. index:: |
| 1496 | pair: Conditional; expression |
| 1497 | pair: Boolean; operation |
| 1498 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1499 | .. productionlist:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1500 | or_test: `and_test` | `or_test` "or" `and_test` |
| 1501 | and_test: `not_test` | `and_test` "and" `not_test` |
| 1502 | not_test: `comparison` | "not" `not_test` |
| 1503 | |
| 1504 | In the context of Boolean operations, and also when expressions are used by |
| 1505 | control flow statements, the following values are interpreted as false: |
| 1506 | ``False``, ``None``, numeric zero of all types, and empty strings and containers |
| 1507 | (including strings, tuples, lists, dictionaries, sets and frozensets). All |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1508 | other values are interpreted as true. User-defined objects can customize their |
| 1509 | truth value by providing a :meth:`__bool__` method. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1510 | |
| 1511 | .. index:: operator: not |
| 1512 | |
| 1513 | The operator :keyword:`not` yields ``True`` if its argument is false, ``False`` |
| 1514 | otherwise. |
| 1515 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1516 | .. index:: operator: and |
| 1517 | |
| 1518 | The expression ``x and y`` first evaluates *x*; if *x* is false, its value is |
| 1519 | returned; otherwise, *y* is evaluated and the resulting value is returned. |
| 1520 | |
| 1521 | .. index:: operator: or |
| 1522 | |
| 1523 | The expression ``x or y`` first evaluates *x*; if *x* is true, its value is |
| 1524 | returned; otherwise, *y* is evaluated and the resulting value is returned. |
| 1525 | |
| 1526 | (Note that neither :keyword:`and` nor :keyword:`or` restrict the value and type |
| 1527 | they return to ``False`` and ``True``, but rather return the last evaluated |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1528 | 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] | 1529 | replaced by a default value if it is empty, the expression ``s or 'foo'`` yields |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 1530 | the desired value. Because :keyword:`not` has to create a new value, it |
| 1531 | returns a boolean value regardless of the type of its argument |
| 1532 | (for example, ``not 'foo'`` produces ``False`` rather than ``''``.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1533 | |
| 1534 | |
Alexander Belopolsky | 50ba19e | 2010-12-15 19:47:37 +0000 | [diff] [blame] | 1535 | Conditional expressions |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 1536 | ======================= |
| 1537 | |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 1538 | .. index:: |
| 1539 | pair: conditional; expression |
| 1540 | pair: ternary; operator |
| 1541 | |
| 1542 | .. productionlist:: |
| 1543 | conditional_expression: `or_test` ["if" `or_test` "else" `expression`] |
Georg Brandl | 242e6a0 | 2013-10-06 10:28:39 +0200 | [diff] [blame] | 1544 | expression: `conditional_expression` | `lambda_expr` |
| 1545 | expression_nocond: `or_test` | `lambda_expr_nocond` |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 1546 | |
| 1547 | Conditional expressions (sometimes called a "ternary operator") have the lowest |
| 1548 | priority of all Python operations. |
| 1549 | |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 1550 | The expression ``x if C else y`` first evaluates the condition, *C* rather than *x*. |
| 1551 | If *C* is true, *x* is evaluated and its value is returned; otherwise, *y* is |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 1552 | evaluated and its value is returned. |
| 1553 | |
| 1554 | See :pep:`308` for more details about conditional expressions. |
| 1555 | |
| 1556 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1557 | .. _lambdas: |
Georg Brandl | c4f8b24 | 2009-04-10 08:17:21 +0000 | [diff] [blame] | 1558 | .. _lambda: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1559 | |
| 1560 | Lambdas |
| 1561 | ======= |
| 1562 | |
| 1563 | .. index:: |
| 1564 | pair: lambda; expression |
| 1565 | pair: lambda; form |
| 1566 | pair: anonymous; function |
| 1567 | |
| 1568 | .. productionlist:: |
Georg Brandl | 242e6a0 | 2013-10-06 10:28:39 +0200 | [diff] [blame] | 1569 | lambda_expr: "lambda" [`parameter_list`]: `expression` |
| 1570 | lambda_expr_nocond: "lambda" [`parameter_list`]: `expression_nocond` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1571 | |
Zachary Ware | 2f78b84 | 2014-06-03 09:32:40 -0500 | [diff] [blame] | 1572 | Lambda expressions (sometimes called lambda forms) are used to create anonymous |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 1573 | functions. The expression ``lambda arguments: expression`` yields a function |
Martin Panter | 1050d2d | 2016-07-26 11:18:21 +0200 | [diff] [blame] | 1574 | object. The unnamed object behaves like a function object defined with: |
| 1575 | |
| 1576 | .. code-block:: none |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1577 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1578 | def <lambda>(arguments): |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1579 | return expression |
| 1580 | |
| 1581 | See section :ref:`function` for the syntax of parameter lists. Note that |
Georg Brandl | 242e6a0 | 2013-10-06 10:28:39 +0200 | [diff] [blame] | 1582 | functions created with lambda expressions cannot contain statements or |
| 1583 | annotations. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1584 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1585 | |
| 1586 | .. _exprlists: |
| 1587 | |
| 1588 | Expression lists |
| 1589 | ================ |
| 1590 | |
| 1591 | .. index:: pair: expression; list |
| 1592 | |
| 1593 | .. productionlist:: |
| 1594 | expression_list: `expression` ( "," `expression` )* [","] |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 1595 | starred_list: `starred_item` ( "," `starred_item` )* [","] |
| 1596 | starred_expression: `expression` | ( `starred_item` "," )* [`starred_item`] |
| 1597 | starred_item: `expression` | "*" `or_expr` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1598 | |
| 1599 | .. index:: object: tuple |
| 1600 | |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 1601 | Except when part of a list or set display, an expression list |
| 1602 | containing at least one comma yields a tuple. The length of |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1603 | the tuple is the number of expressions in the list. The expressions are |
| 1604 | evaluated from left to right. |
| 1605 | |
Martin Panter | 0c0da48 | 2016-06-12 01:46:50 +0000 | [diff] [blame] | 1606 | .. index:: |
| 1607 | pair: iterable; unpacking |
| 1608 | single: *; in expression lists |
| 1609 | |
| 1610 | An asterisk ``*`` denotes :dfn:`iterable unpacking`. Its operand must be |
| 1611 | an :term:`iterable`. The iterable is expanded into a sequence of items, |
| 1612 | which are included in the new tuple, list, or set, at the site of |
| 1613 | the unpacking. |
| 1614 | |
| 1615 | .. versionadded:: 3.5 |
| 1616 | Iterable unpacking in expression lists, originally proposed by :pep:`448`. |
| 1617 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1618 | .. index:: pair: trailing; comma |
| 1619 | |
| 1620 | The trailing comma is required only to create a single tuple (a.k.a. a |
| 1621 | *singleton*); it is optional in all other cases. A single expression without a |
| 1622 | trailing comma doesn't create a tuple, but rather yields the value of that |
| 1623 | expression. (To create an empty tuple, use an empty pair of parentheses: |
| 1624 | ``()``.) |
| 1625 | |
| 1626 | |
| 1627 | .. _evalorder: |
| 1628 | |
| 1629 | Evaluation order |
| 1630 | ================ |
| 1631 | |
| 1632 | .. index:: pair: evaluation; order |
| 1633 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1634 | Python evaluates expressions from left to right. Notice that while evaluating |
| 1635 | 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] | 1636 | |
| 1637 | In the following lines, expressions will be evaluated in the arithmetic order of |
| 1638 | their suffixes:: |
| 1639 | |
| 1640 | expr1, expr2, expr3, expr4 |
| 1641 | (expr1, expr2, expr3, expr4) |
| 1642 | {expr1: expr2, expr3: expr4} |
| 1643 | expr1 + expr2 * (expr3 - expr4) |
Georg Brandl | 734e268 | 2008-08-12 08:18:18 +0000 | [diff] [blame] | 1644 | expr1(expr2, expr3, *expr4, **expr5) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1645 | expr3, expr4 = expr1, expr2 |
| 1646 | |
| 1647 | |
| 1648 | .. _operator-summary: |
| 1649 | |
Ezio Melotti | 9f929bb | 2012-12-25 15:45:15 +0200 | [diff] [blame] | 1650 | Operator precedence |
| 1651 | =================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1652 | |
| 1653 | .. index:: pair: operator; precedence |
| 1654 | |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 1655 | The following table summarizes the operator precedence in Python, from lowest |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 1656 | precedence (least binding) to highest precedence (most binding). Operators in |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1657 | the same box have the same precedence. Unless the syntax is explicitly given, |
| 1658 | operators are binary. Operators in the same box group left to right (except for |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 1659 | exponentiation, which groups from right to left). |
| 1660 | |
| 1661 | Note that comparisons, membership tests, and identity tests, all have the same |
| 1662 | precedence and have a left-to-right chaining feature as described in the |
| 1663 | :ref:`comparisons` section. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1664 | |
Benjamin Peterson | ba01dd9 | 2009-02-20 04:02:38 +0000 | [diff] [blame] | 1665 | |
| 1666 | +-----------------------------------------------+-------------------------------------+ |
| 1667 | | Operator | Description | |
| 1668 | +===============================================+=====================================+ |
| 1669 | | :keyword:`lambda` | Lambda expression | |
| 1670 | +-----------------------------------------------+-------------------------------------+ |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 1671 | | :keyword:`if` -- :keyword:`else` | Conditional expression | |
| 1672 | +-----------------------------------------------+-------------------------------------+ |
Benjamin Peterson | ba01dd9 | 2009-02-20 04:02:38 +0000 | [diff] [blame] | 1673 | | :keyword:`or` | Boolean OR | |
| 1674 | +-----------------------------------------------+-------------------------------------+ |
| 1675 | | :keyword:`and` | Boolean AND | |
| 1676 | +-----------------------------------------------+-------------------------------------+ |
Ezio Melotti | 9f929bb | 2012-12-25 15:45:15 +0200 | [diff] [blame] | 1677 | | :keyword:`not` ``x`` | Boolean NOT | |
Benjamin Peterson | ba01dd9 | 2009-02-20 04:02:38 +0000 | [diff] [blame] | 1678 | +-----------------------------------------------+-------------------------------------+ |
Ezio Melotti | 9f929bb | 2012-12-25 15:45:15 +0200 | [diff] [blame] | 1679 | | :keyword:`in`, :keyword:`not in`, | Comparisons, including membership | |
Georg Brandl | 44ea77b | 2013-03-28 13:28:44 +0100 | [diff] [blame] | 1680 | | :keyword:`is`, :keyword:`is not`, ``<``, | tests and identity tests | |
Georg Brandl | a5ebc26 | 2009-06-03 07:26:22 +0000 | [diff] [blame] | 1681 | | ``<=``, ``>``, ``>=``, ``!=``, ``==`` | | |
Benjamin Peterson | ba01dd9 | 2009-02-20 04:02:38 +0000 | [diff] [blame] | 1682 | +-----------------------------------------------+-------------------------------------+ |
| 1683 | | ``|`` | Bitwise OR | |
| 1684 | +-----------------------------------------------+-------------------------------------+ |
| 1685 | | ``^`` | Bitwise XOR | |
| 1686 | +-----------------------------------------------+-------------------------------------+ |
| 1687 | | ``&`` | Bitwise AND | |
| 1688 | +-----------------------------------------------+-------------------------------------+ |
| 1689 | | ``<<``, ``>>`` | Shifts | |
| 1690 | +-----------------------------------------------+-------------------------------------+ |
| 1691 | | ``+``, ``-`` | Addition and subtraction | |
| 1692 | +-----------------------------------------------+-------------------------------------+ |
Benjamin Peterson | d51374e | 2014-04-09 23:55:56 -0400 | [diff] [blame] | 1693 | | ``*``, ``@``, ``/``, ``//``, ``%`` | Multiplication, matrix | |
| 1694 | | | multiplication division, | |
| 1695 | | | remainder [#]_ | |
Benjamin Peterson | ba01dd9 | 2009-02-20 04:02:38 +0000 | [diff] [blame] | 1696 | +-----------------------------------------------+-------------------------------------+ |
| 1697 | | ``+x``, ``-x``, ``~x`` | Positive, negative, bitwise NOT | |
| 1698 | +-----------------------------------------------+-------------------------------------+ |
| 1699 | | ``**`` | Exponentiation [#]_ | |
| 1700 | +-----------------------------------------------+-------------------------------------+ |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 1701 | | ``await`` ``x`` | Await expression | |
| 1702 | +-----------------------------------------------+-------------------------------------+ |
Benjamin Peterson | ba01dd9 | 2009-02-20 04:02:38 +0000 | [diff] [blame] | 1703 | | ``x[index]``, ``x[index:index]``, | Subscription, slicing, | |
| 1704 | | ``x(arguments...)``, ``x.attribute`` | call, attribute reference | |
| 1705 | +-----------------------------------------------+-------------------------------------+ |
| 1706 | | ``(expressions...)``, | Binding or tuple display, | |
| 1707 | | ``[expressions...]``, | list display, | |
Ezio Melotti | 9f929bb | 2012-12-25 15:45:15 +0200 | [diff] [blame] | 1708 | | ``{key: value...}``, | dictionary display, | |
Brett Cannon | 925914f | 2010-11-21 19:58:24 +0000 | [diff] [blame] | 1709 | | ``{expressions...}`` | set display | |
Benjamin Peterson | ba01dd9 | 2009-02-20 04:02:38 +0000 | [diff] [blame] | 1710 | +-----------------------------------------------+-------------------------------------+ |
| 1711 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1712 | |
| 1713 | .. rubric:: Footnotes |
| 1714 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1715 | .. [#] While ``abs(x%y) < abs(y)`` is true mathematically, for floats it may not be |
| 1716 | true numerically due to roundoff. For example, and assuming a platform on which |
| 1717 | a Python float is an IEEE 754 double-precision number, in order that ``-1e-100 % |
| 1718 | 1e100`` have the same sign as ``1e100``, the computed result is ``-1e-100 + |
Georg Brandl | 063f237 | 2010-12-01 15:32:43 +0000 | [diff] [blame] | 1719 | 1e100``, which is numerically exactly equal to ``1e100``. The function |
| 1720 | :func:`math.fmod` returns a result whose sign matches the sign of the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1721 | first argument instead, and so returns ``-1e-100`` in this case. Which approach |
| 1722 | is more appropriate depends on the application. |
| 1723 | |
| 1724 | .. [#] 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] | 1725 | ``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] | 1726 | cases, Python returns the latter result, in order to preserve that |
| 1727 | ``divmod(x,y)[0] * y + x % y`` be very close to ``x``. |
| 1728 | |
Martin Panter | aa0da86 | 2015-09-23 05:28:13 +0000 | [diff] [blame] | 1729 | .. [#] The Unicode standard distinguishes between :dfn:`code points` |
| 1730 | (e.g. U+0041) and :dfn:`abstract characters` (e.g. "LATIN CAPITAL LETTER A"). |
| 1731 | While most abstract characters in Unicode are only represented using one |
| 1732 | code point, there is a number of abstract characters that can in addition be |
| 1733 | represented using a sequence of more than one code point. For example, the |
| 1734 | abstract character "LATIN CAPITAL LETTER C WITH CEDILLA" can be represented |
| 1735 | as a single :dfn:`precomposed character` at code position U+00C7, or as a |
| 1736 | sequence of a :dfn:`base character` at code position U+0043 (LATIN CAPITAL |
| 1737 | LETTER C), followed by a :dfn:`combining character` at code position U+0327 |
| 1738 | (COMBINING CEDILLA). |
| 1739 | |
| 1740 | The comparison operators on strings compare at the level of Unicode code |
| 1741 | points. This may be counter-intuitive to humans. For example, |
| 1742 | ``"\u00C7" == "\u0043\u0327"`` is ``False``, even though both strings |
| 1743 | represent the same abstract character "LATIN CAPITAL LETTER C WITH CEDILLA". |
| 1744 | |
| 1745 | To compare strings at the level of abstract characters (that is, in a way |
| 1746 | intuitive to humans), use :func:`unicodedata.normalize`. |
Guido van Rossum | da27fd2 | 2007-08-17 00:24:54 +0000 | [diff] [blame] | 1747 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 1748 | .. [#] Due to automatic garbage-collection, free lists, and the dynamic nature of |
Benjamin Peterson | 4118174 | 2008-07-02 20:22:54 +0000 | [diff] [blame] | 1749 | descriptors, you may notice seemingly unusual behaviour in certain uses of |
| 1750 | the :keyword:`is` operator, like those involving comparisons between instance |
| 1751 | methods, or constants. Check their documentation for more info. |
Benjamin Peterson | ba01dd9 | 2009-02-20 04:02:38 +0000 | [diff] [blame] | 1752 | |
Georg Brandl | 063f237 | 2010-12-01 15:32:43 +0000 | [diff] [blame] | 1753 | .. [#] The ``%`` operator is also used for string formatting; the same |
| 1754 | precedence applies. |
Georg Brandl | f1d633c | 2010-09-20 06:29:01 +0000 | [diff] [blame] | 1755 | |
Benjamin Peterson | ba01dd9 | 2009-02-20 04:02:38 +0000 | [diff] [blame] | 1756 | .. [#] The power operator ``**`` binds less tightly than an arithmetic or |
| 1757 | bitwise unary operator on its right, that is, ``2**-1`` is ``0.5``. |