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@amk.ca>
8
9**Source code:** :source:`Lib/modulefinder.py`
10
11--------------
12
13This module provides a :class:`ModuleFinder` class that can be used to determine
14the set of modules imported by a script. ``modulefinder.py`` can also be run as
15a script, giving the filename of a Python script as its argument, after which a
16report 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
60Example usage of :class:`ModuleFinder`
61--------------------------------------
62
63The 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
78The 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
94Sample 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