1 

     2 :mod:`imputil` --- Import utilities

     3 =====================================================

     4 

     5 .. module:: imputil

     6    :synopsis: Manage and augment the import process.

     7    :deprecated:

     8 

     9 .. deprecated:: 2.6

    10    The :mod:`imputil` module has been removed in Python 3.0.

    11 

    12 

    13 .. index:: statement: import

    14 

    15 This module provides a very handy and useful mechanism for custom

    16 :keyword:`import` hooks. Compared to the older :mod:`ihooks` module,

    17 :mod:`imputil` takes a dramatically simpler and more straight-forward

    18 approach to custom :keyword:`import` functions.

    19 

    20 

    21 .. class:: ImportManager([fs_imp])

    22 

    23    Manage the import process.

    24 

    25    .. method:: ImportManager.install([namespace])

    26 

    27       Install this ImportManager into the specified namespace.

    28 

    29    .. method:: ImportManager.uninstall()

    30 

    31       Restore the previous import mechanism.

    32 

    33    .. method:: ImportManager.add_suffix(suffix, importFunc)

    34 

    35       Undocumented.

    36 

    37 

    38 .. class:: Importer()

    39 

    40    Base class for replacing standard import functions.

    41 

    42    .. method:: Importer.import_top(name)

    43 

    44       Import a top-level module.

    45 

    46    .. method:: Importer.get_code(parent, modname, fqname)

    47 

    48       Find and retrieve the code for the given module.

    49 

    50       *parent* specifies a parent module to define a context for importing.

    51       It may be ``None``, indicating no particular context for the search.

    52 

    53       *modname* specifies a single module (not dotted) within the parent.

    54 

    55       *fqname* specifies the fully-qualified module name. This is a

    56       (potentially) dotted name from the "root" of the module namespace

    57       down to the modname.

    58 

    59       If there is no parent, then modname==fqname.

    60 

    61       This method should return ``None``, or a 3-tuple.

    62 

    63         * If the module was not found, then ``None`` should be returned.

    64 

    65         * The first item of the 2- or 3-tuple should be the integer 0 or 1,

    66           specifying whether the module that was found is a package or not.

    67 

    68         * The second item is the code object for the module (it will be

    69           executed within the new module's namespace). This item can also

    70           be a fully-loaded module object (e.g. loaded from a shared lib).

    71 

    72         * The third item is a dictionary of name/value pairs that will be

    73           inserted into new module before the code object is executed. This

    74           is provided in case the module's code expects certain values (such

    75           as where the module was found). When the second item is a module

    76           object, then these names/values will be inserted *after* the module

    77           has been loaded/initialized.

    78 

    79 

    80 .. class:: BuiltinImporter()

    81 

    82    Emulate the import mechanism for builtin and frozen modules.  This is a

    83    sub-class of the :class:`Importer` class.

    84 

    85    .. method:: BuiltinImporter.get_code(parent, modname, fqname)

    86 

    87       Undocumented.

    88 

    89 .. function:: py_suffix_importer(filename, finfo, fqname)

    90 

    91    Undocumented.

    92 

    93 .. class:: DynLoadSuffixImporter([desc])

    94 

    95    Undocumented.

    96 

    97    .. method:: DynLoadSuffixImporter.import_file(filename, finfo, fqname)

    98 

    99       Undocumented.

   100 

   101 .. _examples-imputil:

   102 

   103 Examples

   104 --------

   105 

   106 This is a re-implementation of hierarchical module import.

   107 

   108 This code is intended to be read, not executed.  However, it does work

   109 -- all you need to do to enable it is "import knee".

   110 

   111 (The name is a pun on the clunkier predecessor of this module, "ni".)

   112 

   113 ::

   114 

   115    import sys, imp, __builtin__

   116 

   117    # Replacement for __import__()

   118    def import_hook(name, globals=None, locals=None, fromlist=None):

   119        parent = determine_parent(globals)

   120        q, tail = find_head_package(parent, name)

   121        m = load_tail(q, tail)

   122        if not fromlist:

   123            return q

   124        if hasattr(m, "__path__"):

   125            ensure_fromlist(m, fromlist)

   126        return m

   127 

   128    def determine_parent(globals):

   129        if not globals or  not globals.has_key("__name__"):

   130            return None

   131        pname = globals['__name__']

   132        if globals.has_key("__path__"):

   133            parent = sys.modules[pname]

   134            assert globals is parent.__dict__

   135            return parent

   136        if '.' in pname:

   137            i = pname.rfind('.')

   138            pname = pname[:i]

   139            parent = sys.modules[pname]

   140            assert parent.__name__ == pname

   141            return parent

   142        return None

   143 

   144    def find_head_package(parent, name):

   145        if '.' in name:

   146            i = name.find('.')

   147            head = name[:i]

   148            tail = name[i+1:]

   149        else:

   150            head = name

   151            tail = ""

   152        if parent:

   153            qname = "%s.%s" % (parent.__name__, head)

   154        else:

   155            qname = head

   156        q = import_module(head, qname, parent)

   157        if q: return q, tail

   158        if parent:

   159            qname = head

   160            parent = None

   161            q = import_module(head, qname, parent)

   162            if q: return q, tail

   163        raise ImportError, "No module named " + qname

   164 

   165    def load_tail(q, tail):

   166        m = q

   167        while tail:

   168            i = tail.find('.')

   169            if i < 0: i = len(tail)

   170            head, tail = tail[:i], tail[i+1:]

   171            mname = "%s.%s" % (m.__name__, head)

   172            m = import_module(head, mname, m)

   173            if not m:

   174                raise ImportError, "No module named " + mname

   175        return m

   176 

   177    def ensure_fromlist(m, fromlist, recursive=0):

   178        for sub in fromlist:

   179            if sub == "*":

   180                if not recursive:

   181                    try:

   182                        all = m.__all__

   183                    except AttributeError:

   184                        pass

   185                    else:

   186                        ensure_fromlist(m, all, 1)

   187                continue

   188            if sub != "*" and not hasattr(m, sub):

   189                subname = "%s.%s" % (m.__name__, sub)

   190                submod = import_module(sub, subname, m)

   191                if not submod:

   192                    raise ImportError, "No module named " + subname

   193 

   194    def import_module(partname, fqname, parent):

   195        try:

   196            return sys.modules[fqname]

   197        except KeyError:

   198            pass

   199        try:

   200            fp, pathname, stuff = imp.find_module(partname,

   201                                                  parent and parent.__path__)

   202        except ImportError:

   203            return None

   204        try:

   205            m = imp.load_module(fqname, fp, pathname, stuff)

   206        finally:

   207            if fp: fp.close()

   208        if parent:

   209            setattr(parent, partname, m)

   210        return m

   211 

   212 

   213    # Replacement for reload()

   214    def reload_hook(module):

   215        name = module.__name__

   216        if '.' not in name:

   217            return import_module(name, name, None)

   218        i = name.rfind('.')

   219        pname = name[:i]

   220        parent = sys.modules[pname]

   221        return import_module(name[i+1:], name, parent)

   222 

   223 

   224    # Save the original hooks

   225    original_import = __builtin__.__import__

   226    original_reload = __builtin__.reload

   227 

   228    # Now install our hooks

   229    __builtin__.__import__ = import_hook

   230    __builtin__.reload = reload_hook

   231 

   232 .. index::

   233    module: knee

   234 

   235 Also see the :mod:`importers` module (which can be found

   236 in :file:`Demo/imputil/` in the Python source distribution) for additional

   237 examples.

   238