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.

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()
  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 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.

[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_variables

Another point in the doc, where the meaning of "free variable" is inconsistent with the locals() and code.co_freevars meaning:

https://docs.python.org/3/reference/executionmodel.html#interaction-with-dynamic-features

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_freevars and __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.