gh-95754: Better error when script shadows a standard library or third party module

Doc/whatsnew/3.13.rst

@@ -100,6 +100,40 @@ Improved Error Messages
  variables. See also :ref:`using-on-controlling-color`.
  (Contributed by Pablo Galindo Salgado in :gh:`112730`.)
 
+* A common mistake is to write a script with the same name as a
+ standard library module. When this results in errors, we now
+ display a more helpful error message:
+
+ .. code-block:: shell-session
+
+ $ python random.py
+ Traceback (most recent call last):
+ File "/home/random.py", line 1, in <module>
+ import random; print(random.randint(5))
+ ^^^^^^^^^^^^^
+ File "/home/random.py", line 1, in <module>
+ import random; print(random.randint(5))
+ ^^^^^^^^^^^^^^
+ AttributeError: module 'random' has no attribute 'randint' (consider renaming '/home/random.py' since it has the same name as the standard library module named 'random' and the import system gives it precedence)
+
+ Similarly, if a script has the same name as a third-party
+ module it attempts to import, and this results in errors,
+ we also display a more helpful error message:
+
+ .. code-block:: shell-session
+
+ $ python numpy.py
+ Traceback (most recent call last):
+ File "/home/numpy.py", line 1, in <module>
+ import numpy as np; np.array([1,2,3])
+ ^^^^^^^^^^^^^^^^^^
+ File "/home/numpy.py", line 1, in <module>
+ import numpy as np; np.array([1,2,3])
+ ^^^^^^^^
+ AttributeError: module 'numpy' has no attribute 'array' (consider renaming '/home/numpy.py' if it has the same name as a third-party module you intended to import)
+
+ (Contributed by Shantanu Jain in :gh:`95754`.)
+
 * When an incorrect keyword argument is passed to a function, the error message
  now potentially suggests the correct keyword argument.
  (Contributed by Pablo Galindo Salgado and Shantanu Jain in :gh:`107944`.)

Include/internal/pycore_global_strings.h

@@ -466,6 +466,7 @@ struct _Py_global_strings{
  STRUCT_FOR_ID(h)
  STRUCT_FOR_ID(handle)
  STRUCT_FOR_ID(handle_seq)
+ STRUCT_FOR_ID(has_location)
  STRUCT_FOR_ID(hash_name)
  STRUCT_FOR_ID(header)
  STRUCT_FOR_ID(headers)

Lib/test/test_import/__init__.py

@@ -790,6 +790,227 @@ def test_issue105979(self):
  self.assertIn("Frozen object named 'x' is invalid",
  str(cm.exception))
 
+ def test_script_shadowing_stdlib(self):
+ with os_helper.temp_dir() as tmp:
+ with open(os.path.join(tmp, "fractions.py"), "w", encoding='utf-8') as f:
+ f.write("import fractions\nfractions.Fraction")
+
+ expected_error = (
+ rb"AttributeError: module 'fractions' has no attribute 'Fraction' "
+ rb"\(consider renaming '.*fractions.py' since it has the "
+ rb"same name as the standard library module named 'fractions' "
+ rb"and the import system gives it precedence\)"
+ )
+
+ popen = script_helper.spawn_python(os.path.join(tmp, "fractions.py"), cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertRegex(stdout, expected_error)
+
+ popen = script_helper.spawn_python('-m', 'fractions', cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertRegex(stdout, expected_error)
+
+ popen = script_helper.spawn_python('-c', 'import fractions', cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertRegex(stdout, expected_error)
+
+ # and there's no error at all when using -P
+ popen = script_helper.spawn_python('-P', 'fractions.py', cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertEqual(stdout, b'')
+
+ tmp_child = os.path.join(tmp, "child")
+ os.mkdir(tmp_child)
+
+ # test the logic with different cwd
+ popen = script_helper.spawn_python(os.path.join(tmp, "fractions.py"), cwd=tmp_child)
+ stdout, stderr = popen.communicate()
+ self.assertRegex(stdout, expected_error)
+
+ popen = script_helper.spawn_python('-m', 'fractions', cwd=tmp_child)
+ stdout, stderr = popen.communicate()
+ self.assertEqual(stdout, b'') # no error
+
+ popen = script_helper.spawn_python('-c', 'import fractions', cwd=tmp_child)
+ stdout, stderr = popen.communicate()
+ self.assertEqual(stdout, b'') # no error
+
+ def test_package_shadowing_stdlib_module(self):
+ with os_helper.temp_dir() as tmp:
+ os.mkdir(os.path.join(tmp, "fractions"))
+ with open(os.path.join(tmp, "fractions", "__init__.py"), "w", encoding='utf-8') as f:
+ f.write("shadowing_module = True")
+ with open(os.path.join(tmp, "main.py"), "w", encoding='utf-8') as f:
+ f.write("""
+import fractions
+fractions.shadowing_module
+fractions.Fraction
+""")
+
+ expected_error = (
+ rb"AttributeError: module 'fractions' has no attribute 'Fraction' "
+ rb"\(consider renaming '.*fractions.__init__.py' since it has the "
+ rb"same name as the standard library module named 'fractions' "
+ rb"and the import system gives it precedence\)"
+ )
+
+ popen = script_helper.spawn_python(os.path.join(tmp, "main.py"), cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertRegex(stdout, expected_error)
+
+ popen = script_helper.spawn_python('-m', 'main', cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertRegex(stdout, expected_error)
+
+ # and there's no shadowing at all when using -P
+ popen = script_helper.spawn_python('-P', 'main.py', cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertRegex(stdout, b"module 'fractions' has no attribute 'shadowing_module'")
+
+ def test_script_shadowing_third_party(self):
+ with os_helper.temp_dir() as tmp:
+ with open(os.path.join(tmp, "numpy.py"), "w", encoding='utf-8') as f:
+ f.write("import numpy\nnumpy.array")
+
+ expected_error = (
+ rb"AttributeError: module 'numpy' has no attribute 'array' "
+ rb"\(consider renaming '.*numpy.py' if it has the "
+ rb"same name as a third-party module you intended to import\)\s+\Z"
+ )
+
+ popen = script_helper.spawn_python(os.path.join(tmp, "numpy.py"))
+ stdout, stderr = popen.communicate()
+ self.assertRegex(stdout, expected_error)
+
+ popen = script_helper.spawn_python('-m', 'numpy', cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertRegex(stdout, expected_error)
+
+ popen = script_helper.spawn_python('-c', 'import numpy', cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertRegex(stdout, expected_error)
+
+ def test_script_maybe_not_shadowing_third_party(self):
+ with os_helper.temp_dir() as tmp:
+ with open(os.path.join(tmp, "numpy.py"), "w", encoding='utf-8') as f:
+ f.write("this_script_does_not_attempt_to_import_numpy = True")
+
+ expected_error = (
+ rb"AttributeError: module 'numpy' has no attribute 'attr'\s+\Z"
+ )
+
+ popen = script_helper.spawn_python('-c', 'import numpy; numpy.attr', cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertRegex(stdout, expected_error)
+
+ def test_script_shadowing_stdlib_edge_cases(self):
+ with os_helper.temp_dir() as tmp:
+ with open(os.path.join(tmp, "fractions.py"), "w", encoding='utf-8') as f:
+ f.write("shadowing_module = True")
+ with open(os.path.join(tmp, "main.py"), "w", encoding='utf-8') as f:
+ f.write("""
+import fractions
+fractions.shadowing_module
+class substr(str):
+ __hash__ = None
+fractions.__name__ = substr('fractions')
+try:
+ fractions.Fraction
+except TypeError as e:
+ print(str(e))
+""")
+
+ popen = script_helper.spawn_python("main.py", cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertEqual(stdout.rstrip(), b"unhashable type: 'substr'")
+
+ with open(os.path.join(tmp, "main.py"), "w", encoding='utf-8') as f:
+ f.write("""
+import fractions
+fractions.shadowing_module
+
+import sys
+sys.stdlib_module_names = None
+try:
+ fractions.Fraction
+except AttributeError as e:
+ print(str(e))
+
+del sys.stdlib_module_names
+try:
+ fractions.Fraction
+except AttributeError as e:
+ print(str(e))
+
+sys.path = [0]
+try:
+ fractions.Fraction
+except AttributeError as e:
+ print(str(e))
+""")
+
+ popen = script_helper.spawn_python("main.py", cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertEqual(
+ stdout.splitlines(),
+ [
+ b"module 'fractions' has no attribute 'Fraction'",
+ b"module 'fractions' has no attribute 'Fraction'",
+ b"module 'fractions' has no attribute 'Fraction'",
+ ],
+ )
+
+ with open(os.path.join(tmp, "main.py"), "w", encoding='utf-8') as f:
+ f.write("""
+import fractions
+fractions.shadowing_module
+del fractions.__spec__.origin
+try:
+ fractions.Fraction
+except AttributeError as e:
+ print(str(e))
+
+fractions.__spec__.origin = 0
+try:
+ fractions.Fraction
+except AttributeError as e:
+ print(str(e))
+""")
+
+ popen = script_helper.spawn_python("main.py", cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertEqual(
+ stdout.splitlines(),
+ [
+ b"module 'fractions' has no attribute 'Fraction'",
+ b"module 'fractions' has no attribute 'Fraction'"
+ ],
+ )
+
+ def test_script_shadowing_stdlib_sys_path_modification(self):
+ with os_helper.temp_dir() as tmp:
+ with open(os.path.join(tmp, "fractions.py"), "w", encoding='utf-8') as f:
+ f.write("shadowing_module = True")
+
+ expected_error = (
+ rb"AttributeError: module 'fractions' has no attribute 'Fraction' "
+ rb"\(consider renaming '.*fractions.py' since it has the "
+ rb"same name as the standard library module named 'fractions' "
+ rb"and the import system gives it precedence\)"
+ )
+
+ with open(os.path.join(tmp, "main.py"), "w", encoding='utf-8') as f:
+ f.write("""
+import sys
+sys.path.insert(0, "this_folder_does_not_exist")
+import fractions
+fractions.Fraction
+""")
+
+ popen = script_helper.spawn_python("main.py", cwd=tmp)
+ stdout, stderr = popen.communicate()
+ self.assertRegex(stdout, expected_error)
+
 
 @skip_if_dont_write_bytecode
 class FilePermissionTests(unittest.TestCase):

Misc/NEWS.d/next/Core and Builtins/2024-01-07-03-38-34.gh-issue-95754.aPjEBG.rst

@@ -0,0 +1,4 @@
+Improve the error message when a script shadowing a module from the standard
+library causes :exc:`AttributeError` to be raised. Similarly, improve the error
+message when a script shadowing a third party module attempts to access an
+attribute from that third party module while still initialising.