diff options
Diffstat (limited to 'Doc/reference/expressions.rst')
| -rw-r--r-- | Doc/reference/expressions.rst | 1283 |
1 files changed, 1283 insertions, 0 deletions
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst new file mode 100644 index 0000000000..28c1406eeb --- /dev/null +++ b/Doc/reference/expressions.rst @@ -0,0 +1,1283 @@ + +.. _expressions: + +*********** +Expressions +*********** + +.. index:: single: expression + +This chapter explains the meaning of the elements of expressions in Python. + +.. index:: single: BNF + +**Syntax Notes:** In this and the following chapters, extended BNF notation will +be used to describe syntax, not lexical analysis. When (one alternative of) a +syntax rule has the form + +.. productionlist:: * + name: `othername` + +.. index:: single: syntax + +and no semantics are given, the semantics of this form of ``name`` are the same +as for ``othername``. + + +.. _conversions: + +Arithmetic conversions +====================== + +.. index:: pair: arithmetic; conversion + +.. XXX no coercion rules are documented anymore + +When a description of an arithmetic operator below uses the phrase "the numeric +arguments are converted to a common type," the arguments are coerced using the +coercion rules. If both arguments are standard +numeric types, the following coercions are applied: + +* If either argument is a complex number, the other is converted to complex; + +* otherwise, if either argument is a floating point number, the other is + converted to floating point; + +* otherwise, if either argument is a long integer, the other is converted to + long integer; + +* otherwise, both must be plain integers and no conversion is necessary. + +Some additional rules apply for certain operators (e.g., a string left argument +to the '%' operator). Extensions can define their own coercions. + + +.. _atoms: + +Atoms +===== + +.. index:: single: atom + +Atoms are the most basic elements of expressions. The simplest atoms are +identifiers or literals. Forms enclosed in reverse quotes or in parentheses, +brackets or braces are also categorized syntactically as atoms. The syntax for +atoms is: + +.. productionlist:: + atom: `identifier` | `literal` | `enclosure` + enclosure: `parenth_form` | `list_display` + : | `generator_expression` | `dict_display` + : | `string_conversion` | `yield_atom` + + +.. _atom-identifiers: + +Identifiers (Names) +------------------- + +.. index:: + single: name + single: identifier + +An identifier occurring as an atom is a name. See section :ref:`identifiers` +for lexical definition and section :ref:`naming` for documentation of naming and +binding. + +.. index:: exception: NameError + +When the name is bound to an object, evaluation of the atom yields that object. +When a name is not bound, an attempt to evaluate it raises a :exc:`NameError` +exception. + +.. index:: + pair: name; mangling + pair: private; names + +**Private name mangling:** When an identifier that textually occurs in a class +definition begins with two or more underscore characters and does not end in two +or more underscores, it is considered a :dfn:`private name` of that class. +Private names are transformed to a longer form before code is generated for +them. The transformation inserts the class name in front of the name, with +leading underscores removed, and a single underscore inserted in front of the +class name. For example, the identifier ``__spam`` occurring in a class named +``Ham`` will be transformed to ``_Ham__spam``. This transformation is +independent of the syntactical context in which the identifier is used. If the +transformed name is extremely long (longer than 255 characters), implementation +defined truncation may happen. If the class name consists only of underscores, +no transformation is done. + +.. % +.. % + + +.. _atom-literals: + +Literals +-------- + +.. index:: single: literal + +Python supports string literals and various numeric literals: + +.. productionlist:: + literal: `stringliteral` | `integer` | `longinteger` + : | `floatnumber` | `imagnumber` + +Evaluation of a literal yields an object of the given type (string, integer, +long integer, floating point number, complex number) with the given value. The +value may be approximated in the case of floating point and imaginary (complex) +literals. See section :ref:`literals` for details. + +.. index:: + triple: immutable; data; type + pair: immutable; object + +All literals correspond to immutable data types, and hence the object's identity +is less important than its value. Multiple evaluations of literals with the +same value (either the same occurrence in the program text or a different +occurrence) may obtain the same object or a different object with the same +value. + + +.. _parenthesized: + +Parenthesized forms +------------------- + +.. index:: single: parenthesized form + +A parenthesized form is an optional expression list enclosed in parentheses: + +.. productionlist:: + parenth_form: "(" [`expression_list`] ")" + +A parenthesized expression list yields whatever that expression list yields: if +the list contains at least one comma, it yields a tuple; otherwise, it yields +the single expression that makes up the expression list. + +.. index:: pair: empty; tuple + +An empty pair of parentheses yields an empty tuple object. Since tuples are +immutable, the rules for literals apply (i.e., two occurrences of the empty +tuple may or may not yield the same object). + +.. index:: + single: comma + pair: tuple; display + +Note that tuples are not formed by the parentheses, but rather by use of the +comma operator. The exception is the empty tuple, for which parentheses *are* +required --- allowing unparenthesized "nothing" in expressions would cause +ambiguities and allow common typos to pass uncaught. + + +.. _lists: + +List displays +------------- + +.. index:: + pair: list; display + pair: list; comprehensions + +A list display is a possibly empty series of expressions enclosed in square +brackets: + +.. productionlist:: + list_display: "[" [`expression_list` | `list_comprehension`] "]" + list_comprehension: `expression` `list_for` + list_for: "for" `target_list` "in" `old_expression_list` [`list_iter`] + old_expression_list: `old_expression` [("," `old_expression`)+ [","]] + list_iter: `list_for` | `list_if` + list_if: "if" `old_expression` [`list_iter`] + +.. index:: + pair: list; comprehensions + object: list + pair: empty; list + +A list display yields a new list object. Its contents are specified by +providing either a list of expressions or a list comprehension. When a +comma-separated list of expressions is supplied, its elements are evaluated from +left to right and placed into the list object in that order. When a list +comprehension is supplied, it consists of a single expression followed by at +least one :keyword:`for` clause and zero or more :keyword:`for` or :keyword:`if` +clauses. In this case, the elements of the new list are those that would be +produced by considering each of the :keyword:`for` or :keyword:`if` clauses a +block, nesting from left to right, and evaluating the expression to produce a +list element each time the innermost block is reached [#]_. + + +.. _genexpr: + +Generator expressions +--------------------- + +.. index:: pair: generator; expression + +A generator expression is a compact generator notation in parentheses: + +.. productionlist:: + generator_expression: "(" `expression` `genexpr_for` ")" + genexpr_for: "for" `target_list` "in" `or_test` [`genexpr_iter`] + genexpr_iter: `genexpr_for` | `genexpr_if` + genexpr_if: "if" `old_expression` [`genexpr_iter`] + +.. index:: object: generator + +A generator expression yields a new generator object. It consists of a single +expression followed by at least one :keyword:`for` clause and zero or more +:keyword:`for` or :keyword:`if` clauses. The iterating values of the new +generator are those that would be produced by considering each of the +:keyword:`for` or :keyword:`if` clauses a block, nesting from left to right, and +evaluating the expression to yield a value that is reached the innermost block +for each iteration. + +Variables used in the generator expression are evaluated lazily when the +:meth:`__next__` method is called for generator object (in the same fashion as +normal generators). However, the leftmost :keyword:`for` clause is immediately +evaluated so that error produced by it can be seen before any other possible +error in the code that handles the generator expression. Subsequent +:keyword:`for` clauses cannot be evaluated immediately since they may depend on +the previous :keyword:`for` loop. For example: ``(x*y for x in range(10) for y +in bar(x))``. + +The parentheses can be omitted on calls with only one argument. See section +:ref:`calls` for the detail. + + +.. _dict: + +Dictionary displays +------------------- + +.. index:: pair: dictionary; display + +.. index:: + single: key + single: datum + single: key/datum pair + +A dictionary display is a possibly empty series of key/datum pairs enclosed in +curly braces: + +.. productionlist:: + dict_display: "{" [`key_datum_list`] "}" + key_datum_list: `key_datum` ("," `key_datum`)* [","] + key_datum: `expression` ":" `expression` + +.. index:: object: dictionary + +A dictionary display yields a new dictionary object. + +The key/datum pairs are evaluated from left to right to define the entries of +the dictionary: each key object is used as a key into the dictionary to store +the corresponding datum. + +.. index:: pair: immutable; object + +Restrictions on the types of the key values are listed earlier in section +:ref:`types`. (To summarize, the key type should be hashable, which excludes +all mutable objects.) Clashes between duplicate keys are not detected; the last +datum (textually rightmost in the display) stored for a given key value +prevails. + + +.. _yieldexpr: + +Yield expressions +----------------- + +.. index:: + keyword: yield + pair: yield; expression + pair: generator; function + +.. productionlist:: + yield_atom: "(" `yield_expression` ")" + yield_expression: "yield" [`expression_list`] + +.. versionadded:: 2.5 + +The :keyword:`yield` expression is only used when defining a generator function, +and can only be used in the body of a function definition. Using a +:keyword:`yield` expression in a function definition is sufficient to cause that +definition to create a generator function instead of a normal function. + +When a generator function is called, it returns an iterator known as a +generator. That generator then controls the execution of a generator function. +The execution starts when one of the generator's methods is called. At that +time, the execution proceeds to the first :keyword:`yield` expression, where it +is suspended again, returning the value of :token:`expression_list` to +generator's caller. By suspended we mean that all local state is retained, +including the current bindings of local variables, the instruction pointer, and +the internal evaluation stack. When the execution is resumed by calling one of +the generator's methods, the function can proceed exactly as if the +:keyword:`yield` expression was just another external call. The value of the +:keyword:`yield` expression after resuming depends on the method which resumed +the execution. + +.. index:: single: coroutine + +All of this makes generator functions quite similar to coroutines; they yield +multiple times, they have more than one entry point and their execution can be +suspended. The only difference is that a generator function cannot control +where should the execution continue after it yields; the control is always +transfered to the generator's caller. + +.. index:: object: generator + +The following generator's methods can be used to control the execution of a +generator function: + +.. index:: exception: StopIteration + + +.. method:: generator.next() + + Starts the execution of a generator function or resumes it at the last executed + :keyword:`yield` expression. When a generator function is resumed with a + :meth:`next` method, the current :keyword:`yield` expression always evaluates to + :const:`None`. The execution then continues to the next :keyword:`yield` + expression, where the generator is suspended again, and the value of the + :token:`expression_list` is returned to :meth:`next`'s caller. If the generator + exits without yielding another value, a :exc:`StopIteration` exception is + raised. + + +.. method:: generator.send(value) + + Resumes the execution and "sends" a value into the generator function. The + ``value`` argument becomes the result of the current :keyword:`yield` + expression. The :meth:`send` method returns the next value yielded by the + generator, or raises :exc:`StopIteration` if the generator exits without + yielding another value. When :meth:`send` is called to start the generator, it + must be called with :const:`None` as the argument, because there is no + :keyword:`yield` expression that could receieve the value. + + +.. method:: generator.throw(type[, value[, traceback]]) + + Raises an exception of type ``type`` at the point where generator was paused, + and returns the next value yielded by the generator function. If the generator + exits without yielding another value, a :exc:`StopIteration` exception is + raised. If the generator function does not catch the passed-in exception, or + raises a different exception, then that exception propagates to the caller. + +.. index:: exception: GeneratorExit + + +.. method:: generator.close() + + Raises a :exc:`GeneratorExit` at the point where the generator function was + paused. If the generator function then raises :exc:`StopIteration` (by exiting + normally, or due to already being closed) or :exc:`GeneratorExit` (by not + catching the exception), close returns to its caller. If the generator yields a + value, a :exc:`RuntimeError` is raised. If the generator raises any other + exception, it is propagated to the caller. :meth:`close` does nothing if the + generator has already exited due to an exception or normal exit. + +Here is a simple example that demonstrates the behavior of generators and +generator functions:: + + >>> def echo(value=None): + ... print "Execution starts when 'next()' is called for the first time." + ... try: + ... while True: + ... try: + ... value = (yield value) + ... except GeneratorExit: + ... # never catch GeneratorExit + ... raise + ... except Exception, e: + ... value = e + ... finally: + ... print "Don't forget to clean up when 'close()' is called." + ... + >>> generator = echo(1) + >>> print generator.next() + Execution starts when 'next()' is called for the first time. + 1 + >>> print generator.next() + None + >>> print generator.send(2) + 2 + >>> generator.throw(TypeError, "spam") + TypeError('spam',) + >>> generator.close() + Don't forget to clean up when 'close()' is called. + + +.. seealso:: + + :pep:`0342` - Coroutines via Enhanced Generators + The proposal to enhance the API and syntax of generators, making them usable as + simple coroutines. + + +.. _primaries: + +Primaries +========= + +.. index:: single: primary + +Primaries represent the most tightly bound operations of the language. Their +syntax is: + +.. productionlist:: + primary: `atom` | `attributeref` | `subscription` | `slicing` | `call` + + +.. _attribute-references: + +Attribute references +-------------------- + +.. index:: pair: attribute; reference + +An attribute reference is a primary followed by a period and a name: + +.. productionlist:: + attributeref: `primary` "." `identifier` + +.. index:: + exception: AttributeError + object: module + object: list + +The primary must evaluate to an object of a type that supports attribute +references, e.g., a module, list, or an instance. This object is then asked to +produce the attribute whose name is the identifier. If this attribute is not +available, the exception :exc:`AttributeError` is raised. Otherwise, the type +and value of the object produced is determined by the object. Multiple +evaluations of the same attribute reference may yield different objects. + + +.. _subscriptions: + +Subscriptions +------------- + +.. index:: single: subscription + +.. index:: + object: sequence + object: mapping + object: string + object: tuple + object: list + object: dictionary + pair: sequence; item + +A subscription selects an item of a sequence (string, tuple or list) or mapping +(dictionary) object: + +.. productionlist:: + subscription: `primary` "[" `expression_list` "]" + +The primary must evaluate to an object of a sequence or mapping type. + +If the primary is a mapping, the expression list must evaluate to an object +whose value is one of the keys of the mapping, and the subscription selects the +value in the mapping that corresponds to that key. (The expression list is a +tuple except if it has exactly one item.) + +If the primary is a sequence, the expression (list) must evaluate to a plain +integer. If this value is negative, the length of the sequence is added to it +(so that, e.g., ``x[-1]`` selects the last item of ``x``.) The resulting value +must be a nonnegative integer less than the number of items in the sequence, and +the subscription selects the item whose index is that value (counting from +zero). + +.. index:: + single: character + pair: string; item + +A string's items are characters. A character is not a separate data type but a +string of exactly one character. + + +.. _slicings: + +Slicings +-------- + +.. index:: + single: slicing + single: slice + +.. index:: + object: sequence + object: string + object: tuple + object: list + +A slicing selects a range of items in a sequence object (e.g., a string, tuple +or list). Slicings may be used as expressions or as targets in assignment or +:keyword:`del` statements. The syntax for a slicing: + +.. productionlist:: + slicing: `simple_slicing` | `extended_slicing` + simple_slicing: `primary` "[" `short_slice` "]" + extended_slicing: `primary` "[" `slice_list` "]" + slice_list: `slice_item` ("," `slice_item`)* [","] + slice_item: `expression` | `proper_slice` | `ellipsis` + proper_slice: `short_slice` | `long_slice` + short_slice: [`lower_bound`] ":" [`upper_bound`] + long_slice: `short_slice` ":" [`stride`] + lower_bound: `expression` + upper_bound: `expression` + stride: `expression` + ellipsis: "..." + +.. index:: pair: extended; slicing + +There is ambiguity in the formal syntax here: anything that looks like an +expression list also looks like a slice list, so any subscription can be +interpreted as a slicing. Rather than further complicating the syntax, this is +disambiguated by defining that in this case the interpretation as a subscription +takes priority over the interpretation as a slicing (this is the case if the +slice list contains no proper slice nor ellipses). Similarly, when the slice +list has exactly one short slice and no trailing comma, the interpretation as a +simple slicing takes priority over that as an extended slicing. + +The semantics for a simple slicing are as follows. The primary must evaluate to +a sequence object. The lower and upper bound expressions, if present, must +evaluate to plain integers; defaults are zero and the ``sys.maxint``, +respectively. If either bound is negative, the sequence's length is added to +it. The slicing now selects all items with index *k* such that ``i <= k < j`` +where *i* and *j* are the specified lower and upper bounds. This may be an +empty sequence. It is not an error if *i* or *j* lie outside the range of valid +indexes (such items don't exist so they aren't selected). + +.. index:: + single: start (slice object attribute) + single: stop (slice object attribute) + single: step (slice object attribute) + +The semantics for an extended slicing are as follows. The primary must evaluate +to a mapping object, and it is indexed with a key that is constructed from the +slice list, as follows. If the slice list contains at least one comma, the key +is a tuple containing the conversion of the slice items; otherwise, the +conversion of the lone slice item is the key. The conversion of a slice item +that is an expression is that expression. The conversion of a proper slice is a +slice object (see section :ref:`types`) whose :attr:`start`, :attr:`stop` and +:attr:`step` attributes are the values of the expressions given as lower bound, +upper bound and stride, respectively, substituting ``None`` for missing +expressions. + + +.. _calls: + +Calls +----- + +.. index:: single: call + +.. index:: object: callable + +A call calls a callable object (e.g., a function) with a possibly empty series +of arguments: + +.. productionlist:: + call: `primary` "(" [`argument_list` [","] + : | `expression` `genexpr_for`] ")" + argument_list: `positional_arguments` ["," `keyword_arguments`] + : ["," "*" `expression`] + : ["," "**" `expression`] + : | `keyword_arguments` ["," "*" `expression`] + : ["," "**" `expression`] + : | "*" `expression` ["," "**" `expression`] + : | "**" `expression` + positional_arguments: `expression` ("," `expression`)* + keyword_arguments: `keyword_item` ("," `keyword_item`)* + keyword_item: `identifier` "=" `expression` + +A trailing comma may be present after the positional and keyword arguments but +does not affect the semantics. + +The primary must evaluate to a callable object (user-defined functions, built-in +functions, methods of built-in objects, class objects, methods of class +instances, and certain class instances themselves are callable; extensions may +define additional callable object types). All argument expressions are +evaluated before the call is attempted. Please refer to section :ref:`function` +for the syntax of formal parameter lists. + +If keyword arguments are present, they are first converted to positional +arguments, as follows. First, a list of unfilled slots is created for the +formal parameters. If there are N positional arguments, they are placed in the +first N slots. Next, for each keyword argument, the identifier is used to +determine the corresponding slot (if the identifier is the same as the first +formal parameter name, the first slot is used, and so on). If the slot is +already filled, a :exc:`TypeError` exception is raised. Otherwise, the value of +the argument is placed in the slot, filling it (even if the expression is +``None``, it fills the slot). When all arguments have been processed, the slots +that are still unfilled are filled with the corresponding default value from the +function definition. (Default values are calculated, once, when the function is +defined; thus, a mutable object such as a list or dictionary used as default +value will be shared by all calls that don't specify an argument value for the +corresponding slot; this should usually be avoided.) If there are any unfilled +slots for which no default value is specified, a :exc:`TypeError` exception is +raised. Otherwise, the list of filled slots is used as the argument list for +the call. + +If there are more positional arguments than there are formal parameter slots, a +:exc:`TypeError` exception is raised, unless a formal parameter using the syntax +``*identifier`` is present; in this case, that formal parameter receives a tuple +containing the excess positional arguments (or an empty tuple if there were no +excess positional arguments). + +If any keyword argument does not correspond to a formal parameter name, a +:exc:`TypeError` exception is raised, unless a formal parameter using the syntax +``**identifier`` is present; in this case, that formal parameter receives a +dictionary containing the excess keyword arguments (using the keywords as keys +and the argument values as corresponding values), or a (new) empty dictionary if +there were no excess keyword arguments. + +If the syntax ``*expression`` appears in the function call, ``expression`` must +evaluate to a sequence. Elements from this sequence are treated as if they were +additional positional arguments; if there are postional arguments *x1*,...,*xN* +, and ``expression`` evaluates to a sequence *y1*,...,*yM*, this is equivalent +to a call with M+N positional arguments *x1*,...,*xN*,*y1*,...,*yM*. + +A consequence of this is that although the ``*expression`` syntax appears +*after* any keyword arguments, it is processed *before* the keyword arguments +(and the ``**expression`` argument, if any -- see below). So:: + + >>> def f(a, b): + ... print a, b + ... + >>> f(b=1, *(2,)) + 2 1 + >>> f(a=1, *(2,)) + Traceback (most recent call last): + File "<stdin>", line 1, in ? + TypeError: f() got multiple values for keyword argument 'a' + >>> f(1, *(2,)) + 1 2 + +It is unusual for both keyword arguments and the ``*expression`` syntax to be +used in the same call, so in practice this confusion does not arise. + +If the syntax ``**expression`` appears in the function call, ``expression`` must +evaluate to a mapping, the contents of which are treated as additional keyword +arguments. In the case of a keyword appearing in both ``expression`` and as an +explicit keyword argument, a :exc:`TypeError` exception is raised. + +Formal parameters using the syntax ``*identifier`` or ``**identifier`` cannot be +used as positional argument slots or as keyword argument names. + +A call always returns some value, possibly ``None``, unless it raises an +exception. How this value is computed depends on the type of the callable +object. + +If it is--- + +a user-defined function: + .. index:: + pair: function; call + triple: user-defined; function; call + object: user-defined function + object: function + + The code block for the function is executed, passing it the argument list. The + first thing the code block will do is bind the formal parameters to the + arguments; this is described in section :ref:`function`. When the code block + executes a :keyword:`return` statement, this specifies the return value of the + function call. + +a built-in function or method: + .. index:: + pair: function; call + pair: built-in function; call + pair: method; call + pair: built-in method; call + object: built-in method + object: built-in function + object: method + object: function + + The result is up to the interpreter; see :ref:`built-in-funcs` for the + descriptions of built-in functions and methods. + +a class object: + .. index:: + object: class + pair: class object; call + + A new instance of that class is returned. + +a class instance method: + .. index:: + object: class instance + object: instance + pair: class instance; call + + The corresponding user-defined function is called, with an argument list that is + one longer than the argument list of the call: the instance becomes the first + argument. + +a class instance: + .. index:: + pair: instance; call + single: __call__() (object method) + + The class must define a :meth:`__call__` method; the effect is then the same as + if that method was called. + + +.. _power: + +The power operator +================== + +The power operator binds more tightly than unary operators on its left; it binds +less tightly than unary operators on its right. The syntax is: + +.. productionlist:: + power: `primary` ["**" `u_expr`] + +Thus, in an unparenthesized sequence of power and unary operators, the operators +are evaluated from right to left (this does not constrain the evaluation order +for the operands). + +The power operator has the same semantics as the built-in :func:`pow` function, +when called with two arguments: it yields its left argument raised to the power +of its right argument. The numeric arguments are first converted to a common +type. The result type is that of the arguments after coercion. + +With mixed operand types, the coercion rules for binary arithmetic operators +apply. For int and long int operands, the result has the same type as the +operands (after coercion) unless the second argument is negative; in that case, +all arguments are converted to float and a float result is delivered. For +example, ``10**2`` returns ``100``, but ``10**-2`` returns ``0.01``. (This last +feature was added in Python 2.2. In Python 2.1 and before, if both arguments +were of integer types and the second argument was negative, an exception was +raised). + +Raising ``0.0`` to a negative power results in a :exc:`ZeroDivisionError`. +Raising a negative number to a fractional power results in a :exc:`ValueError`. + + +.. _unary: + +Unary arithmetic operations +=========================== + +.. index:: + triple: unary; arithmetic; operation + triple: unary; bit-wise; operation + +All unary arithmetic (and bit-wise) operations have the same priority: + +.. productionlist:: + u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr` + +.. index:: + single: negation + single: minus + +The unary ``-`` (minus) operator yields the negation of its numeric argument. + +.. index:: single: plus + +The unary ``+`` (plus) operator yields its numeric argument unchanged. + +.. index:: single: inversion + +The unary ``~`` (invert) operator yields the bit-wise inversion of its plain or +long integer argument. The bit-wise inversion of ``x`` is defined as +``-(x+1)``. It only applies to integral numbers. + +.. index:: exception: TypeError + +In all three cases, if the argument does not have the proper type, a +:exc:`TypeError` exception is raised. + + +.. _binary: + +Binary arithmetic operations +============================ + +.. index:: triple: binary; arithmetic; operation + +The binary arithmetic operations have the conventional priority levels. Note +that some of these operations also apply to certain non-numeric types. Apart +from the power operator, there are only two levels, one for multiplicative +operators and one for additive operators: + +.. productionlist:: + m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr` + : | `m_expr` "%" `u_expr` + a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr` + +.. index:: single: multiplication + +The ``*`` (multiplication) operator yields the product of its arguments. The +arguments must either both be numbers, or one argument must be an integer (plain +or long) and the other must be a sequence. In the former case, the numbers are +converted to a common type and then multiplied together. In the latter case, +sequence repetition is performed; a negative repetition factor yields an empty +sequence. + +.. index:: + exception: ZeroDivisionError + single: division + +The ``/`` (division) and ``//`` (floor division) operators yield the quotient of +their arguments. The numeric arguments are first converted to a common type. +Plain or long integer division yields an integer of the same type; the result is +that of mathematical division with the 'floor' function applied to the result. +Division by zero raises the :exc:`ZeroDivisionError` exception. + +.. index:: single: modulo + +The ``%`` (modulo) operator yields the remainder from the division of the first +argument by the second. The numeric arguments are first converted to a common +type. A zero right argument raises the :exc:`ZeroDivisionError` exception. The +arguments may be floating point numbers, e.g., ``3.14%0.7`` equals ``0.34`` +(since ``3.14`` equals ``4*0.7 + 0.34``.) The modulo operator always yields a +result with the same sign as its second operand (or zero); the absolute value of +the result is strictly smaller than the absolute value of the second operand +[#]_. + +The integer division and modulo operators are connected by the following +identity: ``x == (x/y)*y + (x%y)``. Integer division and modulo are also +connected with the built-in function :func:`divmod`: ``divmod(x, y) == (x/y, +x%y)``. These identities don't hold for floating point numbers; there similar +identities hold approximately where ``x/y`` is replaced by ``floor(x/y)`` or +``floor(x/y) - 1`` [#]_. + +In addition to performing the modulo operation on numbers, the ``%`` operator is +also overloaded by string and unicode objects to perform string formatting (also +known as interpolation). The syntax for string formatting is described in the +Python Library Reference, section :ref:`string-formatting`. + +The floor division operator, the modulo operator, and the :func:`divmod` +function are not defined for complex numbers. Instead, convert to a +floating point number using the :func:`abs` function if appropriate. + +.. index:: single: addition + +The ``+`` (addition) operator yields the sum of its arguments. The arguments +must either both be numbers or both sequences of the same type. In the former +case, the numbers are converted to a common type and then added together. In +the latter case, the sequences are concatenated. + +.. index:: single: subtraction + +The ``-`` (subtraction) operator yields the difference of its arguments. The +numeric arguments are first converted to a common type. + + +.. _shifting: + +Shifting operations +=================== + +.. index:: pair: shifting; operation + +The shifting operations have lower priority than the arithmetic operations: + +.. productionlist:: + shift_expr: `a_expr` | `shift_expr` ( "<<" | ">>" ) `a_expr` + +These operators accept plain or long integers as arguments. The arguments are +converted to a common type. They shift the first argument to the left or right +by the number of bits given by the second argument. + +.. index:: exception: ValueError + +A right shift by *n* bits is defined as division by ``pow(2,n)``. A left shift +by *n* bits is defined as multiplication with ``pow(2,n)``; for plain integers +there is no overflow check so in that case the operation drops bits and flips +the sign if the result is not less than ``pow(2,31)`` in absolute value. +Negative shift counts raise a :exc:`ValueError` exception. + + +.. _bitwise: + +Binary bit-wise operations +========================== + +.. index:: triple: binary; bit-wise; operation + +Each of the three bitwise operations has a different priority level: + +.. productionlist:: + and_expr: `shift_expr` | `and_expr` "&" `shift_expr` + xor_expr: `and_expr` | `xor_expr` "^" `and_expr` + or_expr: `xor_expr` | `or_expr` "|" `xor_expr` + +.. index:: pair: bit-wise; and + +The ``&`` operator yields the bitwise AND of its arguments, which must be plain +or long integers. The arguments are converted to a common type. + +.. index:: + pair: bit-wise; xor + pair: exclusive; or + +The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which +must be plain or long integers. The arguments are converted to a common type. + +.. index:: + pair: bit-wise; or + pair: inclusive; or + +The ``|`` operator yields the bitwise (inclusive) OR of its arguments, which +must be plain or long integers. The arguments are converted to a common type. + + +.. _comparisons: + +Comparisons +=========== + +.. index:: single: comparison + +.. index:: pair: C; language + +Unlike C, all comparison operations in Python have the same priority, which is +lower than that of any arithmetic, shifting or bitwise operation. Also unlike +C, expressions like ``a < b < c`` have the interpretation that is conventional +in mathematics: + +.. productionlist:: + comparison: `or_expr` ( `comp_operator` `or_expr` )* + comp_operator: "<" | ">" | "==" | ">=" | "<=" | "!=" + : | "is" ["not"] | ["not"] "in" + +Comparisons yield boolean values: ``True`` or ``False``. + +.. index:: pair: chaining; comparisons + +Comparisons can be chained arbitrarily, e.g., ``x < y <= z`` is equivalent to +``x < y and y <= z``, except that ``y`` is evaluated only once (but in both +cases ``z`` is not evaluated at all when ``x < y`` is found to be false). + +Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and *opa*, *opb*, ..., +*opy* are comparison operators, then *a opa b opb c* ...*y opy z* is equivalent +to *a opa b* :keyword:`and` *b opb c* :keyword:`and` ... *y opy z*, except that +each expression is evaluated at most once. + +Note that *a opa b opb c* doesn't imply any kind of comparison between *a* and +*c*, so that, e.g., ``x < y > z`` is perfectly legal (though perhaps not +pretty). + +The operators ``<``, ``>``, ``==``, ``>=``, ``<=``, and ``!=`` compare the +values of two objects. The objects need not have the same type. If both are +numbers, they are converted to a common type. Otherwise, objects of different +types *always* compare unequal, and are ordered consistently but arbitrarily. +You can control comparison behavior of objects of non-builtin types by defining +a ``__cmp__`` method or rich comparison methods like ``__gt__``, described in +section :ref:`specialnames`. + +(This unusual definition of comparison was used to simplify the definition of +operations like sorting and the :keyword:`in` and :keyword:`not in` operators. +In the future, the comparison rules for objects of different types are likely to +change.) + +Comparison of objects of the same type depends on the type: + +* Numbers are compared arithmetically. + +* Strings are compared lexicographically using the numeric equivalents (the + result of the built-in function :func:`ord`) of their characters. Unicode and + 8-bit strings are fully interoperable in this behavior. + +* Tuples and lists are compared lexicographically using comparison of + corresponding elements. This means that to compare equal, each element must + compare equal and the two sequences must be of the same type and have the same + length. + + If not equal, the sequences are ordered the same as their first differing + elements. For example, ``cmp([1,2,x], [1,2,y])`` returns the same as + ``cmp(x,y)``. If the corresponding element does not exist, the shorter sequence + is ordered first (for example, ``[1,2] < [1,2,3]``). + +* Mappings (dictionaries) compare equal if and only if their sorted (key, value) + lists compare equal. [#]_ Outcomes other than equality are resolved + consistently, but are not otherwise defined. [#]_ + +* Most other objects of builtin types compare unequal unless they are the same + object; the choice whether one object is considered smaller or larger than + another one is made arbitrarily but consistently within one execution of a + program. + +The operators :keyword:`in` and :keyword:`not in` test for set membership. ``x +in s`` evaluates to true if *x* is a member of the set *s*, and false otherwise. +``x not in s`` returns the negation of ``x in s``. The set membership test has +traditionally been bound to sequences; an object is a member of a set if the set +is a sequence and contains an element equal to that object. However, it is +possible for an object to support membership tests without being a sequence. In +particular, dictionaries support membership testing as a nicer way of spelling +``key in dict``; other mapping types may follow suit. + +For the list and tuple types, ``x in y`` is true if and only if there exists an +index *i* such that ``x == y[i]`` is true. + +For the Unicode and string types, ``x in y`` is true if and only if *x* is a +substring of *y*. An equivalent test is ``y.find(x) != -1``. Note, *x* and *y* +need not be the same type; consequently, ``u'ab' in 'abc'`` will return +``True``. Empty strings are always considered to be a substring of any other +string, so ``"" in "abc"`` will return ``True``. + +.. versionchanged:: 2.3 + Previously, *x* was required to be a string of length ``1``. + +For user-defined classes which define the :meth:`__contains__` method, ``x in +y`` is true if and only if ``y.__contains__(x)`` is true. + +For user-defined classes which do not define :meth:`__contains__` and do define +:meth:`__getitem__`, ``x in y`` is true if and only if there is a non-negative +integer index *i* such that ``x == y[i]``, and all lower integer indices do not +raise :exc:`IndexError` exception. (If any other exception is raised, it is as +if :keyword:`in` raised that exception). + +.. index:: + operator: in + operator: not in + pair: membership; test + object: sequence + +The operator :keyword:`not in` is defined to have the inverse true value of +:keyword:`in`. + +.. index:: + operator: is + operator: is not + pair: identity; test + +The operators :keyword:`is` and :keyword:`is not` test for object identity: ``x +is y`` is true if and only if *x* and *y* are the same object. ``x is not y`` +yields the inverse truth value. + + +.. _booleans: + +Boolean operations +================== + +.. index:: + pair: Conditional; expression + pair: Boolean; operation + +Boolean operations have the lowest priority of all Python operations: + +.. productionlist:: + expression: `conditional_expression` | `lambda_form` + old_expression: `or_test` | `old_lambda_form` + conditional_expression: `or_test` ["if" `or_test` "else" `expression`] + or_test: `and_test` | `or_test` "or" `and_test` + and_test: `not_test` | `and_test` "and" `not_test` + not_test: `comparison` | "not" `not_test` + +In the context of Boolean operations, and also when expressions are used by +control flow statements, the following values are interpreted as false: +``False``, ``None``, numeric zero of all types, and empty strings and containers +(including strings, tuples, lists, dictionaries, sets and frozensets). All +other values are interpreted as true. + +.. index:: operator: not + +The operator :keyword:`not` yields ``True`` if its argument is false, ``False`` +otherwise. + +The expression ``x if C else y`` first evaluates *C* (*not* *x*); if *C* is +true, *x* is evaluated and its value is returned; otherwise, *y* is evaluated +and its value is returned. + +.. versionadded:: 2.5 + +.. index:: operator: and + +The expression ``x and y`` first evaluates *x*; if *x* is false, its value is +returned; otherwise, *y* is evaluated and the resulting value is returned. + +.. index:: operator: or + +The expression ``x or y`` first evaluates *x*; if *x* is true, its value is +returned; otherwise, *y* is evaluated and the resulting value is returned. + +(Note that neither :keyword:`and` nor :keyword:`or` restrict the value and type +they return to ``False`` and ``True``, but rather return the last evaluated +argument. This is sometimes useful, e.g., if ``s`` is a string that should be +replaced by a default value if it is empty, the expression ``s or 'foo'`` yields +the desired value. Because :keyword:`not` has to invent a value anyway, it does +not bother to return a value of the same type as its argument, so e.g., ``not +'foo'`` yields ``False``, not ``''``.) + + +.. _lambdas: + +Lambdas +======= + +.. index:: + pair: lambda; expression + pair: lambda; form + pair: anonymous; function + +.. productionlist:: + lambda_form: "lambda" [`parameter_list`]: `expression` + old_lambda_form: "lambda" [`parameter_list`]: `old_expression` + +Lambda forms (lambda expressions) have the same syntactic position as +expressions. They are a shorthand to create anonymous functions; the expression +``lambda arguments: expression`` yields a function object. The unnamed object +behaves like a function object defined with :: + + def name(arguments): + return expression + +See section :ref:`function` for the syntax of parameter lists. Note that +functions created with lambda forms cannot contain statements or annotations. + +.. _lambda: + + +.. _exprlists: + +Expression lists +================ + +.. index:: pair: expression; list + +.. productionlist:: + expression_list: `expression` ( "," `expression` )* [","] + +.. index:: object: tuple + +An expression list containing at least one comma yields a tuple. The length of +the tuple is the number of expressions in the list. The expressions are +evaluated from left to right. + +.. index:: pair: trailing; comma + +The trailing comma is required only to create a single tuple (a.k.a. a +*singleton*); it is optional in all other cases. A single expression without a +trailing comma doesn't create a tuple, but rather yields the value of that +expression. (To create an empty tuple, use an empty pair of parentheses: +``()``.) + + +.. _evalorder: + +Evaluation order +================ + +.. index:: pair: evaluation; order + +Python evaluates expressions from left to right. Notice that while evaluating an +assignment, the right-hand side is evaluated before the left-hand side. + +In the following lines, expressions will be evaluated in the arithmetic order of +their suffixes:: + + expr1, expr2, expr3, expr4 + (expr1, expr2, expr3, expr4) + {expr1: expr2, expr3: expr4} + expr1 + expr2 * (expr3 - expr4) + func(expr1, expr2, *expr3, **expr4) + expr3, expr4 = expr1, expr2 + + +.. _operator-summary: + +Summary +======= + +.. index:: pair: operator; precedence + +The following table summarizes the operator precedences in Python, from lowest +precedence (least binding) to highest precedence (most binding). Operators in +the same box have the same precedence. Unless the syntax is explicitly given, +operators are binary. Operators in the same box group left to right (except for +comparisons, including tests, which all have the same precedence and chain from +left to right --- see section :ref:`comparisons` --- and exponentiation, which +groups from right to left). + ++----------------------------------------------+-------------------------------------+ +| Operator | Description | ++==============================================+=====================================+ +| :keyword:`lambda` | Lambda expression | ++----------------------------------------------+-------------------------------------+ +| :keyword:`or` | Boolean OR | ++----------------------------------------------+-------------------------------------+ +| :keyword:`and` | Boolean AND | ++----------------------------------------------+-------------------------------------+ +| :keyword:`not` *x* | Boolean NOT | ++----------------------------------------------+-------------------------------------+ +| :keyword:`in`, :keyword:`not` :keyword:`in` | Membership tests | ++----------------------------------------------+-------------------------------------+ +| :keyword:`is`, :keyword:`is not` | Identity tests | ++----------------------------------------------+-------------------------------------+ +| ``<``, ``<=``, ``>``, ``>=``, ``!=``, ``==`` | Comparisons | ++----------------------------------------------+-------------------------------------+ +| ``|`` | Bitwise OR | ++----------------------------------------------+-------------------------------------+ +| ``^`` | Bitwise XOR | ++----------------------------------------------+-------------------------------------+ +| ``&`` | Bitwise AND | ++----------------------------------------------+-------------------------------------+ +| ``<<``, ``>>`` | Shifts | ++----------------------------------------------+-------------------------------------+ +| ``+``, ``-`` | Addition and subtraction | ++----------------------------------------------+-------------------------------------+ +| ``*``, ``/``, ``%`` | Multiplication, division, remainder | ++----------------------------------------------+-------------------------------------+ +| ``+x``, ``-x`` | Positive, negative | ++----------------------------------------------+-------------------------------------+ +| ``~x`` | Bitwise not | ++----------------------------------------------+-------------------------------------+ +| ``**`` | Exponentiation | ++----------------------------------------------+-------------------------------------+ +| ``x.attribute`` | Attribute reference | ++----------------------------------------------+-------------------------------------+ +| ``x[index]`` | Subscription | ++----------------------------------------------+-------------------------------------+ +| ``x[index:index]`` | Slicing | ++----------------------------------------------+-------------------------------------+ +| ``f(arguments...)`` | Function call | ++----------------------------------------------+-------------------------------------+ +| ``(expressions...)`` | Binding or tuple display | ++----------------------------------------------+-------------------------------------+ +| ``[expressions...]`` | List display | ++----------------------------------------------+-------------------------------------+ +| ``{key:datum...}`` | Dictionary display | ++----------------------------------------------+-------------------------------------+ + +.. rubric:: Footnotes + +.. [#] In Python 2.3, a list comprehension "leaks" the control variables of each + ``for`` it contains into the containing scope. However, this behavior is + deprecated, and relying on it will not work once this bug is fixed in a future + release + +.. [#] While ``abs(x%y) < abs(y)`` is true mathematically, for floats it may not be + true numerically due to roundoff. For example, and assuming a platform on which + a Python float is an IEEE 754 double-precision number, in order that ``-1e-100 % + 1e100`` have the same sign as ``1e100``, the computed result is ``-1e-100 + + 1e100``, which is numerically exactly equal to ``1e100``. Function :func:`fmod` + in the :mod:`math` module returns a result whose sign matches the sign of the + first argument instead, and so returns ``-1e-100`` in this case. Which approach + is more appropriate depends on the application. + +.. [#] If x is very close to an exact integer multiple of y, it's possible for + ``floor(x/y)`` to be one larger than ``(x-x%y)/y`` due to rounding. In such + cases, Python returns the latter result, in order to preserve that + ``divmod(x,y)[0] * y + x % y`` be very close to ``x``. + +.. [#] The implementation computes this efficiently, without constructing lists or + sorting. + +.. [#] Earlier versions of Python used lexicographic comparison of the sorted (key, + value) lists, but this was very expensive for the common case of comparing for + equality. An even earlier version of Python compared dictionaries by identity + only, but this caused surprises because people expected to be able to test a + dictionary for emptiness by comparing it to ``{}``. + |