Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 1 | \chapter{Execution model} |
| 2 | \index{execution model} |
| 3 | |
| 4 | \section{Code blocks, execution frames, and name spaces} \label{execframes} |
| 5 | \index{code block} |
| 6 | \indexii{execution}{frame} |
| 7 | \index{name space} |
| 8 | |
| 9 | A {\em code block} is a piece of Python program text that can be |
| 10 | executed as a unit, such as a module, a class definition or a function |
| 11 | body. Some code blocks (like modules) are executed only once, others |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 12 | (like function bodies) may be executed many times. Code blocks may |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 13 | textually contain other code blocks. Code blocks may invoke other |
| 14 | code blocks (that may or may not be textually contained in them) as |
| 15 | part of their execution, e.g. by invoking (calling) a function. |
| 16 | \index{code block} |
| 17 | \indexii{code}{block} |
| 18 | |
| 19 | The following are code blocks: A module is a code block. A function |
| 20 | body is a code block. A class definition is a code block. Each |
| 21 | command typed interactively is a separate code block; a script file is |
Guido van Rossum | 4bd023f | 1993-10-27 13:49:20 +0000 | [diff] [blame] | 22 | a code block. The string argument passed to the built-in function |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 23 | \verb@eval@ and to the \verb@exec@ statement are code blocks. |
Guido van Rossum | 4bd023f | 1993-10-27 13:49:20 +0000 | [diff] [blame] | 24 | And finally, the |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 25 | expression read and evaluated by the built-in function \verb@input@ is |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 26 | a code block. |
| 27 | |
| 28 | A code block is executed in an execution frame. An {\em execution |
| 29 | frame} contains some administrative information (used for debugging), |
| 30 | determines where and how execution continues after the code block's |
| 31 | execution has completed, and (perhaps most importantly) defines two |
| 32 | name spaces, the local and the global name space, that affect |
| 33 | execution of the code block. |
| 34 | \indexii{execution}{frame} |
| 35 | |
| 36 | A {\em name space} is a mapping from names (identifiers) to objects. |
| 37 | A particular name space may be referenced by more than one execution |
| 38 | frame, and from other places as well. Adding a name to a name space |
| 39 | is called {\em binding} a name (to an object); changing the mapping of |
| 40 | a name is called {\em rebinding}; removing a name is {\em unbinding}. |
| 41 | Name spaces are functionally equivalent to dictionaries. |
| 42 | \index{name space} |
| 43 | \indexii{binding}{name} |
| 44 | \indexii{rebinding}{name} |
| 45 | \indexii{unbinding}{name} |
| 46 | |
| 47 | The {\em local name space} of an execution frame determines the default |
| 48 | place where names are defined and searched. The {\em global name |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 49 | space} determines the place where names listed in \verb@global@ |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 50 | statements are defined and searched, and where names that are not |
| 51 | explicitly bound in the current code block are searched. |
| 52 | \indexii{local}{name space} |
| 53 | \indexii{global}{name space} |
| 54 | \stindex{global} |
| 55 | |
| 56 | Whether a name is local or global in a code block is determined by |
| 57 | static inspection of the source text for the code block: in the |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 58 | absence of \verb@global@ statements, a name that is bound anywhere in |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 59 | the code block is local in the entire code block; all other names are |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 60 | considered global. The \verb@global@ statement forces global |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 61 | interpretation of selected names throughout the code block. The |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 62 | following constructs bind names: formal parameters, \verb@import@ |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 63 | statements, class and function definitions (these bind the class or |
| 64 | function name), and targets that are identifiers if occurring in an |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 65 | assignment, \verb@for@ loop header, or \verb@except@ clause header. |
| 66 | |
| 67 | A target occurring in a \verb@del@ statement is also considered bound |
| 68 | for this purpose (though the actual semantics are to ``unbind'' the |
| 69 | name). |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 70 | |
| 71 | When a global name is not found in the global name space, it is |
| 72 | searched in the list of ``built-in'' names (which is actually the |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 73 | global name space of the module \verb@__builtin__@). When a name is not |
| 74 | found at all, the \verb@NameError@ exception is raised.% |
Guido van Rossum | 31cce97 | 1995-01-04 19:17:34 +0000 | [diff] [blame] | 75 | \footnote{If the code block contains {\tt exec} statements or the |
| 76 | construct {\tt from \ldots import *}, the semantics of names not |
| 77 | explicitly mentioned in a {\tt global} statement change subtly: name |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 78 | lookup first searches the local name space, then the global one, then |
| 79 | the built-in one.} |
Guido van Rossum | aaec403 | 1995-03-21 14:41:57 +0000 | [diff] [blame] | 80 | \bimodindex{__builtin__} |
| 81 | \stindex{from} |
| 82 | \stindex{exec} |
| 83 | \stindex{global} |
| 84 | \ttindex{NameError} |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 85 | |
| 86 | The following table lists the meaning of the local and global name |
| 87 | space for various types of code blocks. The name space for a |
| 88 | particular module is automatically created when the module is first |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 89 | referenced. Note that in almost all cases, the global name space is |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 90 | the name space of the containing module --- scopes in Python do not |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 91 | nest! |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 92 | |
| 93 | \begin{center} |
| 94 | \begin{tabular}{|l|l|l|l|} |
| 95 | \hline |
| 96 | Code block type & Global name space & Local name space & Notes \\ |
| 97 | \hline |
| 98 | Module & n.s. for this module & same as global & \\ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 99 | Script & n.s. for \verb@__main__@ & same as global & \\ |
| 100 | Interactive command & n.s. for \verb@__main__@ & same as global & \\ |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 101 | Class definition & global n.s. of containing block & new n.s. & \\ |
| 102 | Function body & global n.s. of containing block & new n.s. & \\ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 103 | String passed to \verb@exec@ statement |
| 104 | & global n.s. of cobtaining block |
| 105 | & local n.s. of containing block & (1) \\ |
| 106 | String passed to \verb@eval()@ |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 107 | & global n.s. of caller & local n.s. of caller & (1) \\ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 108 | File read by \verb@execfile()@ |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 109 | & global n.s. of caller & local n.s. of caller & (1) \\ |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 110 | Expression read by \verb@input@ |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 111 | & global n.s. of caller & local n.s. of caller & \\ |
| 112 | \hline |
| 113 | \end{tabular} |
| 114 | \end{center} |
Guido van Rossum | aaec403 | 1995-03-21 14:41:57 +0000 | [diff] [blame] | 115 | \bimodindex{__main__} |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 116 | |
| 117 | Notes: |
| 118 | |
| 119 | \begin{description} |
| 120 | |
| 121 | \item[n.s.] means {\em name space} |
| 122 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 123 | \item[(1)] The global and local name space for these can be |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 124 | overridden with optional extra arguments. |
| 125 | |
| 126 | \end{description} |
| 127 | |
Guido van Rossum | 611be70 | 1995-07-07 23:06:33 +0000 | [diff] [blame] | 128 | The built-in functions \verb@globals()@ and \verb@locals()@ returns a |
| 129 | dictionary representing the current global and local name space, |
| 130 | respectively. The effect of modifications to this dictionary on the |
| 131 | name space are undefined.% |
| 132 | \footnote{The current implementations return the dictionary actually |
Guido van Rossum | 46f2157 | 1995-03-07 10:09:34 +0000 | [diff] [blame] | 133 | used to implement the name space, {\em except} for functions, where |
| 134 | the optimizer may cause the local name space to be implemented |
Guido van Rossum | 611be70 | 1995-07-07 23:06:33 +0000 | [diff] [blame] | 135 | differently, and \verb@locals()@ returns a read-only dictionary.} |
Guido van Rossum | 46f2157 | 1995-03-07 10:09:34 +0000 | [diff] [blame] | 136 | |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 137 | \section{Exceptions} |
| 138 | |
| 139 | Exceptions are a means of breaking out of the normal flow of control |
| 140 | of a code block in order to handle errors or other exceptional |
| 141 | conditions. An exception is {\em raised} at the point where the error |
| 142 | is detected; it may be {\em handled} by the surrounding code block or |
| 143 | by any code block that directly or indirectly invoked the code block |
| 144 | where the error occurred. |
| 145 | \index{exception} |
| 146 | \index{raise an exception} |
| 147 | \index{handle an exception} |
| 148 | \index{exception handler} |
| 149 | \index{errors} |
| 150 | \index{error handling} |
| 151 | |
| 152 | The Python interpreter raises an exception when it detects an run-time |
| 153 | error (such as division by zero). A Python program can also |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 154 | explicitly raise an exception with the \verb@raise@ statement. |
| 155 | Exception handlers are specified with the \verb@try...except@ |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 156 | statement. |
| 157 | |
| 158 | Python uses the ``termination'' model of error handling: an exception |
| 159 | handler can find out what happened and continue execution at an outer |
| 160 | level, but it cannot repair the cause of the error and retry the |
| 161 | failing operation (except by re-entering the the offending piece of |
| 162 | code from the top). |
| 163 | |
| 164 | When an exception is not handled at all, the interpreter terminates |
| 165 | execution of the program, or returns to its interactive main loop. |
| 166 | |
| 167 | Exceptions are identified by string objects. Two different string |
| 168 | objects with the same value identify different exceptions. |
| 169 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 170 | When an exception is raised, an object (maybe \verb@None@) is passed |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 171 | as the exception's ``parameter''; this object does not affect the |
| 172 | selection of an exception handler, but is passed to the selected |
| 173 | exception handler as additional information. |
| 174 | |
Guido van Rossum | 6938f06 | 1994-08-01 12:22:53 +0000 | [diff] [blame] | 175 | See also the description of the \verb@try@ and \verb@raise@ |
Guido van Rossum | 46f3e00 | 1992-08-14 09:11:01 +0000 | [diff] [blame] | 176 | statements. |