PEP 667: Clarify specification ambiguities and the expected impact

peps/pep-0667.rst

@@ -371,6 +371,66 @@ C API
 As with all functions that return a borrowed reference, care must be taken to
 ensure that the reference is not used beyond the lifetime of the object.
 
+Impact on ``exec()``
+====================
+
+Even though this PEP does not modify ``exec()`` directly, the semantic change
+to ``locals()`` impacts the behavior of ``exec()``.
+
+``exec(object)`` has been equivalent to ``exec(object, globals(), locals())``
+for a long time, but it's not officially documented. We plan to keep this
+relation, which means existing code using ``exec()`` will see some different
+behaviors.
+
+The core difference is that the current implementation returns the same dict
+when ``locals()`` is called multiple times in function scope, so the following
+code magically works::
+
+    def f():
+        exec('a = 0')  # equivalent to exec('a = 0', globals(), locals())
+        exec('print(a)')  # equivalent to exec('print(a)', globals(), locals())
+        print(locals())  # {'a': 0}
+        # However, print(a) will not work here
+    f()
+
+``locals()`` is implicitly used as a scope shared between multiple ``exec()``.
+
+This behavior gets harder to predict when the code in ``exec()`` tries to write
+to an existing local variable::
+
+    def f():
+        a = None
+        exec('a = 0')  # equivalent to exec('a = 0', globals(), locals())
+        exec('print(a)')  # equivalent to exec('print(a)', globals(), locals())
+        print(locals())  # {'a': None}
+    f()
+
+``print(a)`` will print ``None`` because the implicit ``locals()`` call in
+``exec()`` refreshes the cached dict with the actual values on the frame.
+
+With the semantic changes to ``locals()``, it's easier to explain the behavior
+of ``exec()`` - it will never affect local function scopes. Any assignment
+to the local variables will be discarded when ``exec()`` returns.
+
+However, you can still achieve the wanted behavior with explicit scopes::
+
+    def f():
+        scope = {}
+        exec('a = 0', locals=scope)
+        exec('print(a)', locals=scope)
+    f()
+
+You can even change the variables in the local scope by explicitly using
+``frame.f_locals`` which is not possible before::
+
+    def f():
+        a = None
+        exec('a = 0', locals=sys._getframe().f_locals)
+        print(a)  # 0
+    f()
+
+The behavior of ``exec()`` for module and class scopes is not changed.
+
 Impact on PEP 709 inlined comprehensions
 ========================================