Tutorial on defining functions has potentially misleading explanation of closure

Documentation

Apologies if I'm using the term closure wrong, I come from more of a Scheme background.

The tutorial says that variable references look "in the local symbol tables of enclosing functions". However, it is not obvious that this refers to functions enclosing the definition, rather than functions enclosing a call to the function. When I first read it I was somewhat confused as it seemed to contradict what I knew about closure in Python.

The following demonstrates half of this:

>>> def f():
...     print(n)
...     
>>> n = 1
>>> f()
1
>>> def g():
...     n = 2
...     f()
...     
>>> g()
1
>>>

If the variable reference looked in the executing function's local symbol table, we would expect that the last call to g would print 2, rather than 1. However, it does not look in the symbol table of the function enclosing its call, going straight to the global symbol table.

This demonstrates the other half, where the value is obtained from the local symbol table of the function enclosing the call:

>>> def f():
...     def g():
...         print(n)
...     n = 1
...     g()
...     n = 2
...     g()
...     
>>> f()
1
2
>>> 

In my opinion all that is required is a change in wording, perhaps to "functions enclosing the definition".

Linked PRs

• gh-151038

Open the tutorial section at docs.python.org/3/tutorial/controlflow.html#defining-functions and review the wording about local symbol tables of enclosing functions. Check the linked PR gh-151038 before making any changes; done means the explanation clearly refers to functions enclosing the definition rather than the call.