# Copyright (c) Twisted Matrix Laboratories. # See LICENSE for details. import inspect, glob from os import path from twisted.trial import unittest from twisted.python import reflect from twisted.python.modules import getModule def errorInFile(f, line=17, name=''): """ Return a filename formatted so emacs will recognize it as an error point @param line: Line number in file. Defaults to 17 because that's about how long the copyright headers are. """ return '%s:%d:%s' % (f, line, name) # return 'File "%s", line %d, in %s' % (f, line, name) class DocCoverage(unittest.TestCase): """ Looking for docstrings in all modules and packages. """ def setUp(self): self.packageNames = [] for mod in getModule('twisted').walkModules(): if mod.isPackage(): self.packageNames.append(mod.name) def testModules(self): """ Looking for docstrings in all modules. """ docless = [] for packageName in self.packageNames: if packageName in ('twisted.test',): # because some stuff in here behaves oddly when imported continue try: package = reflect.namedModule(packageName) except ImportError, e: # This is testing doc coverage, not importability. # (Really, I don't want to deal with the fact that I don't # have pyserial installed.) # print e pass else: docless.extend(self.modulesInPackage(packageName, package)) self.failIf(docless, "No docstrings in module files:\n" "%s" % ('\n'.join(map(errorInFile, docless)),)) def modulesInPackage(self, packageName, package): docless = [] directory = path.dirname(package.__file__) for modfile in glob.glob(path.join(directory, '*.py')): moduleName = inspect.getmodulename(modfile) if moduleName == '__init__': # These are tested by test_packages. continue elif moduleName in ('spelunk_gnome','gtkmanhole'): # argh special case pygtk evil argh. How does epydoc deal # with this? continue try: module = reflect.namedModule('.'.join([packageName, moduleName])) except Exception, e: # print moduleName, "misbehaved:", e pass else: if not inspect.getdoc(module): docless.append(modfile) return docless def testPackages(self): """ Looking for docstrings in all packages. """ docless = [] for packageName in self.packageNames: try: package = reflect.namedModule(packageName) except Exception, e: # This is testing doc coverage, not importability. # (Really, I don't want to deal with the fact that I don't # have pyserial installed.) # print e pass else: if not inspect.getdoc(package): docless.append(package.__file__.replace('.pyc','.py')) self.failIf(docless, "No docstrings for package files\n" "%s" % ('\n'.join(map(errorInFile, docless),))) # This test takes a while and doesn't come close to passing. :( testModules.skip = "Activate me when you feel like writing docstrings, and fixing GTK crashing bugs."