| \chapter{Expressions\label{expressions}} |
| \index{expression} |
| |
| This chapter explains the meaning of the elements of expressions in |
| Python. |
| |
| \strong{Syntax Notes:} In this and the following chapters, extended |
| BNF\index{BNF} notation will be used to describe syntax, not lexical |
| analysis. When (one alternative of) a syntax rule has the form |
| |
| \begin{verbatim} |
| name: othername |
| \end{verbatim} |
| |
| and no semantics are given, the semantics of this form of \code{name} |
| are the same as for \code{othername}. |
| \index{syntax} |
| |
| \section{Arithmetic conversions\label{conversions}} |
| \indexii{arithmetic}{conversion} |
| |
| 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 listed at the end of |
| chapter 3. If both arguments are standard numeric types, the |
| following coercions are applied: |
| |
| \begin{itemize} |
| \item If either argument is a complex number, the other is converted |
| to complex; |
| \item otherwise, if either argument is a floating point number, |
| the other is converted to floating point; |
| \item otherwise, if either argument is a long integer, |
| the other is converted to long integer; |
| \item otherwise, both must be plain integers and no conversion |
| is necessary. |
| \end{itemize} |
| |
| Some additional rules apply for certain operators (e.g., a string left |
| argument to the `\%' operator). Extensions can define their own |
| coercions. |
| |
| |
| \section{Atoms\label{atoms}} |
| \index{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: |
| |
| \begin{verbatim} |
| atom: identifier | literal | enclosure |
| enclosure: parenth_form|list_display|dict_display|string_conversion |
| \end{verbatim} |
| |
| \subsection{Identifiers (Names)\label{atom-identifiers}} |
| \index{name} |
| \index{identifier} |
| |
| An identifier occurring as an atom is a reference to a local, global |
| or built-in name binding. If a name is assigned to anywhere in a code |
| block (even in unreachable code), and is not mentioned in a |
| \keyword{global} statement in that code block, then it refers to a local |
| name throughout that code block. When it is not assigned to anywhere |
| in the block, or when it is assigned to but also explicitly listed in |
| a \keyword{global} statement, it refers to a global name if one exists, |
| else to a built-in name (and this binding may dynamically change). |
| \indexii{name}{binding} |
| \index{code block} |
| \stindex{global} |
| \indexii{built-in}{name} |
| \indexii{global}{name} |
| |
| 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 \exception{NameError} exception. |
| \exindex{NameError} |
| |
| \strong{Private name mangling:}% |
| \indexii{name}{mangling}% |
| \indexii{private}{names}% |
| 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 \code{__spam} occurring in a class named \code{Ham} will be |
| transformed to \code{_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. |
| |
| \subsection{Literals\label{atom-literals}} |
| \index{literal} |
| |
| Python supports string literals and various numeric literals: |
| |
| \begin{verbatim} |
| literal: stringliteral | integer | longinteger | floatnumber | imagnumber |
| \end{verbatim} |
| |
| 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. |
| |
| 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. |
| \indexiii{immutable}{data}{type} |
| \indexii{immutable}{object} |
| |
| \subsection{Parenthesized forms\label{parenthesized}} |
| \index{parenthesized form} |
| |
| A parenthesized form is an optional expression list enclosed in |
| parentheses: |
| |
| \begin{verbatim} |
| parenth_form: "(" [expression_list] ")" |
| \end{verbatim} |
| |
| 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. |
| |
| 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). |
| \indexii{empty}{tuple} |
| |
| 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 \emph{are} required --- allowing unparenthesized ``nothing'' |
| in expressions would cause ambiguities and allow common typos to |
| pass uncaught. |
| \index{comma} |
| \indexii{tuple}{display} |
| |
| \subsection{List displays\label{lists}} |
| \indexii{list}{display} |
| |
| A list display is a possibly empty series of expressions enclosed in |
| square brackets: |
| |
| \begin{verbatim} |
| list_display: "[" [listmaker] "]" |
| listmaker: expression ( list_for | ( "," expression)* [","] ) |
| list_iter: list_for | list_if |
| list_for: "for" expression_list "in" testlist [list_iter] |
| list_if: "if" test [list_iter] |
| \end{verbatim} |
| |
| 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. |
| \obindex{list} |
| \indexii{empty}{list} |
| |
| \subsection{Dictionary displays\label{dict}} |
| \indexii{dictionary}{display} |
| |
| A dictionary display is a possibly empty series of key/datum pairs |
| enclosed in curly braces: |
| \index{key} |
| \index{datum} |
| \index{key/datum pair} |
| |
| \begin{verbatim} |
| dict_display: "{" [key_datum_list] "}" |
| key_datum_list: key_datum ("," key_datum)* [","] |
| key_datum: expression ":" expression |
| \end{verbatim} |
| |
| A dictionary display yields a new dictionary object. |
| \obindex{dictionary} |
| |
| 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. |
| |
| 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. |
| \indexii{immutable}{object} |
| |
| \subsection{String conversions\label{string-conversions}} |
| \indexii{string}{conversion} |
| \indexii{reverse}{quotes} |
| \indexii{backward}{quotes} |
| \index{back-quotes} |
| |
| A string conversion is an expression list enclosed in reverse (a.k.a. |
| backward) quotes: |
| |
| \begin{verbatim} |
| string_conversion: "`" expression_list "`" |
| \end{verbatim} |
| |
| A string conversion evaluates the contained expression list and |
| converts the resulting object into a string according to rules |
| specific to its type. |
| |
| If the object is a string, a number, \code{None}, or a tuple, list or |
| dictionary containing only objects whose type is one of these, the |
| resulting string is a valid Python expression which can be passed to |
| the built-in function \function{eval()} to yield an expression with the |
| same value (or an approximation, if floating point numbers are |
| involved). |
| |
| (In particular, converting a string adds quotes around it and converts |
| ``funny'' characters to escape sequences that are safe to print.) |
| |
| It is illegal to attempt to convert recursive objects (e.g., lists or |
| dictionaries that contain a reference to themselves, directly or |
| indirectly.) |
| \obindex{recursive} |
| |
| The built-in function \function{repr()} performs exactly the same |
| conversion in its argument as enclosing it in parentheses and reverse |
| quotes does. The built-in function \function{str()} performs a |
| similar but more user-friendly conversion. |
| \bifuncindex{repr} |
| \bifuncindex{str} |
| |
| \section{Primaries\label{primaries}} |
| \index{primary} |
| |
| Primaries represent the most tightly bound operations of the language. |
| Their syntax is: |
| |
| \begin{verbatim} |
| primary: atom | attributeref | subscription | slicing | call |
| \end{verbatim} |
| |
| \subsection{Attribute references\label{attribute-references}} |
| \indexii{attribute}{reference} |
| |
| An attribute reference is a primary followed by a period and a name: |
| |
| \begin{verbatim} |
| attributeref: primary "." identifier |
| \end{verbatim} |
| |
| The primary must evaluate to an object of a type that supports |
| attribute references, e.g., a module or a list. This object is then |
| asked to produce the attribute whose name is the identifier. If this |
| attribute is not available, the exception |
| \exception{AttributeError}\exindex{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. |
| \obindex{module} |
| \obindex{list} |
| |
| \subsection{Subscriptions\label{subscriptions}} |
| \index{subscription} |
| |
| A subscription selects an item of a sequence (string, tuple or list) |
| or mapping (dictionary) object: |
| \obindex{sequence} |
| \obindex{mapping} |
| \obindex{string} |
| \obindex{tuple} |
| \obindex{list} |
| \obindex{dictionary} |
| \indexii{sequence}{item} |
| |
| \begin{verbatim} |
| subscription: primary "[" expression_list "]" |
| \end{verbatim} |
| |
| 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., \code{x[-1]} selects the last item of |
| \code{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). |
| |
| A string's items are characters. A character is not a separate data |
| type but a string of exactly one character. |
| \index{character} |
| \indexii{string}{item} |
| |
| \subsection{Slicings\label{slicings}} |
| \index{slicing} |
| \index{slice} |
| |
| 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 del statements. The syntax for a slicing: |
| \obindex{sequence} |
| \obindex{string} |
| \obindex{tuple} |
| \obindex{list} |
| |
| \begin{verbatim} |
| 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: "..." |
| \end{verbatim} |
| |
| 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.\indexii{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 |
| \code{sys.maxint}, respectively. If either bound is negative, the |
| sequence's length is added to it. The slicing now selects all items |
| with index \var{k} such that |
| \code{\var{i} <= \var{k} < \var{j}} where \var{i} |
| and \var{j} are the specified lower and upper bounds. This may be an |
| empty sequence. It is not an error if \var{i} or \var{j} lie outside the |
| range of valid indexes (such items don't exist so they aren't |
| selected). |
| |
| 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 an ellipsis slice |
| item is the built-in \code{Ellipsis} object. The conversion of a |
| proper slice is a slice object (see section \ref{types}) whose |
| \member{start}, \member{stop} and \member{step} attributes are the |
| values of the expressions given as lower bound, upper bound and |
| stride, respectively, substituting \code{None} for missing |
| expressions. |
| \withsubitem{(slice object attribute)}{\ttindex{start} |
| \ttindex{stop}\ttindex{step}} |
| |
| \subsection{Calls\label{calls}} |
| \index{call} |
| |
| A call calls a callable object (e.g., a function) with a possibly empty |
| series of arguments: |
| \obindex{callable} |
| |
| \begin{verbatim} |
| call: primary "(" [argument_list [","]] ")" |
| argument_list: positional_arguments ["," keyword_arguments] |
| | keyword_arguments |
| positional_arguments: expression ("," expression)* |
| keyword_arguments: keyword_item ("," keyword_item)* |
| keyword_item: identifier "=" expression |
| \end{verbatim} |
| |
| A trailing comma may be present after an argument list 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 \exception{TypeError} exception is raised. |
| Otherwise, the value of the argument is placed in the slot, filling it |
| (even if the expression is \code{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 \exception{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 \exception{TypeError} exception is raised, unless a formal |
| parameter using the syntax \samp{*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 \exception{TypeError} exception is raised, unless a formal |
| parameter using the syntax \samp{**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. |
| |
| Formal parameters using the syntax \samp{*identifier} or |
| \samp{**identifier} cannot be used as positional argument slots or |
| as keyword argument names. Formal parameters using the syntax |
| \samp{(sublist)} cannot be used as keyword argument names; the |
| outermost sublist corresponds to a single unnamed argument slot, and |
| the argument value is assigned to the sublist using the usual tuple |
| assignment rules after all other parameter processing is done. |
| |
| A call always returns some value, possibly \code{None}, unless it |
| raises an exception. How this value is computed depends on the type |
| of the callable object. |
| |
| If it is--- |
| |
| \begin{description} |
| |
| \item[a user-defined 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. |
| \indexii{function}{call} |
| \indexiii{user-defined}{function}{call} |
| \obindex{user-defined function} |
| \obindex{function} |
| |
| \item[a built-in function or method:] The result is up to the |
| interpreter; see the \citetitle[../lib/built-in-funcs.html]{Python |
| Library Reference} for the descriptions of built-in functions and |
| methods. |
| \indexii{function}{call} |
| \indexii{built-in function}{call} |
| \indexii{method}{call} |
| \indexii{built-in method}{call} |
| \obindex{built-in method} |
| \obindex{built-in function} |
| \obindex{method} |
| \obindex{function} |
| |
| \item[a class object:] A new instance of that class is returned. |
| \obindex{class} |
| \indexii{class object}{call} |
| |
| \item[a class instance method:] 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. |
| \obindex{class instance} |
| \obindex{instance} |
| \indexii{class instance}{call} |
| |
| \item[a class instance:] The class must define a \method{__call__()} |
| method; the effect is then the same as if that method was called. |
| \indexii{instance}{call} |
| \withsubitem{(object method)}{\ttindex{__call__()}} |
| |
| \end{description} |
| |
| |
| \section{The power operator\label{power}} |
| |
| 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: |
| |
| \begin{verbatim} |
| power: primary ["**" u_expr] |
| \end{verbatim} |
| |
| 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 |
| \function{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; if the result is not |
| expressible in that type (as in raising an integer to a negative |
| power, or a negative floating point number to a broken power), a |
| \exception{TypeError} exception is raised. |
| |
| |
| \section{Unary arithmetic operations \label{unary}} |
| \indexiii{unary}{arithmetic}{operation} |
| \indexiii{unary}{bit-wise}{operation} |
| |
| All unary arithmetic (and bit-wise) operations have the same priority: |
| |
| \begin{verbatim} |
| u_expr: power | "-" u_expr | "+" u_expr | "~" u_expr |
| \end{verbatim} |
| |
| The unary \code{-} (minus) operator yields the negation of its |
| numeric argument. |
| \index{negation} |
| \index{minus} |
| |
| The unary \code{+} (plus) operator yields its numeric argument |
| unchanged. |
| \index{plus} |
| |
| The unary \code{\~} (invert) operator yields the bit-wise inversion |
| of its plain or long integer argument. The bit-wise inversion of |
| \code{x} is defined as \code{-(x+1)}. It only applies to integral |
| numbers. |
| \index{inversion} |
| |
| In all three cases, if the argument does not have the proper type, |
| a \exception{TypeError} exception is raised. |
| \exindex{TypeError} |
| |
| \section{Binary arithmetic operations\label{binary}} |
| \indexiii{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: |
| |
| \begin{verbatim} |
| m_expr: u_expr | m_expr "*" u_expr |
| | m_expr "/" u_expr | m_expr "%" u_expr |
| a_expr: m_expr | aexpr "+" m_expr | aexpr "-" m_expr |
| \end{verbatim} |
| |
| The \code{*} (multiplication) operator yields the product of its |
| arguments. The arguments must either both be numbers, or one argument |
| must be a plain integer 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{multiplication} |
| |
| The \code{/} (division) operator yields the quotient of its |
| 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 |
| \exception{ZeroDivisionError} exception. |
| \exindex{ZeroDivisionError} |
| \index{division} |
| |
| The \code{\%} (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 \exception{ZeroDivisionError} exception. The arguments may be floating |
| point numbers, e.g., \code{3.14\%0.7} equals \code{0.34} (since |
| \code{3.14} equals \code{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 second |
| operand. |
| \index{modulo} |
| |
| The integer division and modulo operators are connected by the |
| following identity: \code{x == (x/y)*y + (x\%y)}. Integer division and |
| modulo are also connected with the built-in function \function{divmod()}: |
| \code{divmod(x, y) == (x/y, x\%y)}. These identities don't hold for |
| floating point and complex numbers; there similar identities hold |
| approximately where \code{x/y} is replaced by \code{floor(x/y)}) or |
| \code{floor(x/y) - 1} (for floats),\footnote{ |
| If x is very close to an exact integer multiple of y, it's |
| possible for \code{floor(x/y)} to be one larger than |
| \code{(x-x\%y)/y} due to rounding. In such cases, Python returns |
| the latter result, in order to preserve that \code{divmod(x,y)[0] |
| * y + x \%{} y} be very close to \code{x}. |
| } or \code{floor((x/y).real)} (for |
| complex). |
| |
| The \code{+} (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{addition} |
| |
| The \code{-} (subtraction) operator yields the difference of its |
| arguments. The numeric arguments are first converted to a common |
| type. |
| \index{subtraction} |
| |
| \section{Shifting operations\label{shifting}} |
| \indexii{shifting}{operation} |
| |
| The shifting operations have lower priority than the arithmetic |
| operations: |
| |
| \begin{verbatim} |
| shift_expr: a_expr | shift_expr ( "<<" | ">>" ) a_expr |
| \end{verbatim} |
| |
| 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. |
| |
| A right shift by \var{n} bits is defined as division by |
| \code{pow(2,\var{n})}. A left shift by \var{n} bits is defined as |
| multiplication with \code{pow(2,\var{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 \code{pow(2,31)} in absolute |
| value. Negative shift counts raise a \exception{ValueError} |
| exception. |
| \exindex{ValueError} |
| |
| \section{Binary bit-wise operations\label{bitwise}} |
| \indexiii{binary}{bit-wise}{operation} |
| |
| Each of the three bitwise operations has a different priority level: |
| |
| \begin{verbatim} |
| and_expr: shift_expr | and_expr "&" shift_expr |
| xor_expr: and_expr | xor_expr "^" and_expr |
| or_expr: xor_expr | or_expr "|" xor_expr |
| \end{verbatim} |
| |
| The \code{\&} operator yields the bitwise AND of its arguments, which |
| must be plain or long integers. The arguments are converted to a |
| common type. |
| \indexii{bit-wise}{and} |
| |
| The \code{\^} 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. |
| \indexii{bit-wise}{xor} |
| \indexii{exclusive}{or} |
| |
| The \code{|} operator yields the bitwise (inclusive) OR of its |
| arguments, which must be plain or long integers. The arguments are |
| converted to a common type. |
| \indexii{bit-wise}{or} |
| \indexii{inclusive}{or} |
| |
| \section{Comparisons\label{comparisons}} |
| \index{comparison} |
| |
| Contrary to \C, all comparison operations in Python have the same |
| priority, which is lower than that of any arithmetic, shifting or |
| bitwise operation. Also contrary to \C, expressions like |
| \code{a < b < c} have the interpretation that is conventional in |
| mathematics: |
| \indexii{C}{language} |
| |
| \begin{verbatim} |
| comparison: or_expr (comp_operator or_expr)* |
| comp_operator: "<"|">"|"=="|">="|"<="|"<>"|"!="|"is" ["not"]|["not"] "in" |
| \end{verbatim} |
| |
| Comparisons yield integer values: \code{1} for true, \code{0} for false. |
| |
| Comparisons can be chained arbitrarily, e.g., \code{x < y <= z} is |
| equivalent to \code{x < y and y <= z}, except that \code{y} is |
| evaluated only once (but in both cases \code{z} is not evaluated at all |
| when \code{x < y} is found to be false). |
| \indexii{chaining}{comparisons} |
| |
| Formally, if \var{a}, \var{b}, \var{c}, \ldots, \var{y}, \var{z} are |
| expressions and \var{opa}, \var{opb}, \ldots, \var{opy} are comparison |
| operators, then \var{a opa b opb c} \ldots \var{y opy z} is equivalent |
| to \var{a opa b} \keyword{and} \var{b opb c} \keyword{and} \ldots |
| \var{y opy z}, except that each expression is evaluated at most once. |
| |
| Note that \var{a opa b opb c} doesn't imply any kind of comparison |
| between \var{a} and \var{c}, so that, e.g., \code{x < y > z} is |
| perfectly legal (though perhaps not pretty). |
| |
| The forms \code{<>} and \code{!=} are equivalent; for consistency with |
| C, \code{!=} is preferred; where \code{!=} is mentioned below |
| \code{<>} is also acceptable. At some point in the (far) future, |
| \code{<>} may become obsolete. |
| |
| The operators \texttt{"<", ">", "==", ">=", "<="}, and \texttt{"!="} compare |
| the values of two objects. The objects needn't have the same type. |
| If both are numbers, they are coverted to a common type. Otherwise, |
| objects of different types \emph{always} compare unequal, and are |
| ordered consistently but arbitrarily. |
| |
| (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: |
| |
| \begin{itemize} |
| |
| \item |
| Numbers are compared arithmetically. |
| |
| \item |
| Strings are compared lexicographically using the numeric equivalents |
| (the result of the built-in function \function{ord()}) of their |
| characters. |
| |
| \item |
| Tuples and lists are compared lexicographically using comparison of |
| corresponding items. |
| |
| \item |
| Mappings (dictionaries) are compared through lexicographic |
| comparison of their sorted (key, value) lists.\footnote{ |
| This is expensive since it requires sorting the keys first, |
| but it is about the only sensible definition. An 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 \code{\{\}}.} |
| |
| \item |
| Most other 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. |
| |
| \end{itemize} |
| |
| The operators \keyword{in} and \keyword{not in} test for set |
| membership: every type can define membership in whatever way is |
| appropriate. Traditionally, this interface has been tightly bound |
| the sequence interface, which is related in that presence in a sequence |
| can be usefully interpreted as membership in a set. |
| |
| For the list, tuple types, \code{\var{x} in \var{y}} is true if and only |
| if there exists such an index \var{i} such that |
| \code{var{x} == \var{y}[\var{i}]} is true. |
| |
| For the Unicode and string types, \code{\var{x} in \var{y}} is true if and only |
| if there exists such an index \var{i} such that |
| \code{var{x} == \var{y}[\var{i}]} is true. If \code{\var{x}} is not |
| a string of length \code{1} or a unicode object of length \code{1}, |
| a \exception{TypeError} exception is raised. |
| |
| For user-defined classes which define the \method{__contains__()} method, |
| \code{\var{x} in \var{y}} is true if and only if |
| \code{\var{y}.__contains__(\var{x})} is true. |
| |
| For user-defined classes which do not define \method{__contains__()} and |
| do define \var{__getitem__}, \code{\var{x} in \var{y}} is true if and only |
| if there is a non-negative integer index \var{i} such that |
| \code{\var{x} == \var{y}[\var{i}]}, and all lower integer indices |
| do not raise \exception{IndexError} exception. (If any other exception |
| is raised, it is as if \keyword{in} raised that exception). |
| |
| The operator \keyword{not in} is defined to have the inverse true value |
| of \keyword{in}. |
| \opindex{in} |
| \opindex{not in} |
| \indexii{membership}{test} |
| \obindex{sequence} |
| |
| The operators \keyword{is} and \keyword{is not} test for object identity: |
| \code{\var{x} is \var{y}} is true if and only if \var{x} and \var{y} |
| are the same object. \code{\var{x} is not \var{y}} yields the inverse |
| truth value. |
| \opindex{is} |
| \opindex{is not} |
| \indexii{identity}{test} |
| |
| \section{Boolean operations\label{Booleans}} |
| \indexii{Boolean}{operation} |
| |
| Boolean operations have the lowest priority of all Python operations: |
| |
| \begin{verbatim} |
| expression: or_test | lambda_form |
| or_test: and_test | or_test "or" and_test |
| and_test: not_test | and_test "and" not_test |
| not_test: comparison | "not" not_test |
| lambda_form: "lambda" [parameter_list]: expression |
| \end{verbatim} |
| |
| In the context of Boolean operations, and also when expressions are |
| used by control flow statements, the following values are interpreted |
| as false: \code{None}, numeric zero of all types, empty sequences |
| (strings, tuples and lists), and empty mappings (dictionaries). All |
| other values are interpreted as true. |
| |
| The operator \keyword{not} yields \code{1} if its argument is false, |
| \code{0} otherwise. |
| \opindex{not} |
| |
| The expression \code{\var{x} and \var{y}} first evaluates \var{x}; if |
| \var{x} is false, its value is returned; otherwise, \var{y} is |
| evaluated and the resulting value is returned. |
| \opindex{and} |
| |
| The expression \code{\var{x} or \var{y}} first evaluates \var{x}; if |
| \var{x} is true, its value is returned; otherwise, \var{y} is |
| evaluated and the resulting value is returned. |
| \opindex{or} |
| |
| (Note that neither \keyword{and} nor \keyword{or} restrict the value |
| and type they return to \code{0} and \code{1}, but rather return the |
| last evaluated argument. |
| This is sometimes useful, e.g., if \code{s} is a string that should be |
| replaced by a default value if it is empty, the expression |
| \code{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., \code{not 'foo'} yields \code{0}, |
| not \code{''}.) |
| |
| Lambda forms (lambda expressions) have the same syntactic position as |
| expressions. They are a shorthand to create anonymous functions; the |
| expression \code{lambda \var{arguments}: \var{expression}} |
| yields a function object that behaves virtually identical to one |
| defined with |
| |
| \begin{verbatim} |
| def name(arguments): |
| return expression |
| \end{verbatim} |
| |
| See section \ref{function} for the syntax of parameter lists. Note |
| that functions created with lambda forms cannot contain statements. |
| \label{lambda} |
| \indexii{lambda}{expression} |
| \indexii{lambda}{form} |
| \indexii{anonmymous}{function} |
| |
| \strong{Programmer's note:} a lambda form defined inside a function |
| has no access to names defined in the function's namespace. This is |
| because Python has only two scopes: local and global. A common |
| work-around is to use default argument values to pass selected |
| variables into the lambda's namespace, e.g.: |
| |
| \begin{verbatim} |
| def make_incrementor(increment): |
| return lambda x, n=increment: x+n |
| \end{verbatim} |
| |
| \section{Expression lists\label{exprlists}} |
| \indexii{expression}{list} |
| |
| \begin{verbatim} |
| expression_list: expression ("," expression)* [","] |
| \end{verbatim} |
| |
| 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. |
| \obindex{tuple} |
| |
| The trailing comma is required only to create a single tuple (a.k.a. a |
| \emph{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: |
| \code{()}.) |
| \indexii{trailing}{comma} |
| |
| |
| \section{Summary\label{summary}} |
| |
| The following table summarizes the operator |
| precedences\indexii{operator}{precedence} 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, which chain from left to |
| right --- see above). |
| |
| \begin{tableii}{c|l}{textrm}{Operator}{Description} |
| \lineii{\keyword{lambda}} {Lambda expression} |
| \hline |
| \lineii{\keyword{or}} {Boolean OR} |
| \hline |
| \lineii{\keyword{and}} {Boolean AND} |
| \hline |
| \lineii{\keyword{not} \var{x}} {Boolean NOT} |
| \hline |
| \lineii{\keyword{in}, \keyword{not} \keyword{in}}{Membership tests} |
| \lineii{\keyword{is}, \keyword{is not}}{Identity tests} |
| \lineii{\code{<}, \code{<=}, \code{>}, \code{>=}, |
| \code{<>}, \code{!=}, \code{==}} |
| {Comparisons} |
| \hline |
| \lineii{\code{|}} {Bitwise OR} |
| \hline |
| \lineii{\code{\^}} {Bitwise XOR} |
| \hline |
| \lineii{\code{\&}} {Bitwise AND} |
| \hline |
| \lineii{\code{<<}, \code{>>}} {Shifts} |
| \hline |
| \lineii{\code{+}, \code{-}}{Addition and subtraction} |
| \hline |
| \lineii{\code{*}, \code{/}, \code{\%}} |
| {Multiplication, division, remainder} |
| \hline |
| \lineii{\code{**}} {Exponentiation} |
| \hline |
| \lineii{\code{+\var{x}}, \code{-\var{x}}} {Positive, negative} |
| \lineii{\code{\~\var{x}}} {Bitwise not} |
| \hline |
| \lineii{\code{\var{x}.\var{attribute}}} {Attribute reference} |
| \lineii{\code{\var{x}[\var{index}]}} {Subscription} |
| \lineii{\code{\var{x}[\var{index}:\var{index}]}} {Slicing} |
| \lineii{\code{\var{f}(\var{arguments}...)}} {Function call} |
| \hline |
| \lineii{\code{(\var{expressions}\ldots)}} {Binding or tuple display} |
| \lineii{\code{[\var{expressions}\ldots]}} {List display} |
| \lineii{\code{\{\var{key}:\var{datum}\ldots\}}}{Dictionary display} |
| \lineii{\code{`\var{expressions}\ldots`}} {String conversion} |
| \end{tableii} |