gh-95754: Better error for shadowing stdlib module

[hauntsaninja]

This is a very common mistake for beginners. This PR tries to detect the most common case: where a file in the current directory ends up on sys.path and shadows a standard library module. (My previous PR #112577 was only marginally helpful and wouldn't help with many such errors)

The first commit in this PR is just refactoring. I'm a little nervous about running this much Python and the potential for recursion in import machinery. It's also easy to do evil things that will make bad things happen. Please let me know if you have suggestions (should I do the path munging in C?) for additional test cases or sanity checks!

• Issue: Add more specific error message when file has same name as an imported module #95754

---

📚 Documentation preview 📚: https://cpython-previews--113769.org.readthedocs.build/

[bedevere-bot]

🤖 New build scheduled with the buildbot fleet by @hauntsaninja for commit d4111e5 🤖

If you want to schedule another build, you need to add the 🔨 test-with-refleak-buildbots label again.

[hauntsaninja]

Oh actually looks like I can use stdlib_module_names.h do get sys.stdlib_module_names in C. And I can of course do the path munging in C as well.

[hauntsaninja]

Should I disable this if sys.flags.safe_path? Also this won't currently work for python nested_folder/script.py where nested_folder contains the shadowing module... I could base this around Py_GetPath()[0] instead.

Oh hmm, Py_GetPath is deprecated, so I guess I have to get sys.path[0] (and assume it hasn't changed). This means we have to call back into Python and risk the bad recursion again. See the code from before 7f24b99 , curious if people have suggestions that are more bulletproof than module name checks.

[pablogsal]

See the code from before 7f24b99 , curious if people have suggestions that are more bulletproof than module name checks.

I think sacrificing a bit of accuracy to avoid bad recursion errors and nasty conditions is very much worth it so my advice is to target maintainability without making the errors plainly worng. In other words: false negatives are a good tradeoff for maintenance.

[erlend-aasland]

Does this need to be a relative include? (I don't like relative includes.)