1 2.. _execmodel: 3 4*************** 5Execution model 6*************** 7 8.. index:: 9 single: execution model 10 pair: code; block 11 12.. _prog_structure: 13 14Structure of a program 15====================== 16 17.. index:: block 18 19A Python program is constructed from code blocks. 20A :dfn:`block` is a piece of Python program text that is executed as a unit. 21The following are blocks: a module, a function body, and a class definition. 22Each command typed interactively is a block. A script file (a file given as 23standard input to the interpreter or specified as a command line argument to the 24interpreter) is a code block. A script command (a command specified on the 25interpreter command line with the :option:`-c` option) is a code block. 26A module run as a top level script (as module ``__main__``) from the command 27line using a :option:`-m` argument is also a code block. The string 28argument passed to the built-in functions :func:`eval` and :func:`exec` is a 29code block. 30 31.. index:: pair: execution; frame 32 33A code block is executed in an :dfn:`execution frame`. A frame contains some 34administrative information (used for debugging) and determines where and how 35execution continues after the code block's execution has completed. 36 37.. _naming: 38 39Naming and binding 40================== 41 42.. index:: 43 single: namespace 44 single: scope 45 46.. _bind_names: 47 48Binding of names 49---------------- 50 51.. index:: 52 single: name 53 pair: binding; name 54 55:dfn:`Names` refer to objects. Names are introduced by name binding operations. 56 57.. index:: single: from; import statement 58 59The following constructs bind names: 60 61* formal parameters to functions, 62* class definitions, 63* function definitions, 64* assignment expressions, 65* :ref:`targets <assignment>` that are identifiers if occurring in 66 an assignment: 67 68 + :keyword:`for` loop header, 69 + after :keyword:`!as` in a :keyword:`with` statement, :keyword:`except` 70 clause, :keyword:`except* <except_star>` clause, or in the as-pattern in structural pattern matching, 71 + in a capture pattern in structural pattern matching 72 73* :keyword:`import` statements. 74* :keyword:`type` statements. 75* :ref:`type parameter lists <type-params>`. 76 77The :keyword:`!import` statement of the form ``from ... import *`` binds all 78names defined in the imported module, except those beginning with an underscore. 79This form may only be used at the module level. 80 81A target occurring in a :keyword:`del` statement is also considered bound for 82this purpose (though the actual semantics are to unbind the name). 83 84Each assignment or import statement occurs within a block defined by a class or 85function definition or at the module level (the top-level code block). 86 87.. index:: pair: free; variable 88 89If a name is bound in a block, it is a local variable of that block, unless 90declared as :keyword:`nonlocal` or :keyword:`global`. If a name is bound at 91the module level, it is a global variable. (The variables of the module code 92block are local and global.) If a variable is used in a code block but not 93defined there, it is a :term:`free variable`. 94 95Each occurrence of a name in the program text refers to the :dfn:`binding` of 96that name established by the following name resolution rules. 97 98.. _resolve_names: 99 100Resolution of names 101------------------- 102 103.. index:: scope 104 105A :dfn:`scope` defines the visibility of a name within a block. If a local 106variable is defined in a block, its scope includes that block. If the 107definition occurs in a function block, the scope extends to any blocks contained 108within the defining one, unless a contained block introduces a different binding 109for the name. 110 111.. index:: single: environment 112 113When a name is used in a code block, it is resolved using the nearest enclosing 114scope. The set of all such scopes visible to a code block is called the block's 115:dfn:`environment`. 116 117.. index:: 118 single: NameError (built-in exception) 119 single: UnboundLocalError 120 121When a name is not found at all, a :exc:`NameError` exception is raised. 122If the current scope is a function scope, and the name refers to a local 123variable that has not yet been bound to a value at the point where the name is 124used, an :exc:`UnboundLocalError` exception is raised. 125:exc:`UnboundLocalError` is a subclass of :exc:`NameError`. 126 127If a name binding operation occurs anywhere within a code block, all uses of the 128name within the block are treated as references to the current block. This can 129lead to errors when a name is used within a block before it is bound. This rule 130is subtle. Python lacks declarations and allows name binding operations to 131occur anywhere within a code block. The local variables of a code block can be 132determined by scanning the entire text of the block for name binding operations. 133See :ref:`the FAQ entry on UnboundLocalError <faq-unboundlocalerror>` 134for examples. 135 136If the :keyword:`global` statement occurs within a block, all uses of the names 137specified in the statement refer to the bindings of those names in the top-level 138namespace. Names are resolved in the top-level namespace by searching the 139global namespace, i.e. the namespace of the module containing the code block, 140and the builtins namespace, the namespace of the module :mod:`builtins`. The 141global namespace is searched first. If the names are not found there, the 142builtins namespace is searched next. If the names are also not found in the 143builtins namespace, new variables are created in the global namespace. 144The global statement must precede all uses of the listed names. 145 146The :keyword:`global` statement has the same scope as a name binding operation 147in the same block. If the nearest enclosing scope for a free variable contains 148a global statement, the free variable is treated as a global. 149 150.. XXX say more about "nonlocal" semantics here 151 152The :keyword:`nonlocal` statement causes corresponding names to refer 153to previously bound variables in the nearest enclosing function scope. 154:exc:`SyntaxError` is raised at compile time if the given name does not 155exist in any enclosing function scope. :ref:`Type parameters <type-params>` 156cannot be rebound with the :keyword:`!nonlocal` statement. 157 158.. index:: pair: module; __main__ 159 160The namespace for a module is automatically created the first time a module is 161imported. The main module for a script is always called :mod:`__main__`. 162 163Class definition blocks and arguments to :func:`exec` and :func:`eval` are 164special in the context of name resolution. 165A class definition is an executable statement that may use and define names. 166These references follow the normal rules for name resolution with an exception 167that unbound local variables are looked up in the global namespace. 168The namespace of the class definition becomes the attribute dictionary of 169the class. The scope of names defined in a class block is limited to the 170class block; it does not extend to the code blocks of methods. This includes 171comprehensions and generator expressions, but it does not include 172:ref:`annotation scopes <annotation-scopes>`, 173which have access to their enclosing class scopes. 174This means that the following will fail:: 175 176 class A: 177 a = 42 178 b = list(a + i for i in range(10)) 179 180However, the following will succeed:: 181 182 class A: 183 type Alias = Nested 184 class Nested: pass 185 186 print(A.Alias.__value__) # <type 'A.Nested'> 187 188.. _annotation-scopes: 189 190Annotation scopes 191----------------- 192 193:ref:`Type parameter lists <type-params>` and :keyword:`type` statements 194introduce *annotation scopes*, which behave mostly like function scopes, 195but with some exceptions discussed below. :term:`Annotations <annotation>` 196currently do not use annotation scopes, but they are expected to use 197annotation scopes in Python 3.13 when :pep:`649` is implemented. 198 199Annotation scopes are used in the following contexts: 200 201* Type parameter lists for :ref:`generic type aliases <generic-type-aliases>`. 202* Type parameter lists for :ref:`generic functions <generic-functions>`. 203 A generic function's annotations are 204 executed within the annotation scope, but its defaults and decorators are not. 205* Type parameter lists for :ref:`generic classes <generic-classes>`. 206 A generic class's base classes and 207 keyword arguments are executed within the annotation scope, but its decorators are not. 208* The bounds, constraints, and default values for type parameters 209 (:ref:`lazily evaluated <lazy-evaluation>`). 210* The value of type aliases (:ref:`lazily evaluated <lazy-evaluation>`). 211 212Annotation scopes differ from function scopes in the following ways: 213 214* Annotation scopes have access to their enclosing class namespace. 215 If an annotation scope is immediately within a class scope, or within another 216 annotation scope that is immediately within a class scope, the code in the 217 annotation scope can use names defined in the class scope as if it were 218 executed directly within the class body. This contrasts with regular 219 functions defined within classes, which cannot access names defined in the class scope. 220* Expressions in annotation scopes cannot contain :keyword:`yield`, ``yield from``, 221 :keyword:`await`, or :token:`:= <python-grammar:assignment_expression>` 222 expressions. (These expressions are allowed in other scopes contained within the 223 annotation scope.) 224* Names defined in annotation scopes cannot be rebound with :keyword:`nonlocal` 225 statements in inner scopes. This includes only type parameters, as no other 226 syntactic elements that can appear within annotation scopes can introduce new names. 227* While annotation scopes have an internal name, that name is not reflected in the 228 :term:`qualified name` of objects defined within the scope. 229 Instead, the :attr:`~definition.__qualname__` 230 of such objects is as if the object were defined in the enclosing scope. 231 232.. versionadded:: 3.12 233 Annotation scopes were introduced in Python 3.12 as part of :pep:`695`. 234 235.. versionchanged:: 3.13 236 Annotation scopes are also used for type parameter defaults, as 237 introduced by :pep:`696`. 238 239.. _lazy-evaluation: 240 241Lazy evaluation 242--------------- 243 244The values of type aliases created through the :keyword:`type` statement are 245*lazily evaluated*. The same applies to the bounds, constraints, and default values of type 246variables created through the :ref:`type parameter syntax <type-params>`. 247This means that they are not evaluated when the type alias or type variable is 248created. Instead, they are only evaluated when doing so is necessary to resolve 249an attribute access. 250 251Example: 252 253.. doctest:: 254 255 >>> type Alias = 1/0 256 >>> Alias.__value__ 257 Traceback (most recent call last): 258 ... 259 ZeroDivisionError: division by zero 260 >>> def func[T: 1/0](): pass 261 >>> T = func.__type_params__[0] 262 >>> T.__bound__ 263 Traceback (most recent call last): 264 ... 265 ZeroDivisionError: division by zero 266 267Here the exception is raised only when the ``__value__`` attribute 268of the type alias or the ``__bound__`` attribute of the type variable 269is accessed. 270 271This behavior is primarily useful for references to types that have not 272yet been defined when the type alias or type variable is created. For example, 273lazy evaluation enables creation of mutually recursive type aliases:: 274 275 from typing import Literal 276 277 type SimpleExpr = int | Parenthesized 278 type Parenthesized = tuple[Literal["("], Expr, Literal[")"]] 279 type Expr = SimpleExpr | tuple[SimpleExpr, Literal["+", "-"], Expr] 280 281Lazily evaluated values are evaluated in :ref:`annotation scope <annotation-scopes>`, 282which means that names that appear inside the lazily evaluated value are looked up 283as if they were used in the immediately enclosing scope. 284 285.. versionadded:: 3.12 286 287.. _restrict_exec: 288 289Builtins and restricted execution 290--------------------------------- 291 292.. index:: pair: restricted; execution 293 294.. impl-detail:: 295 296 Users should not touch ``__builtins__``; it is strictly an implementation 297 detail. Users wanting to override values in the builtins namespace should 298 :keyword:`import` the :mod:`builtins` module and modify its 299 attributes appropriately. 300 301The builtins namespace associated with the execution of a code block 302is actually found by looking up the name ``__builtins__`` in its 303global namespace; this should be a dictionary or a module (in the 304latter case the module's dictionary is used). By default, when in the 305:mod:`__main__` module, ``__builtins__`` is the built-in module 306:mod:`builtins`; when in any other module, ``__builtins__`` is an 307alias for the dictionary of the :mod:`builtins` module itself. 308 309 310.. _dynamic-features: 311 312Interaction with dynamic features 313--------------------------------- 314 315Name resolution of free variables occurs at runtime, not at compile time. 316This means that the following code will print 42:: 317 318 i = 10 319 def f(): 320 print(i) 321 i = 42 322 f() 323 324.. XXX from * also invalid with relative imports (at least currently) 325 326The :func:`eval` and :func:`exec` functions do not have access to the full 327environment for resolving names. Names may be resolved in the local and global 328namespaces of the caller. Free variables are not resolved in the nearest 329enclosing namespace, but in the global namespace. [#]_ The :func:`exec` and 330:func:`eval` functions have optional arguments to override the global and local 331namespace. If only one namespace is specified, it is used for both. 332 333.. XXX(ncoghlan) above is only accurate for string execution. When executing code objects, 334 closure cells may now be passed explicitly to resolve co_freevars references. 335 Docs issue: https://github.com/python/cpython/issues/122826 336 337.. _exceptions: 338 339Exceptions 340========== 341 342.. index:: single: exception 343 344.. index:: 345 single: raise an exception 346 single: handle an exception 347 single: exception handler 348 single: errors 349 single: error handling 350 351Exceptions are a means of breaking out of the normal flow of control of a code 352block in order to handle errors or other exceptional conditions. An exception 353is *raised* at the point where the error is detected; it may be *handled* by the 354surrounding code block or by any code block that directly or indirectly invoked 355the code block where the error occurred. 356 357The Python interpreter raises an exception when it detects a run-time error 358(such as division by zero). A Python program can also explicitly raise an 359exception with the :keyword:`raise` statement. Exception handlers are specified 360with the :keyword:`try` ... :keyword:`except` statement. The :keyword:`finally` 361clause of such a statement can be used to specify cleanup code which does not 362handle the exception, but is executed whether an exception occurred or not in 363the preceding code. 364 365.. index:: single: termination model 366 367Python uses the "termination" model of error handling: an exception handler can 368find out what happened and continue execution at an outer level, but it cannot 369repair the cause of the error and retry the failing operation (except by 370re-entering the offending piece of code from the top). 371 372.. index:: single: SystemExit (built-in exception) 373 374When an exception is not handled at all, the interpreter terminates execution of 375the program, or returns to its interactive main loop. In either case, it prints 376a stack traceback, except when the exception is :exc:`SystemExit`. 377 378Exceptions are identified by class instances. The :keyword:`except` clause is 379selected depending on the class of the instance: it must reference the class of 380the instance or a :term:`non-virtual base class <abstract base class>` thereof. 381The instance can be received by the handler and can carry additional information 382about the exceptional condition. 383 384.. note:: 385 386 Exception messages are not part of the Python API. Their contents may change 387 from one version of Python to the next without warning and should not be 388 relied on by code which will run under multiple versions of the interpreter. 389 390See also the description of the :keyword:`try` statement in section :ref:`try` 391and :keyword:`raise` statement in section :ref:`raise`. 392 393 394.. rubric:: Footnotes 395 396.. [#] This limitation occurs because the code that is executed by these operations 397 is not available at the time the module is compiled. 398