[xbmc-addons] r2284 committed - [script.pydocs] - Version: 2.1.1...
15 views
Skip to first unread message
xbmc-...@googlecode.com
Jun 5, 2012, 1:00:00 PM6/5/12
to xbmc-addo...@googlegroups.com
Revision: 2284
Author: nuka...@gmail.com
Date: Tue Jun 5 09:59:46 2012
Log: [script.pydocs] - Version: 2.1.1
-changed: code cleanup and reordering
-removed: pydoc.py, it's included with python
http://code.google.com/p/xbmc-addons/source/detail?r=2284
Deleted:
/addons/script.pydocs/resources/lib/pydoc.py
Modified:
/addons/script.pydocs/addon.py
/addons/script.pydocs/addon.xml
/addons/script.pydocs/resources/language/English/strings.xml
=======================================
--- /addons/script.pydocs/resources/lib/pydoc.py Wed Jun 16 11:23:54 2010
+++ /dev/null
@@ -1,2274 +0,0 @@
-#!/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://www.python.org/doc/current/lib/
-
-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 <pi...@lfw.org>"
-__date__ = "26 February 2001"
-__version__ = "$Revision: 43347 $"
-__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__
-from repr import Repr
-from string import expandtabs, find, join, lower, split, strip, rfind,
rstrip
-from collections import deque
-
-# --------------------------------------------------------- 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.
- if _re_stripid.search(repr(Exception)):
- return _re_stripid.sub(r'\1', text)
- return 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):
- """Decide whether to show documentation on a variable."""
- # Certain special names are redundant.
- if name in ['__builtins__', '__doc__', '__file__', '__path__',
- '__module__', '__name__']: return 0
- # Private names are hidden, but special names are displayed.
- if name.startswith('__') and name.endswith('__'): 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('_')
-
-# ----------------------------------------------------- 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 synopsis(filename, cache={}):
- """Get the one-line summary out of a module file."""
- mtime = os.stat(filename).st_mtime
- lastupdate, result = cache.get(filename, (0, None))
- if 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 = split(module.__doc__ or '', '\n')[0]
- del sys.modules['__temp__']
- else: # text modules can be directly examined
- 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
- 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, value, tb)):
- 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 \
- split(lower(str(value)))[:2] == ['no', 'module']:
- # The module was not found.
- 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.
- 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 = 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://www.python.org/doc/current/lib")
- 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'))))):
- htmlfile = "module-%s.html" % object.__name__
- if docloc.startswith("http://"):
- docloc = "%s/%s" % (docloc.rstrip("/"), htmlfile)
- else:
- docloc = os.path.join(docloc, htmlfile)
- 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, (name, path, ispackage, shadowed)):
- """Make a link for a module or package to display in an index."""
- 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/peps/pep-%04d.html' % 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)
-
- modules = inspect.getmembers(object, inspect.ismodule)
-
- 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):
- 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):
- 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):
- 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 = []
- modnames = []
- for file in os.listdir(object.__path__[0]):
- path = os.path.join(object.__path__[0], file)
- modname = inspect.getmodulename(file)
- if modname != '__init__':
- if modname and modname not in modnames:
- modpkgs.append((modname, name, 0, 0))
- modnames.append(modname)
- elif 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)
- 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 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:
- push(self.document(getattr(object, name), name, mod,
- funcs, classes, mdict, object))
- push('\n')
- return attrs
-
- def spillproperties(msg, attrs, predicate):
- ok, attrs = _split_list(attrs, predicate)
- if ok:
- hr.maybe()
- push(msg)
- for name, kind, homecls, value in ok:
- push(self._docproperty(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 callable(value) 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 (name, kind, cls, value): visiblename(name),
- inspect.classify_class_attrs(object))
- mdict = {}
- for key, kind, homecls, value in attrs:
- mdict[key] = anchor = '#' + name + '-' + key
- value = getattr(object, key)
- 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.
- attrs.sort(key=lambda t: t[0])
-
- # 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 = spillproperties('Properties %s' % tag, attrs,
- lambda t: t[1] == 'property')
- 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:
- 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 _docproperty(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)
- for attr, tag in [('fget', '<em>get</em>'),
- ('fset', '<em>set</em>'),
- ('fdel', '<em>delete</em>')]:
- func = getattr(value, attr)
- if func is not None:
- base = self.document(func, tag, mod)
- push('<dd>%s</dd>\n' % base)
- push('</dl>\n')
-
- return ''.join(results)
-
- def docproperty(self, object, name=None, mod=None, cl=None):
- """Produce html documentation for a property."""
- return self._docproperty(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 index(self, dir, shadowed=None):
- """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
-
- # Package spam/__init__.py takes precedence over module spam.py.
- for file in files:
- path = os.path.join(dir, file)
- if ispackage(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: found(modname, 0)
-
- 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
-
***The diff for this file has been truncated for email.***
=======================================
--- /addons/script.pydocs/addon.py Sun Jun 3 16:29:40 2012
+++ /addons/script.pydocs/addon.py Tue Jun 5 09:59:46 2012
@@ -1,7 +1,7 @@
## PyDocs & PyPredefs Printer
import os
-import resources.lib.pydoc as pydoc
+import pydoc
import resources.lib.pypredefcom as pypredefcomp
import xbmc
import xbmcaddon
@@ -9,12 +9,14 @@
import xbmcplugin
import xbmcvfs
+ADDON_ID = "script.pydocs"
+
class DocsPrinter:
def __init__(self):
# get Addon object
- self.Addon = xbmcaddon.Addon(id="script.pydocs")
+ self.Addon = xbmcaddon.Addon(id=ADDON_ID)
# get user preferences
self.doc_path = self.Addon.getSetting("doc_path")
self.include_pydocs = (self.Addon.getSetting("include_pydocs")
== "true")
@@ -32,7 +34,7 @@
# set the doc_path setting in case the browse dialog was used
self.Addon.setSetting("doc_path", self.doc_path)
# modules
- modules =
[ "xbmc", "xbmcgui", "xbmcplugin", "xbmcaddon", "xbmcvfs" ]
+ modules =
["xbmc", "xbmcaddon", "xbmcgui", "xbmcplugin", "xbmcvfs"]
# enumerate thru and print our help docs
for count, module in enumerate(modules):
# include PyDocs
@@ -44,13 +46,18 @@
# update dialog
pDialog.update(count * (100 / len(modules)),
self.Addon.getLocalizedString(30711).format(msg="{module}.html
PyDoc".format(module=module)),
self.Addon.getLocalizedString(30712).format(msg=_path))
try:
+ # get our file object
+ pydoc_file = open(_path, "w")
+ except IOError as error:
+ # oops
+ xbmc.log("An error occurred saving
{module}.html PyDoc! ({error})".format(module=module, error=error),
xbmc.LOGERROR)
+ else:
# get our document object
doc = pydoc.HTMLDoc()
# print document
-
open(_path, "w").write(doc.document(eval(module)))
- except Exception as error:
- # oops
- xbmc.log("An error occurred saving
{module}.html PyDoc! ({error})".format(module=module, error=error),
xbmc.LOGERROR)
+ pydoc_file.write(doc.document(eval(module)))
+ # close file
+ pydoc_file.close()
# include PyPredefs
if (self.include_pypredefs):
@@ -63,13 +70,14 @@
try:
# get our file object
predefcomf = open(_path, "w")
+ except IOError as error:
+ # oops
+ xbmc.log("An error occurred saving
{module}.pypredef PyPredef! ({error})".format(module=module, error=error),
xbmc.LOGERROR)
+ else:
# print document
pypredefcomp.pypredefmodule(predefcomf,
eval(module))
# close file
- predefcomf.close();
- except Exception as error:
- # oops
- xbmc.log("An error occurred saving
{module}.pypredef PyPredef! ({error})".format(module=module, error=error),
xbmc.LOGERROR)
+ predefcomf.close()
#close dialog
pDialog.update(100)
@@ -81,7 +89,7 @@
try:
# make dir if it doesn't exist
if (not xbmcvfs.exists(_path)):
- xbmcvfs.mkdir(_path)
+ xbmcvfs.mkdirs(_path)
except:
# oops
xbmc.log("An error occurred making dir for {path}!
({error})".format(module=module, error=error), xbmc.LOGERROR)
@@ -100,6 +108,7 @@
"""
dialog = xbmcgui.Dialog()
value = dialog.browse(dlg_type, heading, shares, mask, use_thumbs,
treat_as_folder, default)
+
return value
=======================================
--- /addons/script.pydocs/addon.xml Sun Jun 3 16:29:40 2012
+++ /addons/script.pydocs/addon.xml Tue Jun 5 09:59:46 2012
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<addon id="script.pydocs" name="PyDocs & PyPredefs Printer"
version="2.1.0" provider-name="nuka1195 & jfcarroll">
+<addon id="script.pydocs" name="PyDocs & PyPredefs Printer"
version="2.1.1" provider-name="nuka1195 & jfcarroll">
<requires>
<import addon="xbmc.python" version="2.0"/>
</requires>
@@ -10,8 +10,9 @@
<platform>all</platform>
<nochangelog>true</nochangelog>
<nofanart>false</nofanart>
- <summary lang="en">Creates Python html help docs and PyDev
Predefined Completions.</summary>
- <description lang="en">Creates Python html help docs and PyDev
Predefined Completions for xbmc, xbmcgui, xbmcplugin, xbmcaddon and xbmcvfs
modules.</description>
- <disclaimer lang="en">Only accurate for the version of XBMC this
addon was run in.</disclaimer>
+ <noicon>false</noicon>
+ <summary lang="en">Creates Python html help docs and PyDev
Predefined Completions for XBMC Python modules.</summary>
+ <description lang="en">Creates Python html help docs and PyDev
Predefined Completions for XBMC Python modules. (xbmc, xbmcaddon, xbmcgui,
xbmcplugin and xbmcvfs)</description>
+ <disclaimer lang="en">Only accurate for the version of XBMC this
add-on was run in.</disclaimer>
</extension>
</addon>
=======================================
--- /addons/script.pydocs/resources/language/English/strings.xml Sun Jun 3
16:29:40 2012
+++ /addons/script.pydocs/resources/language/English/strings.xml Tue Jun 5
09:59:46 2012
@@ -67,7 +67,7 @@
<!-- button labels -->
<string id="30740">Reset</string>
<string id="30741">Previous</string>
- <string id="30742">Defaults</string>
+ <string id="30742">Default</string>
<string id="30745">Open</string>
<string id="30746">Save</string>
<!-- credits titles -->
Author: nuka...@gmail.com
Date: Tue Jun 5 09:59:46 2012
Log: [script.pydocs] - Version: 2.1.1
-changed: code cleanup and reordering
-removed: pydoc.py, it's included with python
http://code.google.com/p/xbmc-addons/source/detail?r=2284
Deleted:
/addons/script.pydocs/resources/lib/pydoc.py
Modified:
/addons/script.pydocs/addon.py
/addons/script.pydocs/addon.xml
/addons/script.pydocs/resources/language/English/strings.xml
=======================================
--- /addons/script.pydocs/resources/lib/pydoc.py Wed Jun 16 11:23:54 2010
+++ /dev/null
@@ -1,2274 +0,0 @@
-#!/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://www.python.org/doc/current/lib/
-
-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 <pi...@lfw.org>"
-__date__ = "26 February 2001"
-__version__ = "$Revision: 43347 $"
-__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__
-from repr import Repr
-from string import expandtabs, find, join, lower, split, strip, rfind,
rstrip
-from collections import deque
-
-# --------------------------------------------------------- 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.
- if _re_stripid.search(repr(Exception)):
- return _re_stripid.sub(r'\1', text)
- return 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):
- """Decide whether to show documentation on a variable."""
- # Certain special names are redundant.
- if name in ['__builtins__', '__doc__', '__file__', '__path__',
- '__module__', '__name__']: return 0
- # Private names are hidden, but special names are displayed.
- if name.startswith('__') and name.endswith('__'): 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('_')
-
-# ----------------------------------------------------- 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 synopsis(filename, cache={}):
- """Get the one-line summary out of a module file."""
- mtime = os.stat(filename).st_mtime
- lastupdate, result = cache.get(filename, (0, None))
- if 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 = split(module.__doc__ or '', '\n')[0]
- del sys.modules['__temp__']
- else: # text modules can be directly examined
- 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
- 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, value, tb)):
- 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 \
- split(lower(str(value)))[:2] == ['no', 'module']:
- # The module was not found.
- 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.
- 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 = 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://www.python.org/doc/current/lib")
- 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'))))):
- htmlfile = "module-%s.html" % object.__name__
- if docloc.startswith("http://"):
- docloc = "%s/%s" % (docloc.rstrip("/"), htmlfile)
- else:
- docloc = os.path.join(docloc, htmlfile)
- 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, (name, path, ispackage, shadowed)):
- """Make a link for a module or package to display in an index."""
- 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/peps/pep-%04d.html' % 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)
-
- modules = inspect.getmembers(object, inspect.ismodule)
-
- 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):
- 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):
- 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):
- 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 = []
- modnames = []
- for file in os.listdir(object.__path__[0]):
- path = os.path.join(object.__path__[0], file)
- modname = inspect.getmodulename(file)
- if modname != '__init__':
- if modname and modname not in modnames:
- modpkgs.append((modname, name, 0, 0))
- modnames.append(modname)
- elif 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)
- 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 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:
- push(self.document(getattr(object, name), name, mod,
- funcs, classes, mdict, object))
- push('\n')
- return attrs
-
- def spillproperties(msg, attrs, predicate):
- ok, attrs = _split_list(attrs, predicate)
- if ok:
- hr.maybe()
- push(msg)
- for name, kind, homecls, value in ok:
- push(self._docproperty(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 callable(value) 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 (name, kind, cls, value): visiblename(name),
- inspect.classify_class_attrs(object))
- mdict = {}
- for key, kind, homecls, value in attrs:
- mdict[key] = anchor = '#' + name + '-' + key
- value = getattr(object, key)
- 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.
- attrs.sort(key=lambda t: t[0])
-
- # 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 = spillproperties('Properties %s' % tag, attrs,
- lambda t: t[1] == 'property')
- 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:
- 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 _docproperty(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)
- for attr, tag in [('fget', '<em>get</em>'),
- ('fset', '<em>set</em>'),
- ('fdel', '<em>delete</em>')]:
- func = getattr(value, attr)
- if func is not None:
- base = self.document(func, tag, mod)
- push('<dd>%s</dd>\n' % base)
- push('</dl>\n')
-
- return ''.join(results)
-
- def docproperty(self, object, name=None, mod=None, cl=None):
- """Produce html documentation for a property."""
- return self._docproperty(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 index(self, dir, shadowed=None):
- """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
-
- # Package spam/__init__.py takes precedence over module spam.py.
- for file in files:
- path = os.path.join(dir, file)
- if ispackage(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: found(modname, 0)
-
- 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
-
***The diff for this file has been truncated for email.***
=======================================
--- /addons/script.pydocs/addon.py Sun Jun 3 16:29:40 2012
+++ /addons/script.pydocs/addon.py Tue Jun 5 09:59:46 2012
@@ -1,7 +1,7 @@
## PyDocs & PyPredefs Printer
import os
-import resources.lib.pydoc as pydoc
+import pydoc
import resources.lib.pypredefcom as pypredefcomp
import xbmc
import xbmcaddon
@@ -9,12 +9,14 @@
import xbmcplugin
import xbmcvfs
+ADDON_ID = "script.pydocs"
+
class DocsPrinter:
def __init__(self):
# get Addon object
- self.Addon = xbmcaddon.Addon(id="script.pydocs")
+ self.Addon = xbmcaddon.Addon(id=ADDON_ID)
# get user preferences
self.doc_path = self.Addon.getSetting("doc_path")
self.include_pydocs = (self.Addon.getSetting("include_pydocs")
== "true")
@@ -32,7 +34,7 @@
# set the doc_path setting in case the browse dialog was used
self.Addon.setSetting("doc_path", self.doc_path)
# modules
- modules =
[ "xbmc", "xbmcgui", "xbmcplugin", "xbmcaddon", "xbmcvfs" ]
+ modules =
["xbmc", "xbmcaddon", "xbmcgui", "xbmcplugin", "xbmcvfs"]
# enumerate thru and print our help docs
for count, module in enumerate(modules):
# include PyDocs
@@ -44,13 +46,18 @@
# update dialog
pDialog.update(count * (100 / len(modules)),
self.Addon.getLocalizedString(30711).format(msg="{module}.html
PyDoc".format(module=module)),
self.Addon.getLocalizedString(30712).format(msg=_path))
try:
+ # get our file object
+ pydoc_file = open(_path, "w")
+ except IOError as error:
+ # oops
+ xbmc.log("An error occurred saving
{module}.html PyDoc! ({error})".format(module=module, error=error),
xbmc.LOGERROR)
+ else:
# get our document object
doc = pydoc.HTMLDoc()
# print document
-
open(_path, "w").write(doc.document(eval(module)))
- except Exception as error:
- # oops
- xbmc.log("An error occurred saving
{module}.html PyDoc! ({error})".format(module=module, error=error),
xbmc.LOGERROR)
+ pydoc_file.write(doc.document(eval(module)))
+ # close file
+ pydoc_file.close()
# include PyPredefs
if (self.include_pypredefs):
@@ -63,13 +70,14 @@
try:
# get our file object
predefcomf = open(_path, "w")
+ except IOError as error:
+ # oops
+ xbmc.log("An error occurred saving
{module}.pypredef PyPredef! ({error})".format(module=module, error=error),
xbmc.LOGERROR)
+ else:
# print document
pypredefcomp.pypredefmodule(predefcomf,
eval(module))
# close file
- predefcomf.close();
- except Exception as error:
- # oops
- xbmc.log("An error occurred saving
{module}.pypredef PyPredef! ({error})".format(module=module, error=error),
xbmc.LOGERROR)
+ predefcomf.close()
#close dialog
pDialog.update(100)
@@ -81,7 +89,7 @@
try:
# make dir if it doesn't exist
if (not xbmcvfs.exists(_path)):
- xbmcvfs.mkdir(_path)
+ xbmcvfs.mkdirs(_path)
except:
# oops
xbmc.log("An error occurred making dir for {path}!
({error})".format(module=module, error=error), xbmc.LOGERROR)
@@ -100,6 +108,7 @@
"""
dialog = xbmcgui.Dialog()
value = dialog.browse(dlg_type, heading, shares, mask, use_thumbs,
treat_as_folder, default)
+
return value
=======================================
--- /addons/script.pydocs/addon.xml Sun Jun 3 16:29:40 2012
+++ /addons/script.pydocs/addon.xml Tue Jun 5 09:59:46 2012
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<addon id="script.pydocs" name="PyDocs & PyPredefs Printer"
version="2.1.0" provider-name="nuka1195 & jfcarroll">
+<addon id="script.pydocs" name="PyDocs & PyPredefs Printer"
version="2.1.1" provider-name="nuka1195 & jfcarroll">
<requires>
<import addon="xbmc.python" version="2.0"/>
</requires>
@@ -10,8 +10,9 @@
<platform>all</platform>
<nochangelog>true</nochangelog>
<nofanart>false</nofanart>
- <summary lang="en">Creates Python html help docs and PyDev
Predefined Completions.</summary>
- <description lang="en">Creates Python html help docs and PyDev
Predefined Completions for xbmc, xbmcgui, xbmcplugin, xbmcaddon and xbmcvfs
modules.</description>
- <disclaimer lang="en">Only accurate for the version of XBMC this
addon was run in.</disclaimer>
+ <noicon>false</noicon>
+ <summary lang="en">Creates Python html help docs and PyDev
Predefined Completions for XBMC Python modules.</summary>
+ <description lang="en">Creates Python html help docs and PyDev
Predefined Completions for XBMC Python modules. (xbmc, xbmcaddon, xbmcgui,
xbmcplugin and xbmcvfs)</description>
+ <disclaimer lang="en">Only accurate for the version of XBMC this
add-on was run in.</disclaimer>
</extension>
</addon>
=======================================
--- /addons/script.pydocs/resources/language/English/strings.xml Sun Jun 3
16:29:40 2012
+++ /addons/script.pydocs/resources/language/English/strings.xml Tue Jun 5
09:59:46 2012
@@ -67,7 +67,7 @@
<!-- button labels -->
<string id="30740">Reset</string>
<string id="30741">Previous</string>
- <string id="30742">Defaults</string>
+ <string id="30742">Default</string>
<string id="30745">Open</string>
<string id="30746">Save</string>
<!-- credits titles -->
Reply all
Reply to author
Forward
0 new messages