py: Add metaclass __prepare__ method support (PEP 3115).

Implements the __prepare__ metaclass method which allows metaclasses to
customize the namespace dictionary before class body execution. This is
required for enum.auto() support and other advanced metaclass patterns.

Changes:
- py/mpconfig.h: Add MICROPY_PY_METACLASS_PREPARE configuration flag
- py/modbuiltins.c: Reorder __build_class__ to call __prepare__ before
  class body execution
- tests/basics/class_metaclass_prepare.py: Add comprehensive tests

Size impact: ~152 bytes when enabled (measured on Unix port)

Follows the implementation approach from PR micropython#18362.

Signed-off-by: Andrew Leech <[email protected]>

Author: pi-anl

py/modbuiltins.c

@@ -49,39 +49,61 @@ extern struct _mp_dummy_t mp_sys_stdout_obj; // type is irrelevant, just need po
 static mp_obj_t mp_builtin___build_class__(size_t n_args, const mp_obj_t *args, mp_map_t *kwargs) {
     assert(2 <= n_args);
 
-    // set the new classes __locals__ object
-    mp_obj_dict_t *old_locals = mp_locals_get();
-    mp_obj_t class_locals = mp_obj_new_dict(0);
-    mp_locals_set(MP_OBJ_TO_PTR(class_locals));
-
-    // call the class code
-    mp_obj_t cell = mp_call_function_0(args[0]);
-
-    // restore old __locals__ object
-    mp_locals_set(old_locals);
-
-    // get the class type (meta object) from the base objects
+    // STEP 1: Determine metaclass FIRST (before creating namespace)
     mp_obj_t meta;
     mp_map_elem_t *key_elem = mp_map_lookup(kwargs, MP_OBJ_NEW_QSTR(MP_QSTR_metaclass), MP_MAP_LOOKUP);
     if (key_elem != NULL) {
         meta = key_elem->value;
     } else {
-    if (n_args == 2) {
-        // no explicit bases, so use 'type'
-        meta = MP_OBJ_FROM_PTR(&mp_type_type);
-    } else {
-        // use type of first base object
-        meta = MP_OBJ_FROM_PTR(mp_obj_get_type(args[2]));
-    }
+        if (n_args == 2) {
+            // no explicit bases, so use 'type'
+            meta = MP_OBJ_FROM_PTR(&mp_type_type);
+        } else {
+            // use type of first base object
+            meta = MP_OBJ_FROM_PTR(mp_obj_get_type(args[2]));
+        }
     }
 
     // TODO do proper metaclass resolution for multiple base objects
 
-    // create the new class using a call to the meta object
+    // STEP 2: Call __prepare__ if it exists, or create regular dict
+    mp_obj_t class_locals;
+    #if MICROPY_PY_METACLASS_PREPARE
+    mp_obj_t prepare_dest[2] = {MP_OBJ_NULL, MP_OBJ_NULL};
+    mp_load_method_maybe(meta, MP_QSTR___prepare__, prepare_dest);
+
+    if (prepare_dest[0] != MP_OBJ_NULL) {
+        // __prepare__ exists, call it with (name, bases)
+        mp_obj_t prepare_args[4];
+        prepare_args[0] = prepare_dest[0];  // method function
+        prepare_args[1] = prepare_dest[1];  // self (metaclass)
+        prepare_args[2] = args[1];          // class name
+        prepare_args[3] = mp_obj_new_tuple(n_args - 2, args + 2); // bases tuple
+        class_locals = mp_call_method_n_kw(2, 0, prepare_args);
+    } else {
+        // No __prepare__, use regular dict
+        class_locals = mp_obj_new_dict(0);
+    }
+    #else
+    // __prepare__ not supported, always use regular dict
+    class_locals = mp_obj_new_dict(0);
+    #endif
+
+    // STEP 3: Execute class body with the namespace from __prepare__
+    mp_obj_dict_t *old_locals = mp_locals_get();
+    mp_locals_set(MP_OBJ_TO_PTR(class_locals));
+
+    // call the class code
+    mp_obj_t cell = mp_call_function_0(args[0]);
+
+    // restore old __locals__ object
+    mp_locals_set(old_locals);
+
+    // STEP 4: Create the class using the metaclass
     mp_obj_t meta_args[3];
     meta_args[0] = args[1]; // class name
     meta_args[1] = mp_obj_new_tuple(n_args - 2, args + 2); // tuple of bases
-    meta_args[2] = class_locals; // dict of members
+    meta_args[2] = class_locals; // dict of members (now from __prepare__)
     mp_obj_t new_class = mp_call_function_n_kw(meta, 3, 0, meta_args);
 
     // store into cell if needed

py/mpconfig.h

@@ -1314,6 +1314,14 @@ typedef time_t mp_timestamp_t;
 #define MICROPY_PY_METACLASS_PROPERTIES (MICROPY_CONFIG_ROM_LEVEL_AT_LEAST_EXTRA_FEATURES)
 #endif
 
+// Whether to support metaclass __prepare__ method (PEP 3115)
+// Allows metaclasses to customize the namespace dict before class creation
+// Required for enum.auto() to track insertion order
+// Size impact: ~150-180 bytes
+#ifndef MICROPY_PY_METACLASS_PREPARE
+#define MICROPY_PY_METACLASS_PREPARE (MICROPY_CONFIG_ROM_LEVEL_AT_LEAST_FULL_FEATURES)
+#endif
+
 // Support for async/await/async for/async with
 #ifndef MICROPY_PY_ASYNC_AWAIT
 #define MICROPY_PY_ASYNC_AWAIT (MICROPY_CONFIG_ROM_LEVEL_AT_LEAST_CORE_FEATURES)

tests/basics/class_metaclass_prepare.py

@@ -0,0 +1,115 @@
+# Test metaclass __prepare__ method (PEP 3115)
+
+# Skip test if __prepare__ is not supported
+_prepare_test = []
+class _TestMeta(type):
+    @classmethod
+    def __prepare__(mcs, name, bases):
+        _prepare_test.append(1)
+        return {}
+
+class _Test(metaclass=_TestMeta):
+    pass
+
+if not _prepare_test:
+    print("SKIP")
+    raise SystemExit
+
+# Test 1: Basic __prepare__ is called before class body execution
+print("Test 1: Basic __prepare__ call")
+prepare_log = []
+
+class Meta1(type):
+    @classmethod
+    def __prepare__(mcs, name, bases):
+        prepare_log.append(f"__prepare__({name})")
+        return {}
+
+class Test1(metaclass=Meta1):
+    prepare_log.append("body")
+
+print(prepare_log)
+print("PASS" if prepare_log == ["__prepare__(Test1)", "body"] else "FAIL")
+
+# Test 2: __prepare__ receives correct arguments
+print("\nTest 2: __prepare__ arguments")
+
+class Meta2(type):
+    @classmethod
+    def __prepare__(mcs, name, bases):
+        print(f"mcs={mcs.__name__}, name={name}, bases={bases}")
+        return {}
+
+class Base2:
+    pass
+
+class Test2(Base2, metaclass=Meta2):
+    pass
+
+# Test 3: __prepare__ return value is used as class namespace
+print("\nTest 3: __prepare__ return value as namespace")
+
+class Meta3(type):
+    @classmethod
+    def __prepare__(mcs, name, bases):
+        # Pre-populate namespace with a value
+        return {"injected": 42}
+
+class Test3(metaclass=Meta3):
+    pass
+
+print(f"Test3.injected = {Test3.injected}")
+print("PASS" if Test3.injected == 42 else "FAIL")
+
+# Test 4: __prepare__ can access namespace in __new__
+print("\nTest 4: Access namespace from __new__")
+
+class Meta4(type):
+    @classmethod
+    def __prepare__(mcs, name, bases):
+        # Return dict with tracking info
+        d = {}
+        d['_prepared'] = True
+        return d
+
+    def __new__(mcs, name, bases, namespace):
+        # Verify __prepare__ returned dict was used
+        was_prepared = namespace.get('_prepared', False)
+        cls = type.__new__(mcs, name, bases, dict(namespace))
+        cls._was_prepared = was_prepared
+        return cls
+
+class Test4(metaclass=Meta4):
+    x = 1
+
+print(f"Was prepared: {Test4._was_prepared}")
+print("PASS" if Test4._was_prepared else "FAIL")
+
+# Test 5: __prepare__ inheritance
+print("\nTest 5: Inherited __prepare__")
+
+class BaseMeta(type):
+    @classmethod
+    def __prepare__(mcs, name, bases):
+        print(f"BaseMeta.__prepare__({name})")
+        return {}
+
+class DerivedMeta(BaseMeta):
+    pass
+
+class Test5(metaclass=DerivedMeta):
+    pass
+
+# Test 6: __prepare__ not called when metaclass doesn't define it
+print("\nTest 6: No __prepare__ defined")
+
+class Meta6(type):
+    pass
+
+class Test6(metaclass=Meta6):
+    x = 1
+
+print(f"Test6.x = {Test6.x}")
+print("PASS")
+
+print("\nAll __prepare__ tests completed!")

tests/basics/class_metaclass_prepare.py.exp

@@ -0,0 +1,23 @@
+Test 1: Basic __prepare__ call
+['__prepare__(Test1)', 'body']
+PASS
+
+Test 2: __prepare__ arguments
+mcs=Meta2, name=Test2, bases=(<class 'Base2'>,)
+
+Test 3: __prepare__ return value as namespace
+Test3.injected = 42
+PASS
+
+Test 4: Access namespace from __new__
+Was prepared: True
+PASS
+
+Test 5: Inherited __prepare__
+BaseMeta.__prepare__(Test5)
+
+Test 6: No __prepare__ defined
+Test6.x = 1
+PASS
+
+All __prepare__ tests completed!