def module_section(self, obj, package_context ):
"""Create a module-links section for the given object (module)"""
modules = inspect.getmembers(obj, inspect.ismodule)
package_context.clean(modules, obj)
package_context.recurse_scan(modules)
if hasattr(obj, '__path__'):
modpkgs = []
modnames = []
for file in os.listdir(obj.__path__[0]):
path = os.path.join(obj.__path__[0], file)
modname = inspect.getmodulename(file)
if modname and modname not in modnames:
modpkgs.append((modname, obj.__name__, 0, 0))
modnames.append(modname)
elif pydoc.ispackage(path):
modpkgs.append((file, obj.__name__, 1, 0))
modpkgs.sort()
# do more recursion here...
for (modname, name, ya, yo) in modpkgs:
package_context.add_interesting('.'.join((obj.__name__, modname)))
items = []
for (modname, name, ispackage, is_shadowed) in modpkgs:
try:
# get the actual module obj...
#if modname == "events":
# import pdb
# pdb.set_trace()
module = pydoc.safeimport('{0}.{1}'.format(name, modname))
description, documentation = pydoc.splitdoc(inspect.getdoc(module))
if description:
items.append(
'{0} -- {1}'.format(
self.modpkglink((modname, name, ispackage, is_shadowed)),
description,
)
)
else:
items.append(
self.modpkglink((modname, name, ispackage, is_shadowed))
)
except:
items.append(
self.modpkglink((modname, name, ispackage, is_shadowed))
)
contents = '<br>'.join(items)
result = self.bigsection(
'Package Contents', '#ffffff', '#aa55cc', contents)
elif modules:
contents = self.multicolumn(
modules,
lambda a: self.modulelink(a[1])
)
result = self.bigsection(
'Modules', '#fffff', '#aa55cc', contents)
else:
result = ""
return result
def moduleSection( self, object, packageContext ): """Create a module-links section for the given object (module)""" modules = inspect.getmembers(object, inspect.ismodule) packageContext.clean ( modules, object ) packageContext.recurseScan( modules ) if hasattr(object, '__path__'): modpkgs = [] modnames = [] for file in os.listdir(object.__path__[0]): path = os.path.join(object.__path__[0], file) modname = inspect.getmodulename(file) if modname and modname not in modnames: modpkgs.append((modname, object.__name__, 0, 0)) modnames.append(modname) elif pydoc.ispackage(path): modpkgs.append((file, object.__name__, 1, 0)) modpkgs.sort() # do more recursion here... for (modname, name, ya,yo) in modpkgs: packageContext.addInteresting( join( (object.__name__, modname), '.')) items = [] for (modname, name, ispackage,isshadowed) in modpkgs: try: # get the actual module object... ## if modname == "events": ## import pdb ## pdb.set_trace() module = pydoc.safeimport( "%s.%s"%(name,modname) ) description, documentation = pydoc.splitdoc( inspect.getdoc( module )) if description: items.append( """%s -- %s"""% ( self.modpkglink( (modname, name, ispackage, isshadowed) ), description, ) ) else: items.append( self.modpkglink( (modname, name, ispackage, isshadowed) ) ) except: items.append( self.modpkglink( (modname, name, ispackage, isshadowed) ) ) contents = string.join( items, '<br>') result = self.bigsection( 'Package Contents', '#ffffff', '#aa55cc', contents) elif modules: contents = self.multicolumn( modules, lambda (key, value), s=self: s.modulelink(value)) result = self.bigsection( 'Modules', '#fffff', '#aa55cc', contents) else: result = "" return result
def _iter_modules(path):
"""Iterate over all modules in a package."""
import pkgutil
if hasattr(pkgutil, 'iter_modules'):
for importer, modname, ispkg in pkgutil.iter_modules(path):
yield modname, ispkg
return
from inspect import getmodulename
from pydoc import ispackage
found = set()
for path in path:
for filename in os.listdir(path):
p = os.path.join(path, filename)
modname = getmodulename(filename)
if modname and modname != '__init__':
if modname not in found:
found.add(modname)
yield modname, ispackage(modname)
def myWritedocs(dir, pkgpath='', done=None):
"""Write out HTML documentation for all modules in a directory tree."""
if done is None: done = {}
for file in os.listdir(dir):
path = os.path.join(dir, file)
if ispackage(path):
writedocs(path, pkgpath + file + '.', done)
elif os.path.isfile(path):
modname = inspect.getmodulename(path)
if modname:
if modname == '__init__':
modname = pkgpath[:-1] # remove trailing period
else:
modname = pkgpath + modname
if modname not in done:
done[modname] = 1
try:
writedoc(modname)
except:
print 'failed to document', modname
def index(self, dir, shadowed=None, includes=[], excludes=[]):
"""Generate an HTML index for a directory of modules."""
modpkgs = []
if shadowed is None: shadowed = {}
seen = {}
files = os.listdir(dir)
def found(name, ispackage, modpkgs=modpkgs, shadowed=shadowed,
seen=seen):
if name not in seen:
modpkgs.append((name, '', ispackage, name in shadowed))
seen[name] = 1
shadowed[name] = 1
matched = PyDoc(self.env).filter_match
# Package spam/__init__.py takes precedence over module spam.py.
for file in files:
path = os.path.join(dir, file)
if ispackage(path) and matched(path):
found(file, 1)
for file in files:
path = os.path.join(dir, file)
if os.path.isfile(path):
modname = inspect.getmodulename(file)
if modname and matched(modname):
found(modname, 0)
elif os.path.isdir(path):
if matched(file):
found(file, 1)
modpkgs.sort()
contents = self.multicolumn(modpkgs, self.modpkglink)
if modpkgs:
return self.bigsection(dir, '#ffffff', '#ee77aa', contents)
else:
return ''
def submodules(self, (dir, package)):
children = []
for file in os.listdir(dir):
path = os.path.join(dir, file)
if ispackage(path):
children.append((path, package + (package and '.') + file))
else:
children.append((path, package))
children.sort() # so that spam.py comes before spam.pyc or spam.pyo
return children
def isnewpackage(self, (dir, package)):
inode = os.path.exists(dir) and os.stat(dir).st_ino
if not (os.path.islink(dir) and inode in self.inodes):
self.inodes.append(inode) # detect circular symbolic links
return ispackage(dir)
return False
def run(self, callback, key=None, completer=None):
if key: key = lower(key)
self.quit = False
seen = {}
for modname in sys.builtin_module_names:
if modname != '__main__':
seen[modname] = 1
if key is None:
callback(None, modname, '')
else:
desc = split(__import__(modname).__doc__ or '', '\n')[0]
if key in lower('%s - %s' % (modname, desc)):
def test_is_package_when_is_package(self):
with test.support.temp_cwd() as test_dir:
init_path = os.path.join(test_dir, '__init__.py')
open(init_path, 'w').close()
self.assertTrue(pydoc.ispackage(test_dir))
os.remove(init_path)
def test_is_package_when_not_package(self):
with test.support.temp_cwd() as test_dir:
self.assertFalse(pydoc.ispackage(test_dir))
def docmodule(self, obj, name=None, mod=None, package_context=None, *ignored):
"""Produce HTML documentation for a module object."""
name = obj.__name__ # ignore the passed-in name
parts = name.split('.')
links = []
for i in range(len(parts)-1):
links.append(
'<a href="%s.html"><font color="#ffffff">%s</font></a>' %
('.'.join(parts[:i+1]), parts[i]))
linked_name = '.'.join(links + parts[-1:])
head = '<big><big><strong>{0}</strong></big></big>'.format(linked_name)
try:
path = inspect.getabsfile(obj)
url = path
if sys.platform == 'win32':
import nturl2path
url = nturl2path.pathname2url(path)
fake_link = '<a href="file:{0}">{1}</a>'.format(url, path)
except TypeError:
fake_link = '(built-in)'
info = []
if hasattr(obj, '__version__'):
version = str(obj.__version__)
if version[:11] == '$' + 'Revision: ' and version[-1:] == '$':
version = version[11:-1].strip()
info.append('version %s' % self.escape(version))
if hasattr(obj, '__date__'):
info.append(self.escape(str(obj.__date__)))
if info:
head += ' ({0})'.format(', '.join(info))
result = self.heading(
head, '#ffffff', '#7799ee', '<a href=".">index</a><br>' + fake_link)
modules = inspect.getmembers(obj, inspect.ismodule)
classes, cdict = [], {}
for key, value in inspect.getmembers(obj, inspect.isclass):
if (inspect.getmodule(value) or obj) is obj:
classes.append((key, value))
cdict[key] = cdict[value] = '#' + key
for key, value in classes:
for base in value.__bases__:
key, modname = base.__name__, base.__module__
module = sys.modules.get(modname)
if modname != name and module and hasattr(module, key):
if getattr(module, key) is base:
if key not in cdict:
cdict[key] = cdict[base] = modname + '.html#' + key
funcs, fdict = [], {}
for key, value in inspect.getmembers(obj, inspect.isroutine):
if inspect.isbuiltin(value) or inspect.getmodule(value) is obj:
funcs.append((key, value))
fdict[key] = '#-' + key
if inspect.isfunction(value):
fdict[value] = fdict[key]
data = []
for key, value in inspect.getmembers(obj, pydoc.isdata):
if key not in ['__builtins__', '__doc__']:
data.append((key, value))
doc = self.markup(pydoc.getdoc(obj), self.preformat, fdict, cdict)
doc = doc and '<tt>%s</tt>' % doc
result += '<p>{0}</p>\n'.format(doc)
package_context.clean(classes, obj)
package_context.clean(funcs, obj)
package_context.clean(data, obj)
if hasattr(obj, '__path__'):
modpkgs = []
modnames = []
for file in os.listdir(obj.__path__[0]):
path = os.path.join(obj.__path__[0], file)
modname = inspect.getmodulename(file)
if modname and modname not in modnames:
modpkgs.append((modname, name, 0, 0))
modnames.append(modname)
elif pydoc.ispackage(path):
modpkgs.append((file, name, 1, 0))
modpkgs.sort()
contents = self.multicolumn(modpkgs, self.modpkglink)
## result = result + self.bigsection(
## 'Package Contents', '#ffffff', '#aa55cc', contents)
result = result + self.module_section(obj, package_context)
elif modules:
contents = self.multicolumn(
modules,
lambda a: self.modulelink(a[1])
)
result = result + self.bigsection(
'Modules', '#fffff', '#aa55cc', contents)
if classes:
class_list = map(lambda a: a[1], classes)
contents = [
self.formattree(inspect.getclasstree(class_list, 1), name)]
for key, value in classes:
contents.append(self.document(value, key, name, fdict, cdict))
result = result + self.bigsection(
'Classes', '#ffffff', '#ee77aa', ''.join(contents)
)
if funcs:
contents = []
for key, value in funcs:
contents.append(self.document(value, key, name, fdict, cdict))
result = result + self.bigsection(
'Functions', '#ffffff', '#eeaa77', ''.join(contents)
)
if data:
contents = []
for key, value in data:
try:
contents.append(self.document(value, key))
except Exception:
pass
result = result + self.bigsection(
'Data', '#ffffff', '#55aa55', '<br>\n'.join(contents)
)
if hasattr(obj, '__author__'):
contents = self.markup(str(obj.__author__), self.preformat)
result = result + self.bigsection(
'Author', '#ffffff', '#7799ee', contents)
if hasattr(obj, '__credits__'):
contents = self.markup(str(obj.__credits__), self.preformat)
result = result + self.bigsection(
'Credits', '#ffffff', '#7799ee', contents)
return result
def docmodule(self, object, name=None, mod=None, packageContext=None, *ignored):
"""Produce HTML documentation for a module object."""
name = object.__name__ # ignore the passed-in name
parts = split(name, ".")
links = []
for i in range(len(parts) - 1):
links.append(
'<a href="%s.html"><font color="#ffffff">%s</font></a>' % (join(parts[: i + 1], "."), parts[i])
)
linkedname = join(links + parts[-1:], ".")
head = "<big><big><strong>%s</strong></big></big>" % linkedname
try:
path = inspect.getabsfile(object)
url = path
if sys.platform == "win32":
import nturl2path
url = nturl2path.pathname2url(path)
filelink = '<a href="file:%s">%s</a>' % (url, path)
except TypeError:
filelink = "(built-in)"
info = []
if hasattr(object, "__version__"):
version = str(object.__version__)
if version[:11] == "$" + "Revision: " and version[-1:] == "$":
version = strip(version[11:-1])
info.append("version %s" % self.escape(version))
if hasattr(object, "__date__"):
info.append(self.escape(str(object.__date__)))
if info:
head = head + " (%s)" % join(info, ", ")
result = self.heading(head, "#ffffff", "#7799ee", '<a href=".">index</a><br>' + filelink)
modules = inspect.getmembers(object, inspect.ismodule)
classes, cdict = [], {}
for key, value in inspect.getmembers(object, inspect.isclass):
if (inspect.getmodule(value) or object) is object:
classes.append((key, value))
cdict[key] = cdict[value] = "#" + key
for key, value in classes:
for base in value.__bases__:
key, modname = base.__name__, base.__module__
module = sys.modules.get(modname)
if modname != name and module and hasattr(module, key):
if getattr(module, key) is base:
if not cdict.has_key(key):
cdict[key] = cdict[base] = modname + ".html#" + key
funcs, fdict = [], {}
for key, value in inspect.getmembers(object, inspect.isroutine):
if inspect.isbuiltin(value) or inspect.getmodule(value) is object:
funcs.append((key, value))
fdict[key] = "#-" + key
if inspect.isfunction(value):
fdict[value] = fdict[key]
data = []
for key, value in inspect.getmembers(object, pydoc.isdata):
if key not in ["__builtins__", "__doc__"]:
data.append((key, value))
doc = self.markup(pydoc.getdoc(object), self.preformat, fdict, cdict)
doc = doc and "<tt>%s</tt>" % doc
result = result + "<p>%s</p>\n" % doc
packageContext.clean(classes, object)
packageContext.clean(funcs, object)
packageContext.clean(data, object)
if hasattr(object, "__path__"):
modpkgs = []
modnames = []
for file in os.listdir(object.__path__[0]):
path = os.path.join(object.__path__[0], file)
modname = inspect.getmodulename(file)
if modname and modname not in modnames:
modpkgs.append((modname, name, 0, 0))
modnames.append(modname)
elif pydoc.ispackage(path):
modpkgs.append((file, name, 1, 0))
modpkgs.sort()
contents = self.multicolumn(modpkgs, self.modpkglink)
## result = result + self.bigsection(
## 'Package Contents', '#ffffff', '#aa55cc', contents)
result = result + self.moduleSection(object, packageContext)
elif modules:
contents = self.multicolumn(modules, lambda (key, value), s=self: s.modulelink(value))
result = result + self.bigsection("Modules", "#fffff", "#aa55cc", contents)
if classes:
classlist = map(lambda (key, value): value, classes)
contents = [self.formattree(inspect.getclasstree(classlist, 1), name)]
for key, value in classes:
contents.append(self.document(value, key, name, fdict, cdict))
result = result + self.bigsection("Classes", "#ffffff", "#ee77aa", join(contents))
if funcs:
contents = []
for key, value in funcs:
contents.append(self.document(value, key, name, fdict, cdict))
result = result + self.bigsection("Functions", "#ffffff", "#eeaa77", join(contents))
if data:
contents = []
for key, value in data:
contents.append(self.document(value, key))
result = result + self.bigsection("Data", "#ffffff", "#55aa55", join(contents, "<br>\n"))
if hasattr(object, "__author__"):
contents = self.markup(str(object.__author__), self.preformat)
result = result + self.bigsection("Author", "#ffffff", "#7799ee", contents)
if hasattr(object, "__credits__"):
contents = self.markup(str(object.__credits__), self.preformat)
result = result + self.bigsection("Credits", "#ffffff", "#7799ee", contents)
return result
def docmodule(self, object, name=None, mod=None):
''' Produce text documentation for a given module object.
'''
name = object.__name__ # ignore the passed-in name
synop, desc = pydoc.splitdoc(pydoc.getdoc(object))
result = self.section('Name', name + (synop and ' - ' + synop))
if desc:
result = result + self.section('Description', desc)
classes = []
for key, value in inspect.getmembers(object, inspect.isclass):
if (inspect.getmodule(value) or object) is object:
classes.append((key, value))
funcs = []
for key, value in inspect.getmembers(object, inspect.isroutine):
if inspect.isbuiltin(value) or inspect.getmodule(value) is object:
funcs.append((key, value))
if hasattr(object, '__path__'):
modpkgs = []
for file in os.listdir(object.__path__[0]):
path = os.path.join(object.__path__[0], file)
modname = inspect.getmodulename(file)
if modname and modname not in modpkgs:
modpkgs.append(modname)
elif pydoc.ispackage(path):
modpkgs.append(file + ' (package)')
modpkgs.sort()
result = result + self.section(
'Package contents', '\n'.join(modpkgs))
if classes:
classlist = map(lambda (key, value): value, classes)
classes_tree = self.formattree(inspect.getclasstree(classlist, 1), name)
if classes_tree:
classes_tree = '```text\n%s\n```\n' % classes_tree
result = result + self.section('Classes Tree', classes_tree)
contents = []
for key, value in classes:
contents.append(self.document(value, key, name))
result = result + self.section('Classes', '\n'.join(contents))
if funcs:
contents = []
for key, value in funcs:
contents.append(self.document(value, key, name))
result = result + self.section('Functions', '\n'.join(contents))
if hasattr(object, '__version__'):
version = str(object.__version__)
if version[:11] == '$' + 'Revision: ' and version[-1:] == '$':
version = strip(version[11:-1])
result = result + self.section('Version', version)
if hasattr(object, '__date__'):
result = result + self.section('Date', str(object.__date__))
if hasattr(object, '__author__'):
result = result + self.section('Author', str(object.__author__))
if hasattr(object, '__credits__'):
result = result + self.section('Credits', str(object.__credits__))
return result
def test_is_package_when_not_package(self):
with sql_mode.support.temp_cwd() as test_dir:
self.assertFalse(pydoc.ispackage(test_dir))
def test_is_package_when_is_package(self):
with test.support.temp_cwd() as test_dir:
init_path = os.path.join(test_dir, '__init__.py')
open(init_path, 'w').close()
self.assertTrue(pydoc.ispackage(test_dir))
os.remove(init_path)
def docmodule(self, object, name=None, mod=None, packageContext = None, *ignored):
"""Produce HTML documentation for a module object."""
name = object.__name__ # ignore the passed-in name
parts = split(name, '.')
links = []
for i in range(len(parts)-1):
links.append(
'<a href="%s.html"><font color="#ffffff">%s</font></a>' %
(join(parts[:i+1], '.'), parts[i]))
linkedname = join(links + parts[-1:], '.')
head = '<big><big><strong>%s</strong></big></big>' % linkedname
try:
path = inspect.getabsfile(object)
url = path
if sys.platform == 'win32':
import nturl2path
url = nturl2path.pathname2url(path)
filelink = '<a href="file:%s">%s</a>' % (url, path)
except TypeError:
filelink = '(built-in)'
info = []
if hasattr(object, '__version__'):
version = str(object.__version__)
if version[:11] == '$' + 'Revision: ' and version[-1:] == '$':
version = strip(version[11:-1])
info.append('version %s' % self.escape(version))
if hasattr(object, '__date__'):
info.append(self.escape(str(object.__date__)))
if info:
head = head + ' (%s)' % join(info, ', ')
result = self.heading(
head, '#ffffff', '#7799ee', '<a href=".">index</a><br>' + filelink)
modules = inspect.getmembers(object, inspect.ismodule)
classes, cdict = [], {}
for key, value in inspect.getmembers(object, inspect.isclass):
if (inspect.getmodule(value) or object) is object:
classes.append((key, value))
cdict[key] = cdict[value] = '#' + key
for key, value in classes:
for base in value.__bases__:
key, modname = base.__name__, base.__module__
module = sys.modules.get(modname)
if modname != name and module and hasattr(module, key):
if getattr(module, key) is base:
if not cdict.has_key(key):
cdict[key] = cdict[base] = modname + '.html#' + key
funcs, fdict = [], {}
for key, value in inspect.getmembers(object, inspect.isroutine):
if inspect.isbuiltin(value) or inspect.getmodule(value) is object:
funcs.append((key, value))
fdict[key] = '#-' + key
if inspect.isfunction(value): fdict[value] = fdict[key]
data = []
for key, value in inspect.getmembers(object, pydoc.isdata):
if key not in ['__builtins__', '__doc__']:
data.append((key, value))
doc = self.markup(pydoc.getdoc(object), self.preformat, fdict, cdict)
doc = doc and '<tt>%s</tt>' % doc
result = result + '<p>%s</p>\n' % doc
packageContext.clean ( classes, object )
packageContext.clean ( funcs, object )
packageContext.clean ( data, object )
if hasattr(object, '__path__'):
modpkgs = []
modnames = []
for file in os.listdir(object.__path__[0]):
path = os.path.join(object.__path__[0], file)
modname = inspect.getmodulename(file)
if modname and modname not in modnames:
modpkgs.append((modname, name, 0, 0))
modnames.append(modname)
elif pydoc.ispackage(path):
modpkgs.append((file, name, 1, 0))
modpkgs.sort()
contents = self.multicolumn(modpkgs, self.modpkglink)
## result = result + self.bigsection(
## 'Package Contents', '#ffffff', '#aa55cc', contents)
result = result + self.moduleSection( object, packageContext)
elif modules:
contents = self.multicolumn(
modules, lambda (key, value), s=self: s.modulelink(value))
result = result + self.bigsection(
'Modules', '#fffff', '#aa55cc', contents)
if classes:
classlist = map(lambda (key, value): value, classes)
contents = [
self.formattree(inspect.getclasstree(classlist, 1), name)]
for key, value in classes:
contents.append(self.document(value, key, name, fdict, cdict))
result = result + self.bigsection(
'Classes', '#ffffff', '#ee77aa', join(contents))
if funcs:
contents = []
for key, value in funcs:
contents.append(self.document(value, key, name, fdict, cdict))
result = result + self.bigsection(
'Functions', '#ffffff', '#eeaa77', join(contents))
if data:
contents = []
for key, value in data:
contents.append(self.document(value, key))
result = result + self.bigsection(
'Data', '#ffffff', '#55aa55', join(contents, '<br>\n'))
if hasattr(object, '__author__'):
contents = self.markup(str(object.__author__), self.preformat)
result = result + self.bigsection(
'Author', '#ffffff', '#7799ee', contents)
if hasattr(object, '__credits__'):
contents = self.markup(str(object.__credits__), self.preformat)
result = result + self.bigsection(
'Credits', '#ffffff', '#7799ee', contents)
return result