Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 1 | \chapter{Expressions and conditions} |
| 2 | \index{expression} |
| 3 | \index{condition} |
| 4 | |
| 5 | {\bf Note:} In this and the following chapters, extended BNF notation |
| 6 | will be used to describe syntax, not lexical analysis. |
| 7 | \index{BNF} |
| 8 | |
| 9 | This chapter explains the meaning of the elements of expressions and |
| 10 | conditions. Conditions are a superset of expressions, and a condition |
| 11 | may be used wherever an expression is required by enclosing it in |
| 12 | parentheses. The only places where expressions are used in the syntax |
| 13 | instead of conditions is in expression statements and on the |
| 14 | right-hand side of assignment statements; this catches some nasty bugs |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 15 | like accidentally writing \verb@x == 1@ instead of \verb@x = 1@. |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 16 | \indexii{assignment}{statement} |
| 17 | |
| 18 | The comma plays several roles in Python's syntax. It is usually an |
| 19 | operator with a lower precedence than all others, but occasionally |
| 20 | serves other purposes as well; e.g. it separates function arguments, |
| 21 | is used in list and dictionary constructors, and has special semantics |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 22 | in \verb@print@ statements. |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 23 | \index{comma} |
| 24 | |
| 25 | When (one alternative of) a syntax rule has the form |
| 26 | |
| 27 | \begin{verbatim} |
| 28 | name: othername |
| 29 | \end{verbatim} |
| 30 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 31 | and no semantics are given, the semantics of this form of \verb@name@ |
| 32 | are the same as for \verb@othername@. |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 33 | \index{syntax} |
| 34 | |
| 35 | \section{Arithmetic conversions} |
| 36 | \indexii{arithmetic}{conversion} |
| 37 | |
| 38 | When a description of an arithmetic operator below uses the phrase |
| 39 | ``the numeric arguments are converted to a common type'', |
| 40 | this both means that if either argument is not a number, a |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 41 | \verb@TypeError@ exception is raised, and that otherwise |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 42 | the following conversions are applied: |
| 43 | \exindex{TypeError} |
| 44 | \indexii{floating point}{number} |
| 45 | \indexii{long}{integer} |
| 46 | \indexii{plain}{integer} |
| 47 | |
| 48 | \begin{itemize} |
| 49 | \item first, if either argument is a floating point number, |
| 50 | the other is converted to floating point; |
| 51 | \item else, if either argument is a long integer, |
| 52 | the other is converted to long integer; |
| 53 | \item otherwise, both must be plain integers and no conversion |
| 54 | is necessary. |
| 55 | \end{itemize} |
| 56 | |
| 57 | \section{Atoms} |
| 58 | \index{atom} |
| 59 | |
| 60 | Atoms are the most basic elements of expressions. Forms enclosed in |
| 61 | reverse quotes or in parentheses, brackets or braces are also |
| 62 | categorized syntactically as atoms. The syntax for atoms is: |
| 63 | |
| 64 | \begin{verbatim} |
| 65 | atom: identifier | literal | enclosure |
| 66 | enclosure: parenth_form | list_display | dict_display | string_conversion |
| 67 | \end{verbatim} |
| 68 | |
| 69 | \subsection{Identifiers (Names)} |
| 70 | \index{name} |
| 71 | \index{identifier} |
| 72 | |
| 73 | An identifier occurring as an atom is a reference to a local, global |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 74 | or built-in name binding. If a name is assigned to anywhere in a code |
| 75 | block (even in unreachable code), and is not mentioned in a |
| 76 | \verb@global@ statement in that code block, then it refers to a local |
| 77 | name throughout that code block. When it is not assigned to anywhere |
| 78 | in the block, or when it is assigned to but also explicitly listed in |
| 79 | a \verb@global@ statement, it refers to a global name if one exists, |
| 80 | else to a built-in name (and this binding may dynamically change). |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 81 | \indexii{name}{binding} |
| 82 | \index{code block} |
| 83 | \stindex{global} |
| 84 | \indexii{built-in}{name} |
| 85 | \indexii{global}{name} |
| 86 | |
| 87 | When the name is bound to an object, evaluation of the atom yields |
| 88 | that object. When a name is not bound, an attempt to evaluate it |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 89 | raises a \verb@NameError@ exception. |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 90 | \exindex{NameError} |
| 91 | |
| 92 | \subsection{Literals} |
| 93 | \index{literal} |
| 94 | |
| 95 | Python knows string and numeric literals: |
| 96 | |
| 97 | \begin{verbatim} |
| 98 | literal: stringliteral | integer | longinteger | floatnumber |
| 99 | \end{verbatim} |
| 100 | |
| 101 | Evaluation of a literal yields an object of the given type (string, |
| 102 | integer, long integer, floating point number) with the given value. |
| 103 | The value may be approximated in the case of floating point literals. |
| 104 | See section \ref{literals} for details. |
| 105 | |
| 106 | All literals correspond to immutable data types, and hence the |
| 107 | object's identity is less important than its value. Multiple |
| 108 | evaluations of literals with the same value (either the same |
| 109 | occurrence in the program text or a different occurrence) may obtain |
| 110 | the same object or a different object with the same value. |
| 111 | \indexiii{immutable}{data}{type} |
| 112 | |
| 113 | (In the original implementation, all literals in the same code block |
| 114 | with the same type and value yield the same object.) |
| 115 | |
| 116 | \subsection{Parenthesized forms} |
| 117 | \index{parenthesized form} |
| 118 | |
| 119 | A parenthesized form is an optional condition list enclosed in |
| 120 | parentheses: |
| 121 | |
| 122 | \begin{verbatim} |
| 123 | parenth_form: "(" [condition_list] ")" |
| 124 | \end{verbatim} |
| 125 | |
| 126 | A parenthesized condition list yields whatever that condition list |
| 127 | yields. |
| 128 | |
| 129 | An empty pair of parentheses yields an empty tuple object. Since |
| 130 | tuples are immutable, the rules for literals apply here. |
| 131 | \indexii{empty}{tuple} |
| 132 | |
| 133 | (Note that tuples are not formed by the parentheses, but rather by use |
| 134 | of the comma operator. The exception is the empty tuple, for which |
| 135 | parentheses {\em are} required --- allowing unparenthesized ``nothing'' |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 136 | in expressions would cause ambiguities and allow common typos to |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 137 | pass uncaught.) |
| 138 | \index{comma} |
| 139 | \indexii{tuple}{display} |
| 140 | |
| 141 | \subsection{List displays} |
| 142 | \indexii{list}{display} |
| 143 | |
| 144 | A list display is a possibly empty series of conditions enclosed in |
| 145 | square brackets: |
| 146 | |
| 147 | \begin{verbatim} |
| 148 | list_display: "[" [condition_list] "]" |
| 149 | \end{verbatim} |
| 150 | |
| 151 | A list display yields a new list object. |
| 152 | \obindex{list} |
| 153 | |
| 154 | If it has no condition list, the list object has no items. Otherwise, |
| 155 | the elements of the condition list are evaluated from left to right |
| 156 | and inserted in the list object in that order. |
| 157 | \indexii{empty}{list} |
| 158 | |
| 159 | \subsection{Dictionary displays} \label{dict} |
| 160 | \indexii{dictionary}{display} |
| 161 | |
| 162 | A dictionary display is a possibly empty series of key/datum pairs |
| 163 | enclosed in curly braces: |
| 164 | \index{key} |
| 165 | \index{datum} |
| 166 | \index{key/datum pair} |
| 167 | |
| 168 | \begin{verbatim} |
| 169 | dict_display: "{" [key_datum_list] "}" |
| 170 | key_datum_list: key_datum ("," key_datum)* [","] |
| 171 | key_datum: condition ":" condition |
| 172 | \end{verbatim} |
| 173 | |
| 174 | A dictionary display yields a new dictionary object. |
| 175 | \obindex{dictionary} |
| 176 | |
| 177 | The key/datum pairs are evaluated from left to right to define the |
| 178 | entries of the dictionary: each key object is used as a key into the |
| 179 | dictionary to store the corresponding datum. |
| 180 | |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 181 | Restrictions on the types of the key values are listed earlier in |
| 182 | section \ref{types}. |
| 183 | Clashes between duplicate keys are not detected; the last |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 184 | datum (textually rightmost in the display) stored for a given key |
| 185 | value prevails. |
| 186 | \exindex{TypeError} |
| 187 | |
| 188 | \subsection{String conversions} |
| 189 | \indexii{string}{conversion} |
Guido van Rossum | 31cce97 | 1995-01-04 19:17:34 +0000 | [diff] [blame] | 190 | \indexii{reverse}{quotes} |
| 191 | \indexii{backward}{quotes} |
| 192 | \index{back-quotes} |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 193 | |
| 194 | A string conversion is a condition list enclosed in reverse (or |
| 195 | backward) quotes: |
| 196 | |
| 197 | \begin{verbatim} |
| 198 | string_conversion: "`" condition_list "`" |
| 199 | \end{verbatim} |
| 200 | |
| 201 | A string conversion evaluates the contained condition list and |
| 202 | converts the resulting object into a string according to rules |
| 203 | specific to its type. |
| 204 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 205 | If the object is a string, a number, \verb@None@, or a tuple, list or |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 206 | dictionary containing only objects whose type is one of these, the |
| 207 | resulting string is a valid Python expression which can be passed to |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 208 | the built-in function \verb@eval()@ to yield an expression with the |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 209 | same value (or an approximation, if floating point numbers are |
| 210 | involved). |
| 211 | |
| 212 | (In particular, converting a string adds quotes around it and converts |
| 213 | ``funny'' characters to escape sequences that are safe to print.) |
| 214 | |
| 215 | It is illegal to attempt to convert recursive objects (e.g. lists or |
| 216 | dictionaries that contain a reference to themselves, directly or |
| 217 | indirectly.) |
| 218 | \obindex{recursive} |
| 219 | |
Guido van Rossum | 31cce97 | 1995-01-04 19:17:34 +0000 | [diff] [blame] | 220 | The built-in function \verb@repr()@ performs exactly the same |
| 221 | conversion in its argument as enclosing it it reverse quotes does. |
| 222 | The built-in function \verb@str()@ performs a similar but more |
| 223 | user-friendly conversion. |
| 224 | \bifuncindex{repr} |
| 225 | \bifuncindex{str} |
| 226 | |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 227 | \section{Primaries} \label{primaries} |
| 228 | \index{primary} |
| 229 | |
| 230 | Primaries represent the most tightly bound operations of the language. |
| 231 | Their syntax is: |
| 232 | |
| 233 | \begin{verbatim} |
| 234 | primary: atom | attributeref | subscription | slicing | call |
| 235 | \end{verbatim} |
| 236 | |
| 237 | \subsection{Attribute references} |
| 238 | \indexii{attribute}{reference} |
| 239 | |
| 240 | An attribute reference is a primary followed by a period and a name: |
| 241 | |
| 242 | \begin{verbatim} |
| 243 | attributeref: primary "." identifier |
| 244 | \end{verbatim} |
| 245 | |
| 246 | The primary must evaluate to an object of a type that supports |
| 247 | attribute references, e.g. a module or a list. This object is then |
| 248 | asked to produce the attribute whose name is the identifier. If this |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 249 | attribute is not available, the exception \verb@AttributeError@ is |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 250 | raised. Otherwise, the type and value of the object produced is |
| 251 | determined by the object. Multiple evaluations of the same attribute |
| 252 | reference may yield different objects. |
| 253 | \obindex{module} |
| 254 | \obindex{list} |
| 255 | |
| 256 | \subsection{Subscriptions} |
| 257 | \index{subscription} |
| 258 | |
| 259 | A subscription selects an item of a sequence (string, tuple or list) |
| 260 | or mapping (dictionary) object: |
| 261 | \obindex{sequence} |
| 262 | \obindex{mapping} |
| 263 | \obindex{string} |
| 264 | \obindex{tuple} |
| 265 | \obindex{list} |
| 266 | \obindex{dictionary} |
| 267 | \indexii{sequence}{item} |
| 268 | |
| 269 | \begin{verbatim} |
| 270 | subscription: primary "[" condition "]" |
| 271 | \end{verbatim} |
| 272 | |
| 273 | The primary must evaluate to an object of a sequence or mapping type. |
| 274 | |
| 275 | If it is a mapping, the condition must evaluate to an object whose |
| 276 | value is one of the keys of the mapping, and the subscription selects |
| 277 | the value in the mapping that corresponds to that key. |
| 278 | |
| 279 | If it is a sequence, the condition must evaluate to a plain integer. |
| 280 | If this value is negative, the length of the sequence is added to it |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 281 | (so that, e.g. \verb@x[-1]@ selects the last item of \verb@x@.) |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 282 | The resulting value must be a nonnegative integer smaller than the |
| 283 | number of items in the sequence, and the subscription selects the item |
| 284 | whose index is that value (counting from zero). |
| 285 | |
| 286 | A string's items are characters. A character is not a separate data |
| 287 | type but a string of exactly one character. |
| 288 | \index{character} |
| 289 | \indexii{string}{item} |
| 290 | |
| 291 | \subsection{Slicings} |
| 292 | \index{slicing} |
| 293 | \index{slice} |
| 294 | |
| 295 | A slicing (or slice) selects a range of items in a sequence (string, |
| 296 | tuple or list) object: |
| 297 | \obindex{sequence} |
| 298 | \obindex{string} |
| 299 | \obindex{tuple} |
| 300 | \obindex{list} |
| 301 | |
| 302 | \begin{verbatim} |
| 303 | slicing: primary "[" [condition] ":" [condition] "]" |
| 304 | \end{verbatim} |
| 305 | |
| 306 | The primary must evaluate to a sequence object. The lower and upper |
| 307 | bound expressions, if present, must evaluate to plain integers; |
| 308 | defaults are zero and the sequence's length, respectively. If either |
| 309 | bound is negative, the sequence's length is added to it. The slicing |
| 310 | now selects all items with index $k$ such that $i <= k < j$ where $i$ |
| 311 | and $j$ are the specified lower and upper bounds. This may be an |
| 312 | empty sequence. It is not an error if $i$ or $j$ lie outside the |
| 313 | range of valid indexes (such items don't exist so they aren't |
| 314 | selected). |
| 315 | |
| 316 | \subsection{Calls} \label{calls} |
| 317 | \index{call} |
| 318 | |
| 319 | A call calls a callable object (e.g. a function) with a possibly empty |
| 320 | series of arguments: |
| 321 | \obindex{callable} |
| 322 | |
| 323 | \begin{verbatim} |
| 324 | call: primary "(" [condition_list] ")" |
| 325 | \end{verbatim} |
| 326 | |
| 327 | The primary must evaluate to a callable object (user-defined |
| 328 | functions, built-in functions, methods of built-in objects, class |
| 329 | objects, and methods of class instances are callable). If it is a |
| 330 | class, the argument list must be empty; otherwise, the arguments are |
| 331 | evaluated. |
| 332 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 333 | A call always returns some value, possibly \verb@None@, unless it |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 334 | raises an exception. How this value is computed depends on the type |
| 335 | of the callable object. If it is: |
| 336 | |
| 337 | \begin{description} |
| 338 | |
| 339 | \item[a user-defined function:] the code block for the function is |
| 340 | executed, passing it the argument list. The first thing the code |
| 341 | block will do is bind the formal parameters to the arguments; this is |
| 342 | described in section \ref{function}. When the code block executes a |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 343 | \verb@return@ statement, this specifies the return value of the |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 344 | function call. |
| 345 | \indexii{function}{call} |
| 346 | \indexiii{user-defined}{function}{call} |
| 347 | \obindex{user-defined function} |
| 348 | \obindex{function} |
| 349 | |
| 350 | \item[a built-in function or method:] the result is up to the |
| 351 | interpreter; see the library reference manual for the descriptions of |
| 352 | built-in functions and methods. |
| 353 | \indexii{function}{call} |
| 354 | \indexii{built-in function}{call} |
| 355 | \indexii{method}{call} |
| 356 | \indexii{built-in method}{call} |
| 357 | \obindex{built-in method} |
| 358 | \obindex{built-in function} |
| 359 | \obindex{method} |
| 360 | \obindex{function} |
| 361 | |
| 362 | \item[a class object:] a new instance of that class is returned. |
| 363 | \obindex{class} |
| 364 | \indexii{class object}{call} |
| 365 | |
| 366 | \item[a class instance method:] the corresponding user-defined |
| 367 | function is called, with an argument list that is one longer than the |
| 368 | argument list of the call: the instance becomes the first argument. |
| 369 | \obindex{class instance} |
| 370 | \obindex{instance} |
| 371 | \indexii{instance}{call} |
| 372 | \indexii{class instance}{call} |
| 373 | |
| 374 | \end{description} |
| 375 | |
| 376 | \section{Unary arithmetic operations} |
| 377 | \indexiii{unary}{arithmetic}{operation} |
| 378 | \indexiii{unary}{bit-wise}{operation} |
| 379 | |
| 380 | All unary arithmetic (and bit-wise) operations have the same priority: |
| 381 | |
| 382 | \begin{verbatim} |
| 383 | u_expr: primary | "-" u_expr | "+" u_expr | "~" u_expr |
| 384 | \end{verbatim} |
| 385 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 386 | The unary \verb@"-"@ (minus) operator yields the negation of its |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 387 | numeric argument. |
| 388 | \index{negation} |
| 389 | \index{minus} |
| 390 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 391 | The unary \verb@"+"@ (plus) operator yields its numeric argument |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 392 | unchanged. |
| 393 | \index{plus} |
| 394 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 395 | The unary \verb@"~"@ (invert) operator yields the bit-wise inversion |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 396 | of its plain or long integer argument. The bit-wise inversion of |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 397 | \verb@x@ is defined as \verb@-(x+1)@. |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 398 | \index{inversion} |
| 399 | |
| 400 | In all three cases, if the argument does not have the proper type, |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 401 | a \verb@TypeError@ exception is raised. |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 402 | \exindex{TypeError} |
| 403 | |
| 404 | \section{Binary arithmetic operations} |
| 405 | \indexiii{binary}{arithmetic}{operation} |
| 406 | |
| 407 | The binary arithmetic operations have the conventional priority |
| 408 | levels. Note that some of these operations also apply to certain |
| 409 | non-numeric types. There is no ``power'' operator, so there are only |
| 410 | two levels, one for multiplicative operators and one for additive |
| 411 | operators: |
| 412 | |
| 413 | \begin{verbatim} |
| 414 | m_expr: u_expr | m_expr "*" u_expr |
| 415 | | m_expr "/" u_expr | m_expr "%" u_expr |
| 416 | a_expr: m_expr | aexpr "+" m_expr | aexpr "-" m_expr |
| 417 | \end{verbatim} |
| 418 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 419 | The \verb@"*"@ (multiplication) operator yields the product of its |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 420 | arguments. The arguments must either both be numbers, or one argument |
| 421 | must be a plain integer and the other must be a sequence. In the |
| 422 | former case, the numbers are converted to a common type and then |
| 423 | multiplied together. In the latter case, sequence repetition is |
| 424 | performed; a negative repetition factor yields an empty sequence. |
| 425 | \index{multiplication} |
| 426 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 427 | The \verb@"/"@ (division) operator yields the quotient of its |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 428 | arguments. The numeric arguments are first converted to a common |
| 429 | type. Plain or long integer division yields an integer of the same |
| 430 | type; the result is that of mathematical division with the `floor' |
| 431 | function applied to the result. Division by zero raises the |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 432 | \verb@ZeroDivisionError@ exception. |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 433 | \exindex{ZeroDivisionError} |
| 434 | \index{division} |
| 435 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 436 | The \verb@"%"@ (modulo) operator yields the remainder from the |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 437 | division of the first argument by the second. The numeric arguments |
| 438 | are first converted to a common type. A zero right argument raises |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 439 | the \verb@ZeroDivisionError@ exception. The arguments may be floating |
| 440 | point numbers, e.g. \verb@3.14 % 0.7@ equals \verb@0.34@. The modulo |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 441 | operator always yields a result with the same sign as its second |
| 442 | operand (or zero); the absolute value of the result is strictly |
| 443 | smaller than the second operand. |
| 444 | \index{modulo} |
| 445 | |
| 446 | The integer division and modulo operators are connected by the |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 447 | following identity: \verb@x == (x/y)*y + (x%y)@. Integer division and |
| 448 | modulo are also connected with the built-in function \verb@divmod()@: |
| 449 | \verb@divmod(x, y) == (x/y, x%y)@. These identities don't hold for |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 450 | floating point numbers; there a similar identity holds where |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 451 | \verb@x/y@ is replaced by \verb@floor(x/y)@). |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 452 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 453 | The \verb@"+"@ (addition) operator yields the sum of its arguments. |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 454 | The arguments must either both be numbers, or both sequences of the |
| 455 | same type. In the former case, the numbers are converted to a common |
| 456 | type and then added together. In the latter case, the sequences are |
| 457 | concatenated. |
| 458 | \index{addition} |
| 459 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 460 | The \verb@"-"@ (subtraction) operator yields the difference of its |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 461 | arguments. The numeric arguments are first converted to a common |
| 462 | type. |
| 463 | \index{subtraction} |
| 464 | |
| 465 | \section{Shifting operations} |
| 466 | \indexii{shifting}{operation} |
| 467 | |
| 468 | The shifting operations have lower priority than the arithmetic |
| 469 | operations: |
| 470 | |
| 471 | \begin{verbatim} |
| 472 | shift_expr: a_expr | shift_expr ( "<<" | ">>" ) a_expr |
| 473 | \end{verbatim} |
| 474 | |
| 475 | These operators accept plain or long integers as arguments. The |
| 476 | arguments are converted to a common type. They shift the first |
| 477 | argument to the left or right by the number of bits given by the |
| 478 | second argument. |
| 479 | |
| 480 | A right shift by $n$ bits is defined as division by $2^n$. A left |
| 481 | shift by $n$ bits is defined as multiplication with $2^n$; for plain |
| 482 | integers there is no overflow check so this drops bits and flip the |
| 483 | sign if the result is not less than $2^{31}$ in absolute value. |
| 484 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 485 | Negative shift counts raise a \verb@ValueError@ exception. |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 486 | \exindex{ValueError} |
| 487 | |
| 488 | \section{Binary bit-wise operations} |
| 489 | \indexiii{binary}{bit-wise}{operation} |
| 490 | |
| 491 | Each of the three bitwise operations has a different priority level: |
| 492 | |
| 493 | \begin{verbatim} |
| 494 | and_expr: shift_expr | and_expr "&" shift_expr |
| 495 | xor_expr: and_expr | xor_expr "^" and_expr |
| 496 | or_expr: xor_expr | or_expr "|" xor_expr |
| 497 | \end{verbatim} |
| 498 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 499 | The \verb@"&"@ operator yields the bitwise AND of its arguments, which |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 500 | must be plain or long integers. The arguments are converted to a |
| 501 | common type. |
| 502 | \indexii{bit-wise}{and} |
| 503 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 504 | The \verb@"^"@ operator yields the bitwise XOR (exclusive OR) of its |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 505 | arguments, which must be plain or long integers. The arguments are |
| 506 | converted to a common type. |
| 507 | \indexii{bit-wise}{xor} |
| 508 | \indexii{exclusive}{or} |
| 509 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 510 | The \verb@"|"@ operator yields the bitwise (inclusive) OR of its |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 511 | arguments, which must be plain or long integers. The arguments are |
| 512 | converted to a common type. |
| 513 | \indexii{bit-wise}{or} |
| 514 | \indexii{inclusive}{or} |
| 515 | |
| 516 | \section{Comparisons} |
| 517 | \index{comparison} |
| 518 | |
| 519 | Contrary to C, all comparison operations in Python have the same |
| 520 | priority, which is lower than that of any arithmetic, shifting or |
| 521 | bitwise operation. Also contrary to C, expressions like |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 522 | \verb@a < b < c@ have the interpretation that is conventional in |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 523 | mathematics: |
| 524 | \index{C} |
| 525 | |
| 526 | \begin{verbatim} |
| 527 | comparison: or_expr (comp_operator or_expr)* |
| 528 | comp_operator: "<"|">"|"=="|">="|"<="|"<>"|"!="|"is" ["not"]|["not"] "in" |
| 529 | \end{verbatim} |
| 530 | |
| 531 | Comparisons yield integer values: 1 for true, 0 for false. |
| 532 | |
| 533 | Comparisons can be chained arbitrarily, e.g. $x < y <= z$ is |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 534 | equivalent to $x < y$ \verb@and@ $y <= z$, except that $y$ is |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 535 | evaluated only once (but in both cases $z$ is not evaluated at all |
| 536 | when $x < y$ is found to be false). |
| 537 | \indexii{chaining}{comparisons} |
| 538 | |
Guido van Rossum | 4ac605e | 1992-12-17 15:31:02 +0000 | [diff] [blame] | 539 | \catcode`\_=8 |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 540 | Formally, $e_0 op_1 e_1 op_2 e_2 ...e_{n-1} op_n e_n$ is equivalent to |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 541 | $e_0 op_1 e_1$ \verb@and@ $e_1 op_2 e_2$ \verb@and@ ... \verb@and@ |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 542 | $e_{n-1} op_n e_n$, except that each expression is evaluated at most once. |
| 543 | |
| 544 | Note that $e_0 op_1 e_1 op_2 e_2$ does not imply any kind of comparison |
| 545 | between $e_0$ and $e_2$, e.g. $x < y > z$ is perfectly legal. |
Guido van Rossum | 4ac605e | 1992-12-17 15:31:02 +0000 | [diff] [blame] | 546 | \catcode`\_=12 |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 547 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 548 | The forms \verb@<>@ and \verb@!=@ are equivalent; for consistency with |
| 549 | C, \verb@!=@ is preferred; where \verb@!=@ is mentioned below |
| 550 | \verb@<>@ is also implied. |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 551 | |
| 552 | The operators {\tt "<", ">", "==", ">=", "<="}, and {\tt "!="} compare |
| 553 | the values of two objects. The objects needn't have the same type. |
| 554 | If both are numbers, they are coverted to a common type. Otherwise, |
| 555 | objects of different types {\em always} compare unequal, and are |
| 556 | ordered consistently but arbitrarily. |
| 557 | |
| 558 | (This unusual definition of comparison is done to simplify the |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 559 | definition of operations like sorting and the \verb@in@ and |
| 560 | \verb@not in@ operators.) |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 561 | |
| 562 | Comparison of objects of the same type depends on the type: |
| 563 | |
| 564 | \begin{itemize} |
| 565 | |
| 566 | \item |
| 567 | Numbers are compared arithmetically. |
| 568 | |
| 569 | \item |
| 570 | Strings are compared lexicographically using the numeric equivalents |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 571 | (the result of the built-in function \verb@ord@) of their characters. |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 572 | |
| 573 | \item |
| 574 | Tuples and lists are compared lexicographically using comparison of |
| 575 | corresponding items. |
| 576 | |
| 577 | \item |
| 578 | Mappings (dictionaries) are compared through lexicographic |
| 579 | comparison of their sorted (key, value) lists.% |
| 580 | \footnote{This is expensive since it requires sorting the keys first, |
Guido van Rossum | b2c6556 | 1993-05-12 08:53:36 +0000 | [diff] [blame] | 581 | but about the only sensible definition. An earlier version of Python |
| 582 | compared dictionaries by identity only, but this caused surprises |
| 583 | because people expected to be able to test a dictionary for emptiness |
| 584 | by comparing it to {\tt \{\}}.} |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 585 | |
| 586 | \item |
| 587 | Most other types compare unequal unless they are the same object; |
| 588 | the choice whether one object is considered smaller or larger than |
| 589 | another one is made arbitrarily but consistently within one |
| 590 | execution of a program. |
| 591 | |
| 592 | \end{itemize} |
| 593 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 594 | The operators \verb@in@ and \verb@not in@ test for sequence |
| 595 | membership: if $y$ is a sequence, $x ~\verb@in@~ y$ is true if and |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 596 | only if there exists an index $i$ such that $x = y[i]$. |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 597 | $x ~\verb@not in@~ y$ yields the inverse truth value. The exception |
| 598 | \verb@TypeError@ is raised when $y$ is not a sequence, or when $y$ is |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 599 | a string and $x$ is not a string of length one.% |
| 600 | \footnote{The latter restriction is sometimes a nuisance.} |
| 601 | \opindex{in} |
| 602 | \opindex{not in} |
| 603 | \indexii{membership}{test} |
| 604 | \obindex{sequence} |
| 605 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 606 | The operators \verb@is@ and \verb@is not@ test for object identity: |
| 607 | $x ~\verb@is@~ y$ is true if and only if $x$ and $y$ are the same |
| 608 | object. $x ~\verb@is not@~ y$ yields the inverse truth value. |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 609 | \opindex{is} |
| 610 | \opindex{is not} |
| 611 | \indexii{identity}{test} |
| 612 | |
| 613 | \section{Boolean operations} \label{Booleans} |
| 614 | \indexii{Boolean}{operation} |
| 615 | |
| 616 | Boolean operations have the lowest priority of all Python operations: |
| 617 | |
| 618 | \begin{verbatim} |
Guido van Rossum | 3cbc16d | 1993-12-17 12:13:53 +0000 | [diff] [blame] | 619 | condition: or_test | lambda_form |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 620 | or_test: and_test | or_test "or" and_test |
| 621 | and_test: not_test | and_test "and" not_test |
| 622 | not_test: comparison | "not" not_test |
Guido van Rossum | 3cbc16d | 1993-12-17 12:13:53 +0000 | [diff] [blame] | 623 | lambda_form: "lambda" [parameter_list]: condition |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 624 | \end{verbatim} |
| 625 | |
| 626 | In the context of Boolean operations, and also when conditions are |
| 627 | used by control flow statements, the following values are interpreted |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 628 | as false: \verb@None@, numeric zero of all types, empty sequences |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 629 | (strings, tuples and lists), and empty mappings (dictionaries). All |
| 630 | other values are interpreted as true. |
| 631 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 632 | The operator \verb@not@ yields 1 if its argument is false, 0 otherwise. |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 633 | \opindex{not} |
| 634 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 635 | The condition $x ~\verb@and@~ y$ first evaluates $x$; if $x$ is false, |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 636 | its value is returned; otherwise, $y$ is evaluated and the resulting |
| 637 | value is returned. |
| 638 | \opindex{and} |
| 639 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 640 | The condition $x ~\verb@or@~ y$ first evaluates $x$; if $x$ is true, |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 641 | its value is returned; otherwise, $y$ is evaluated and the resulting |
| 642 | value is returned. |
| 643 | \opindex{or} |
| 644 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 645 | (Note that \verb@and@ and \verb@or@ do not restrict the value and type |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 646 | they return to 0 and 1, but rather return the last evaluated argument. |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 647 | This is sometimes useful, e.g. if \verb@s@ is a string that should be |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 648 | replaced by a default value if it is empty, the expression |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 649 | \verb@s or 'foo'@ yields the desired value. Because \verb@not@ has to |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 650 | invent a value anyway, it does not bother to return a value of the |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 651 | same type as its argument, so e.g. \verb@not 'foo'@ yields \verb@0@, |
| 652 | not \verb@''@.) |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 653 | |
Guido van Rossum | 3cbc16d | 1993-12-17 12:13:53 +0000 | [diff] [blame] | 654 | Lambda forms (lambda expressions) have the same syntactic position as |
| 655 | conditions. They are a shorthand to create anonymous functions; the |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 656 | expression {\em {\tt lambda} arguments{\tt :} condition} |
Guido van Rossum | 3cbc16d | 1993-12-17 12:13:53 +0000 | [diff] [blame] | 657 | yields a function object that behaves virtually identical to one |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 658 | defined with |
| 659 | {\em {\tt def} name {\tt (}arguments{\tt ): return} condition}. |
| 660 | See section \ref{function} for the syntax of |
Guido van Rossum | 3cbc16d | 1993-12-17 12:13:53 +0000 | [diff] [blame] | 661 | parameter lists. Note that functions created with lambda forms cannot |
| 662 | contain statements. |
| 663 | \label{lambda} |
| 664 | \indexii{lambda}{expression} |
| 665 | \indexii{lambda}{form} |
| 666 | \indexii{anonmymous}{function} |
| 667 | |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 668 | \section{Expression lists and condition lists} |
| 669 | \indexii{expression}{list} |
| 670 | \indexii{condition}{list} |
| 671 | |
| 672 | \begin{verbatim} |
| 673 | expr_list: or_expr ("," or_expr)* [","] |
| 674 | cond_list: condition ("," condition)* [","] |
| 675 | \end{verbatim} |
| 676 | |
| 677 | The only difference between expression lists and condition lists is |
| 678 | the lowest priority of operators that can be used in them without |
| 679 | being enclosed in parentheses; condition lists allow all operators, |
| 680 | while expression lists don't allow comparisons and Boolean operators |
| 681 | (they do allow bitwise and shift operators though). |
| 682 | |
| 683 | Expression lists are used in expression statements and assignments; |
| 684 | condition lists are used everywhere else where a list of |
| 685 | comma-separated values is required. |
| 686 | |
| 687 | An expression (condition) list containing at least one comma yields a |
| 688 | tuple. The length of the tuple is the number of expressions |
| 689 | (conditions) in the list. The expressions (conditions) are evaluated |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 690 | from left to right. (Condition lists are used syntactically is a few |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 691 | places where no tuple is constructed but a list of values is needed |
| 692 | nevertheless.) |
| 693 | \obindex{tuple} |
| 694 | |
| 695 | The trailing comma is required only to create a single tuple (a.k.a. a |
| 696 | {\em singleton}); it is optional in all other cases. A single |
| 697 | expression (condition) without a trailing comma doesn't create a |
| 698 | tuple, but rather yields the value of that expression (condition). |
| 699 | \indexii{trailing}{comma} |
| 700 | |
| 701 | (To create an empty tuple, use an empty pair of parentheses: |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 702 | \verb@()@.) |