--- /dev/null
+"""Utilities to support packages."""\r
+\r
+# NOTE: This module must remain compatible with Python 2.3, as it is shared\r
+# by setuptools for distribution with Python 2.3 and up.\r
+\r
+import os\r
+import sys\r
+import imp\r
+import os.path\r
+from types import ModuleType\r
+\r
+__all__ = [\r
+ 'get_importer', 'iter_importers', 'get_loader', 'find_loader',\r
+ 'walk_packages', 'iter_modules', 'get_data',\r
+ 'ImpImporter', 'ImpLoader', 'read_code', 'extend_path',\r
+]\r
+\r
+def read_code(stream):\r
+ # This helper is needed in order for the PEP 302 emulation to\r
+ # correctly handle compiled files\r
+ import marshal\r
+\r
+ magic = stream.read(4)\r
+ if magic != imp.get_magic():\r
+ return None\r
+\r
+ stream.read(4) # Skip timestamp\r
+ return marshal.load(stream)\r
+\r
+\r
+def simplegeneric(func):\r
+ """Make a trivial single-dispatch generic function"""\r
+ registry = {}\r
+ def wrapper(*args, **kw):\r
+ ob = args[0]\r
+ try:\r
+ cls = ob.__class__\r
+ except AttributeError:\r
+ cls = type(ob)\r
+ try:\r
+ mro = cls.__mro__\r
+ except AttributeError:\r
+ try:\r
+ class cls(cls, object):\r
+ pass\r
+ mro = cls.__mro__[1:]\r
+ except TypeError:\r
+ mro = object, # must be an ExtensionClass or some such :(\r
+ for t in mro:\r
+ if t in registry:\r
+ return registry[t](*args, **kw)\r
+ else:\r
+ return func(*args, **kw)\r
+ try:\r
+ wrapper.__name__ = func.__name__\r
+ except (TypeError, AttributeError):\r
+ pass # Python 2.3 doesn't allow functions to be renamed\r
+\r
+ def register(typ, func=None):\r
+ if func is None:\r
+ return lambda f: register(typ, f)\r
+ registry[typ] = func\r
+ return func\r
+\r
+ wrapper.__dict__ = func.__dict__\r
+ wrapper.__doc__ = func.__doc__\r
+ wrapper.register = register\r
+ return wrapper\r
+\r
+\r
+def walk_packages(path=None, prefix='', onerror=None):\r
+ """Yields (module_loader, name, ispkg) for all modules recursively\r
+ on path, or, if path is None, all accessible modules.\r
+\r
+ 'path' should be either None or a list of paths to look for\r
+ modules in.\r
+\r
+ 'prefix' is a string to output on the front of every module name\r
+ on output.\r
+\r
+ Note that this function must import all *packages* (NOT all\r
+ modules!) on the given path, in order to access the __path__\r
+ attribute to find submodules.\r
+\r
+ 'onerror' is a function which gets called with one argument (the\r
+ name of the package which was being imported) if any exception\r
+ occurs while trying to import a package. If no onerror function is\r
+ supplied, ImportErrors are caught and ignored, while all other\r
+ exceptions are propagated, terminating the search.\r
+\r
+ Examples:\r
+\r
+ # list all modules python can access\r
+ walk_packages()\r
+\r
+ # list all submodules of ctypes\r
+ walk_packages(ctypes.__path__, ctypes.__name__+'.')\r
+ """\r
+\r
+ def seen(p, m={}):\r
+ if p in m:\r
+ return True\r
+ m[p] = True\r
+\r
+ for importer, name, ispkg in iter_modules(path, prefix):\r
+ yield importer, name, ispkg\r
+\r
+ if ispkg:\r
+ try:\r
+ __import__(name)\r
+ except ImportError:\r
+ if onerror is not None:\r
+ onerror(name)\r
+ except Exception:\r
+ if onerror is not None:\r
+ onerror(name)\r
+ else:\r
+ raise\r
+ else:\r
+ path = getattr(sys.modules[name], '__path__', None) or []\r
+\r
+ # don't traverse path items we've seen before\r
+ path = [p for p in path if not seen(p)]\r
+\r
+ for item in walk_packages(path, name+'.', onerror):\r
+ yield item\r
+\r
+\r
+def iter_modules(path=None, prefix=''):\r
+ """Yields (module_loader, name, ispkg) for all submodules on path,\r
+ or, if path is None, all top-level modules on sys.path.\r
+\r
+ 'path' should be either None or a list of paths to look for\r
+ modules in.\r
+\r
+ 'prefix' is a string to output on the front of every module name\r
+ on output.\r
+ """\r
+\r
+ if path is None:\r
+ importers = iter_importers()\r
+ else:\r
+ importers = map(get_importer, path)\r
+\r
+ yielded = {}\r
+ for i in importers:\r
+ for name, ispkg in iter_importer_modules(i, prefix):\r
+ if name not in yielded:\r
+ yielded[name] = 1\r
+ yield i, name, ispkg\r
+\r
+\r
+#@simplegeneric\r
+def iter_importer_modules(importer, prefix=''):\r
+ if not hasattr(importer, 'iter_modules'):\r
+ return []\r
+ return importer.iter_modules(prefix)\r
+\r
+iter_importer_modules = simplegeneric(iter_importer_modules)\r
+\r
+\r
+class ImpImporter:\r
+ """PEP 302 Importer that wraps Python's "classic" import algorithm\r
+\r
+ ImpImporter(dirname) produces a PEP 302 importer that searches that\r
+ directory. ImpImporter(None) produces a PEP 302 importer that searches\r
+ the current sys.path, plus any modules that are frozen or built-in.\r
+\r
+ Note that ImpImporter does not currently support being used by placement\r
+ on sys.meta_path.\r
+ """\r
+\r
+ def __init__(self, path=None):\r
+ self.path = path\r
+\r
+ def find_module(self, fullname, path=None):\r
+ # Note: we ignore 'path' argument since it is only used via meta_path\r
+ subname = fullname.split(".")[-1]\r
+ if subname != fullname and self.path is None:\r
+ return None\r
+ if self.path is None:\r
+ path = None\r
+ else:\r
+ path = [os.path.realpath(self.path)]\r
+ try:\r
+ file, filename, etc = imp.find_module(subname, path)\r
+ except ImportError:\r
+ return None\r
+ return ImpLoader(fullname, file, filename, etc)\r
+\r
+ def iter_modules(self, prefix=''):\r
+ if self.path is None or not os.path.isdir(self.path):\r
+ return\r
+\r
+ yielded = {}\r
+ import inspect\r
+ try:\r
+ filenames = os.listdir(self.path)\r
+ except OSError:\r
+ # ignore unreadable directories like import does\r
+ filenames = []\r
+ filenames.sort() # handle packages before same-named modules\r
+\r
+ for fn in filenames:\r
+ modname = inspect.getmodulename(fn)\r
+ if modname=='__init__' or modname in yielded:\r
+ continue\r
+\r
+ path = os.path.join(self.path, fn)\r
+ ispkg = False\r
+\r
+ if not modname and os.path.isdir(path) and '.' not in fn:\r
+ modname = fn\r
+ try:\r
+ dircontents = os.listdir(path)\r
+ except OSError:\r
+ # ignore unreadable directories like import does\r
+ dircontents = []\r
+ for fn in dircontents:\r
+ subname = inspect.getmodulename(fn)\r
+ if subname=='__init__':\r
+ ispkg = True\r
+ break\r
+ else:\r
+ continue # not a package\r
+\r
+ if modname and '.' not in modname:\r
+ yielded[modname] = 1\r
+ yield prefix + modname, ispkg\r
+\r
+\r
+class ImpLoader:\r
+ """PEP 302 Loader that wraps Python's "classic" import algorithm\r
+ """\r
+ code = source = None\r
+\r
+ def __init__(self, fullname, file, filename, etc):\r
+ self.file = file\r
+ self.filename = filename\r
+ self.fullname = fullname\r
+ self.etc = etc\r
+\r
+ def load_module(self, fullname):\r
+ self._reopen()\r
+ try:\r
+ mod = imp.load_module(fullname, self.file, self.filename, self.etc)\r
+ finally:\r
+ if self.file:\r
+ self.file.close()\r
+ # Note: we don't set __loader__ because we want the module to look\r
+ # normal; i.e. this is just a wrapper for standard import machinery\r
+ return mod\r
+\r
+ def get_data(self, pathname):\r
+ return open(pathname, "rb").read()\r
+\r
+ def _reopen(self):\r
+ if self.file and self.file.closed:\r
+ mod_type = self.etc[2]\r
+ if mod_type==imp.PY_SOURCE:\r
+ self.file = open(self.filename, 'rU')\r
+ elif mod_type in (imp.PY_COMPILED, imp.C_EXTENSION):\r
+ self.file = open(self.filename, 'rb')\r
+\r
+ def _fix_name(self, fullname):\r
+ if fullname is None:\r
+ fullname = self.fullname\r
+ elif fullname != self.fullname:\r
+ raise ImportError("Loader for module %s cannot handle "\r
+ "module %s" % (self.fullname, fullname))\r
+ return fullname\r
+\r
+ def is_package(self, fullname):\r
+ fullname = self._fix_name(fullname)\r
+ return self.etc[2]==imp.PKG_DIRECTORY\r
+\r
+ def get_code(self, fullname=None):\r
+ fullname = self._fix_name(fullname)\r
+ if self.code is None:\r
+ mod_type = self.etc[2]\r
+ if mod_type==imp.PY_SOURCE:\r
+ source = self.get_source(fullname)\r
+ self.code = compile(source, self.filename, 'exec')\r
+ elif mod_type==imp.PY_COMPILED:\r
+ self._reopen()\r
+ try:\r
+ self.code = read_code(self.file)\r
+ finally:\r
+ self.file.close()\r
+ elif mod_type==imp.PKG_DIRECTORY:\r
+ self.code = self._get_delegate().get_code()\r
+ return self.code\r
+\r
+ def get_source(self, fullname=None):\r
+ fullname = self._fix_name(fullname)\r
+ if self.source is None:\r
+ mod_type = self.etc[2]\r
+ if mod_type==imp.PY_SOURCE:\r
+ self._reopen()\r
+ try:\r
+ self.source = self.file.read()\r
+ finally:\r
+ self.file.close()\r
+ elif mod_type==imp.PY_COMPILED:\r
+ if os.path.exists(self.filename[:-1]):\r
+ f = open(self.filename[:-1], 'rU')\r
+ self.source = f.read()\r
+ f.close()\r
+ elif mod_type==imp.PKG_DIRECTORY:\r
+ self.source = self._get_delegate().get_source()\r
+ return self.source\r
+\r
+\r
+ def _get_delegate(self):\r
+ return ImpImporter(self.filename).find_module('__init__')\r
+\r
+ def get_filename(self, fullname=None):\r
+ fullname = self._fix_name(fullname)\r
+ mod_type = self.etc[2]\r
+ if self.etc[2]==imp.PKG_DIRECTORY:\r
+ return self._get_delegate().get_filename()\r
+ elif self.etc[2] in (imp.PY_SOURCE, imp.PY_COMPILED, imp.C_EXTENSION):\r
+ return self.filename\r
+ return None\r
+\r
+\r
+try:\r
+ import zipimport\r
+ from zipimport import zipimporter\r
+\r
+ def iter_zipimport_modules(importer, prefix=''):\r
+ dirlist = zipimport._zip_directory_cache[importer.archive].keys()\r
+ dirlist.sort()\r
+ _prefix = importer.prefix\r
+ plen = len(_prefix)\r
+ yielded = {}\r
+ import inspect\r
+ for fn in dirlist:\r
+ if not fn.startswith(_prefix):\r
+ continue\r
+\r
+ fn = fn[plen:].split(os.sep)\r
+\r
+ if len(fn)==2 and fn[1].startswith('__init__.py'):\r
+ if fn[0] not in yielded:\r
+ yielded[fn[0]] = 1\r
+ yield fn[0], True\r
+\r
+ if len(fn)!=1:\r
+ continue\r
+\r
+ modname = inspect.getmodulename(fn[0])\r
+ if modname=='__init__':\r
+ continue\r
+\r
+ if modname and '.' not in modname and modname not in yielded:\r
+ yielded[modname] = 1\r
+ yield prefix + modname, False\r
+\r
+ iter_importer_modules.register(zipimporter, iter_zipimport_modules)\r
+\r
+except ImportError:\r
+ pass\r
+\r
+\r
+def get_importer(path_item):\r
+ """Retrieve a PEP 302 importer for the given path item\r
+\r
+ The returned importer is cached in sys.path_importer_cache\r
+ if it was newly created by a path hook.\r
+\r
+ If there is no importer, a wrapper around the basic import\r
+ machinery is returned. This wrapper is never inserted into\r
+ the importer cache (None is inserted instead).\r
+\r
+ The cache (or part of it) can be cleared manually if a\r
+ rescan of sys.path_hooks is necessary.\r
+ """\r
+ try:\r
+ importer = sys.path_importer_cache[path_item]\r
+ except KeyError:\r
+ for path_hook in sys.path_hooks:\r
+ try:\r
+ importer = path_hook(path_item)\r
+ break\r
+ except ImportError:\r
+ pass\r
+ else:\r
+ importer = None\r
+ sys.path_importer_cache.setdefault(path_item, importer)\r
+\r
+ if importer is None:\r
+ try:\r
+ importer = ImpImporter(path_item)\r
+ except ImportError:\r
+ importer = None\r
+ return importer\r
+\r
+\r
+def iter_importers(fullname=""):\r
+ """Yield PEP 302 importers for the given module name\r
+\r
+ If fullname contains a '.', the importers will be for the package\r
+ containing fullname, otherwise they will be importers for sys.meta_path,\r
+ sys.path, and Python's "classic" import machinery, in that order. If\r
+ the named module is in a package, that package is imported as a side\r
+ effect of invoking this function.\r
+\r
+ Non PEP 302 mechanisms (e.g. the Windows registry) used by the\r
+ standard import machinery to find files in alternative locations\r
+ are partially supported, but are searched AFTER sys.path. Normally,\r
+ these locations are searched BEFORE sys.path, preventing sys.path\r
+ entries from shadowing them.\r
+\r
+ For this to cause a visible difference in behaviour, there must\r
+ be a module or package name that is accessible via both sys.path\r
+ and one of the non PEP 302 file system mechanisms. In this case,\r
+ the emulation will find the former version, while the builtin\r
+ import mechanism will find the latter.\r
+\r
+ Items of the following types can be affected by this discrepancy:\r
+ imp.C_EXTENSION, imp.PY_SOURCE, imp.PY_COMPILED, imp.PKG_DIRECTORY\r
+ """\r
+ if fullname.startswith('.'):\r
+ raise ImportError("Relative module names not supported")\r
+ if '.' in fullname:\r
+ # Get the containing package's __path__\r
+ pkg = '.'.join(fullname.split('.')[:-1])\r
+ if pkg not in sys.modules:\r
+ __import__(pkg)\r
+ path = getattr(sys.modules[pkg], '__path__', None) or []\r
+ else:\r
+ for importer in sys.meta_path:\r
+ yield importer\r
+ path = sys.path\r
+ for item in path:\r
+ yield get_importer(item)\r
+ if '.' not in fullname:\r
+ yield ImpImporter()\r
+\r
+def get_loader(module_or_name):\r
+ """Get a PEP 302 "loader" object for module_or_name\r
+\r
+ If the module or package is accessible via the normal import\r
+ mechanism, a wrapper around the relevant part of that machinery\r
+ is returned. Returns None if the module cannot be found or imported.\r
+ If the named module is not already imported, its containing package\r
+ (if any) is imported, in order to establish the package __path__.\r
+\r
+ This function uses iter_importers(), and is thus subject to the same\r
+ limitations regarding platform-specific special import locations such\r
+ as the Windows registry.\r
+ """\r
+ if module_or_name in sys.modules:\r
+ module_or_name = sys.modules[module_or_name]\r
+ if isinstance(module_or_name, ModuleType):\r
+ module = module_or_name\r
+ loader = getattr(module, '__loader__', None)\r
+ if loader is not None:\r
+ return loader\r
+ fullname = module.__name__\r
+ else:\r
+ fullname = module_or_name\r
+ return find_loader(fullname)\r
+\r
+def find_loader(fullname):\r
+ """Find a PEP 302 "loader" object for fullname\r
+\r
+ If fullname contains dots, path must be the containing package's __path__.\r
+ Returns None if the module cannot be found or imported. This function uses\r
+ iter_importers(), and is thus subject to the same limitations regarding\r
+ platform-specific special import locations such as the Windows registry.\r
+ """\r
+ for importer in iter_importers(fullname):\r
+ loader = importer.find_module(fullname)\r
+ if loader is not None:\r
+ return loader\r
+\r
+ return None\r
+\r
+\r
+def extend_path(path, name):\r
+ """Extend a package's path.\r
+\r
+ Intended use is to place the following code in a package's __init__.py:\r
+\r
+ from pkgutil import extend_path\r
+ __path__ = extend_path(__path__, __name__)\r
+\r
+ This will add to the package's __path__ all subdirectories of\r
+ directories on sys.path named after the package. This is useful\r
+ if one wants to distribute different parts of a single logical\r
+ package as multiple directories.\r
+\r
+ It also looks for *.pkg files beginning where * matches the name\r
+ argument. This feature is similar to *.pth files (see site.py),\r
+ except that it doesn't special-case lines starting with 'import'.\r
+ A *.pkg file is trusted at face value: apart from checking for\r
+ duplicates, all entries found in a *.pkg file are added to the\r
+ path, regardless of whether they are exist the filesystem. (This\r
+ is a feature.)\r
+\r
+ If the input path is not a list (as is the case for frozen\r
+ packages) it is returned unchanged. The input path is not\r
+ modified; an extended copy is returned. Items are only appended\r
+ to the copy at the end.\r
+\r
+ It is assumed that sys.path is a sequence. Items of sys.path that\r
+ are not (unicode or 8-bit) strings referring to existing\r
+ directories are ignored. Unicode items of sys.path that cause\r
+ errors when used as filenames may cause this function to raise an\r
+ exception (in line with os.path.isdir() behavior).\r
+ """\r
+\r
+ if not isinstance(path, list):\r
+ # This could happen e.g. when this is called from inside a\r
+ # frozen package. Return the path unchanged in that case.\r
+ return path\r
+\r
+ pname = os.path.join(*name.split('.')) # Reconstitute as relative path\r
+ # Just in case os.extsep != '.'\r
+ sname = os.extsep.join(name.split('.'))\r
+ sname_pkg = sname + os.extsep + "pkg"\r
+ init_py = "__init__" + os.extsep + "py"\r
+\r
+ path = path[:] # Start with a copy of the existing path\r
+\r
+ for dir in sys.path:\r
+ if not isinstance(dir, basestring) or not os.path.isdir(dir):\r
+ continue\r
+ subdir = os.path.join(dir, pname)\r
+ # XXX This may still add duplicate entries to path on\r
+ # case-insensitive filesystems\r
+ initfile = os.path.join(subdir, init_py)\r
+ if subdir not in path and os.path.isfile(initfile):\r
+ path.append(subdir)\r
+ # XXX Is this the right thing for subpackages like zope.app?\r
+ # It looks for a file named "zope.app.pkg"\r
+ pkgfile = os.path.join(dir, sname_pkg)\r
+ if os.path.isfile(pkgfile):\r
+ try:\r
+ f = open(pkgfile)\r
+ except IOError, msg:\r
+ sys.stderr.write("Can't open %s: %s\n" %\r
+ (pkgfile, msg))\r
+ else:\r
+ for line in f:\r
+ line = line.rstrip('\n')\r
+ if not line or line.startswith('#'):\r
+ continue\r
+ path.append(line) # Don't check for existence!\r
+ f.close()\r
+\r
+ return path\r
+\r
+def get_data(package, resource):\r
+ """Get a resource from a package.\r
+\r
+ This is a wrapper round the PEP 302 loader get_data API. The package\r
+ argument should be the name of a package, in standard module format\r
+ (foo.bar). The resource argument should be in the form of a relative\r
+ filename, using '/' as the path separator. The parent directory name '..'\r
+ is not allowed, and nor is a rooted name (starting with a '/').\r
+\r
+ The function returns a binary string, which is the contents of the\r
+ specified resource.\r
+\r
+ For packages located in the filesystem, which have already been imported,\r
+ this is the rough equivalent of\r
+\r
+ d = os.path.dirname(sys.modules[package].__file__)\r
+ data = open(os.path.join(d, resource), 'rb').read()\r
+\r
+ If the package cannot be located or loaded, or it uses a PEP 302 loader\r
+ which does not support get_data(), then None is returned.\r
+ """\r
+\r
+ loader = get_loader(package)\r
+ if loader is None or not hasattr(loader, 'get_data'):\r
+ return None\r
+ mod = sys.modules.get(package) or loader.load_module(package)\r
+ if mod is None or not hasattr(mod, '__file__'):\r
+ return None\r
+\r
+ # Modify the resource name to be compatible with the loader.get_data\r
+ # signature - an os.path format "filename" starting with the dirname of\r
+ # the package's __file__\r
+ parts = resource.split('/')\r
+ parts.insert(0, os.path.dirname(mod.__file__))\r
+ resource_name = os.path.join(*parts)\r
+ return loader.get_data(resource_name)\r