Use a miss-only __getattr__ hook for AttributeError suggestions

Move the suggestion logic for regular reflected types off the hot
attribute-access path. Previously ClassObject overrode tp_getattro
(__getattribute__), so every successful attribute access paid a managed
round-trip (~17 ns/access measured). Instead, install a shared
__getattr__ on each reflected type, which CPython only invokes on a miss
via slot_tp_getattr_hook; hits go straight through the native generic
getattr with no managed transition.

pythonnet's metatype does not run CPython's slot-fixup when attributes
are set on a type, so AttributeErrorHint wires tp_getattro to the hook
manually (the hook address is read from a probe class). Only types still
using the native generic getattr are redirected, so dynamic objects,
modules and interfaces (which have their own tp_getattro) are untouched;
DynamicClassObject keeps enriching on its own miss path.

Benchmark (System.Version, best-of-N, ns/access):
  hit  path:  ~109 ns  (baseline ~105; tp_getattro was ~122)
  miss path:  ~11 us   (rare; reflection + Levenshtein, as before)

The hot-path overhead is effectively eliminated; the extra miss-path
cost only applies when an attribute is actually absent.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: jhonabreul

src/runtime/AttributeErrorHint.cs

@@ -0,0 +1,109 @@
+using System;
+
+using Python.Runtime.Native;
+
+namespace Python.Runtime
+{
+    /// <summary>
+    /// Installs a miss-only <c>__getattr__</c> hook on reflected .NET types so that an
+    /// <c>AttributeError</c> raised for a missing attribute is enriched with suggestions
+    /// of similarly-named members — without adding any cost to the (common) successful
+    /// attribute-access path.
+    /// </summary>
+    /// <remarks>
+    /// CPython only invokes <c>__getattr__</c> after the normal attribute lookup fails,
+    /// via the native <c>slot_tp_getattr_hook</c>: on a hit it calls the generic getattr
+    /// directly (no managed transition); only on a miss does it call our <c>__getattr__</c>.
+    /// pythonnet's metatype does not run CPython's slot-fixup machinery when an attribute
+    /// is set on a type, so simply adding <c>__getattr__</c> to the type dict would not
+    /// rewire the slot — we therefore wire <c>tp_getattro</c> to the hook manually.
+    /// </remarks>
+    internal static class AttributeErrorHint
+    {
+        // The shared __getattr__ function object installed on every eligible type.
+        private static PyObject? _getAttr;
+        // The managed message builder exposed to Python, kept alive for _getAttr's globals.
+        private static PyObject? _messageBuilder;
+        // Address of CPython's slot_tp_getattr_hook (extracted from a probe type).
+        private static IntPtr _hookSlot;
+        // Address of PyObject_GenericGetAttr, used to detect types we may safely redirect.
+        private static IntPtr _genericGetAttr;
+
+        private static bool IsReady => _getAttr is not null && _hookSlot != IntPtr.Zero;
+
+        internal static void Initialize()
+        {
+            try
+            {
+                _genericGetAttr = Util.ReadIntPtr(Runtime.PyBaseObjectType, TypeOffset.tp_getattro);
+
+                Func<PyObject, string, string> builder = ClassBase.BuildMissingAttributeMessage;
+                _messageBuilder = builder.ToPython();
+
+                using var globals = new PyDict();
+                Runtime.PyDict_SetItemString(globals.Reference, "__builtins__", Runtime.PyEval_GetBuiltins());
+                globals["__clr_attr_msg__"] = _messageBuilder;
+
+                // Define the shared hook, plus a probe class whose tp_getattro is
+                // slot_tp_getattr_hook so we can read that function pointer.
+                PythonEngine.Exec(
+                    "def __clr_getattr__(self, name):\n" +
+                    "    raise AttributeError(__clr_attr_msg__(self, name))\n" +
+                    "class __clr_getattr_probe__:\n" +
+                    "    def __getattr__(self, name):\n" +
+                    "        raise AttributeError(name)\n",
+                    globals);
+
+                _getAttr = globals["__clr_getattr__"];
+                using var probe = globals["__clr_getattr_probe__"];
+                _hookSlot = Util.ReadIntPtr(probe.Reference, TypeOffset.tp_getattro);
+            }
+            catch (Exception e)
+            {
+                // Degrade gracefully: without the hook, AttributeError messages are simply
+                // not enriched. Never let this break interpreter initialization.
+                DebugUtil.Print($"AttributeErrorHint.Initialize failed: {e}");
+                Shutdown();
+            }
+        }
+
+        /// <summary>
+        /// Wires the miss-only hook onto <paramref name="type"/> if it still uses the
+        /// native generic getattr. Types with a custom <c>tp_getattro</c> (dynamic
+        /// objects, modules, interfaces, ...) handle misses themselves and are left
+        /// untouched; derived types that inherit an already-hooked base are likewise
+        /// skipped, since they inherit the behavior through the MRO.
+        /// </summary>
+        internal static void Install(BorrowedReference type)
+        {
+            if (!IsReady)
+            {
+                return;
+            }
+
+            if (Util.ReadIntPtr(type, TypeOffset.tp_getattro) != _genericGetAttr)
+            {
+                return;
+            }
+
+            if (Runtime.PyObject_SetAttrString(type, "__getattr__", _getAttr!.Reference) != 0)
+            {
+                Exceptions.Clear();
+                return;
+            }
+
+            Util.WriteIntPtr(type, TypeOffset.tp_getattro, _hookSlot);
+            Runtime.PyType_Modified(type);
+        }
+
+        internal static void Shutdown()
+        {
+            _getAttr?.Dispose();
+            _getAttr = null;
+            _messageBuilder?.Dispose();
+            _messageBuilder = null;
+            _hookSlot = IntPtr.Zero;
+            _genericGetAttr = IntPtr.Zero;
+        }
+    }
+}

src/runtime/PythonEngine.cs

@@ -263,6 +263,10 @@ public static void Initialize(IEnumerable<string> args, bool setSysArgv = true,
             }
 
             ImportHook.UpdateCLRModuleDict();
+
+            // Set up the miss-only __getattr__ hook used to enrich AttributeError
+            // messages on reflected .NET types with member-name suggestions.
+            AttributeErrorHint.Initialize();
         }
 
         static BorrowedReference DefineModule(string name)
@@ -369,6 +373,9 @@ public static void Shutdown()
             AppDomain.CurrentDomain.ProcessExit -= OnProcessExit;
 
             ExecuteShutdownHandlers();
+
+            AttributeErrorHint.Shutdown();
+
             // Remember to shut down the runtime.
             Runtime.Shutdown();
 

src/runtime/TypeManager.cs

@@ -303,6 +303,10 @@ internal static void InitializeClass(PyType type, ClassBase impl, Type clrType)
 
             Runtime.PyType_Modified(type.Reference);
 
+            // Enrich AttributeError messages for missing attributes with member-name
+            // suggestions, via a miss-only __getattr__ hook (no hot-path cost).
+            AttributeErrorHint.Install(type.Reference);
+
             //DebugUtil.DumpType(type);
         }
 

src/runtime/Types/ClassBase.cs

@@ -628,20 +628,13 @@ internal static void AppendAttributeErrorSuggestions(BorrowedReference ob, Borro
             }
 
             var name = Runtime.GetManagedString(key);
-            // Skip empty and dunder names: the latter are probed internally by CPython
-            // (e.g. __iter__, __len__) and are never user-facing typos worth helping with.
-            if (string.IsNullOrEmpty(name) || name.StartsWith("__", StringComparison.Ordinal))
+            if (string.IsNullOrEmpty(name))
             {
                 return;
             }
 
-            if (GetManagedObject(ob) is not CLRObject clrObj || clrObj.inst is null)
-            {
-                return;
-            }
-
-            var suggestions = GetSimilarMemberNames(clrObj.inst.GetType(), name);
-            if (suggestions.Count == 0)
+            var hint = GetSuggestionHint(ob, name);
+            if (hint.Length == 0)
             {
                 return;
             }
@@ -651,7 +644,6 @@ internal static void AppendAttributeErrorSuggestions(BorrowedReference ob, Borro
             try
             {
                 var baseMessage = GetErrorMessage(errValue.BorrowNullable(), name);
-                var hint = " Did you mean: " + string.Join(", ", suggestions.Select(s => $"'{s}'")) + "?";
                 Exceptions.SetError(Exceptions.AttributeError, baseMessage + hint);
             }
             finally
@@ -662,6 +654,65 @@ internal static void AppendAttributeErrorSuggestions(BorrowedReference ob, Borro
             }
         }
 
+        /// <summary>
+        /// Builds the full message for an <c>AttributeError</c> raised for a missing
+        /// attribute on a .NET object, including any "Did you mean ...?" hint. Used by
+        /// the miss-only <c>__getattr__</c> hook installed on reflected types (see
+        /// <see cref="AttributeErrorHint"/>), where the original error has already been
+        /// cleared, so the base message is reconstructed here.
+        /// </summary>
+        internal static string BuildMissingAttributeMessage(PyObject self, string name)
+        {
+            var typeName = "object";
+            try
+            {
+                using var pyType = self.GetPythonType();
+                typeName = pyType.Name;
+            }
+            catch
+            {
+                // fall back to the generic type name
+            }
+
+            var message = $"'{typeName}' object has no attribute '{name}'";
+            try
+            {
+                return message + GetSuggestionHint(self.Reference, name);
+            }
+            catch
+            {
+                // never let suggestion building turn into a different exception
+                return message;
+            }
+        }
+
+        /// <summary>
+        /// Returns " Did you mean: 'x', 'y'?" listing similarly-named members of the
+        /// managed object, or an empty string when there is nothing to suggest. Dunder
+        /// names are skipped: they are probed internally by CPython (e.g. __iter__,
+        /// __len__) and are never user-facing typos worth helping with.
+        /// </summary>
+        private static string GetSuggestionHint(BorrowedReference ob, string name)
+        {
+            if (string.IsNullOrEmpty(name) || name.StartsWith("__", StringComparison.Ordinal))
+            {
+                return string.Empty;
+            }
+
+            if (GetManagedObject(ob) is not CLRObject clrObj || clrObj.inst is null)
+            {
+                return string.Empty;
+            }
+
+            var suggestions = GetSimilarMemberNames(clrObj.inst.GetType(), name);
+            if (suggestions.Count == 0)
+            {
+                return string.Empty;
+            }
+
+            return " Did you mean: " + string.Join(", ", suggestions.Select(s => $"'{s}'")) + "?";
+        }
+
         private static string GetErrorMessage(BorrowedReference value, string fallbackName)
         {
             if (value != null)

src/runtime/Types/ClassObject.cs

@@ -167,21 +167,6 @@ public override void InitializeSlots(BorrowedReference pyType, SlotsHolder slots
         protected virtual NewReference NewObjectToPython(object obj, BorrowedReference tp)
             => CLRObject.GetReference(obj, tp);
 
-        /// <summary>
-        /// Type __getattro__ implementation. Delegates to the generic CLR attribute
-        /// lookup, but enriches the AttributeError raised for a missing attribute with
-        /// suggestions of similarly-named members of the managed type.
-        /// </summary>
-        public static NewReference tp_getattro(BorrowedReference ob, BorrowedReference key)
-        {
-            var result = Runtime.PyObject_GenericGetAttr(ob, key);
-            if (result.IsNull())
-            {
-                AppendAttributeErrorSuggestions(ob, key);
-            }
-            return result;
-        }
-
         private static NewReference NewEnum(Type type, BorrowedReference args, BorrowedReference tp)
         {
             nint argCount = Runtime.PyTuple_Size(args);