[issue26683] Questionable terminology for describing what locals() does

[Marco Buttu]

Marco Buttu added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26683] Questionable terminology for describing what locals() does

[Marco Buttu]

Marco Buttu added the comment:

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

--
nosy: +marco.buttu

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26683] Questionable terminology for describing what locals() does

[Terry J. Reedy]

Terry J. Reedy added the comment:

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.

--
nosy: +terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26683] Questionable terminology for describing what locals() does

[Raymond Hettinger]

Raymond Hettinger added the comment:

> 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, ...}

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26683] Questionable terminology for describing what locals() does

[Martin Panter]

Martin Panter added the comment:

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.

--
nosy: +martin.panter

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26683] Questionable terminology for describing what locals() does

[Raymond Hettinger]

New submission from Raymond Hettinger:

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.

--
assignee: docs@python
components: Documentation
messages: 262713
nosy: docs@python, rhettinger
priority: normal
severity: normal
status: open
title: Questionable terminology for describing what locals() does
versions: Python 2.7, Python 3.5, Python 3.6

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com