Table of Contents

Module: imports ./src/peak/util/imports.py

Tools for doing dynamic imports

Imported modules   
import __main__
from peak.util.EigenData import AlreadyRead
from sys import modules
from types import StringTypes, ModuleType
Functions   
_loadAndRunHooks
_setModuleHook
getModuleHooks
importObject
importSequence
importString
importSuite
joinPath
lazyModule
whenImported
  _loadAndRunHooks 
_loadAndRunHooks ( module )

Load an unactivated "lazy" module object

  _setModuleHook 
_setModuleHook ( moduleName,  hook )

  getModuleHooks 
getModuleHooks ( moduleName )

Get list of hooks for 'moduleName'; error if module already loaded

Exceptions   
AlreadyRead( "Module already imported", moduleName )
  importObject 
importObject ( spec,  globalDict=defaultGlobalDict )

Convert a possible string specifier to an object

If spec is a string or unicode object, import it using importString(), otherwise return it as-is.

  importSequence 
importSequence ( specs,  globalDict=defaultGlobalDict )

Convert a string or list specifier to a list of objects.

If specs is a string or unicode object, treat it as a comma-separated list of import specifications, and return a list of the imported objects.

If the result is not a string but is iterable, return a list with any string/unicode items replaced with their corresponding imports.

  importString 
importString ( name,  globalDict=defaultGlobalDict )

Import an item specified by a string

Example Usage:

        attribute1 = importString('some.module:attribute1')
        attribute2 = importString('other.module:nested.attribute2')

importString imports an object from a module, according to an import specification string: a dot-delimited path to an object in the Python package namespace. For example, the string "some.module.attribute" is equivalent to the result of from some.module import attribute.

For readability of import strings, it's sometimes helpful to use a : to separate a module name from items it contains. It's optional, though, as importString will convert the ': to a .' internally anyway.

  importSuite 
importSuite ( specs,  globalDict=defaultGlobalDict )

Create a test suite from import specs

  joinPath 
joinPath ( modname,  relativePath )

Adjust a module name by a '/'-separated, relative or absolute path

  lazyModule 
lazyModule ( modname,  relativePath=None )

Return module modname, but with its contents loaded "on demand"

This function returns 'sys.modules[modname]', if present. Otherwise it creates a LazyModule object for the specified module, caches it in sys.modules, and returns it.

LazyModule is a subclass of the standard Python module type, that remains empty until an attempt is made to access one of its attributes. At that moment, the module is loaded into memory, and any hooks that were defined via whenImported() are invoked.

Note that calling lazyModule with the name of a non-existent or unimportable module will delay the ImportError until the moment access is attempted. The ImportError will occur every time an attribute access is attempted, until the problem is corrected.

This function also takes an optional second parameter, relativePath, which will be interpreted as a '/'-separated path string relative to modname. If a relativePath is supplied, the module found by traversing the path will be loaded instead of modname. In the path, '. refers to the current module, and ..' to the current module's parent. For example:

        fooBaz = lazyModule('foo.bar','../baz')

will return the module foo.baz. The main use of the relativePath feature is to allow relative imports in modules that are intended for use with module inheritance. Where an absolute import would be carried over as-is into the inheriting module, an import relative to __name__ will be relative to the inheriting module, e.g.:

        something = lazyModule(__name__,'../path/to/something')

The above code will have different results in each module that inherits it.

(Note: relativePath can also be an absolute path (starting with /); this is mainly useful for module __bases__ lists.)

  whenImported 
whenImported ( moduleName,  hook )

Call hook(module) when module named moduleName is first used

hook must accept one argument: the module object named by moduleName, which must be a fully qualified (i.e. absolute) module name. The hook should not raise any exceptions, or it may prevent later hooks from running.

If the module has already been imported normally, hook(module) is called immediately, and the module object is returned from this function. If the module has not been imported, or has only been imported lazily, then the hook is called when the module is first used, and a lazy import of the module is returned from this function. If the module was imported lazily and used before calling this function, the hook is called immediately, and the loaded module is returned from this function.

Note that using this function implies a possible lazy import of the specified module, and lazy importing means that any ImportError will be deferred until the module is used.


Table of Contents

This document was automatically generated on Tue Feb 17 19:55:52 2004 by HappyDoc version 2.1