/lib-python/2/pydoc.py
Python | 2360 lines | 2300 code | 35 blank | 25 comment | 98 complexity | 385e5e211898c88c74373fd9e5740f03 MD5 | raw file
Possible License(s): Apache-2.0
Large files files are truncated, but you can click here to view the full file
- #!/usr/bin/env python
- # -*- coding: latin-1 -*-
- """Generate Python documentation in HTML or text for interactive use.
- In the Python interpreter, do "from pydoc import help" to provide online
- help. Calling help(thing) on a Python object documents the object.
- Or, at the shell command line outside of Python:
- Run "pydoc <name>" to show documentation on something. <name> may be
- the name of a function, module, package, or a dotted reference to a
- class or function within a module or module in a package. If the
- argument contains a path segment delimiter (e.g. slash on Unix,
- backslash on Windows) it is treated as the path to a Python source file.
- Run "pydoc -k <keyword>" to search for a keyword in the synopsis lines
- of all available modules.
- Run "pydoc -p <port>" to start an HTTP server on a given port on the
- local machine to generate documentation web pages.
- For platforms without a command line, "pydoc -g" starts the HTTP server
- and also pops up a little window for controlling it.
- Run "pydoc -w <name>" to write out the HTML documentation for a module
- to a file named "<name>.html".
- Module docs for core modules are assumed to be in
- http://docs.python.org/library/
- This can be overridden by setting the PYTHONDOCS environment variable
- to a different URL or to a local directory containing the Library
- Reference Manual pages.
- """
- __author__ = "Ka-Ping Yee <ping@lfw.org>"
- __date__ = "26 February 2001"
- __version__ = "$Revision: 88564 $"
- __credits__ = """Guido van Rossum, for an excellent programming language.
- Tommy Burnette, the original creator of manpy.
- Paul Prescod, for all his work on onlinehelp.
- Richard Chamberlain, for the first implementation of textdoc.
- """
- # Known bugs that can't be fixed here:
- # - imp.load_module() cannot be prevented from clobbering existing
- # loaded modules, so calling synopsis() on a binary module file
- # changes the contents of any existing module with the same name.
- # - If the __file__ attribute on a module is a relative path and
- # the current directory is changed with os.chdir(), an incorrect
- # path will be displayed.
- import sys, imp, os, re, types, inspect, __builtin__, pkgutil, warnings
- from repr import Repr
- from string import expandtabs, find, join, lower, split, strip, rfind, rstrip
- from traceback import extract_tb
- try:
- from collections import deque
- except ImportError:
- # Python 2.3 compatibility
- class deque(list):
- def popleft(self):
- return self.pop(0)
- # --------------------------------------------------------- common routines
- def pathdirs():
- """Convert sys.path into a list of absolute, existing, unique paths."""
- dirs = []
- normdirs = []
- for dir in sys.path:
- dir = os.path.abspath(dir or '.')
- normdir = os.path.normcase(dir)
- if normdir not in normdirs and os.path.isdir(dir):
- dirs.append(dir)
- normdirs.append(normdir)
- return dirs
- def getdoc(object):
- """Get the doc string or comments for an object."""
- result = inspect.getdoc(object) or inspect.getcomments(object)
- return result and re.sub('^ *\n', '', rstrip(result)) or ''
- def splitdoc(doc):
- """Split a doc string into a synopsis line (if any) and the rest."""
- lines = split(strip(doc), '\n')
- if len(lines) == 1:
- return lines[0], ''
- elif len(lines) >= 2 and not rstrip(lines[1]):
- return lines[0], join(lines[2:], '\n')
- return '', join(lines, '\n')
- def classname(object, modname):
- """Get a class name and qualify it with a module name if necessary."""
- name = object.__name__
- if object.__module__ != modname:
- name = object.__module__ + '.' + name
- return name
- def isdata(object):
- """Check if an object is of a type that probably means it's data."""
- return not (inspect.ismodule(object) or inspect.isclass(object) or
- inspect.isroutine(object) or inspect.isframe(object) or
- inspect.istraceback(object) or inspect.iscode(object))
- def replace(text, *pairs):
- """Do a series of global replacements on a string."""
- while pairs:
- text = join(split(text, pairs[0]), pairs[1])
- pairs = pairs[2:]
- return text
- def cram(text, maxlen):
- """Omit part of a string if needed to make it fit in a maximum length."""
- if len(text) > maxlen:
- pre = max(0, (maxlen-3)//2)
- post = max(0, maxlen-3-pre)
- return text[:pre] + '...' + text[len(text)-post:]
- return text
- _re_stripid = re.compile(r' at 0x[0-9a-f]{6,16}(>+)$', re.IGNORECASE)
- def stripid(text):
- """Remove the hexadecimal id from a Python object representation."""
- # The behaviour of %p is implementation-dependent in terms of case.
- return _re_stripid.sub(r'\1', text)
- def _is_some_method(obj):
- return inspect.ismethod(obj) or inspect.ismethoddescriptor(obj)
- def allmethods(cl):
- methods = {}
- for key, value in inspect.getmembers(cl, _is_some_method):
- methods[key] = 1
- for base in cl.__bases__:
- methods.update(allmethods(base)) # all your base are belong to us
- for key in methods.keys():
- methods[key] = getattr(cl, key)
- return methods
- def _split_list(s, predicate):
- """Split sequence s via predicate, and return pair ([true], [false]).
- The return value is a 2-tuple of lists,
- ([x for x in s if predicate(x)],
- [x for x in s if not predicate(x)])
- """
- yes = []
- no = []
- for x in s:
- if predicate(x):
- yes.append(x)
- else:
- no.append(x)
- return yes, no
- def visiblename(name, all=None, obj=None):
- """Decide whether to show documentation on a variable."""
- # Certain special names are redundant.
- _hidden_names = ('__builtins__', '__doc__', '__file__', '__path__',
- '__module__', '__name__', '__slots__', '__package__')
- if name in _hidden_names: return 0
- # Private names are hidden, but special names are displayed.
- if name.startswith('__') and name.endswith('__'): return 1
- # Namedtuples have public fields and methods with a single leading underscore
- if name.startswith('_') and hasattr(obj, '_fields'):
- return 1
- if all is not None:
- # only document that which the programmer exported in __all__
- return name in all
- else:
- return not name.startswith('_')
- def classify_class_attrs(object):
- """Wrap inspect.classify_class_attrs, with fixup for data descriptors."""
- def fixup(data):
- name, kind, cls, value = data
- if inspect.isdatadescriptor(value):
- kind = 'data descriptor'
- return name, kind, cls, value
- return map(fixup, inspect.classify_class_attrs(object))
- # ----------------------------------------------------- module manipulation
- def ispackage(path):
- """Guess whether a path refers to a package directory."""
- if os.path.isdir(path):
- for ext in ('.py', '.pyc', '.pyo'):
- if os.path.isfile(os.path.join(path, '__init__' + ext)):
- return True
- return False
- def source_synopsis(file):
- line = file.readline()
- while line[:1] == '#' or not strip(line):
- line = file.readline()
- if not line: break
- line = strip(line)
- if line[:4] == 'r"""': line = line[1:]
- if line[:3] == '"""':
- line = line[3:]
- if line[-1:] == '\\': line = line[:-1]
- while not strip(line):
- line = file.readline()
- if not line: break
- result = strip(split(line, '"""')[0])
- else: result = None
- return result
- def synopsis(filename, cache={}):
- """Get the one-line summary out of a module file."""
- mtime = os.stat(filename).st_mtime
- lastupdate, result = cache.get(filename, (None, None))
- if lastupdate is None or lastupdate < mtime:
- info = inspect.getmoduleinfo(filename)
- try:
- file = open(filename)
- except IOError:
- # module can't be opened, so skip it
- return None
- if info and 'b' in info[2]: # binary modules have to be imported
- try: module = imp.load_module('__temp__', file, filename, info[1:])
- except: return None
- result = (module.__doc__ or '').splitlines()[0]
- del sys.modules['__temp__']
- else: # text modules can be directly examined
- result = source_synopsis(file)
- file.close()
- cache[filename] = (mtime, result)
- return result
- class ErrorDuringImport(Exception):
- """Errors that occurred while trying to import something to document it."""
- def __init__(self, filename, exc_info):
- exc, value, tb = exc_info
- self.filename = filename
- self.exc = exc
- self.value = value
- self.tb = tb
- def __str__(self):
- exc = self.exc
- if type(exc) is types.ClassType:
- exc = exc.__name__
- return 'problem in %s - %s: %s' % (self.filename, exc, self.value)
- def importfile(path):
- """Import a Python source file or compiled file given its path."""
- magic = imp.get_magic()
- file = open(path, 'r')
- if file.read(len(magic)) == magic:
- kind = imp.PY_COMPILED
- else:
- kind = imp.PY_SOURCE
- file.close()
- filename = os.path.basename(path)
- name, ext = os.path.splitext(filename)
- file = open(path, 'r')
- try:
- module = imp.load_module(name, file, path, (ext, 'r', kind))
- except:
- raise ErrorDuringImport(path, sys.exc_info())
- file.close()
- return module
- def safeimport(path, forceload=0, cache={}):
- """Import a module; handle errors; return None if the module isn't found.
- If the module *is* found but an exception occurs, it's wrapped in an
- ErrorDuringImport exception and reraised. Unlike __import__, if a
- package path is specified, the module at the end of the path is returned,
- not the package at the beginning. If the optional 'forceload' argument
- is 1, we reload the module from disk (unless it's a dynamic extension)."""
- try:
- # If forceload is 1 and the module has been previously loaded from
- # disk, we always have to reload the module. Checking the file's
- # mtime isn't good enough (e.g. the module could contain a class
- # that inherits from another module that has changed).
- if forceload and path in sys.modules:
- if path not in sys.builtin_module_names:
- # Avoid simply calling reload() because it leaves names in
- # the currently loaded module lying around if they're not
- # defined in the new source file. Instead, remove the
- # module from sys.modules and re-import. Also remove any
- # submodules because they won't appear in the newly loaded
- # module's namespace if they're already in sys.modules.
- subs = [m for m in sys.modules if m.startswith(path + '.')]
- for key in [path] + subs:
- # Prevent garbage collection.
- cache[key] = sys.modules[key]
- del sys.modules[key]
- module = __import__(path)
- except:
- # Did the error occur before or after the module was found?
- (exc, value, tb) = info = sys.exc_info()
- if path in sys.modules:
- # An error occurred while executing the imported module.
- raise ErrorDuringImport(sys.modules[path].__file__, info)
- elif exc is SyntaxError:
- # A SyntaxError occurred before we could execute the module.
- raise ErrorDuringImport(value.filename, info)
- elif exc is ImportError and extract_tb(tb)[-1][2]=='safeimport':
- # The import error occurred directly in this function,
- # which means there is no such module in the path.
- return None
- else:
- # Some other error occurred during the importing process.
- raise ErrorDuringImport(path, sys.exc_info())
- for part in split(path, '.')[1:]:
- try: module = getattr(module, part)
- except AttributeError: return None
- return module
- # ---------------------------------------------------- formatter base class
- class Doc:
- def document(self, object, name=None, *args):
- """Generate documentation for an object."""
- args = (object, name) + args
- # 'try' clause is to attempt to handle the possibility that inspect
- # identifies something in a way that pydoc itself has issues handling;
- # think 'super' and how it is a descriptor (which raises the exception
- # by lacking a __name__ attribute) and an instance.
- if inspect.isgetsetdescriptor(object): return self.docdata(*args)
- if inspect.ismemberdescriptor(object): return self.docdata(*args)
- try:
- if inspect.ismodule(object): return self.docmodule(*args)
- if inspect.isclass(object): return self.docclass(*args)
- if inspect.isroutine(object): return self.docroutine(*args)
- except AttributeError:
- pass
- if isinstance(object, property): return self.docproperty(*args)
- return self.docother(*args)
- def fail(self, object, name=None, *args):
- """Raise an exception for unimplemented types."""
- message = "don't know how to document object%s of type %s" % (
- name and ' ' + repr(name), type(object).__name__)
- raise TypeError, message
- docmodule = docclass = docroutine = docother = docproperty = docdata = fail
- def getdocloc(self, object):
- """Return the location of module docs or None"""
- try:
- file = inspect.getabsfile(object)
- except TypeError:
- file = '(built-in)'
- docloc = os.environ.get("PYTHONDOCS",
- "http://docs.python.org/library")
- basedir = os.path.join(sys.exec_prefix, "lib",
- "python"+sys.version[0:3])
- if (isinstance(object, type(os)) and
- (object.__name__ in ('errno', 'exceptions', 'gc', 'imp',
- 'marshal', 'posix', 'signal', 'sys',
- 'thread', 'zipimport') or
- (file.startswith(basedir) and
- not file.startswith(os.path.join(basedir, 'site-packages')))) and
- object.__name__ not in ('xml.etree', 'test.pydoc_mod')):
- if docloc.startswith("http://"):
- docloc = "%s/%s" % (docloc.rstrip("/"), object.__name__)
- else:
- docloc = os.path.join(docloc, object.__name__ + ".html")
- else:
- docloc = None
- return docloc
- # -------------------------------------------- HTML documentation generator
- class HTMLRepr(Repr):
- """Class for safely making an HTML representation of a Python object."""
- def __init__(self):
- Repr.__init__(self)
- self.maxlist = self.maxtuple = 20
- self.maxdict = 10
- self.maxstring = self.maxother = 100
- def escape(self, text):
- return replace(text, '&', '&', '<', '<', '>', '>')
- def repr(self, object):
- return Repr.repr(self, object)
- def repr1(self, x, level):
- if hasattr(type(x), '__name__'):
- methodname = 'repr_' + join(split(type(x).__name__), '_')
- if hasattr(self, methodname):
- return getattr(self, methodname)(x, level)
- return self.escape(cram(stripid(repr(x)), self.maxother))
- def repr_string(self, x, level):
- test = cram(x, self.maxstring)
- testrepr = repr(test)
- if '\\' in test and '\\' not in replace(testrepr, r'\\', ''):
- # Backslashes are only literal in the string and are never
- # needed to make any special characters, so show a raw string.
- return 'r' + testrepr[0] + self.escape(test) + testrepr[0]
- return re.sub(r'((\\[\\abfnrtv\'"]|\\[0-9]..|\\x..|\\u....)+)',
- r'<font color="#c040c0">\1</font>',
- self.escape(testrepr))
- repr_str = repr_string
- def repr_instance(self, x, level):
- try:
- return self.escape(cram(stripid(repr(x)), self.maxstring))
- except:
- return self.escape('<%s instance>' % x.__class__.__name__)
- repr_unicode = repr_string
- class HTMLDoc(Doc):
- """Formatter class for HTML documentation."""
- # ------------------------------------------- HTML formatting utilities
- _repr_instance = HTMLRepr()
- repr = _repr_instance.repr
- escape = _repr_instance.escape
- def page(self, title, contents):
- """Format an HTML page."""
- return '''
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
- <html><head><title>Python: %s</title>
- </head><body bgcolor="#f0f0f8">
- %s
- </body></html>''' % (title, contents)
- def heading(self, title, fgcol, bgcol, extras=''):
- """Format a page heading."""
- return '''
- <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="heading">
- <tr bgcolor="%s">
- <td valign=bottom> <br>
- <font color="%s" face="helvetica, arial"> <br>%s</font></td
- ><td align=right valign=bottom
- ><font color="%s" face="helvetica, arial">%s</font></td></tr></table>
- ''' % (bgcol, fgcol, title, fgcol, extras or ' ')
- def section(self, title, fgcol, bgcol, contents, width=6,
- prelude='', marginalia=None, gap=' '):
- """Format a section with a heading."""
- if marginalia is None:
- marginalia = '<tt>' + ' ' * width + '</tt>'
- result = '''<p>
- <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
- <tr bgcolor="%s">
- <td colspan=3 valign=bottom> <br>
- <font color="%s" face="helvetica, arial">%s</font></td></tr>
- ''' % (bgcol, fgcol, title)
- if prelude:
- result = result + '''
- <tr bgcolor="%s"><td rowspan=2>%s</td>
- <td colspan=2>%s</td></tr>
- <tr><td>%s</td>''' % (bgcol, marginalia, prelude, gap)
- else:
- result = result + '''
- <tr><td bgcolor="%s">%s</td><td>%s</td>''' % (bgcol, marginalia, gap)
- return result + '\n<td width="100%%">%s</td></tr></table>' % contents
- def bigsection(self, title, *args):
- """Format a section with a big heading."""
- title = '<big><strong>%s</strong></big>' % title
- return self.section(title, *args)
- def preformat(self, text):
- """Format literal preformatted text."""
- text = self.escape(expandtabs(text))
- return replace(text, '\n\n', '\n \n', '\n\n', '\n \n',
- ' ', ' ', '\n', '<br>\n')
- def multicolumn(self, list, format, cols=4):
- """Format a list of items into a multi-column list."""
- result = ''
- rows = (len(list)+cols-1)//cols
- for col in range(cols):
- result = result + '<td width="%d%%" valign=top>' % (100//cols)
- for i in range(rows*col, rows*col+rows):
- if i < len(list):
- result = result + format(list[i]) + '<br>\n'
- result = result + '</td>'
- return '<table width="100%%" summary="list"><tr>%s</tr></table>' % result
- def grey(self, text): return '<font color="#909090">%s</font>' % text
- def namelink(self, name, *dicts):
- """Make a link for an identifier, given name-to-URL mappings."""
- for dict in dicts:
- if name in dict:
- return '<a href="%s">%s</a>' % (dict[name], name)
- return name
- def classlink(self, object, modname):
- """Make a link for a class."""
- name, module = object.__name__, sys.modules.get(object.__module__)
- if hasattr(module, name) and getattr(module, name) is object:
- return '<a href="%s.html#%s">%s</a>' % (
- module.__name__, name, classname(object, modname))
- return classname(object, modname)
- def modulelink(self, object):
- """Make a link for a module."""
- return '<a href="%s.html">%s</a>' % (object.__name__, object.__name__)
- def modpkglink(self, data):
- """Make a link for a module or package to display in an index."""
- name, path, ispackage, shadowed = data
- if shadowed:
- return self.grey(name)
- if path:
- url = '%s.%s.html' % (path, name)
- else:
- url = '%s.html' % name
- if ispackage:
- text = '<strong>%s</strong> (package)' % name
- else:
- text = name
- return '<a href="%s">%s</a>' % (url, text)
- def markup(self, text, escape=None, funcs={}, classes={}, methods={}):
- """Mark up some plain text, given a context of symbols to look for.
- Each context dictionary maps object names to anchor names."""
- escape = escape or self.escape
- results = []
- here = 0
- pattern = re.compile(r'\b((http|ftp)://\S+[\w/]|'
- r'RFC[- ]?(\d+)|'
- r'PEP[- ]?(\d+)|'
- r'(self\.)?(\w+))')
- while True:
- match = pattern.search(text, here)
- if not match: break
- start, end = match.span()
- results.append(escape(text[here:start]))
- all, scheme, rfc, pep, selfdot, name = match.groups()
- if scheme:
- url = escape(all).replace('"', '"')
- results.append('<a href="%s">%s</a>' % (url, url))
- elif rfc:
- url = 'http://www.rfc-editor.org/rfc/rfc%d.txt' % int(rfc)
- results.append('<a href="%s">%s</a>' % (url, escape(all)))
- elif pep:
- url = 'http://www.python.org/dev/peps/pep-%04d/' % int(pep)
- results.append('<a href="%s">%s</a>' % (url, escape(all)))
- elif text[end:end+1] == '(':
- results.append(self.namelink(name, methods, funcs, classes))
- elif selfdot:
- results.append('self.<strong>%s</strong>' % name)
- else:
- results.append(self.namelink(name, classes))
- here = end
- results.append(escape(text[here:]))
- return join(results, '')
- # ---------------------------------------------- type-specific routines
- def formattree(self, tree, modname, parent=None):
- """Produce HTML for a class tree as given by inspect.getclasstree()."""
- result = ''
- for entry in tree:
- if type(entry) is type(()):
- c, bases = entry
- result = result + '<dt><font face="helvetica, arial">'
- result = result + self.classlink(c, modname)
- if bases and bases != (parent,):
- parents = []
- for base in bases:
- parents.append(self.classlink(base, modname))
- result = result + '(' + join(parents, ', ') + ')'
- result = result + '\n</font></dt>'
- elif type(entry) is type([]):
- result = result + '<dd>\n%s</dd>\n' % self.formattree(
- entry, modname, c)
- return '<dl>\n%s</dl>\n' % result
- def docmodule(self, object, name=None, mod=None, *ignored):
- """Produce HTML documentation for a module object."""
- name = object.__name__ # ignore the passed-in name
- try:
- all = object.__all__
- except AttributeError:
- all = None
- 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, ', ')
- docloc = self.getdocloc(object)
- if docloc is not None:
- docloc = '<br><a href="%(docloc)s">Module Docs</a>' % locals()
- else:
- docloc = ''
- result = self.heading(
- head, '#ffffff', '#7799ee',
- '<a href=".">index</a><br>' + filelink + docloc)
- def isnonbuiltinmodule(obj):
- return inspect.ismodule(obj) and obj is not __builtin__
- modules = inspect.getmembers(object, isnonbuiltinmodule)
- classes, cdict = [], {}
- for key, value in inspect.getmembers(object, inspect.isclass):
- # if __all__ exists, believe it. Otherwise use old heuristic.
- if (all is not None or
- (inspect.getmodule(value) or object) is object):
- if visiblename(key, all, 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 key in cdict:
- cdict[key] = cdict[base] = modname + '.html#' + key
- funcs, fdict = [], {}
- for key, value in inspect.getmembers(object, inspect.isroutine):
- # if __all__ exists, believe it. Otherwise use old heuristic.
- if (all is not None or
- inspect.isbuiltin(value) or inspect.getmodule(value) is object):
- if visiblename(key, all, object):
- funcs.append((key, value))
- fdict[key] = '#-' + key
- if inspect.isfunction(value): fdict[value] = fdict[key]
- data = []
- for key, value in inspect.getmembers(object, isdata):
- if visiblename(key, all, object):
- data.append((key, value))
- doc = self.markup(getdoc(object), self.preformat, fdict, cdict)
- doc = doc and '<tt>%s</tt>' % doc
- result = result + '<p>%s</p>\n' % doc
- if hasattr(object, '__path__'):
- modpkgs = []
- for importer, modname, ispkg in pkgutil.iter_modules(object.__path__):
- modpkgs.append((modname, name, ispkg, 0))
- modpkgs.sort()
- contents = self.multicolumn(modpkgs, self.modpkglink)
- result = result + self.bigsection(
- 'Package Contents', '#ffffff', '#aa55cc', contents)
- elif modules:
- contents = self.multicolumn(
- modules, lambda key_value, s=self: s.modulelink(key_value[1]))
- result = result + self.bigsection(
- 'Modules', '#ffffff', '#aa55cc', contents)
- if classes:
- classlist = map(lambda key_value: key_value[1], 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 docclass(self, object, name=None, mod=None, funcs={}, classes={},
- *ignored):
- """Produce HTML documentation for a class object."""
- realname = object.__name__
- name = name or realname
- bases = object.__bases__
- contents = []
- push = contents.append
- # Cute little class to pump out a horizontal rule between sections.
- class HorizontalRule:
- def __init__(self):
- self.needone = 0
- def maybe(self):
- if self.needone:
- push('<hr>\n')
- self.needone = 1
- hr = HorizontalRule()
- # List the mro, if non-trivial.
- mro = deque(inspect.getmro(object))
- if len(mro) > 2:
- hr.maybe()
- push('<dl><dt>Method resolution order:</dt>\n')
- for base in mro:
- push('<dd>%s</dd>\n' % self.classlink(base,
- object.__module__))
- push('</dl>\n')
- def spill(msg, attrs, predicate):
- ok, attrs = _split_list(attrs, predicate)
- if ok:
- hr.maybe()
- push(msg)
- for name, kind, homecls, value in ok:
- try:
- value = getattr(object, name)
- except Exception:
- # Some descriptors may meet a failure in their __get__.
- # (bug #1785)
- push(self._docdescriptor(name, value, mod))
- else:
- push(self.document(value, name, mod,
- funcs, classes, mdict, object))
- push('\n')
- return attrs
- def spilldescriptors(msg, attrs, predicate):
- ok, attrs = _split_list(attrs, predicate)
- if ok:
- hr.maybe()
- push(msg)
- for name, kind, homecls, value in ok:
- push(self._docdescriptor(name, value, mod))
- return attrs
- def spilldata(msg, attrs, predicate):
- ok, attrs = _split_list(attrs, predicate)
- if ok:
- hr.maybe()
- push(msg)
- for name, kind, homecls, value in ok:
- base = self.docother(getattr(object, name), name, mod)
- if (hasattr(value, '__call__') or
- inspect.isdatadescriptor(value)):
- doc = getattr(value, "__doc__", None)
- else:
- doc = None
- if doc is None:
- push('<dl><dt>%s</dl>\n' % base)
- else:
- doc = self.markup(getdoc(value), self.preformat,
- funcs, classes, mdict)
- doc = '<dd><tt>%s</tt>' % doc
- push('<dl><dt>%s%s</dl>\n' % (base, doc))
- push('\n')
- return attrs
- attrs = filter(lambda data: visiblename(data[0], obj=object),
- classify_class_attrs(object))
- mdict = {}
- for key, kind, homecls, value in attrs:
- mdict[key] = anchor = '#' + name + '-' + key
- try:
- value = getattr(object, name)
- except Exception:
- # Some descriptors may meet a failure in their __get__.
- # (bug #1785)
- pass
- try:
- # The value may not be hashable (e.g., a data attr with
- # a dict or list value).
- mdict[value] = anchor
- except TypeError:
- pass
- while attrs:
- if mro:
- thisclass = mro.popleft()
- else:
- thisclass = attrs[0][2]
- attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass)
- if thisclass is __builtin__.object:
- attrs = inherited
- continue
- elif thisclass is object:
- tag = 'defined here'
- else:
- tag = 'inherited from %s' % self.classlink(thisclass,
- object.__module__)
- tag += ':<br>\n'
- # Sort attrs by name.
- try:
- attrs.sort(key=lambda t: t[0])
- except TypeError:
- attrs.sort(lambda t1, t2: cmp(t1[0], t2[0])) # 2.3 compat
- # Pump out the attrs, segregated by kind.
- attrs = spill('Methods %s' % tag, attrs,
- lambda t: t[1] == 'method')
- attrs = spill('Class methods %s' % tag, attrs,
- lambda t: t[1] == 'class method')
- attrs = spill('Static methods %s' % tag, attrs,
- lambda t: t[1] == 'static method')
- attrs = spilldescriptors('Data descriptors %s' % tag, attrs,
- lambda t: t[1] == 'data descriptor')
- attrs = spilldata('Data and other attributes %s' % tag, attrs,
- lambda t: t[1] == 'data')
- assert attrs == []
- attrs = inherited
- contents = ''.join(contents)
- if name == realname:
- title = '<a name="%s">class <strong>%s</strong></a>' % (
- name, realname)
- else:
- title = '<strong>%s</strong> = <a name="%s">class %s</a>' % (
- name, name, realname)
- if bases:
- parents = []
- for base in bases:
- parents.append(self.classlink(base, object.__module__))
- title = title + '(%s)' % join(parents, ', ')
- doc = self.markup(getdoc(object), self.preformat, funcs, classes, mdict)
- doc = doc and '<tt>%s<br> </tt>' % doc
- return self.section(title, '#000000', '#ffc8d8', contents, 3, doc)
- def formatvalue(self, object):
- """Format an argument default value as text."""
- return self.grey('=' + self.repr(object))
- def docroutine(self, object, name=None, mod=None,
- funcs={}, classes={}, methods={}, cl=None):
- """Produce HTML documentation for a function or method object."""
- realname = object.__name__
- name = name or realname
- anchor = (cl and cl.__name__ or '') + '-' + name
- note = ''
- skipdocs = 0
- if inspect.ismethod(object):
- imclass = object.im_class
- if cl:
- if imclass is not cl:
- note = ' from ' + self.classlink(imclass, mod)
- else:
- if object.im_self is not None:
- note = ' method of %s instance' % self.classlink(
- object.im_self.__class__, mod)
- else:
- note = ' unbound %s method' % self.classlink(imclass,mod)
- object = object.im_func
- if name == realname:
- title = '<a name="%s"><strong>%s</strong></a>' % (anchor, realname)
- else:
- if (cl and realname in cl.__dict__ and
- cl.__dict__[realname] is object):
- reallink = '<a href="#%s">%s</a>' % (
- cl.__name__ + '-' + realname, realname)
- skipdocs = 1
- else:
- reallink = realname
- title = '<a name="%s"><strong>%s</strong></a> = %s' % (
- anchor, name, reallink)
- if inspect.isfunction(object):
- args, varargs, varkw, defaults = inspect.getargspec(object)
- argspec = inspect.formatargspec(
- args, varargs, varkw, defaults, formatvalue=self.formatvalue)
- if realname == '<lambda>':
- title = '<strong>%s</strong> <em>lambda</em> ' % name
- argspec = argspec[1:-1] # remove parentheses
- else:
- argspec = '(...)'
- decl = title + argspec + (note and self.grey(
- '<font face="helvetica, arial">%s</font>' % note))
- if skipdocs:
- return '<dl><dt>%s</dt></dl>\n' % decl
- else:
- doc = self.markup(
- getdoc(object), self.preformat, funcs, classes, methods)
- doc = doc and '<dd><tt>%s</tt></dd>' % doc
- return '<dl><dt>%s</dt>%s</dl>\n' % (decl, doc)
- def _docdescriptor(self, name, value, mod):
- results = []
- push = results.append
- if name:
- push('<dl><dt><strong>%s</strong></dt>\n' % name)
- if value.__doc__ is not None:
- doc = self.markup(getdoc(value), self.preformat)
- push('<dd><tt>%s</tt></dd>\n' % doc)
- push('</dl>\n')
- return ''.join(results)
- def docproperty(self, object, name=None, mod=None, cl=None):
- """Produce html documentation for a property."""
- return self._docdescriptor(name, object, mod)
- def docother(self, object, name=None, mod=None, *ignored):
- """Produce HTML documentation for a data object."""
- lhs = name and '<strong>%s</strong> = ' % name or ''
- return lhs + self.repr(object)
- def docdata(self, object, name=None, mod=None, cl=None):
- """Produce html documentation for a data descriptor."""
- return self._docdescriptor(name, object, mod)
- def index(self, dir, shadowed=None):
- """Generate an HTML index for a directory of modules."""
- modpkgs = []
- if shadowed is None: shadowed = {}
- for importer, name, ispkg in pkgutil.iter_modules([dir]):
- modpkgs.append((name, '', ispkg, name in shadowed))
- shadowed[name] = 1
- modpkgs.sort()
- contents = self.multicolumn(modpkgs, self.modpkglink)
- return self.bigsection(dir, '#ffffff', '#ee77aa', contents)
- # -------------------------------------------- text documentation generator
- class TextRepr(Repr):
- """Class for safely making a text representation of a Python object."""
- def __init__(self):
- Repr.__init__(self)
- self.maxlist = self.maxtuple = 20
- self.maxdict = 10
- self.maxstring = self.maxother = 100
- def repr1(self, x, level):
- if hasattr(type(x), '__name__'):
- methodname = 'repr_' + join(split(type(x).__name__), '_')
- if hasattr(self, methodname):
- return getattr(self, methodname)(x, level)
- return cram(stripid(repr(x)), self.maxother)
- def repr_string(self, x, level):
- test = cram(x, self.maxstring)
- testrepr = repr(test)
- if '\\' in test and '\\' not in replace(testrepr, r'\\', ''):
- # Backslashes are only literal in the string and are never
- # needed to make any special characters, so show a raw string.
- return 'r' + testrepr[0] + test + testrepr[0]
- return testrepr
- repr_str = repr_string
- def repr_instance(self, x, level):
- try:
- return cram(stripid(repr(x)), self.maxstring)
- except:
- return '<%s instance>' % x.__class__.__name__
- class TextDoc(Doc):
- """Formatter class for text documentation."""
- # ------------------------------------------- text formatting utilities
- _repr_instance = TextRepr()
- repr = _repr_instance.repr
- def bold(self, text):
- """Format a string in bold by overstriking."""
- return join(map(lambda ch: ch + '\b' + ch, text), '')
- def indent(self, text, prefix=' '):
- """Indent text by prepending a given prefix to each line."""
- if not text: return ''
- lines = split(text, '\n')
- lines = map(lambda line, prefix=prefix: prefix + line, lines)
- if lines: lines[-1] = rstrip(lines[-1])
- return join(lines, '\n')
- def section(self, title, contents):
- """Format a section with a given heading."""
- return self.bold(title) + '\n' + rstrip(self.indent(contents)) + '\n\n'
- # ---------------------------------------------- type-specific routines
- def formattree(self, tree, modname, parent=None, prefix=''):
- """Render in text a class tree as returned by inspect.getclasstree()."""
- result = ''
- for entry in tree:
- if type(entry) is type(()):
- c, bases = entry
- result = result + prefix + classname(c, modname)
- if bases and bases != (parent,):
- parents = map(lambda c, m=modname: classname(c, m), bases)
- result = result + '(%s)' % join(parents, ', ')
- result = result + '\n'
- elif type(entry) is type([]):
- result = result + self.formattree(
- entry, modname, c, prefix + ' ')
- 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 = splitdoc(getdoc(object))
- result = self.section('NAME', name + (synop and ' - ' + synop))
- try:
- all = object.__all__
- except AttributeError:
- all = None
- try:
- file = inspect.getabsfile(object)
- except TypeError:
- file = '(built-in)'
- result = result + self.section('FILE', file)
- docloc = self.getdocloc(object)
- if docloc is not None:
- result = result + self.section('MODULE DOCS', docloc)
- if desc:
- result = result + self.section('DESCRIPTION', desc)
- classes = []
- for key, value in inspect.getmembers(object, inspect.isclass):
- # if __all__ exists, believe it. Otherwise use old heuristic.
- if (all is not None
- or (inspect.getmodule(value) or object) is object):
- if visiblename(key, all, object):
- classes.append((key, value))
- funcs = []
- for key, value in inspect.getmembers(object, inspect.isroutine):
- # if __all__ exists, believe it. Otherwise use old heuristic.
- if (all is not None or
- inspect.isbuiltin(value) or inspect.getmodule(value) is object):
- if visiblename(key, all, object):
- funcs.append((key, value))
- data = []
- for key, value in inspect.getmembers(object, isdata):
- if visiblename(key, all, object):
- data.append((key, value))
- modpkgs = []
- modpkgs_names = set()
- if hasattr(object, '__path__'):
- for importer, modname, ispkg in pkgutil.iter_modules(object.__path__):
- modpkgs_names.add(modname)
- if ispkg:
- modpkgs.append(modname + ' (package)')
- else:
- modpkgs.append(modname)
- modpkgs.sort()
- result = result + self.section(
- 'PACKAGE CONTENTS', join(modpkgs, '\n'))
- # Detect submodules as sometimes created by C extensions
- submodules = []
- for key, value in inspect.getmembers(object, inspect.ismodule):
- if value.__name__.startswith(name + '.') and key not in modpkgs_names:
- submodules.append(key)
- if submodules:
- submodules.sort()
- result = result + self.section(
- 'SUBMODULES', join(submodules, '\n'))
- if classes:
- classlist = map(lambda key_value: key_value[1], classes)
- contents = [self.formattree(
- inspect.getclasstree(classlist, 1), name)]
- for key, value in classes:
- contents.append(self.document(value, key, name))
- result = result + self.section('CLASSES', join(contents, '\n'))
- if funcs:
- contents = []
- for key, value in funcs:
- contents.append(self.document(value, key, name))
- result = result + self.section('FUNCTIONS', join(contents, '\n'))
- if data:
- contents = []
- for key, value in data:
- contents.append(self.docother(value, key, name, maxlen=70))
- result = result + self.section('DATA', join(contents, '\n'))
- 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 docclass(self, object, name=None, mod=None, *ignored):
- """Produce text documentation for a given class object."""
- realname = object.__name__
- name = name or realname
- bases = object.__bases__
- def makename(c, m=object.__module__):
- return classname(c, m)
- if name == realname:
- title = 'class ' + self.bold(realname)
- else:
- title = self.bold(name) + ' = class ' + realname
- if bases:
- parents = map(makename, bases)
- title = title + '(%s)' % join(parents, ', ')
- doc = getdoc(object)
- contents = doc and [doc + '\n'] or []
- push = contents.append
- # List the mro, if non-trivial.
- mro = deque(inspect.getmro(object))
- if len(mro) > 2:
- push("Method resolution order:")
- for base in mro:
- push(' ' + makename(base))
- push('')
- # Cute little class to pump out a horizontal rule between sections.
- class HorizontalRule:
- def __init__(self):
- self.needone = 0
- def maybe(self):
- if self.needone:
- push('-' * 70)
- self.needone = 1
- hr = HorizontalRule()
- def spill(msg, attrs, predicate):
- ok, attrs = _split_list(attrs, predicate)
- if ok:
- hr.maybe()
- push(msg)
- for name, kind, homecls, value in ok:
- try:
- value = getattr(object, name)
- except Exception:
- # Some descriptors may meet a failure in their __get__.
- # (bug #1785)
- push(self._docdescriptor(name, value, mod))
- else:
- push(self.document(value,
- name, mod, object))
- return attrs
- def spilldescriptors(msg, attrs, predicate):
- ok, attrs = _split_list(attrs, predicate)
- if ok:
- hr.maybe()
- push(msg)
- for name, kind, homecls, value in ok:
- push(self._docdescriptor(name, value, mod))
- return attrs
- def spilldata(msg, attrs, predicate):
- ok, attrs = _split_list(attrs, predicate)
- if ok:
- hr.maybe()
- push(msg)
- for name, kind, homecls, value in ok:
- if (hasattr(value, '__call__') or
- inspect.isdatadescriptor(value)):
- doc = getdoc(value)
- else:
- doc = None
- push(self.docother(getattr(object, name),
- name, mod, maxlen=70, doc=doc) + '\n')
- return attrs
- attrs = filter(lambda data: visiblename(data[0], obj=object),
- classify_class_attrs(object))
- while attrs:
- if mro:
- thisclass = mro.popleft()
- else:
- thisclass = attrs[0][2]
- attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass)
- if thisclass is __builtin__.object:
- attrs = inherited
- continue
- elif thisclass is object:
- tag = "defined here"
- else:
- tag = "inherited from %s" % classname(thisclass,
- object.__module__)
- # Sort attrs by name.
- attrs.sort()
- # Pump out the attrs, segregated by kind.
- attrs = spill("Methods %s:\n" % tag, attrs,
- lambda t: t[1] == 'method')
- attrs = spill("Class methods %s:\n" % tag, attrs,
- lambda t: t[1] == 'class method')
- attrs = spill("Static methods %s:\n" % tag, attrs,
- lambda t: t[1] == 'static method')
- attrs = spilldescriptors("Data descriptors %s:\n" % tag, attrs,
- lambda t: t[1] == 'data de…
Large files files are truncated, but you can click here to view the full file