From afccd63ac9541630953cd4e59a421696d3869311 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 20 Jan 2009 02:21:27 +0000 Subject: [PATCH] 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 | 78 +++++++++++++++++++++++++++++++++++++++ Doc/library/modules.rst | 1 + Lib/importlib/NOTES | 13 ++----- Lib/importlib/__init__.py | 47 ++++++++++++----------- Misc/NEWS | 2 + 5 files changed, 111 insertions(+), 30 deletions(-) create mode 100644 Doc/library/importlib.rst diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst new file mode 100644 index 00000000000..d247f2b8729 --- /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 +.. sectionauthor:: Brett Cannon + +.. 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 `__ + 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. diff --git a/Doc/library/modules.rst b/Doc/library/modules.rst index 2590a3a678e..24307d5460c 100644 --- a/Doc/library/modules.rst +++ b/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 diff --git a/Lib/importlib/NOTES b/Lib/importlib/NOTES index 95d002b56f6..e0ca28cdaa5 100644 --- a/Lib/importlib/NOTES +++ b/Lib/importlib/NOTES @@ -1,12 +1,11 @@ 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__ diff --git a/Lib/importlib/__init__.py b/Lib/importlib/__init__.py index b59c9c4656c..8d11502d56e 100644 --- a/Lib/importlib/__init__.py +++ b/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 * diff --git a/Misc/NEWS b/Misc/NEWS index 50e47028575..1050ae422dc 100644 --- a/Misc/NEWS +++ b/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.