Document import's semantics for the language reference. This includes filling

in missing details for the sys module.

Doc/glossary.rst

@@ -182,7 +182,8 @@ Glossary
    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.
+      details and :class:`importlib.abc.Finder` for an
+      :term:`abstract base class`.
 
    floor division
       Mathematical division discarding any remainder.  The floor division
@@ -363,7 +364,8 @@ Glossary
    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.
+      :term:`finder`. See :pep:`302` for details and
+      :class:`importlib.abc.Loader` for an :term:`abstract base class`.
 
    mapping
       A container object (such as :class:`dict`) which supports arbitrary key

Doc/library/sys.rst

@@ -478,6 +478,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
 
    This is a dictionary that maps module names to modules which have already been
@@ -508,6 +524,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

Lib/importlib/NOTES

-to do
-/////
-
-* Make sure that there is documentation *somewhere* fully explaining the
-semantics of import that can be referenced from the package's documentation
-(even if it is in the package documentation itself, although it might be best
-in the language specification).