Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | |
| 2 | .. _execmodel: |
| 3 | |
| 4 | *************** |
| 5 | Execution model |
| 6 | *************** |
| 7 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | .. index:: |
Nick Coghlan | 91e561a | 2015-08-05 23:07:24 +1000 | [diff] [blame] | 9 | single: execution model |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | pair: code; block |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | |
Nick Coghlan | 91e561a | 2015-08-05 23:07:24 +1000 | [diff] [blame] | 12 | .. _prog_structure: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | |
R David Murray | 51d3f8b | 2015-11-20 09:57:20 -0500 | [diff] [blame] | 14 | Structure of a program |
| 15 | ====================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 17 | .. index:: block |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 18 | |
Nick Coghlan | 91e561a | 2015-08-05 23:07:24 +1000 | [diff] [blame] | 19 | A Python program is constructed from code blocks. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | A :dfn:`block` is a piece of Python program text that is executed as a unit. |
| 21 | The following are blocks: a module, a function body, and a class definition. |
| 22 | Each command typed interactively is a block. A script file (a file given as |
Raymond Hettinger | aa7886d | 2014-05-26 22:20:37 -0700 | [diff] [blame] | 23 | standard input to the interpreter or specified as a command line argument to the |
| 24 | interpreter) is a code block. A script command (a command specified on the |
| 25 | interpreter command line with the '**-c**' option) is a code block. The string |
| 26 | argument passed to the built-in functions :func:`eval` and :func:`exec` is a |
| 27 | code block. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | |
| 29 | .. index:: pair: execution; frame |
| 30 | |
| 31 | A code block is executed in an :dfn:`execution frame`. A frame contains some |
| 32 | administrative information (used for debugging) and determines where and how |
| 33 | execution continues after the code block's execution has completed. |
| 34 | |
Nick Coghlan | 91e561a | 2015-08-05 23:07:24 +1000 | [diff] [blame] | 35 | .. _naming: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 36 | |
Nick Coghlan | 91e561a | 2015-08-05 23:07:24 +1000 | [diff] [blame] | 37 | Naming and binding |
| 38 | ================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | |
| 40 | .. index:: |
Nick Coghlan | 91e561a | 2015-08-05 23:07:24 +1000 | [diff] [blame] | 41 | single: namespace |
| 42 | single: scope |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | |
Nick Coghlan | 91e561a | 2015-08-05 23:07:24 +1000 | [diff] [blame] | 44 | .. _bind_names: |
| 45 | |
| 46 | Binding of names |
| 47 | ---------------- |
| 48 | |
| 49 | .. index:: |
| 50 | single: name |
| 51 | pair: binding; name |
| 52 | |
| 53 | :dfn:`Names` refer to objects. Names are introduced by name binding operations. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 54 | |
| 55 | .. index:: statement: from |
| 56 | |
| 57 | The following constructs bind names: formal parameters to functions, |
| 58 | :keyword:`import` statements, class and function definitions (these bind the |
| 59 | class or function name in the defining block), and targets that are identifiers |
Georg Brandl | 7f15786 | 2009-03-15 21:57:20 +0000 | [diff] [blame] | 60 | if occurring in an assignment, :keyword:`for` loop header, or after |
Georg Brandl | 682d7e0 | 2010-10-06 10:26:05 +0000 | [diff] [blame] | 61 | :keyword:`as` in a :keyword:`with` statement or :keyword:`except` clause. |
Georg Brandl | 7f15786 | 2009-03-15 21:57:20 +0000 | [diff] [blame] | 62 | The :keyword:`import` statement |
| 63 | of the form ``from ... import *`` binds all names defined in the imported |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 64 | module, except those beginning with an underscore. This form may only be used |
| 65 | at the module level. |
| 66 | |
| 67 | A target occurring in a :keyword:`del` statement is also considered bound for |
Benjamin Peterson | c6696d2 | 2011-02-26 21:32:16 +0000 | [diff] [blame] | 68 | this purpose (though the actual semantics are to unbind the name). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
| 70 | Each assignment or import statement occurs within a block defined by a class or |
| 71 | function definition or at the module level (the top-level code block). |
| 72 | |
Nick Coghlan | 91e561a | 2015-08-05 23:07:24 +1000 | [diff] [blame] | 73 | .. index:: pair: free; variable |
| 74 | |
| 75 | If a name is bound in a block, it is a local variable of that block, unless |
| 76 | declared as :keyword:`nonlocal` or :keyword:`global`. If a name is bound at |
| 77 | the module level, it is a global variable. (The variables of the module code |
| 78 | block are local and global.) If a variable is used in a code block but not |
| 79 | defined there, it is a :dfn:`free variable`. |
| 80 | |
| 81 | Each occurrence of a name in the program text refers to the :dfn:`binding` of |
| 82 | that name established by the following name resolution rules. |
| 83 | |
| 84 | .. _resolve_names: |
| 85 | |
| 86 | Resolution of names |
| 87 | ------------------- |
| 88 | |
| 89 | .. index:: scope |
| 90 | |
| 91 | A :dfn:`scope` defines the visibility of a name within a block. If a local |
| 92 | variable is defined in a block, its scope includes that block. If the |
| 93 | definition occurs in a function block, the scope extends to any blocks contained |
| 94 | within the defining one, unless a contained block introduces a different binding |
| 95 | for the name. |
| 96 | |
| 97 | .. index:: single: environment |
| 98 | |
| 99 | When a name is used in a code block, it is resolved using the nearest enclosing |
| 100 | scope. The set of all such scopes visible to a code block is called the block's |
| 101 | :dfn:`environment`. |
| 102 | |
| 103 | .. index:: |
| 104 | single: NameError (built-in exception) |
| 105 | single: UnboundLocalError |
| 106 | |
| 107 | When a name is not found at all, a :exc:`NameError` exception is raised. |
| 108 | If the current scope is a function scope, and the name refers to a local |
| 109 | variable that has not yet been bound to a value at the point where the name is |
| 110 | used, an :exc:`UnboundLocalError` exception is raised. |
| 111 | :exc:`UnboundLocalError` is a subclass of :exc:`NameError`. |
| 112 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 113 | If a name binding operation occurs anywhere within a code block, all uses of the |
| 114 | name within the block are treated as references to the current block. This can |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 115 | lead to errors when a name is used within a block before it is bound. This rule |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | is subtle. Python lacks declarations and allows name binding operations to |
| 117 | occur anywhere within a code block. The local variables of a code block can be |
| 118 | determined by scanning the entire text of the block for name binding operations. |
| 119 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 120 | If the :keyword:`global` statement occurs within a block, all uses of the name |
| 121 | specified in the statement refer to the binding of that name in the top-level |
| 122 | namespace. Names are resolved in the top-level namespace by searching the |
| 123 | global namespace, i.e. the namespace of the module containing the code block, |
Georg Brandl | 22b3431 | 2009-07-26 14:54:51 +0000 | [diff] [blame] | 124 | and the builtins namespace, the namespace of the module :mod:`builtins`. The |
Georg Brandl | a4c8c47 | 2014-10-31 10:38:49 +0100 | [diff] [blame] | 125 | global namespace is searched first. If the name is not found there, the |
| 126 | builtins namespace is searched. The :keyword:`global` statement must precede |
| 127 | all uses of the name. |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 128 | |
Nick Coghlan | 91e561a | 2015-08-05 23:07:24 +1000 | [diff] [blame] | 129 | The :keyword:`global` statement has the same scope as a name binding operation |
| 130 | in the same block. If the nearest enclosing scope for a free variable contains |
| 131 | a global statement, the free variable is treated as a global. |
| 132 | |
| 133 | .. XXX say more about "nonlocal" semantics here |
| 134 | |
| 135 | The :keyword:`nonlocal` statement causes corresponding names to refer |
| 136 | to previously bound variables in the nearest enclosing function scope. |
| 137 | :exc:`SyntaxError` is raised at compile time if the given name does not |
| 138 | exist in any enclosing function scope. |
| 139 | |
| 140 | .. index:: module: __main__ |
| 141 | |
| 142 | The namespace for a module is automatically created the first time a module is |
| 143 | imported. The main module for a script is always called :mod:`__main__`. |
| 144 | |
| 145 | Class definition blocks and arguments to :func:`exec` and :func:`eval` are |
| 146 | special in the context of name resolution. |
| 147 | A class definition is an executable statement that may use and define names. |
| 148 | These references follow the normal rules for name resolution with an exception |
| 149 | that unbound local variables are looked up in the global namespace. |
| 150 | The namespace of the class definition becomes the attribute dictionary of |
| 151 | the class. The scope of names defined in a class block is limited to the |
| 152 | class block; it does not extend to the code blocks of methods -- this includes |
| 153 | comprehensions and generator expressions since they are implemented using a |
| 154 | function scope. This means that the following will fail:: |
| 155 | |
| 156 | class A: |
| 157 | a = 42 |
| 158 | b = list(a + i for i in range(10)) |
| 159 | |
| 160 | .. _restrict_exec: |
| 161 | |
| 162 | Builtins and restricted execution |
| 163 | --------------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 164 | |
| 165 | .. index:: pair: restricted; execution |
| 166 | |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 167 | .. impl-detail:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 168 | |
| 169 | Users should not touch ``__builtins__``; it is strictly an implementation |
Georg Brandl | 93dc9eb | 2010-03-14 10:56:14 +0000 | [diff] [blame] | 170 | detail. Users wanting to override values in the builtins namespace should |
Georg Brandl | 1a3284e | 2007-12-02 09:40:06 +0000 | [diff] [blame] | 171 | :keyword:`import` the :mod:`builtins` module and modify its |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 172 | attributes appropriately. |
| 173 | |
Naomi Ceder | 43c8a9e | 2017-05-22 14:09:55 -0700 | [diff] [blame] | 174 | The builtins namespace associated with the execution of a code block |
| 175 | is actually found by looking up the name ``__builtins__`` in its |
| 176 | global namespace; this should be a dictionary or a module (in the |
| 177 | latter case the module's dictionary is used). By default, when in the |
| 178 | :mod:`__main__` module, ``__builtins__`` is the built-in module |
| 179 | :mod:`builtins`; when in any other module, ``__builtins__`` is an |
| 180 | alias for the dictionary of the :mod:`builtins` module itself. |
| 181 | |
| 182 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 183 | .. _dynamic-features: |
| 184 | |
| 185 | Interaction with dynamic features |
| 186 | --------------------------------- |
| 187 | |
Nick Coghlan | 91e561a | 2015-08-05 23:07:24 +1000 | [diff] [blame] | 188 | Name resolution of free variables occurs at runtime, not at compile time. |
| 189 | This means that the following code will print 42:: |
| 190 | |
| 191 | i = 10 |
| 192 | def f(): |
| 193 | print(i) |
| 194 | i = 42 |
| 195 | f() |
| 196 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 197 | .. XXX from * also invalid with relative imports (at least currently) |
| 198 | |
| 199 | The :func:`eval` and :func:`exec` functions do not have access to the full |
| 200 | environment for resolving names. Names may be resolved in the local and global |
| 201 | namespaces of the caller. Free variables are not resolved in the nearest |
| 202 | enclosing namespace, but in the global namespace. [#]_ The :func:`exec` and |
| 203 | :func:`eval` functions have optional arguments to override the global and local |
| 204 | namespace. If only one namespace is specified, it is used for both. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 205 | |
| 206 | |
| 207 | .. _exceptions: |
| 208 | |
| 209 | Exceptions |
| 210 | ========== |
| 211 | |
| 212 | .. index:: single: exception |
| 213 | |
| 214 | .. index:: |
| 215 | single: raise an exception |
| 216 | single: handle an exception |
| 217 | single: exception handler |
| 218 | single: errors |
| 219 | single: error handling |
| 220 | |
| 221 | Exceptions are a means of breaking out of the normal flow of control of a code |
| 222 | block in order to handle errors or other exceptional conditions. An exception |
| 223 | is *raised* at the point where the error is detected; it may be *handled* by the |
| 224 | surrounding code block or by any code block that directly or indirectly invoked |
| 225 | the code block where the error occurred. |
| 226 | |
| 227 | The Python interpreter raises an exception when it detects a run-time error |
| 228 | (such as division by zero). A Python program can also explicitly raise an |
| 229 | exception with the :keyword:`raise` statement. Exception handlers are specified |
Alexandre Vassalotti | eca20b6 | 2008-05-16 02:54:33 +0000 | [diff] [blame] | 230 | with the :keyword:`try` ... :keyword:`except` statement. The :keyword:`finally` |
| 231 | clause of such a statement can be used to specify cleanup code which does not |
| 232 | handle the exception, but is executed whether an exception occurred or not in |
| 233 | the preceding code. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 234 | |
| 235 | .. index:: single: termination model |
| 236 | |
| 237 | Python uses the "termination" model of error handling: an exception handler can |
| 238 | find out what happened and continue execution at an outer level, but it cannot |
| 239 | repair the cause of the error and retry the failing operation (except by |
| 240 | re-entering the offending piece of code from the top). |
| 241 | |
| 242 | .. index:: single: SystemExit (built-in exception) |
| 243 | |
| 244 | When an exception is not handled at all, the interpreter terminates execution of |
| 245 | the program, or returns to its interactive main loop. In either case, it prints |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 246 | a stack backtrace, except when the exception is :exc:`SystemExit`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 247 | |
| 248 | Exceptions are identified by class instances. The :keyword:`except` clause is |
| 249 | selected depending on the class of the instance: it must reference the class of |
| 250 | the instance or a base class thereof. The instance can be received by the |
| 251 | handler and can carry additional information about the exceptional condition. |
| 252 | |
Georg Brandl | e720c0a | 2009-04-27 16:20:50 +0000 | [diff] [blame] | 253 | .. note:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 254 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 255 | Exception messages are not part of the Python API. Their contents may change |
| 256 | from one version of Python to the next without warning and should not be |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 257 | relied on by code which will run under multiple versions of the interpreter. |
| 258 | |
| 259 | See also the description of the :keyword:`try` statement in section :ref:`try` |
| 260 | and :keyword:`raise` statement in section :ref:`raise`. |
| 261 | |
Georg Brandl | 1aea30a | 2008-07-19 15:51:07 +0000 | [diff] [blame] | 262 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 263 | .. rubric:: Footnotes |
| 264 | |
Georg Brandl | 96593ed | 2007-09-07 14:15:41 +0000 | [diff] [blame] | 265 | .. [#] This limitation occurs because the code that is executed by these operations |
| 266 | is not available at the time the module is compiled. |