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} |
Fred Drake | 5381588 | 2002-03-15 23:21:37 +0000 | [diff] [blame] | 9 | \production{simple_stmt}{\token{expression_stmt}} |
| 10 | \productioncont{| \token{assert_stmt}} |
| 11 | \productioncont{| \token{assignment_stmt}} |
| 12 | \productioncont{| \token{augmented_assignment_stmt}} |
| 13 | \productioncont{| \token{pass_stmt}} |
| 14 | \productioncont{| \token{del_stmt}} |
| 15 | \productioncont{| \token{print_stmt}} |
| 16 | \productioncont{| \token{return_stmt}} |
| 17 | \productioncont{| \token{yield_stmt}} |
| 18 | \productioncont{| \token{raise_stmt}} |
| 19 | \productioncont{| \token{break_stmt}} |
| 20 | \productioncont{| \token{continue_stmt}} |
| 21 | \productioncont{| \token{import_stmt}} |
| 22 | \productioncont{| \token{global_stmt}} |
| 23 | \productioncont{| \token{exec_stmt}} |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 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 |
Fred Drake | c2f496a | 2001-12-05 05:46:25 +0000 | [diff] [blame] | 48 | section~\ref{print}) on a line by itself. (Expression statements |
| 49 | yielding \code{None} are not written, so that procedure calls do not |
| 50 | cause 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} |
Fred Drake | 007fadd | 2003-03-31 14:53:03 +0000 | [diff] [blame] | 65 | \production{assert_stmt} |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 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} |
Fred Drake | 5381588 | 2002-03-15 23:21:37 +0000 | [diff] [blame] | 114 | {\token{identifier}} |
| 115 | \productioncont{| "(" \token{target_list} ")"} |
| 116 | \productioncont{| "[" \token{target_list} "]"} |
| 117 | \productioncont{| \token{attributeref}} |
| 118 | \productioncont{| \token{subscription}} |
| 119 | \productioncont{| \token{slicing}} |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 120 | \end{productionlist} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 121 | |
Fred Drake | c2f496a | 2001-12-05 05:46:25 +0000 | [diff] [blame] | 122 | (See section~\ref{primaries} for the syntax definitions for the last |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 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 |
Fred Drake | c2f496a | 2001-12-05 05:46:25 +0000 | [diff] [blame] | 137 | definition of the object types (see section~\ref{types}). |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 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 | 5381588 | 2002-03-15 23:21:37 +0000 | [diff] [blame] | 266 | \subsection{Augmented assignment statements \label{augassign}} |
Fred Drake | 31f5550 | 2000-09-12 20:32:18 +0000 | [diff] [blame] | 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} |
Fred Drake | 5381588 | 2002-03-15 23:21:37 +0000 | [diff] [blame] | 277 | {"+=" | "-=" | "*=" | "/=" | "\%=" | "**="} |
| 278 | \productioncont{| ">>=" | "<<=" | "\&=" | "\textasciicircum=" | "|="} |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 279 | \end{productionlist} |
Fred Drake | 31f5550 | 2000-09-12 20:32:18 +0000 | [diff] [blame] | 280 | |
Fred Drake | c2f496a | 2001-12-05 05:46:25 +0000 | [diff] [blame] | 281 | (See section~\ref{primaries} for the syntax definitions for the last |
Fred Drake | 31f5550 | 2000-09-12 20:32:18 +0000 | [diff] [blame] | 282 | three symbols.) |
| 283 | |
Fred Drake | d68442b | 2000-09-21 22:01:36 +0000 | [diff] [blame] | 284 | An augmented assignment evaluates the target (which, unlike normal |
| 285 | assignment statements, cannot be an unpacking) and the expression |
| 286 | list, performs the binary operation specific to the type of assignment |
| 287 | on the two operands, and assigns the result to the original |
| 288 | target. The target is only evaluated once. |
Fred Drake | 31f5550 | 2000-09-12 20:32:18 +0000 | [diff] [blame] | 289 | |
| 290 | An augmented assignment expression like \code{x += 1} can be rewritten as |
| 291 | \code{x = x + 1} to achieve a similar, but not exactly equal effect. In the |
| 292 | augmented version, \code{x} is only evaluated once. Also, when possible, the |
| 293 | actual operation is performed \emph{in-place}, meaning that rather than |
| 294 | creating a new object and assigning that to the target, the old object is |
| 295 | modified instead. |
| 296 | |
| 297 | With the exception of assigning to tuples and multiple targets in a single |
| 298 | statement, the assignment done by augmented assignment statements is handled |
| 299 | the same way as normal assignments. Similarly, with the exception of the |
Fred Drake | c2f496a | 2001-12-05 05:46:25 +0000 | [diff] [blame] | 300 | possible \emph{in-place} behavior, the binary operation performed by |
Fred Drake | 31f5550 | 2000-09-12 20:32:18 +0000 | [diff] [blame] | 301 | augmented assignment is the same as the normal binary operations. |
| 302 | |
Raymond Hettinger | 04e7e0c | 2002-06-25 13:36:41 +0000 | [diff] [blame] | 303 | For targets which are attribute references, the initial value is |
| 304 | retrieved with a \method{getattr()} and the result is assigned with a |
| 305 | \method{setattr()}. Notice that the two methods do not necessarily |
| 306 | refer to the same variable. When \method{getattr()} refers to a class |
| 307 | variable, \method{setattr()} still writes to an instance variable. |
| 308 | For example: |
| 309 | |
| 310 | \begin{verbatim} |
| 311 | class A: |
| 312 | x = 3 # class variable |
| 313 | a = A() |
| 314 | a.x += 1 # writes a.x as 4 leaving A.x as 3 |
| 315 | \end{verbatim} |
| 316 | |
Fred Drake | 31f5550 | 2000-09-12 20:32:18 +0000 | [diff] [blame] | 317 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame] | 318 | \section{The \keyword{pass} statement \label{pass}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 319 | \stindex{pass} |
| 320 | |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 321 | \begin{productionlist} |
| 322 | \production{pass_stmt} |
| 323 | {"pass"} |
| 324 | \end{productionlist} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 325 | |
| 326 | \keyword{pass} is a null operation --- when it is executed, nothing |
| 327 | happens. It is useful as a placeholder when a statement is |
| 328 | required syntactically, but no code needs to be executed, for example: |
| 329 | \indexii{null}{operation} |
| 330 | |
| 331 | \begin{verbatim} |
| 332 | def f(arg): pass # a function that does nothing (yet) |
| 333 | |
| 334 | class C: pass # a class with no methods (yet) |
| 335 | \end{verbatim} |
| 336 | |
Fred Drake | 2829f1c | 2001-06-23 05:27:20 +0000 | [diff] [blame] | 337 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame] | 338 | \section{The \keyword{del} statement \label{del}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 339 | \stindex{del} |
| 340 | |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 341 | \begin{productionlist} |
| 342 | \production{del_stmt} |
| 343 | {"del" \token{target_list}} |
| 344 | \end{productionlist} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 345 | |
| 346 | Deletion is recursively defined very similar to the way assignment is |
| 347 | defined. Rather that spelling it out in full details, here are some |
| 348 | hints. |
| 349 | \indexii{deletion}{target} |
| 350 | \indexiii{deletion}{target}{list} |
| 351 | |
| 352 | Deletion of a target list recursively deletes each target, from left |
| 353 | to right. |
| 354 | |
Jeremy Hylton | d09ed68 | 2002-04-01 21:15:14 +0000 | [diff] [blame] | 355 | Deletion of a name removes the binding of that name |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 356 | from the local or global namespace, depending on whether the name |
Jeremy Hylton | d09ed68 | 2002-04-01 21:15:14 +0000 | [diff] [blame] | 357 | occurs in a \keyword{global} statement in the same code block. If the |
| 358 | name is unbound, a \exception{NameError} exception will be raised. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 359 | \stindex{global} |
| 360 | \indexii{unbinding}{name} |
| 361 | |
Jeremy Hylton | d09ed68 | 2002-04-01 21:15:14 +0000 | [diff] [blame] | 362 | It is illegal to delete a name from the local namespace if it occurs |
Michael W. Hudson | 495afea | 2002-06-17 12:51:57 +0000 | [diff] [blame] | 363 | as a free variable\indexii{free}{variable} in a nested block. |
Jeremy Hylton | d09ed68 | 2002-04-01 21:15:14 +0000 | [diff] [blame] | 364 | |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 365 | Deletion of attribute references, subscriptions and slicings |
| 366 | is passed to the primary object involved; deletion of a slicing |
| 367 | is in general equivalent to assignment of an empty slice of the |
| 368 | right type (but even this is determined by the sliced object). |
| 369 | \indexii{attribute}{deletion} |
| 370 | |
Fred Drake | 2829f1c | 2001-06-23 05:27:20 +0000 | [diff] [blame] | 371 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame] | 372 | \section{The \keyword{print} statement \label{print}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 373 | \stindex{print} |
| 374 | |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 375 | \begin{productionlist} |
| 376 | \production{print_stmt} |
Fred Drake | 5381588 | 2002-03-15 23:21:37 +0000 | [diff] [blame] | 377 | {"print" ( \optional{\token{expression} ("," \token{expression})* \optional{","}}} |
| 378 | \productioncont{| ">\code{>}" \token{expression} |
| 379 | \optional{("," \token{expression})+ \optional{","}} )} |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 380 | \end{productionlist} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 381 | |
Fred Drake | d4c3352 | 1998-10-01 20:39:47 +0000 | [diff] [blame] | 382 | \keyword{print} evaluates each expression in turn and writes the |
| 383 | resulting object to standard output (see below). If an object is not |
Fred Drake | be9d10e | 2001-06-23 06:16:52 +0000 | [diff] [blame] | 384 | 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] | 385 | conversions. The (resulting or original) string is then written. A |
Fred Drake | be9d10e | 2001-06-23 06:16:52 +0000 | [diff] [blame] | 386 | space is written before each object is (converted and) written, unless |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 387 | 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] | 388 | line. This is the case (1) when no characters have yet been written |
| 389 | to standard output, (2) when the last character written to standard |
Fred Drake | d4c3352 | 1998-10-01 20:39:47 +0000 | [diff] [blame] | 390 | output is \character{\e n}, or (3) when the last write operation on |
| 391 | standard output was not a \keyword{print} statement. (In some cases |
| 392 | it may be functional to write an empty string to standard output for |
Fred Drake | c2f496a | 2001-12-05 05:46:25 +0000 | [diff] [blame] | 393 | this reason.) \note{Objects which act like file objects but which are |
| 394 | not the built-in file objects often do not properly emulate this |
| 395 | aspect of the file object's behavior, so it is best not to rely on |
| 396 | this.} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 397 | \index{output} |
| 398 | \indexii{writing}{values} |
| 399 | |
Fred Drake | d4c3352 | 1998-10-01 20:39:47 +0000 | [diff] [blame] | 400 | A \character{\e n} character is written at the end, unless the |
| 401 | \keyword{print} statement ends with a comma. This is the only action |
| 402 | if the statement contains just the keyword \keyword{print}. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 403 | \indexii{trailing}{comma} |
| 404 | \indexii{newline}{suppression} |
| 405 | |
Fred Drake | dde91f0 | 1998-05-06 20:59:46 +0000 | [diff] [blame] | 406 | Standard output is defined as the file object named \code{stdout} |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 407 | in the built-in module \module{sys}. If no such object exists, or if |
| 408 | it does not have a \method{write()} method, a \exception{RuntimeError} |
| 409 | exception is raised. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 410 | \indexii{standard}{output} |
| 411 | \refbimodindex{sys} |
Fred Drake | 2b3730e | 1998-11-25 17:40:00 +0000 | [diff] [blame] | 412 | \withsubitem{(in module sys)}{\ttindex{stdout}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 413 | \exindex{RuntimeError} |
| 414 | |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 415 | \keyword{print} also has an extended\index{extended print statement} |
| 416 | form, defined by the second portion of the syntax described above. |
| 417 | This form is sometimes referred to as ``\keyword{print} chevron.'' |
Fred Drake | 62effc1 | 2001-04-13 15:55:25 +0000 | [diff] [blame] | 418 | In this form, the first expression after the \code{>}\code{>} must |
Barry Warsaw | 8c0a242 | 2000-08-21 15:45:16 +0000 | [diff] [blame] | 419 | evaluate to a ``file-like'' object, specifically an object that has a |
Barry Warsaw | 33f785f | 2000-08-29 04:57:34 +0000 | [diff] [blame] | 420 | \method{write()} method as described above. With this extended form, |
| 421 | the subsequent expressions are printed to this file object. If the |
| 422 | first expression evaluates to \code{None}, then \code{sys.stdout} is |
| 423 | used as the file for output. |
Barry Warsaw | 8c0a242 | 2000-08-21 15:45:16 +0000 | [diff] [blame] | 424 | |
Fred Drake | 2829f1c | 2001-06-23 05:27:20 +0000 | [diff] [blame] | 425 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame] | 426 | \section{The \keyword{return} statement \label{return}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 427 | \stindex{return} |
| 428 | |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 429 | \begin{productionlist} |
| 430 | \production{return_stmt} |
| 431 | {"return" [\token{expression_list}]} |
| 432 | \end{productionlist} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 433 | |
| 434 | \keyword{return} may only occur syntactically nested in a function |
| 435 | definition, not within a nested class definition. |
| 436 | \indexii{function}{definition} |
| 437 | \indexii{class}{definition} |
| 438 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 439 | If an expression list is present, it is evaluated, else \code{None} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 440 | is substituted. |
| 441 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 442 | \keyword{return} leaves the current function call with the expression |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 443 | list (or \code{None}) as return value. |
| 444 | |
| 445 | When \keyword{return} passes control out of a \keyword{try} statement |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 446 | with a \keyword{finally} clause, that \keyword{finally} clause is executed |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 447 | before really leaving the function. |
| 448 | \kwindex{finally} |
| 449 | |
Fred Drake | e31e9ce | 2001-12-11 21:10:08 +0000 | [diff] [blame] | 450 | In a generator function, the \keyword{return} statement is not allowed |
| 451 | to include an \grammartoken{expression_list}. In that context, a bare |
| 452 | \keyword{return} indicates that the generator is done and will cause |
| 453 | \exception{StopIteration} to be raised. |
| 454 | |
| 455 | |
| 456 | \section{The \keyword{yield} statement \label{yield}} |
| 457 | \stindex{yield} |
| 458 | |
| 459 | \begin{productionlist} |
| 460 | \production{yield_stmt} |
| 461 | {"yield" \token{expression_list}} |
| 462 | \end{productionlist} |
| 463 | |
| 464 | \index{generator!function} |
| 465 | \index{generator!iterator} |
| 466 | \index{function!generator} |
| 467 | \exindex{StopIteration} |
| 468 | |
| 469 | The \keyword{yield} statement is only used when defining a generator |
| 470 | function, and is only used in the body of the generator function. |
| 471 | Using a \keyword{yield} statement in a function definition is |
| 472 | sufficient to cause that definition to create a generator function |
| 473 | instead of a normal function. |
| 474 | |
| 475 | When a generator function is called, it returns an iterator known as a |
| 476 | generator iterator, or more commonly, a generator. The body of the |
| 477 | generator function is executed by calling the generator's |
| 478 | \method{next()} method repeatedly until it raises an exception. |
| 479 | |
| 480 | When a \keyword{yield} statement is executed, the state of the |
| 481 | generator is frozen and the value of \grammartoken{expression_list} is |
| 482 | returned to \method{next()}'s caller. By ``frozen'' we mean that all |
| 483 | local state is retained, including the current bindings of local |
| 484 | variables, the instruction pointer, and the internal evaluation stack: |
| 485 | enough information is saved so that the next time \method{next()} is |
| 486 | invoked, the function can proceed exactly as if the \keyword{yield} |
| 487 | statement were just another external call. |
| 488 | |
Fred Drake | 3a8e59e | 2001-12-11 21:58:35 +0000 | [diff] [blame] | 489 | The \keyword{yield} statement is not allowed in the \keyword{try} |
| 490 | clause of a \keyword{try} ...\ \keyword{finally} construct. The |
| 491 | difficulty is that there's no guarantee the generator will ever be |
| 492 | resumed, hence no guarantee that the \keyword{finally} block will ever |
| 493 | get executed. |
Fred Drake | e31e9ce | 2001-12-11 21:10:08 +0000 | [diff] [blame] | 494 | |
Fred Drake | 08d752c | 2001-12-14 22:55:14 +0000 | [diff] [blame] | 495 | \begin{notice} |
| 496 | In Python 2.2, the \keyword{yield} statement is only allowed |
Fred Drake | 8d0645c | 2001-12-12 06:06:43 +0000 | [diff] [blame] | 497 | when the \code{generators} feature has been enabled. It will always |
| 498 | be enabled in Python 2.3. This \code{__future__} import statment can |
Fred Drake | 08d752c | 2001-12-14 22:55:14 +0000 | [diff] [blame] | 499 | be used to enable the feature: |
Fred Drake | 8d0645c | 2001-12-12 06:06:43 +0000 | [diff] [blame] | 500 | |
| 501 | \begin{verbatim} |
| 502 | from __future__ import generators |
| 503 | \end{verbatim} |
Fred Drake | 08d752c | 2001-12-14 22:55:14 +0000 | [diff] [blame] | 504 | \end{notice} |
Fred Drake | 8d0645c | 2001-12-12 06:06:43 +0000 | [diff] [blame] | 505 | |
| 506 | |
Fred Drake | e31e9ce | 2001-12-11 21:10:08 +0000 | [diff] [blame] | 507 | \begin{seealso} |
| 508 | \seepep{0255}{Simple Generators} |
| 509 | {The proposal for adding generators and the \keyword{yield} |
| 510 | statement to Python.} |
| 511 | \end{seealso} |
| 512 | |
Fred Drake | 2829f1c | 2001-06-23 05:27:20 +0000 | [diff] [blame] | 513 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame] | 514 | \section{The \keyword{raise} statement \label{raise}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 515 | \stindex{raise} |
| 516 | |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 517 | \begin{productionlist} |
| 518 | \production{raise_stmt} |
| 519 | {"raise" [\token{expression} ["," \token{expression} |
| 520 | ["," \token{expression}]]]} |
| 521 | \end{productionlist} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 522 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 523 | If no expressions are present, \keyword{raise} re-raises the last |
Fred Drake | 81932e2 | 2002-06-20 20:55:29 +0000 | [diff] [blame] | 524 | expression that was active in the current scope. If no exception has |
| 525 | been active in the current scope, an exception is raised that |
| 526 | indicates indicates that this is the error. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 527 | \index{exception} |
| 528 | \indexii{raising}{exception} |
| 529 | |
Fred Drake | 81932e2 | 2002-06-20 20:55:29 +0000 | [diff] [blame] | 530 | Otherwise, \keyword{raise} evaluates the expressions to get three |
| 531 | objects, using \code{None} as the value of omitted expressions. The |
| 532 | first two objects are used to determine the \emph{type} and |
| 533 | \emph{value} of the exception. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 534 | |
Fred Drake | 81932e2 | 2002-06-20 20:55:29 +0000 | [diff] [blame] | 535 | If the first object is an instance, the type of the exception is the |
Fred Drake | 8bd62af | 2003-01-25 03:47:35 +0000 | [diff] [blame] | 536 | class of the instance, the instance itself is the value, and the |
Fred Drake | 81932e2 | 2002-06-20 20:55:29 +0000 | [diff] [blame] | 537 | second object must be \code{None}. |
| 538 | |
| 539 | If the first object is a class, it becomes the type of the exception. |
| 540 | The second object is used to determine the exception value: If it is |
| 541 | an instance of the class, the instance becomes the exception value. |
| 542 | If the second object is a tuple, it is used as the argument list for |
| 543 | the class constructor; if it is \code{None}, an empty argument list is |
| 544 | used, and any other object is treated as a single argument to the |
| 545 | constructor. The instance so created by calling the constructor is |
| 546 | used as the exception value. |
| 547 | |
| 548 | If the first object is a string, the string object is the exception |
| 549 | type, and the second object becomes the exception value. |
| 550 | |
| 551 | If a third object is present and not \code{None}, it must be a |
| 552 | traceback\obindex{traceback} object (see section~\ref{traceback}), and |
| 553 | it is substituted instead of the current location as the place where |
| 554 | the exception occurred. If the third object is present and not a |
| 555 | traceback object or \code{None}, a \exception{TypeError} exception is |
| 556 | raised. The three-expression form of \keyword{raise} is useful to |
| 557 | re-raise an exception transparently in an except clause, but |
| 558 | \keyword{raise} with no expressions should be preferred if the |
| 559 | exception to be re-raised was the most recently active exception in |
| 560 | the current scope. |
| 561 | |
Fred Drake | e7097e0 | 2002-10-18 15:18:18 +0000 | [diff] [blame] | 562 | Additional information on exceptions can be found in |
| 563 | section~\ref{exceptions}, and information about handling exceptions is |
| 564 | in section~\ref{try}. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 565 | |
Fred Drake | 2829f1c | 2001-06-23 05:27:20 +0000 | [diff] [blame] | 566 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame] | 567 | \section{The \keyword{break} statement \label{break}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 568 | \stindex{break} |
| 569 | |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 570 | \begin{productionlist} |
| 571 | \production{break_stmt} |
| 572 | {"break"} |
| 573 | \end{productionlist} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 574 | |
| 575 | \keyword{break} may only occur syntactically nested in a \keyword{for} |
| 576 | or \keyword{while} loop, but not nested in a function or class definition |
| 577 | within that loop. |
| 578 | \stindex{for} |
| 579 | \stindex{while} |
| 580 | \indexii{loop}{statement} |
| 581 | |
| 582 | It terminates the nearest enclosing loop, skipping the optional |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 583 | \keyword{else} clause if the loop has one. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 584 | \kwindex{else} |
| 585 | |
| 586 | If a \keyword{for} loop is terminated by \keyword{break}, the loop control |
| 587 | target keeps its current value. |
| 588 | \indexii{loop control}{target} |
| 589 | |
| 590 | When \keyword{break} passes control out of a \keyword{try} statement |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 591 | with a \keyword{finally} clause, that \keyword{finally} clause is executed |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 592 | before really leaving the loop. |
| 593 | \kwindex{finally} |
| 594 | |
Fred Drake | 2829f1c | 2001-06-23 05:27:20 +0000 | [diff] [blame] | 595 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame] | 596 | \section{The \keyword{continue} statement \label{continue}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 597 | \stindex{continue} |
| 598 | |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 599 | \begin{productionlist} |
| 600 | \production{continue_stmt} |
| 601 | {"continue"} |
| 602 | \end{productionlist} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 603 | |
| 604 | \keyword{continue} may only occur syntactically nested in a \keyword{for} or |
| 605 | \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] | 606 | \keyword{try} statement within that loop.\footnote{It may |
| 607 | occur within an \keyword{except} or \keyword{else} clause. The |
Thomas Wouters | f9b526d | 2000-07-16 19:05:38 +0000 | [diff] [blame] | 608 | restriction on occurring in the \keyword{try} clause is implementor's |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 609 | laziness and will eventually be lifted.} |
| 610 | It continues with the next cycle of the nearest enclosing loop. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 611 | \stindex{for} |
| 612 | \stindex{while} |
| 613 | \indexii{loop}{statement} |
| 614 | \kwindex{finally} |
| 615 | |
Fred Drake | 2829f1c | 2001-06-23 05:27:20 +0000 | [diff] [blame] | 616 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame] | 617 | \section{The \keyword{import} statement \label{import}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 618 | \stindex{import} |
| 619 | |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 620 | \begin{productionlist} |
| 621 | \production{import_stmt} |
| 622 | {"import" \token{module} ["as" \token{name}] |
Fred Drake | 5381588 | 2002-03-15 23:21:37 +0000 | [diff] [blame] | 623 | ( "," \token{module} ["as" \token{name}] )*} |
| 624 | \productioncont{| "from" \token{module} "import" \token{identifier} |
| 625 | ["as" \token{name}]} |
| 626 | \productioncont{ ( "," \token{identifier} ["as" \token{name}] )*} |
| 627 | \productioncont{| "from" \token{module} "import" "*"} |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 628 | \production{module} |
| 629 | {(\token{identifier} ".")* \token{identifier}} |
| 630 | \end{productionlist} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 631 | |
| 632 | Import statements are executed in two steps: (1) find a module, and |
| 633 | 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] | 634 | namespace (of the scope where the \keyword{import} statement occurs). |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 635 | The first form (without \keyword{from}) repeats these steps for each |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 636 | identifier in the list. The form with \keyword{from} performs step |
| 637 | (1) once, and then performs step (2) repeatedly. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 638 | \indexii{importing}{module} |
| 639 | \indexii{name}{binding} |
| 640 | \kwindex{from} |
| 641 | |
Raymond Hettinger | e701dcb | 2003-01-19 13:08:18 +0000 | [diff] [blame] | 642 | In this context, to ``initialize'' a built-in or extension module means to |
| 643 | call an initialization function that the module must provide for the purpose |
| 644 | (in the reference implementation, the function's name is obtained by |
| 645 | prepending string ``init'' to the module's name); to ``initialize'' a |
| 646 | Python-coded module means to execute the module's body. |
| 647 | |
| 648 | The system maintains a table of modules that have been or are being |
| 649 | initialized, |
Fred Drake | 191a282 | 2000-07-06 00:50:42 +0000 | [diff] [blame] | 650 | indexed by module name. This table is |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 651 | accessible as \code{sys.modules}. When a module name is found in |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 652 | 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] | 653 | definition is started. When a module is found, it is loaded. Details |
| 654 | of the module searching and loading process are implementation and |
| 655 | platform specific. It generally involves searching for a ``built-in'' |
| 656 | module with the given name and then searching a list of locations |
| 657 | given as \code{sys.path}. |
Fred Drake | 2b3730e | 1998-11-25 17:40:00 +0000 | [diff] [blame] | 658 | \withsubitem{(in module sys)}{\ttindex{modules}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 659 | \ttindex{sys.modules} |
| 660 | \indexii{module}{name} |
| 661 | \indexii{built-in}{module} |
| 662 | \indexii{user-defined}{module} |
| 663 | \refbimodindex{sys} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 664 | \indexii{filename}{extension} |
Fred Drake | dde91f0 | 1998-05-06 20:59:46 +0000 | [diff] [blame] | 665 | \indexiii{module}{search}{path} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 666 | |
| 667 | If a built-in module is found, its built-in initialization code is |
| 668 | executed and step (1) is finished. If no matching file is found, |
| 669 | \exception{ImportError} is raised. If a file is found, it is parsed, |
| 670 | yielding an executable code block. If a syntax error occurs, |
| 671 | \exception{SyntaxError} is raised. Otherwise, an empty module of the given |
| 672 | name is created and inserted in the module table, and then the code |
| 673 | block is executed in the context of this module. Exceptions during |
| 674 | this execution terminate step (1). |
| 675 | \indexii{module}{initialization} |
| 676 | \exindex{SyntaxError} |
| 677 | \exindex{ImportError} |
| 678 | \index{code block} |
| 679 | |
| 680 | When step (1) finishes without raising an exception, step (2) can |
| 681 | begin. |
| 682 | |
Fred Drake | 859eb62 | 2001-03-06 07:34:00 +0000 | [diff] [blame] | 683 | The first form of \keyword{import} statement binds the module name in |
| 684 | the local namespace to the module object, and then goes on to import |
| 685 | the next identifier, if any. If the module name is followed by |
| 686 | \keyword{as}, the name following \keyword{as} is used as the local |
Martin v. Löwis | 13dd9d9 | 2003-01-16 11:30:08 +0000 | [diff] [blame] | 687 | name for the module. |
Thomas Wouters | 8bad612 | 2000-08-19 20:55:02 +0000 | [diff] [blame] | 688 | |
Thomas Wouters | 5215225 | 2000-08-17 22:55:00 +0000 | [diff] [blame] | 689 | The \keyword{from} form does not bind the module name: it goes through the |
| 690 | list of identifiers, looks each one of them up in the module found in step |
| 691 | (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] | 692 | 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] | 693 | supplied by specifying "\keyword{as} localname". If a name is not found, |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 694 | \exception{ImportError} is raised. If the list of identifiers is replaced |
Fred Drake | 08fd515 | 2001-10-24 19:50:31 +0000 | [diff] [blame] | 695 | by a star (\character{*}), all public names defined in the module are |
| 696 | bound in the local namespace of the \keyword{import} statement.. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 697 | \indexii{name}{binding} |
| 698 | \exindex{ImportError} |
| 699 | |
Fred Drake | 08fd515 | 2001-10-24 19:50:31 +0000 | [diff] [blame] | 700 | The \emph{public names} defined by a module are determined by checking |
| 701 | the module's namespace for a variable named \code{__all__}; if |
| 702 | defined, it must be a sequence of strings which are names defined or |
| 703 | imported by that module. The names given in \code{__all__} are all |
| 704 | considered public and are required to exist. If \code{__all__} is not |
| 705 | defined, the set of public names includes all names found in the |
| 706 | module's namespace which do not begin with an underscore character |
Raymond Hettinger | 1772f17 | 2003-01-06 12:54:54 +0000 | [diff] [blame] | 707 | (\character{_}). \code{__all__} should contain the entire public API. |
| 708 | It is intended to avoid accidentally exporting items that are not part |
| 709 | of the API (such as library modules which were imported and used within |
| 710 | the module). |
Fred Drake | 27cae1f | 2002-12-07 16:00:00 +0000 | [diff] [blame] | 711 | \withsubitem{(optional module attribute)}{\ttindex{__all__}} |
Fred Drake | 08fd515 | 2001-10-24 19:50:31 +0000 | [diff] [blame] | 712 | |
Jeremy Hylton | f0c1f1b | 2002-04-01 21:19:44 +0000 | [diff] [blame] | 713 | The \keyword{from} form with \samp{*} may only occur in a module |
| 714 | scope. If the wild card form of import --- \samp{import *} --- is |
| 715 | used in a function and the function contains or is a nested block with |
| 716 | free variables, the compiler will raise a \exception{SyntaxError}. |
| 717 | |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 718 | \kwindex{from} |
Fred Drake | 2b3730e | 1998-11-25 17:40:00 +0000 | [diff] [blame] | 719 | \stindex{from} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 720 | |
Fred Drake | 246837d | 1998-07-24 20:28:22 +0000 | [diff] [blame] | 721 | \strong{Hierarchical module names:}\indexiii{hierarchical}{module}{names} |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 722 | when the module names contains one or more dots, the module search |
| 723 | path is carried out differently. The sequence of identifiers up to |
| 724 | the last dot is used to find a ``package''\index{packages}; the final |
| 725 | identifier is then searched inside the package. A package is |
| 726 | generally a subdirectory of a directory on \code{sys.path} that has a |
| 727 | file \file{__init__.py}.\ttindex{__init__.py} |
| 728 | % |
| 729 | [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] | 730 | \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] | 731 | about how the module search works from inside a package.] |
| 732 | |
Fred Drake | 08fd515 | 2001-10-24 19:50:31 +0000 | [diff] [blame] | 733 | The built-in function \function{__import__()} is provided to support |
| 734 | applications that determine which modules need to be loaded |
| 735 | dynamically; refer to \ulink{Built-in |
| 736 | Functions}{../lib/built-in-funcs.html} in the |
| 737 | \citetitle[../lib/lib.html]{Python Library Reference} for additional |
| 738 | information. |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 739 | \bifuncindex{__import__} |
| 740 | |
Fred Drake | 2829f1c | 2001-06-23 05:27:20 +0000 | [diff] [blame] | 741 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame] | 742 | \section{The \keyword{global} statement \label{global}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 743 | \stindex{global} |
| 744 | |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 745 | \begin{productionlist} |
| 746 | \production{global_stmt} |
| 747 | {"global" \token{identifier} ("," \token{identifier})*} |
| 748 | \end{productionlist} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 749 | |
| 750 | The \keyword{global} statement is a declaration which holds for the |
| 751 | entire current code block. It means that the listed identifiers are to be |
Jeremy Hylton | f3255c8 | 2002-04-01 21:25:32 +0000 | [diff] [blame] | 752 | interpreted as globals. It would be impossible to assign to a global |
| 753 | variable without \keyword{global}, although free variables may refer |
| 754 | to globals without being declared global. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 755 | \indexiii{global}{name}{binding} |
| 756 | |
| 757 | 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] | 758 | code block textually preceding that \keyword{global} statement. |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 759 | |
| 760 | Names listed in a \keyword{global} statement must not be defined as formal |
| 761 | parameters or in a \keyword{for} loop control target, \keyword{class} |
| 762 | definition, function definition, or \keyword{import} statement. |
| 763 | |
| 764 | (The current implementation does not enforce the latter two |
| 765 | restrictions, but programs should not abuse this freedom, as future |
| 766 | implementations may enforce them or silently change the meaning of the |
| 767 | program.) |
| 768 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 769 | \strong{Programmer's note:} |
| 770 | the \keyword{global} is a directive to the parser. It |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 771 | applies only to code parsed at the same time as the \keyword{global} |
| 772 | statement. In particular, a \keyword{global} statement contained in an |
Fred Drake | dde91f0 | 1998-05-06 20:59:46 +0000 | [diff] [blame] | 773 | \keyword{exec} statement does not affect the code block \emph{containing} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 774 | the \keyword{exec} statement, and code contained in an \keyword{exec} |
| 775 | statement is unaffected by \keyword{global} statements in the code |
| 776 | containing the \keyword{exec} statement. The same applies to the |
| 777 | \function{eval()}, \function{execfile()} and \function{compile()} functions. |
| 778 | \stindex{exec} |
| 779 | \bifuncindex{eval} |
| 780 | \bifuncindex{execfile} |
| 781 | \bifuncindex{compile} |
Guido van Rossum | 5f574aa | 1998-07-06 13:18:39 +0000 | [diff] [blame] | 782 | |
Fred Drake | 2829f1c | 2001-06-23 05:27:20 +0000 | [diff] [blame] | 783 | |
Fred Drake | 011f6fc | 1999-04-14 12:52:14 +0000 | [diff] [blame] | 784 | \section{The \keyword{exec} statement \label{exec}} |
Guido van Rossum | 5f574aa | 1998-07-06 13:18:39 +0000 | [diff] [blame] | 785 | \stindex{exec} |
| 786 | |
Fred Drake | cb4638a | 2001-07-06 22:49:53 +0000 | [diff] [blame] | 787 | \begin{productionlist} |
| 788 | \production{exec_stmt} |
| 789 | {"exec" \token{expression} |
| 790 | ["in" \token{expression} ["," \token{expression}]]} |
| 791 | \end{productionlist} |
Guido van Rossum | 5f574aa | 1998-07-06 13:18:39 +0000 | [diff] [blame] | 792 | |
| 793 | This statement supports dynamic execution of Python code. The first |
| 794 | expression should evaluate to either a string, an open file object, or |
| 795 | a code object. If it is a string, the string is parsed as a suite of |
| 796 | Python statements which is then executed (unless a syntax error |
Fred Drake | 93852ef | 2001-06-23 06:06:52 +0000 | [diff] [blame] | 797 | 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] | 798 | executed. If it is a code object, it is simply executed. |
| 799 | |
| 800 | In all cases, if the optional parts are omitted, the code is executed |
| 801 | in the current scope. If only the first expression after \keyword{in} |
| 802 | is specified, it should be a dictionary, which will be used for both |
| 803 | the global and the local variables. If two expressions are given, |
| 804 | both must be dictionaries and they are used for the global and local |
| 805 | variables, respectively. |
| 806 | |
| 807 | As a side effect, an implementation may insert additional keys into |
| 808 | the dictionaries given besides those corresponding to variable names |
| 809 | set by the executed code. For example, the current implementation |
| 810 | may add a reference to the dictionary of the built-in module |
| 811 | \module{__builtin__} under the key \code{__builtins__} (!). |
| 812 | \ttindex{__builtins__} |
| 813 | \refbimodindex{__builtin__} |
| 814 | |
Guido van Rossum | 56c2013 | 1998-07-24 18:25:38 +0000 | [diff] [blame] | 815 | \strong{Programmer's hints:} |
| 816 | dynamic evaluation of expressions is supported by the built-in |
Guido van Rossum | 5f574aa | 1998-07-06 13:18:39 +0000 | [diff] [blame] | 817 | function \function{eval()}. The built-in functions |
| 818 | \function{globals()} and \function{locals()} return the current global |
| 819 | and local dictionary, respectively, which may be useful to pass around |
| 820 | for use by \keyword{exec}. |
| 821 | \bifuncindex{eval} |
| 822 | \bifuncindex{globals} |
| 823 | \bifuncindex{locals} |
Greg Ward | 38c28e3 | 2000-04-27 18:32:02 +0000 | [diff] [blame] | 824 | |
| 825 | Also, in the current implementation, multi-line compound statements must |
| 826 | end with a newline: |
| 827 | \code{exec "for v in seq:\e{}n\e{}tprint v\e{}n"} works, but |
| 828 | \code{exec "for v in seq:\e{}n\e{}tprint v"} fails with |
| 829 | \exception{SyntaxError}. |
| 830 | \exindex{SyntaxError} |
| 831 | |
| 832 | |