This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: [doc] Questionable terminology ('free variables') for describing what locals() does
Type: Stage:
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, marco.buttu, martin.panter, rhettinger, terry.reedy
Priority: normal Keywords:

Created on 2016-04-01 01:31 by rhettinger, last changed 2022-04-11 14:58 by admin.

Messages (6)
msg262713 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-04-01 01:31
The docs for locals() say that inside a function that local variables and free variables are included:

Elsewhere we use the terms "cell variables" or "nonlocals".   Mathematically, the word "free" means unbound, so that isn't applicable here and isn't the usual way of describing variables in the enclosing scope.

>>> def f(x):
        def g(y):
            z = x + y
        return g

>>> f(10)(20)
{'x': 10, 'y': 20, 'z': 30}

Also, I'm not sure why "x" and "y" are included in the definition for locals().  That seems strange given that "x" and "y" are not local to "g" and that "x += 1" would fail with an UnboundLocalError.
msg262718 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-04-01 03:36
Regarding “free variables”, in Issue 17546 I proposed the wording “. . . also includes non-local, non-global names”.

In your code example, I would consider y to be 100 percent local to the g() function. It is a function parameter, and “y += 1” should work. I agree x is not a true local, it is a “non-local non-global”. A national variable maybe :)

For functions, considering that you shouldn’t modify the dictionary (original concern in Issue 17546), I do agree the behaviour is a bit strange and inconsistent. It might have made more sense to either only return true locals, or return a complete namespace of locals, non-locals, globals, and builtins. It seems there is no way to get a similar list of non-local non-globals in a class scope.
msg262722 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-04-01 04:53
> A national variable maybe :)

I would think that "nonlocal" is exactly the right term given that that is how you would declare it if you wanted to write to it.

>>> w = 5

>>> def f(x):
        def g(y):
            nonlocal x
            global w
            z = x + y
            x += 1
        return g

>>> f(10)(20)
{'y': 20, 'x': 11, 'z': 30}
{'w': 5, ...}
msg262753 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-04-01 18:24
I requested that we stop (mis)using 'free variable' in the docs years ago.  A strong +1 from me.

The 'locals' function what named when 'local' and 'non-global' were synonyms.  When non-local, non-global names were added, nonlocals were included with 'locals' as 'non-global'.  (This must have been thought to be more useful than adding nonlocals() or excluding them.)

They are, of course, local in some surrounding non-global context.  And for most purposes, their entries in locals() should also be treated as read-only.  I think the doc should say that function locals() includes the locals of surrounding function contexts, even though they are called 'nonlocal' within the nested function.
msg282284 - (view) Author: Marco Buttu (marco.buttu) * Date: 2016-12-03 13:56
The documentation [1] says: "If a variable is used in a code block but not defined there, it is a free variable." According to this description,  it seems to me that the variable ``x`` is free in ``foo()``::

  >>> def foo():
  ...     print(x)

But actually for the code object it is not::

  >>> foo.__code__.co_freevars

The meaning of free variable used for the code object is consistent with the ``locals()`` documentation [2]: "Free variables are returned by locals() when it is called in function blocks". In fact, in the following code ``x` is not a free variable for ``locals()``::

  >>> def foo():
  ...     print(x)
  ...     print(locals())
  >>> x = 3
  >>> foo()

So, I thing there is an inconsistency between the definition of "free variable" given in [1] and the meaning of "free variable" both in the code object and in the ``locals()`` documentation [2]. 
But if we change the definition of "free variable" according to the meaning of both the code object and ``locals()``, I am afraid we go in the wrong direction, because I suspect for most people the proper definition of free variable is the one given in [1]. Also for Wikipedia [3]: "In computer programming, the term free variable refers to variables used in a function that are neither local variables nor parameters of that function.".

Instead, if we keep or remove the definition of "free variable" given in [1], I agree with Terry to change the ``locals()`` documentation, writing that "``locals()`` includes also the locals of the surrounding function contexts, even though they are called 'nonlocal' within the nested function.". Maybe it is also worth adding a shell example, to better clarify. 

So, at the end, to me the ideal solution would be to keep in [1] the current definition of "free variable", to change the ``locals()`` documentation according to Terry suggestion, and to change the behavior of ``code.co_freevars`` (maybe not only this) in order to fit the definition.

msg282989 - (view) Author: Marco Buttu (marco.buttu) * Date: 2016-12-12 12:13
Another point in the doc, where the meaning of "free variable" is inconsistent with the ``locals()`` and ``code.co_freevars`` meaning:
Date User Action Args
2022-04-11 14:58:29adminsetgithub: 70870
2021-11-27 00:24:37iritkatrielsettitle: Questionable terminology for describing what locals() does -> [doc] Questionable terminology ('free variables') for describing what locals() does
versions: + Python 3.9, Python 3.10, Python 3.11, - Python 2.7, Python 3.5, Python 3.6
2016-12-12 12:13:40marco.buttusetmessages: + msg282989
2016-12-03 13:56:18marco.buttusetnosy: + marco.buttu
messages: + msg282284
2016-04-01 18:24:59terry.reedysetnosy: + terry.reedy
messages: + msg262753
2016-04-01 04:53:44rhettingersetmessages: + msg262722
2016-04-01 03:36:16martin.pantersetnosy: + martin.panter
messages: + msg262718
2016-04-01 01:31:32rhettingercreate