Document the (very small) public API for importlib. As time goes on and some

key refactorings occur more of the API will be exposed and documented.

Doc/library/importlib.rst

+:mod:`importlib` -- An implementation of :keyword:`import`
+==========================================================
+
+.. module:: importlib
+   :synopsis: An implementation of the import machinery.
+
+.. moduleauthor:: Brett Cannon <brett@python.org>
+.. sectionauthor:: Brett Cannon <brett@python.org>
+
+.. versionadded:: 3.1
+
+
+Introduction
+------------
+
+The purpose of the :mod:`importlib` package is two-fold. One is to provide an
+implementation of the :keyword:`import` statement (and thus, by extension, the
+: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.
+
+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`.
+
+.. seealso::
+
+    :ref:`import`
+        The language reference for the :keyword:`import` statement.
+
+    `Packages specification <http://www.python.org/doc/essays/packages.html>`__
+        Original specification of packages. Some semantics have changed since
+        the writing of this document (e.g. redirecting based on :keyword:`None`
+        in :data:`sys.modules`).
+
+    The :func:`.__import__` function
+        The built-in function for which the :keyword:`import` statement is
+        syntactic sugar for.
+
+    :pep:`235`
+        Import on Case-Insensitive Platforms
+
+    :pep:`263`
+        Defining Python Source Code Encodings
+
+    :pep:`302`
+        New Import Hooks.
+
+    :pep:`328`
+        Imports: Multi-Line and Absolute/Relative
+
+    :pep:`366`
+        Main module explicit relative imports
+
+    :pep:`3128`
+        Using UTF-8 as the Default Source Encoding
+
+
+Functions
+---------
+
+.. function:: __import__(name, globals={}, locals={}, fromlist=\[\], level=0)
+
+    An implementation of the built-in :func:`__import__` function. See the
+    built-in function's documentation for usage instructions.
+
+.. function:: import_module(name, package=None)
+
+    Import a module. The ``name`` argument specifies what module to
+    import in absolute or relative terms
+    (e.g. either ``pkg.mod`` or ``..mod``). If the name is
+    specified in relative terms, then the ``package`` argument must be
+    specified to the package which is to act as the anchor for resolving the
+    package name (e.g. ``import_module('..mod', 'pkg.subpkg')`` will import
+    ``pkg.mod``). The specified module will be inserted into
+    :data:`sys.modules` and returned.

Doc/library/modules.rst

@@ -18,3 +18,4 @@ The full list of modules described in this chapter is:
    pkgutil.rst
    modulefinder.rst
    runpy.rst
+   importlib.rst

Lib/importlib/NOTES

 to do
 /////
 
-* Write importlib.__import__
+* Expose resolve_name().
 
-* Document
-    + Package.
+* Backport to Python 2.7.
     + import_module
-    + __import__
+    + resolve_name
 
 * Create reasonable base tests that all finders and loaders must pass so
   that various implementations can just subclass as needed.
@@ -42,7 +41,7 @@ to do
     - Absolute name from sys.path.
     - Relative name from sys.path.
 
-* Public API (w/ docs!)
+* Public API to expose (w/ docs!)
   + abc
       - Finder
         * find_module
@@ -72,9 +71,5 @@ to do
       - Source/bytecode importers
           * SourceFinder
           * (?) Loader
-  + __init__
-      - __import__
-      - import_module (backport to 2.7)
-      - resolve_name (backport to 2.7)
 
 * Bootstrap importlib as implementation of builtins.__import__

Lib/importlib/__init__.py

@@ -79,27 +79,6 @@ def _r_long(int_bytes):
     return x
 
 
-def import_module(name, package=None):
-    """Import a module.
-
-    The 'package' argument is used to resolve relative import names. Typically
-    this is the __package__ attribute of the module making the function call.
-
-    """
-    if name.startswith('.'):
-        if not package:
-            raise TypeError("relative imports require the 'package' argument")
-        level = 0
-        for character in name:
-            if character != '.':
-                break
-            level += 1
-        name = Import._resolve_name(name[level:], package, level)
-    __import__(name)
-    return sys.modules[name]
-
-
-
 # Required built-in modules.
 try:
     import posix as _os
@@ -130,4 +109,30 @@ _bootstrap._case_ok = _case_ok
 marshal._w_long = _w_long
 marshal._r_long = _r_long
 
+
+__import__ = _bootstrap.Import().__call__
+
+
+def import_module(name, package=None):
+    """Import a module.
+
+    The 'package' argument is required when performing a relative import. It
+    specifies the package to use as the anchor point from which to resolve the
+    relative import to an absolute import.
+
+    """
+    if name.startswith('.'):
+        if not package:
+            raise TypeError("relative imports require the 'package' argument")
+        level = 0
+        for character in name:
+            if character != '.':
+                break
+            level += 1
+        name = Import._resolve_name(name[level:], package, level)
+    __import__(name)
+    return sys.modules[name]
+
+
+
 from ._bootstrap import *

Misc/NEWS

@@ -134,6 +134,8 @@ Core and Builtins
 Library
 -------
 
+- Add the importlib package.
+
 - Issue #4301: Patch the logging module to add processName support, remove
   _check_logger_class from multiprocessing.