How do the globals and locals mappings passed to exec() decide what the code can see?

## The three call shapes `exec(source, globals=None, locals=None)` - and `eval()` with the same signature - lets you choose the namespace the code runs in. Which of the two arguments you supply changes the semantics, not just the contents. **Neither argument.** The code runs in the caller's scope. At module level that means the module's globals, so `exec("total = 5")` really creates a module attribute. Inside a function it means the caller's globals plus a *snapshot* of the caller's locals, which is why an assignment there never reaches the function's own variables. **Globals only.** The locals argument defaults to the same object, so the string executes in one flat namespace exactly like top-level module code. Everything it binds is visible in your dict afterwards: ```python ns = {"start": 10} exec("doubled = start * 2", ns) ns["doubled"] # 20 ``` This is the shape most code wants. One dict in, one dict out, no surprises about where a name went. **Both arguments.** Now the two namespaces are distinct. Reads resolve locals first, then globals, then builtins. Writes go to the locals mapping only - your globals dict is not modified: ```python g = {"start": 10} l = {} exec("doubled = start * 2", g, l) l["doubled"] # 20 "doubled" in g # False ``` ## Class-body semantics, and the trap that follows The language reference describes the two-mapping form as executing "as if the code were embedded in a class definition", and that is not a loose analogy - it is the same scoping rule. A class body has a local namespace that is a real dict, and crucially **that namespace does not become an enclosing scope for functions defined inside it**. The same holds here: ```python g, l = {}, {"n": 5} exec("def h(): return n\nres = h()", g, l) # NameError: name 'n' is not defined ``` `h` compiles a global lookup for `n`, because there was no enclosing *function* scope to close over. At call time it consults `g`, where `n` does not exist. Comprehensions hit the same wall, since a comprehension body is compiled as its own scope: `exec("out = [n for _ in range(2)]", {}, {"n": 3})` raises `NameError` too. The fix is simply to pass one dict rather than two, which collapses the distinction and makes every name a global from the executed code's point of view. ## What each argument must be `globals` must be an actual `dict`. Handing `exec()` some other mapping raises `TypeError: exec() globals must be a dict`. `locals` is far more permissive: any mapping will do, so a `dict` subclass or a custom class implementing `__getitem__` can compute or log names on demand - a useful hook when the executed code is a small operator-authored formula and you want to resolve field names against a live record. Also worth knowing: if the globals dict you pass has no builtins entry, Python inserts a reference to the `builtins` module into it before running the code. That is a convenience, not a restriction, and it is why an empty globals dict is **not** a sandbox - the executed code still reaches every builtin. ## The 3.13 keyword-argument change Both arguments used to be positional-only. Since **Python 3.13** you can write `eval(src, globals=g, locals=l)`, which mostly helps readability at call sites that pass only the second one - previously you had to pass `None` for globals to reach it. ## Choosing a shape in practice For evaluating a small expression against a record, the sensible default is a single dict per evaluation: build it from the fields the expression is allowed to reference, pass it as globals, and let any bindings land there. Reuse a fresh dict per evaluation rather than a shared one, so no state carries between runs and nothing is shared across threads. Reach for the two-mapping form only when you deliberately want a stable read-only backdrop plus a scratch namespace for results - and remember that a function defined in the string will not see the scratch half.