moving into the Doc/tools directory

Tools/scripts/findsyms.py

-#!/usr/bin/env python
-
-# Released to the public domain by Skip Montanaro, 28 March 2002
-
-"""
-findsyms.py - try to identify undocumented symbols exported by modules
-
-Usage:    findsyms.py librefdir
-
-For each lib*.tex file in the libref manual source directory, identify which
-module is documented, import the module if possible, then search the LaTeX
-source for the symbols global to that module.  Report any that don't seem to
-be documented.
-
-Certain exceptions are made to the list of undocumented symbols:
-
-    * don't mention symbols in which all letters are upper case on the
-      assumption they are manifest constants
-
-    * don't mention symbols that are themselves modules
-
-    * don't mention symbols that match those exported by os, math, string,
-      types, or __builtin__ modules
-
-Finally, if a name is exported by the module but fails a getattr() lookup,
-that anomaly is reported.
-"""
-
-import __builtin__
-import getopt
-import glob
-import math
-import os
-import re
-import string
-import sys
-import types
-import warnings
-
-def usage():
-    print >> sys.stderr, """
-usage: %s dir
-where 'dir' is the Library Reference Manual source directory.
-""" % os.path.basename(sys.argv[0])
-    
-def main():
-    try:
-        opts, args = getopt.getopt(sys.argv[1:], "")
-    except getopt.error:
-        usage()
-        return
-
-    if not args:
-        usage()
-        return
-
-    libdir = args[0]
-    
-    warnings.filterwarnings("error")
-
-    pat = re.compile(r"\\declaremodule\s*{[^}]*}\s*{([^}]*)}")
-
-    missing = []
-    filelist = glob.glob(os.path.join(libdir, "lib*.tex"))
-    filelist.sort()
-    for f in filelist:
-        mod = f[3:-4]
-        if not mod: continue
-        data = open(f).read()
-        mods = re.findall(pat, data)
-        if not mods:
-            print "No module declarations found in", f
-            continue
-        for modname in mods:
-            # skip special modules
-            if modname.startswith("__"):
-                continue
-            try:
-                mod = __import__(modname)
-            except ImportError:
-                missing.append(modname)
-                continue
-            except DeprecationWarning:
-                print "Deprecated module:", modname
-                continue
-            if hasattr(mod, "__all__"):
-                all = mod.__all__
-            else:
-                all = [k for k in dir(mod) if k[0] != "_"]
-            mentioned = 0
-            all.sort()
-            for name in all:
-                if data.find(name) == -1:
-                    # certain names are predominantly used for testing
-                    if name in ("main","test","_test"):
-                        continue
-                    # is it some sort of manifest constant?
-                    if name.upper() == name:
-                        continue
-                    try:
-                        item = getattr(mod, name)
-                    except AttributeError:
-                        print "  ", name, "exposed, but not an attribute"
-                        continue
-                    # don't care about modules that might be exposed
-                    if type(item) == types.ModuleType:
-                        continue
-                    # check a few modules which tend to be import *'d
-                    isglobal = 0
-                    for m in (os, math, string, __builtin__, types):
-                        if hasattr(m, name) and item == getattr(m, name):
-                            isglobal = 1
-                            break
-                    if isglobal: continue
-                    if not mentioned:
-                        print "Not mentioned in", modname, "docs:"
-                        mentioned = 1
-                    print "  ", name
-    if missing:
-        missing.sort()
-        print "Could not import:"
-        print "  ", ", ".join(missing)
-
-if __name__ == "__main__":
-    try:
-        main()
-    except KeyboardInterrupt:
-        pass