DOCS: Suggest always calling exec with a globals argument and no locals argument (GH-119235)

Many users think they want a locals argument for various reasons but they do not
understand that it makes code be treated as a class definition. They do not want
their code treated as a class definition and get surprised. The reason not
to pass locals specifically is that the following code raises a `NameError`:

```py
exec("""
def f():
    print("hi")

f()

def g():
    f()
g()
""", {}, {})
```

The reason not to leave out globals is as follows:

```py
def t():
    exec("""
def f():
    print("hi")

f()

def g():
    f()
g()
    """)
```
This commit is contained in:
Hood Chatham 2024-05-20 13:42:15 -04:00 committed by GitHub
parent 1195c164da
commit 7e1a130b8f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -608,9 +608,13 @@ are always available. They are listed here in alphabetical order.
will be used for both the global and the local variables. If *globals* and will be used for both the global and the local variables. If *globals* and
*locals* are given, they are used for the global and local variables, *locals* are given, they are used for the global and local variables,
respectively. If provided, *locals* can be any mapping object. Remember respectively. If provided, *locals* can be any mapping object. Remember
that at the module level, globals and locals are the same dictionary. If exec that at the module level, globals and locals are the same dictionary.
gets two separate objects as *globals* and *locals*, the code will be
executed as if it were embedded in a class definition. .. note::
Most users should just pass a *globals* argument and never *locals*.
If exec gets two separate objects as *globals* and *locals*, the code
will be executed as if it were embedded in a class definition.
If the *globals* dictionary does not contain a value for the key If the *globals* dictionary does not contain a value for the key
``__builtins__``, a reference to the dictionary of the built-in module ``__builtins__``, a reference to the dictionary of the built-in module