[Python-checkins] cpython (merge 3.4 -> 3.5): Merge issue #24129 from 3.4

Wed Aug 5 15:25:28 CEST 2015

https://hg.python.org/cpython/rev/5e4d21311772
changeset: 97273:5e4d21311772
branch: 3.5
parent: 97270:f0cdbc5d2cf3
parent: 97272:94e215a5e24b
user: Nick Coghlan <ncoghlan at gmail.com>
date: Wed Aug 05 23:23:24 2015 +1000
summary:
 Merge issue #24129 from 3.4
files:
 Doc/reference/executionmodel.rst | 173 +++++++++++-------
 Misc/ACKS | 1 +
 Misc/NEWS | 5 +
 3 files changed, 112 insertions(+), 67 deletions(-)

diff --git a/Doc/reference/executionmodel.rst b/Doc/reference/executionmodel.rst
--- a/Doc/reference/executionmodel.rst
+++ b/Doc/reference/executionmodel.rst
@@ -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 program 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.
 
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -836,6 +836,7 @@
 Alain Leufroy
 Mark Levinson
 Mark Levitt
+Ivan Levkivskyi
 William Lewis
 Akira Li
 Xuanji Li
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -40,6 +40,11 @@
 Documentation
 -------------
 
+- Issue #24129: Clarify the reference documentation for name resolution.
+ This includes removing the assumption that readers will be familiar with the
+ name resolution scheme Python used prior to the introduction of lexical
+ scoping for function namespaces. Patch by Ivan Levkivskyi.
+
 - Issue #20769: Improve reload() docs. Patch by Dorian Pula.
 
 - Issue #23589: Remove duplicate sentence from the FAQ. Patch by Yongzhi Pan.
-- 
Repository URL: https://hg.python.org/cpython
