py/objtype: Add support for PEP487 __set_name__.

AJMansfield · AJMansfield · commit ecad02edff3c · 2025-07-21T10:52:42.000-04:00
This PR adds support for the `__set_name__` data model method specified by PEP487 - Simpler customisation of class creation. This includes support for methods that mutate the owner class, and avoids the naive modify-while-iterating hazard possible in a naive implementation like #15503. Note that based on the benchmarks in #16825, this is also as fast or faster than the naive implementation, thanks to clever data layout in setname_list_t, and the way this allows the capture step to run during an existing loop through the class dict. Other rejected approaches for dealing with the hazard include: - python/cpython#72983 During the implementation of this feature for MicroPython, it was discovered that some versions of CPython also have this naive hazard. CPython resolved this bug in BPO-28797 and now makes a complete flat copy of the class's dict to iterate. This design decision doesn't make much sense for a microcontroller though, even if it's perfectly reasonable in the desktop world where memcpy might actually be cheaper than a hard-to-branch-predict conditional; and it's also motivated in their case by error-tracing considerations. - #16816 This is an equivalent implementation to CPython's approach that places this copy directly on the stack; however it is both slower and has larger code size than the approach taken here. - #15503 The simplest implementation is to just not worry about it and let the user face the consequences if they mutate the owner class. That's not a very friendly behavior, though, and it's not actually much more performant than this implementation on either time or code size. - #17693 Another alternative is to do the same as #15503 but leverage MicroPython's existing `is_fixed` field in its dict type to convert attempted mutations of the owner dict into `AttributeError`s. This is safer than just leaving the open hazard, but there's still important use-cases for owner-mutating descriptors, and the performance ain is small enough that it isn't worth missing support for those cases. - combined #17693 with this Another version of this feature used a new feature define, `MICROPY_PY_METACLASSES_LITE`, to control whether this algorithm or the naive version is used. This was rejected in favor of simplicity, based on the very limited performance margin the naive version has (which in some cases even goes _against_ it). Signed-off-by: Anson Mansfield <amansfield@mantaro.com>
diff --git a/py/objtype.c b/py/objtype.c
@@ -661,8 +661,8 @@ static void mp_obj_instance_load_attr(mp_obj_t self_in, qstr attr, mp_obj_t *des
     // try __getattr__
     if (attr != MP_QSTR___getattr__) {
         #if MICROPY_PY_DESCRIPTORS
-        // With descriptors enabled, don't delegate lookups of __get__/__set__/__delete__.
-        if (attr == MP_QSTR___get__ || attr == MP_QSTR___set__ || attr == MP_QSTR___delete__) {
+        // With descriptors enabled, don't delegate lookups of __get__/__set__/__delete__/__set_name__.
+        if (attr == MP_QSTR___get__ || attr == MP_QSTR___set__ || attr == MP_QSTR___delete__ || attr == MP_QSTR___set_name__) {
             return;
         }
         #endif
@@ -960,7 +960,7 @@ static bool check_for_special_accessors(mp_obj_t key, mp_obj_t value) {
     #endif
     #if MICROPY_PY_DESCRIPTORS
     static const uint8_t to_check[] = {
-        MP_QSTR___get__, MP_QSTR___set__, MP_QSTR___delete__,
+        MP_QSTR___get__, MP_QSTR___set__, MP_QSTR___delete__, // not needed for MP_QSTR___set_name__ tho
     };
     for (size_t i = 0; i < MP_ARRAY_SIZE(to_check); ++i) {
         mp_obj_t dest_temp[2];
@@ -974,6 +974,51 @@ static bool check_for_special_accessors(mp_obj_t key, mp_obj_t value) {
 }
 #endif
 
+#if MICROPY_PY_DESCRIPTORS
+// Shared data layout for the __set_name__ call and a linked list of calls to be made.
+typedef union _setname_list_t setname_list_t;
+union _setname_list_t {
+    mp_obj_t call[4];
+    struct {
+        mp_obj_t _meth;
+        mp_obj_t _self;
+        setname_list_t *next; // can use the "owner" argument position temporarily for the linked list
+        mp_obj_t _name;
+    };
+};
+
+// Append any `__set_name__` method on `value` to the setname list, with its per-attr args
+static setname_list_t *setname_maybe_bind_append(setname_list_t *tail, mp_obj_t name, mp_obj_t value) {
+    // make certain our type-punning is safe:
+    MP_STATIC_ASSERT_NONCONSTEXPR(offsetof(setname_list_t, next) == offsetof(setname_list_t, call[2]));
+
+    // tail is a blank list entry
+    mp_load_method_maybe(value, MP_QSTR___set_name__, tail->call);
+    if (tail->call[1] != MP_OBJ_NULL) {
+        // Each time a __set_name__ is found, leave it in-place in the former tail and allocate a new tail
+        tail->next = m_new_obj(setname_list_t);
+        tail->next->next = NULL;
+        tail->call[3] = name;
+        return tail->next;
+    } else {
+        return tail;
+    }
+}
+
+// Execute the captured `__set_name__` calls, destroying the setname list in the process.
+static void setname_consume_call_all(setname_list_t head, mp_obj_t owner) {
+    setname_list_t *iter = &head, *next;
+    while ((next = iter->next) != NULL) {
+        iter->call[2] = owner;
+        mp_call_method_n_kw(2, 0, iter->call);
+        if (iter != &head) { // head is stack, just mark blank
+            m_del_obj(setname_list_t, iter); // optimistic free, help gc not take too many passes to unwind
+        }
+        iter = next;
+    }
+}
+#endif
+
 static void type_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind) {
     (void)kind;
     mp_obj_type_t *self = MP_OBJ_TO_PTR(self_in);
@@ -1210,20 +1255,38 @@ mp_obj_t mp_obj_new_type(qstr name, mp_obj_t bases_tuple, mp_obj_t locals_dict)
         }
     }
 
+    #if MICROPY_PY_DESCRIPTORS
+    // To avoid any dynamic allocations when no __set_name__ exists,
+    // the head of this list is kept on the stack (marked blank with `next = NULL`).
+    setname_list_t setname_list = { .next = NULL };
+    setname_list_t *setname_tail = &setname_list;
+    #endif
+
     #if ENABLE_SPECIAL_ACCESSORS
-    // Check if the class has any special accessor methods
-    if (!(o->flags & MP_TYPE_FLAG_HAS_SPECIAL_ACCESSORS)) {
-        for (size_t i = 0; i < locals_ptr->map.alloc; i++) {
-            if (mp_map_slot_is_filled(&locals_ptr->map, i)) {
-                const mp_map_elem_t *elem = &locals_ptr->map.table[i];
-                if (check_for_special_accessors(elem->key, elem->value)) {
-                    o->flags |= MP_TYPE_FLAG_HAS_SPECIAL_ACCESSORS;
-                    break;
-                }
+    // Check if the class has any special accessor methods,
+    // and accumulate bound __set_name__ methods that need to be called
+    for (size_t i = 0; i < locals_ptr->map.alloc; i++) {
+        #if !MICROPY_PY_DESCRIPTORS
+        // __set_name__ needs to scan the entire locals map, can't early-terminate
+        if (o->flags & MP_TYPE_FLAG_HAS_SPECIAL_ACCESSORS) {
+            break;
+        }
+        #endif
+
+        if (mp_map_slot_is_filled(&locals_ptr->map, i)) {
+            const mp_map_elem_t *elem = &locals_ptr->map.table[i];
+
+            if (!(o->flags & MP_TYPE_FLAG_HAS_SPECIAL_ACCESSORS) // elidable when the early-termination check is enabled
+                && check_for_special_accessors(elem->key, elem->value)) {
+                o->flags |= MP_TYPE_FLAG_HAS_SPECIAL_ACCESSORS;
             }
+
+            #if MICROPY_PY_DESCRIPTORS
+            setname_tail = setname_maybe_bind_append(setname_tail, elem->key, elem->value);
+            #endif
         }
     }
-    #endif
+    #endif // ENABLE_SPECIAL_ACCESSORS
 
     const mp_obj_type_t *native_base;
     size_t num_native_bases = instance_count_native_bases(o, &native_base);
@@ -1241,6 +1304,10 @@ mp_obj_t mp_obj_new_type(qstr name, mp_obj_t bases_tuple, mp_obj_t locals_dict)
         }
     }
 
+    #if MICROPY_PY_DESCRIPTORS
+    setname_consume_call_all(setname_list, MP_OBJ_FROM_PTR(o));
+    #endif
+
     return MP_OBJ_FROM_PTR(o);
 }
 
