[docs] [issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

Sandro, import is a somewhat dark corner of Python that newcomers and even experienced people ofter trip over. So getting the text both correct and clear is worth some thought.

I just noticed that the text is only true for Python-coded modules and not for built-in modules. I discovered this by setting sys.path to {} and importing itertools. It works. It appears that Python first searches for builtins -- I created itertools.py and it did not mask the builtin. If there were a Lib/itertools.py which imported _itertools, it would have been masked. So it appears that the text should begin

"When a module named :mod:`spam` is imported, the interpreter first searches for a built-in module with that name. If not found, it then searches for a file ..."

I suggest changing
"This allows Python programs to modify or replace the module search path."
to
"After initialization, Python programs can modify sys.path."

and changing the followup

" Note that because the directory containing the script being run is on the search path, it is important that the script not have the same name as a standard module, or Python will attempt to load the script as a module when that module is imported.  This will generally be an error."

to something more like

"Because the directory containing the script being run is placed at the beginning of the search path, ahead of the standard library path, the script and other scripts in that directory should not have the same name as a standard library module unless one really intends for the script to be loaded in place of the standard library module."

or perhaps

"The directory containing the script being run is placed at the beginning of the search path, ahead of the standard library path. This means that scripts in that directory will be loaded instead of modules of the same name in the library directory. This is an error unless the replacement is intended."

I think the change to warn about all possibly conflicting scripts in the directory is needed because a common problem people have is more like

import random
a = random.choice('abc')

raising AttributeError ("O python-list, why???") because there is a forgotten random.py in the same directory.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11948>
_______________________________________