diff -r c0827842102e Doc/reference/executionmodel.rst --- a/Doc/reference/executionmodel.rst Fri Jun 19 13:08:58 2015 -0700 +++ b/Doc/reference/executionmodel.rst Sun Jun 21 15:43:53 2015 +0200 @@ -5,29 +5,18 @@ Execution model *************** -.. index:: single: execution model +.. index:: + single: execution model + pair: code; block +.. _prog_structure: -.. _naming: - -Naming and binding -================== - -.. index:: - pair: code; block - single: namespace - single: scope - -.. index:: - single: name - pair: binding; name - -:dfn:`Names` refer to objects. Names are introduced by name binding operations. -Each occurrence of a name in the program text refers to the :dfn:`binding` of -that name established in the innermost function block containing the use. +Structure of a programm +======================= .. index:: block +A Python programm is constructed from code blocks. A :dfn:`block` is a piece of Python program text that is executed as a unit. The following are blocks: a module, a function body, and a class definition. Each command typed interactively is a block. A script file (a file given as @@ -43,43 +32,25 @@ administrative information (used for debugging) and determines where and how execution continues after the code block's execution has completed. -.. index:: scope +.. _naming: -A :dfn:`scope` defines the visibility of a name within a block. If a local -variable is defined in a block, its scope includes that block. If the -definition occurs in a function block, the scope extends to any blocks contained -within the defining one, unless a contained block introduces a different binding -for the name. The scope of names defined in a class block is limited to the -class block; it does not extend to the code blocks of methods -- this includes -comprehensions and generator expressions since they are implemented using a -function scope. This means that the following will fail:: - - class A: - a = 42 - b = list(a + i for i in range(10)) - -.. index:: single: environment - -When a name is used in a code block, it is resolved using the nearest enclosing -scope. The set of all such scopes visible to a code block is called the block's -:dfn:`environment`. - -.. index:: pair: free; variable - -If a name is bound in a block, it is a local variable of that block, unless -declared as :keyword:`nonlocal`. If a name is bound at the module level, it is -a global variable. (The variables of the module code block are local and -global.) If a variable is used in a code block but not defined there, it is a -:dfn:`free variable`. +Naming and binding +================== .. index:: - single: NameError (built-in exception) - single: UnboundLocalError + single: namespace + single: scope -When a name is not found at all, a :exc:`NameError` exception is raised. If the -name refers to a local variable that has not been bound, an -:exc:`UnboundLocalError` exception is raised. :exc:`UnboundLocalError` is a -subclass of :exc:`NameError`. +.. _bind_names: + +Binding of names +---------------- + +.. index:: + single: name + pair: binding; name + +:dfn:`Names` refer to objects. Names are introduced by name binding operations. .. index:: statement: from @@ -99,6 +70,46 @@ Each assignment or import statement occurs within a block defined by a class or function definition or at the module level (the top-level code block). +.. index:: pair: free; variable + +If a name is bound in a block, it is a local variable of that block, unless +declared as :keyword:`nonlocal` or :keyword:`global`. If a name is bound at the module level, it is +a global variable. (The variables of the module code block are local and +global.) If a variable is used in a code block but not defined there, it is a +:dfn:`free variable`. + +Each occurrence of a name in the program text refers to the :dfn:`binding` of +that name established by the following name resolution rules. + +.. _resolve_names: + +Resolution of names +------------------- + +.. index:: scope + +A :dfn:`scope` defines the visibility of a name within a block. If a local +variable is defined in a block, its scope includes that block. If the +definition occurs in a function block, the scope extends to any blocks contained +within the defining one, unless a contained block introduces a different binding +for the name. + +.. index:: single: environment + +When a name is used in a code block, it is resolved using the nearest enclosing +scope. The set of all such scopes visible to a code block is called the block's +:dfn:`environment`. + +.. index:: + single: NameError (built-in exception) + single: UnboundLocalError + +When a name is not found at all, a :exc:`NameError` exception is raised. +If the current scope is a function scope, and the name refers to a local +variable that has not yet been bound to a value at the point where the name is used, +an :exc:`UnboundLocalError` exception is raised. :exc:`UnboundLocalError` is a +subclass of :exc:`NameError`. + If a name binding operation occurs anywhere within a code block, all uses of the name within the block are treated as references to the current block. This can lead to errors when a name is used within a block before it is bound. This rule @@ -115,7 +126,41 @@ builtins namespace is searched. The :keyword:`global` statement must precede all uses of the name. -.. XXX document "nonlocal" semantics here +The :keyword:`global` statement has the same scope as a name binding operation +in the same block. If the nearest enclosing scope for a free variable contains +a global statement, the free variable is treated as a global. + +.. XXX say more about "nonlocal" semantics here + +The :keyword:`nonlocal` statement causes corresponding names to refer +to previously bound variables in the nearest enclosing function scope. +:exc:`SyntaxError` is raised at compile time if the given name does not +exist in any enclosing function scope. + +.. index:: module: __main__ + +The namespace for a module is automatically created the first time a module is +imported. The main module for a script is always called :mod:`__main__`. + +Class definition blocks and arguments to :func:`exec` and :func:`eval` are special +in the context of name resolution. +A class definition is an executable statement that may use and define names. +These references follow the normal rules for name resolution with an exception that +unbound local variables are looked up in the global namespace. +The namespace of the class definition becomes the attribute dictionary of +the class. The scope of names defined in a class block is limited to the +class block; it does not extend to the code blocks of methods -- this includes +comprehensions and generator expressions since they are implemented using a +function scope. This means that the following will fail:: + + class A: + a = 42 + b = list(a + i for i in range(10)) + +.. _restrict_exec: + +Builtins and restricted execution +--------------------------------- .. index:: pair: restricted; execution @@ -135,26 +180,20 @@ :keyword:`import` the :mod:`builtins` module and modify its attributes appropriately. -.. index:: module: __main__ - -The namespace for a module is automatically created the first time a module is -imported. The main module for a script is always called :mod:`__main__`. - -The :keyword:`global` statement has the same scope as a name binding operation -in the same block. If the nearest enclosing scope for a free variable contains -a global statement, the free variable is treated as a global. - -A class definition is an executable statement that may use and define names. -These references follow the normal rules for name resolution. The namespace of -the class definition becomes the attribute dictionary of the class. Names -defined at the class scope are not visible in methods. - - .. _dynamic-features: Interaction with dynamic features --------------------------------- +Name resolution of free variables occurs at runtime, not at compile time. +This means that the following code will print 42:: + + i = 10 + def f(): + print(i) + i = 42 + f() + There are several cases where Python statements are illegal when used in conjunction with nested scopes that contain free variables.