/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
 14This module provides a :class:`ModuleFinder` class that can be used to determine
 15the set of modules imported by a script. ``modulefinder.py`` can also be run as
 16a script, giving the filename of a Python script as its argument, after which a
 17report 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
 62Example usage of :class:`ModuleFinder`
 63--------------------------------------
 64
 65The 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
 80The 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
 96Sample 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