microPython的源码解析之 scope.c

MicroPython 是一种适用于微控制器和其他受限环境的 Python 编程语言的实现。它旨在提供与 Python 3 语言的紧密兼容，同时考虑到内存和计算资源的限制。MicroPython 库是这门语言的核心组成部分，提供了一系列的模块和函数，使得开发者能够在硬件上执行各种任务。
下面将通过系列文章,逐一解读microPython,以便让读者了解掌握microPython的整个核心逻辑.,以便读者可以透过这个Python的最小内核,掌握Python解析器的核心实现逻辑,学习世界上最优秀的源码设计之一.

---

microPython Python最小内核源码解析
NI-motion运动控制c语言示例代码解析
python编程示例系列 python编程示例系列二
python的Web神器Streamlit

---

这段代码是一个Python解释器的一部分，用于处理作用域和变量声明。它定义了几个函数来创建、释放、查找和修改作用域中的变量信息。这些函数使用了一些宏和断言来确保代码的正确性。代码中的注释已经翻译成中文，并且我添加了一些额外的注释来帮助理解代码的功能和结构。

#include <assert.h>

#include "py/scope.h"

// 如果启用了编译器，下面的代码将被编译。
#if MICROPY_ENABLE_COMPILER

// 这些低编号的qstrs应该适合在8位内。下面的断言确保它们确实可以放入uint8_t。
// 未转义的名称出现在QSTR生成脚本`py/makeqstrdata.py`的`unsorted_str_list`中，以确保它们被分配低编号。
static const uint8_t scope_simple_name_table[] = {
   
    [SCOPE_MODULE] = MP_QSTR__lt_module_gt_, // 模块作用域
    [SCOPE_LAMBDA] = MP_QSTR__lt_lambda_gt_, //  lambda表达式作用域
    [SCOPE_LIST_COMP] = MP_QSTR__lt_listcomp_gt_, // 列表推导式作用域
    [SCOPE_DICT_COMP] = MP_QSTR__lt_dictcomp_gt_, // 字典推导式作用域
    [SCOPE_SET_COMP] = MP_QSTR__lt_setcomp_gt_, // 集合推导式作用域
    [SCOPE_GEN_EXPR] = MP_QSTR__lt_genexpr_gt_, // 生成器表达式作用域
};

// 创建一个新的作用域。
scope_t *scope_new(scope_kind_t kind, mp_parse_node_t pn, mp_uint_t emit_options) {
   
    // 确保这些qstrs确实可以放入一个uint8_t。
    MP_STATIC_ASSERT(MP_QSTR__lt_module_gt_ <= UINT8_MAX); // 断言模块作用域的qstr可以放入uint8_t
    MP_STATIC_ASSERT(MP_QSTR__lt_lambda_gt_ <= UINT8_MAX); // 断言lambda表达式作用域的qstr可以放入uint8_t
    MP_STATIC_ASSERT(MP_QSTR__lt_listcomp_gt_ <= UINT8_MAX); // 断言列表推导式作用域的qstr可以放入uint8_t
    MP_STATIC_ASSERT(MP_QSTR__lt_dictcomp_gt_ <= UINT8_MAX); // 断言字典推导式作用域的qstr可以放入uint8_t
    MP_STATIC_ASSERT(MP_QSTR__lt_setcomp_gt_ <= UINT8_MAX); // 断言集合推导式作用域的qstr可以放入uint8_t
    MP_STATIC_ASSERT(MP_QSTR__lt_genexpr_gt_ <= UINT8_MAX); // 断言生成器表达式作用域的qstr可以放入uint8_t

    // 分配内存并初始化新的作用域。
    scope_t *scope = m_new0(scope_t, 1);
    scope->kind = kind; // 设置作用域类型
    scope->pn = pn; // 设置解析节点
    if (kind == SCOPE_FUNCTION || kind == SCOPE_CLASS) {
   
        assert(MP_PARSE_NODE_IS_STRUCT(pn)); // 断言解析节点是结构体类型
        scope->simple_name = MP_PARSE_NODE_LEAF_ARG(((mp_parse_node_struct_t *)pn)->nodes[0]); // 设置简单名称
    } else {
   
        scope->simple_name = scope_simple_name_table[kind]; // 从表格中获取简单名称
    }
    scope->raw_code = mp_emit_glue_new_raw_code(); // 创建新的原始代码
    scope->emit_options = emit_options; // 设置发射选项
    scope->id_info_alloc = MICROPY_ALLOC_SCOPE_ID_INIT; // 初始化id信息分配
    scope->id_info = m_new(id_info_t, scope->id_info_alloc); // 分配id信息数组

    return scope;
}

// 释放作用域占用的内存。
void scope_free(scope_t *scope) {
   
    m_del(id_info_t, scope->id_info, scope->id_info_alloc); // 释放id信息数组
    m_del(scope_t, scope, 1); // 释放作用域本身
}

// 在作用域中查找或添加id信息。
id_info_t *scope_find_or_add_id(scope_t *scope, qstr qst, id_info_kind_t kind) {
   
    id_info_t *id_info = scope_find(scope, qst); // 首先尝试查找id信息
    if (id_info != NULL) {
   
        return id_info; // 如果找到，则返回
    }

    // 确保有足够的内存来存储新的id信息。
    if (scope->id_info_len >= scope->id_info_alloc) {
   
        scope->id_info = m_renew(id_info_t, scope->id_info, scope->id_info_alloc, scope->id_info_alloc + MICROPY_ALLOC_SCOPE_ID_INC); // 重新分配更大的数组
        scope->id_info_alloc += MICROPY_ALLOC_SCOPE_ID_INC; // 增加分配的内存
    }

    // 将新的id信息添加到所有id的数组末尾；这似乎与CPython的实现相匹配。
    id_info = &scope->id_info[scope->id_info_len++]; // 获取新的id信息指针并增加长度

    id_info->kind = kind; // 设置id信息类型
    id_info->flags = 0; // 初始化标志
    id_info->local_num = 0; // 初始化局部编号
    id_info->qst = qst; // 设置qstr
    return id_info; // 返回新的id信息
}

// 在作用域中查找id信息。
id_info_t *scope_find(scope_t *scope, qstr qst) {
   
    for (mp_uint_t i = 0; i < scope->id_info_len; i++) {
    // 遍历所有的id信息
        if (scope->id_info[i].qst == qst) {
    // 如果找到匹配的qstr
            return &scope->id_info[i]; // 返回找到的id信息
        }
    }
    return NULL; // 如果没有找到，返回NULL
}

// 在全局作用域中查找id信息。
id_info_t *scope_find_global(scope_t *scope, qstr qst) {
   
    while (scope->parent != NULL) {
    // 遍历所有父作用域
        scope = scope->parent; // 移动到下一个父作用域
    }
    return scope_find(scope, qst); // 在最外层作用域中查找id信息
}

// 在父作用域中关闭覆盖的变量。
static void scope_close_over_in_parents(scope_t *scope, qstr qst) {
   
    assert(scope->parent != NULL); // 我们应该至少有一个父作用域
    for (scope_t *s = scope->parent;; s = s->parent) {
    // 遍历所有父作用域
        assert(s->parent != NULL); // 我们不应该到达外部作用域
        id_info_t *id = scope_find_or_add_id(s, qst, ID_INFO_KIND_UNDECIDED); // 在父作用域中查找或添加id信息
        if (id->kind == ID_INFO_KIND_UNDECIDED) {
    // 如果变量在这个作用域中未被声明
            // 变量尚未被声明，所以将其声明为自由变量，并继续在父作用域中搜索
            id->kind = ID_INFO_KIND_FREE;
        } else {
   
            // 变量已在这个作用域中被声明，所以结束搜索
            if (id->kind == ID_INFO_KIND_LOCAL) {
   
                // 变量是这个作用域的局部变量，将其转换为闭包变量
                id->kind = ID_INFO_KIND_CELL;
            } else {
   
                // ID_INFO_KIND_FREE: 变量已经在父作用域中被闭包
                // ID_INFO_KIND_CELL: 变量已经在当前作用域中被闭包
                assert(id->kind == ID_INFO_KIND_FREE || id->kind == ID_INFO_KIND_CELL);
            }
            return; // 返回
        }
    }
}

// 检查并关闭覆盖的变量。
void scope_check_to_close_over(scope_t