局部变量是怎么实现静态查找的，它和 local 名字空间又有什么联系呢？

x = 123

def foo1():
    global x
    a = 1
    b = 2

# co_nlocals 会返回局部变量的个数
# a 和 b 是局部变量，x 是全局变量，因此是 2
print(foo1.__code__.co_nlocals)  # 2


def foo2(a, b):
    pass

print(foo2.__code__.co_nlocals)  # 2


def foo3(a, b):
    a = 1
    b = 2
    c = 3

print(foo3.__code__.co_nlocals)  # 3

// Objects/call.c
/*
 * Python 函数也是一个对象，当调用 Python 函数时
 * 底层会将 Python 函数对象作为参数，调用 _PyFunction_Vectorcall
 * 关于函数，我们后续会剖析
 */
PyObject *
_PyFunction_Vectorcall(PyObject *func, PyObject* const* stack,
                       size_t nargsf, PyObject *kwnames)
{
    // ...
    
    // 参数 func 指向函数对象，它内部的 func_code 指向 PyCodeObject 对象
    // 如果 co_flags & CO_OPTIMIZED 为真，表示 PyCodeObject 是被优化过的
    // 那么对应的函数在调用时，会静态查找本地局部变量
    if (((PyCodeObject *)f->func_code)->co_flags & CO_OPTIMIZED) {
        // 在这种情况下，会给 _PyEval_Vector 的第三个参数传递 NULL
        return _PyEval_Vector(tstate, f, NULL, stack, nargs, kwnames);
    }
    // ...
}


// Python/ceval.c
/*
 * 创建栈帧，调用 _PyEval_EvalFrame，最终执行帧评估函数
 * 注意该函数的第三个参数，显然它表示局部名字空间
 * 而 _PyFunction_Vectorcall 在调用时传递的是 NULL
 */
PyObject *
_PyEval_Vector(PyThreadState *tstate, PyFunctionObject *func,
               PyObject *locals,
               PyObject* const* args, size_t argcount,
               PyObject *kwnames)
{
    // ...
    
    // 执行帧评估函数之前，要先创建栈帧
    // 这个过程由 _PyEvalFramePushAndInit 负责
    _PyInterpreterFrame *frame = _PyEvalFramePushAndInit(
        tstate, func, locals, args, argcount, kwnames);
    // ...
    return _PyEval_EvalFrame(tstate, frame, 0);
}

/*
 * 在当前栈帧之上创建新的栈帧，并推入虚拟机为其准备的 C Stack 中
 */
static _PyInterpreterFrame *
_PyEvalFramePushAndInit(PyThreadState *tstate, PyFunctionObject *func,
                        PyObject *locals, PyObject* const* args,
                        size_t argcount, PyObject *kwnames)
{
    // ...

    // 栈帧创建之后，调用 _PyFrame_Initialize，进行初始化
    _PyFrame_Initialize(frame, func, locals, code, 0);
    // ...
}

// Include/internal/pycore_frame.h
/*
 * 对 frame 进行初始化
 */
staticinlinevoid
_PyFrame_Initialize(
    _PyInterpreterFrame *frame, PyFunctionObject *func,
    PyObject *locals, PyCodeObject *code, int null_locals_from)
{
    frame->f_funcobj = (PyObject *)func;
    frame->f_code = (PyCodeObject *)Py_NewRef(code);
    frame->f_builtins = func->func_builtins;
    frame->f_globals = func->func_globals;
    // 将 f_locals 字段初始化为参数 locals
    // 而参数 locals 是从 _PyFunction_Vectorcall 一层层传过来的
    // 由于 _PyFunction_Vectorcall 传的是 NULL
    // 所以栈帧的 f_locals 字段最终会被初始化为 NULL
    frame->f_locals = locals;
    // ...
}

import inspect

# 模块的栈帧
frame = inspect.currentframe()
# 对于模块而言，局部名字空间和全局名字空间是同一个字典
print(frame.f_locals is frame.f_globals)  # True
# 当然啦，局部名字空间和全局名字空间也可以通过内置函数获取
print(
    frame.f_locals is locals() is frame.f_globals is globals()
)  # True


# 但对于函数而言就不一样了
def foo():
    name = "古明地觉"
    return inspect.currentframe()

frame = foo()
# global 名字空间全局唯一
# 无论是获取栈帧的 f_globals，还是调用 globals()
# 得到的都是同一份字典
print(frame.f_globals is globals())  # True
# 但每个函数都有自己独立的局部名字空间
print(frame.f_locals)  # {'name': '古明地觉'}

# 咦，不是说局部名字空间被初始化为 NULL 吗？
# 那么在 Python 里面获取的话，结果应该是个 None 才对啊
# 关于这一点，我们稍后会解释

def foo(a, b):
    c = a + b
    print(c)

TARGET(LOAD_FAST) {
    PyObject *value;
    #line 192 "Python/bytecodes.c"
    // 通过宏 GETLOCAL 获取局部变量的值
    value = GETLOCAL(oparg);
    assert(value != NULL);
    Py_INCREF(value);
    #line 90 "Python/generated_cases.c.h"
    // 将值压入运行时栈，等价于 PUSH(value)
    STACK_GROW(1);
    stack_pointer[-1] = value;
    DISPATCH();
}

TARGET(STORE_FAST) {
    // 获取栈顶元素
    PyObject *value = stack_pointer[-1];
    #line 209 "Python/bytecodes.c"
    // 通过宏 SETLOCAL 创建局部变量
    SETLOCAL(oparg, value);
    #line 124 "Python/generated_cases.c.h"
    // 将 stack_pointer 向栈底移动一个位置，即弹出栈顶元素
    // 如果和第一行组合起来的话，等价于 TOP()
    STACK_SHRINK(1);
    DISPATCH();
}

// Python/ceval_macros.h

#define GETLOCAL(i)     (frame->localsplus[i])

#define SETLOCAL(i, value)      do { PyObject *tmp = GETLOCAL(i); \
                                     GETLOCAL(i) = value; \
                                     Py_XDECREF(tmp); } while (0)
/* 这里额外再补充一个关于 C 语言的知识点
 * 我们看到宏 SETLOCAL 展开之后的结果是 do {...} while (0) 
 * do while 循环会先执行 do 里面的循环体，然后再判断条件是否满足
 * 因此从效果上来说，执行 do {...} while (0) 和直接执行 ... 是等价的
 * 那么问题来了，既然效果等价，为啥还要再套一层 do while 呢
 * 其实原因很简单，如果宏在展开之后会生成多条语句，那么这些语句要成为一个整体
 * 另外由于 C 程序的语句要以分号结尾，所以在调用宏时，我们也会习惯性地在结尾加上分号
 * 因此我们希望有这样一种结构，能同时满足以下要求：
 *   1）可以将多条语句包裹起来，作为一个整体；
 *   2）程序的语义不能发生改变；
 *   3）在语法上，要以分号结尾；
 * 显然 do while 完美满足以上三个要求，只需将 while 里的条件设置为 0 即可
 * 并且当编译器看到 while (0) 时，也会进行优化，去掉不必要的循环控制结构
 * 因此以后看到 do {...} while (0) 时，不要觉得奇怪，这是宏的一个常用技巧
 */

def foo(a, b):
    c = a + b
    print(c)

print(
    foo.__code__.co_varnames
)  # ('a', 'b', 'c')

x = 1

def foo():
    globals()["x"] = 2
    
foo()
print(x)  # 2

def foo():
    x = 1
    locals()["x"] = 2
    print(x)


foo()  # 1

def foo():
    name = "satori"
    print(locals())
    age = 17
    print(locals())
    gender = "female"
    print(locals())

foo()
"""
{'name': 'satori'}
{'name': 'satori', 'age': 17}
{'name': 'satori', 'age': 17, 'gender': 'female'}
"""

def foo():
    name = "satori"
    age = 17
    gender = "female"
    print(locals())

# 符号表：保存了函数中创建的局部变量的名字
print(foo.__code__.co_varnames)
"""
('name', 'age', 'gender')
"""
# 调用函数时会创建栈帧，局部变量的值都保存在 f_localsplus 里面
# 并且符号表中变量名的顺序和 f_localsplus 中变量值的顺序是一致的
f_localsplus = ["satori", 17, "female"]
# 这里就用一个列表来模拟了

def foo():
    name = "satori"
    # 会从 f_localsplus 中静态查找
    print(name)
    # 先基于已有的变量和值创建一个字典
    # 然后通过字典实现变量的动态查找
    print(locals()["name"])

foo()
"""
satori
satori
"""

def foo():
    name = "satori"
    locals()["age"] = 17
    try:
        print(age)
    except NameError as e:
        print(e)

foo()
"""
name 'age' is not defined
"""

def foo():
    name = "satori"
    # 执行 locals() 的时候，内部只有一个键值对
    d = locals()
    print(d)  # {'name': 'satori'}
    # 再次获取，此时有两个键值对
    print(locals())  # {'name': 'satori', 'd': {...}}
    
    # 但两者的 id 相同，因为一个函数只有一个局部名字空间
    # 不管调用多少次 locals()，拿到的都是同一个字典
    print(id(d) == id(locals()))  # True

foo()

def foo():
    # 创建一个字典，由于当前还没有定义局部变量，因此是空字典
    print(locals())
    """
    {}
    """
    # 往局部名字空间添加一个键值对
    locals()["a"] = "b"
    print(locals())
    """
    {'a': 'b'}
    """
    # 定义一个局部变量
    name = "satori"
    # 由于局部名字空间已存在，因此不会再次创建
    # 直接将局部变量的名字作为 key、值作为 value，拷贝到字典中
    print(locals())
    """
    {'a': 'b', 'name': 'satori'}
    """

foo()

// Python/bltinmodule.c
static PyObject *
builtin_locals_impl(PyObject *module)
{
    // Python 内置函数的源码实现位于 bltinmodule.c 中
    // 这里又调用了 _PyEval_GetFrameLocals
    return _PyEval_GetFrameLocals();
}

// Python/ceval.c
PyObject *
_PyEval_GetFrameLocals(void)
{
    PyThreadState *tstate = _PyThreadState_GET();
     _PyInterpreterFrame *current_frame = _PyThreadState_GetFrame(tstate);
    if (current_frame == NULL) {
        _PyErr_SetString(tstate, PyExc_SystemError, "frame does not exist");
        return NULL;
    }
    // 调用了 _PyFrame_GetLocals
    return _PyFrame_GetLocals(current_frame, 1);
}

// Object/frameobject.c
PyObject *
_PyFrame_GetLocals(_PyInterpreterFrame *frame, int include_hidden)
{
    // 获取局部名字空间
    PyObject *locals = frame->f_locals;
    // 如果为 NULL，那么创建一个新字典，作为名字空间
    // 所以局部名字空间只会创建一次，后续不会再创建
    if (locals == NULL) {
        locals = frame->f_locals = PyDict_New();
        if (locals == NULL) {
            return NULL;
        }
    }
    PyObject *hidden = NULL;

    // 在 Include/internal/pycore_code.h 里面有 4 个宏
    /* #define CO_FAST_HIDDEN  0x10
     * #define CO_FAST_LOCAL   0x20
     * #define CO_FAST_CELL    0x40
     * #define CO_FAST_FREE    0x80
     */
    // 它们分别对应隐藏变量、局部变量、cell 变量、free 变量
    // 所谓隐藏变量，指的就是解析式里的临时变量，比如列表解析式
    // 解析式具有独立的作用域，里面的临时变量不会污染外部的作用域
    // 所以一般我们也不会关注这些隐藏变量，locals() 也不会返回它
    // 但如果你真的关注，那么可以将 include_hidden 指定为真
    // 那么调用 locals() 时，这些隐藏变量也会一块儿返回
    if (include_hidden) {
        // 单独创建一个字典，负责保存隐藏变量
        hidden = PyDict_New();
        if (hidden == NULL) {
            return NULL;
        }
    }
    // 初始化 free 变量，这个和闭包有关
    // 关于闭包，等剖析完函数之后会说，这里暂时先不关注
    frame_init_get_vars(frame);

    PyCodeObject *co = frame->f_code;
    // co_nlocalsplus 等于局部变量、cell 变量、free 变量的个数之和
    // 这些变量都要拷贝到 local 名字空间中
    for (int i = 0; i < co->co_nlocalsplus; i++) {
        PyObject *value;
        // 获取 f_localsplus[i]，在函数内部会对 value 进行修改
        if (!frame_get_var(frame, co, i, &value)) {
            continue;
        }
        // f_localsplus[i] 对应局部名字空间的 value
        // 那么 co_localsplusnames[i] 显然对应局部名字空间的 key
        // 估计有人已经忘记 co_localsplusnames 字段的含义了，我们再解释一下
        /* co_localsplusnames：包含所有局部变量、cell 变量、free 变量的名称
         * co_nlocalsplus：co_localsplusnames 的长度，或者说这些变量的个数之和

         * co_varnames：包含所有局部变量的名称，co_nlocals：局部变量的个数
         * co_cellvars：包含所有 cell 变量的名称，co_ncellvars：cell 变量的个数
         * co_freevars：包含所有 free 变量的名称，co_nfreevars：free 变量的个数
         
         * 因此不难得出它们之间的关系：
         * co_localsplusnames = co_varnames + co_cellvars + co_freevars
         * co_nlocalsplus = co_nlocals + co_ncellvars + co_nfreevars
         */
        // 所以 co_localsplusnames 也是符号表，并且是 co_varnames 的超集
        PyObject *name = PyTuple_GET_ITEM(co->co_localsplusnames, i);
        // 到此局部名字空间的 key 和 value 便有了，但还要做一个判断
        _PyLocals_Kind kind = _PyLocals_GetKind(co->co_localspluskinds, i);
        // 如果变量的类型是隐藏变量，那么添加到 hidden 中
        // 所以 co_localsplusnames 其实还包含了隐藏变量的名称
        // 但我们基本不会遇到这种情况，因此关于隐藏变量直接忽略掉即可
        if (kind & CO_FAST_HIDDEN) {
            if (include_hidden && value != NULL) {
                if (PyObject_SetItem(hidden, name, value) != 0) {
                    goto error;
                }
            }
            continue;
        }
        // 如果不是隐藏变量，那么拷贝到 locals 中，但这里有一个判断很重要
        // 当 value 为 NULL 时，如果 key 已存在，那么会将它删掉
        // 关于这里的玄机，稍后会解释
        if (value == NULL) {
            if (PyObject_DelItem(locals, name) != 0) {
                if (PyErr_ExceptionMatches(PyExc_KeyError)) {
                    PyErr_Clear();
                }
                else {
                    goto error;
                }
            }
        }
        // 到这里说明 value 指向了一块合法的内存
        // 也就是变量名和变量值已经完成了绑定，那么将它们添加到 locals 中
        else {
            if (PyObject_SetItem(locals, name, value) != 0) {
                goto error;
            }
        }
        // 继续遍历下一个符号
    }
    // 隐藏变量保存在 hidden 中，它不会污染 f_locals
    if (include_hidden && PyDict_Size(hidden)) {
        // 创建一个新字典
        PyObject *innerlocals = PyDict_New();
        if (innerlocals == NULL) {
            goto error;
        }
        // 合并 locals
        if (PyDict_Merge(innerlocals, locals, 1) != 0) {
            Py_DECREF(innerlocals);
            goto error;
        }
        // 合并 hidden
        if (PyDict_Merge(innerlocals, hidden, 1) != 0) {
            Py_DECREF(innerlocals);
            goto error;
        }
        // 重新赋值给 locals，所以返回的结果会包含 hidden 里的键值对
        // 但 f_locals 里面是没有隐藏变量的
        locals = innerlocals;
    }
    else {
        Py_INCREF(locals);
    }
    Py_CLEAR(hidden);
    // 返回 locals
    return locals;

  error:
    Py_XDECREF(hidden);
    return NULL;
}

def foo():
    print(locals())  # {}
    exec("x = 1")
    print(locals())  # {'x': 1}
    try:
        print(x)
    except NameError as e:
        print(e)  # name 'x' is not defined
        
foo()

exec("x = 1")
print(x)  # 1

def foo():
    # 此时 exec 影响的是全局名字空间
    exec("x = 123", globals())
    # 这里不会报错, 但此时的 x 不是局部变量, 而是全局变量
    print(x)

foo()
print(x)
"""
123
123
"""

def foo():
    exec("x = 1")
    print(locals()["x"])

foo()
"""
1
"""

def bar():
    exec("x = 1")
    print(locals()["x"])
    x = 123

bar()
"""
Traceback (most recent call last):
  File .....
    bar()
  File .....
    print(locals()["x"])
KeyError: 'x'
"""

def foo():
    # 创建局部名字空间，并写入键值对 "x": 1
    # 此时名字空间为 {"x": 1}
    exec("x = 1")
    # 获取名字空间，会进行更新
    # 但当前不存在局部变量，所以名字空间仍是 {"x": 1}
    print(locals())

def bar():
    # 创建局部名字空间，并写入键值对 "x": 1
    # 此时名字空间为 {"x": 1}
    exec("x = 1")
    # 获取名字空间，会进行更新
    # 由于里面存在局部变量 x，但尚未赋值
    # 于是将字典中 key 为 "x" 的键值对给删掉
    # 所以名字空间变成了 {}
    print(locals())
    x = 123


foo()  # {'x': 1}
bar()  # {}

def foo():
    exec("x = 2")
    print(locals())

foo()  # {'x': 2}


def bar():
    x = 1
    exec("x = 2")
    print(locals())

bar()  # {'x': 1}

# 例 0
def foo():
    exec('y = 1 + 1')
    z = locals()['y']
    print(z)

foo()
# 输出：2


# 例 1
def foo():
    exec('y = 1 + 1')
    y = locals()['y']
    print(y)

foo()
# 报错：KeyError: 'y'

# 例 2
def foo():
    y = 1 + 1
    y = locals()['y']
    print(y)

foo()
# 2

# 例3
def foo():
    exec('y = 1 + 1')
    boc = locals()
    y = boc['y']
    print(y)

foo()
# KeyError: 'y'

# 例4
def foo():
    boc = locals()
    exec('y = 1 + 1')
    y = boc['y']
    print(y)

foo()
# 2

# 例5
def foo():
    boc = locals()
    exec('y = 1 + 1')
    print(locals())
    y = boc['y']
    print(y)

foo()

# {'boc': {...}} 
# KeyError: 'y'