+++ /dev/null
-#!/usr/bin/env python\r
-# -*- coding: latin-1 -*-\r
-\r
-# Module 'pydoc' -- Generate Python documentation in HTML or text for interactive use.\r
-#\r
-# Copyright (c) 2015, Daryl McDaniel. All rights reserved.<BR>\r
-# Copyright (c) 2011 - 2012, Intel Corporation. All rights reserved.<BR>\r
-# This program and the accompanying materials are licensed and made available under\r
-# the terms and conditions of the BSD License that accompanies this distribution.\r
-# The full text of the license may be found at\r
-# http://opensource.org/licenses/bsd-license.\r
-#\r
-# THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
-# WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
-\r
-"""Generate Python documentation in HTML or text for interactive use.\r
-\r
-In the Python interpreter, do "from pydoc import help" to provide online\r
-help. Calling help(thing) on a Python object documents the object.\r
-\r
-Or, at the shell command line outside of Python:\r
-\r
-Run "pydoc <name>" to show documentation on something. <name> may be\r
-the name of a function, module, package, or a dotted reference to a\r
-class or function within a module or module in a package. If the\r
-argument contains a path segment delimiter (e.g. slash on Unix,\r
-backslash on Windows) it is treated as the path to a Python source file.\r
-\r
-Run "pydoc -k <keyword>" to search for a keyword in the synopsis lines\r
-of all available modules.\r
-\r
-Run "pydoc -p <port>" to start an HTTP server on a given port on the\r
-local machine to generate documentation web pages. Port number 0 can be\r
-used to get an arbitrary unused port.\r
-\r
-For platforms without a command line, "pydoc -g" starts the HTTP server\r
-and also pops up a little window for controlling it.\r
-\r
-Run "pydoc -w <name>" to write out the HTML documentation for a module\r
-to a file named "<name>.html".\r
-\r
-Module docs for core modules are assumed to be in\r
-\r
- http://docs.python.org/library/\r
-\r
-This can be overridden by setting the PYTHONDOCS environment variable\r
-to a different URL or to a local directory containing the Library\r
-Reference Manual pages.\r
-"""\r
-\r
-__author__ = "Ka-Ping Yee <ping@lfw.org>"\r
-__date__ = "26 February 2001"\r
-\r
-__version__ = "$Revision: 88564 $"\r
-__credits__ = """Guido van Rossum, for an excellent programming language.\r
-Tommy Burnette, the original creator of manpy.\r
-Paul Prescod, for all his work on onlinehelp.\r
-Richard Chamberlain, for the first implementation of textdoc.\r
-"""\r
-\r
-# Known bugs that can't be fixed here:\r
-# - imp.load_module() cannot be prevented from clobbering existing\r
-# loaded modules, so calling synopsis() on a binary module file\r
-# changes the contents of any existing module with the same name.\r
-# - If the __file__ attribute on a module is a relative path and\r
-# the current directory is changed with os.chdir(), an incorrect\r
-# path will be displayed.\r
-\r
-import sys, imp, os, re, types, inspect, __builtin__, pkgutil, warnings\r
-from repr import Repr\r
-from string import expandtabs, find, join, lower, split, strip, rfind, rstrip\r
-from traceback import extract_tb\r
-try:\r
- from collections import deque\r
-except ImportError:\r
- # Python 2.3 compatibility\r
- class deque(list):\r
- def popleft(self):\r
- return self.pop(0)\r
-\r
-# --------------------------------------------------------- common routines\r
-\r
-def pathdirs():\r
- """Convert sys.path into a list of absolute, existing, unique paths."""\r
- dirs = []\r
- normdirs = []\r
- for dir in sys.path:\r
- dir = os.path.abspath(dir or '.')\r
- normdir = os.path.normcase(dir)\r
- if normdir not in normdirs and os.path.isdir(dir):\r
- dirs.append(dir)\r
- normdirs.append(normdir)\r
- return dirs\r
-\r
-def getdoc(object):\r
- """Get the doc string or comments for an object."""\r
- result = inspect.getdoc(object) or inspect.getcomments(object)\r
- result = _encode(result)\r
- return result and re.sub('^ *\n', '', rstrip(result)) or ''\r
-\r
-def splitdoc(doc):\r
- """Split a doc string into a synopsis line (if any) and the rest."""\r
- lines = split(strip(doc), '\n')\r
- if len(lines) == 1:\r
- return lines[0], ''\r
- elif len(lines) >= 2 and not rstrip(lines[1]):\r
- return lines[0], join(lines[2:], '\n')\r
- return '', join(lines, '\n')\r
-\r
-def classname(object, modname):\r
- """Get a class name and qualify it with a module name if necessary."""\r
- name = object.__name__\r
- if object.__module__ != modname:\r
- name = object.__module__ + '.' + name\r
- return name\r
-\r
-def isdata(object):\r
- """Check if an object is of a type that probably means it's data."""\r
- return not (inspect.ismodule(object) or inspect.isclass(object) or\r
- inspect.isroutine(object) or inspect.isframe(object) or\r
- inspect.istraceback(object) or inspect.iscode(object))\r
-\r
-def replace(text, *pairs):\r
- """Do a series of global replacements on a string."""\r
- while pairs:\r
- text = join(split(text, pairs[0]), pairs[1])\r
- pairs = pairs[2:]\r
- return text\r
-\r
-def cram(text, maxlen):\r
- """Omit part of a string if needed to make it fit in a maximum length."""\r
- if len(text) > maxlen:\r
- pre = max(0, (maxlen-3)//2)\r
- post = max(0, maxlen-3-pre)\r
- return text[:pre] + '...' + text[len(text)-post:]\r
- return text\r
-\r
-_re_stripid = re.compile(r' at 0x[0-9a-f]{6,16}(>+)$', re.IGNORECASE)\r
-def stripid(text):\r
- """Remove the hexadecimal id from a Python object representation."""\r
- # The behaviour of %p is implementation-dependent in terms of case.\r
- return _re_stripid.sub(r'\1', text)\r
-\r
-def _is_some_method(obj):\r
- return inspect.ismethod(obj) or inspect.ismethoddescriptor(obj)\r
-\r
-def allmethods(cl):\r
- methods = {}\r
- for key, value in inspect.getmembers(cl, _is_some_method):\r
- methods[key] = 1\r
- for base in cl.__bases__:\r
- methods.update(allmethods(base)) # all your base are belong to us\r
- for key in methods.keys():\r
- methods[key] = getattr(cl, key)\r
- return methods\r
-\r
-def _split_list(s, predicate):\r
- """Split sequence s via predicate, and return pair ([true], [false]).\r
-\r
- The return value is a 2-tuple of lists,\r
- ([x for x in s if predicate(x)],\r
- [x for x in s if not predicate(x)])\r
- """\r
-\r
- yes = []\r
- no = []\r
- for x in s:\r
- if predicate(x):\r
- yes.append(x)\r
- else:\r
- no.append(x)\r
- return yes, no\r
-\r
-def visiblename(name, all=None, obj=None):\r
- """Decide whether to show documentation on a variable."""\r
- # Certain special names are redundant.\r
- _hidden_names = ('__builtins__', '__doc__', '__file__', '__path__',\r
- '__module__', '__name__', '__slots__', '__package__')\r
- if name in _hidden_names: return 0\r
- # Private names are hidden, but special names are displayed.\r
- if name.startswith('__') and name.endswith('__'): return 1\r
- # Namedtuples have public fields and methods with a single leading underscore\r
- if name.startswith('_') and hasattr(obj, '_fields'):\r
- return 1\r
- if all is not None:\r
- # only document that which the programmer exported in __all__\r
- return name in all\r
- else:\r
- return not name.startswith('_')\r
-\r
-def classify_class_attrs(object):\r
- """Wrap inspect.classify_class_attrs, with fixup for data descriptors."""\r
- def fixup(data):\r
- name, kind, cls, value = data\r
- if inspect.isdatadescriptor(value):\r
- kind = 'data descriptor'\r
- return name, kind, cls, value\r
- return map(fixup, inspect.classify_class_attrs(object))\r
-\r
-# ----------------------------------------------------- Unicode support helpers\r
-\r
-try:\r
- _unicode = unicode\r
-except NameError:\r
- # If Python is built without Unicode support, the unicode type\r
- # will not exist. Fake one that nothing will match, and make\r
- # the _encode function that do nothing.\r
- class _unicode(object):\r
- pass\r
- _encoding = 'ascii'\r
- def _encode(text, encoding='ascii'):\r
- return text\r
-else:\r
- import locale\r
- _encoding = locale.getpreferredencoding()\r
-\r
- def _encode(text, encoding=None):\r
- if isinstance(text, unicode):\r
- return text.encode(encoding or _encoding, 'xmlcharrefreplace')\r
- else:\r
- return text\r
-\r
-def _binstr(obj):\r
- # Ensure that we have an encoded (binary) string representation of obj,\r
- # even if it is a unicode string.\r
- if isinstance(obj, _unicode):\r
- return obj.encode(_encoding, 'xmlcharrefreplace')\r
- return str(obj)\r
-\r
-# ----------------------------------------------------- module manipulation\r
-\r
-def ispackage(path):\r
- """Guess whether a path refers to a package directory."""\r
- if os.path.isdir(path):\r
- for ext in ('.py', '.pyc', '.pyo'):\r
- if os.path.isfile(os.path.join(path, '__init__' + ext)):\r
- return True\r
- return False\r
-\r
-def source_synopsis(file):\r
- line = file.readline()\r
- while line[:1] == '#' or not strip(line):\r
- line = file.readline()\r
- if not line: break\r
- line = strip(line)\r
- if line[:4] == 'r"""': line = line[1:]\r
- if line[:3] == '"""':\r
- line = line[3:]\r
- if line[-1:] == '\\': line = line[:-1]\r
- while not strip(line):\r
- line = file.readline()\r
- if not line: break\r
- result = strip(split(line, '"""')[0])\r
- else: result = None\r
- return result\r
-\r
-def synopsis(filename, cache={}):\r
- """Get the one-line summary out of a module file."""\r
- mtime = os.stat(filename).st_mtime\r
- lastupdate, result = cache.get(filename, (None, None))\r
- if lastupdate is None or lastupdate < mtime:\r
- info = inspect.getmoduleinfo(filename)\r
- try:\r
- file = open(filename)\r
- except IOError:\r
- # module can't be opened, so skip it\r
- return None\r
- if info and 'b' in info[2]: # binary modules have to be imported\r
- try: module = imp.load_module('__temp__', file, filename, info[1:])\r
- except: return None\r
- result = module.__doc__.splitlines()[0] if module.__doc__ else None\r
- del sys.modules['__temp__']\r
- else: # text modules can be directly examined\r
- result = source_synopsis(file)\r
- file.close()\r
- cache[filename] = (mtime, result)\r
- return result\r
-\r
-class ErrorDuringImport(Exception):\r
- """Errors that occurred while trying to import something to document it."""\r
- def __init__(self, filename, exc_info):\r
- exc, value, tb = exc_info\r
- self.filename = filename\r
- self.exc = exc\r
- self.value = value\r
- self.tb = tb\r
-\r
- def __str__(self):\r
- exc = self.exc\r
- if type(exc) is types.ClassType:\r
- exc = exc.__name__\r
- return 'problem in %s - %s: %s' % (self.filename, exc, self.value)\r
-\r
-def importfile(path):\r
- """Import a Python source file or compiled file given its path."""\r
- magic = imp.get_magic()\r
- file = open(path, 'r')\r
- if file.read(len(magic)) == magic:\r
- kind = imp.PY_COMPILED\r
- else:\r
- kind = imp.PY_SOURCE\r
- file.close()\r
- filename = os.path.basename(path)\r
- name, ext = os.path.splitext(filename)\r
- file = open(path, 'r')\r
- try:\r
- module = imp.load_module(name, file, path, (ext, 'r', kind))\r
- except:\r
- raise ErrorDuringImport(path, sys.exc_info())\r
- file.close()\r
- return module\r
-\r
-def safeimport(path, forceload=0, cache={}):\r
- """Import a module; handle errors; return None if the module isn't found.\r
-\r
- If the module *is* found but an exception occurs, it's wrapped in an\r
- ErrorDuringImport exception and reraised. Unlike __import__, if a\r
- package path is specified, the module at the end of the path is returned,\r
- not the package at the beginning. If the optional 'forceload' argument\r
- is 1, we reload the module from disk (unless it's a dynamic extension)."""\r
- try:\r
- # If forceload is 1 and the module has been previously loaded from\r
- # disk, we always have to reload the module. Checking the file's\r
- # mtime isn't good enough (e.g. the module could contain a class\r
- # that inherits from another module that has changed).\r
- if forceload and path in sys.modules:\r
- if path not in sys.builtin_module_names:\r
- # Avoid simply calling reload() because it leaves names in\r
- # the currently loaded module lying around if they're not\r
- # defined in the new source file. Instead, remove the\r
- # module from sys.modules and re-import. Also remove any\r
- # submodules because they won't appear in the newly loaded\r
- # module's namespace if they're already in sys.modules.\r
- subs = [m for m in sys.modules if m.startswith(path + '.')]\r
- for key in [path] + subs:\r
- # Prevent garbage collection.\r
- cache[key] = sys.modules[key]\r
- del sys.modules[key]\r
- module = __import__(path)\r
- except:\r
- # Did the error occur before or after the module was found?\r
- (exc, value, tb) = info = sys.exc_info()\r
- if path in sys.modules:\r
- # An error occurred while executing the imported module.\r
- raise ErrorDuringImport(sys.modules[path].__file__, info)\r
- elif exc is SyntaxError:\r
- # A SyntaxError occurred before we could execute the module.\r
- raise ErrorDuringImport(value.filename, info)\r
- elif exc is ImportError and extract_tb(tb)[-1][2]=='safeimport':\r
- # The import error occurred directly in this function,\r
- # which means there is no such module in the path.\r
- return None\r
- else:\r
- # Some other error occurred during the importing process.\r
- raise ErrorDuringImport(path, sys.exc_info())\r
- for part in split(path, '.')[1:]:\r
- try: module = getattr(module, part)\r
- except AttributeError: return None\r
- return module\r
-\r
-# ---------------------------------------------------- formatter base class\r
-\r
-class Doc:\r
- def document(self, object, name=None, *args):\r
- """Generate documentation for an object."""\r
- args = (object, name) + args\r
- # 'try' clause is to attempt to handle the possibility that inspect\r
- # identifies something in a way that pydoc itself has issues handling;\r
- # think 'super' and how it is a descriptor (which raises the exception\r
- # by lacking a __name__ attribute) and an instance.\r
- if inspect.isgetsetdescriptor(object): return self.docdata(*args)\r
- if inspect.ismemberdescriptor(object): return self.docdata(*args)\r
- try:\r
- if inspect.ismodule(object): return self.docmodule(*args)\r
- if inspect.isclass(object): return self.docclass(*args)\r
- if inspect.isroutine(object): return self.docroutine(*args)\r
- except AttributeError:\r
- pass\r
- if isinstance(object, property): return self.docproperty(*args)\r
- return self.docother(*args)\r
-\r
- def fail(self, object, name=None, *args):\r
- """Raise an exception for unimplemented types."""\r
- message = "don't know how to document object%s of type %s" % (\r
- name and ' ' + repr(name), type(object).__name__)\r
- raise TypeError, message\r
-\r
- docmodule = docclass = docroutine = docother = docproperty = docdata = fail\r
-\r
- def getdocloc(self, object):\r
- """Return the location of module docs or None"""\r
-\r
- try:\r
- file = inspect.getabsfile(object)\r
- except TypeError:\r
- file = '(built-in)'\r
-\r
- docloc = os.environ.get("PYTHONDOCS",\r
- "http://docs.python.org/library")\r
- basedir = os.path.join(sys.exec_prefix, "lib",\r
- "python"+sys.version[0:3])\r
- if (isinstance(object, type(os)) and\r
- (object.__name__ in ('errno', 'exceptions', 'gc', 'imp',\r
- 'marshal', 'posix', 'signal', 'sys',\r
- 'thread', 'zipimport') or\r
- (file.startswith(basedir) and\r
- not file.startswith(os.path.join(basedir, 'site-packages')))) and\r
- object.__name__ not in ('xml.etree', 'test.pydoc_mod')):\r
- if docloc.startswith("http://"):\r
- docloc = "%s/%s" % (docloc.rstrip("/"), object.__name__)\r
- else:\r
- docloc = os.path.join(docloc, object.__name__ + ".html")\r
- else:\r
- docloc = None\r
- return docloc\r
-\r
-# -------------------------------------------- HTML documentation generator\r
-\r
-class HTMLRepr(Repr):\r
- """Class for safely making an HTML representation of a Python object."""\r
- def __init__(self):\r
- Repr.__init__(self)\r
- self.maxlist = self.maxtuple = 20\r
- self.maxdict = 10\r
- self.maxstring = self.maxother = 100\r
-\r
- def escape(self, text):\r
- return replace(text, '&', '&', '<', '<', '>', '>')\r
-\r
- def repr(self, object):\r
- return Repr.repr(self, object)\r
-\r
- def repr1(self, x, level):\r
- if hasattr(type(x), '__name__'):\r
- methodname = 'repr_' + join(split(type(x).__name__), '_')\r
- if hasattr(self, methodname):\r
- return getattr(self, methodname)(x, level)\r
- return self.escape(cram(stripid(repr(x)), self.maxother))\r
-\r
- def repr_string(self, x, level):\r
- test = cram(x, self.maxstring)\r
- testrepr = repr(test)\r
- if '\\' in test and '\\' not in replace(testrepr, r'\\', ''):\r
- # Backslashes are only literal in the string and are never\r
- # needed to make any special characters, so show a raw string.\r
- return 'r' + testrepr[0] + self.escape(test) + testrepr[0]\r
- return re.sub(r'((\\[\\abfnrtv\'"]|\\[0-9]..|\\x..|\\u....)+)',\r
- r'<font color="#c040c0">\1</font>',\r
- self.escape(testrepr))\r
-\r
- repr_str = repr_string\r
-\r
- def repr_instance(self, x, level):\r
- try:\r
- return self.escape(cram(stripid(repr(x)), self.maxstring))\r
- except:\r
- return self.escape('<%s instance>' % x.__class__.__name__)\r
-\r
- repr_unicode = repr_string\r
-\r
-class HTMLDoc(Doc):\r
- """Formatter class for HTML documentation."""\r
-\r
- # ------------------------------------------- HTML formatting utilities\r
-\r
- _repr_instance = HTMLRepr()\r
- repr = _repr_instance.repr\r
- escape = _repr_instance.escape\r
-\r
- def page(self, title, contents):\r
- """Format an HTML page."""\r
- return _encode('''\r
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">\r
-<html><head><title>Python: %s</title>\r
-<meta charset="utf-8">\r
-</head><body bgcolor="#f0f0f8">\r
-%s\r
-</body></html>''' % (title, contents), 'ascii')\r
-\r
- def heading(self, title, fgcol, bgcol, extras=''):\r
- """Format a page heading."""\r
- return '''\r
-<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="heading">\r
-<tr bgcolor="%s">\r
-<td valign=bottom> <br>\r
-<font color="%s" face="helvetica, arial"> <br>%s</font></td\r
-><td align=right valign=bottom\r
-><font color="%s" face="helvetica, arial">%s</font></td></tr></table>\r
- ''' % (bgcol, fgcol, title, fgcol, extras or ' ')\r
-\r
- def section(self, title, fgcol, bgcol, contents, width=6,\r
- prelude='', marginalia=None, gap=' '):\r
- """Format a section with a heading."""\r
- if marginalia is None:\r
- marginalia = '<tt>' + ' ' * width + '</tt>'\r
- result = '''<p>\r
-<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">\r
-<tr bgcolor="%s">\r
-<td colspan=3 valign=bottom> <br>\r
-<font color="%s" face="helvetica, arial">%s</font></td></tr>\r
- ''' % (bgcol, fgcol, title)\r
- if prelude:\r
- result = result + '''\r
-<tr bgcolor="%s"><td rowspan=2>%s</td>\r
-<td colspan=2>%s</td></tr>\r
-<tr><td>%s</td>''' % (bgcol, marginalia, prelude, gap)\r
- else:\r
- result = result + '''\r
-<tr><td bgcolor="%s">%s</td><td>%s</td>''' % (bgcol, marginalia, gap)\r
-\r
- return result + '\n<td width="100%%">%s</td></tr></table>' % contents\r
-\r
- def bigsection(self, title, *args):\r
- """Format a section with a big heading."""\r
- title = '<big><strong>%s</strong></big>' % title\r
- return self.section(title, *args)\r
-\r
- def preformat(self, text):\r
- """Format literal preformatted text."""\r
- text = self.escape(expandtabs(text))\r
- return replace(text, '\n\n', '\n \n', '\n\n', '\n \n',\r
- ' ', ' ', '\n', '<br>\n')\r
-\r
- def multicolumn(self, list, format, cols=4):\r
- """Format a list of items into a multi-column list."""\r
- result = ''\r
- rows = (len(list)+cols-1)//cols\r
- for col in range(cols):\r
- result = result + '<td width="%d%%" valign=top>' % (100//cols)\r
- for i in range(rows*col, rows*col+rows):\r
- if i < len(list):\r
- result = result + format(list[i]) + '<br>\n'\r
- result = result + '</td>'\r
- return '<table width="100%%" summary="list"><tr>%s</tr></table>' % result\r
-\r
- def grey(self, text): return '<font color="#909090">%s</font>' % text\r
-\r
- def namelink(self, name, *dicts):\r
- """Make a link for an identifier, given name-to-URL mappings."""\r
- for dict in dicts:\r
- if name in dict:\r
- return '<a href="%s">%s</a>' % (dict[name], name)\r
- return name\r
-\r
- def classlink(self, object, modname):\r
- """Make a link for a class."""\r
- name, module = object.__name__, sys.modules.get(object.__module__)\r
- if hasattr(module, name) and getattr(module, name) is object:\r
- return '<a href="%s.html#%s">%s</a>' % (\r
- module.__name__, name, classname(object, modname))\r
- return classname(object, modname)\r
-\r
- def modulelink(self, object):\r
- """Make a link for a module."""\r
- return '<a href="%s.html">%s</a>' % (object.__name__, object.__name__)\r
-\r
- def modpkglink(self, data):\r
- """Make a link for a module or package to display in an index."""\r
- name, path, ispackage, shadowed = data\r
- if shadowed:\r
- return self.grey(name)\r
- if path:\r
- url = '%s.%s.html' % (path, name)\r
- else:\r
- url = '%s.html' % name\r
- if ispackage:\r
- text = '<strong>%s</strong> (package)' % name\r
- else:\r
- text = name\r
- return '<a href="%s">%s</a>' % (url, text)\r
-\r
- def markup(self, text, escape=None, funcs={}, classes={}, methods={}):\r
- """Mark up some plain text, given a context of symbols to look for.\r
- Each context dictionary maps object names to anchor names."""\r
- escape = escape or self.escape\r
- results = []\r
- here = 0\r
- pattern = re.compile(r'\b((http|ftp)://\S+[\w/]|'\r
- r'RFC[- ]?(\d+)|'\r
- r'PEP[- ]?(\d+)|'\r
- r'(self\.)?(\w+))')\r
- while True:\r
- match = pattern.search(text, here)\r
- if not match: break\r
- start, end = match.span()\r
- results.append(escape(text[here:start]))\r
-\r
- all, scheme, rfc, pep, selfdot, name = match.groups()\r
- if scheme:\r
- url = escape(all).replace('"', '"')\r
- results.append('<a href="%s">%s</a>' % (url, url))\r
- elif rfc:\r
- url = 'http://www.rfc-editor.org/rfc/rfc%d.txt' % int(rfc)\r
- results.append('<a href="%s">%s</a>' % (url, escape(all)))\r
- elif pep:\r
- url = 'http://www.python.org/dev/peps/pep-%04d/' % int(pep)\r
- results.append('<a href="%s">%s</a>' % (url, escape(all)))\r
- elif selfdot:\r
- # Create a link for methods like 'self.method(...)'\r
- # and use <strong> for attributes like 'self.attr'\r
- if text[end:end+1] == '(':\r
- results.append('self.' + self.namelink(name, methods))\r
- else:\r
- results.append('self.<strong>%s</strong>' % name)\r
- elif text[end:end+1] == '(':\r
- results.append(self.namelink(name, methods, funcs, classes))\r
- else:\r
- results.append(self.namelink(name, classes))\r
- here = end\r
- results.append(escape(text[here:]))\r
- return join(results, '')\r
-\r
- # ---------------------------------------------- type-specific routines\r
-\r
- def formattree(self, tree, modname, parent=None):\r
- """Produce HTML for a class tree as given by inspect.getclasstree()."""\r
- result = ''\r
- for entry in tree:\r
- if type(entry) is type(()):\r
- c, bases = entry\r
- result = result + '<dt><font face="helvetica, arial">'\r
- result = result + self.classlink(c, modname)\r
- if bases and bases != (parent,):\r
- parents = []\r
- for base in bases:\r
- parents.append(self.classlink(base, modname))\r
- result = result + '(' + join(parents, ', ') + ')'\r
- result = result + '\n</font></dt>'\r
- elif type(entry) is type([]):\r
- result = result + '<dd>\n%s</dd>\n' % self.formattree(\r
- entry, modname, c)\r
- return '<dl>\n%s</dl>\n' % result\r
-\r
- def docmodule(self, object, name=None, mod=None, *ignored):\r
- """Produce HTML documentation for a module object."""\r
- name = object.__name__ # ignore the passed-in name\r
- try:\r
- all = object.__all__\r
- except AttributeError:\r
- all = None\r
- parts = split(name, '.')\r
- links = []\r
- for i in range(len(parts)-1):\r
- links.append(\r
- '<a href="%s.html"><font color="#ffffff">%s</font></a>' %\r
- (join(parts[:i+1], '.'), parts[i]))\r
- linkedname = join(links + parts[-1:], '.')\r
- head = '<big><big><strong>%s</strong></big></big>' % linkedname\r
- try:\r
- path = inspect.getabsfile(object)\r
- url = path\r
- if sys.platform == 'win32':\r
- import nturl2path\r
- url = nturl2path.pathname2url(path)\r
- filelink = '<a href="file:%s">%s</a>' % (url, path)\r
- except TypeError:\r
- filelink = '(built-in)'\r
- info = []\r
- if hasattr(object, '__version__'):\r
- version = _binstr(object.__version__)\r
- if version[:11] == '$' + 'Revision: ' and version[-1:] == '$':\r
- version = strip(version[11:-1])\r
- info.append('version %s' % self.escape(version))\r
- if hasattr(object, '__date__'):\r
- info.append(self.escape(_binstr(object.__date__)))\r
- if info:\r
- head = head + ' (%s)' % join(info, ', ')\r
- docloc = self.getdocloc(object)\r
- if docloc is not None:\r
- docloc = '<br><a href="%(docloc)s">Module Docs</a>' % locals()\r
- else:\r
- docloc = ''\r
- result = self.heading(\r
- head, '#ffffff', '#7799ee',\r
- '<a href=".">index</a><br>' + filelink + docloc)\r
-\r
- modules = inspect.getmembers(object, inspect.ismodule)\r
-\r
- classes, cdict = [], {}\r
- for key, value in inspect.getmembers(object, inspect.isclass):\r
- # if __all__ exists, believe it. Otherwise use old heuristic.\r
- if (all is not None or\r
- (inspect.getmodule(value) or object) is object):\r
- if visiblename(key, all, object):\r
- classes.append((key, value))\r
- cdict[key] = cdict[value] = '#' + key\r
- for key, value in classes:\r
- for base in value.__bases__:\r
- key, modname = base.__name__, base.__module__\r
- module = sys.modules.get(modname)\r
- if modname != name and module and hasattr(module, key):\r
- if getattr(module, key) is base:\r
- if not key in cdict:\r
- cdict[key] = cdict[base] = modname + '.html#' + key\r
- funcs, fdict = [], {}\r
- for key, value in inspect.getmembers(object, inspect.isroutine):\r
- # if __all__ exists, believe it. Otherwise use old heuristic.\r
- if (all is not None or\r
- inspect.isbuiltin(value) or inspect.getmodule(value) is object):\r
- if visiblename(key, all, object):\r
- funcs.append((key, value))\r
- fdict[key] = '#-' + key\r
- if inspect.isfunction(value): fdict[value] = fdict[key]\r
- data = []\r
- for key, value in inspect.getmembers(object, isdata):\r
- if visiblename(key, all, object):\r
- data.append((key, value))\r
-\r
- doc = self.markup(getdoc(object), self.preformat, fdict, cdict)\r
- doc = doc and '<tt>%s</tt>' % doc\r
- result = result + '<p>%s</p>\n' % doc\r
-\r
- if hasattr(object, '__path__'):\r
- modpkgs = []\r
- for importer, modname, ispkg in pkgutil.iter_modules(object.__path__):\r
- modpkgs.append((modname, name, ispkg, 0))\r
- modpkgs.sort()\r
- contents = self.multicolumn(modpkgs, self.modpkglink)\r
- result = result + self.bigsection(\r
- 'Package Contents', '#ffffff', '#aa55cc', contents)\r
- elif modules:\r
- contents = self.multicolumn(\r
- modules, lambda key_value, s=self: s.modulelink(key_value[1]))\r
- result = result + self.bigsection(\r
- 'Modules', '#ffffff', '#aa55cc', contents)\r
-\r
- if classes:\r
- classlist = map(lambda key_value: key_value[1], classes)\r
- contents = [\r
- self.formattree(inspect.getclasstree(classlist, 1), name)]\r
- for key, value in classes:\r
- contents.append(self.document(value, key, name, fdict, cdict))\r
- result = result + self.bigsection(\r
- 'Classes', '#ffffff', '#ee77aa', join(contents))\r
- if funcs:\r
- contents = []\r
- for key, value in funcs:\r
- contents.append(self.document(value, key, name, fdict, cdict))\r
- result = result + self.bigsection(\r
- 'Functions', '#ffffff', '#eeaa77', join(contents))\r
- if data:\r
- contents = []\r
- for key, value in data:\r
- contents.append(self.document(value, key))\r
- result = result + self.bigsection(\r
- 'Data', '#ffffff', '#55aa55', join(contents, '<br>\n'))\r
- if hasattr(object, '__author__'):\r
- contents = self.markup(_binstr(object.__author__), self.preformat)\r
- result = result + self.bigsection(\r
- 'Author', '#ffffff', '#7799ee', contents)\r
- if hasattr(object, '__credits__'):\r
- contents = self.markup(_binstr(object.__credits__), self.preformat)\r
- result = result + self.bigsection(\r
- 'Credits', '#ffffff', '#7799ee', contents)\r
-\r
- return result\r
-\r
- def docclass(self, object, name=None, mod=None, funcs={}, classes={},\r
- *ignored):\r
- """Produce HTML documentation for a class object."""\r
- realname = object.__name__\r
- name = name or realname\r
- bases = object.__bases__\r
-\r
- contents = []\r
- push = contents.append\r
-\r
- # Cute little class to pump out a horizontal rule between sections.\r
- class HorizontalRule:\r
- def __init__(self):\r
- self.needone = 0\r
- def maybe(self):\r
- if self.needone:\r
- push('<hr>\n')\r
- self.needone = 1\r
- hr = HorizontalRule()\r
-\r
- # List the mro, if non-trivial.\r
- mro = deque(inspect.getmro(object))\r
- if len(mro) > 2:\r
- hr.maybe()\r
- push('<dl><dt>Method resolution order:</dt>\n')\r
- for base in mro:\r
- push('<dd>%s</dd>\n' % self.classlink(base,\r
- object.__module__))\r
- push('</dl>\n')\r
-\r
- def spill(msg, attrs, predicate):\r
- ok, attrs = _split_list(attrs, predicate)\r
- if ok:\r
- hr.maybe()\r
- push(msg)\r
- for name, kind, homecls, value in ok:\r
- try:\r
- value = getattr(object, name)\r
- except Exception:\r
- # Some descriptors may meet a failure in their __get__.\r
- # (bug #1785)\r
- push(self._docdescriptor(name, value, mod))\r
- else:\r
- push(self.document(value, name, mod,\r
- funcs, classes, mdict, object))\r
- push('\n')\r
- return attrs\r
-\r
- def spilldescriptors(msg, attrs, predicate):\r
- ok, attrs = _split_list(attrs, predicate)\r
- if ok:\r
- hr.maybe()\r
- push(msg)\r
- for name, kind, homecls, value in ok:\r
- push(self._docdescriptor(name, value, mod))\r
- return attrs\r
-\r
- def spilldata(msg, attrs, predicate):\r
- ok, attrs = _split_list(attrs, predicate)\r
- if ok:\r
- hr.maybe()\r
- push(msg)\r
- for name, kind, homecls, value in ok:\r
- base = self.docother(getattr(object, name), name, mod)\r
- if (hasattr(value, '__call__') or\r
- inspect.isdatadescriptor(value)):\r
- doc = getattr(value, "__doc__", None)\r
- else:\r
- doc = None\r
- if doc is None:\r
- push('<dl><dt>%s</dl>\n' % base)\r
- else:\r
- doc = self.markup(getdoc(value), self.preformat,\r
- funcs, classes, mdict)\r
- doc = '<dd><tt>%s</tt>' % doc\r
- push('<dl><dt>%s%s</dl>\n' % (base, doc))\r
- push('\n')\r
- return attrs\r
-\r
- attrs = filter(lambda data: visiblename(data[0], obj=object),\r
- classify_class_attrs(object))\r
- mdict = {}\r
- for key, kind, homecls, value in attrs:\r
- mdict[key] = anchor = '#' + name + '-' + key\r
- try:\r
- value = getattr(object, name)\r
- except Exception:\r
- # Some descriptors may meet a failure in their __get__.\r
- # (bug #1785)\r
- pass\r
- try:\r
- # The value may not be hashable (e.g., a data attr with\r
- # a dict or list value).\r
- mdict[value] = anchor\r
- except TypeError:\r
- pass\r
-\r
- while attrs:\r
- if mro:\r
- thisclass = mro.popleft()\r
- else:\r
- thisclass = attrs[0][2]\r
- attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass)\r
-\r
- if thisclass is __builtin__.object:\r
- attrs = inherited\r
- continue\r
- elif thisclass is object:\r
- tag = 'defined here'\r
- else:\r
- tag = 'inherited from %s' % self.classlink(thisclass,\r
- object.__module__)\r
- tag += ':<br>\n'\r
-\r
- # Sort attrs by name.\r
- try:\r
- attrs.sort(key=lambda t: t[0])\r
- except TypeError:\r
- attrs.sort(lambda t1, t2: cmp(t1[0], t2[0])) # 2.3 compat\r
-\r
- # Pump out the attrs, segregated by kind.\r
- attrs = spill('Methods %s' % tag, attrs,\r
- lambda t: t[1] == 'method')\r
- attrs = spill('Class methods %s' % tag, attrs,\r
- lambda t: t[1] == 'class method')\r
- attrs = spill('Static methods %s' % tag, attrs,\r
- lambda t: t[1] == 'static method')\r
- attrs = spilldescriptors('Data descriptors %s' % tag, attrs,\r
- lambda t: t[1] == 'data descriptor')\r
- attrs = spilldata('Data and other attributes %s' % tag, attrs,\r
- lambda t: t[1] == 'data')\r
- assert attrs == []\r
- attrs = inherited\r
-\r
- contents = ''.join(contents)\r
-\r
- if name == realname:\r
- title = '<a name="%s">class <strong>%s</strong></a>' % (\r
- name, realname)\r
- else:\r
- title = '<strong>%s</strong> = <a name="%s">class %s</a>' % (\r
- name, name, realname)\r
- if bases:\r
- parents = []\r
- for base in bases:\r
- parents.append(self.classlink(base, object.__module__))\r
- title = title + '(%s)' % join(parents, ', ')\r
- doc = self.markup(getdoc(object), self.preformat, funcs, classes, mdict)\r
- doc = doc and '<tt>%s<br> </tt>' % doc\r
-\r
- return self.section(title, '#000000', '#ffc8d8', contents, 3, doc)\r
-\r
- def formatvalue(self, object):\r
- """Format an argument default value as text."""\r
- return self.grey('=' + self.repr(object))\r
-\r
- def docroutine(self, object, name=None, mod=None,\r
- funcs={}, classes={}, methods={}, cl=None):\r
- """Produce HTML documentation for a function or method object."""\r
- realname = object.__name__\r
- name = name or realname\r
- anchor = (cl and cl.__name__ or '') + '-' + name\r
- note = ''\r
- skipdocs = 0\r
- if inspect.ismethod(object):\r
- imclass = object.im_class\r
- if cl:\r
- if imclass is not cl:\r
- note = ' from ' + self.classlink(imclass, mod)\r
- else:\r
- if object.im_self is not None:\r
- note = ' method of %s instance' % self.classlink(\r
- object.im_self.__class__, mod)\r
- else:\r
- note = ' unbound %s method' % self.classlink(imclass,mod)\r
- object = object.im_func\r
-\r
- if name == realname:\r
- title = '<a name="%s"><strong>%s</strong></a>' % (anchor, realname)\r
- else:\r
- if (cl and realname in cl.__dict__ and\r
- cl.__dict__[realname] is object):\r
- reallink = '<a href="#%s">%s</a>' % (\r
- cl.__name__ + '-' + realname, realname)\r
- skipdocs = 1\r
- else:\r
- reallink = realname\r
- title = '<a name="%s"><strong>%s</strong></a> = %s' % (\r
- anchor, name, reallink)\r
- if inspect.isfunction(object):\r
- args, varargs, varkw, defaults = inspect.getargspec(object)\r
- argspec = inspect.formatargspec(\r
- args, varargs, varkw, defaults, formatvalue=self.formatvalue)\r
- if realname == '<lambda>':\r
- title = '<strong>%s</strong> <em>lambda</em> ' % name\r
- argspec = argspec[1:-1] # remove parentheses\r
- else:\r
- argspec = '(...)'\r
-\r
- decl = title + argspec + (note and self.grey(\r
- '<font face="helvetica, arial">%s</font>' % note))\r
-\r
- if skipdocs:\r
- return '<dl><dt>%s</dt></dl>\n' % decl\r
- else:\r
- doc = self.markup(\r
- getdoc(object), self.preformat, funcs, classes, methods)\r
- doc = doc and '<dd><tt>%s</tt></dd>' % doc\r
- return '<dl><dt>%s</dt>%s</dl>\n' % (decl, doc)\r
-\r
- def _docdescriptor(self, name, value, mod):\r
- results = []\r
- push = results.append\r
-\r
- if name:\r
- push('<dl><dt><strong>%s</strong></dt>\n' % name)\r
- if value.__doc__ is not None:\r
- doc = self.markup(getdoc(value), self.preformat)\r
- push('<dd><tt>%s</tt></dd>\n' % doc)\r
- push('</dl>\n')\r
-\r
- return ''.join(results)\r
-\r
- def docproperty(self, object, name=None, mod=None, cl=None):\r
- """Produce html documentation for a property."""\r
- return self._docdescriptor(name, object, mod)\r
-\r
- def docother(self, object, name=None, mod=None, *ignored):\r
- """Produce HTML documentation for a data object."""\r
- lhs = name and '<strong>%s</strong> = ' % name or ''\r
- return lhs + self.repr(object)\r
-\r
- def docdata(self, object, name=None, mod=None, cl=None):\r
- """Produce html documentation for a data descriptor."""\r
- return self._docdescriptor(name, object, mod)\r
-\r
- def index(self, dir, shadowed=None):\r
- """Generate an HTML index for a directory of modules."""\r
- modpkgs = []\r
- if shadowed is None: shadowed = {}\r
- for importer, name, ispkg in pkgutil.iter_modules([dir]):\r
- modpkgs.append((name, '', ispkg, name in shadowed))\r
- shadowed[name] = 1\r
-\r
- modpkgs.sort()\r
- contents = self.multicolumn(modpkgs, self.modpkglink)\r
- return self.bigsection(dir, '#ffffff', '#ee77aa', contents)\r
-\r
-# -------------------------------------------- text documentation generator\r
-\r
-class TextRepr(Repr):\r
- """Class for safely making a text representation of a Python object."""\r
- def __init__(self):\r
- Repr.__init__(self)\r
- self.maxlist = self.maxtuple = 20\r
- self.maxdict = 10\r
- self.maxstring = self.maxother = 100\r
-\r
- def repr1(self, x, level):\r
- if hasattr(type(x), '__name__'):\r
- methodname = 'repr_' + join(split(type(x).__name__), '_')\r
- if hasattr(self, methodname):\r
- return getattr(self, methodname)(x, level)\r
- return cram(stripid(repr(x)), self.maxother)\r
-\r
- def repr_string(self, x, level):\r
- test = cram(x, self.maxstring)\r
- testrepr = repr(test)\r
- if '\\' in test and '\\' not in replace(testrepr, r'\\', ''):\r
- # Backslashes are only literal in the string and are never\r
- # needed to make any special characters, so show a raw string.\r
- return 'r' + testrepr[0] + test + testrepr[0]\r
- return testrepr\r
-\r
- repr_str = repr_string\r
-\r
- def repr_instance(self, x, level):\r
- try:\r
- return cram(stripid(repr(x)), self.maxstring)\r
- except:\r
- return '<%s instance>' % x.__class__.__name__\r
-\r
-class TextDoc(Doc):\r
- """Formatter class for text documentation."""\r
-\r
- # ------------------------------------------- text formatting utilities\r
-\r
- _repr_instance = TextRepr()\r
- repr = _repr_instance.repr\r
-\r
- def bold(self, text):\r
- """Format a string in bold by overstriking."""\r
- return join(map(lambda ch: ch + '\b' + ch, text), '')\r
-\r
- def indent(self, text, prefix=' '):\r
- """Indent text by prepending a given prefix to each line."""\r
- if not text: return ''\r
- lines = split(text, '\n')\r
- lines = map(lambda line, prefix=prefix: prefix + line, lines)\r
- if lines: lines[-1] = rstrip(lines[-1])\r
- return join(lines, '\n')\r
-\r
- def section(self, title, contents):\r
- """Format a section with a given heading."""\r
- return self.bold(title) + '\n' + rstrip(self.indent(contents)) + '\n\n'\r
-\r
- # ---------------------------------------------- type-specific routines\r
-\r
- def formattree(self, tree, modname, parent=None, prefix=''):\r
- """Render in text a class tree as returned by inspect.getclasstree()."""\r
- result = ''\r
- for entry in tree:\r
- if type(entry) is type(()):\r
- c, bases = entry\r
- result = result + prefix + classname(c, modname)\r
- if bases and bases != (parent,):\r
- parents = map(lambda c, m=modname: classname(c, m), bases)\r
- result = result + '(%s)' % join(parents, ', ')\r
- result = result + '\n'\r
- elif type(entry) is type([]):\r
- result = result + self.formattree(\r
- entry, modname, c, prefix + ' ')\r
- return result\r
-\r
- def docmodule(self, object, name=None, mod=None):\r
- """Produce text documentation for a given module object."""\r
- name = object.__name__ # ignore the passed-in name\r
- synop, desc = splitdoc(getdoc(object))\r
- result = self.section('NAME', name + (synop and ' - ' + synop))\r
-\r
- try:\r
- all = object.__all__\r
- except AttributeError:\r
- all = None\r
-\r
- try:\r
- file = inspect.getabsfile(object)\r
- except TypeError:\r
- file = '(built-in)'\r
- result = result + self.section('FILE', file)\r
-\r
- docloc = self.getdocloc(object)\r
- if docloc is not None:\r
- result = result + self.section('MODULE DOCS', docloc)\r
-\r
- if desc:\r
- result = result + self.section('DESCRIPTION', desc)\r
-\r
- classes = []\r
- for key, value in inspect.getmembers(object, inspect.isclass):\r
- # if __all__ exists, believe it. Otherwise use old heuristic.\r
- if (all is not None\r
- or (inspect.getmodule(value) or object) is object):\r
- if visiblename(key, all, object):\r
- classes.append((key, value))\r
- funcs = []\r
- for key, value in inspect.getmembers(object, inspect.isroutine):\r
- # if __all__ exists, believe it. Otherwise use old heuristic.\r
- if (all is not None or\r
- inspect.isbuiltin(value) or inspect.getmodule(value) is object):\r
- if visiblename(key, all, object):\r
- funcs.append((key, value))\r
- data = []\r
- for key, value in inspect.getmembers(object, isdata):\r
- if visiblename(key, all, object):\r
- data.append((key, value))\r
-\r
- modpkgs = []\r
- modpkgs_names = set()\r
- if hasattr(object, '__path__'):\r
- for importer, modname, ispkg in pkgutil.iter_modules(object.__path__):\r
- modpkgs_names.add(modname)\r
- if ispkg:\r
- modpkgs.append(modname + ' (package)')\r
- else:\r
- modpkgs.append(modname)\r
-\r
- modpkgs.sort()\r
- result = result + self.section(\r
- 'PACKAGE CONTENTS', join(modpkgs, '\n'))\r
-\r
- # Detect submodules as sometimes created by C extensions\r
- submodules = []\r
- for key, value in inspect.getmembers(object, inspect.ismodule):\r
- if value.__name__.startswith(name + '.') and key not in modpkgs_names:\r
- submodules.append(key)\r
- if submodules:\r
- submodules.sort()\r
- result = result + self.section(\r
- 'SUBMODULES', join(submodules, '\n'))\r
-\r
- if classes:\r
- classlist = map(lambda key_value: key_value[1], classes)\r
- contents = [self.formattree(\r
- inspect.getclasstree(classlist, 1), name)]\r
- for key, value in classes:\r
- contents.append(self.document(value, key, name))\r
- result = result + self.section('CLASSES', join(contents, '\n'))\r
-\r
- if funcs:\r
- contents = []\r
- for key, value in funcs:\r
- contents.append(self.document(value, key, name))\r
- result = result + self.section('FUNCTIONS', join(contents, '\n'))\r
-\r
- if data:\r
- contents = []\r
- for key, value in data:\r
- contents.append(self.docother(value, key, name, maxlen=70))\r
- result = result + self.section('DATA', join(contents, '\n'))\r
-\r
- if hasattr(object, '__version__'):\r
- version = _binstr(object.__version__)\r
- if version[:11] == '$' + 'Revision: ' and version[-1:] == '$':\r
- version = strip(version[11:-1])\r
- result = result + self.section('VERSION', version)\r
- if hasattr(object, '__date__'):\r
- result = result + self.section('DATE', _binstr(object.__date__))\r
- if hasattr(object, '__author__'):\r
- result = result + self.section('AUTHOR', _binstr(object.__author__))\r
- if hasattr(object, '__credits__'):\r
- result = result + self.section('CREDITS', _binstr(object.__credits__))\r
- return result\r
-\r
- def docclass(self, object, name=None, mod=None, *ignored):\r
- """Produce text documentation for a given class object."""\r
- realname = object.__name__\r
- name = name or realname\r
- bases = object.__bases__\r
-\r
- def makename(c, m=object.__module__):\r
- return classname(c, m)\r
-\r
- if name == realname:\r
- title = 'class ' + self.bold(realname)\r
- else:\r
- title = self.bold(name) + ' = class ' + realname\r
- if bases:\r
- parents = map(makename, bases)\r
- title = title + '(%s)' % join(parents, ', ')\r
-\r
- doc = getdoc(object)\r
- contents = doc and [doc + '\n'] or []\r
- push = contents.append\r
-\r
- # List the mro, if non-trivial.\r
- mro = deque(inspect.getmro(object))\r
- if len(mro) > 2:\r
- push("Method resolution order:")\r
- for base in mro:\r
- push(' ' + makename(base))\r
- push('')\r
-\r
- # Cute little class to pump out a horizontal rule between sections.\r
- class HorizontalRule:\r
- def __init__(self):\r
- self.needone = 0\r
- def maybe(self):\r
- if self.needone:\r
- push('-' * 70)\r
- self.needone = 1\r
- hr = HorizontalRule()\r
-\r
- def spill(msg, attrs, predicate):\r
- ok, attrs = _split_list(attrs, predicate)\r
- if ok:\r
- hr.maybe()\r
- push(msg)\r
- for name, kind, homecls, value in ok:\r
- try:\r
- value = getattr(object, name)\r
- except Exception:\r
- # Some descriptors may meet a failure in their __get__.\r
- # (bug #1785)\r
- push(self._docdescriptor(name, value, mod))\r
- else:\r
- push(self.document(value,\r
- name, mod, object))\r
- return attrs\r
-\r
- def spilldescriptors(msg, attrs, predicate):\r
- ok, attrs = _split_list(attrs, predicate)\r
- if ok:\r
- hr.maybe()\r
- push(msg)\r
- for name, kind, homecls, value in ok:\r
- push(self._docdescriptor(name, value, mod))\r
- return attrs\r
-\r
- def spilldata(msg, attrs, predicate):\r
- ok, attrs = _split_list(attrs, predicate)\r
- if ok:\r
- hr.maybe()\r
- push(msg)\r
- for name, kind, homecls, value in ok:\r
- if (hasattr(value, '__call__') or\r
- inspect.isdatadescriptor(value)):\r
- doc = getdoc(value)\r
- else:\r
- doc = None\r
- push(self.docother(getattr(object, name),\r
- name, mod, maxlen=70, doc=doc) + '\n')\r
- return attrs\r
-\r
- attrs = filter(lambda data: visiblename(data[0], obj=object),\r
- classify_class_attrs(object))\r
- while attrs:\r
- if mro:\r
- thisclass = mro.popleft()\r
- else:\r
- thisclass = attrs[0][2]\r
- attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass)\r
-\r
- if thisclass is __builtin__.object:\r
- attrs = inherited\r
- continue\r
- elif thisclass is object:\r
- tag = "defined here"\r
- else:\r
- tag = "inherited from %s" % classname(thisclass,\r
- object.__module__)\r
-\r
- # Sort attrs by name.\r
- attrs.sort()\r
-\r
- # Pump out the attrs, segregated by kind.\r
- attrs = spill("Methods %s:\n" % tag, attrs,\r
- lambda t: t[1] == 'method')\r
- attrs = spill("Class methods %s:\n" % tag, attrs,\r
- lambda t: t[1] == 'class method')\r
- attrs = spill("Static methods %s:\n" % tag, attrs,\r
- lambda t: t[1] == 'static method')\r
- attrs = spilldescriptors("Data descriptors %s:\n" % tag, attrs,\r
- lambda t: t[1] == 'data descriptor')\r
- attrs = spilldata("Data and other attributes %s:\n" % tag, attrs,\r
- lambda t: t[1] == 'data')\r
- assert attrs == []\r
- attrs = inherited\r
-\r
- contents = '\n'.join(contents)\r
- if not contents:\r
- return title + '\n'\r
- return title + '\n' + self.indent(rstrip(contents), ' | ') + '\n'\r
-\r
- def formatvalue(self, object):\r
- """Format an argument default value as text."""\r
- return '=' + self.repr(object)\r
-\r
- def docroutine(self, object, name=None, mod=None, cl=None):\r
- """Produce text documentation for a function or method object."""\r
- realname = object.__name__\r
- name = name or realname\r
- note = ''\r
- skipdocs = 0\r
- if inspect.ismethod(object):\r
- imclass = object.im_class\r
- if cl:\r
- if imclass is not cl:\r
- note = ' from ' + classname(imclass, mod)\r
- else:\r
- if object.im_self is not None:\r
- note = ' method of %s instance' % classname(\r
- object.im_self.__class__, mod)\r
- else:\r
- note = ' unbound %s method' % classname(imclass,mod)\r
- object = object.im_func\r
-\r
- if name == realname:\r
- title = self.bold(realname)\r
- else:\r
- if (cl and realname in cl.__dict__ and\r
- cl.__dict__[realname] is object):\r
- skipdocs = 1\r
- title = self.bold(name) + ' = ' + realname\r
- if inspect.isfunction(object):\r
- args, varargs, varkw, defaults = inspect.getargspec(object)\r
- argspec = inspect.formatargspec(\r
- args, varargs, varkw, defaults, formatvalue=self.formatvalue)\r
- if realname == '<lambda>':\r
- title = self.bold(name) + ' lambda '\r
- argspec = argspec[1:-1] # remove parentheses\r
- else:\r
- argspec = '(...)'\r
- decl = title + argspec + note\r
-\r
- if skipdocs:\r
- return decl + '\n'\r
- else:\r
- doc = getdoc(object) or ''\r
- return decl + '\n' + (doc and rstrip(self.indent(doc)) + '\n')\r
-\r
- def _docdescriptor(self, name, value, mod):\r
- results = []\r
- push = results.append\r
-\r
- if name:\r
- push(self.bold(name))\r
- push('\n')\r
- doc = getdoc(value) or ''\r
- if doc:\r
- push(self.indent(doc))\r
- push('\n')\r
- return ''.join(results)\r
-\r
- def docproperty(self, object, name=None, mod=None, cl=None):\r
- """Produce text documentation for a property."""\r
- return self._docdescriptor(name, object, mod)\r
-\r
- def docdata(self, object, name=None, mod=None, cl=None):\r
- """Produce text documentation for a data descriptor."""\r
- return self._docdescriptor(name, object, mod)\r
-\r
- def docother(self, object, name=None, mod=None, parent=None, maxlen=None, doc=None):\r
- """Produce text documentation for a data object."""\r
- repr = self.repr(object)\r
- if maxlen:\r
- line = (name and name + ' = ' or '') + repr\r
- chop = maxlen - len(line)\r
- if chop < 0: repr = repr[:chop] + '...'\r
- line = (name and self.bold(name) + ' = ' or '') + repr\r
- if doc is not None:\r
- line += '\n' + self.indent(str(doc))\r
- return line\r
-\r
-# --------------------------------------------------------- user interfaces\r
-\r
-def pager(text):\r
- """The first time this is called, determine what kind of pager to use."""\r
- global pager\r
- pager = getpager()\r
- pager(text)\r
-\r
-def getpager():\r
- """Decide what method to use for paging through text."""\r
- if type(sys.stdout) is not types.FileType:\r
- return plainpager\r
- if not hasattr(sys.stdin, "isatty"):\r
- return plainpager\r
- if not sys.stdin.isatty() or not sys.stdout.isatty():\r
- return plainpager\r
- if 'PAGER' in os.environ:\r
- if sys.platform == 'win32': # pipes completely broken in Windows\r
- return lambda text: tempfilepager(plain(text), os.environ['PAGER'])\r
- elif sys.platform == 'uefi':\r
- return lambda text: tempfilepager(plain(text), os.environ['PAGER'])\r
- elif os.environ.get('TERM') in ('dumb', 'emacs'):\r
- return lambda text: pipepager(plain(text), os.environ['PAGER'])\r
- else:\r
- return lambda text: pipepager(text, os.environ['PAGER'])\r
- if os.environ.get('TERM') in ('dumb', 'emacs'):\r
- return plainpager\r
- if sys.platform == 'uefi':\r
- return plainpager\r
- if sys.platform == 'win32' or sys.platform.startswith('os2'):\r
- return lambda text: tempfilepager(plain(text), 'more <')\r
- if hasattr(os, 'system') and os.system('(less) 2>/dev/null') == 0:\r
- return lambda text: pipepager(text, 'less')\r
-\r
- import tempfile\r
- (fd, filename) = tempfile.mkstemp()\r
- os.close(fd)\r
- try:\r
- if hasattr(os, 'system') and os.system('more "%s"' % filename) == 0:\r
- return lambda text: pipepager(text, 'more')\r
- else:\r
- return ttypager\r
- finally:\r
- os.unlink(filename)\r
-\r
-def plain(text):\r
- """Remove boldface formatting from text."""\r
- return re.sub('.\b', '', text)\r
-\r
-def pipepager(text, cmd):\r
- """Page through text by feeding it to another program."""\r
- pipe = os.popen(cmd, 'w')\r
- try:\r
- pipe.write(_encode(text))\r
- pipe.close()\r
- except IOError:\r
- pass # Ignore broken pipes caused by quitting the pager program.\r
-\r
-def tempfilepager(text, cmd):\r
- """Page through text by invoking a program on a temporary file."""\r
- import tempfile\r
- filename = tempfile.mktemp()\r
- file = open(filename, 'w')\r
- file.write(_encode(text))\r
- file.close()\r
- try:\r
- os.system(cmd + ' "' + filename + '"')\r
- finally:\r
- os.unlink(filename)\r
-\r
-def ttypager(text):\r
- """Page through text on a text terminal."""\r
- lines = plain(_encode(plain(text), getattr(sys.stdout, 'encoding', _encoding))).split('\n')\r
- try:\r
- import tty\r
- fd = sys.stdin.fileno()\r
- old = tty.tcgetattr(fd)\r
- tty.setcbreak(fd)\r
- getchar = lambda: sys.stdin.read(1)\r
- except (ImportError, AttributeError):\r
- tty = None\r
- getchar = lambda: sys.stdin.readline()[:-1][:1]\r
-\r
- try:\r
- try:\r
- h = int(os.environ.get('LINES', 0))\r
- except ValueError:\r
- h = 0\r
- if h <= 1:\r
- h = 25\r
- r = inc = h - 1\r
- sys.stdout.write(join(lines[:inc], '\n') + '\n')\r
- while lines[r:]:\r
- sys.stdout.write('-- more --')\r
- sys.stdout.flush()\r
- c = getchar()\r
-\r
- if c in ('q', 'Q'):\r
- sys.stdout.write('\r \r')\r
- break\r
- elif c in ('\r', '\n'):\r
- sys.stdout.write('\r \r' + lines[r] + '\n')\r
- r = r + 1\r
- continue\r
- if c in ('b', 'B', '\x1b'):\r
- r = r - inc - inc\r
- if r < 0: r = 0\r
- sys.stdout.write('\n' + join(lines[r:r+inc], '\n') + '\n')\r
- r = r + inc\r
-\r
- finally:\r
- if tty:\r
- tty.tcsetattr(fd, tty.TCSAFLUSH, old)\r
-\r
-def plainpager(text):\r
- """Simply print unformatted text. This is the ultimate fallback."""\r
- sys.stdout.write(_encode(plain(text), getattr(sys.stdout, 'encoding', _encoding)))\r
-\r
-def describe(thing):\r
- """Produce a short description of the given thing."""\r
- if inspect.ismodule(thing):\r
- if thing.__name__ in sys.builtin_module_names:\r
- return 'built-in module ' + thing.__name__\r
- if hasattr(thing, '__path__'):\r
- return 'package ' + thing.__name__\r
- else:\r
- return 'module ' + thing.__name__\r
- if inspect.isbuiltin(thing):\r
- return 'built-in function ' + thing.__name__\r
- if inspect.isgetsetdescriptor(thing):\r
- return 'getset descriptor %s.%s.%s' % (\r
- thing.__objclass__.__module__, thing.__objclass__.__name__,\r
- thing.__name__)\r
- if inspect.ismemberdescriptor(thing):\r
- return 'member descriptor %s.%s.%s' % (\r
- thing.__objclass__.__module__, thing.__objclass__.__name__,\r
- thing.__name__)\r
- if inspect.isclass(thing):\r
- return 'class ' + thing.__name__\r
- if inspect.isfunction(thing):\r
- return 'function ' + thing.__name__\r
- if inspect.ismethod(thing):\r
- return 'method ' + thing.__name__\r
- if type(thing) is types.InstanceType:\r
- return 'instance of ' + thing.__class__.__name__\r
- return type(thing).__name__\r
-\r
-def locate(path, forceload=0):\r
- """Locate an object by name or dotted path, importing as necessary."""\r
- parts = [part for part in split(path, '.') if part]\r
- module, n = None, 0\r
- while n < len(parts):\r
- nextmodule = safeimport(join(parts[:n+1], '.'), forceload)\r
- if nextmodule: module, n = nextmodule, n + 1\r
- else: break\r
- if module:\r
- object = module\r
- else:\r
- object = __builtin__\r
- for part in parts[n:]:\r
- try:\r
- object = getattr(object, part)\r
- except AttributeError:\r
- return None\r
- return object\r
-\r
-# --------------------------------------- interactive interpreter interface\r
-\r
-text = TextDoc()\r
-html = HTMLDoc()\r
-\r
-class _OldStyleClass: pass\r
-_OLD_INSTANCE_TYPE = type(_OldStyleClass())\r
-\r
-def resolve(thing, forceload=0):\r
- """Given an object or a path to an object, get the object and its name."""\r
- if isinstance(thing, str):\r
- object = locate(thing, forceload)\r
- if object is None:\r
- raise ImportError, 'no Python documentation found for %r' % thing\r
- return object, thing\r
- else:\r
- name = getattr(thing, '__name__', None)\r
- return thing, name if isinstance(name, str) else None\r
-\r
-def render_doc(thing, title='Python Library Documentation: %s', forceload=0):\r
- """Render text documentation, given an object or a path to an object."""\r
- object, name = resolve(thing, forceload)\r
- desc = describe(object)\r
- module = inspect.getmodule(object)\r
- if name and '.' in name:\r
- desc += ' in ' + name[:name.rfind('.')]\r
- elif module and module is not object:\r
- desc += ' in module ' + module.__name__\r
- if type(object) is _OLD_INSTANCE_TYPE:\r
- # If the passed object is an instance of an old-style class,\r
- # document its available methods instead of its value.\r
- object = object.__class__\r
- elif not (inspect.ismodule(object) or\r
- inspect.isclass(object) or\r
- inspect.isroutine(object) or\r
- inspect.isgetsetdescriptor(object) or\r
- inspect.ismemberdescriptor(object) or\r
- isinstance(object, property)):\r
- # If the passed object is a piece of data or an instance,\r
- # document its available methods instead of its value.\r
- object = type(object)\r
- desc += ' object'\r
- return title % desc + '\n\n' + text.document(object, name)\r
-\r
-def doc(thing, title='Python Library Documentation: %s', forceload=0):\r
- """Display text documentation, given an object or a path to an object."""\r
- try:\r
- pager(render_doc(thing, title, forceload))\r
- except (ImportError, ErrorDuringImport), value:\r
- print value\r
-\r
-def writedoc(thing, forceload=0):\r
- """Write HTML documentation to a file in the current directory."""\r
- try:\r
- object, name = resolve(thing, forceload)\r
- page = html.page(describe(object), html.document(object, name))\r
- file = open(name + '.html', 'w')\r
- file.write(page)\r
- file.close()\r
- print 'wrote', name + '.html'\r
- except (ImportError, ErrorDuringImport), value:\r
- print value\r
-\r
-def writedocs(dir, pkgpath='', done=None):\r
- """Write out HTML documentation for all modules in a directory tree."""\r
- if done is None: done = {}\r
- for importer, modname, ispkg in pkgutil.walk_packages([dir], pkgpath):\r
- writedoc(modname)\r
- return\r
-\r
-class Helper:\r
-\r
- # These dictionaries map a topic name to either an alias, or a tuple\r
- # (label, seealso-items). The "label" is the label of the corresponding\r
- # section in the .rst file under Doc/ and an index into the dictionary\r
- # in pydoc_data/topics.py.\r
- #\r
- # CAUTION: if you change one of these dictionaries, be sure to adapt the\r
- # list of needed labels in Doc/tools/pyspecific.py and\r
- # regenerate the pydoc_data/topics.py file by running\r
- # make pydoc-topics\r
- # in Doc/ and copying the output file into the Lib/ directory.\r
-\r
- keywords = {\r
- 'and': 'BOOLEAN',\r
- 'as': 'with',\r
- 'assert': ('assert', ''),\r
- 'break': ('break', 'while for'),\r
- 'class': ('class', 'CLASSES SPECIALMETHODS'),\r
- 'continue': ('continue', 'while for'),\r
- 'def': ('function', ''),\r
- 'del': ('del', 'BASICMETHODS'),\r
- 'elif': 'if',\r
- 'else': ('else', 'while for'),\r
- 'except': 'try',\r
- 'exec': ('exec', ''),\r
- 'finally': 'try',\r
- 'for': ('for', 'break continue while'),\r
- 'from': 'import',\r
- 'global': ('global', 'NAMESPACES'),\r
- 'if': ('if', 'TRUTHVALUE'),\r
- 'import': ('import', 'MODULES'),\r
- 'in': ('in', 'SEQUENCEMETHODS2'),\r
- 'is': 'COMPARISON',\r
- 'lambda': ('lambda', 'FUNCTIONS'),\r
- 'not': 'BOOLEAN',\r
- 'or': 'BOOLEAN',\r
- 'pass': ('pass', ''),\r
- 'print': ('print', ''),\r
- 'raise': ('raise', 'EXCEPTIONS'),\r
- 'return': ('return', 'FUNCTIONS'),\r
- 'try': ('try', 'EXCEPTIONS'),\r
- 'while': ('while', 'break continue if TRUTHVALUE'),\r
- 'with': ('with', 'CONTEXTMANAGERS EXCEPTIONS yield'),\r
- 'yield': ('yield', ''),\r
- }\r
- # Either add symbols to this dictionary or to the symbols dictionary\r
- # directly: Whichever is easier. They are merged later.\r
- _symbols_inverse = {\r
- 'STRINGS' : ("'", "'''", "r'", "u'", '"""', '"', 'r"', 'u"'),\r
- 'OPERATORS' : ('+', '-', '*', '**', '/', '//', '%', '<<', '>>', '&',\r
- '|', '^', '~', '<', '>', '<=', '>=', '==', '!=', '<>'),\r
- 'COMPARISON' : ('<', '>', '<=', '>=', '==', '!=', '<>'),\r
- 'UNARY' : ('-', '~'),\r
- 'AUGMENTEDASSIGNMENT' : ('+=', '-=', '*=', '/=', '%=', '&=', '|=',\r
- '^=', '<<=', '>>=', '**=', '//='),\r
- 'BITWISE' : ('<<', '>>', '&', '|', '^', '~'),\r
- 'COMPLEX' : ('j', 'J')\r
- }\r
- symbols = {\r
- '%': 'OPERATORS FORMATTING',\r
- '**': 'POWER',\r
- ',': 'TUPLES LISTS FUNCTIONS',\r
- '.': 'ATTRIBUTES FLOAT MODULES OBJECTS',\r
- '...': 'ELLIPSIS',\r
- ':': 'SLICINGS DICTIONARYLITERALS',\r
- '@': 'def class',\r
- '\\': 'STRINGS',\r
- '_': 'PRIVATENAMES',\r
- '__': 'PRIVATENAMES SPECIALMETHODS',\r
- '`': 'BACKQUOTES',\r
- '(': 'TUPLES FUNCTIONS CALLS',\r
- ')': 'TUPLES FUNCTIONS CALLS',\r
- '[': 'LISTS SUBSCRIPTS SLICINGS',\r
- ']': 'LISTS SUBSCRIPTS SLICINGS'\r
- }\r
- for topic, symbols_ in _symbols_inverse.iteritems():\r
- for symbol in symbols_:\r
- topics = symbols.get(symbol, topic)\r
- if topic not in topics:\r
- topics = topics + ' ' + topic\r
- symbols[symbol] = topics\r
-\r
- topics = {\r
- 'TYPES': ('types', 'STRINGS UNICODE NUMBERS SEQUENCES MAPPINGS '\r
- 'FUNCTIONS CLASSES MODULES FILES inspect'),\r
- 'STRINGS': ('strings', 'str UNICODE SEQUENCES STRINGMETHODS FORMATTING '\r
- 'TYPES'),\r
- 'STRINGMETHODS': ('string-methods', 'STRINGS FORMATTING'),\r
- 'FORMATTING': ('formatstrings', 'OPERATORS'),\r
- 'UNICODE': ('strings', 'encodings unicode SEQUENCES STRINGMETHODS '\r
- 'FORMATTING TYPES'),\r
- 'NUMBERS': ('numbers', 'INTEGER FLOAT COMPLEX TYPES'),\r
- 'INTEGER': ('integers', 'int range'),\r
- 'FLOAT': ('floating', 'float math'),\r
- 'COMPLEX': ('imaginary', 'complex cmath'),\r
- 'SEQUENCES': ('typesseq', 'STRINGMETHODS FORMATTING xrange LISTS'),\r
- 'MAPPINGS': 'DICTIONARIES',\r
- 'FUNCTIONS': ('typesfunctions', 'def TYPES'),\r
- 'METHODS': ('typesmethods', 'class def CLASSES TYPES'),\r
- 'CODEOBJECTS': ('bltin-code-objects', 'compile FUNCTIONS TYPES'),\r
- 'TYPEOBJECTS': ('bltin-type-objects', 'types TYPES'),\r
- 'FRAMEOBJECTS': 'TYPES',\r
- 'TRACEBACKS': 'TYPES',\r
- 'NONE': ('bltin-null-object', ''),\r
- 'ELLIPSIS': ('bltin-ellipsis-object', 'SLICINGS'),\r
- 'FILES': ('bltin-file-objects', ''),\r
- 'SPECIALATTRIBUTES': ('specialattrs', ''),\r
- 'CLASSES': ('types', 'class SPECIALMETHODS PRIVATENAMES'),\r
- 'MODULES': ('typesmodules', 'import'),\r
- 'PACKAGES': 'import',\r
- 'EXPRESSIONS': ('operator-summary', 'lambda or and not in is BOOLEAN '\r
- 'COMPARISON BITWISE SHIFTING BINARY FORMATTING POWER '\r
- 'UNARY ATTRIBUTES SUBSCRIPTS SLICINGS CALLS TUPLES '\r
- 'LISTS DICTIONARIES BACKQUOTES'),\r
- 'OPERATORS': 'EXPRESSIONS',\r
- 'PRECEDENCE': 'EXPRESSIONS',\r
- 'OBJECTS': ('objects', 'TYPES'),\r
- 'SPECIALMETHODS': ('specialnames', 'BASICMETHODS ATTRIBUTEMETHODS '\r
- 'CALLABLEMETHODS SEQUENCEMETHODS1 MAPPINGMETHODS '\r
- 'SEQUENCEMETHODS2 NUMBERMETHODS CLASSES'),\r
- 'BASICMETHODS': ('customization', 'cmp hash repr str SPECIALMETHODS'),\r
- 'ATTRIBUTEMETHODS': ('attribute-access', 'ATTRIBUTES SPECIALMETHODS'),\r
- 'CALLABLEMETHODS': ('callable-types', 'CALLS SPECIALMETHODS'),\r
- 'SEQUENCEMETHODS1': ('sequence-types', 'SEQUENCES SEQUENCEMETHODS2 '\r
- 'SPECIALMETHODS'),\r
- 'SEQUENCEMETHODS2': ('sequence-methods', 'SEQUENCES SEQUENCEMETHODS1 '\r
- 'SPECIALMETHODS'),\r
- 'MAPPINGMETHODS': ('sequence-types', 'MAPPINGS SPECIALMETHODS'),\r
- 'NUMBERMETHODS': ('numeric-types', 'NUMBERS AUGMENTEDASSIGNMENT '\r
- 'SPECIALMETHODS'),\r
- 'EXECUTION': ('execmodel', 'NAMESPACES DYNAMICFEATURES EXCEPTIONS'),\r
- 'NAMESPACES': ('naming', 'global ASSIGNMENT DELETION DYNAMICFEATURES'),\r
- 'DYNAMICFEATURES': ('dynamic-features', ''),\r
- 'SCOPING': 'NAMESPACES',\r
- 'FRAMES': 'NAMESPACES',\r
- 'EXCEPTIONS': ('exceptions', 'try except finally raise'),\r
- 'COERCIONS': ('coercion-rules','CONVERSIONS'),\r
- 'CONVERSIONS': ('conversions', 'COERCIONS'),\r
- 'IDENTIFIERS': ('identifiers', 'keywords SPECIALIDENTIFIERS'),\r
- 'SPECIALIDENTIFIERS': ('id-classes', ''),\r
- 'PRIVATENAMES': ('atom-identifiers', ''),\r
- 'LITERALS': ('atom-literals', 'STRINGS BACKQUOTES NUMBERS '\r
- 'TUPLELITERALS LISTLITERALS DICTIONARYLITERALS'),\r
- 'TUPLES': 'SEQUENCES',\r
- 'TUPLELITERALS': ('exprlists', 'TUPLES LITERALS'),\r
- 'LISTS': ('typesseq-mutable', 'LISTLITERALS'),\r
- 'LISTLITERALS': ('lists', 'LISTS LITERALS'),\r
- 'DICTIONARIES': ('typesmapping', 'DICTIONARYLITERALS'),\r
- 'DICTIONARYLITERALS': ('dict', 'DICTIONARIES LITERALS'),\r
- 'BACKQUOTES': ('string-conversions', 'repr str STRINGS LITERALS'),\r
- 'ATTRIBUTES': ('attribute-references', 'getattr hasattr setattr '\r
- 'ATTRIBUTEMETHODS'),\r
- 'SUBSCRIPTS': ('subscriptions', 'SEQUENCEMETHODS1'),\r
- 'SLICINGS': ('slicings', 'SEQUENCEMETHODS2'),\r
- 'CALLS': ('calls', 'EXPRESSIONS'),\r
- 'POWER': ('power', 'EXPRESSIONS'),\r
- 'UNARY': ('unary', 'EXPRESSIONS'),\r
- 'BINARY': ('binary', 'EXPRESSIONS'),\r
- 'SHIFTING': ('shifting', 'EXPRESSIONS'),\r
- 'BITWISE': ('bitwise', 'EXPRESSIONS'),\r
- 'COMPARISON': ('comparisons', 'EXPRESSIONS BASICMETHODS'),\r
- 'BOOLEAN': ('booleans', 'EXPRESSIONS TRUTHVALUE'),\r
- 'ASSERTION': 'assert',\r
- 'ASSIGNMENT': ('assignment', 'AUGMENTEDASSIGNMENT'),\r
- 'AUGMENTEDASSIGNMENT': ('augassign', 'NUMBERMETHODS'),\r
- 'DELETION': 'del',\r
- 'PRINTING': 'print',\r
- 'RETURNING': 'return',\r
- 'IMPORTING': 'import',\r
- 'CONDITIONAL': 'if',\r
- 'LOOPING': ('compound', 'for while break continue'),\r
- 'TRUTHVALUE': ('truth', 'if while and or not BASICMETHODS'),\r
- 'DEBUGGING': ('debugger', 'pdb'),\r
- 'CONTEXTMANAGERS': ('context-managers', 'with'),\r
- }\r
-\r
- def __init__(self, input=None, output=None):\r
- self._input = input\r
- self._output = output\r
-\r
- input = property(lambda self: self._input or sys.stdin)\r
- output = property(lambda self: self._output or sys.stdout)\r
-\r
- def __repr__(self):\r
- if inspect.stack()[1][3] == '?':\r
- self()\r
- return ''\r
- return '<pydoc.Helper instance>'\r
-\r
- _GoInteractive = object()\r
- def __call__(self, request=_GoInteractive):\r
- if request is not self._GoInteractive:\r
- self.help(request)\r
- else:\r
- self.intro()\r
- self.interact()\r
- self.output.write('''\r
-You are now leaving help and returning to the Python interpreter.\r
-If you want to ask for help on a particular object directly from the\r
-interpreter, you can type "help(object)". Executing "help('string')"\r
-has the same effect as typing a particular string at the help> prompt.\r
-''')\r
-\r
- def interact(self):\r
- self.output.write('\n')\r
- while True:\r
- try:\r
- request = self.getline('help> ')\r
- if not request: break\r
- except (KeyboardInterrupt, EOFError):\r
- break\r
- request = strip(replace(request, '"', '', "'", ''))\r
- if lower(request) in ('q', 'quit'): break\r
- self.help(request)\r
-\r
- def getline(self, prompt):\r
- """Read one line, using raw_input when available."""\r
- if self.input is sys.stdin:\r
- return raw_input(prompt)\r
- else:\r
- self.output.write(prompt)\r
- self.output.flush()\r
- return self.input.readline()\r
-\r
- def help(self, request):\r
- if type(request) is type(''):\r
- request = request.strip()\r
- if request == 'help': self.intro()\r
- elif request == 'keywords': self.listkeywords()\r
- elif request == 'symbols': self.listsymbols()\r
- elif request == 'topics': self.listtopics()\r
- elif request == 'modules': self.listmodules()\r
- elif request[:8] == 'modules ':\r
- self.listmodules(split(request)[1])\r
- elif request in self.symbols: self.showsymbol(request)\r
- elif request in self.keywords: self.showtopic(request)\r
- elif request in self.topics: self.showtopic(request)\r
- elif request: doc(request, 'Help on %s:')\r
- elif isinstance(request, Helper): self()\r
- else: doc(request, 'Help on %s:')\r
- self.output.write('\n')\r
-\r
- def intro(self):\r
- self.output.write('''\r
-Welcome to Python %s! This is the online help utility.\r
-\r
-If this is your first time using Python, you should definitely check out\r
-the tutorial on the Internet at http://docs.python.org/%s/tutorial/.\r
-\r
-Enter the name of any module, keyword, or topic to get help on writing\r
-Python programs and using Python modules. To quit this help utility and\r
-return to the interpreter, just type "quit".\r
-\r
-To get a list of available modules, keywords, or topics, type "modules",\r
-"keywords", or "topics". Each module also comes with a one-line summary\r
-of what it does; to list the modules whose summaries contain a given word\r
-such as "spam", type "modules spam".\r
-''' % tuple([sys.version[:3]]*2))\r
-\r
- def list(self, items, columns=4, width=80):\r
- items = items[:]\r
- items.sort()\r
- colw = width / columns\r
- rows = (len(items) + columns - 1) / columns\r
- for row in range(rows):\r
- for col in range(columns):\r
- i = col * rows + row\r
- if i < len(items):\r
- self.output.write(items[i])\r
- if col < columns - 1:\r
- self.output.write(' ' + ' ' * (colw-1 - len(items[i])))\r
- self.output.write('\n')\r
-\r
- def listkeywords(self):\r
- self.output.write('''\r
-Here is a list of the Python keywords. Enter any keyword to get more help.\r
-\r
-''')\r
- self.list(self.keywords.keys())\r
-\r
- def listsymbols(self):\r
- self.output.write('''\r
-Here is a list of the punctuation symbols which Python assigns special meaning\r
-to. Enter any symbol to get more help.\r
-\r
-''')\r
- self.list(self.symbols.keys())\r
-\r
- def listtopics(self):\r
- self.output.write('''\r
-Here is a list of available topics. Enter any topic name to get more help.\r
-\r
-''')\r
- self.list(self.topics.keys())\r
-\r
- def showtopic(self, topic, more_xrefs=''):\r
- try:\r
- import pydoc_data.topics\r
- except ImportError:\r
- self.output.write('''\r
-Sorry, topic and keyword documentation is not available because the\r
-module "pydoc_data.topics" could not be found.\r
-''')\r
- return\r
- target = self.topics.get(topic, self.keywords.get(topic))\r
- if not target:\r
- self.output.write('no documentation found for %s\n' % repr(topic))\r
- return\r
- if type(target) is type(''):\r
- return self.showtopic(target, more_xrefs)\r
-\r
- label, xrefs = target\r
- try:\r
- doc = pydoc_data.topics.topics[label]\r
- except KeyError:\r
- self.output.write('no documentation found for %s\n' % repr(topic))\r
- return\r
- pager(strip(doc) + '\n')\r
- if more_xrefs:\r
- xrefs = (xrefs or '') + ' ' + more_xrefs\r
- if xrefs:\r
- import StringIO, formatter\r
- buffer = StringIO.StringIO()\r
- formatter.DumbWriter(buffer).send_flowing_data(\r
- 'Related help topics: ' + join(split(xrefs), ', ') + '\n')\r
- self.output.write('\n%s\n' % buffer.getvalue())\r
-\r
- def showsymbol(self, symbol):\r
- target = self.symbols[symbol]\r
- topic, _, xrefs = target.partition(' ')\r
- self.showtopic(topic, xrefs)\r
-\r
- def listmodules(self, key=''):\r
- if key:\r
- self.output.write('''\r
-Here is a list of matching modules. Enter any module name to get more help.\r
-\r
-''')\r
- apropos(key)\r
- else:\r
- self.output.write('''\r
-Please wait a moment while I gather a list of all available modules...\r
-\r
-''')\r
- modules = {}\r
- def callback(path, modname, desc, modules=modules):\r
- if modname and modname[-9:] == '.__init__':\r
- modname = modname[:-9] + ' (package)'\r
- if find(modname, '.') < 0:\r
- modules[modname] = 1\r
- def onerror(modname):\r
- callback(None, modname, None)\r
- ModuleScanner().run(callback, onerror=onerror)\r
- self.list(modules.keys())\r
- self.output.write('''\r
-Enter any module name to get more help. Or, type "modules spam" to search\r
-for modules whose descriptions contain the word "spam".\r
-''')\r
-\r
-help = Helper()\r
-\r
-class Scanner:\r
- """A generic tree iterator."""\r
- def __init__(self, roots, children, descendp):\r
- self.roots = roots[:]\r
- self.state = []\r
- self.children = children\r
- self.descendp = descendp\r
-\r
- def next(self):\r
- if not self.state:\r
- if not self.roots:\r
- return None\r
- root = self.roots.pop(0)\r
- self.state = [(root, self.children(root))]\r
- node, children = self.state[-1]\r
- if not children:\r
- self.state.pop()\r
- return self.next()\r
- child = children.pop(0)\r
- if self.descendp(child):\r
- self.state.append((child, self.children(child)))\r
- return child\r
-\r
-\r
-class ModuleScanner:\r
- """An interruptible scanner that searches module synopses."""\r
-\r
- def run(self, callback, key=None, completer=None, onerror=None):\r
- if key: key = lower(key)\r
- self.quit = False\r
- seen = {}\r
-\r
- for modname in sys.builtin_module_names:\r
- if modname != '__main__':\r
- seen[modname] = 1\r
- if key is None:\r
- callback(None, modname, '')\r
- else:\r
- desc = split(__import__(modname).__doc__ or '', '\n')[0]\r
- if find(lower(modname + ' - ' + desc), key) >= 0:\r
- callback(None, modname, desc)\r
-\r
- for importer, modname, ispkg in pkgutil.walk_packages(onerror=onerror):\r
- if self.quit:\r
- break\r
- if key is None:\r
- callback(None, modname, '')\r
- else:\r
- loader = importer.find_module(modname)\r
- if hasattr(loader,'get_source'):\r
- import StringIO\r
- desc = source_synopsis(\r
- StringIO.StringIO(loader.get_source(modname))\r
- ) or ''\r
- if hasattr(loader,'get_filename'):\r
- path = loader.get_filename(modname)\r
- else:\r
- path = None\r
- else:\r
- module = loader.load_module(modname)\r
- desc = module.__doc__.splitlines()[0] if module.__doc__ else ''\r
- path = getattr(module,'__file__',None)\r
- if find(lower(modname + ' - ' + desc), key) >= 0:\r
- callback(path, modname, desc)\r
-\r
- if completer:\r
- completer()\r
-\r
-def apropos(key):\r
- """Print all the one-line module summaries that contain a substring."""\r
- def callback(path, modname, desc):\r
- if modname[-9:] == '.__init__':\r
- modname = modname[:-9] + ' (package)'\r
- print modname, desc and '- ' + desc\r
- def onerror(modname):\r
- pass\r
- with warnings.catch_warnings():\r
- warnings.filterwarnings('ignore') # ignore problems during import\r
- ModuleScanner().run(callback, key, onerror=onerror)\r
-\r
-# --------------------------------------------------- web browser interface\r
-\r
-def serve(port, callback=None, completer=None):\r
- import BaseHTTPServer, mimetools, select\r
-\r
- # Patch up mimetools.Message so it doesn't break if rfc822 is reloaded.\r
- class Message(mimetools.Message):\r
- def __init__(self, fp, seekable=1):\r
- Message = self.__class__\r
- Message.__bases__[0].__bases__[0].__init__(self, fp, seekable)\r
- self.encodingheader = self.getheader('content-transfer-encoding')\r
- self.typeheader = self.getheader('content-type')\r
- self.parsetype()\r
- self.parseplist()\r
-\r
- class DocHandler(BaseHTTPServer.BaseHTTPRequestHandler):\r
- def send_document(self, title, contents):\r
- try:\r
- self.send_response(200)\r
- self.send_header('Content-Type', 'text/html')\r
- self.end_headers()\r
- self.wfile.write(html.page(title, contents))\r
- except IOError: pass\r
-\r
- def do_GET(self):\r
- path = self.path\r
- if path[-5:] == '.html': path = path[:-5]\r
- if path[:1] == '/': path = path[1:]\r
- if path and path != '.':\r
- try:\r
- obj = locate(path, forceload=1)\r
- except ErrorDuringImport, value:\r
- self.send_document(path, html.escape(str(value)))\r
- return\r
- if obj:\r
- self.send_document(describe(obj), html.document(obj, path))\r
- else:\r
- self.send_document(path,\r
-'no Python documentation found for %s' % repr(path))\r
- else:\r
- heading = html.heading(\r
-'<big><big><strong>Python: Index of Modules</strong></big></big>',\r
-'#ffffff', '#7799ee')\r
- def bltinlink(name):\r
- return '<a href="%s.html">%s</a>' % (name, name)\r
- names = filter(lambda x: x != '__main__',\r
- sys.builtin_module_names)\r
- contents = html.multicolumn(names, bltinlink)\r
- indices = ['<p>' + html.bigsection(\r
- 'Built-in Modules', '#ffffff', '#ee77aa', contents)]\r
-\r
- seen = {}\r
- for dir in sys.path:\r
- indices.append(html.index(dir, seen))\r
- contents = heading + join(indices) + '''<p align=right>\r
-<font color="#909090" face="helvetica, arial"><strong>\r
-pydoc</strong> by Ka-Ping Yee <ping@lfw.org></font>'''\r
- self.send_document('Index of Modules', contents)\r
-\r
- def log_message(self, *args): pass\r
-\r
- class DocServer(BaseHTTPServer.HTTPServer):\r
- def __init__(self, port, callback):\r
- host = 'localhost'\r
- self.address = (host, port)\r
- self.callback = callback\r
- self.base.__init__(self, self.address, self.handler)\r
-\r
- def serve_until_quit(self):\r
- import select\r
- self.quit = False\r
- while not self.quit:\r
- rd, wr, ex = select.select([self.socket.fileno()], [], [], 1)\r
- if rd: self.handle_request()\r
-\r
- def server_activate(self):\r
- self.base.server_activate(self)\r
- self.url = 'http://%s:%d/' % (self.address[0], self.server_port)\r
- if self.callback: self.callback(self)\r
-\r
- DocServer.base = BaseHTTPServer.HTTPServer\r
- DocServer.handler = DocHandler\r
- DocHandler.MessageClass = Message\r
- try:\r
- try:\r
- DocServer(port, callback).serve_until_quit()\r
- except (KeyboardInterrupt, select.error):\r
- pass\r
- finally:\r
- if completer: completer()\r
-\r
-# ----------------------------------------------------- graphical interface\r
-\r
-def gui():\r
- """Graphical interface (starts web server and pops up a control window)."""\r
- class GUI:\r
- def __init__(self, window, port=7464):\r
- self.window = window\r
- self.server = None\r
- self.scanner = None\r
-\r
- import Tkinter\r
- self.server_frm = Tkinter.Frame(window)\r
- self.title_lbl = Tkinter.Label(self.server_frm,\r
- text='Starting server...\n ')\r
- self.open_btn = Tkinter.Button(self.server_frm,\r
- text='open browser', command=self.open, state='disabled')\r
- self.quit_btn = Tkinter.Button(self.server_frm,\r
- text='quit serving', command=self.quit, state='disabled')\r
-\r
- self.search_frm = Tkinter.Frame(window)\r
- self.search_lbl = Tkinter.Label(self.search_frm, text='Search for')\r
- self.search_ent = Tkinter.Entry(self.search_frm)\r
- self.search_ent.bind('<Return>', self.search)\r
- self.stop_btn = Tkinter.Button(self.search_frm,\r
- text='stop', pady=0, command=self.stop, state='disabled')\r
- if sys.platform == 'win32':\r
- # Trying to hide and show this button crashes under Windows.\r
- self.stop_btn.pack(side='right')\r
-\r
- self.window.title('pydoc')\r
- self.window.protocol('WM_DELETE_WINDOW', self.quit)\r
- self.title_lbl.pack(side='top', fill='x')\r
- self.open_btn.pack(side='left', fill='x', expand=1)\r
- self.quit_btn.pack(side='right', fill='x', expand=1)\r
- self.server_frm.pack(side='top', fill='x')\r
-\r
- self.search_lbl.pack(side='left')\r
- self.search_ent.pack(side='right', fill='x', expand=1)\r
- self.search_frm.pack(side='top', fill='x')\r
- self.search_ent.focus_set()\r
-\r
- font = ('helvetica', sys.platform == 'win32' and 8 or 10)\r
- self.result_lst = Tkinter.Listbox(window, font=font, height=6)\r
- self.result_lst.bind('<Button-1>', self.select)\r
- self.result_lst.bind('<Double-Button-1>', self.goto)\r
- self.result_scr = Tkinter.Scrollbar(window,\r
- orient='vertical', command=self.result_lst.yview)\r
- self.result_lst.config(yscrollcommand=self.result_scr.set)\r
-\r
- self.result_frm = Tkinter.Frame(window)\r
- self.goto_btn = Tkinter.Button(self.result_frm,\r
- text='go to selected', command=self.goto)\r
- self.hide_btn = Tkinter.Button(self.result_frm,\r
- text='hide results', command=self.hide)\r
- self.goto_btn.pack(side='left', fill='x', expand=1)\r
- self.hide_btn.pack(side='right', fill='x', expand=1)\r
-\r
- self.window.update()\r
- self.minwidth = self.window.winfo_width()\r
- self.minheight = self.window.winfo_height()\r
- self.bigminheight = (self.server_frm.winfo_reqheight() +\r
- self.search_frm.winfo_reqheight() +\r
- self.result_lst.winfo_reqheight() +\r
- self.result_frm.winfo_reqheight())\r
- self.bigwidth, self.bigheight = self.minwidth, self.bigminheight\r
- self.expanded = 0\r
- self.window.wm_geometry('%dx%d' % (self.minwidth, self.minheight))\r
- self.window.wm_minsize(self.minwidth, self.minheight)\r
- self.window.tk.willdispatch()\r
-\r
- import threading\r
- threading.Thread(\r
- target=serve, args=(port, self.ready, self.quit)).start()\r
-\r
- def ready(self, server):\r
- self.server = server\r
- self.title_lbl.config(\r
- text='Python documentation server at\n' + server.url)\r
- self.open_btn.config(state='normal')\r
- self.quit_btn.config(state='normal')\r
-\r
- def open(self, event=None, url=None):\r
- url = url or self.server.url\r
- try:\r
- import webbrowser\r
- webbrowser.open(url)\r
- except ImportError: # pre-webbrowser.py compatibility\r
- if sys.platform == 'win32':\r
- os.system('start "%s"' % url)\r
- else:\r
- rc = os.system('netscape -remote "openURL(%s)" &' % url)\r
- if rc: os.system('netscape "%s" &' % url)\r
-\r
- def quit(self, event=None):\r
- if self.server:\r
- self.server.quit = 1\r
- self.window.quit()\r
-\r
- def search(self, event=None):\r
- key = self.search_ent.get()\r
- self.stop_btn.pack(side='right')\r
- self.stop_btn.config(state='normal')\r
- self.search_lbl.config(text='Searching for "%s"...' % key)\r
- self.search_ent.forget()\r
- self.search_lbl.pack(side='left')\r
- self.result_lst.delete(0, 'end')\r
- self.goto_btn.config(state='disabled')\r
- self.expand()\r
-\r
- import threading\r
- if self.scanner:\r
- self.scanner.quit = 1\r
- self.scanner = ModuleScanner()\r
- threading.Thread(target=self.scanner.run,\r
- args=(self.update, key, self.done)).start()\r
-\r
- def update(self, path, modname, desc):\r
- if modname[-9:] == '.__init__':\r
- modname = modname[:-9] + ' (package)'\r
- self.result_lst.insert('end',\r
- modname + ' - ' + (desc or '(no description)'))\r
-\r
- def stop(self, event=None):\r
- if self.scanner:\r
- self.scanner.quit = 1\r
- self.scanner = None\r
-\r
- def done(self):\r
- self.scanner = None\r
- self.search_lbl.config(text='Search for')\r
- self.search_lbl.pack(side='left')\r
- self.search_ent.pack(side='right', fill='x', expand=1)\r
- if sys.platform != 'win32': self.stop_btn.forget()\r
- self.stop_btn.config(state='disabled')\r
-\r
- def select(self, event=None):\r
- self.goto_btn.config(state='normal')\r
-\r
- def goto(self, event=None):\r
- selection = self.result_lst.curselection()\r
- if selection:\r
- modname = split(self.result_lst.get(selection[0]))[0]\r
- self.open(url=self.server.url + modname + '.html')\r
-\r
- def collapse(self):\r
- if not self.expanded: return\r
- self.result_frm.forget()\r
- self.result_scr.forget()\r
- self.result_lst.forget()\r
- self.bigwidth = self.window.winfo_width()\r
- self.bigheight = self.window.winfo_height()\r
- self.window.wm_geometry('%dx%d' % (self.minwidth, self.minheight))\r
- self.window.wm_minsize(self.minwidth, self.minheight)\r
- self.expanded = 0\r
-\r
- def expand(self):\r
- if self.expanded: return\r
- self.result_frm.pack(side='bottom', fill='x')\r
- self.result_scr.pack(side='right', fill='y')\r
- self.result_lst.pack(side='top', fill='both', expand=1)\r
- self.window.wm_geometry('%dx%d' % (self.bigwidth, self.bigheight))\r
- self.window.wm_minsize(self.minwidth, self.bigminheight)\r
- self.expanded = 1\r
-\r
- def hide(self, event=None):\r
- self.stop()\r
- self.collapse()\r
-\r
- import Tkinter\r
- try:\r
- root = Tkinter.Tk()\r
- # Tk will crash if pythonw.exe has an XP .manifest\r
- # file and the root has is not destroyed explicitly.\r
- # If the problem is ever fixed in Tk, the explicit\r
- # destroy can go.\r
- try:\r
- gui = GUI(root)\r
- root.mainloop()\r
- finally:\r
- root.destroy()\r
- except KeyboardInterrupt:\r
- pass\r
-\r
-# -------------------------------------------------- command-line interface\r
-\r
-def ispath(x):\r
- return isinstance(x, str) and find(x, os.sep) >= 0\r
-\r
-def cli():\r
- """Command-line interface (looks at sys.argv to decide what to do)."""\r
- import getopt\r
- class BadUsage: pass\r
-\r
- # Scripts don't get the current directory in their path by default\r
- # unless they are run with the '-m' switch\r
- if '' not in sys.path:\r
- scriptdir = os.path.dirname(sys.argv[0])\r
- if scriptdir in sys.path:\r
- sys.path.remove(scriptdir)\r
- sys.path.insert(0, '.')\r
-\r
- try:\r
- opts, args = getopt.getopt(sys.argv[1:], 'gk:p:w')\r
- writing = 0\r
-\r
- for opt, val in opts:\r
- if opt == '-g':\r
- gui()\r
- return\r
- if opt == '-k':\r
- apropos(val)\r
- return\r
- if opt == '-p':\r
- try:\r
- port = int(val)\r
- except ValueError:\r
- raise BadUsage\r
- def ready(server):\r
- print 'pydoc server ready at %s' % server.url\r
- def stopped():\r
- print 'pydoc server stopped'\r
- serve(port, ready, stopped)\r
- return\r
- if opt == '-w':\r
- writing = 1\r
-\r
- if not args: raise BadUsage\r
- for arg in args:\r
- if ispath(arg) and not os.path.exists(arg):\r
- print 'file %r does not exist' % arg\r
- break\r
- try:\r
- if ispath(arg) and os.path.isfile(arg):\r
- arg = importfile(arg)\r
- if writing:\r
- if ispath(arg) and os.path.isdir(arg):\r
- writedocs(arg)\r
- else:\r
- writedoc(arg)\r
- else:\r
- help.help(arg)\r
- except ErrorDuringImport, value:\r
- print value\r
-\r
- except (getopt.error, BadUsage):\r
- cmd = os.path.basename(sys.argv[0])\r
- print """pydoc - the Python documentation tool\r
-\r
-%s <name> ...\r
- Show text documentation on something. <name> may be the name of a\r
- Python keyword, topic, function, module, or package, or a dotted\r
- reference to a class or function within a module or module in a\r
- package. If <name> contains a '%s', it is used as the path to a\r
- Python source file to document. If name is 'keywords', 'topics',\r
- or 'modules', a listing of these things is displayed.\r
-\r
-%s -k <keyword>\r
- Search for a keyword in the synopsis lines of all available modules.\r
-\r
-%s -p <port>\r
- Start an HTTP server on the given port on the local machine. Port\r
- number 0 can be used to get an arbitrary unused port.\r
-\r
-%s -g\r
- Pop up a graphical interface for finding and serving documentation.\r
-\r
-%s -w <name> ...\r
- Write out the HTML documentation for a module to a file in the current\r
- directory. If <name> contains a '%s', it is treated as a filename; if\r
- it names a directory, documentation is written for all the contents.\r
-""" % (cmd, os.sep, cmd, cmd, cmd, cmd, os.sep)\r
-\r
-if __name__ == '__main__': cli()\r
projects / mirror_edk2.git / blobdiff