[3.12] DOCS: Suggest always calling exec with a globals argument and no locals argume...

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()
    """)
```
(cherry picked from commit 7e1a130b8ff1ed8b3a5f00fe0f06d3916b852216)

Co-authored-by: Hood Chatham <roberthoodchatham@gmail.com>

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index b314cb2a703993443ee35b3af7bcced5957ebf3d..d8f65b06763cadcd8ba9cb961544c2f7cac8fd87 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -604,9 +604,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
    *locals* are given, they are used for the global and local variables,
    respectively.  If provided, *locals* can be any mapping object.  Remember
-   that at the module level, globals and locals are the same dictionary. If exec
-   gets two separate objects as *globals* and *locals*, the code will be
-   executed as if it were embedded in a class definition.
+   that at the module level, globals and locals are the same dictionary.
+
+   .. 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
    ``__builtins__``, a reference to the dictionary of the built-in module