Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 1 | \chapter{Simple statements \label{simple}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 2 | \indexii{simple}{statement} |
| 3 | |
| 4 | Simple statements are comprised within a single logical line. |
| 5 | Several simple statements may occur on a single line separated |
| 6 | by semicolons. The syntax for simple statements is: |
| 7 | |
| 8 | \begin{verbatim} |
| 9 | simple_stmt: expression_stmt |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 10 | | assert_stmt |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 11 | | assignment_stmt |
| 12 | | pass_stmt |
| 13 | | del_stmt |
| 14 | | print_stmt |
| 15 | | return_stmt |
| 16 | | raise_stmt |
| 17 | | break_stmt |
| 18 | | continue_stmt |
| 19 | | import_stmt |
| 20 | | global_stmt |
| 21 | | exec_stmt |
| 22 | \end{verbatim} |
| 23 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 24 | \section{Expression statements \label{exprstmts}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 25 | \indexii{expression}{statement} |
| 26 | |
| 27 | Expression statements are used (mostly interactively) to compute and |
| 28 | write a value, or (usually) to call a procedure (a function that |
| 29 | returns no meaningful result; in Python, procedures return the value |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 30 | \code{None}). Other uses of expression statements are allowed and |
| 31 | occasionally useful. The syntax for an expression statement is: |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 32 | |
| 33 | \begin{verbatim} |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 34 | expression_stmt: expression_list |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 35 | \end{verbatim} |
| 36 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 37 | An expression statement evaluates the expression list (which may be a |
| 38 | single expression). |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 39 | \indexii{expression}{list} |
| 40 | |
| 41 | In interactive mode, if the value is not \code{None}, it is converted |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 42 | to a string using the built-in \function{repr()}\bifuncindex{repr} |
| 43 | function and the resulting string is written to standard output (see |
| 44 | section \ref{print}) on a line by itself. (Expression statements |
| 45 | yielding None are not written, so that procedure calls do not cause |
| 46 | any output.) |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 47 | \ttindex{None} |
| 48 | \indexii{string}{conversion} |
| 49 | \index{output} |
| 50 | \indexii{standard}{output} |
| 51 | \indexii{writing}{values} |
| 52 | \indexii{procedure}{call} |
| 53 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 54 | \section{Assert statements \label{assert}} |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 55 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 56 | Assert statements\stindex{assert} are a convenient way to insert |
| 57 | debugging assertions\indexii{debugging}{assertions} into a program: |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 58 | |
| 59 | \begin{verbatim} |
| 60 | assert_statement: "assert" expression ["," expression] |
| 61 | \end{verbatim} |
| 62 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 63 | The simple form, \samp{assert expression}, is equivalent to |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 64 | |
| 65 | \begin{verbatim} |
| 66 | if __debug__: |
| 67 | if not expression: raise AssertionError |
| 68 | \end{verbatim} |
| 69 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 70 | The extended form, \samp{assert expression1, expression2}, is |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 71 | equivalent to |
| 72 | |
| 73 | \begin{verbatim} |
| 74 | if __debug__: |
| 75 | if not expression1: raise AssertionError, expression2 |
| 76 | \end{verbatim} |
| 77 | |
| 78 | These equivalences assume that \code{__debug__}\ttindex{__debug__} and |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 79 | \exception{AssertionError}\exindex{AssertionError} refer to the built-in |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 80 | variables with those names. In the current implementation, the |
| 81 | built-in variable \code{__debug__} is 1 under normal circumstances, 0 |
| 82 | when optimization is requested (command line option -O). The current |
| 83 | code generator emits no code for an assert statement when optimization |
| 84 | is requested at compile time. Note that it is unnecessary to include |
| 85 | the source code for the expression that failed in the error message; |
| 86 | it will be displayed as part of the stack trace. |
| 87 | |
| 88 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 89 | \section{Assignment statements \label{assignment}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 90 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 91 | Assignment statements\indexii{assignment}{statement} are used to |
| 92 | (re)bind names to values and to modify attributes or items of mutable |
| 93 | objects: |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 94 | \indexii{binding}{name} |
| 95 | \indexii{rebinding}{name} |
| 96 | \obindex{mutable} |
| 97 | \indexii{attribute}{assignment} |
| 98 | |
| 99 | \begin{verbatim} |
| 100 | assignment_stmt: (target_list "=")+ expression_list |
| 101 | target_list: target ("," target)* [","] |
| 102 | target: identifier | "(" target_list ")" | "[" target_list "]" |
| 103 | | attributeref | subscription | slicing |
| 104 | \end{verbatim} |
| 105 | |
| 106 | (See section \ref{primaries} for the syntax definitions for the last |
| 107 | three symbols.) |
| 108 | |
| 109 | An assignment statement evaluates the expression list (remember that |
| 110 | this can be a single expression or a comma-separated list, the latter |
| 111 | yielding a tuple) and assigns the single resulting object to each of |
| 112 | the target lists, from left to right. |
| 113 | \indexii{expression}{list} |
| 114 | |
| 115 | Assignment is defined recursively depending on the form of the target |
| 116 | (list). When a target is part of a mutable object (an attribute |
| 117 | reference, subscription or slicing), the mutable object must |
| 118 | ultimately perform the assignment and decide about its validity, and |
| 119 | may raise an exception if the assignment is unacceptable. The rules |
| 120 | observed by various types and the exceptions raised are given with the |
| 121 | definition of the object types (see section \ref{types}). |
| 122 | \index{target} |
| 123 | \indexii{target}{list} |
| 124 | |
| 125 | Assignment of an object to a target list is recursively defined as |
| 126 | follows. |
| 127 | \indexiii{target}{list}{assignment} |
| 128 | |
| 129 | \begin{itemize} |
| 130 | \item |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 131 | If the target list is a single target: The object is assigned to that |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 132 | target. |
| 133 | |
| 134 | \item |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 135 | If the target list is a comma-separated list of targets: The object |
| 136 | must be a sequence with the same number of items as the there are |
| 137 | targets in the target list, and the items are assigned, from left to |
| 138 | right, to the corresponding targets. (This rule is relaxed as of |
| 139 | Python 1.5; in earlier versions, the object had to be a tuple. Since |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 140 | strings are sequences, an assignment like \samp{a, b = "xy"} is |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 141 | now legal as long as the string has the right length.) |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 142 | |
| 143 | \end{itemize} |
| 144 | |
| 145 | Assignment of an object to a single target is recursively defined as |
| 146 | follows. |
| 147 | |
| 148 | \begin{itemize} % nested |
| 149 | |
| 150 | \item |
| 151 | If the target is an identifier (name): |
| 152 | |
| 153 | \begin{itemize} |
| 154 | |
| 155 | \item |
| 156 | If the name does not occur in a \keyword{global} statement in the current |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 157 | code block: the name is bound to the object in the current local |
| 158 | namespace. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 159 | \stindex{global} |
| 160 | |
| 161 | \item |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 162 | Otherwise: the name is bound to the object in the current global |
| 163 | namespace. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 164 | |
| 165 | \end{itemize} % nested |
| 166 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 167 | The name is rebound if it was already bound. This may cause the |
| 168 | reference count for the object previously bound to the name to reach |
| 169 | zero, causing the object to be deallocated and its |
| 170 | destructor\index{destructor} (if it has one) to be called. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 171 | |
| 172 | \item |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 173 | If the target is a target list enclosed in parentheses or in square |
| 174 | brackets: The object must be a sequence with the same number of items |
| 175 | as there are targets in the target list, and its items are assigned, |
| 176 | from left to right, to the corresponding targets. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 177 | |
| 178 | \item |
| 179 | If the target is an attribute reference: The primary expression in the |
| 180 | reference is evaluated. It should yield an object with assignable |
| 181 | attributes; if this is not the case, \exception{TypeError} is raised. That |
| 182 | object is then asked to assign the assigned object to the given |
| 183 | attribute; if it cannot perform the assignment, it raises an exception |
| 184 | (usually but not necessarily \exception{AttributeError}). |
| 185 | \indexii{attribute}{assignment} |
| 186 | |
| 187 | \item |
| 188 | If the target is a subscription: The primary expression in the |
| 189 | reference is evaluated. It should yield either a mutable sequence |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 190 | object (e.g., a list) or a mapping object (e.g., a dictionary). Next, |
| 191 | the subscript expression is evaluated. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 192 | \indexii{subscription}{assignment} |
| 193 | \obindex{mutable} |
| 194 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 195 | If the primary is a mutable sequence object (e.g., a list), the subscript |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 196 | must yield a plain integer. If it is negative, the sequence's length |
| 197 | is added to it. The resulting value must be a nonnegative integer |
| 198 | less than the sequence's length, and the sequence is asked to assign |
| 199 | the assigned object to its item with that index. If the index is out |
| 200 | of range, \exception{IndexError} is raised (assignment to a subscripted |
| 201 | sequence cannot add new items to a list). |
| 202 | \obindex{sequence} |
| 203 | \obindex{list} |
| 204 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 205 | If the primary is a mapping object (e.g., a dictionary), the subscript must |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 206 | have a type compatible with the mapping's key type, and the mapping is |
| 207 | then asked to create a key/datum pair which maps the subscript to |
| 208 | the assigned object. This can either replace an existing key/value |
| 209 | pair with the same key value, or insert a new key/value pair (if no |
| 210 | key with the same value existed). |
| 211 | \obindex{mapping} |
| 212 | \obindex{dictionary} |
| 213 | |
| 214 | \item |
| 215 | If the target is a slicing: The primary expression in the reference is |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 216 | evaluated. It should yield a mutable sequence object (e.g., a list). The |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 217 | assigned object should be a sequence object of the same type. Next, |
| 218 | the lower and upper bound expressions are evaluated, insofar they are |
| 219 | present; defaults are zero and the sequence's length. The bounds |
| 220 | should evaluate to (small) integers. If either bound is negative, the |
| 221 | sequence's length is added to it. The resulting bounds are clipped to |
| 222 | lie between zero and the sequence's length, inclusive. Finally, the |
| 223 | sequence object is asked to replace the slice with the items of the |
| 224 | assigned sequence. The length of the slice may be different from the |
| 225 | length of the assigned sequence, thus changing the length of the |
| 226 | target sequence, if the object allows it. |
| 227 | \indexii{slicing}{assignment} |
| 228 | |
| 229 | \end{itemize} |
| 230 | |
| 231 | (In the current implementation, the syntax for targets is taken |
| 232 | to be the same as for expressions, and invalid syntax is rejected |
| 233 | during the code generation phase, causing less detailed error |
| 234 | messages.) |
| 235 | |
| 236 | WARNING: Although the definition of assignment implies that overlaps |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 237 | between the left-hand side and the right-hand side are `safe' (e.g., |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 238 | \samp{a, b = b, a} swaps two variables), overlaps \emph{within} the |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 239 | collection of assigned-to variables are not safe! For instance, the |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 240 | following program prints \samp{[0, 2]}: |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 241 | |
| 242 | \begin{verbatim} |
| 243 | x = [0, 1] |
| 244 | i = 0 |
| 245 | i, x[i] = 1, 2 |
| 246 | print x |
| 247 | \end{verbatim} |
| 248 | |
| 249 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 250 | \section{The \keyword{pass} statement \label{pass}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 251 | \stindex{pass} |
| 252 | |
| 253 | \begin{verbatim} |
| 254 | pass_stmt: "pass" |
| 255 | \end{verbatim} |
| 256 | |
| 257 | \keyword{pass} is a null operation --- when it is executed, nothing |
| 258 | happens. It is useful as a placeholder when a statement is |
| 259 | required syntactically, but no code needs to be executed, for example: |
| 260 | \indexii{null}{operation} |
| 261 | |
| 262 | \begin{verbatim} |
| 263 | def f(arg): pass # a function that does nothing (yet) |
| 264 | |
| 265 | class C: pass # a class with no methods (yet) |
| 266 | \end{verbatim} |
| 267 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 268 | \section{The \keyword{del} statement \label{del}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 269 | \stindex{del} |
| 270 | |
| 271 | \begin{verbatim} |
| 272 | del_stmt: "del" target_list |
| 273 | \end{verbatim} |
| 274 | |
| 275 | Deletion is recursively defined very similar to the way assignment is |
| 276 | defined. Rather that spelling it out in full details, here are some |
| 277 | hints. |
| 278 | \indexii{deletion}{target} |
| 279 | \indexiii{deletion}{target}{list} |
| 280 | |
| 281 | Deletion of a target list recursively deletes each target, from left |
| 282 | to right. |
| 283 | |
| 284 | Deletion of a name removes the binding of that name (which must exist) |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 285 | from the local or global namespace, depending on whether the name |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 286 | occurs in a \keyword{global} statement in the same code block. |
| 287 | \stindex{global} |
| 288 | \indexii{unbinding}{name} |
| 289 | |
| 290 | Deletion of attribute references, subscriptions and slicings |
| 291 | is passed to the primary object involved; deletion of a slicing |
| 292 | is in general equivalent to assignment of an empty slice of the |
| 293 | right type (but even this is determined by the sliced object). |
| 294 | \indexii{attribute}{deletion} |
| 295 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 296 | \section{The \keyword{print} statement \label{print}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 297 | \stindex{print} |
| 298 | |
| 299 | \begin{verbatim} |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 300 | print_stmt: "print" [ expression ("," expression)* [","] ] |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 301 | \end{verbatim} |
| 302 | |
Fred Drake | d4c3352 | 1998-10-01 20:39:47 +0000 | [diff] [blame] | 303 | \keyword{print} evaluates each expression in turn and writes the |
| 304 | resulting object to standard output (see below). If an object is not |
| 305 | a string, it is first converted to a string using the rules for string |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 306 | conversions. The (resulting or original) string is then written. A |
Fred Drake | d4c3352 | 1998-10-01 20:39:47 +0000 | [diff] [blame] | 307 | space is written before each object is (converted and) written, unless |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 308 | the output system believes it is positioned at the beginning of a |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 309 | line. This is the case (1) when no characters have yet been written |
| 310 | to standard output, (2) when the last character written to standard |
Fred Drake | d4c3352 | 1998-10-01 20:39:47 +0000 | [diff] [blame] | 311 | output is \character{\e n}, or (3) when the last write operation on |
| 312 | standard output was not a \keyword{print} statement. (In some cases |
| 313 | it may be functional to write an empty string to standard output for |
| 314 | this reason.) |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 315 | \index{output} |
| 316 | \indexii{writing}{values} |
| 317 | |
Fred Drake | d4c3352 | 1998-10-01 20:39:47 +0000 | [diff] [blame] | 318 | A \character{\e n} character is written at the end, unless the |
| 319 | \keyword{print} statement ends with a comma. This is the only action |
| 320 | if the statement contains just the keyword \keyword{print}. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 321 | \indexii{trailing}{comma} |
| 322 | \indexii{newline}{suppression} |
| 323 | |
Fred Drake | dde91f0 | 1998-05-06 20:59:46 +0000 | [diff] [blame] | 324 | Standard output is defined as the file object named \code{stdout} |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 325 | in the built-in module \module{sys}. If no such object exists, or if |
| 326 | it does not have a \method{write()} method, a \exception{RuntimeError} |
| 327 | exception is raised. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 328 | \indexii{standard}{output} |
| 329 | \refbimodindex{sys} |
Fred Drake | 2b3730e | 1998-11-25 17:40:00 +0000 | [diff] [blame] | 330 | \withsubitem{(in module sys)}{\ttindex{stdout}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 331 | \exindex{RuntimeError} |
| 332 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 333 | \section{The \keyword{return} statement \label{return}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 334 | \stindex{return} |
| 335 | |
| 336 | \begin{verbatim} |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 337 | return_stmt: "return" [expression_list] |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 338 | \end{verbatim} |
| 339 | |
| 340 | \keyword{return} may only occur syntactically nested in a function |
| 341 | definition, not within a nested class definition. |
| 342 | \indexii{function}{definition} |
| 343 | \indexii{class}{definition} |
| 344 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 345 | If an expression list is present, it is evaluated, else \code{None} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 346 | is substituted. |
| 347 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 348 | \keyword{return} leaves the current function call with the expression |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 349 | list (or \code{None}) as return value. |
| 350 | |
| 351 | When \keyword{return} passes control out of a \keyword{try} statement |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 352 | with a \keyword{finally} clause, that \keyword{finally} clause is executed |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 353 | before really leaving the function. |
| 354 | \kwindex{finally} |
| 355 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 356 | \section{The \keyword{raise} statement \label{raise}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 357 | \stindex{raise} |
| 358 | |
| 359 | \begin{verbatim} |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 360 | raise_stmt: "raise" [expression ["," expression ["," expression]]] |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 361 | \end{verbatim} |
| 362 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 363 | If no expressions are present, \keyword{raise} re-raises the last |
| 364 | expression that was raised in the current scope. |
| 365 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 366 | Otherwise, \keyword{raise} evaluates its first expression, which must yield |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 367 | a string, class, or instance object. If there is a second expression, |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 368 | this is evaluated, else \code{None} is substituted. If the first |
Guido van Rossum | f5a80a4 | 1998-08-25 14:45:41 +0000 | [diff] [blame] | 369 | expression is a class object, then the second expression may be an |
| 370 | instance of that class or one of its derivatives, and then that |
| 371 | instance is raised. If the second expression is not such an instance, |
| 372 | the given class is instantiated. The argument list for the |
| 373 | instantiation is determined as follows: if the second expression is a |
| 374 | tuple, it is used as the argument list; if it is \code{None}, the |
| 375 | argument list is empty; otherwise, the argument list consists of a |
| 376 | single argument which is the second expression. If the first |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 377 | expression is an instance object, the second expression must be |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 378 | \code{None}. |
| 379 | \index{exception} |
| 380 | \indexii{raising}{exception} |
| 381 | |
Guido van Rossum | f5a80a4 | 1998-08-25 14:45:41 +0000 | [diff] [blame] | 382 | If the first object is a string, it then raises the exception |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 383 | identified by the first object, with the second one (or \code{None}) |
Guido van Rossum | f5a80a4 | 1998-08-25 14:45:41 +0000 | [diff] [blame] | 384 | as its parameter. If the first object is a class or instance, |
| 385 | it raises the exception identified by the class of the instance |
| 386 | determined in the previous step, with the instance as |
| 387 | its parameter. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 388 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 389 | If a third object is present, and it is not \code{None}, it should be |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 390 | a traceback object (see section \ref{traceback}), and it is |
| 391 | substituted instead of the current location as the place where the |
| 392 | exception occurred. This is useful to re-raise an exception |
| 393 | transparently in an except clause. |
| 394 | \obindex{traceback} |
| 395 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 396 | \section{The \keyword{break} statement \label{break}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 397 | \stindex{break} |
| 398 | |
| 399 | \begin{verbatim} |
| 400 | break_stmt: "break" |
| 401 | \end{verbatim} |
| 402 | |
| 403 | \keyword{break} may only occur syntactically nested in a \keyword{for} |
| 404 | or \keyword{while} loop, but not nested in a function or class definition |
| 405 | within that loop. |
| 406 | \stindex{for} |
| 407 | \stindex{while} |
| 408 | \indexii{loop}{statement} |
| 409 | |
| 410 | It terminates the nearest enclosing loop, skipping the optional |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 411 | \keyword{else} clause if the loop has one. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 412 | \kwindex{else} |
| 413 | |
| 414 | If a \keyword{for} loop is terminated by \keyword{break}, the loop control |
| 415 | target keeps its current value. |
| 416 | \indexii{loop control}{target} |
| 417 | |
| 418 | When \keyword{break} passes control out of a \keyword{try} statement |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 419 | with a \keyword{finally} clause, that \keyword{finally} clause is executed |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 420 | before really leaving the loop. |
| 421 | \kwindex{finally} |
| 422 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 423 | \section{The \keyword{continue} statement \label{continue}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 424 | \stindex{continue} |
| 425 | |
| 426 | \begin{verbatim} |
| 427 | continue_stmt: "continue" |
| 428 | \end{verbatim} |
| 429 | |
| 430 | \keyword{continue} may only occur syntactically nested in a \keyword{for} or |
| 431 | \keyword{while} loop, but not nested in a function or class definition or |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 432 | \keyword{try} statement within that loop.\footnote{It may |
| 433 | occur within an \keyword{except} or \keyword{else} clause. The |
| 434 | restriction on occurring in the \keyword{try} clause is implementer's |
| 435 | laziness and will eventually be lifted.} |
| 436 | It continues with the next cycle of the nearest enclosing loop. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 437 | \stindex{for} |
| 438 | \stindex{while} |
| 439 | \indexii{loop}{statement} |
| 440 | \kwindex{finally} |
| 441 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 442 | \section{The \keyword{import} statement \label{import}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 443 | \stindex{import} |
| 444 | |
| 445 | \begin{verbatim} |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 446 | import_stmt: "import" module ("," module)* |
| 447 | | "from" module "import" identifier ("," identifier)* |
| 448 | | "from" module "import" "*" |
| 449 | module: (identifier ".")* identifier |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 450 | \end{verbatim} |
| 451 | |
| 452 | Import statements are executed in two steps: (1) find a module, and |
| 453 | initialize it if necessary; (2) define a name or names in the local |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 454 | namespace (of the scope where the \keyword{import} statement occurs). |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 455 | The first form (without \keyword{from}) repeats these steps for each |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 456 | identifier in the list. The form with \keyword{from} performs step |
| 457 | (1) once, and then performs step (2) repeatedly. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 458 | \indexii{importing}{module} |
| 459 | \indexii{name}{binding} |
| 460 | \kwindex{from} |
Guido van Rossum | b1f97d6 | 1998-12-21 18:57:36 +0000 | [diff] [blame] | 461 | % XXX Need to define what ``initialize'' means here |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 462 | |
| 463 | The system maintains a table of modules that have been initialized, |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 464 | indexed by module name. This table table |
| 465 | accessible as \code{sys.modules}. When a module name is found in |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 466 | this table, step (1) is finished. If not, a search for a module |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 467 | definition is started. When a module is found, it is loaded. Details |
| 468 | of the module searching and loading process are implementation and |
| 469 | platform specific. It generally involves searching for a ``built-in'' |
| 470 | module with the given name and then searching a list of locations |
| 471 | given as \code{sys.path}. |
Fred Drake | 2b3730e | 1998-11-25 17:40:00 +0000 | [diff] [blame] | 472 | \withsubitem{(in module sys)}{\ttindex{modules}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 473 | \ttindex{sys.modules} |
| 474 | \indexii{module}{name} |
| 475 | \indexii{built-in}{module} |
| 476 | \indexii{user-defined}{module} |
| 477 | \refbimodindex{sys} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 478 | \indexii{filename}{extension} |
Fred Drake | dde91f0 | 1998-05-06 20:59:46 +0000 | [diff] [blame] | 479 | \indexiii{module}{search}{path} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 480 | |
| 481 | If a built-in module is found, its built-in initialization code is |
| 482 | executed and step (1) is finished. If no matching file is found, |
| 483 | \exception{ImportError} is raised. If a file is found, it is parsed, |
| 484 | yielding an executable code block. If a syntax error occurs, |
| 485 | \exception{SyntaxError} is raised. Otherwise, an empty module of the given |
| 486 | name is created and inserted in the module table, and then the code |
| 487 | block is executed in the context of this module. Exceptions during |
| 488 | this execution terminate step (1). |
| 489 | \indexii{module}{initialization} |
| 490 | \exindex{SyntaxError} |
| 491 | \exindex{ImportError} |
| 492 | \index{code block} |
| 493 | |
| 494 | When step (1) finishes without raising an exception, step (2) can |
| 495 | begin. |
| 496 | |
| 497 | The first form of \keyword{import} statement binds the module name in the |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 498 | local namespace to the module object, and then goes on to import the |
| 499 | next identifier, if any. The \keyword{from} form does not bind the |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 500 | module name: it goes through the list of identifiers, looks each one |
| 501 | of them up in the module found in step (1), and binds the name in the |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 502 | local namespace to the object thus found. If a name is not found, |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 503 | \exception{ImportError} is raised. If the list of identifiers is replaced |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 504 | by a star (\samp{*}), all names defined in the module are bound, |
| 505 | except those beginning with an underscore (\character{_}). |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 506 | \indexii{name}{binding} |
| 507 | \exindex{ImportError} |
| 508 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 509 | Names bound by \keyword{import} statements may not occur in |
| 510 | \keyword{global} statements in the same scope. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 511 | \stindex{global} |
| 512 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 513 | The \keyword{from} form with \samp{*} may only occur in a module scope. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 514 | \kwindex{from} |
Fred Drake | 2b3730e | 1998-11-25 17:40:00 +0000 | [diff] [blame] | 515 | \stindex{from} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 516 | |
| 517 | (The current implementation does not enforce the latter two |
| 518 | restrictions, but programs should not abuse this freedom, as future |
| 519 | implementations may enforce them or silently change the meaning of the |
| 520 | program.) |
| 521 | |
Fred Drake | 246837d | 1998-07-24 20:28:22 +0000 | [diff] [blame] | 522 | \strong{Hierarchical module names:}\indexiii{hierarchical}{module}{names} |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 523 | when the module names contains one or more dots, the module search |
| 524 | path is carried out differently. The sequence of identifiers up to |
| 525 | the last dot is used to find a ``package''\index{packages}; the final |
| 526 | identifier is then searched inside the package. A package is |
| 527 | generally a subdirectory of a directory on \code{sys.path} that has a |
| 528 | file \file{__init__.py}.\ttindex{__init__.py} |
| 529 | % |
| 530 | [XXX Can't be bothered to spell this out right now; see the URL |
Fred Drake | 1a0b872 | 1998-08-07 17:40:20 +0000 | [diff] [blame] | 531 | \url{http://www.python.org/doc/essays/packages.html} for more details, also |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 532 | about how the module search works from inside a package.] |
| 533 | |
| 534 | [XXX Also should mention __import__().] |
| 535 | \bifuncindex{__import__} |
| 536 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 537 | \section{The \keyword{global} statement \label{global}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 538 | \stindex{global} |
| 539 | |
| 540 | \begin{verbatim} |
| 541 | global_stmt: "global" identifier ("," identifier)* |
| 542 | \end{verbatim} |
| 543 | |
| 544 | The \keyword{global} statement is a declaration which holds for the |
| 545 | entire current code block. It means that the listed identifiers are to be |
Fred Drake | dde91f0 | 1998-05-06 20:59:46 +0000 | [diff] [blame] | 546 | interpreted as globals. While \emph{using} global names is automatic |
| 547 | if they are not defined in the local scope, \emph{assigning} to global |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 548 | names would be impossible without \keyword{global}. |
| 549 | \indexiii{global}{name}{binding} |
| 550 | |
| 551 | Names listed in a \keyword{global} statement must not be used in the same |
Guido van Rossum | b1f97d6 | 1998-12-21 18:57:36 +0000 | [diff] [blame] | 552 | code block textually preceding that \keyword{global} statement. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 553 | |
| 554 | Names listed in a \keyword{global} statement must not be defined as formal |
| 555 | parameters or in a \keyword{for} loop control target, \keyword{class} |
| 556 | definition, function definition, or \keyword{import} statement. |
| 557 | |
| 558 | (The current implementation does not enforce the latter two |
| 559 | restrictions, but programs should not abuse this freedom, as future |
| 560 | implementations may enforce them or silently change the meaning of the |
| 561 | program.) |
| 562 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 563 | \strong{Programmer's note:} |
| 564 | the \keyword{global} is a directive to the parser. It |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 565 | applies only to code parsed at the same time as the \keyword{global} |
| 566 | statement. In particular, a \keyword{global} statement contained in an |
Fred Drake | dde91f0 | 1998-05-06 20:59:46 +0000 | [diff] [blame] | 567 | \keyword{exec} statement does not affect the code block \emph{containing} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 568 | the \keyword{exec} statement, and code contained in an \keyword{exec} |
| 569 | statement is unaffected by \keyword{global} statements in the code |
| 570 | containing the \keyword{exec} statement. The same applies to the |
| 571 | \function{eval()}, \function{execfile()} and \function{compile()} functions. |
| 572 | \stindex{exec} |
| 573 | \bifuncindex{eval} |
| 574 | \bifuncindex{execfile} |
| 575 | \bifuncindex{compile} |
Guido van Rossum | 5f574aa | 1998-07-06 13:18:39 +0000 | [diff] [blame] | 576 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame^] | 577 | \section{The \keyword{exec} statement \label{exec}} |
Guido van Rossum | 5f574aa | 1998-07-06 13:18:39 +0000 | [diff] [blame] | 578 | \stindex{exec} |
| 579 | |
| 580 | \begin{verbatim} |
| 581 | exec_stmt: "exec" expression ["in" expression ["," expression]] |
| 582 | \end{verbatim} |
| 583 | |
| 584 | This statement supports dynamic execution of Python code. The first |
| 585 | expression should evaluate to either a string, an open file object, or |
| 586 | a code object. If it is a string, the string is parsed as a suite of |
| 587 | Python statements which is then executed (unless a syntax error |
| 588 | occurs). If it is an open file, the file is parsed until EOF and |
| 589 | executed. If it is a code object, it is simply executed. |
| 590 | |
| 591 | In all cases, if the optional parts are omitted, the code is executed |
| 592 | in the current scope. If only the first expression after \keyword{in} |
| 593 | is specified, it should be a dictionary, which will be used for both |
| 594 | the global and the local variables. If two expressions are given, |
| 595 | both must be dictionaries and they are used for the global and local |
| 596 | variables, respectively. |
| 597 | |
| 598 | As a side effect, an implementation may insert additional keys into |
| 599 | the dictionaries given besides those corresponding to variable names |
| 600 | set by the executed code. For example, the current implementation |
| 601 | may add a reference to the dictionary of the built-in module |
| 602 | \module{__builtin__} under the key \code{__builtins__} (!). |
| 603 | \ttindex{__builtins__} |
| 604 | \refbimodindex{__builtin__} |
| 605 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 606 | \strong{Programmer's hints:} |
| 607 | dynamic evaluation of expressions is supported by the built-in |
Guido van Rossum | 5f574aa | 1998-07-06 13:18:39 +0000 | [diff] [blame] | 608 | function \function{eval()}. The built-in functions |
| 609 | \function{globals()} and \function{locals()} return the current global |
| 610 | and local dictionary, respectively, which may be useful to pass around |
| 611 | for use by \keyword{exec}. |
| 612 | \bifuncindex{eval} |
| 613 | \bifuncindex{globals} |
| 614 | \bifuncindex{locals} |