summaryrefslogtreecommitdiffstats
path: root/Doc/library/importlib.rst
diff options
context:
space:
mode:
authorBrett Cannon <bcannon@gmail.com>2009-01-20 02:21:27 (GMT)
committerBrett Cannon <bcannon@gmail.com>2009-01-20 02:21:27 (GMT)
commitafccd63ac9541630953cd4e59a421696d3869311 (patch)
tree35229a6a1a7b3836c50f660fed3df2a8f40e14e5 /Doc/library/importlib.rst
parentdf50106408d525a8e7022b6545ecbd0c13ce8740 (diff)
downloadcpython-afccd63ac9541630953cd4e59a421696d3869311.zip
cpython-afccd63ac9541630953cd4e59a421696d3869311.tar.gz
cpython-afccd63ac9541630953cd4e59a421696d3869311.tar.bz2
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.
Diffstat (limited to 'Doc/library/importlib.rst')
-rw-r--r--Doc/library/importlib.rst78
1 files changed, 78 insertions, 0 deletions
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
new file mode 100644
index 0000000..d247f2b
--- /dev/null
+++ b/Doc/library/importlib.rst
@@ -0,0 +1,78 @@
+: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.