What does Python's locals() do?

Question

Python's locals() documentation says:

Update and return a dictionary representing the current local symbol table. Free variables are returned by locals() when it is called in function blocks, but not in class blocks.

1. What are in the current local symbol table exactly?

2. Is the local symbol table guaranteed to be the same as the argument dict if locals() is called at the very beginning of a function?

   For example, if we have the following program:

   def foo(x, y):
       print(locals() == {'x': 1, 'y': 2})
   foo(1, 2)
   

   Will it always output True no matter what platforms and Python implementations we use?

Answer 1

What are in the current local symbol table exactly?

Well, you can take a look yourself. At the very beginging of your Python, program, here is what the symbol table returned by locals() looks like:

print(locals())

Which outputs:

{'__doc__': None, '__spec__': None, '__package__': None, '__builtins__': 
<module 'builtins' (built-in)>, '__name__': '__main__', '__loader__': 
<class '_frozen_importlib.BuiltinImporter'>, 
'__file__': 'C:\\Users\\$Name$\\Desktop\\script.py'}

The symbol table consists of a few "magic variables", and some info about your current Python file. Such as the __file__ key, which contains the name of your current source file. The description of what locals returns pretty much matches the definition for a symbol table:

In computer science, a symbol table is a data structure used by a language translator such as a compiler or interpreter, where each identifier in a program's source code is associated with information relating to its declaration or appearance in the source. - Wikipedia: Symbol table

_{(emphasis mine)}

---

Is the local symbol table guaranteed to be the same as the argument dict if locals() is called at the very beginning of a function?

To which the answer would ¹yes. Functions have their own scope. And, as hinted at by the name, locals() only returns identifiers local to the current scope. So a call to locals() inside of a function, could not be changed by the outer scope of a program. eg.

>>> var = 10 # global variable
>>> locals()['var'] # var is accessible in the current scope
10
>>> def func():
    print(locals()['var']) # but not in this scope. Python will raise an error


>>> func()
Traceback (most recent call last):
  File "<pyshell#17>", line 1, in <module>
    func()
  File "<pyshell#16>", line 2, in func
    print(locals()['var'])
KeyError: 'var'
>>> 

---

¹ _{Its a little hard to fully understand what your asking in your second question, so I apologize if my answer is not related. But I believe your asking: If I call locals() at the beginning of my function, inside of my definition, is the dict() returned by locals guaranteed to stay the same?}. If this isn't the case, update your question and I'll try to re-answer.