From 0f09e03034f7986eaf7eb20c2b712cc85768b4ab Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Mon, 20 May 2024 12:40:35 -0400 Subject: [PATCH 1/2] DOCS: Suggest always calling exec with a globals argument and no locals argument 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() """) ``` --- Doc/library/functions.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 0c7ef67774cd05..a2a0785162d12e 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -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 *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:: + + You probably should always pass a globals argument and never a locals + argument. 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 From 39a3bf780d9b123ba926d14c052866ec07a3913e Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Mon, 20 May 2024 10:19:39 -0700 Subject: [PATCH 2/2] Tweak the wording same overall meaning. --- Doc/library/functions.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index a2a0785162d12e..3986ace02b561a 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -612,9 +612,9 @@ are always available. They are listed here in alphabetical order. .. note:: - You probably should always pass a globals argument and never a locals - argument. If exec gets two separate objects as *globals* and *locals*, the - code will be executed as if it were embedded in a class definition. + 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