Allow sys.settrace() to inspect locals() variables including (optional) name resolution.

ports/unix/variants/standard/mpconfigvariant.h

@@ -27,7 +27,9 @@
 // Set base feature level.
 #define MICROPY_CONFIG_ROM_LEVEL (MICROPY_CONFIG_ROM_LEVEL_EXTRA_FEATURES)
 
-#define MICROPY_PY_SYS_SETTRACE (1)
+// #define MICROPY_PY_SYS_SETTRACE (1)
+// #define MICROPY_PY_SYS_SETTRACE_SAVE_NAMES (1) // Save local variable names for debugging
+
 
 // Enable extra Unix features.
 #include "../mpconfigvariant_common.h"

py/compile.c

@@ -38,6 +38,9 @@
 #include "py/nativeglue.h"
 #include "py/persistentcode.h"
 #include "py/smallint.h"
+#if MICROPY_PY_SYS_SETTRACE_SAVE_NAMES
+#include "py/localnames.h"
+#endif
 
 #if MICROPY_ENABLE_COMPILER
 
@@ -3435,6 +3438,21 @@ static void scope_compute_things(scope_t *scope) {
         }
     }
 
+    #if MICROPY_PY_SYS_SETTRACE_SAVE_NAMES
+    // Save the local variable names in the raw_code for debugging
+    if (SCOPE_IS_FUNC_LIKE(scope->kind) && scope->num_locals > 0) {
+        // Initialize local_names structure with variable names
+        for (int i = 0; i < scope->id_info_len; i++) {
+            id_info_t *id = &scope->id_info[i];
+            if ((id->kind == ID_INFO_KIND_LOCAL || id->kind == ID_INFO_KIND_CELL) &&
+                id->local_num < scope->num_locals &&
+                id->local_num < MICROPY_PY_SYS_SETTRACE_NAMES_MAX) {
+                mp_local_names_add(&scope->raw_code->local_names, id->local_num, id->qst);
+            }
+        }
+    }
+    #endif
+
     // compute the index of free vars
     // make sure they are in the order of the parent scope
     if (scope->parent != NULL) {

py/emitglue.c

@@ -57,6 +57,9 @@ mp_raw_code_t *mp_emit_glue_new_raw_code(void) {
     #if MICROPY_PY_SYS_SETTRACE
     rc->line_of_definition = 0;
     #endif
+    #if MICROPY_PY_SYS_SETTRACE_SAVE_NAMES
+    mp_local_names_init(&rc->local_names);
+    #endif
     return rc;
 }
 

py/emitglue.h

@@ -28,6 +28,9 @@
 
 #include "py/obj.h"
 #include "py/bc.h"
+#if MICROPY_PY_SYS_SETTRACE_SAVE_NAMES
+#include "py/localnames.h"
+#endif
 
 // These variables and functions glue the code emitters to the runtime.
 
@@ -96,6 +99,9 @@ typedef struct _mp_raw_code_t {
     uint32_t asm_n_pos_args : 8;
     uint32_t asm_type_sig : 24; // compressed as 2-bit types; ret is MSB, then arg0, arg1, etc
     #endif
+    #if MICROPY_PY_SYS_SETTRACE_SAVE_NAMES
+    mp_local_names_t local_names;       // Maps local variable indices to names
+    #endif
 } mp_raw_code_t;
 
 // Version of mp_raw_code_t but without the asm_n_pos_args/asm_type_sig entries, which are

py/localnames.c

@@ -0,0 +1,112 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2025 Jos Verlinde
+ *
+ * Permission is hereby granted, free
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include "py/runtime.h"
+#include "py/localnames.h"
+
+#if MICROPY_PY_SYS_SETTRACE_SAVE_NAMES
+
+// Initialize the local names structure
+void mp_local_names_init(mp_local_names_t *local_names) {
+    if (local_names == NULL) {
+        return;
+    }
+
+    local_names->num_locals = 0;
+    local_names->order_count = 0;
+
+    // Initialize all entries with null qstrs and invalid indices
+    for (uint16_t i = 0; i < MICROPY_PY_SYS_SETTRACE_NAMES_MAX; i++) {
+        local_names->local_names[i] = MP_QSTRnull;
+        local_names->local_nums[i] = UINT16_MAX; // Invalid index marker
+    }
+}
+
+// Get the name of a local variable by its index
+qstr mp_local_names_get_name(const mp_local_names_t *local_names, uint16_t local_num) {
+    if (local_names == NULL || local_num >= MICROPY_PY_SYS_SETTRACE_NAMES_MAX) {
+        return MP_QSTRnull;
+    }
+
+    // Direct array access
+    return local_names->local_names[local_num];
+}
+
+// Look up the original local_num by order index (source code order)
+uint16_t mp_local_names_get_local_num(const mp_local_names_t *local_names, uint16_t order_idx) {
+    if (local_names == NULL || order_idx >= local_names->order_count) {
+        return UINT16_MAX; // Invalid index
+    }
+
+    return local_names->local_nums[order_idx];
+}
+
+// Add or update a name mapping for a local variable
+void mp_local_names_add(mp_local_names_t *local_names, uint16_t local_num, qstr qstr_name) {
+    if (local_names == NULL || local_num >= MICROPY_PY_SYS_SETTRACE_NAMES_MAX) {
+        return;
+    }
+
+    // Store name directly using local_num as index
+    local_names->local_names[local_num] = qstr_name;
+
+    // Update number of locals if needed
+    if (local_num >= local_names->num_locals) {
+        local_names->num_locals = local_num + 1;
+    }
+
+    // Also store in order of definition for correct runtime mapping
+    if (local_names->order_count < MICROPY_PY_SYS_SETTRACE_NAMES_MAX) {
+        uint16_t idx = local_names->order_count;
+        local_names->local_nums[idx] = local_num;
+        local_names->order_count++;
+    }
+
+    // Refine runtime slot mapping logic
+    // Test the hypothesis that variables are assigned from highest slots down
+    uint16_t runtime_slot = local_num; // Default to direct mapping
+
+    if (local_names->order_count > 0) {
+        // Find position in order array
+        for (uint16_t i = 0; i < local_names->order_count; ++i) {
+            if (local_names->local_nums[i] == local_num) {
+                runtime_slot = i;
+                break;
+            }
+        }
+    }
+    local_names->runtime_slots[local_num] = runtime_slot;
+}
+
+// Get the runtime slot for a local variable by its index
+uint16_t mp_local_names_get_runtime_slot(const mp_local_names_t *local_names, uint16_t local_num) {
+    if (local_names == NULL || local_num >= MICROPY_PY_SYS_SETTRACE_NAMES_MAX) {
+        return UINT16_MAX; // Invalid slot
+    }
+    return local_names->runtime_slots[local_num];
+}
+
+#endif // MICROPY_PY_SYS_SETTRACE_SAVE_NAMES

py/localnames.h

@@ -0,0 +1,63 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2025 Contributors to the MicroPython project
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#ifndef MICROPY_INCLUDED_PY_LOCALNAMES_H
+#define MICROPY_INCLUDED_PY_LOCALNAMES_H
+
+#include "py/obj.h"
+#include "py/qstr.h"
+
+#if MICROPY_PY_SYS_SETTRACE_SAVE_NAMES
+
+#define MICROPY_PY_SYS_SETTRACE_NAMES_MAX 32  // Maximum number of local variables to store names for
+
+// Structure to hold variable name mappings for a function scope
+typedef struct _mp_local_names_t {
+    uint16_t num_locals;                 // Total number of local variables with names
+    qstr local_names[MICROPY_PY_SYS_SETTRACE_NAMES_MAX];  // Array of variable names, indexed by local_num
+    uint16_t local_nums[MICROPY_PY_SYS_SETTRACE_NAMES_MAX]; // Reverse mapping: name index -> local_num (for correct state array mapping)
+    uint16_t order_count;                 // Number of variables stored in order they were defined
+    uint16_t runtime_slots[MICROPY_PY_SYS_SETTRACE_NAMES_MAX]; // Mapping of local_num to runtime slots
+} mp_local_names_t;
+
+// Initialize the local names structure
+void mp_local_names_init(mp_local_names_t *local_names);
+
+// Function to look up a variable name by its index
+qstr mp_local_names_get_name(const mp_local_names_t *local_names, uint16_t local_num);
+
+// Function to look up the original local_num by order index (source code order)
+uint16_t mp_local_names_get_local_num(const mp_local_names_t *local_names, uint16_t order_idx);
+
+// Function to add or update a name mapping for a local variable
+void mp_local_names_add(mp_local_names_t *local_names, uint16_t local_num, qstr qstr_name);
+
+// Function to get the runtime slot of a local variable by its index
+uint16_t mp_local_names_get_runtime_slot(const mp_local_names_t *local_names, uint16_t local_num);
+
+#endif // MICROPY_PY_SYS_SETTRACE_SAVE_NAMES
+
+#endif // MICROPY_INCLUDED_PY_LOCALNAMES_H

py/modsys.c

@@ -239,7 +239,7 @@ static mp_obj_t mp_sys_settrace(mp_obj_t obj) {
 }
 MP_DEFINE_CONST_FUN_OBJ_1(mp_sys_settrace_obj, mp_sys_settrace);
 
-static mp_obj_t mp_sys_gettrace() {
+static mp_obj_t mp_sys_gettrace(void) {
     return mp_prof_gettrace();
 }
 MP_DEFINE_CONST_FUN_OBJ_0(mp_sys_gettrace_obj, mp_sys_gettrace);

py/mpconfig.h

@@ -238,6 +238,11 @@
 #define MICROPY_ALLOC_PARSE_RESULT_INC (16)
 #endif
 
+// If not explicitly enabled, disable local variable name saving
+#ifndef MICROPY_PY_SYS_SETTRACE_SAVE_NAMES
+#define MICROPY_PY_SYS_SETTRACE_SAVE_NAMES (0)
+#endif
+
 // Strings this length or less will be interned by the parser
 #ifndef MICROPY_ALLOC_PARSE_INTERN_STRING_LEN
 #define MICROPY_ALLOC_PARSE_INTERN_STRING_LEN (10)

py/objfun.c

@@ -36,6 +36,9 @@
 #include "py/bc.h"
 #include "py/stackctrl.h"
 #include "py/profile.h"
+#if MICROPY_PY_SYS_SETTRACE_SAVE_NAMES
+#include "py/localnames.h"
+#endif
 
 #if MICROPY_DEBUG_VERBOSE // print debugging info
 #define DEBUG_PRINT (1)