Repository navigation
[doc] Questionable terminology ('free variables') for describing what locals() does #70870
Description
Activity
The docs for locals() say that inside a function that local variables and free variables are included: https://docs.python.org/3/library/functions.html#locals
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 print(locals()) 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.
Regarding “free variables”, in bpo-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 bpo-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.
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 print(locals()) print(globals()) return g >>> f(10)(20) {'y': 20, 'x': 11, 'z': 30} {'w': 5, ...}
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.
marco-buttu commented
on Dec 3, 2016 marco-buttumannequinMannequinThe 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
xis free infoo()::>>> 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 codex` is not a free variable forlocals()``::>>> def foo(): ... print(x) ... print(locals()) ... >>> x = 3 >>> foo() 3 {}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 andlocals(), 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 ofcode.co_freevars(maybe not only this) in order to fit the definition.[1] https://docs.python.org/3/reference/executionmodel.html#naming-and-binding
[2] https://docs.python.org/3/library/functions.html#locals
[3] https://en.wikipedia.org/wiki/Free_variables_and_bound_variablesmarco-buttu commented
on Dec 12, 2016 marco-buttumannequinMannequinAnother point in the doc, where the meaning of "free variable" is inconsistent with the
locals()andcode.co_freevarsmeaning:https://docs.python.org/3/reference/executionmodel.html#interaction-with-dynamic-features
- changed the title
[-]Questionable terminology for describing what locals() does[/-][+][doc] Questionable terminology ('free variables') for describing what locals() does[/+]on Nov 27, 2021 - added a commit that references this issue
on Aug 1, 2024 In 3.13, the
locals()docs now say:In an optimized scope (including functions, generators, and coroutines), each call to locals() instead returns a fresh dictionary containing the current bindings of the function’s local variables and any nonlocal cell references.
I also posted a separate PR after reviewing all the references to "free variable" in the documentation: #122545
While I left some of them alone, I changed several others to either "closure variable", or "free (closure) variable" (sometimes including specific references to
co_freevars).The PR makes the definitions of
co_freevarsand__closure__reference each other and defines both "free variable" and "closure variable" in the glossary. The definition of "free variable" notes that the term gets used in two different ways rather than attempting to exclusively reserve it for the formally correct meaning.
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
Linked PRs