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