Why doesn't Python's nonlocal keyword like the global scope?

Question

In Python 3.3.1, this works:

i = 76

def A():
    global i
    i += 10

print(i) # 76
A()
print(i) # 86

This also works:

def enclosing_function():
    i = 76
    def A():
        nonlocal i
        i += 10

    print(i) # 76
    A()
    print(i) # 86

enclosing_function()

But this doesn't work:

i = 76
def A():
    nonlocal i # "SyntaxError: no binding for nonlocal 'i' found"
    i += 10

print(i)
A()
print(i)

The documentation for the nonlocal keyword states (emphasis added):

The nonlocal statement causes the listed identifiers to refer to previously bound variables in the nearest enclosing scope.

In the third example, the "nearest enclosing scope" just happens to be the global scope. So why doesn't it work?

PLEASE READ THIS BIT

I do notice that the documentation goes on to state (emphasis added):

The [nonlocal] statement allows encapsulated code to rebind variables outside of the local scope besides the global (module) scope.

but, strictly speaking, this doesn't mean that what I'm doing in the third example shouldn't work.

Answer 1

The search order for names is LEGB, i.e Local, Enclosing, Global, Builtin. So the global scope is not an enclosing scope.

EDIT

From the docs:

The nonlocal statement causes the listed identifiers to refer to previously bound variables in the nearest enclosing scope. This is important because the default behavior for binding is to search the local namespace first. The statement allows encapsulated code to rebind variables outside of the local scope besides the global (module) scope.

Answer 2

why is a module's scope considered global and not an enclosing one? It's still not global to other modules (well, unless you do from module import *), is it?

If you put some name into module's namespace; it is visible in any module that uses module i.e., it is global for the whole Python process.

In general, your application should use as few mutable globals as possible. See Why globals are bad?:

• Non-locality
• No Access Control or Constraint Checking
• Implicit coupling
• Concurrency issues
• Namespace pollution
• Testing and Confinement

Therefore It would be bad if nonlocal allowed to create globals by accident. If you want to modify a global variable; you could use global keyword directly.

• global is the most destructive: may affect all uses of the module anywhere in the program
• nonlocal is less destructive: limited by the outer() function scope (the binding is checked at compile time)
• no declaration (local variable) is the least destructive option: limited by inner() function scope

You can read about history and motivation behind nonlocal in PEP: 3104 Access to Names in Outer Scopes.