Doc/library/modulefinder.rst

   1
   2 :mod:`modulefinder` --- Find modules used by a script
   3 =====================================================
   4
   5 .. sectionauthor:: A.M. Kuchling <amk@amk.ca>
   6
   7
   8 .. module:: modulefinder
   9    :synopsis: Find modules used by a script.
  10
  11
  12 .. versionadded:: 2.3
  13
  14 This module provides a :class:`ModuleFinder` class that can be used to determine
  15 the set of modules imported by a script. ``modulefinder.py`` can also be run as
  16 a script, giving the filename of a Python script as its argument, after which a
  17 report of the imported modules will be printed.
  18
  19
  20 .. function:: AddPackagePath(pkg_name, path)
  21
  22    Record that the package named *pkg_name* can be found in the specified *path*.
  23
  24
  25 .. function:: ReplacePackage(oldname, newname)
  26
  27    Allows specifying that the module named *oldname* is in fact the package named
  28    *newname*.  The most common usage would be  to handle how the :mod:`_xmlplus`
  29    package replaces the :mod:`xml` package.
  30
  31
  32 .. class:: ModuleFinder([path=None, debug=0, excludes=[], replace_paths=[]])
  33
  34    This class provides :meth:`run_script` and :meth:`report` methods to determine
  35    the set of modules imported by a script. *path* can be a list of directories to
  36    search for modules; if not specified, ``sys.path`` is used.  *debug* sets the
  37    debugging level; higher values make the class print  debugging messages about
  38    what it's doing. *excludes* is a list of module names to exclude from the
  39    analysis. *replace_paths* is a list of ``(oldpath, newpath)`` tuples that will
  40    be replaced in module paths.
  41
  42
  43    .. method:: report()
  44
  45       Print a report to standard output that lists the modules imported by the
  46       script and their paths, as well as modules that are missing or seem to be
  47       missing.
  48
  49    .. method:: run_script(pathname)
  50
  51       Analyze the contents of the *pathname* file, which must contain Python
  52       code.
  53
  54    .. attribute:: modules
  55
  56       A dictionary mapping module names to modules. See
  57       :ref:`modulefinder-example`
  58
  59
  60 .. _modulefinder-example:
  61
  62 Example usage of :class:`ModuleFinder`
  63 --------------------------------------
  64
  65 The script that is going to get analyzed later on (bacon.py)::
  66
  67    import re, itertools
  68
  69    try:
  70        import baconhameggs
  71    except ImportError:
  72        pass
  73
  74    try:
  75        import guido.python.ham
  76    except ImportError:
  77        pass
  78
  79
  80 The script that will output the report of bacon.py::
  81
  82    from modulefinder import ModuleFinder
  83
  84    finder = ModuleFinder()
  85    finder.run_script('bacon.py')
  86
  87    print 'Loaded modules:'
  88    for name, mod in finder.modules.iteritems():
  89        print '%s: ' % name,
  90        print ','.join(mod.globalnames.keys()[:3])
  91
  92    print '-'*50
  93    print 'Modules not imported:'
  94    print '\n'.join(finder.badmodules.iterkeys())
  95
  96 Sample output (may vary depending on the architecture)::
  97
  98     Loaded modules:
  99     _types:
 100     copy_reg:  _inverted_registry,_slotnames,__all__
 101     sre_compile:  isstring,_sre,_optimize_unicode
 102     _sre:
 103     sre_constants:  REPEAT_ONE,makedict,AT_END_LINE
 104     sys:
 105     re:  __module__,finditer,_expand
 106     itertools:
 107     __main__:  re,itertools,baconhameggs
 108     sre_parse:  __getslice__,_PATTERNENDERS,SRE_FLAG_UNICODE
 109     array:
 110     types:  __module__,IntType,TypeType
 111     ---------------------------------------------------
 112     Modules not imported:
 113     guido.python.ham
 114     baconhameggs
 115
 116