Address serhiy-storchaka feedback: isinstance, mutable/immutable, None, float

- Use isinstance() instead of type(obj) for hint lookup, so subclasses
  of builtin types (e.g. OrderedDict, custom list subclasses) also
  get cross-language hints.
- Restructure table to index by method name for efficient isinstance
  iteration.
- Add mutable-on-immutable hints: tuple.append/extend/insert/remove
  suggest list, frozenset.add/discard/remove/update suggest set,
  frozendict.update suggests dict.
- Add NoneType hints: common methods (keys, upper, sort, etc.) tried
  on None suggest the type the user likely expected.
- Add float bitwise hints: __or__/__and__/__xor__/__lshift__/__rshift__
  suggest using int, fixing the misleading __dir__ Levenshtein suggestion.
- Cross-language hints now take priority over Levenshtein (they are more
  specific; Levenshtein still fires as fallback when no table match).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mvanhorn

Doc/whatsnew/3.15.rst

@@ -447,6 +447,28 @@ Improved error messages
      ...
      AttributeError: 'dict' object has no attribute 'put'. Use d[k] = v.
 
+  When a mutable method is called on an immutable type, the hint suggests
+  the mutable counterpart:
+
+  .. doctest::
+
+     >>> (1, 2, 3).append(4)  # doctest: +ELLIPSIS
+     Traceback (most recent call last):
+     ...
+     AttributeError: 'tuple' object has no attribute 'append'. Did you mean to use a 'list' object?
+
+  When a common method is called on ``None``, the hint suggests the type
+  the user likely expected:
+
+  .. doctest::
+
+     >>> None.keys()  # doctest: +ELLIPSIS
+     Traceback (most recent call last):
+     ...
+     AttributeError: 'NoneType' object has no attribute 'keys'. Did you expect a 'dict'?
+
+  These hints also work for subclasses of builtin types.
+
   (Contributed by Matt Van Horn in :gh:`146406`.)
 
 

Lib/test/test_traceback.py

@@ -4598,22 +4598,76 @@ def test_cross_language(self):
                 actual = self.get_suggestion(obj, attr)
                 self.assertEndsWith(actual, expected)
 
-    def test_cross_language_levenshtein_takes_priority(self):
-        # Levenshtein catches trim->strip and indexOf->index before
-        # the cross-language table is consulted
+    def test_cross_language_levenshtein_fallback(self):
+        # When no cross-language entry exists, Levenshtein still works
+        # (e.g., trim->strip is not in the table but Levenshtein catches it)
         actual = self.get_suggestion('', 'trim')
         self.assertIn("strip", actual)
 
     def test_cross_language_no_hint_for_unknown_attr(self):
         actual = self.get_suggestion([], 'completely_unknown_method')
         self.assertNotIn("Did you mean", actual)
 
-    def test_cross_language_not_triggered_for_subclasses(self):
-        # Only exact builtin types, not subclasses
+    def test_cross_language_works_for_subclasses(self):
+        # isinstance() check means subclasses also get hints
         class MyList(list):
             pass
         actual = self.get_suggestion(MyList(), 'push')
-        self.assertNotIn("append", actual)
+        self.assertEndsWith(actual, "Did you mean '.append'?")
+
+        class MyDict(dict):
+            pass
+        actual = self.get_suggestion(MyDict(), 'keySet')
+        self.assertEndsWith(actual, "Did you mean '.keys'?")
+
+    @force_not_colorized
+    def test_cross_language_mutable_on_immutable(self):
+        # Mutable method on immutable type suggests the mutable counterpart
+        cases = [
+            (tuple, 'append', "Did you mean to use a 'list' object?"),
+            (tuple, 'extend', "Did you mean to use a 'list' object?"),
+            (tuple, 'insert', "Did you mean to use a 'list' object?"),
+            (tuple, 'remove', "Did you mean to use a 'list' object?"),
+            (frozenset, 'add', "Did you mean to use a 'set' object?"),
+            (frozenset, 'discard', "Did you mean to use a 'set' object?"),
+            (frozenset, 'remove', "Did you mean to use a 'set' object?"),
+            (frozenset, 'update', "Did you mean to use a 'set' object?"),
+            (frozendict, 'update', "Did you mean to use a 'dict' object?"),
+        ]
+        for test_type, attr, expected in cases:
+            with self.subTest(type=test_type.__name__, attr=attr):
+                obj = test_type()
+                actual = self.get_suggestion(obj, attr)
+                self.assertEndsWith(actual, expected)
+
+    @force_not_colorized
+    def test_cross_language_none_suggestions(self):
+        # Common methods tried on None suggest the expected type
+        cases = [
+            ('keys', "Did you expect a 'dict'?"),
+            ('values', "Did you expect a 'dict'?"),
+            ('items', "Did you expect a 'dict'?"),
+            ('upper', "Did you expect a 'str'?"),
+            ('lower', "Did you expect a 'str'?"),
+            ('strip', "Did you expect a 'str'?"),
+            ('split', "Did you expect a 'str'?"),
+            ('sort', "Did you expect a 'list'?"),
+            ('pop', "Did you expect a 'list' or 'dict'?"),
+        ]
+        for attr, expected in cases:
+            with self.subTest(attr=attr):
+                actual = self.get_suggestion(None, attr)
+                self.assertEndsWith(actual, expected)
+
+    @force_not_colorized
+    def test_cross_language_float_bitwise(self):
+        # Bitwise operators on float suggest using int
+        cases = ['__or__', '__and__', '__xor__', '__lshift__', '__rshift__']
+        for attr in cases:
+            with self.subTest(attr=attr):
+                actual = self.get_suggestion(1.0, attr)
+                self.assertIn("'int'", actual)
+                self.assertIn("Bitwise operators", actual)
 
     def make_module(self, code):
         tmpdir = Path(tempfile.mkdtemp())

Lib/traceback.py

@@ -1147,16 +1147,20 @@ def __init__(self, exc_type, exc_value, exc_traceback, *, limit=None,
         elif exc_type and issubclass(exc_type, AttributeError) and \
                 getattr(exc_value, "name", None) is not None:
             wrong_name = getattr(exc_value, "name", None)
-            suggestion = _compute_suggestion_error(exc_value, exc_traceback, wrong_name)
-            if suggestion:
-                if suggestion.isascii():
-                    self._str += f". Did you mean '.{suggestion}' instead of '.{wrong_name}'?"
-                else:
-                    self._str += f". Did you mean '.{suggestion}' ({suggestion!a}) instead of '.{wrong_name}' ({wrong_name!a})?"
-            elif hasattr(exc_value, 'obj'):
+            # Check cross-language/wrong-type hints first (more specific),
+            # then fall back to Levenshtein distance suggestions.
+            hint = None
+            if hasattr(exc_value, 'obj'):
                 hint = _get_cross_language_hint(exc_value.obj, wrong_name)
-                if hint:
-                    self._str += f". {hint}"
+            if hint:
+                self._str += f". {hint}"
+            else:
+                suggestion = _compute_suggestion_error(exc_value, exc_traceback, wrong_name)
+                if suggestion:
+                    if suggestion.isascii():
+                        self._str += f". Did you mean '.{suggestion}' instead of '.{wrong_name}'?"
+                    else:
+                        self._str += f". Did you mean '.{suggestion}' ({suggestion!a}) instead of '.{wrong_name}' ({wrong_name!a})?"
         elif exc_type and issubclass(exc_type, NameError) and \
                 getattr(exc_value, "name", None) is not None:
             wrong_name = getattr(exc_value, "name", None)
@@ -1663,32 +1667,61 @@ def print(self, *, file=None, chain=True, **kwargs):
 #   2. Must not be catchable by Levenshtein distance (too different from
 #      the correct Python method name).
 #
-# Each entry maps (builtin_type, wrong_name) to a (suggestion, is_raw) tuple.
+# Each entry maps a wrong method name to a list of (type, suggestion, is_raw)
+# tuples. The lookup checks isinstance() so subclasses are also matched.
 # If is_raw is False, the suggestion is wrapped in "Did you mean '.X'?".
 # If is_raw is True, the suggestion is rendered as-is.
 #
 # See https://github.com/python/cpython/issues/146406.
-_CROSS_LANGUAGE_HINTS = frozendict({
+_CROSS_LANGUAGE_HINTS = {
     # list -- JavaScript/Ruby equivalents
-    (list, "push"): ("append", False),
-    (list, "concat"): ("extend", False),
+    "push": [(list, "append", False)],
+    "concat": [(list, "extend", False)],
     # list -- Java/C# equivalents
-    (list, "addAll"): ("extend", False),
-    (list, "contains"): ("Use 'x in list'.", True),
-    # list -- wrong-type suggestion more likely means the user expected a set
-    (list, "add"): ("Did you mean to use a 'set' object?", True),
+    "addAll": [(list, "extend", False)],
+    "contains": [(list, "Use 'x in list'.", True)],
+    # list -- wrong-type suggestion (user expected a set)
+    "add": [(list, "Did you mean to use a 'set' object?", True),
+            (frozenset, "Did you mean to use a 'set' object?", True)],
     # str -- JavaScript equivalents
-    (str, "toUpperCase"): ("upper", False),
-    (str, "toLowerCase"): ("lower", False),
-    (str, "trimStart"): ("lstrip", False),
-    (str, "trimEnd"): ("rstrip", False),
+    "toUpperCase": [(str, "upper", False)],
+    "toLowerCase": [(str, "lower", False)],
+    "trimStart": [(str, "lstrip", False)],
+    "trimEnd": [(str, "rstrip", False)],
     # dict -- Java/JavaScript equivalents
-    (dict, "keySet"): ("keys", False),
-    (dict, "entrySet"): ("items", False),
-    (dict, "entries"): ("items", False),
-    (dict, "putAll"): ("update", False),
-    (dict, "put"): ("Use d[k] = v.", True),
-})
+    "keySet": [(dict, "keys", False)],
+    "entrySet": [(dict, "items", False)],
+    "entries": [(dict, "items", False)],
+    "putAll": [(dict, "update", False)],
+    "put": [(dict, "Use d[k] = v.", True)],
+    # tuple -- mutable method on immutable type (user expected a list)
+    "append": [(tuple, "Did you mean to use a 'list' object?", True)],
+    "extend": [(tuple, "Did you mean to use a 'list' object?", True)],
+    "insert": [(tuple, "Did you mean to use a 'list' object?", True)],
+    "remove": [(tuple, "Did you mean to use a 'list' object?", True),
+               (frozenset, "Did you mean to use a 'set' object?", True)],
+    # frozenset -- mutable method on immutable type (user expected a set)
+    "discard": [(frozenset, "Did you mean to use a 'set' object?", True)],
+    # frozendict -- mutable method on immutable type (user expected a dict)
+    "update": [(frozenset, "Did you mean to use a 'set' object?", True),
+               (frozendict, "Did you mean to use a 'dict' object?", True)],
+    # float -- bitwise operators belong to int
+    "__or__": [(float, "Did you mean to use an 'int' object? Bitwise operators are not supported by 'float'.", True)],
+    "__and__": [(float, "Did you mean to use an 'int' object? Bitwise operators are not supported by 'float'.", True)],
+    "__xor__": [(float, "Did you mean to use an 'int' object? Bitwise operators are not supported by 'float'.", True)],
+    "__lshift__": [(float, "Did you mean to use an 'int' object? Bitwise operators are not supported by 'float'.", True)],
+    "__rshift__": [(float, "Did you mean to use an 'int' object? Bitwise operators are not supported by 'float'.", True)],
+    # NoneType -- common methods tried on None (got None instead of expected type)
+    "keys": [(type(None), "Did you expect a 'dict'?", True)],
+    "values": [(type(None), "Did you expect a 'dict'?", True)],
+    "items": [(type(None), "Did you expect a 'dict'?", True)],
+    "upper": [(type(None), "Did you expect a 'str'?", True)],
+    "lower": [(type(None), "Did you expect a 'str'?", True)],
+    "strip": [(type(None), "Did you expect a 'str'?", True)],
+    "split": [(type(None), "Did you expect a 'str'?", True)],
+    "sort": [(type(None), "Did you expect a 'list'?", True)],
+    "pop": [(type(None), "Did you expect a 'list' or 'dict'?", True)],
+}
 
 
 def _substitution_cost(ch_a, ch_b):
@@ -1753,19 +1786,21 @@ def _check_for_nested_attribute(obj, wrong_name, attrs):
 
 
 def _get_cross_language_hint(obj, wrong_name):
-    """Check if wrong_name is a common method name from another language.
+    """Check if wrong_name is a common method name from another language,
+    a mutable method on an immutable type, or a method tried on None.
 
-    Only checks exact builtin types (list, str, dict) to avoid false
-    positives on subclasses that may intentionally lack these methods.
+    Uses isinstance() so subclasses of builtin types also get hints.
     Returns a formatted hint string, or None.
     """
-    entry = _CROSS_LANGUAGE_HINTS.get((type(obj), wrong_name))
-    if entry is None:
+    entries = _CROSS_LANGUAGE_HINTS.get(wrong_name)
+    if entries is None:
         return None
-    hint, is_raw = entry
-    if is_raw:
-        return hint
-    return f"Did you mean '.{hint}'?"
+    for check_type, hint, is_raw in entries:
+        if isinstance(obj, check_type):
+            if is_raw:
+                return hint
+            return f"Did you mean '.{hint}'?"
+    return None
 
 
 def _get_safe___dir__(obj):

Misc/NEWS.d/next/Library/2026-03-25-07-17-41.gh-issue-146406.ydsmqe.rst

@@ -1,4 +1,6 @@
 Cross-language method suggestions are now shown for :exc:`AttributeError` on
-builtin types when the existing Levenshtein-based suggestions find no match.
-For example, ``[].push()`` now suggests ``append`` and
-``"".toUpperCase()`` suggests ``upper``.
+builtin types and their subclasses.
+For example, ``[].push()`` suggests ``append``,
+``(1,2).append(3)`` suggests using a ``list``,
+``None.keys()`` suggests expecting a ``dict``,
+and ``1.0.__or__`` suggests using an ``int``.