[Python-checkins] r69662 - in python/branches/py3k: Doc/library/importlib.rst Lib/importlib/NOTES

[brett.cannon]

Author: brett.cannon
Date: Mon Feb 16 05:18:01 2009
New Revision: 69662

Log:
Document importlib.machinery.PathFinder.

Modified:
   python/branches/py3k/Doc/library/importlib.rst
   python/branches/py3k/Lib/importlib/NOTES

Modified: python/branches/py3k/Doc/library/importlib.rst
==============================================================================
--- python/branches/py3k/Doc/library/importlib.rst	(original)
+++ python/branches/py3k/Doc/library/importlib.rst	Mon Feb 16 05:18:01 2009
@@ -18,12 +18,12 @@
 :func:`__import__` function) in Python source code. This provides an
 implementaiton of :keyword:`import` which is portable to any Python
 interpreter. This also provides a reference implementation which is easier to
-read than one in a programming language other than Python.
+comprehend than one in a programming language other than Python.
 
 Two, the components to implement :keyword:`import` can be exposed in this
 package, making it easier for users to create their own custom objects (known
-generically as importers) to participate in the import process. Details on
-providing custom importers can be found in :pep:`302`.
+generically as an :term:`importer`) to participate in the import process.
+Details on providing custom importers can be found in :pep:`302`.
 
 .. seealso::
 
@@ -126,3 +126,28 @@
 
         Class method that allows this class to be a :term:`loader` for frozen
         modules.
+
+
+.. class:: PathFinder
+
+    :term:`Finder` for :data:`sys.path`.
+
+    This class does not perfectly mirror the semantics of :keyword:`import` in
+    terms of :data:`sys.path`. No implicit path hooks are assumed for
+    simplification of the class and its semantics.
+
+    Only class method are defined by this class to alleviate the need for
+    instantiation.
+
+    .. classmethod:: find_module(fullname, path=None)
+
+        Class method that attempts to find a :term:`loader` for the module
+        specified by *fullname* either on :data:`sys.path` or, if defined, on
+        *path*. For each path entry that is searched,
+        :data:`sys.path_importer_cache` is checked. If an non-false object is
+        found then it is used as the :term:`finder` to query for the module
+        being searched for. For no entry is found in
+        :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is
+        searched for a finder for the path entry and, if found, is stored in
+        :data:`sys.path_importer_cache` along with being queried about the
+        module.

Modified: python/branches/py3k/Lib/importlib/NOTES
==============================================================================
--- python/branches/py3k/Lib/importlib/NOTES	(original)
+++ python/branches/py3k/Lib/importlib/NOTES	Mon Feb 16 05:18:01 2009
@@ -52,7 +52,6 @@
   + machinery
 
       - (?) Chained path hook/finder
-      - (?) FileFinder
       - Extensions importers
 
           * ExtensionFinder
@@ -65,6 +64,11 @@
 
       - PathFinder
 
+* 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).
+
 * Write benchmark suite.
 
 * OPTIMIZE!