new script - helps track down symbols exported by modules but not

mentioned in the library reference manual

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