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

Mở phần hướng dẫn tại docs.python.org/3/tutorial/controlflow.html#defining-functions và xem lại cách diễn đạt về các bảng ký hiệu cục bộ của các hàm bao quanh. Kiểm tra PR được liên kết gh-151038 trước khi thực hiện bất kỳ thay đổi nào; hoàn tất có nghĩa là phần giải thích đề cập rõ ràng đến các hàm bao quanh phần định nghĩa, thay vì lời gọi.