A few more docstring/API cleanups for importlib.

4 files changed, 55 insertions, 53 deletions

diff --git a/Lib/importlib/__init__.py b/Lib/importlib/__init__.py
index 7474350..37577ff 100644
--- a/Lib/importlib/__init__.py
+++ b/Lib/importlib/__init__.py
@@ -26,20 +26,6 @@ import os
 import re
 import tokenize
 
-# XXX Temporary functions that should eventually be removed.
-def _set__import__():
-    """Set __import__ to an instance of Import."""
-    global original__import__
-    original__import__ = __import__
-    __builtins__['__import__'] = _bootstrap._import
-
-
-def _reset__import__():
-    """Set __import__ back to the original implementation (assumes
-    _set__import__ was called previously)."""
-    __builtins__['__import__'] = original__import__
-
-
 # Bootstrap help #####################################################
 
 def _case_ok(directory, check):
@@ -116,7 +102,7 @@ marshal._r_long = _r_long
 
 # Public API #########################################################
 
-__import__ = _bootstrap._import
+from ._bootstrap import __import__
 
 
 def import_module(name, package=None):
diff --git a/Lib/importlib/_bootstrap.py b/Lib/importlib/_bootstrap.py
index cae12ed..e94c1d2 100644
--- a/Lib/importlib/_bootstrap.py
+++ b/Lib/importlib/_bootstrap.py
@@ -183,16 +183,16 @@ def _suffix_list(suffix_type):
 
 class BuiltinImporter:
 
-    """Meta path loader for built-in modules.
+    """Meta path import for built-in modules.
 
-    All methods are either class or static methods, allowing direct use of the
-    class.
+    All methods are either class or static methods to avoid the need to
+    instantiate the class.
 
     """
 
     @classmethod
     def find_module(cls, fullname, path=None):
-        """Try to find the built-in module.
+        """Find the built-in module.
 
         If 'path' is ever specified then the search is considered a failure.
 
@@ -219,10 +219,10 @@ class BuiltinImporter:
 
 class FrozenImporter:
 
-    """Meta path class for importing frozen modules.
+    """Meta path import for frozen modules.
 
-    All methods are either class or static method to allow direct use of the
-    class.
+    All methods are either class or static methods to avoid the need to
+    instantiate the class.
 
     """
 
@@ -249,10 +249,13 @@ class FrozenImporter:
 
 class PyLoader:
 
-    """Loader base class for Python source.
+    """Loader base class for Python source code.
 
-    Requires implementing the optional PEP 302 protocols as well as
-    source_path.
+    Subclasses need to implement the methods:
+
+    - source_path
+    - get_data
+    - is_package
 
     """
 
@@ -595,7 +598,8 @@ class PathFinder:
 
     @classmethod
     def find_module(cls, fullname, path=None):
-        """Find the module on sys.path or 'path'."""
+        """Find the module on sys.path or 'path' based on sys.path_hooks and
+        sys.path_importer_cache."""
         if not path:
             path = sys.path
         for entry in path:
@@ -857,7 +861,7 @@ def _gcd_import(name, package=None, level=0):
         return module
 
 
-def _import(name, globals={}, locals={}, fromlist=[], level=0):
+def __import__(name, globals={}, locals={}, fromlist=[], level=0):
     """Import a module.
 
     The 'globals' argument is used to infer where the import is occuring from
diff --git a/Lib/importlib/abc.py b/Lib/importlib/abc.py
index 2ecb821..6b00569 100644
--- a/Lib/importlib/abc.py
+++ b/Lib/importlib/abc.py
@@ -7,13 +7,11 @@ import types
 
 class Loader(metaclass=abc.ABCMeta):
 
-    """Abstract base class for import loaders.
-
-    See PEP 302 for details.
-
-    """
+    """Abstract base class for import loaders."""
 
+    @abc.abstractmethod
     def load_module(self, fullname:str) -> types.ModuleType:
+        """Abstract method which when implemented should load a module."""
         raise NotImplementedError
 
 Loader.register(machinery.BuiltinImporter)
@@ -22,14 +20,11 @@ Loader.register(machinery.FrozenImporter)
 
 class Finder(metaclass=abc.ABCMeta):
 
-    """Abstract base class for import finders.
-
-    See PEP 302 for details.
-
-    """
+    """Abstract base class for import finders."""
 
     @abc.abstractmethod
     def find_module(self, fullname:str, path:[str]=None) -> Loader:
+        """Abstract method which when implemented should find a module."""
         raise NotImplementedError
 
 Finder.register(machinery.BuiltinImporter)
@@ -37,16 +32,10 @@ Finder.register(machinery.FrozenImporter)
 Finder.register(machinery.PathFinder)
 
 
-class Importer(Finder, Loader):
-
-    """Abstract base class for importers."""
-
-
-
 class ResourceLoader(Loader):
 
-    """Abstract base class for loaders which can return data from the back-end
-    storage.
+    """Abstract base class for loaders which can return data from their
+    back-end storage.
 
     This ABC represents one of the optional protocols specified by PEP 302.
 
@@ -54,12 +43,15 @@ class ResourceLoader(Loader):
 
     @abc.abstractmethod
     def get_data(self, path:str) -> bytes:
+        """Abstract method which when implemented should return the bytes for
+        the specified path."""
         raise NotImplementedError
 
 
 class InspectLoader(Loader):
 
-    """Abstract base class for loaders which supports introspection.
+    """Abstract base class for loaders which support inspection about the
+    modules they can load.
 
     This ABC represents one of the optional protocols specified by PEP 302.
 
@@ -67,44 +59,64 @@ class InspectLoader(Loader):
 
     @abc.abstractmethod
     def is_package(self, fullname:str) -> bool:
+        """Abstract method which when implemented should return whether the
+        module is a package."""
         return NotImplementedError
 
     @abc.abstractmethod
     def get_code(self, fullname:str) -> types.CodeType:
+        """Abstract method which when implemented should return the code object
+        for the module"""
         return NotImplementedError
 
     @abc.abstractmethod
     def get_source(self, fullname:str) -> str:
+        """Abstract method which should return the source code for the
+        module."""
         return NotImplementedError
 
 
 class PyLoader(_bootstrap.PyLoader, InspectLoader):
 
-    """Abstract base class that implements the core parts needed to load Python
-    source code."""
+    """Abstract base class to assist in loading source code by requiring only
+    back-end storage methods to be implemented.
 
-    # load_module and get_code are implemented.
+    The methods get_code, get_source, and load_module are implemented for the
+    user.
+
+    """
 
     @abc.abstractmethod
     def source_path(self, fullname:str) -> object:
+        """Abstract method which when implemented should return the path to the
+        sourced code for the module."""
         raise NotImplementedError
 
 
 class PyPycLoader(_bootstrap.PyPycLoader, PyLoader):
 
-    """Abstract base class that implements the core parts needed to load Python
-    source and bytecode."""
+    """Abstract base class to assist in loading source and bytecode by
+    requiring only back-end storage methods to be implemented.
+
+    The methods get_code, get_source, and load_module are implemented for the
+    user.
 
-    # Implements load_module and get_code.
+    """
 
     @abc.abstractmethod
     def source_mtime(self, fullname:str) -> int:
+        """Abstract method which when implemented should return the
+        modification time for the source of the module."""
         raise NotImplementedError
 
     @abc.abstractmethod
     def bytecode_path(self, fullname:str) -> object:
+        """Abstract method which when implemented should return the path to the
+        bytecode for the module."""
         raise NotImplementedError
 
     @abc.abstractmethod
     def write_bytecode(self, fullname:str, bytecode:bytes):
+        """Abstract method which when implemented should attempt to write the
+        bytecode for the module."""
         raise NotImplementedError
diff --git a/Lib/importlib/test/import_/util.py b/Lib/importlib/test/import_/util.py
index 1a74c38..5a1b727 100644
--- a/Lib/importlib/test/import_/util.py
+++ b/Lib/importlib/test/import_/util.py
@@ -10,7 +10,7 @@ def import_(*args, **kwargs):
     if using___import__:
         return __import__(*args, **kwargs)
     else:
-        return importlib._bootstrap._import(*args, **kwargs)
+        return importlib._bootstrap.__import__(*args, **kwargs)
 
 
 def importlib_only(fxn):