| \chapter{Simple statements \label{simple}} |
| \indexii{simple}{statement} |
| |
| Simple statements are comprised within a single logical line. |
| Several simple statements may occur on a single line separated |
| by semicolons. The syntax for simple statements is: |
| |
| \begin{productionlist} |
| \production{simple_stmt}{\token{expression_stmt}} |
| \productioncont{| \token{assert_stmt}} |
| \productioncont{| \token{assignment_stmt}} |
| \productioncont{| \token{augmented_assignment_stmt}} |
| \productioncont{| \token{pass_stmt}} |
| \productioncont{| \token{del_stmt}} |
| \productioncont{| \token{print_stmt}} |
| \productioncont{| \token{return_stmt}} |
| \productioncont{| \token{yield_stmt}} |
| \productioncont{| \token{raise_stmt}} |
| \productioncont{| \token{break_stmt}} |
| \productioncont{| \token{continue_stmt}} |
| \productioncont{| \token{import_stmt}} |
| \productioncont{| \token{global_stmt}} |
| \productioncont{| \token{exec_stmt}} |
| \end{productionlist} |
| |
| |
| \section{Expression statements \label{exprstmts}} |
| \indexii{expression}{statement} |
| |
| Expression statements are used (mostly interactively) to compute and |
| write a value, or (usually) to call a procedure (a function that |
| returns no meaningful result; in Python, procedures return the value |
| \code{None}). Other uses of expression statements are allowed and |
| occasionally useful. The syntax for an expression statement is: |
| |
| \begin{productionlist} |
| \production{expression_stmt} |
| {\token{expression_list}} |
| \end{productionlist} |
| |
| An expression statement evaluates the expression list (which may be a |
| single expression). |
| \indexii{expression}{list} |
| |
| In interactive mode, if the value is not \code{None}, it is converted |
| to a string using the built-in \function{repr()}\bifuncindex{repr} |
| function and the resulting string is written to standard output (see |
| section~\ref{print}) on a line by itself. (Expression statements |
| yielding \code{None} are not written, so that procedure calls do not |
| cause any output.) |
| \ttindex{None} |
| \indexii{string}{conversion} |
| \index{output} |
| \indexii{standard}{output} |
| \indexii{writing}{values} |
| \indexii{procedure}{call} |
| |
| |
| \section{Assert statements \label{assert}} |
| |
| Assert statements\stindex{assert} are a convenient way to insert |
| debugging assertions\indexii{debugging}{assertions} into a program: |
| |
| \begin{productionlist} |
| \production{assert_statement} |
| {"assert" \token{expression} ["," \token{expression}]} |
| \end{productionlist} |
| |
| The simple form, \samp{assert expression}, is equivalent to |
| |
| \begin{verbatim} |
| if __debug__: |
| if not expression: raise AssertionError |
| \end{verbatim} |
| |
| The extended form, \samp{assert expression1, expression2}, is |
| equivalent to |
| |
| \begin{verbatim} |
| if __debug__: |
| if not expression1: raise AssertionError, expression2 |
| \end{verbatim} |
| |
| These equivalences assume that \code{__debug__}\ttindex{__debug__} and |
| \exception{AssertionError}\exindex{AssertionError} refer to the built-in |
| variables with those names. In the current implementation, the |
| built-in variable \code{__debug__} is 1 under normal circumstances, 0 |
| when optimization is requested (command line option -O). The current |
| code generator emits no code for an assert statement when optimization |
| is requested at compile time. Note that it is unnecessary to include |
| the source code for the expression that failed in the error message; |
| it will be displayed as part of the stack trace. |
| |
| Assignments to \code{__debug__} are illegal. The value for the |
| built-in variable is determined when the interpreter starts. |
| |
| |
| \section{Assignment statements \label{assignment}} |
| |
| Assignment statements\indexii{assignment}{statement} are used to |
| (re)bind names to values and to modify attributes or items of mutable |
| objects: |
| \indexii{binding}{name} |
| \indexii{rebinding}{name} |
| \obindex{mutable} |
| \indexii{attribute}{assignment} |
| |
| \begin{productionlist} |
| \production{assignment_stmt} |
| {(\token{target_list} "=")+ \token{expression_list}} |
| \production{target_list} |
| {\token{target} ("," \token{target})* [","]} |
| \production{target} |
| {\token{identifier}} |
| \productioncont{| "(" \token{target_list} ")"} |
| \productioncont{| "[" \token{target_list} "]"} |
| \productioncont{| \token{attributeref}} |
| \productioncont{| \token{subscription}} |
| \productioncont{| \token{slicing}} |
| \end{productionlist} |
| |
| (See section~\ref{primaries} for the syntax definitions for the last |
| three symbols.) |
| |
| An assignment statement evaluates the expression list (remember that |
| this can be a single expression or a comma-separated list, the latter |
| yielding a tuple) and assigns the single resulting object to each of |
| the target lists, from left to right. |
| \indexii{expression}{list} |
| |
| Assignment is defined recursively depending on the form of the target |
| (list). When a target is part of a mutable object (an attribute |
| reference, subscription or slicing), the mutable object must |
| ultimately perform the assignment and decide about its validity, and |
| may raise an exception if the assignment is unacceptable. The rules |
| observed by various types and the exceptions raised are given with the |
| definition of the object types (see section~\ref{types}). |
| \index{target} |
| \indexii{target}{list} |
| |
| Assignment of an object to a target list is recursively defined as |
| follows. |
| \indexiii{target}{list}{assignment} |
| |
| \begin{itemize} |
| \item |
| If the target list is a single target: The object is assigned to that |
| target. |
| |
| \item |
| If the target list is a comma-separated list of targets: The object |
| must be a sequence with the same number of items as the there are |
| targets in the target list, and the items are assigned, from left to |
| right, to the corresponding targets. (This rule is relaxed as of |
| Python 1.5; in earlier versions, the object had to be a tuple. Since |
| strings are sequences, an assignment like \samp{a, b = "xy"} is |
| now legal as long as the string has the right length.) |
| |
| \end{itemize} |
| |
| Assignment of an object to a single target is recursively defined as |
| follows. |
| |
| \begin{itemize} % nested |
| |
| \item |
| If the target is an identifier (name): |
| |
| \begin{itemize} |
| |
| \item |
| If the name does not occur in a \keyword{global} statement in the current |
| code block: the name is bound to the object in the current local |
| namespace. |
| \stindex{global} |
| |
| \item |
| Otherwise: the name is bound to the object in the current global |
| namespace. |
| |
| \end{itemize} % nested |
| |
| The name is rebound if it was already bound. This may cause the |
| reference count for the object previously bound to the name to reach |
| zero, causing the object to be deallocated and its |
| destructor\index{destructor} (if it has one) to be called. |
| |
| \item |
| If the target is a target list enclosed in parentheses or in square |
| brackets: The object must be a sequence with the same number of items |
| as there are targets in the target list, and its items are assigned, |
| from left to right, to the corresponding targets. |
| |
| \item |
| If the target is an attribute reference: The primary expression in the |
| reference is evaluated. It should yield an object with assignable |
| attributes; if this is not the case, \exception{TypeError} is raised. That |
| object is then asked to assign the assigned object to the given |
| attribute; if it cannot perform the assignment, it raises an exception |
| (usually but not necessarily \exception{AttributeError}). |
| \indexii{attribute}{assignment} |
| |
| \item |
| If the target is a subscription: The primary expression in the |
| reference is evaluated. It should yield either a mutable sequence |
| object (e.g., a list) or a mapping object (e.g., a dictionary). Next, |
| the subscript expression is evaluated. |
| \indexii{subscription}{assignment} |
| \obindex{mutable} |
| |
| If the primary is a mutable sequence object (e.g., a list), the subscript |
| must yield a plain integer. If it is negative, the sequence's length |
| is added to it. The resulting value must be a nonnegative integer |
| less than the sequence's length, and the sequence is asked to assign |
| the assigned object to its item with that index. If the index is out |
| of range, \exception{IndexError} is raised (assignment to a subscripted |
| sequence cannot add new items to a list). |
| \obindex{sequence} |
| \obindex{list} |
| |
| If the primary is a mapping object (e.g., a dictionary), the subscript must |
| have a type compatible with the mapping's key type, and the mapping is |
| then asked to create a key/datum pair which maps the subscript to |
| the assigned object. This can either replace an existing key/value |
| pair with the same key value, or insert a new key/value pair (if no |
| key with the same value existed). |
| \obindex{mapping} |
| \obindex{dictionary} |
| |
| \item |
| If the target is a slicing: The primary expression in the reference is |
| evaluated. It should yield a mutable sequence object (e.g., a list). The |
| assigned object should be a sequence object of the same type. Next, |
| the lower and upper bound expressions are evaluated, insofar they are |
| present; defaults are zero and the sequence's length. The bounds |
| should evaluate to (small) integers. If either bound is negative, the |
| sequence's length is added to it. The resulting bounds are clipped to |
| lie between zero and the sequence's length, inclusive. Finally, the |
| sequence object is asked to replace the slice with the items of the |
| assigned sequence. The length of the slice may be different from the |
| length of the assigned sequence, thus changing the length of the |
| target sequence, if the object allows it. |
| \indexii{slicing}{assignment} |
| |
| \end{itemize} |
| |
| (In the current implementation, the syntax for targets is taken |
| to be the same as for expressions, and invalid syntax is rejected |
| during the code generation phase, causing less detailed error |
| messages.) |
| |
| WARNING: Although the definition of assignment implies that overlaps |
| between the left-hand side and the right-hand side are `safe' (e.g., |
| \samp{a, b = b, a} swaps two variables), overlaps \emph{within} the |
| collection of assigned-to variables are not safe! For instance, the |
| following program prints \samp{[0, 2]}: |
| |
| \begin{verbatim} |
| x = [0, 1] |
| i = 0 |
| i, x[i] = 1, 2 |
| print x |
| \end{verbatim} |
| |
| |
| \subsection{Augmented assignment statements \label{augassign}} |
| |
| Augmented assignment is the combination, in a single statement, of a binary |
| operation and an assignment statement: |
| \indexii{augmented}{assignment} |
| \index{statement!assignment, augmented} |
| |
| \begin{productionlist} |
| \production{augmented_assignment_stmt} |
| {\token{target} \token{augop} \token{expression_list}} |
| \production{augop} |
| {"+=" | "-=" | "*=" | "/=" | "\%=" | "**="} |
| \productioncont{| ">>=" | "<<=" | "\&=" | "\textasciicircum=" | "|="} |
| \end{productionlist} |
| |
| (See section~\ref{primaries} for the syntax definitions for the last |
| three symbols.) |
| |
| An augmented assignment evaluates the target (which, unlike normal |
| assignment statements, cannot be an unpacking) and the expression |
| list, performs the binary operation specific to the type of assignment |
| on the two operands, and assigns the result to the original |
| target. The target is only evaluated once. |
| |
| An augmented assignment expression like \code{x += 1} can be rewritten as |
| \code{x = x + 1} to achieve a similar, but not exactly equal effect. In the |
| augmented version, \code{x} is only evaluated once. Also, when possible, the |
| actual operation is performed \emph{in-place}, meaning that rather than |
| creating a new object and assigning that to the target, the old object is |
| modified instead. |
| |
| With the exception of assigning to tuples and multiple targets in a single |
| statement, the assignment done by augmented assignment statements is handled |
| the same way as normal assignments. Similarly, with the exception of the |
| possible \emph{in-place} behavior, the binary operation performed by |
| augmented assignment is the same as the normal binary operations. |
| |
| For targets which are attribute references, the initial value is |
| retrieved with a \method{getattr()} and the result is assigned with a |
| \method{setattr()}. Notice that the two methods do not necessarily |
| refer to the same variable. When \method{getattr()} refers to a class |
| variable, \method{setattr()} still writes to an instance variable. |
| For example: |
| |
| \begin{verbatim} |
| class A: |
| x = 3 # class variable |
| a = A() |
| a.x += 1 # writes a.x as 4 leaving A.x as 3 |
| \end{verbatim} |
| |
| |
| \section{The \keyword{pass} statement \label{pass}} |
| \stindex{pass} |
| |
| \begin{productionlist} |
| \production{pass_stmt} |
| {"pass"} |
| \end{productionlist} |
| |
| \keyword{pass} is a null operation --- when it is executed, nothing |
| happens. It is useful as a placeholder when a statement is |
| required syntactically, but no code needs to be executed, for example: |
| \indexii{null}{operation} |
| |
| \begin{verbatim} |
| def f(arg): pass # a function that does nothing (yet) |
| |
| class C: pass # a class with no methods (yet) |
| \end{verbatim} |
| |
| |
| \section{The \keyword{del} statement \label{del}} |
| \stindex{del} |
| |
| \begin{productionlist} |
| \production{del_stmt} |
| {"del" \token{target_list}} |
| \end{productionlist} |
| |
| Deletion is recursively defined very similar to the way assignment is |
| defined. Rather that spelling it out in full details, here are some |
| hints. |
| \indexii{deletion}{target} |
| \indexiii{deletion}{target}{list} |
| |
| Deletion of a target list recursively deletes each target, from left |
| to right. |
| |
| Deletion of a name removes the binding of that name |
| from the local or global namespace, depending on whether the name |
| occurs in a \keyword{global} statement in the same code block. If the |
| name is unbound, a \exception{NameError} exception will be raised. |
| \stindex{global} |
| \indexii{unbinding}{name} |
| |
| It is illegal to delete a name from the local namespace if it occurs |
| as a free variable\indexii{free}{variable} in a nested block. |
| |
| Deletion of attribute references, subscriptions and slicings |
| is passed to the primary object involved; deletion of a slicing |
| is in general equivalent to assignment of an empty slice of the |
| right type (but even this is determined by the sliced object). |
| \indexii{attribute}{deletion} |
| |
| |
| \section{The \keyword{print} statement \label{print}} |
| \stindex{print} |
| |
| \begin{productionlist} |
| \production{print_stmt} |
| {"print" ( \optional{\token{expression} ("," \token{expression})* \optional{","}}} |
| \productioncont{| ">\code{>}" \token{expression} |
| \optional{("," \token{expression})+ \optional{","}} )} |
| \end{productionlist} |
| |
| \keyword{print} evaluates each expression in turn and writes the |
| resulting object to standard output (see below). If an object is not |
| a string, it is first converted to a string using the rules for string |
| conversions. The (resulting or original) string is then written. A |
| space is written before each object is (converted and) written, unless |
| the output system believes it is positioned at the beginning of a |
| line. This is the case (1) when no characters have yet been written |
| to standard output, (2) when the last character written to standard |
| output is \character{\e n}, or (3) when the last write operation on |
| standard output was not a \keyword{print} statement. (In some cases |
| it may be functional to write an empty string to standard output for |
| this reason.) \note{Objects which act like file objects but which are |
| not the built-in file objects often do not properly emulate this |
| aspect of the file object's behavior, so it is best not to rely on |
| this.} |
| \index{output} |
| \indexii{writing}{values} |
| |
| A \character{\e n} character is written at the end, unless the |
| \keyword{print} statement ends with a comma. This is the only action |
| if the statement contains just the keyword \keyword{print}. |
| \indexii{trailing}{comma} |
| \indexii{newline}{suppression} |
| |
| Standard output is defined as the file object named \code{stdout} |
| in the built-in module \module{sys}. If no such object exists, or if |
| it does not have a \method{write()} method, a \exception{RuntimeError} |
| exception is raised. |
| \indexii{standard}{output} |
| \refbimodindex{sys} |
| \withsubitem{(in module sys)}{\ttindex{stdout}} |
| \exindex{RuntimeError} |
| |
| \keyword{print} also has an extended\index{extended print statement} |
| form, defined by the second portion of the syntax described above. |
| This form is sometimes referred to as ``\keyword{print} chevron.'' |
| In this form, the first expression after the \code{>}\code{>} must |
| evaluate to a ``file-like'' object, specifically an object that has a |
| \method{write()} method as described above. With this extended form, |
| the subsequent expressions are printed to this file object. If the |
| first expression evaluates to \code{None}, then \code{sys.stdout} is |
| used as the file for output. |
| |
| |
| \section{The \keyword{return} statement \label{return}} |
| \stindex{return} |
| |
| \begin{productionlist} |
| \production{return_stmt} |
| {"return" [\token{expression_list}]} |
| \end{productionlist} |
| |
| \keyword{return} may only occur syntactically nested in a function |
| definition, not within a nested class definition. |
| \indexii{function}{definition} |
| \indexii{class}{definition} |
| |
| If an expression list is present, it is evaluated, else \code{None} |
| is substituted. |
| |
| \keyword{return} leaves the current function call with the expression |
| list (or \code{None}) as return value. |
| |
| When \keyword{return} passes control out of a \keyword{try} statement |
| with a \keyword{finally} clause, that \keyword{finally} clause is executed |
| before really leaving the function. |
| \kwindex{finally} |
| |
| In a generator function, the \keyword{return} statement is not allowed |
| to include an \grammartoken{expression_list}. In that context, a bare |
| \keyword{return} indicates that the generator is done and will cause |
| \exception{StopIteration} to be raised. |
| |
| |
| \section{The \keyword{yield} statement \label{yield}} |
| \stindex{yield} |
| |
| \begin{productionlist} |
| \production{yield_stmt} |
| {"yield" \token{expression_list}} |
| \end{productionlist} |
| |
| \index{generator!function} |
| \index{generator!iterator} |
| \index{function!generator} |
| \exindex{StopIteration} |
| |
| The \keyword{yield} statement is only used when defining a generator |
| function, and is only used in the body of the generator function. |
| Using a \keyword{yield} statement in a function definition is |
| sufficient to cause that definition to create a generator function |
| instead of a normal function. |
| |
| When a generator function is called, it returns an iterator known as a |
| generator iterator, or more commonly, a generator. The body of the |
| generator function is executed by calling the generator's |
| \method{next()} method repeatedly until it raises an exception. |
| |
| When a \keyword{yield} statement is executed, the state of the |
| generator is frozen and the value of \grammartoken{expression_list} is |
| returned to \method{next()}'s caller. By ``frozen'' we mean that all |
| local state is retained, including the current bindings of local |
| variables, the instruction pointer, and the internal evaluation stack: |
| enough information is saved so that the next time \method{next()} is |
| invoked, the function can proceed exactly as if the \keyword{yield} |
| statement were just another external call. |
| |
| The \keyword{yield} statement is not allowed in the \keyword{try} |
| clause of a \keyword{try} ...\ \keyword{finally} construct. The |
| difficulty is that there's no guarantee the generator will ever be |
| resumed, hence no guarantee that the \keyword{finally} block will ever |
| get executed. |
| |
| \begin{notice} |
| In Python 2.2, the \keyword{yield} statement is only allowed |
| when the \code{generators} feature has been enabled. It will always |
| be enabled in Python 2.3. This \code{__future__} import statment can |
| be used to enable the feature: |
| |
| \begin{verbatim} |
| from __future__ import generators |
| \end{verbatim} |
| \end{notice} |
| |
| |
| \begin{seealso} |
| \seepep{0255}{Simple Generators} |
| {The proposal for adding generators and the \keyword{yield} |
| statement to Python.} |
| \end{seealso} |
| |
| |
| \section{The \keyword{raise} statement \label{raise}} |
| \stindex{raise} |
| |
| \begin{productionlist} |
| \production{raise_stmt} |
| {"raise" [\token{expression} ["," \token{expression} |
| ["," \token{expression}]]]} |
| \end{productionlist} |
| |
| If no expressions are present, \keyword{raise} re-raises the last |
| expression that was active in the current scope. If no exception has |
| been active in the current scope, an exception is raised that |
| indicates indicates that this is the error. |
| \index{exception} |
| \indexii{raising}{exception} |
| |
| Otherwise, \keyword{raise} evaluates the expressions to get three |
| objects, using \code{None} as the value of omitted expressions. The |
| first two objects are used to determine the \emph{type} and |
| \emph{value} of the exception. |
| |
| If the first object is an instance, the type of the exception is the |
| class of the instance, the instance itself if the value, and the |
| second object must be \code{None}. |
| |
| If the first object is a class, it becomes the type of the exception. |
| The second object is used to determine the exception value: If it is |
| an instance of the class, the instance becomes the exception value. |
| If the second object is a tuple, it is used as the argument list for |
| the class constructor; if it is \code{None}, an empty argument list is |
| used, and any other object is treated as a single argument to the |
| constructor. The instance so created by calling the constructor is |
| used as the exception value. |
| |
| If the first object is a string, the string object is the exception |
| type, and the second object becomes the exception value. |
| |
| If a third object is present and not \code{None}, it must be a |
| traceback\obindex{traceback} object (see section~\ref{traceback}), and |
| it is substituted instead of the current location as the place where |
| the exception occurred. If the third object is present and not a |
| traceback object or \code{None}, a \exception{TypeError} exception is |
| raised. The three-expression form of \keyword{raise} is useful to |
| re-raise an exception transparently in an except clause, but |
| \keyword{raise} with no expressions should be preferred if the |
| exception to be re-raised was the most recently active exception in |
| the current scope. |
| |
| Additional information on exceptions can be found in |
| section~\ref{exceptions}, and information about handling exceptions is |
| in section~\ref{try}. |
| |
| |
| \section{The \keyword{break} statement \label{break}} |
| \stindex{break} |
| |
| \begin{productionlist} |
| \production{break_stmt} |
| {"break"} |
| \end{productionlist} |
| |
| \keyword{break} may only occur syntactically nested in a \keyword{for} |
| or \keyword{while} loop, but not nested in a function or class definition |
| within that loop. |
| \stindex{for} |
| \stindex{while} |
| \indexii{loop}{statement} |
| |
| It terminates the nearest enclosing loop, skipping the optional |
| \keyword{else} clause if the loop has one. |
| \kwindex{else} |
| |
| If a \keyword{for} loop is terminated by \keyword{break}, the loop control |
| target keeps its current value. |
| \indexii{loop control}{target} |
| |
| When \keyword{break} passes control out of a \keyword{try} statement |
| with a \keyword{finally} clause, that \keyword{finally} clause is executed |
| before really leaving the loop. |
| \kwindex{finally} |
| |
| |
| \section{The \keyword{continue} statement \label{continue}} |
| \stindex{continue} |
| |
| \begin{productionlist} |
| \production{continue_stmt} |
| {"continue"} |
| \end{productionlist} |
| |
| \keyword{continue} may only occur syntactically nested in a \keyword{for} or |
| \keyword{while} loop, but not nested in a function or class definition or |
| \keyword{try} statement within that loop.\footnote{It may |
| occur within an \keyword{except} or \keyword{else} clause. The |
| restriction on occurring in the \keyword{try} clause is implementor's |
| laziness and will eventually be lifted.} |
| It continues with the next cycle of the nearest enclosing loop. |
| \stindex{for} |
| \stindex{while} |
| \indexii{loop}{statement} |
| \kwindex{finally} |
| |
| |
| \section{The \keyword{import} statement \label{import}} |
| \stindex{import} |
| |
| \begin{productionlist} |
| \production{import_stmt} |
| {"import" \token{module} ["as" \token{name}] |
| ( "," \token{module} ["as" \token{name}] )*} |
| \productioncont{| "from" \token{module} "import" \token{identifier} |
| ["as" \token{name}]} |
| \productioncont{ ( "," \token{identifier} ["as" \token{name}] )*} |
| \productioncont{| "from" \token{module} "import" "*"} |
| \production{module} |
| {(\token{identifier} ".")* \token{identifier}} |
| \end{productionlist} |
| |
| Import statements are executed in two steps: (1) find a module, and |
| initialize it if necessary; (2) define a name or names in the local |
| namespace (of the scope where the \keyword{import} statement occurs). |
| The first form (without \keyword{from}) repeats these steps for each |
| identifier in the list. The form with \keyword{from} performs step |
| (1) once, and then performs step (2) repeatedly. |
| \indexii{importing}{module} |
| \indexii{name}{binding} |
| \kwindex{from} |
| |
| In this context, to ``initialize'' a built-in or extension module means to |
| call an initialization function that the module must provide for the purpose |
| (in the reference implementation, the function's name is obtained by |
| prepending string ``init'' to the module's name); to ``initialize'' a |
| Python-coded module means to execute the module's body. |
| |
| The system maintains a table of modules that have been or are being |
| initialized, |
| indexed by module name. This table is |
| accessible as \code{sys.modules}. When a module name is found in |
| this table, step (1) is finished. If not, a search for a module |
| definition is started. When a module is found, it is loaded. Details |
| of the module searching and loading process are implementation and |
| platform specific. It generally involves searching for a ``built-in'' |
| module with the given name and then searching a list of locations |
| given as \code{sys.path}. |
| \withsubitem{(in module sys)}{\ttindex{modules}} |
| \ttindex{sys.modules} |
| \indexii{module}{name} |
| \indexii{built-in}{module} |
| \indexii{user-defined}{module} |
| \refbimodindex{sys} |
| \indexii{filename}{extension} |
| \indexiii{module}{search}{path} |
| |
| If a built-in module is found, its built-in initialization code is |
| executed and step (1) is finished. If no matching file is found, |
| \exception{ImportError} is raised. If a file is found, it is parsed, |
| yielding an executable code block. If a syntax error occurs, |
| \exception{SyntaxError} is raised. Otherwise, an empty module of the given |
| name is created and inserted in the module table, and then the code |
| block is executed in the context of this module. Exceptions during |
| this execution terminate step (1). |
| \indexii{module}{initialization} |
| \exindex{SyntaxError} |
| \exindex{ImportError} |
| \index{code block} |
| |
| When step (1) finishes without raising an exception, step (2) can |
| begin. |
| |
| The first form of \keyword{import} statement binds the module name in |
| the local namespace to the module object, and then goes on to import |
| the next identifier, if any. If the module name is followed by |
| \keyword{as}, the name following \keyword{as} is used as the local |
| name for the module. |
| |
| The \keyword{from} form does not bind the module name: it goes through the |
| list of identifiers, looks each one of them up in the module found in step |
| (1), and binds the name in the local namespace to the object thus found. |
| As with the first form of \keyword{import}, an alternate local name can be |
| supplied by specifying "\keyword{as} localname". If a name is not found, |
| \exception{ImportError} is raised. If the list of identifiers is replaced |
| by a star (\character{*}), all public names defined in the module are |
| bound in the local namespace of the \keyword{import} statement.. |
| \indexii{name}{binding} |
| \exindex{ImportError} |
| |
| The \emph{public names} defined by a module are determined by checking |
| the module's namespace for a variable named \code{__all__}; if |
| defined, it must be a sequence of strings which are names defined or |
| imported by that module. The names given in \code{__all__} are all |
| considered public and are required to exist. If \code{__all__} is not |
| defined, the set of public names includes all names found in the |
| module's namespace which do not begin with an underscore character |
| (\character{_}). \code{__all__} should contain the entire public API. |
| It is intended to avoid accidentally exporting items that are not part |
| of the API (such as library modules which were imported and used within |
| the module). |
| \withsubitem{(optional module attribute)}{\ttindex{__all__}} |
| |
| The \keyword{from} form with \samp{*} may only occur in a module |
| scope. If the wild card form of import --- \samp{import *} --- is |
| used in a function and the function contains or is a nested block with |
| free variables, the compiler will raise a \exception{SyntaxError}. |
| |
| \kwindex{from} |
| \stindex{from} |
| |
| \strong{Hierarchical module names:}\indexiii{hierarchical}{module}{names} |
| when the module names contains one or more dots, the module search |
| path is carried out differently. The sequence of identifiers up to |
| the last dot is used to find a ``package''\index{packages}; the final |
| identifier is then searched inside the package. A package is |
| generally a subdirectory of a directory on \code{sys.path} that has a |
| file \file{__init__.py}.\ttindex{__init__.py} |
| % |
| [XXX Can't be bothered to spell this out right now; see the URL |
| \url{http://www.python.org/doc/essays/packages.html} for more details, also |
| about how the module search works from inside a package.] |
| |
| The built-in function \function{__import__()} is provided to support |
| applications that determine which modules need to be loaded |
| dynamically; refer to \ulink{Built-in |
| Functions}{../lib/built-in-funcs.html} in the |
| \citetitle[../lib/lib.html]{Python Library Reference} for additional |
| information. |
| \bifuncindex{__import__} |
| |
| |
| \section{The \keyword{global} statement \label{global}} |
| \stindex{global} |
| |
| \begin{productionlist} |
| \production{global_stmt} |
| {"global" \token{identifier} ("," \token{identifier})*} |
| \end{productionlist} |
| |
| The \keyword{global} statement is a declaration which holds for the |
| entire current code block. It means that the listed identifiers are to be |
| interpreted as globals. It would be impossible to assign to a global |
| variable without \keyword{global}, although free variables may refer |
| to globals without being declared global. |
| \indexiii{global}{name}{binding} |
| |
| Names listed in a \keyword{global} statement must not be used in the same |
| code block textually preceding that \keyword{global} statement. |
| |
| Names listed in a \keyword{global} statement must not be defined as formal |
| parameters or in a \keyword{for} loop control target, \keyword{class} |
| definition, function definition, or \keyword{import} statement. |
| |
| (The current implementation does not enforce the latter two |
| restrictions, but programs should not abuse this freedom, as future |
| implementations may enforce them or silently change the meaning of the |
| program.) |
| |
| \strong{Programmer's note:} |
| the \keyword{global} is a directive to the parser. It |
| applies only to code parsed at the same time as the \keyword{global} |
| statement. In particular, a \keyword{global} statement contained in an |
| \keyword{exec} statement does not affect the code block \emph{containing} |
| the \keyword{exec} statement, and code contained in an \keyword{exec} |
| statement is unaffected by \keyword{global} statements in the code |
| containing the \keyword{exec} statement. The same applies to the |
| \function{eval()}, \function{execfile()} and \function{compile()} functions. |
| \stindex{exec} |
| \bifuncindex{eval} |
| \bifuncindex{execfile} |
| \bifuncindex{compile} |
| |
| |
| \section{The \keyword{exec} statement \label{exec}} |
| \stindex{exec} |
| |
| \begin{productionlist} |
| \production{exec_stmt} |
| {"exec" \token{expression} |
| ["in" \token{expression} ["," \token{expression}]]} |
| \end{productionlist} |
| |
| This statement supports dynamic execution of Python code. The first |
| expression should evaluate to either a string, an open file object, or |
| a code object. If it is a string, the string is parsed as a suite of |
| Python statements which is then executed (unless a syntax error |
| occurs). If it is an open file, the file is parsed until \EOF{} and |
| executed. If it is a code object, it is simply executed. |
| |
| In all cases, if the optional parts are omitted, the code is executed |
| in the current scope. If only the first expression after \keyword{in} |
| is specified, it should be a dictionary, which will be used for both |
| the global and the local variables. If two expressions are given, |
| both must be dictionaries and they are used for the global and local |
| variables, respectively. |
| |
| As a side effect, an implementation may insert additional keys into |
| the dictionaries given besides those corresponding to variable names |
| set by the executed code. For example, the current implementation |
| may add a reference to the dictionary of the built-in module |
| \module{__builtin__} under the key \code{__builtins__} (!). |
| \ttindex{__builtins__} |
| \refbimodindex{__builtin__} |
| |
| \strong{Programmer's hints:} |
| dynamic evaluation of expressions is supported by the built-in |
| function \function{eval()}. The built-in functions |
| \function{globals()} and \function{locals()} return the current global |
| and local dictionary, respectively, which may be useful to pass around |
| for use by \keyword{exec}. |
| \bifuncindex{eval} |
| \bifuncindex{globals} |
| \bifuncindex{locals} |
| |
| Also, in the current implementation, multi-line compound statements must |
| end with a newline: |
| \code{exec "for v in seq:\e{}n\e{}tprint v\e{}n"} works, but |
| \code{exec "for v in seq:\e{}n\e{}tprint v"} fails with |
| \exception{SyntaxError}. |
| \exindex{SyntaxError} |
| |
| |