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

Ouvrez la section du tutoriel à l’adresse docs.python.org/3/tutorial/controlflow.html#defining-functions et vérifiez la formulation concernant les tables de symboles locales des fonctions englobantes. Consultez le PR lié gh-151038 avant d’apporter des modifications ; le travail est terminé lorsque l’explication fait clairement référence aux fonctions qui englobent la définition, et non à l’appel.