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

打开 docs.python.org/3/tutorial/controlflow.html#defining-functions 中的教程部分，检查关于外围函数局部符号表的措辞。在进行任何更改之前检查链接的 PR gh-151038；完成的标准是解释明确指向包含定义的函数，而不是调用。