gh-146406: Add cross-language method suggestions for builtin AttributeError by mvanhorn · Pull Request #146407 · python/cpython

mvanhorn · 2026-03-25T07:16:45Z

Summary

When an AttributeError on a builtin type (list, str, dict) has no
Levenshtein-based suggestion, check a static table of common method names
from other languages.

Before:

>>> [1, 2, 3].push(4)
AttributeError: 'list' object has no attribute 'push'

After:

>>> [1, 2, 3].push(4)
AttributeError: 'list' object has no attribute 'push'. Did you mean '.append' instead of '.push'?

Discourse discussion

Discussed at https://discuss.python.org/t/106632 (420 views, 25 likes, 15 posts, 3 core devs).

Design decisions from the thread:

Flat table per @pf_moore (post 14, 4 likes):

"the table can simply map the method name and object type onto a suggestion. So add on a list is mapped straight to 'did you mean to use a set?' No need to check whether add is a set method - you know it is already."
list.add() suggests set, not append per @Storchaka (post 8):

"It can also mean that you passed a list instead of set. Changing 'add' to 'append' will not fix the error, it will introduce yet one error."

Reinforced by @tjreedy (post 12):

"When a method exists for another, related, Python class, I think it better to suggest the other class rather than assume a foreign language match."
Scope guardrails per @dr_carlos (post 3): only add entries backed by real confusion evidence, not just because methods are similar.
Static table for builtins only (Option 1) - community consensus. 11 entries covering JavaScript, Java, C#, and Ruby.

Verification

Before (system Python 3.13, no cross-language hints):

>>> [1, 2, 3].push(4)
AttributeError: 'list' object has no attribute 'push'

>>> 'hello'.toUpperCase()
AttributeError: 'str' object has no attribute 'toUpperCase'

>>> {}.keySet()
AttributeError: 'dict' object has no attribute 'keySet'

>>> [].add(1)
AttributeError: 'list' object has no attribute 'add'

After (this PR):

>>> [1, 2, 3].push(4)
AttributeError: 'list' object has no attribute 'push'. Did you mean '.append' instead of '.push'?

>>> 'hello'.toUpperCase()
AttributeError: 'str' object has no attribute 'toUpperCase'. Did you mean '.upper' instead of '.toUpperCase'?

>>> {}.keySet()
AttributeError: 'dict' object has no attribute 'keySet'. Did you mean '.keys' instead of '.keySet'?

>>> [].add(1)
AttributeError: 'list' object has no attribute 'add'. Did you mean to use a set? Sets have an .add() method

Levenshtein still takes priority (trim->strip, indexOf->index already work and are not in the table). Only exact builtin types are matched - subclasses are not affected.

Changes

Lib/traceback.py: Added _CROSS_LANGUAGE_HINTS dict (11 entries), _get_cross_language_hint() function, and a 4-line fallback hook in TracebackException.__init__ that runs only when Levenshtein found nothing.
Lib/test/test_traceback.py: 15 test cases covering all entries, priority ordering, unknown attrs, and subclass exclusion.
Misc/NEWS.d/: NEWS entry.

Evidence

Source	Evidence
SO: push vs append	320K views
SO: trim whitespace	1.5M views
JetBrains/PSF Survey 2024	40% of Python devs also use JS
CPython precedent	`elseif`->`elif` (gh-132449), `import x from y`->`from x import y` (gh-98931)
Discourse thread	420 views, 25 likes, 3 core devs supportive

Fixes #146406

Issue: Add cross-language method suggestions for builtin AttributeError #146406

When Levenshtein-based suggestions find no match for an AttributeError on list, str, or dict, check a static table of common method names from JavaScript, Java, C#, and Ruby. For example, [].push() now suggests .append(), "".toUpperCase() suggests .upper(), and {}.keySet() suggests .keys(). The list.add() case suggests using a set instead of suggesting .append(), since .add() is a set method and the user may have passed a list where a set was expected (per discussion with Serhiy Storchaka, Terry Reedy, and Paul Moore). Design: flat (type, attr) -> suggestion text table, no runtime introspection. Only exact builtin types are matched to avoid false positives on subclasses. Discussion: https://discuss.python.org/t/106632

mvanhorn · 2026-03-25T07:18:49Z

Verification screenshots

Built CPython from source and ran the REPL to verify before/after behavior.

Before (Python 3.13, no cross-language hints)

After (this PR)

All 447 tests in test_traceback pass (including 28 new cross-language tests).

picnixz · 2026-03-25T09:06:10Z

I will make a review of this PR when I have time (by the end of the week), so fellow core devs, please hold off any merge, TiA!

nedbat · 2026-03-25T09:25:01Z

Thanks for taking this on! From a language perspective, I think these can be shorter. Instead of:

AttributeError: 'list' object has no attribute 'push'. Did you mean '.append' instead of '.push'?

I think it is enough to say:

AttributeError: 'list' object has no attribute 'push'. Did you mean '.append' instead?

or even:

AttributeError: 'list' object has no attribute 'push'. Did you mean '.append'?

ZeroIntensity

Looks very cool!

It'd also be nice if we could suggest using language constructs in some cases. For example:

dict.put -> dict[x] = y
list.contains -> x in list

ZeroIntensity · 2026-03-25T12:19:04Z

Lib/traceback.py

+#
+# See https://discuss.python.org/t/106632 for the design discussion.


Let's link to the GH issue instead.

Done, switched to the GH issue link.

ZeroIntensity · 2026-03-25T12:22:06Z

Lib/traceback.py

+    (list, "push"):     "append",
+    (list, "concat"):   "extend",


I'd prefer to keep standard convention and just use a single space after the :. Alignment adds extra maintenance (because we need to change each entry if we add something that breaks it) and also creates a false-symmetry between each entry (e.g., for our purposes (list, "push"): "append" has no functional relation to (list, "concat"): "extend").

Makes sense, dropped the alignment.

ZeroIntensity · 2026-03-25T12:23:49Z

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

+``"".toUpperCase()`` suggests ``upper``. The ``list.add()`` case suggests
+using a set instead, following feedback from the community discussion.


This last sentence isn't particularly useful:

Suggested change

``"".toUpperCase()`` suggests ``upper``. The ``list.add()`` case suggests

using a set instead, following feedback from the community discussion.

``"".toUpperCase()`` suggests ``upper``.

Applied your suggestion.

ZeroIntensity · 2026-03-25T12:28:16Z

Lib/traceback.py

                else:
                    self._str += f". Did you mean '.{suggestion}' ({suggestion!a}) instead of '.{wrong_name}' ({wrong_name!a})?"
+            elif hasattr(exc_value, 'obj'):
+                with suppress(Exception):


Hm, what needs to be suppressed here?

Nothing realistic - _get_cross_language_hint is just a dict lookup on (type(obj), wrong_name), both of which are already validated by the time we get here. I had it as a defensive measure since we're inside traceback formatting, but on reflection it's unnecessary given how simple the function is. Removed it.

@ZeroIntensity

- Shorten hint format to "Did you mean '.append'?" (drop redundant "instead of '.push'" since the error already names the attribute) - Add dict.put and list.contains entries suggesting language constructs (dict[key] = value, x in list) per @ZeroIntensity's review - Replace suppress(Exception) with direct call (function is safe) - Link to GH issue instead of Discourse thread in comment - Drop column alignment in hint table entries - Trim NEWS entry last sentence

mvanhorn · 2026-03-25T12:50:49Z

Good call - the error message already says "has no attribute 'push'" so repeating it in the hint is noise. Shortened to Did you mean '.append'? in 6d58cdc.

I kept the existing Levenshtein format as-is (that's a separate code path and probably a separate discussion), so the cross-language hints now have their own slighty shorter style.

mvanhorn · 2026-03-25T12:51:13Z

@ZeroIntensity re: suggesting language constructs - added both in 6d58cdc. They use the custom hint format since they suggest constructs rather than method equivalents:

>>> {}.put("a", 1)
AttributeError: 'dict' object has no attribute 'put'. Use dict[key] = value for item assignment

>>> [].contains(1)
AttributeError: 'list' object has no attribute 'contains'. Use 'x in list' to check membership

The existing architecture already handles this - entries with a space in the hint string are rendered as-is rather than wrapped in "Did you mean" format.

mvanhorn · 2026-03-25T12:52:32Z

I will make a review of this PR when I have time (by the end of the week), so fellow core devs, please hold off any merge, TiA!

appreciat you digging in when you're ready! ::anxiously waits::

ZeroIntensity · 2026-03-25T12:53:28Z

Oh, you also need to add an entry to "What's New in Python 3.15".

mvanhorn · 2026-03-25T13:12:24Z

Added in 579d037 - covers the basic hint format and the language-construct variant (dict.put, list.contains).

Lib/traceback.py

Doc/whatsnew/3.15.rst

- Use (hint, is_raw) tuples instead of space-based raw detection - Shorten list.add hint to "Did you mean to use a 'set' object?" - Use d[k] = v instead of dict[key] = value for dict.put hint - Add dict.entries -> items (JavaScript) - Remove Levenshtein guardrail from code comment (belongs on issue) - Add periods to raw hint messages - Add test for dict.entries

Lib/traceback.py

Lib/test/test_traceback.py

Lib/traceback.py

@vstinner

Address review feedback from @vstinner: - Merge 14 individual test_cross_language_* methods into a single parameterized test_cross_language using subTest - Shorten raw-message hints: "Use 'x in list'." and "Use d[k] = v." - Fix pre-existing levenshtein priority test assertion - Update whatsnew entry to match shortened hint text

Lib/test/test_traceback.py

…suffix matching Apply vstinner's review suggestion: use assertEndsWith instead of assertIn for more precise test assertions. Split cases into method hints (checked via Did you mean pattern) and raw hints (checked via exact suffix).

vstinner

LGTM. The implementation is correct and well tested. IMO the feature makes sense and is useful.

vstinner · 2026-03-25T23:28:33Z

Lib/traceback.py

+# If is_raw is True, the suggestion is rendered as-is.
+#
+# See https://github.com/python/cpython/issues/146406.
+_CROSS_LANGUAGE_HINTS = {


You might use a frozendict for such global constant dictionary.

Applied in f702e79 - wrapped in types.MappingProxyType.

You don't need types.MappingProxyType. We have a native frozendict type in 3.15 as of PEP 814.

Nice - frozendict is cleaner than the MappingProxyType wrapper. Thanks for applying it.

It seems like the frozendict was lost in the meanwhile.

Lib/traceback.py

vstinner · 2026-03-26T16:38:34Z

I applied my suggestion to replace types.MappingProxyType with frozendict.

vstinner · 2026-04-07T21:06:02Z

@ZeroIntensity @picnixz: Are you ok with this change?

picnixz

One nit and otherwise LGTM. I think @serhiy-storchaka had some more reservations/suggestions so I'd wait a bit for his feedback maybe?

Lib/traceback.py

ZeroIntensity

Fine with me!

mvanhorn · 2026-04-09T06:15:26Z

Thanks @picnixz for the review and approval! Happy to wait for @serhiy-storchaka's feedback.

Is the nit you mentioned something I should address now, or was it from the earlier round (the Levenshtein point and the raw hint formatting)? Those should be fixed in the latest commits but let me know if I missed something.

picnixz · 2026-04-09T07:19:39Z

The nit is just adding a newline before the "1.".

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

mvanhorn · 2026-04-10T15:00:48Z

Added the blank line in 0089761. Waiting on @serhiy-storchaka whenever he has time.

serhiy-storchaka · 2026-04-10T15:35:35Z

See my comments on the issue.

First, it should work for subclasses. We should also fix suggestions for float.__or__ and other wrong suggestions. Add suggestions for tuple.append, frozenset.add, frozendict.update, etc. Maybe add some suggestions for None.

…e, 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>

mvanhorn · 2026-04-10T16:57:02Z

Thanks @serhiy-storchaka for the thorough feedback! Addressed all your points in e2c12ec:

Subclass support: Switched from type(obj) exact match to isinstance() check. OrderedDict().entries() now suggests .items(), custom list subclasses get hints too. Table restructured to index by method name for efficient isinstance iteration.

Mutable on immutable: Added tuple.append/extend/insert/remove (suggests list), frozenset.add/discard/remove/update (suggests set), frozendict.update (suggests dict).

None suggestions: Added hints for common methods tried on None: None.keys() suggests dict, None.upper() suggests str, None.sort() suggests list, etc.

Float bitwise: Added float.__or__/__and__/__xor__/__lshift__/__rshift__ suggesting int. Cross-language hints now take priority over Levenshtein (more specific), so the misleading __dir__ suggestion is replaced. Levenshtein still fires as fallback when no table match exists.

Demo (built from source, Python REPL):

All 433 tests in test_traceback pass.

vstinner · 2026-04-10T18:37:56Z

Lib/traceback.py

+    "__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)],


You can replace type(None) with types.NoneType.

vstinner · 2026-04-10T18:53:28Z

Doc/whatsnew/3.15.rst

+
+  .. doctest::
+
+     >>> None.keys()  # doctest: +ELLIPSIS


I don't understand the None suggestions. Yes, None has no keys() method, but I don't see how I'm supposed to replace it with a dict in this example.

I expected an example where a variable is set to None by mistake, such as:

>>> lst=[1,2,3].sort() >>> lst.pop()

cc @serhiy-storchaka

vstinner · 2026-04-10T18:55:35Z

Lib/traceback.py

+# If is_raw is True, the suggestion is rendered as-is.
+#
+# See https://github.com/python/cpython/issues/146406.
+_CROSS_LANGUAGE_HINTS = {


It seems like the frozendict was lost in the meanwhile.

Add missing @force_not_colorized decorator to three cross-language test methods. The CPython C-level traceback path includes ANSI color codes in error output, causing assertEndsWith to fail when the expected string doesn't account for trailing escape sequences. Also add the decorator to test_cross_language_levenshtein_fallback and test_cross_language_no_hint_for_unknown_attr for consistency with all other cross-language tests.

1. Restore frozendict() wrapper for _CROSS_LANGUAGE_HINTS table (lost during the isinstance() refactor in e2c12ec). Convert inner lists to tuples for consistency with immutable container. 2. Replace type(None) with types.NoneType per review. 3. Replace contrived None.keys() doctest with a realistic example: lst = [3, 1, 2].sort() followed by lst.pop(), showing the common "method returned None" mistake vstinner suggested.

mvanhorn · 2026-04-10T21:22:44Z

Addressed all three in e1eb6f4:

type(None) → types.NoneType - Done.
frozendict wrapper restored - The frozendict() wrapper was lost during the isinstance() refactor in e2c12ec. Restored it, and converted inner lists to tuples for consistency with the immutable container.
None doctest - Good point, None.keys() was contrived. Replaced with your example:

>>> lst = [3, 1, 2].sort()
>>> lst.pop()

This shows the real scenario (method returned None instead of the expected object). Also updated the prose to explain why.

(Also fixed the CI failure from the previous push in 564ca3a - three cross-language tests were missing @force_not_colorized.)

bedevere-app bot mentioned this pull request Mar 25, 2026

Add cross-language method suggestions for builtin AttributeError #146406

Open

bedevere-app bot added the awaiting review label Mar 25, 2026

fix NEWS entry filename for bedevere bot

aecaacb

picnixz self-requested a review March 25, 2026 09:05

ZeroIntensity reviewed Mar 25, 2026

View reviewed changes

mvanhorn requested a review from AA-Turner as a code owner March 25, 2026 13:10

Add What's New entry for cross-language AttributeError hints

8a39e32

mvanhorn force-pushed the osc/cross-language-attr-hints branch from 57b8fc8 to 8a39e32 Compare March 25, 2026 13:17

picnixz reviewed Mar 25, 2026

View reviewed changes

Lib/traceback.py Outdated Show resolved Hide resolved

Keep Levenshtein criterion, remove survey restriction per picnixz

99e106a

vstinner reviewed Mar 25, 2026

View reviewed changes

Lib/test/test_traceback.py Outdated Show resolved Hide resolved

Lib/traceback.py Outdated Show resolved Hide resolved

Lib/traceback.py Outdated Show resolved Hide resolved

vstinner reviewed Mar 25, 2026

View reviewed changes

Lib/test/test_traceback.py Outdated Show resolved Hide resolved

vstinner approved these changes Mar 25, 2026

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting review labels Mar 25, 2026

Use MappingProxyType for _CROSS_LANGUAGE_HINTS per vstinner review

f702e79

vstinner reviewed Mar 26, 2026

View reviewed changes

Lib/traceback.py Outdated Show resolved Hide resolved

Update Lib/traceback.py

3ad54c8

picnixz approved these changes Apr 7, 2026

View reviewed changes

Lib/traceback.py Show resolved Hide resolved

ZeroIntensity approved these changes Apr 8, 2026

View reviewed changes

Add blank line before criteria list per review

0089761

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

vstinner reviewed Apr 10, 2026

View reviewed changes

mvanhorn added 2 commits April 10, 2026 16:55

		#
		# See https://discuss.python.org/t/106632 for the design discussion.

		``"".toUpperCase()`` suggests ``upper``. The ``list.add()`` case suggests
		using a set instead, following feedback from the community discussion.

Uh oh!

Conversation

mvanhorn commented Mar 25, 2026 • edited by bedevere-app bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Discourse discussion

Verification

Changes

Evidence

Uh oh!

mvanhorn commented Mar 25, 2026

Verification screenshots

Before (Python 3.13, no cross-language hints)

After (this PR)

Uh oh!

picnixz commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nedbat commented Mar 25, 2026

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mvanhorn commented Mar 25, 2026

Uh oh!

mvanhorn commented Mar 25, 2026

Uh oh!

mvanhorn commented Mar 25, 2026

Uh oh!

ZeroIntensity commented Mar 25, 2026

Uh oh!

mvanhorn commented Mar 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vstinner commented Mar 26, 2026

Uh oh!

vstinner commented Apr 7, 2026

Uh oh!

mvanhorn commented Mar 25, 2026 •

edited by bedevere-app bot

Loading

picnixz commented Mar 25, 2026 •

edited

Loading