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

Abra a seção do tutorial em docs.python.org/3/tutorial/controlflow.html#defining-functions e revise a redação sobre as tabelas de símbolos locais das funções envolventes. Verifique o PR vinculado gh-151038 antes de fazer qualquer alteração; considera-se concluído quando a explicação se referir claramente às funções que envolvem a definição, e não à chamada.