Why use "locals()"

[Terry Reedy]

Sion Arrowsmith wrote:
> Gabriel Genellina <gagsl-py2 at yahoo.com.ar> wrote:
>> <sion at viridian.paintbox> escribi�:
>>> What I'm not clear about is under what circumstances locals() does
>>> not produce the same result as vars() .
>> py> help(vars)
>> Help on built-in function vars in module __builtin__:
>>
>> vars(...)
>>     vars([object]) -> dictionary
>>
>>     Without arguments, equivalent to locals().
>>     With an argument, equivalent to object.__dict__.
> 
> Meh, that's what I get for trying to make sense of
> http://docs.python.org/library/functions.html#vars
> -- which implies the above, but isn't explicit about
> it -- rather than using help. In particular, the docs
> for locals talk about the inclusion of free variables
> in functions, which is absent for vars, which might
> imply that there is a difference.

I believe the 'free var' stuff is a doc error, so I filed
http://bugs.python.org/issue6925
Doc for locals and vars

tjr