[Python-checkins] cpython (3.2): Issue #11948: clarify modules search path

[sandro.tosi]

http://hg.python.org/cpython/rev/6d663db63705
changeset:   74522:6d663db63705
branch:      3.2
parent:      74517:dfd74d752b0e
user:        Sandro Tosi <sandro.tosi at gmail.com>
date:        Thu Jan 19 11:29:26 2012 +0100
summary:
  Issue #11948: clarify modules search path

files:
  Doc/tutorial/modules.rst |  32 +++++++++++++--------------
  1 files changed, 15 insertions(+), 17 deletions(-)


diff --git a/Doc/tutorial/modules.rst b/Doc/tutorial/modules.rst
--- a/Doc/tutorial/modules.rst
+++ b/Doc/tutorial/modules.rst
@@ -159,24 +159,22 @@
 
 .. index:: triple: module; search; path
 
-When a module named :mod:`spam` is imported, the interpreter searches for a
-file named :file:`spam.py` in the directory containing the input script and
-then in the list of directories specified by the environment variable
-:envvar:`PYTHONPATH`.  This has the same syntax as the shell variable
-:envvar:`PATH`, that is, a list of directory names.  When :envvar:`PYTHONPATH`
-is not set, or when the file is not found there, the search continues in an
-installation-dependent default path; on Unix, this is usually
-:file:`.:/usr/local/lib/python`.
+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
+named :file:`spam.py` in a list of directories given by the variable
+:data:`sys.path`.  :data:`sys.path` is initialized from these locations:
 
-Actually, modules are searched in the list of directories given by the variable
-``sys.path`` which is initialized from the directory containing the input script
-(or the current directory), :envvar:`PYTHONPATH` and the installation- dependent
-default.  This allows Python programs that know what they're doing to modify or
-replace the module search path.  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.  See
-section :ref:`tut-standardmodules` for more information.
+* the directory containing the input script (or the current directory).
+* :envvar:`PYTHONPATH` (a list of directory names, with the same syntax as the
+  shell variable :envvar:`PATH`).
+* the installation-dependent default.
+
+After initialization, Python programs can modify :data:`sys.path`.  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.  See section
+:ref:`tut-standardmodules` for more information.
 
 .. %
     Do we need stuff on zip files etc. ? DUBOIS

-- 
Repository URL: http://hg.python.org/cpython