Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 1 | \chapter{Simple statements} |
| 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 |
| 10 | | assignment_stmt |
| 11 | | pass_stmt |
| 12 | | del_stmt |
| 13 | | print_stmt |
| 14 | | return_stmt |
| 15 | | raise_stmt |
| 16 | | break_stmt |
| 17 | | continue_stmt |
| 18 | | import_stmt |
| 19 | | global_stmt |
Guido van Rossum | a75d306 | 1993-10-18 17:59:42 +0000 | [diff] [blame] | 20 | | access_stmt |
| 21 | | exec_stmt |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 22 | \end{verbatim} |
| 23 | |
| 24 | \section{Expression statements} |
| 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 | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 30 | \verb@None@): |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 31 | |
| 32 | \begin{verbatim} |
Guido van Rossum | 611be70 | 1995-07-07 23:06:33 +0000 | [diff] [blame] | 33 | expression_stmt: condition_list |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 34 | \end{verbatim} |
| 35 | |
Guido van Rossum | 611be70 | 1995-07-07 23:06:33 +0000 | [diff] [blame] | 36 | An expression statement evaluates the condition list (which may be a |
| 37 | single condition). |
| 38 | \indexii{expression}{list} |
| 39 | |
| 40 | In interactive mode, if the value is not \verb@None@, it is converted |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 41 | to a string using the rules for string conversions (expressions in |
| 42 | reverse quotes), and the resulting string is written to standard |
| 43 | output (see section \ref{print}) on a line by itself. |
Guido van Rossum | 611be70 | 1995-07-07 23:06:33 +0000 | [diff] [blame] | 44 | (The exception for \verb@None@ is made so that procedure calls, which |
| 45 | are syntactically equivalent to expressions, do not cause any output.) |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 46 | \ttindex{None} |
| 47 | \indexii{string}{conversion} |
| 48 | \index{output} |
| 49 | \indexii{standard}{output} |
| 50 | \indexii{writing}{values} |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 51 | \indexii{procedure}{call} |
| 52 | |
| 53 | \section{Assignment statements} |
| 54 | \indexii{assignment}{statement} |
| 55 | |
| 56 | Assignment statements are used to (re)bind names to values and to |
| 57 | modify attributes or items of mutable objects: |
| 58 | \indexii{binding}{name} |
| 59 | \indexii{rebinding}{name} |
| 60 | \obindex{mutable} |
| 61 | \indexii{attribute}{assignment} |
| 62 | |
| 63 | \begin{verbatim} |
| 64 | assignment_stmt: (target_list "=")+ expression_list |
| 65 | target_list: target ("," target)* [","] |
| 66 | target: identifier | "(" target_list ")" | "[" target_list "]" |
| 67 | | attributeref | subscription | slicing |
| 68 | \end{verbatim} |
| 69 | |
| 70 | (See section \ref{primaries} for the syntax definitions for the last |
| 71 | three symbols.) |
| 72 | |
| 73 | An assignment statement evaluates the expression list (remember that |
| 74 | this can be a single expression or a comma-separated list, the latter |
| 75 | yielding a tuple) and assigns the single resulting object to each of |
| 76 | the target lists, from left to right. |
| 77 | \indexii{expression}{list} |
| 78 | |
| 79 | Assignment is defined recursively depending on the form of the target |
| 80 | (list). When a target is part of a mutable object (an attribute |
| 81 | reference, subscription or slicing), the mutable object must |
| 82 | ultimately perform the assignment and decide about its validity, and |
| 83 | may raise an exception if the assignment is unacceptable. The rules |
| 84 | observed by various types and the exceptions raised are given with the |
| 85 | definition of the object types (see section \ref{types}). |
| 86 | \index{target} |
| 87 | \indexii{target}{list} |
| 88 | |
| 89 | Assignment of an object to a target list is recursively defined as |
| 90 | follows. |
| 91 | \indexiii{target}{list}{assignment} |
| 92 | |
| 93 | \begin{itemize} |
| 94 | \item |
| 95 | If the target list is a single target: the object is assigned to that |
| 96 | target. |
| 97 | |
| 98 | \item |
| 99 | If the target list is a comma-separated list of targets: the object |
| 100 | must be a tuple with the same number of items as the list contains |
| 101 | targets, and the items are assigned, from left to right, to the |
| 102 | corresponding targets. |
| 103 | |
| 104 | \end{itemize} |
| 105 | |
| 106 | Assignment of an object to a single target is recursively defined as |
| 107 | follows. |
| 108 | |
| 109 | \begin{itemize} % nested |
| 110 | |
| 111 | \item |
| 112 | If the target is an identifier (name): |
| 113 | |
| 114 | \begin{itemize} |
| 115 | |
| 116 | \item |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 117 | If the name does not occur in a \verb@global@ statement in the current |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 118 | code block: the name is bound to the object in the current local name |
| 119 | space. |
| 120 | \stindex{global} |
| 121 | |
| 122 | \item |
| 123 | Otherwise: the name is bound to the object in the current global name |
| 124 | space. |
| 125 | |
| 126 | \end{itemize} % nested |
| 127 | |
| 128 | The name is rebound if it was already bound. |
| 129 | |
| 130 | \item |
| 131 | If the target is a target list enclosed in parentheses: the object is |
| 132 | assigned to that target list as described above. |
| 133 | |
| 134 | \item |
| 135 | If the target is a target list enclosed in square brackets: the object |
| 136 | must be a list with the same number of items as the target list |
| 137 | contains targets, and its items are assigned, from left to right, to |
| 138 | the corresponding targets. |
| 139 | |
| 140 | \item |
| 141 | If the target is an attribute reference: The primary expression in the |
| 142 | reference is evaluated. It should yield an object with assignable |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 143 | attributes; if this is not the case, \verb@TypeError@ is raised. That |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 144 | object is then asked to assign the assigned object to the given |
| 145 | attribute; if it cannot perform the assignment, it raises an exception |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 146 | (usually but not necessarily \verb@AttributeError@). |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 147 | \indexii{attribute}{assignment} |
| 148 | |
| 149 | \item |
| 150 | If the target is a subscription: The primary expression in the |
| 151 | reference is evaluated. It should yield either a mutable sequence |
| 152 | (list) object or a mapping (dictionary) object. Next, the subscript |
| 153 | expression is evaluated. |
| 154 | \indexii{subscription}{assignment} |
| 155 | \obindex{mutable} |
| 156 | |
| 157 | If the primary is a mutable sequence object (a list), the subscript |
| 158 | must yield a plain integer. If it is negative, the sequence's length |
| 159 | is added to it. The resulting value must be a nonnegative integer |
| 160 | less than the sequence's length, and the sequence is asked to assign |
| 161 | the assigned object to its item with that index. If the index is out |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 162 | of range, \verb@IndexError@ is raised (assignment to a subscripted |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 163 | sequence cannot add new items to a list). |
| 164 | \obindex{sequence} |
| 165 | \obindex{list} |
| 166 | |
| 167 | If the primary is a mapping (dictionary) object, the subscript must |
| 168 | have a type compatible with the mapping's key type, and the mapping is |
Guido van Rossum | 31cce97 | 1995-01-04 19:17:34 +0000 | [diff] [blame] | 169 | then asked to create a key/datum pair which maps the subscript to |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 170 | the assigned object. This can either replace an existing key/value |
| 171 | pair with the same key value, or insert a new key/value pair (if no |
| 172 | key with the same value existed). |
| 173 | \obindex{mapping} |
| 174 | \obindex{dictionary} |
| 175 | |
| 176 | \item |
| 177 | If the target is a slicing: The primary expression in the reference is |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 178 | evaluated. It should yield a mutable sequence object (e.g. a list). The |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 179 | assigned object should be a sequence object of the same type. Next, |
| 180 | the lower and upper bound expressions are evaluated, insofar they are |
| 181 | present; defaults are zero and the sequence's length. The bounds |
| 182 | should evaluate to (small) integers. If either bound is negative, the |
| 183 | sequence's length is added to it. The resulting bounds are clipped to |
| 184 | lie between zero and the sequence's length, inclusive. Finally, the |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 185 | sequence object is asked to replace the slice with the items of the |
| 186 | assigned sequence. The length of the slice may be different from the |
| 187 | length of the assigned sequence, thus changing the length of the |
| 188 | target sequence, if the object allows it. |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 189 | \indexii{slicing}{assignment} |
| 190 | |
| 191 | \end{itemize} |
| 192 | |
Guido van Rossum | bd851cd | 1994-08-23 13:26:22 +0000 | [diff] [blame] | 193 | (In the current implementation, the syntax for targets is taken |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 194 | to be the same as for expressions, and invalid syntax is rejected |
| 195 | during the code generation phase, causing less detailed error |
| 196 | messages.) |
| 197 | |
Guido van Rossum | bd851cd | 1994-08-23 13:26:22 +0000 | [diff] [blame] | 198 | WARNING: Although the definition of assignment implies that overlaps |
| 199 | between the left-hand side and the right-hand side are `safe' (e.g. |
| 200 | \verb@a, b = b, a@ swaps two variables), overlaps within the |
| 201 | collection of assigned-to variables are not safe! For instance, the |
| 202 | following program prints \code@[0, 2]@: |
| 203 | |
| 204 | \begin{verbatim} |
| 205 | x = [0, 1] |
| 206 | i = 0 |
| 207 | i, x[i] = 1, 2 |
| 208 | print x |
| 209 | \end{verbatim} |
| 210 | |
| 211 | |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 212 | \section{The {\tt pass} statement} |
| 213 | \stindex{pass} |
| 214 | |
| 215 | \begin{verbatim} |
| 216 | pass_stmt: "pass" |
| 217 | \end{verbatim} |
| 218 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 219 | \verb@pass@ is a null operation --- when it is executed, nothing |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 220 | happens. It is useful as a placeholder when a statement is |
| 221 | required syntactically, but no code needs to be executed, for example: |
| 222 | \indexii{null}{operation} |
| 223 | |
| 224 | \begin{verbatim} |
| 225 | def f(arg): pass # a function that does nothing (yet) |
| 226 | |
Guido van Rossum | 611be70 | 1995-07-07 23:06:33 +0000 | [diff] [blame] | 227 | class C: pass # a class with no methods (yet) |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 228 | \end{verbatim} |
| 229 | |
| 230 | \section{The {\tt del} statement} |
| 231 | \stindex{del} |
| 232 | |
| 233 | \begin{verbatim} |
| 234 | del_stmt: "del" target_list |
| 235 | \end{verbatim} |
| 236 | |
| 237 | Deletion is recursively defined very similar to the way assignment is |
| 238 | defined. Rather that spelling it out in full details, here are some |
| 239 | hints. |
| 240 | \indexii{deletion}{target} |
| 241 | \indexiii{deletion}{target}{list} |
| 242 | |
| 243 | Deletion of a target list recursively deletes each target, from left |
| 244 | to right. |
| 245 | |
| 246 | Deletion of a name removes the binding of that name (which must exist) |
| 247 | from the local or global name space, depending on whether the name |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 248 | occurs in a \verb@global@ statement in the same code block. |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 249 | \stindex{global} |
| 250 | \indexii{unbinding}{name} |
| 251 | |
| 252 | Deletion of attribute references, subscriptions and slicings |
| 253 | is passed to the primary object involved; deletion of a slicing |
| 254 | is in general equivalent to assignment of an empty slice of the |
| 255 | right type (but even this is determined by the sliced object). |
| 256 | \indexii{attribute}{deletion} |
| 257 | |
| 258 | \section{The {\tt print} statement} \label{print} |
| 259 | \stindex{print} |
| 260 | |
| 261 | \begin{verbatim} |
| 262 | print_stmt: "print" [ condition ("," condition)* [","] ] |
| 263 | \end{verbatim} |
| 264 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 265 | \verb@print@ evaluates each condition in turn and writes the resulting |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 266 | object to standard output (see below). If an object is not a string, |
| 267 | it is first converted to a string using the rules for string |
| 268 | conversions. The (resulting or original) string is then written. A |
| 269 | space is written before each object is (converted and) written, unless |
| 270 | the output system believes it is positioned at the beginning of a |
| 271 | line. This is the case: (1) when no characters have yet been written |
| 272 | to standard output; or (2) when the last character written to standard |
| 273 | output is \verb/\n/; or (3) when the last write operation on standard |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 274 | output was not a \verb@print@ statement. (In some cases it may be |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 275 | functional to write an empty string to standard output for this |
| 276 | reason.) |
| 277 | \index{output} |
| 278 | \indexii{writing}{values} |
| 279 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 280 | A \verb/"\n"/ character is written at the end, unless the \verb@print@ |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 281 | statement ends with a comma. This is the only action if the statement |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 282 | contains just the keyword \verb@print@. |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 283 | \indexii{trailing}{comma} |
| 284 | \indexii{newline}{suppression} |
| 285 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 286 | Standard output is defined as the file object named \verb@stdout@ |
| 287 | in the built-in module \verb@sys@. If no such object exists, |
| 288 | or if it is not a writable file, a \verb@RuntimeError@ exception is raised. |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 289 | (The original implementation attempts to write to the system's original |
| 290 | standard output instead, but this is not safe, and should be fixed.) |
| 291 | \indexii{standard}{output} |
| 292 | \bimodindex{sys} |
| 293 | \ttindex{stdout} |
| 294 | \exindex{RuntimeError} |
| 295 | |
| 296 | \section{The {\tt return} statement} |
| 297 | \stindex{return} |
| 298 | |
| 299 | \begin{verbatim} |
| 300 | return_stmt: "return" [condition_list] |
| 301 | \end{verbatim} |
| 302 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 303 | \verb@return@ may only occur syntactically nested in a function |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 304 | definition, not within a nested class definition. |
| 305 | \indexii{function}{definition} |
| 306 | \indexii{class}{definition} |
| 307 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 308 | If a condition list is present, it is evaluated, else \verb@None@ |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 309 | is substituted. |
| 310 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 311 | \verb@return@ leaves the current function call with the condition |
| 312 | list (or \verb@None@) as return value. |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 313 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 314 | When \verb@return@ passes control out of a \verb@try@ statement |
| 315 | with a \verb@finally@ clause, that finally clause is executed |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 316 | before really leaving the function. |
| 317 | \kwindex{finally} |
| 318 | |
| 319 | \section{The {\tt raise} statement} |
| 320 | \stindex{raise} |
| 321 | |
| 322 | \begin{verbatim} |
Guido van Rossum | 611be70 | 1995-07-07 23:06:33 +0000 | [diff] [blame] | 323 | raise_stmt: "raise" condition ["," condition ["," condition]] |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 324 | \end{verbatim} |
| 325 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 326 | \verb@raise@ evaluates its first condition, which must yield |
Guido van Rossum | eb8b0d2 | 1995-02-07 14:37:17 +0000 | [diff] [blame] | 327 | a string, class, or instance object. If there is a second condition, |
| 328 | this is evaluated, else \verb@None@ is substituted. If the first |
| 329 | condition is a class object, then the second condition must be an |
| 330 | instance of that class or one of its derivatives. If the first |
| 331 | condition is an instance object, the second condition must be |
| 332 | \verb@None@. |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 333 | \index{exception} |
| 334 | \indexii{raising}{exception} |
| 335 | |
Guido van Rossum | eb8b0d2 | 1995-02-07 14:37:17 +0000 | [diff] [blame] | 336 | If the first object is a class or string, it then raises the exception |
| 337 | identified by the first object, with the second one (or \verb@None@) |
| 338 | as its parameter. If the first object is an instance, it raises the |
| 339 | exception identified by the class of the object, with the instance as |
Guido van Rossum | 611be70 | 1995-07-07 23:06:33 +0000 | [diff] [blame] | 340 | its parameter (and there should be no second object, or the second |
| 341 | object should be \verb@None@). |
| 342 | |
| 343 | If a third object is present, and it it not \verb@None@, it should be |
| 344 | a traceback object (see section \ref{traceback}), and it is |
| 345 | substituted instead of the current location as the place where the |
| 346 | exception occurred. This is useful to re-raise an exception |
| 347 | transparently in an except clause. |
| 348 | \obindex{traceback} |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 349 | |
| 350 | \section{The {\tt break} statement} |
| 351 | \stindex{break} |
| 352 | |
| 353 | \begin{verbatim} |
| 354 | break_stmt: "break" |
| 355 | \end{verbatim} |
| 356 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 357 | \verb@break@ may only occur syntactically nested in a \verb@for@ |
| 358 | or \verb@while@ loop, but not nested in a function or class definition |
| 359 | within that loop. |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 360 | \stindex{for} |
| 361 | \stindex{while} |
| 362 | \indexii{loop}{statement} |
| 363 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 364 | It terminates the nearest enclosing loop, skipping the optional |
| 365 | \verb@else@ clause if the loop has one. |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 366 | \kwindex{else} |
| 367 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 368 | If a \verb@for@ loop is terminated by \verb@break@, the loop control |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 369 | target keeps its current value. |
| 370 | \indexii{loop control}{target} |
| 371 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 372 | When \verb@break@ passes control out of a \verb@try@ statement |
| 373 | with a \verb@finally@ clause, that finally clause is executed |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 374 | before really leaving the loop. |
| 375 | \kwindex{finally} |
| 376 | |
| 377 | \section{The {\tt continue} statement} |
| 378 | \stindex{continue} |
| 379 | |
| 380 | \begin{verbatim} |
| 381 | continue_stmt: "continue" |
| 382 | \end{verbatim} |
| 383 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 384 | \verb@continue@ may only occur syntactically nested in a \verb@for@ or |
| 385 | \verb@while@ loop, but not nested in a function or class definition or |
| 386 | \verb@try@ statement within that loop.\footnote{Except that it may |
Guido van Rossum | 31cce97 | 1995-01-04 19:17:34 +0000 | [diff] [blame] | 387 | currently occur within an {\tt except} clause.} |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 388 | \stindex{for} |
| 389 | \stindex{while} |
| 390 | \indexii{loop}{statement} |
| 391 | \kwindex{finally} |
| 392 | |
| 393 | It continues with the next cycle of the nearest enclosing loop. |
| 394 | |
| 395 | \section{The {\tt import} statement} \label{import} |
| 396 | \stindex{import} |
| 397 | |
| 398 | \begin{verbatim} |
| 399 | import_stmt: "import" identifier ("," identifier)* |
| 400 | | "from" identifier "import" identifier ("," identifier)* |
| 401 | | "from" identifier "import" "*" |
| 402 | \end{verbatim} |
| 403 | |
| 404 | Import statements are executed in two steps: (1) find a module, and |
| 405 | initialize it if necessary; (2) define a name or names in the local |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 406 | name space (of the scope where the \verb@import@ statement occurs). |
| 407 | The first form (without \verb@from@) repeats these steps for each |
| 408 | identifier in the list, the \verb@from@ form performs them once, with |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 409 | the first identifier specifying the module name. |
| 410 | \indexii{importing}{module} |
| 411 | \indexii{name}{binding} |
| 412 | \kwindex{from} |
| 413 | |
| 414 | The system maintains a table of modules that have been initialized, |
| 415 | indexed by module name. (The current implementation makes this table |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 416 | accessible as \verb@sys.modules@.) When a module name is found in |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 417 | this table, step (1) is finished. If not, a search for a module |
| 418 | definition is started. This first looks for a built-in module |
| 419 | definition, and if no built-in module if the given name is found, it |
| 420 | searches a user-specified list of directories for a file whose name is |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 421 | the module name with extension \verb@".py"@. (The current |
| 422 | implementation uses the list of strings \verb@sys.path@ as the search |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 423 | path; it is initialized from the shell environment variable |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 424 | \verb@$PYTHONPATH@, with an installation-dependent default.) |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 425 | \ttindex{modules} |
| 426 | \ttindex{sys.modules} |
| 427 | \indexii{module}{name} |
| 428 | \indexii{built-in}{module} |
| 429 | \indexii{user-defined}{module} |
| 430 | \bimodindex{sys} |
| 431 | \ttindex{path} |
| 432 | \ttindex{sys.path} |
| 433 | \indexii{filename}{extension} |
| 434 | |
| 435 | If a built-in module is found, its built-in initialization code is |
| 436 | executed and step (1) is finished. If no matching file is found, |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 437 | \verb@ImportError@ is raised. If a file is found, it is parsed, |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 438 | yielding an executable code block. If a syntax error occurs, |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 439 | \verb@SyntaxError@ is raised. Otherwise, an empty module of the given |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 440 | name is created and inserted in the module table, and then the code |
| 441 | block is executed in the context of this module. Exceptions during |
| 442 | this execution terminate step (1). |
| 443 | \indexii{module}{initialization} |
| 444 | \exindex{SyntaxError} |
| 445 | \exindex{ImportError} |
| 446 | \index{code block} |
| 447 | |
| 448 | When step (1) finishes without raising an exception, step (2) can |
| 449 | begin. |
| 450 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 451 | The first form of \verb@import@ statement binds the module name in the |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 452 | local name space to the module object, and then goes on to import the |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 453 | next identifier, if any. The \verb@from@ from does not bind the |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 454 | module name: it goes through the list of identifiers, looks each one |
| 455 | of them up in the module found in step (1), and binds the name in the |
| 456 | local name space to the object thus found. If a name is not found, |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 457 | \verb@ImportError@ is raised. If the list of identifiers is replaced |
| 458 | by a star (\verb@*@), all names defined in the module are bound, |
| 459 | except those beginning with an underscore(\verb@_@). |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 460 | \indexii{name}{binding} |
| 461 | \exindex{ImportError} |
| 462 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 463 | Names bound by import statements may not occur in \verb@global@ |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 464 | statements in the same scope. |
| 465 | \stindex{global} |
| 466 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 467 | The \verb@from@ form with \verb@*@ may only occur in a module scope. |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 468 | \kwindex{from} |
| 469 | \ttindex{from ... import *} |
| 470 | |
| 471 | (The current implementation does not enforce the latter two |
| 472 | restrictions, but programs should not abuse this freedom, as future |
| 473 | implementations may enforce them or silently change the meaning of the |
| 474 | program.) |
| 475 | |
| 476 | \section{The {\tt global} statement} \label{global} |
| 477 | \stindex{global} |
| 478 | |
| 479 | \begin{verbatim} |
| 480 | global_stmt: "global" identifier ("," identifier)* |
| 481 | \end{verbatim} |
| 482 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 483 | The \verb@global@ statement is a declaration which holds for the |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 484 | entire current scope. It means that the listed identifiers are to be |
| 485 | interpreted as globals. While {\em using} global names is automatic |
| 486 | if they are not defined in the local scope, {\em assigning} to global |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 487 | names would be impossible without \verb@global@. |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 488 | \indexiii{global}{name}{binding} |
| 489 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 490 | Names listed in a \verb@global@ statement must not be used in the same |
| 491 | scope before that \verb@global@ statement is executed. |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 492 | |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 493 | Names listed in a \verb@global@ statement must not be defined as formal |
| 494 | parameters or in a \verb@for@ loop control target, \verb@class@ |
| 495 | definition, function definition, or \verb@import@ statement. |
Guido van Rossum | da43a4a | 1992-08-14 09:17:29 +0000 | [diff] [blame] | 496 | |
| 497 | (The current implementation does not enforce the latter two |
| 498 | restrictions, but programs should not abuse this freedom, as future |
| 499 | implementations may enforce them or silently change the meaning of the |
| 500 | program.) |
Guido van Rossum | a75d306 | 1993-10-18 17:59:42 +0000 | [diff] [blame] | 501 | |
| 502 | \section{The {\tt access} statement} \label{access} |
| 503 | \stindex{access} |
| 504 | |
| 505 | \begin{verbatim} |
| 506 | access_stmt: "access" ... |
| 507 | \end{verbatim} |
| 508 | |
Guido van Rossum | c5d0d79 | 1995-10-08 00:52:14 +0000 | [diff] [blame] | 509 | This statement is obsolete. It no longer generates any code; in the |
| 510 | future, \verb@access@ will no longer be a reserved word. |
Guido van Rossum | a75d306 | 1993-10-18 17:59:42 +0000 | [diff] [blame] | 511 | |
| 512 | \section{The {\tt exec} statement} \label{exec} |
| 513 | \stindex{exec} |
| 514 | |
| 515 | \begin{verbatim} |
| 516 | exec_stmt: "exec" expression ["in" expression ["," expression]] |
| 517 | \end{verbatim} |
| 518 | |
| 519 | This statement supports dynamic execution of Python code. The first |
| 520 | expression should evaluate to either a string, an open file object, or |
| 521 | a code object. If it is a string, the string is parsed as a suite of |
| 522 | Python statements which is then executed (unless a syntax error |
| 523 | occurs). If it is an open file, the file is parsed until EOF and |
| 524 | executed. If it is a code object, it is simply executed. |
| 525 | |
| 526 | In all cases, if the optional parts are omitted, the code is executed |
Guido van Rossum | e991496 | 1994-08-01 12:38:14 +0000 | [diff] [blame] | 527 | in the current scope. If only the first expression after \verb@in@ is |
Guido van Rossum | a75d306 | 1993-10-18 17:59:42 +0000 | [diff] [blame] | 528 | specified, it should be a dictionary, which will be used for both the |
| 529 | global and the local variables. If two expressions are given, both |
| 530 | must be dictionaries and they are used for the global and local |
| 531 | variables, respectively. |
| 532 | |
Guido van Rossum | 46f2157 | 1995-03-07 10:09:34 +0000 | [diff] [blame] | 533 | Hints: dynamic evaluation of expressions is supported by the built-in |
Guido van Rossum | 611be70 | 1995-07-07 23:06:33 +0000 | [diff] [blame] | 534 | function \verb@eval()@. The built-in functions \verb@globals()@ and |
| 535 | \verb@locals()@ return the current global and local dictionary, |
| 536 | respectively, which may be useful to pass around for use by \verb@exec@. |