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