1 2 .. _expressions: 3 4 *********** 5 Expressions 6 *********** 7 8 .. index:: expression, BNF 9 10 This chapter explains the meaning of the elements of expressions in Python. 11 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 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 30 When a description of an arithmetic operator below uses the phrase "the numeric 31 arguments are converted to a common type," this means that the operator 32 implementation for built-in types works as follows: 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 39 * otherwise, both must be integers and no conversion is necessary. 40 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. 44 45 46 .. _atoms: 47 48 Atoms 49 ===== 50 51 .. index:: atom 52 53 Atoms are the most basic elements of expressions. The simplest atoms are 54 identifiers or literals. Forms enclosed in parentheses, brackets or braces are 55 also categorized syntactically as atoms. The syntax for atoms is: 56 57 .. productionlist:: 58 atom: `identifier` | `literal` | `enclosure` 59 enclosure: `parenth_form` | `list_display` | `dict_display` | `set_display` 60 : | `generator_expression` | `yield_atom` 61 62 63 .. _atom-identifiers: 64 65 Identifiers (Names) 66 ------------------- 67 68 .. index:: name, identifier 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 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. 95 96 97 .. _atom-literals: 98 99 Literals 100 -------- 101 102 .. index:: single: literal 103 104 Python supports string and bytes literals and various numeric literals: 105 106 .. productionlist:: 107 literal: `stringliteral` | `bytesliteral` 108 : | `integer` | `floatnumber` | `imagnumber` 109 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) 113 literals. See section :ref:`literals` for details. 114 115 .. index:: 116 triple: immutable; data; type 117 pair: immutable; object 118 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. 124 125 126 .. _parenthesized: 127 128 Parenthesized forms 129 ------------------- 130 131 .. index:: single: parenthesized form 132 133 A parenthesized form is an optional expression list enclosed in parentheses: 134 135 .. productionlist:: 136 parenth_form: "(" [`starred_expression`] ")" 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 158 .. _comprehensions: 159 160 Displays for lists, sets and dictionaries 161 ----------------------------------------- 162 163 For constructing a list, a set or a dictionary Python provides special syntax 164 called "displays", each of them in two flavors: 165 166 * either the container contents are listed explicitly, or 167 168 * they are computed via a set of looping and filtering instructions, called a 169 :dfn:`comprehension`. 170 171 Common syntax elements for comprehensions are: 172 173 .. productionlist:: 174 comprehension: `expression` `comp_for` 175 comp_for: [ASYNC] "for" `target_list` "in" `or_test` [`comp_iter`] 176 comp_iter: `comp_for` | `comp_if` 177 comp_if: "if" `expression_nocond` [`comp_iter`] 178 179 The comprehension consists of a single expression followed by at least one 180 :keyword:`for` clause and zero or more :keyword:`for` or :keyword:`if` clauses. 181 In this case, the elements of the new container are those that would be produced 182 by considering each of the :keyword:`for` or :keyword:`if` clauses a block, 183 nesting from left to right, and evaluating the expression to produce an element 184 each time the innermost block is reached. 185 186 Note that the comprehension is executed in a separate scope, so names assigned 187 to in the target list don't "leak" into the enclosing scope. 188 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 193 expression, may contain additional :keyword:`for` or :keyword:`async for` 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`. 200 201 .. _lists: 202 203 List displays 204 ------------- 205 206 .. index:: 207 pair: list; display 208 pair: list; comprehensions 209 pair: empty; list 210 object: list 211 212 A list display is a possibly empty series of expressions enclosed in square 213 brackets: 214 215 .. productionlist:: 216 list_display: "[" [`starred_list` | `comprehension`] "]" 217 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. 223 224 225 .. _set: 226 227 Set displays 228 ------------ 229 230 .. index:: pair: set; display 231 object: set 232 233 A set display is denoted by curly braces and distinguishable from dictionary 234 displays by the lack of colons separating keys and values: 235 236 .. productionlist:: 237 set_display: "{" (`starred_list` | `comprehension`) "}" 238 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. 244 245 An empty set cannot be constructed with ``{}``; this literal constructs an empty 246 dictionary. 247 248 249 .. _dict: 250 251 Dictionary displays 252 ------------------- 253 254 .. index:: pair: dictionary; display 255 key, datum, key/datum pair 256 object: dictionary 257 258 A dictionary display is a possibly empty series of key/datum pairs enclosed in 259 curly braces: 260 261 .. productionlist:: 262 dict_display: "{" [`key_datum_list` | `dict_comprehension`] "}" 263 key_datum_list: `key_datum` ("," `key_datum`)* [","] 264 key_datum: `expression` ":" `expression` | "**" `or_expr` 265 dict_comprehension: `expression` ":" `expression` `comp_for` 266 267 A dictionary display yields a new dictionary object. 268 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 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 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. 289 290 .. index:: pair: immutable; object 291 hashable 292 293 Restrictions on the types of the key values are listed earlier in section 294 :ref:`types`. (To summarize, the key type should be :term:`hashable`, which excludes 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 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 318 :meth:`~generator.__next__` method is called for the generator object (in the same 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))``. 325 326 The parentheses can be omitted on calls with only one argument. See section 327 :ref:`calls` for details. 328 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`). 337 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` ")" 350 yield_expression: "yield" [`expression_list` | "from" `expression`] 351 352 The yield expression is used when defining a :term:`generator` function 353 or an :term:`asynchronous generator` function and 354 thus can only be used in the body of a function definition. Using a yield 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`. 368 369 When a generator function is called, it returns an iterator known as a 370 generator. That generator then controls the execution of the generator function. 371 The execution starts when one of the generator's methods is called. At that 372 time, the execution proceeds to the first yield expression, where it is 373 suspended again, returning the value of :token:`expression_list` to the generator's 374 caller. By suspended, we mean that all local state is retained, including the 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 378 generator's methods, the function can proceed exactly as if the yield expression 379 were just another external call. The value of the yield expression after 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. 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 391 where the execution should continue after it yields; the control is always 392 transferred to the generator's caller. 393 394 Yield expressions are allowed anywhere in a :keyword:`try` construct. If the 395 generator is not resumed before it is 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. 399 400 When ``yield from <expr>`` is used, it treats the supplied expression as 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 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. 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 415 .. versionchanged:: 3.3 416 Added ``yield from <expr>`` to delegate control flow to a subiterator. 417 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 423 :pep:`255` - Simple Generators 424 The proposal for adding generators and the :keyword:`yield` statement to Python. 425 426 :pep:`342` - Coroutines via Enhanced Generators 427 The proposal to enhance the API and syntax of generators, making them 428 usable as simple coroutines. 429 430 :pep:`380` - Syntax for Delegating to a Subgenerator 431 The proposal to introduce the :token:`yield_from` syntax, making delegation 432 to sub-generators easy. 433 434 .. index:: object: generator 435 .. _generator-methods: 436 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. 445 446 .. index:: exception: StopIteration 447 448 449 .. method:: generator.__next__() 450 451 Starts the execution of a generator function or resumes it at the last 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 456 :token:`expression_list` is returned to :meth:`__next__`'s caller. If the 457 generator exits without yielding another value, a :exc:`StopIteration` 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. 462 463 464 .. method:: generator.send(value) 465 466 Resumes the execution and "sends" a value into the generator function. The 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. 473 474 475 .. method:: generator.throw(type[, value[, traceback]]) 476 477 Raises an exception of type ``type`` at the point where the generator was paused, 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 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. 495 496 .. index:: single: yield; examples 497 498 Examples 499 ^^^^^^^^ 500 501 Here is a simple example that demonstrates the behavior of generators and 502 generator functions:: 503 504 >>> def echo(value=None): 505 ... print("Execution starts when 'next()' is called for the first time.") 506 ... try: 507 ... while True: 508 ... try: 509 ... value = (yield value) 510 ... except Exception as e: 511 ... value = e 512 ... finally: 513 ... print("Don't forget to clean up when 'close()' is called.") 514 ... 515 >>> generator = echo(1) 516 >>> print(next(generator)) 517 Execution starts when 'next()' is called for the first time. 518 1 519 >>> print(next(generator)) 520 None 521 >>> print(generator.send(2)) 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 528 For examples using ``yield from``, see :ref:`pep-380` in "What's New in 529 Python." 530 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. 659 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 692 references, which most objects do. This object is then asked to produce the 693 attribute whose name is the identifier. This production can be customized by 694 overriding the :meth:`__getattr__` method. If this attribute is not available, 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. 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 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. 725 726 For built-in objects, there are two types of objects that support subscription: 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 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. 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:: 774 slicing: `primary` "[" `slice_list` "]" 775 slice_list: `slice_item` ("," `slice_item`)* [","] 776 slice_item: `expression` | `proper_slice` 777 proper_slice: [`lower_bound`] ":" [`upper_bound`] [ ":" [`stride`] ] 778 lower_bound: `expression` 779 upper_bound: `expression` 780 stride: `expression` 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 787 slice list contains no proper slice). 788 789 .. index:: 790 single: start (slice object attribute) 791 single: stop (slice object attribute) 792 single: step (slice object attribute) 793 794 The semantics for a slicing are as follows. The primary is indexed (using the 795 same :meth:`__getitem__` method as 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 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. 805 806 807 .. index:: 808 object: callable 809 single: call 810 single: argument; call semantics 811 812 .. _calls: 813 814 Calls 815 ----- 816 817 A call calls a callable object (e.g., a :term:`function`) with a possibly empty 818 series of :term:`arguments <argument>`: 819 820 .. productionlist:: 821 call: `primary` "(" [`argument_list` [","] | `comprehension`] ")" 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`) 830 : ("," `keyword_item` | "," "**" `expression`)* 831 keyword_item: `identifier` "=" `expression` 832 833 An optional trailing comma may be present after the positional and keyword arguments 834 but does not affect the semantics. 835 836 .. index:: 837 single: parameter; call semantics 838 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 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 843 to section :ref:`function` for the syntax of formal :term:`parameter` lists. 844 845 .. XXX update with kwonly args PEP 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 865 .. impl-detail:: 866 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 870 case for functions implemented in C that use :c:func:`PyArg_ParseTuple` to 871 parse their arguments. 872 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 886 .. index:: 887 single: *; in function calls 888 single: unpacking; in function calls 889 890 If the syntax ``*expression`` appears in the function call, ``expression`` must 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*. 896 897 A consequence of this is that although the ``*expression`` syntax may appear 898 *after* explicit keyword arguments, it is processed *before* the 899 keyword arguments (and any ``**expression`` arguments -- see below). So:: 900 901 >>> def f(a, b): 902 ... print(a, b) 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 916 .. index:: 917 single: **; in function calls 918 919 If the syntax ``**expression`` appears in the function call, ``expression`` must 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. 924 925 Formal parameters using the syntax ``*identifier`` or ``**identifier`` cannot be 926 used as positional argument slots or as keyword argument names. 927 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 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 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:: 1002 await_expr: "await" `primary` 1003 1004 .. versionadded:: 3.5 1005 1006 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:: 1016 power: ( `await_expr` | `primary` ) ["**" `u_expr`] 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 1020 for the operands): ``-1**2`` results in ``-1``. 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 1025 type, and the result is of that type. 1026 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``. 1031 1032 Raising ``0.0`` to a negative power results in a :exc:`ZeroDivisionError`. 1033 Raising a negative number to a fractional power results in a :class:`complex` 1034 number. (In earlier versions it raised a :exc:`ValueError`.) 1035 1036 1037 .. _unary: 1038 1039 Unary arithmetic and bitwise operations 1040 ======================================= 1041 1042 .. index:: 1043 triple: unary; arithmetic; operation 1044 triple: unary; bitwise; operation 1045 1046 All unary arithmetic and bitwise operations have the same priority: 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 1063 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. 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:: 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` 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 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. 1099 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 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. 1113 Division of integers yields a float, while floor division of integers results in an 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. 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 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)``. [#]_. 1133 1134 In addition to performing the modulo operation on numbers, the ``%`` operator is 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 1137 Python Library Reference, section :ref:`old-string-formatting`. 1138 1139 The floor division operator, the modulo operator, and the :func:`divmod` 1140 function are not defined for complex numbers. Instead, convert to a floating 1141 point number using the :func:`abs` function if appropriate. 1142 1143 .. index:: single: addition 1144 1145 The ``+`` (addition) operator yields the sum of its arguments. The arguments 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. 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 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. 1170 1171 .. index:: exception: ValueError 1172 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)``. 1175 1176 .. note:: 1177 1178 In the current implementation, the right-hand operand is required 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. 1181 1182 .. _bitwise: 1183 1184 Binary bitwise operations 1185 ========================= 1186 1187 .. index:: triple: binary; bitwise; operation 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 1196 .. index:: pair: bitwise; and 1197 1198 The ``&`` operator yields the bitwise AND of its arguments, which must be 1199 integers. 1200 1201 .. index:: 1202 pair: bitwise; xor 1203 pair: exclusive; or 1204 1205 The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which 1206 must be integers. 1207 1208 .. index:: 1209 pair: bitwise; or 1210 pair: inclusive; or 1211 1212 The ``|`` operator yields the bitwise (inclusive) OR of its arguments, which 1213 must be integers. 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 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. 1247 1248 Note that ``a op1 b op2 c`` doesn't imply any kind of comparison between *a* and 1249 *c*, so that, e.g., ``x < y > z`` is perfectly legal (though perhaps not 1250 pretty). 1251 1252 Value comparisons 1253 ----------------- 1254 1255 The operators ``<``, ``>``, ``==``, ``>=``, ``<=``, and ``!=`` compare the 1256 values of two objects. The objects do not need to have the same type. 1257 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. 1266 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`. 1272 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 1304 will return ``False``. For example, both ``3 < float('NaN')`` and 1305 ``float('NaN') < 3`` will return ``False``. 1306 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. 1310 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. [#]_ 1314 1315 Strings and binary sequences cannot be directly compared. 1316 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 1320 results in inequality, and ordering comparison across these types raises 1321 :exc:`TypeError`. 1322 1323 Sequences compare lexicographically using comparison of corresponding 1324 elements, whereby reflexivity of the elements is enforced. 1325 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 1370 another). Accordingly, sets are not appropriate arguments for functions 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). 1373 1374 Comparison of sets enforces reflexivity of its elements. 1375 1376 * Most other built-in types have no comparison methods implemented, so they 1377 inherit the default comparison behavior. 1378 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 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 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: 1428 .. _membership-test-details: 1429 1430 Membership test operations 1431 -------------------------- 1432 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 1436 support this as well as dictionary, for which :keyword:`in` tests whether the 1437 dictionary has a given key. For container types such as list, tuple, set, 1438 frozenset, dict, or collections.deque, the expression ``x in y`` is equivalent 1439 to ``any(x is e or x == e for e in y)``. 1440 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``. 1445 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 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 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 1457 raise :exc:`IndexError` exception. (If any other exception is raised, it is as 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 1474 1475 .. _is: 1476 .. _is not: 1477 1478 Identity comparisons 1479 -------------------- 1480 1481 The operators :keyword:`is` and :keyword:`is not` test for object identity: ``x 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. [#]_ 1485 1486 1487 .. _booleans: 1488 .. _and: 1489 .. _or: 1490 .. _not: 1491 1492 Boolean operations 1493 ================== 1494 1495 .. index:: 1496 pair: Conditional; expression 1497 pair: Boolean; operation 1498 1499 .. productionlist:: 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 1508 other values are interpreted as true. User-defined objects can customize their 1509 truth value by providing a :meth:`__bool__` method. 1510 1511 .. index:: operator: not 1512 1513 The operator :keyword:`not` yields ``True`` if its argument is false, ``False`` 1514 otherwise. 1515 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 1528 argument. This is sometimes useful, e.g., if ``s`` is a string that should be 1529 replaced by a default value if it is empty, the expression ``s or 'foo'`` yields 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 ``''``.) 1533 1534 1535 Conditional expressions 1536 ======================= 1537 1538 .. index:: 1539 pair: conditional; expression 1540 pair: ternary; operator 1541 1542 .. productionlist:: 1543 conditional_expression: `or_test` ["if" `or_test` "else" `expression`] 1544 expression: `conditional_expression` | `lambda_expr` 1545 expression_nocond: `or_test` | `lambda_expr_nocond` 1546 1547 Conditional expressions (sometimes called a "ternary operator") have the lowest 1548 priority of all Python operations. 1549 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 1552 evaluated and its value is returned. 1553 1554 See :pep:`308` for more details about conditional expressions. 1555 1556 1557 .. _lambdas: 1558 .. _lambda: 1559 1560 Lambdas 1561 ======= 1562 1563 .. index:: 1564 pair: lambda; expression 1565 pair: lambda; form 1566 pair: anonymous; function 1567 1568 .. productionlist:: 1569 lambda_expr: "lambda" [`parameter_list`]: `expression` 1570 lambda_expr_nocond: "lambda" [`parameter_list`]: `expression_nocond` 1571 1572 Lambda expressions (sometimes called lambda forms) are used to create anonymous 1573 functions. The expression ``lambda arguments: expression`` yields a function 1574 object. The unnamed object behaves like a function object defined with: 1575 1576 .. code-block:: none 1577 1578 def <lambda>(arguments): 1579 return expression 1580 1581 See section :ref:`function` for the syntax of parameter lists. Note that 1582 functions created with lambda expressions cannot contain statements or 1583 annotations. 1584 1585 1586 .. _exprlists: 1587 1588 Expression lists 1589 ================ 1590 1591 .. index:: pair: expression; list 1592 1593 .. productionlist:: 1594 expression_list: `expression` ( "," `expression` )* [","] 1595 starred_list: `starred_item` ( "," `starred_item` )* [","] 1596 starred_expression: `expression` | ( `starred_item` "," )* [`starred_item`] 1597 starred_item: `expression` | "*" `or_expr` 1598 1599 .. index:: object: tuple 1600 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 1603 the tuple is the number of expressions in the list. The expressions are 1604 evaluated from left to right. 1605 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 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 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. 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) 1644 expr1(expr2, expr3, *expr4, **expr5) 1645 expr3, expr4 = expr1, expr2 1646 1647 1648 .. _operator-summary: 1649 1650 Operator precedence 1651 =================== 1652 1653 .. index:: pair: operator; precedence 1654 1655 The following table summarizes the operator precedence in Python, from lowest 1656 precedence (least binding) to highest precedence (most binding). Operators in 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 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. 1664 1665 1666 +-----------------------------------------------+-------------------------------------+ 1667 | Operator | Description | 1668 +===============================================+=====================================+ 1669 | :keyword:`lambda` | Lambda expression | 1670 +-----------------------------------------------+-------------------------------------+ 1671 | :keyword:`if` -- :keyword:`else` | Conditional expression | 1672 +-----------------------------------------------+-------------------------------------+ 1673 | :keyword:`or` | Boolean OR | 1674 +-----------------------------------------------+-------------------------------------+ 1675 | :keyword:`and` | Boolean AND | 1676 +-----------------------------------------------+-------------------------------------+ 1677 | :keyword:`not` ``x`` | Boolean NOT | 1678 +-----------------------------------------------+-------------------------------------+ 1679 | :keyword:`in`, :keyword:`not in`, | Comparisons, including membership | 1680 | :keyword:`is`, :keyword:`is not`, ``<``, | tests and identity tests | 1681 | ``<=``, ``>``, ``>=``, ``!=``, ``==`` | | 1682 +-----------------------------------------------+-------------------------------------+ 1683 | ``|`` | Bitwise OR | 1684 +-----------------------------------------------+-------------------------------------+ 1685 | ``^`` | Bitwise XOR | 1686 +-----------------------------------------------+-------------------------------------+ 1687 | ``&`` | Bitwise AND | 1688 +-----------------------------------------------+-------------------------------------+ 1689 | ``<<``, ``>>`` | Shifts | 1690 +-----------------------------------------------+-------------------------------------+ 1691 | ``+``, ``-`` | Addition and subtraction | 1692 +-----------------------------------------------+-------------------------------------+ 1693 | ``*``, ``@``, ``/``, ``//``, ``%`` | Multiplication, matrix | 1694 | | multiplication division, | 1695 | | remainder [#]_ | 1696 +-----------------------------------------------+-------------------------------------+ 1697 | ``+x``, ``-x``, ``~x`` | Positive, negative, bitwise NOT | 1698 +-----------------------------------------------+-------------------------------------+ 1699 | ``**`` | Exponentiation [#]_ | 1700 +-----------------------------------------------+-------------------------------------+ 1701 | ``await`` ``x`` | Await expression | 1702 +-----------------------------------------------+-------------------------------------+ 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, | 1708 | ``{key: value...}``, | dictionary display, | 1709 | ``{expressions...}`` | set display | 1710 +-----------------------------------------------+-------------------------------------+ 1711 1712 1713 .. rubric:: Footnotes 1714 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 + 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 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 1725 ``x//y`` to be one larger than ``(x-x%y)//y`` due to rounding. In such 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 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`. 1747 1748 .. [#] Due to automatic garbage-collection, free lists, and the dynamic nature of 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. 1752 1753 .. [#] The ``%`` operator is also used for string formatting; the same 1754 precedence applies. 1755 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``. 1758