GH-145006: add ModuleNotFoundError hints when a module for a different ABI exists

Signed-off-by: Filipe Laíns <lains@riseup.net>

Author: FFY00

Lib/test/test_traceback.py

@@ -13,6 +13,7 @@
 import tempfile
 import random
 import string
+import importlib.machinery
 from test import support
 import shutil
 from test.support import (Error, captured_output, cpython_only, ALWAYS_EQ,
@@ -5194,6 +5195,16 @@ def test_windows_only_module_error(self):
         else:
             self.fail("ModuleNotFoundError was not raised")
 
+    def test_find_incompatible_extension_modules(self):
+        """_find_incompatible_extension_modules assumes the last extension in
+        importlib.machinery.EXTENSION_SUFFIXES (defined in Python/dynload_*.c)
+        is untagged (eg. .so, .pyd).
+
+        This test exists to make sure that assumption is correct.
+        """
+        if importlib.machinery.EXTENSION_SUFFIXES:
+            self.assertEqual(len(importlib.machinery.EXTENSION_SUFFIXES[-1].split('.')), 2)
+
 
 class TestColorizedTraceback(unittest.TestCase):
     maxDiff = None

Lib/traceback.py

@@ -3,6 +3,7 @@
 import collections.abc
 import itertools
 import linecache
+import os
 import sys
 import textwrap
 import types
@@ -1129,6 +1130,11 @@ def __init__(self, exc_type, exc_value, exc_traceback, *, limit=None,
                 self._str += (". Site initialization is disabled, did you forget to "
                     + "add the site-packages directory to sys.path "
                     + "or to enable your virtual environment?")
+            elif abi_tag := _find_incompatible_extension_module(module_name):
+                self._str += (
+                    ". Although a module with this name was found for a "
+                    f"different Python version ({abi_tag})."
+                )
             else:
                 suggestion = _compute_suggestion_error(exc_value, exc_traceback, module_name)
                 if suggestion:
@@ -1880,3 +1886,28 @@ def _levenshtein_distance(a, b, max_cost):
             # Everything in this row is too big, so bail early.
             return max_cost + 1
     return result
+
+
+def _find_incompatible_extension_module(module_name):
+    import importlib.machinery
+    import importlib.resources.readers
+
+    if not module_name or not importlib.machinery.EXTENSION_SUFFIXES:
+        return
+
+    # We assume the last extension is untagged (eg. .so, .pyd)!
+    # tests.test_traceback.MiscTest.test_find_incompatible_extension_modules
+    # tests that assumption.
+    untagged_suffix = importlib.machinery.EXTENSION_SUFFIXES[-1]
+
+    parent, _, child = module_name.rpartition('.')
+    if parent:
+        traversable = importlib.resources.files(parent)
+    else:
+        traversable = importlib.resources.readers.MultiplexedPath(
+            *filter(os.path.isdir, sys.path)
+        )
+
+    for entry in traversable.iterdir():
+        if entry.name.startswith(child + '.') and entry.name.endswith(untagged_suffix):
+            return entry.name.removeprefix(child + '.').removesuffix(untagged_suffix)

Misc/NEWS.d/next/Library/2026-02-19-17-50-47.gh-issue-145006.9gqA0Q.rst

@@ -0,0 +1,2 @@
+Add :exc:`ModuleNotFoundError` hints when a module for a different ABI
+exists.