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