#5529: backport new docs of import semantics written by Brett to 2.x.

Doc/glossary.rst

@@ -185,6 +185,11 @@ Glossary
       A module written in C or C++, using Python's C API to interact with the core and
       with user code.
 
+   finder
+      An object that tries to find the :term:`loader` for a module. It must
+      implement a method named :meth:`find_module`. See :pep:`302` for
+      details.
+
    function
       A series of statements which returns some value to a caller. It can also
       be passed zero or more arguments which may be used in the execution of
@@ -288,6 +293,10 @@ Glossary
       fraction.  Integer division can be forced by using the ``//`` operator
       instead of the ``/`` operator.  See also :term:`__future__`.
 
+   importer
+      An object that both finds and loads a module; both a
+      :term:`finder` and :term:`loader` object.
+
    interactive
       Python has an interactive interpreter which means you can enter
       statements and expressions at the interpreter prompt, immediately
@@ -368,6 +377,11 @@ Glossary
       clause is optional.  If omitted, all elements in ``range(256)`` are
       processed.
 
+   loader
+      An object that loads a module. It must define a method named
+      :meth:`load_module`. A loader is typically returned by a
+      :term:`finder`. See :pep:`302` for details.
+
    mapping
       A container object (such as :class:`dict`) which supports arbitrary key
       lookups using the special method :meth:`__getitem__`.

Doc/library/sys.rst

@@ -554,6 +554,22 @@ always available.
    characters are stored as UCS-2 or UCS-4.
 
 
+.. data:: meta_path
+
+    A list of :term:`finder` objects that have their :meth:`find_module`
+    methods called to see if one of the objects can find the module to be
+    imported. The :meth:`find_module` method is called at least with the
+    absolute name of the module being imported. If the module to be imported is
+    contained in package then the parent package's :attr:`__path__` attribute
+    is passed in as a second argument. The method returns :keyword:`None` if
+    the module cannot be found, else returns a :term:`loader`.
+
+    :data:`sys.meta_path` is searched before any implicit default finders or
+    :data:`sys.path`.
+
+    See :pep:`302` for the original specification.
+
+
 .. data:: modules
 
    .. index:: builtin: reload
@@ -590,6 +606,27 @@ always available.
       :data:`sys.path`.
 
 
+.. data:: path_hooks
+
+    A list of callables that take a path argument to try to create a
+    :term:`finder` for the path. If a finder can be created, it is to be
+    returned by the callable, else raise :exc:`ImportError`.
+
+    Originally specified in :pep:`302`.
+
+
+.. data:: path_importer_cache
+
+    A dictionary acting as a cache for :term:`finder` objects. The keys are
+    paths that have been passed to :data:`sys.path_hooks` and the values are
+    the finders that are found. If a path is a valid file system path but no
+    explicit finder is found on :data:`sys.path_hooks` then :keyword:`None` is
+    stored to represent the implicit default finder should be used. If the path
+    is not an existing path then :class:`imp.NullImporter` is set.
+
+    Originally specified in :pep:`302`.
+
+
 .. data:: platform
 
    This string contains a platform identifier that can be used to append