Fix HAVE_DECL_ISINF/ISNAN test (again).
[python.git] / Lib / pydoc.py
blobdda0208edf7f89f084913b7ee5809ed50a265020
1 #!/usr/bin/env python
2 # -*- coding: latin-1 -*-
3 """Generate Python documentation in HTML or text for interactive use.
5 In the Python interpreter, do "from pydoc import help" to provide online
6 help. Calling help(thing) on a Python object documents the object.
8 Or, at the shell command line outside of Python:
10 Run "pydoc <name>" to show documentation on something. <name> may be
11 the name of a function, module, package, or a dotted reference to a
12 class or function within a module or module in a package. If the
13 argument contains a path segment delimiter (e.g. slash on Unix,
14 backslash on Windows) it is treated as the path to a Python source file.
16 Run "pydoc -k <keyword>" to search for a keyword in the synopsis lines
17 of all available modules.
19 Run "pydoc -p <port>" to start an HTTP server on a given port on the
20 local machine to generate documentation web pages.
22 For platforms without a command line, "pydoc -g" starts the HTTP server
23 and also pops up a little window for controlling it.
25 Run "pydoc -w <name>" to write out the HTML documentation for a module
26 to a file named "<name>.html".
28 Module docs for core modules are assumed to be in
30 http://docs.python.org/library/
32 This can be overridden by setting the PYTHONDOCS environment variable
33 to a different URL or to a local directory containing the Library
34 Reference Manual pages.
35 """
37 __author__ = "Ka-Ping Yee <ping@lfw.org>"
38 __date__ = "26 February 2001"
40 __version__ = "$Revision$"
41 __credits__ = """Guido van Rossum, for an excellent programming language.
42 Tommy Burnette, the original creator of manpy.
43 Paul Prescod, for all his work on onlinehelp.
44 Richard Chamberlain, for the first implementation of textdoc.
45 """
47 # Known bugs that can't be fixed here:
48 # - imp.load_module() cannot be prevented from clobbering existing
49 # loaded modules, so calling synopsis() on a binary module file
50 # changes the contents of any existing module with the same name.
51 # - If the __file__ attribute on a module is a relative path and
52 # the current directory is changed with os.chdir(), an incorrect
53 # path will be displayed.
55 import sys, imp, os, re, types, inspect, __builtin__, pkgutil
56 from repr import Repr
57 from string import expandtabs, find, join, lower, split, strip, rfind, rstrip
58 try:
59 from collections import deque
60 except ImportError:
61 # Python 2.3 compatibility
62 class deque(list):
63 def popleft(self):
64 return self.pop(0)
66 # --------------------------------------------------------- common routines
68 def pathdirs():
69 """Convert sys.path into a list of absolute, existing, unique paths."""
70 dirs = []
71 normdirs = []
72 for dir in sys.path:
73 dir = os.path.abspath(dir or '.')
74 normdir = os.path.normcase(dir)
75 if normdir not in normdirs and os.path.isdir(dir):
76 dirs.append(dir)
77 normdirs.append(normdir)
78 return dirs
80 def getdoc(object):
81 """Get the doc string or comments for an object."""
82 result = inspect.getdoc(object) or inspect.getcomments(object)
83 return result and re.sub('^ *\n', '', rstrip(result)) or ''
85 def splitdoc(doc):
86 """Split a doc string into a synopsis line (if any) and the rest."""
87 lines = split(strip(doc), '\n')
88 if len(lines) == 1:
89 return lines[0], ''
90 elif len(lines) >= 2 and not rstrip(lines[1]):
91 return lines[0], join(lines[2:], '\n')
92 return '', join(lines, '\n')
94 def classname(object, modname):
95 """Get a class name and qualify it with a module name if necessary."""
96 name = object.__name__
97 if object.__module__ != modname:
98 name = object.__module__ + '.' + name
99 return name
101 def isdata(object):
102 """Check if an object is of a type that probably means it's data."""
103 return not (inspect.ismodule(object) or inspect.isclass(object) or
104 inspect.isroutine(object) or inspect.isframe(object) or
105 inspect.istraceback(object) or inspect.iscode(object))
107 def replace(text, *pairs):
108 """Do a series of global replacements on a string."""
109 while pairs:
110 text = join(split(text, pairs[0]), pairs[1])
111 pairs = pairs[2:]
112 return text
114 def cram(text, maxlen):
115 """Omit part of a string if needed to make it fit in a maximum length."""
116 if len(text) > maxlen:
117 pre = max(0, (maxlen-3)//2)
118 post = max(0, maxlen-3-pre)
119 return text[:pre] + '...' + text[len(text)-post:]
120 return text
122 _re_stripid = re.compile(r' at 0x[0-9a-f]{6,16}(>+)$', re.IGNORECASE)
123 def stripid(text):
124 """Remove the hexadecimal id from a Python object representation."""
125 # The behaviour of %p is implementation-dependent in terms of case.
126 if _re_stripid.search(repr(Exception)):
127 return _re_stripid.sub(r'\1', text)
128 return text
130 def _is_some_method(obj):
131 return inspect.ismethod(obj) or inspect.ismethoddescriptor(obj)
133 def allmethods(cl):
134 methods = {}
135 for key, value in inspect.getmembers(cl, _is_some_method):
136 methods[key] = 1
137 for base in cl.__bases__:
138 methods.update(allmethods(base)) # all your base are belong to us
139 for key in methods.keys():
140 methods[key] = getattr(cl, key)
141 return methods
143 def _split_list(s, predicate):
144 """Split sequence s via predicate, and return pair ([true], [false]).
146 The return value is a 2-tuple of lists,
147 ([x for x in s if predicate(x)],
148 [x for x in s if not predicate(x)])
151 yes = []
152 no = []
153 for x in s:
154 if predicate(x):
155 yes.append(x)
156 else:
157 no.append(x)
158 return yes, no
160 def visiblename(name, all=None):
161 """Decide whether to show documentation on a variable."""
162 # Certain special names are redundant.
163 _hidden_names = ('__builtins__', '__doc__', '__file__', '__path__',
164 '__module__', '__name__', '__slots__', '__package__')
165 if name in _hidden_names: return 0
166 # Private names are hidden, but special names are displayed.
167 if name.startswith('__') and name.endswith('__'): return 1
168 if all is not None:
169 # only document that which the programmer exported in __all__
170 return name in all
171 else:
172 return not name.startswith('_')
174 def classify_class_attrs(object):
175 """Wrap inspect.classify_class_attrs, with fixup for data descriptors."""
176 def fixup(data):
177 name, kind, cls, value = data
178 if inspect.isdatadescriptor(value):
179 kind = 'data descriptor'
180 return name, kind, cls, value
181 return map(fixup, inspect.classify_class_attrs(object))
183 # ----------------------------------------------------- module manipulation
185 def ispackage(path):
186 """Guess whether a path refers to a package directory."""
187 if os.path.isdir(path):
188 for ext in ('.py', '.pyc', '.pyo'):
189 if os.path.isfile(os.path.join(path, '__init__' + ext)):
190 return True
191 return False
193 def source_synopsis(file):
194 line = file.readline()
195 while line[:1] == '#' or not strip(line):
196 line = file.readline()
197 if not line: break
198 line = strip(line)
199 if line[:4] == 'r"""': line = line[1:]
200 if line[:3] == '"""':
201 line = line[3:]
202 if line[-1:] == '\\': line = line[:-1]
203 while not strip(line):
204 line = file.readline()
205 if not line: break
206 result = strip(split(line, '"""')[0])
207 else: result = None
208 return result
210 def synopsis(filename, cache={}):
211 """Get the one-line summary out of a module file."""
212 mtime = os.stat(filename).st_mtime
213 lastupdate, result = cache.get(filename, (0, None))
214 if lastupdate < mtime:
215 info = inspect.getmoduleinfo(filename)
216 try:
217 file = open(filename)
218 except IOError:
219 # module can't be opened, so skip it
220 return None
221 if info and 'b' in info[2]: # binary modules have to be imported
222 try: module = imp.load_module('__temp__', file, filename, info[1:])
223 except: return None
224 result = (module.__doc__ or '').splitlines()[0]
225 del sys.modules['__temp__']
226 else: # text modules can be directly examined
227 result = source_synopsis(file)
228 file.close()
229 cache[filename] = (mtime, result)
230 return result
232 class ErrorDuringImport(Exception):
233 """Errors that occurred while trying to import something to document it."""
234 def __init__(self, filename, exc_info):
235 exc, value, tb = exc_info
236 self.filename = filename
237 self.exc = exc
238 self.value = value
239 self.tb = tb
241 def __str__(self):
242 exc = self.exc
243 if type(exc) is types.ClassType:
244 exc = exc.__name__
245 return 'problem in %s - %s: %s' % (self.filename, exc, self.value)
247 def importfile(path):
248 """Import a Python source file or compiled file given its path."""
249 magic = imp.get_magic()
250 file = open(path, 'r')
251 if file.read(len(magic)) == magic:
252 kind = imp.PY_COMPILED
253 else:
254 kind = imp.PY_SOURCE
255 file.close()
256 filename = os.path.basename(path)
257 name, ext = os.path.splitext(filename)
258 file = open(path, 'r')
259 try:
260 module = imp.load_module(name, file, path, (ext, 'r', kind))
261 except:
262 raise ErrorDuringImport(path, sys.exc_info())
263 file.close()
264 return module
266 def safeimport(path, forceload=0, cache={}):
267 """Import a module; handle errors; return None if the module isn't found.
269 If the module *is* found but an exception occurs, it's wrapped in an
270 ErrorDuringImport exception and reraised. Unlike __import__, if a
271 package path is specified, the module at the end of the path is returned,
272 not the package at the beginning. If the optional 'forceload' argument
273 is 1, we reload the module from disk (unless it's a dynamic extension)."""
274 try:
275 # If forceload is 1 and the module has been previously loaded from
276 # disk, we always have to reload the module. Checking the file's
277 # mtime isn't good enough (e.g. the module could contain a class
278 # that inherits from another module that has changed).
279 if forceload and path in sys.modules:
280 if path not in sys.builtin_module_names:
281 # Avoid simply calling reload() because it leaves names in
282 # the currently loaded module lying around if they're not
283 # defined in the new source file. Instead, remove the
284 # module from sys.modules and re-import. Also remove any
285 # submodules because they won't appear in the newly loaded
286 # module's namespace if they're already in sys.modules.
287 subs = [m for m in sys.modules if m.startswith(path + '.')]
288 for key in [path] + subs:
289 # Prevent garbage collection.
290 cache[key] = sys.modules[key]
291 del sys.modules[key]
292 module = __import__(path)
293 except:
294 # Did the error occur before or after the module was found?
295 (exc, value, tb) = info = sys.exc_info()
296 if path in sys.modules:
297 # An error occurred while executing the imported module.
298 raise ErrorDuringImport(sys.modules[path].__file__, info)
299 elif exc is SyntaxError:
300 # A SyntaxError occurred before we could execute the module.
301 raise ErrorDuringImport(value.filename, info)
302 elif exc is ImportError and \
303 split(lower(str(value)))[:2] == ['no', 'module']:
304 # The module was not found.
305 return None
306 else:
307 # Some other error occurred during the importing process.
308 raise ErrorDuringImport(path, sys.exc_info())
309 for part in split(path, '.')[1:]:
310 try: module = getattr(module, part)
311 except AttributeError: return None
312 return module
314 # ---------------------------------------------------- formatter base class
316 class Doc:
317 def document(self, object, name=None, *args):
318 """Generate documentation for an object."""
319 args = (object, name) + args
320 # 'try' clause is to attempt to handle the possibility that inspect
321 # identifies something in a way that pydoc itself has issues handling;
322 # think 'super' and how it is a descriptor (which raises the exception
323 # by lacking a __name__ attribute) and an instance.
324 if inspect.isgetsetdescriptor(object): return self.docdata(*args)
325 if inspect.ismemberdescriptor(object): return self.docdata(*args)
326 try:
327 if inspect.ismodule(object): return self.docmodule(*args)
328 if inspect.isclass(object): return self.docclass(*args)
329 if inspect.isroutine(object): return self.docroutine(*args)
330 except AttributeError:
331 pass
332 if isinstance(object, property): return self.docproperty(*args)
333 return self.docother(*args)
335 def fail(self, object, name=None, *args):
336 """Raise an exception for unimplemented types."""
337 message = "don't know how to document object%s of type %s" % (
338 name and ' ' + repr(name), type(object).__name__)
339 raise TypeError, message
341 docmodule = docclass = docroutine = docother = docproperty = docdata = fail
343 def getdocloc(self, object):
344 """Return the location of module docs or None"""
346 try:
347 file = inspect.getabsfile(object)
348 except TypeError:
349 file = '(built-in)'
351 docloc = os.environ.get("PYTHONDOCS",
352 "http://docs.python.org/library")
353 basedir = os.path.join(sys.exec_prefix, "lib",
354 "python"+sys.version[0:3])
355 if (isinstance(object, type(os)) and
356 (object.__name__ in ('errno', 'exceptions', 'gc', 'imp',
357 'marshal', 'posix', 'signal', 'sys',
358 'thread', 'zipimport') or
359 (file.startswith(basedir) and
360 not file.startswith(os.path.join(basedir, 'site-packages'))))):
361 if docloc.startswith("http://"):
362 docloc = "%s/%s" % (docloc.rstrip("/"), object.__name__)
363 else:
364 docloc = os.path.join(docloc, object.__name__ + ".html")
365 else:
366 docloc = None
367 return docloc
369 # -------------------------------------------- HTML documentation generator
371 class HTMLRepr(Repr):
372 """Class for safely making an HTML representation of a Python object."""
373 def __init__(self):
374 Repr.__init__(self)
375 self.maxlist = self.maxtuple = 20
376 self.maxdict = 10
377 self.maxstring = self.maxother = 100
379 def escape(self, text):
380 return replace(text, '&', '&amp;', '<', '&lt;', '>', '&gt;')
382 def repr(self, object):
383 return Repr.repr(self, object)
385 def repr1(self, x, level):
386 if hasattr(type(x), '__name__'):
387 methodname = 'repr_' + join(split(type(x).__name__), '_')
388 if hasattr(self, methodname):
389 return getattr(self, methodname)(x, level)
390 return self.escape(cram(stripid(repr(x)), self.maxother))
392 def repr_string(self, x, level):
393 test = cram(x, self.maxstring)
394 testrepr = repr(test)
395 if '\\' in test and '\\' not in replace(testrepr, r'\\', ''):
396 # Backslashes are only literal in the string and are never
397 # needed to make any special characters, so show a raw string.
398 return 'r' + testrepr[0] + self.escape(test) + testrepr[0]
399 return re.sub(r'((\\[\\abfnrtv\'"]|\\[0-9]..|\\x..|\\u....)+)',
400 r'<font color="#c040c0">\1</font>',
401 self.escape(testrepr))
403 repr_str = repr_string
405 def repr_instance(self, x, level):
406 try:
407 return self.escape(cram(stripid(repr(x)), self.maxstring))
408 except:
409 return self.escape('<%s instance>' % x.__class__.__name__)
411 repr_unicode = repr_string
413 class HTMLDoc(Doc):
414 """Formatter class for HTML documentation."""
416 # ------------------------------------------- HTML formatting utilities
418 _repr_instance = HTMLRepr()
419 repr = _repr_instance.repr
420 escape = _repr_instance.escape
422 def page(self, title, contents):
423 """Format an HTML page."""
424 return '''
425 <!doctype html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
426 <html><head><title>Python: %s</title>
427 </head><body bgcolor="#f0f0f8">
429 </body></html>''' % (title, contents)
431 def heading(self, title, fgcol, bgcol, extras=''):
432 """Format a page heading."""
433 return '''
434 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="heading">
435 <tr bgcolor="%s">
436 <td valign=bottom>&nbsp;<br>
437 <font color="%s" face="helvetica, arial">&nbsp;<br>%s</font></td
438 ><td align=right valign=bottom
439 ><font color="%s" face="helvetica, arial">%s</font></td></tr></table>
440 ''' % (bgcol, fgcol, title, fgcol, extras or '&nbsp;')
442 def section(self, title, fgcol, bgcol, contents, width=6,
443 prelude='', marginalia=None, gap='&nbsp;'):
444 """Format a section with a heading."""
445 if marginalia is None:
446 marginalia = '<tt>' + '&nbsp;' * width + '</tt>'
447 result = '''<p>
448 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
449 <tr bgcolor="%s">
450 <td colspan=3 valign=bottom>&nbsp;<br>
451 <font color="%s" face="helvetica, arial">%s</font></td></tr>
452 ''' % (bgcol, fgcol, title)
453 if prelude:
454 result = result + '''
455 <tr bgcolor="%s"><td rowspan=2>%s</td>
456 <td colspan=2>%s</td></tr>
457 <tr><td>%s</td>''' % (bgcol, marginalia, prelude, gap)
458 else:
459 result = result + '''
460 <tr><td bgcolor="%s">%s</td><td>%s</td>''' % (bgcol, marginalia, gap)
462 return result + '\n<td width="100%%">%s</td></tr></table>' % contents
464 def bigsection(self, title, *args):
465 """Format a section with a big heading."""
466 title = '<big><strong>%s</strong></big>' % title
467 return self.section(title, *args)
469 def preformat(self, text):
470 """Format literal preformatted text."""
471 text = self.escape(expandtabs(text))
472 return replace(text, '\n\n', '\n \n', '\n\n', '\n \n',
473 ' ', '&nbsp;', '\n', '<br>\n')
475 def multicolumn(self, list, format, cols=4):
476 """Format a list of items into a multi-column list."""
477 result = ''
478 rows = (len(list)+cols-1)/cols
479 for col in range(cols):
480 result = result + '<td width="%d%%" valign=top>' % (100/cols)
481 for i in range(rows*col, rows*col+rows):
482 if i < len(list):
483 result = result + format(list[i]) + '<br>\n'
484 result = result + '</td>'
485 return '<table width="100%%" summary="list"><tr>%s</tr></table>' % result
487 def grey(self, text): return '<font color="#909090">%s</font>' % text
489 def namelink(self, name, *dicts):
490 """Make a link for an identifier, given name-to-URL mappings."""
491 for dict in dicts:
492 if name in dict:
493 return '<a href="%s">%s</a>' % (dict[name], name)
494 return name
496 def classlink(self, object, modname):
497 """Make a link for a class."""
498 name, module = object.__name__, sys.modules.get(object.__module__)
499 if hasattr(module, name) and getattr(module, name) is object:
500 return '<a href="%s.html#%s">%s</a>' % (
501 module.__name__, name, classname(object, modname))
502 return classname(object, modname)
504 def modulelink(self, object):
505 """Make a link for a module."""
506 return '<a href="%s.html">%s</a>' % (object.__name__, object.__name__)
508 def modpkglink(self, data):
509 """Make a link for a module or package to display in an index."""
510 name, path, ispackage, shadowed = data
511 if shadowed:
512 return self.grey(name)
513 if path:
514 url = '%s.%s.html' % (path, name)
515 else:
516 url = '%s.html' % name
517 if ispackage:
518 text = '<strong>%s</strong>&nbsp;(package)' % name
519 else:
520 text = name
521 return '<a href="%s">%s</a>' % (url, text)
523 def markup(self, text, escape=None, funcs={}, classes={}, methods={}):
524 """Mark up some plain text, given a context of symbols to look for.
525 Each context dictionary maps object names to anchor names."""
526 escape = escape or self.escape
527 results = []
528 here = 0
529 pattern = re.compile(r'\b((http|ftp)://\S+[\w/]|'
530 r'RFC[- ]?(\d+)|'
531 r'PEP[- ]?(\d+)|'
532 r'(self\.)?(\w+))')
533 while True:
534 match = pattern.search(text, here)
535 if not match: break
536 start, end = match.span()
537 results.append(escape(text[here:start]))
539 all, scheme, rfc, pep, selfdot, name = match.groups()
540 if scheme:
541 url = escape(all).replace('"', '&quot;')
542 results.append('<a href="%s">%s</a>' % (url, url))
543 elif rfc:
544 url = 'http://www.rfc-editor.org/rfc/rfc%d.txt' % int(rfc)
545 results.append('<a href="%s">%s</a>' % (url, escape(all)))
546 elif pep:
547 url = 'http://www.python.org/dev/peps/pep-%04d/' % int(pep)
548 results.append('<a href="%s">%s</a>' % (url, escape(all)))
549 elif text[end:end+1] == '(':
550 results.append(self.namelink(name, methods, funcs, classes))
551 elif selfdot:
552 results.append('self.<strong>%s</strong>' % name)
553 else:
554 results.append(self.namelink(name, classes))
555 here = end
556 results.append(escape(text[here:]))
557 return join(results, '')
559 # ---------------------------------------------- type-specific routines
561 def formattree(self, tree, modname, parent=None):
562 """Produce HTML for a class tree as given by inspect.getclasstree()."""
563 result = ''
564 for entry in tree:
565 if type(entry) is type(()):
566 c, bases = entry
567 result = result + '<dt><font face="helvetica, arial">'
568 result = result + self.classlink(c, modname)
569 if bases and bases != (parent,):
570 parents = []
571 for base in bases:
572 parents.append(self.classlink(base, modname))
573 result = result + '(' + join(parents, ', ') + ')'
574 result = result + '\n</font></dt>'
575 elif type(entry) is type([]):
576 result = result + '<dd>\n%s</dd>\n' % self.formattree(
577 entry, modname, c)
578 return '<dl>\n%s</dl>\n' % result
580 def docmodule(self, object, name=None, mod=None, *ignored):
581 """Produce HTML documentation for a module object."""
582 name = object.__name__ # ignore the passed-in name
583 try:
584 all = object.__all__
585 except AttributeError:
586 all = None
587 parts = split(name, '.')
588 links = []
589 for i in range(len(parts)-1):
590 links.append(
591 '<a href="%s.html"><font color="#ffffff">%s</font></a>' %
592 (join(parts[:i+1], '.'), parts[i]))
593 linkedname = join(links + parts[-1:], '.')
594 head = '<big><big><strong>%s</strong></big></big>' % linkedname
595 try:
596 path = inspect.getabsfile(object)
597 url = path
598 if sys.platform == 'win32':
599 import nturl2path
600 url = nturl2path.pathname2url(path)
601 filelink = '<a href="file:%s">%s</a>' % (url, path)
602 except TypeError:
603 filelink = '(built-in)'
604 info = []
605 if hasattr(object, '__version__'):
606 version = str(object.__version__)
607 if version[:11] == '$' + 'Revision: ' and version[-1:] == '$':
608 version = strip(version[11:-1])
609 info.append('version %s' % self.escape(version))
610 if hasattr(object, '__date__'):
611 info.append(self.escape(str(object.__date__)))
612 if info:
613 head = head + ' (%s)' % join(info, ', ')
614 docloc = self.getdocloc(object)
615 if docloc is not None:
616 docloc = '<br><a href="%(docloc)s">Module Docs</a>' % locals()
617 else:
618 docloc = ''
619 result = self.heading(
620 head, '#ffffff', '#7799ee',
621 '<a href=".">index</a><br>' + filelink + docloc)
623 modules = inspect.getmembers(object, inspect.ismodule)
625 classes, cdict = [], {}
626 for key, value in inspect.getmembers(object, inspect.isclass):
627 # if __all__ exists, believe it. Otherwise use old heuristic.
628 if (all is not None or
629 (inspect.getmodule(value) or object) is object):
630 if visiblename(key, all):
631 classes.append((key, value))
632 cdict[key] = cdict[value] = '#' + key
633 for key, value in classes:
634 for base in value.__bases__:
635 key, modname = base.__name__, base.__module__
636 module = sys.modules.get(modname)
637 if modname != name and module and hasattr(module, key):
638 if getattr(module, key) is base:
639 if not key in cdict:
640 cdict[key] = cdict[base] = modname + '.html#' + key
641 funcs, fdict = [], {}
642 for key, value in inspect.getmembers(object, inspect.isroutine):
643 # if __all__ exists, believe it. Otherwise use old heuristic.
644 if (all is not None or
645 inspect.isbuiltin(value) or inspect.getmodule(value) is object):
646 if visiblename(key, all):
647 funcs.append((key, value))
648 fdict[key] = '#-' + key
649 if inspect.isfunction(value): fdict[value] = fdict[key]
650 data = []
651 for key, value in inspect.getmembers(object, isdata):
652 if visiblename(key, all):
653 data.append((key, value))
655 doc = self.markup(getdoc(object), self.preformat, fdict, cdict)
656 doc = doc and '<tt>%s</tt>' % doc
657 result = result + '<p>%s</p>\n' % doc
659 if hasattr(object, '__path__'):
660 modpkgs = []
661 for importer, modname, ispkg in pkgutil.iter_modules(object.__path__):
662 modpkgs.append((modname, name, ispkg, 0))
663 modpkgs.sort()
664 contents = self.multicolumn(modpkgs, self.modpkglink)
665 result = result + self.bigsection(
666 'Package Contents', '#ffffff', '#aa55cc', contents)
667 elif modules:
668 contents = self.multicolumn(
669 modules, lambda key_value, s=self: s.modulelink(key_value[1]))
670 result = result + self.bigsection(
671 'Modules', '#ffffff', '#aa55cc', contents)
673 if classes:
674 classlist = map(lambda key_value: key_value[1], classes)
675 contents = [
676 self.formattree(inspect.getclasstree(classlist, 1), name)]
677 for key, value in classes:
678 contents.append(self.document(value, key, name, fdict, cdict))
679 result = result + self.bigsection(
680 'Classes', '#ffffff', '#ee77aa', join(contents))
681 if funcs:
682 contents = []
683 for key, value in funcs:
684 contents.append(self.document(value, key, name, fdict, cdict))
685 result = result + self.bigsection(
686 'Functions', '#ffffff', '#eeaa77', join(contents))
687 if data:
688 contents = []
689 for key, value in data:
690 contents.append(self.document(value, key))
691 result = result + self.bigsection(
692 'Data', '#ffffff', '#55aa55', join(contents, '<br>\n'))
693 if hasattr(object, '__author__'):
694 contents = self.markup(str(object.__author__), self.preformat)
695 result = result + self.bigsection(
696 'Author', '#ffffff', '#7799ee', contents)
697 if hasattr(object, '__credits__'):
698 contents = self.markup(str(object.__credits__), self.preformat)
699 result = result + self.bigsection(
700 'Credits', '#ffffff', '#7799ee', contents)
702 return result
704 def docclass(self, object, name=None, mod=None, funcs={}, classes={},
705 *ignored):
706 """Produce HTML documentation for a class object."""
707 realname = object.__name__
708 name = name or realname
709 bases = object.__bases__
711 contents = []
712 push = contents.append
714 # Cute little class to pump out a horizontal rule between sections.
715 class HorizontalRule:
716 def __init__(self):
717 self.needone = 0
718 def maybe(self):
719 if self.needone:
720 push('<hr>\n')
721 self.needone = 1
722 hr = HorizontalRule()
724 # List the mro, if non-trivial.
725 mro = deque(inspect.getmro(object))
726 if len(mro) > 2:
727 hr.maybe()
728 push('<dl><dt>Method resolution order:</dt>\n')
729 for base in mro:
730 push('<dd>%s</dd>\n' % self.classlink(base,
731 object.__module__))
732 push('</dl>\n')
734 def spill(msg, attrs, predicate):
735 ok, attrs = _split_list(attrs, predicate)
736 if ok:
737 hr.maybe()
738 push(msg)
739 for name, kind, homecls, value in ok:
740 push(self.document(getattr(object, name), name, mod,
741 funcs, classes, mdict, object))
742 push('\n')
743 return attrs
745 def spilldescriptors(msg, attrs, predicate):
746 ok, attrs = _split_list(attrs, predicate)
747 if ok:
748 hr.maybe()
749 push(msg)
750 for name, kind, homecls, value in ok:
751 push(self._docdescriptor(name, value, mod))
752 return attrs
754 def spilldata(msg, attrs, predicate):
755 ok, attrs = _split_list(attrs, predicate)
756 if ok:
757 hr.maybe()
758 push(msg)
759 for name, kind, homecls, value in ok:
760 base = self.docother(getattr(object, name), name, mod)
761 if (hasattr(value, '__call__') or
762 inspect.isdatadescriptor(value)):
763 doc = getattr(value, "__doc__", None)
764 else:
765 doc = None
766 if doc is None:
767 push('<dl><dt>%s</dl>\n' % base)
768 else:
769 doc = self.markup(getdoc(value), self.preformat,
770 funcs, classes, mdict)
771 doc = '<dd><tt>%s</tt>' % doc
772 push('<dl><dt>%s%s</dl>\n' % (base, doc))
773 push('\n')
774 return attrs
776 attrs = filter(lambda data: visiblename(data[0]),
777 classify_class_attrs(object))
778 mdict = {}
779 for key, kind, homecls, value in attrs:
780 mdict[key] = anchor = '#' + name + '-' + key
781 value = getattr(object, key)
782 try:
783 # The value may not be hashable (e.g., a data attr with
784 # a dict or list value).
785 mdict[value] = anchor
786 except TypeError:
787 pass
789 while attrs:
790 if mro:
791 thisclass = mro.popleft()
792 else:
793 thisclass = attrs[0][2]
794 attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass)
796 if thisclass is __builtin__.object:
797 attrs = inherited
798 continue
799 elif thisclass is object:
800 tag = 'defined here'
801 else:
802 tag = 'inherited from %s' % self.classlink(thisclass,
803 object.__module__)
804 tag += ':<br>\n'
806 # Sort attrs by name.
807 try:
808 attrs.sort(key=lambda t: t[0])
809 except TypeError:
810 attrs.sort(lambda t1, t2: cmp(t1[0], t2[0])) # 2.3 compat
812 # Pump out the attrs, segregated by kind.
813 attrs = spill('Methods %s' % tag, attrs,
814 lambda t: t[1] == 'method')
815 attrs = spill('Class methods %s' % tag, attrs,
816 lambda t: t[1] == 'class method')
817 attrs = spill('Static methods %s' % tag, attrs,
818 lambda t: t[1] == 'static method')
819 attrs = spilldescriptors('Data descriptors %s' % tag, attrs,
820 lambda t: t[1] == 'data descriptor')
821 attrs = spilldata('Data and other attributes %s' % tag, attrs,
822 lambda t: t[1] == 'data')
823 assert attrs == []
824 attrs = inherited
826 contents = ''.join(contents)
828 if name == realname:
829 title = '<a name="%s">class <strong>%s</strong></a>' % (
830 name, realname)
831 else:
832 title = '<strong>%s</strong> = <a name="%s">class %s</a>' % (
833 name, name, realname)
834 if bases:
835 parents = []
836 for base in bases:
837 parents.append(self.classlink(base, object.__module__))
838 title = title + '(%s)' % join(parents, ', ')
839 doc = self.markup(getdoc(object), self.preformat, funcs, classes, mdict)
840 doc = doc and '<tt>%s<br>&nbsp;</tt>' % doc
842 return self.section(title, '#000000', '#ffc8d8', contents, 3, doc)
844 def formatvalue(self, object):
845 """Format an argument default value as text."""
846 return self.grey('=' + self.repr(object))
848 def docroutine(self, object, name=None, mod=None,
849 funcs={}, classes={}, methods={}, cl=None):
850 """Produce HTML documentation for a function or method object."""
851 realname = object.__name__
852 name = name or realname
853 anchor = (cl and cl.__name__ or '') + '-' + name
854 note = ''
855 skipdocs = 0
856 if inspect.ismethod(object):
857 imclass = object.im_class
858 if cl:
859 if imclass is not cl:
860 note = ' from ' + self.classlink(imclass, mod)
861 else:
862 if object.im_self is not None:
863 note = ' method of %s instance' % self.classlink(
864 object.im_self.__class__, mod)
865 else:
866 note = ' unbound %s method' % self.classlink(imclass,mod)
867 object = object.im_func
869 if name == realname:
870 title = '<a name="%s"><strong>%s</strong></a>' % (anchor, realname)
871 else:
872 if (cl and realname in cl.__dict__ and
873 cl.__dict__[realname] is object):
874 reallink = '<a href="#%s">%s</a>' % (
875 cl.__name__ + '-' + realname, realname)
876 skipdocs = 1
877 else:
878 reallink = realname
879 title = '<a name="%s"><strong>%s</strong></a> = %s' % (
880 anchor, name, reallink)
881 if inspect.isfunction(object):
882 args, varargs, varkw, defaults = inspect.getargspec(object)
883 argspec = inspect.formatargspec(
884 args, varargs, varkw, defaults, formatvalue=self.formatvalue)
885 if realname == '<lambda>':
886 title = '<strong>%s</strong> <em>lambda</em> ' % name
887 argspec = argspec[1:-1] # remove parentheses
888 else:
889 argspec = '(...)'
891 decl = title + argspec + (note and self.grey(
892 '<font face="helvetica, arial">%s</font>' % note))
894 if skipdocs:
895 return '<dl><dt>%s</dt></dl>\n' % decl
896 else:
897 doc = self.markup(
898 getdoc(object), self.preformat, funcs, classes, methods)
899 doc = doc and '<dd><tt>%s</tt></dd>' % doc
900 return '<dl><dt>%s</dt>%s</dl>\n' % (decl, doc)
902 def _docdescriptor(self, name, value, mod):
903 results = []
904 push = results.append
906 if name:
907 push('<dl><dt><strong>%s</strong></dt>\n' % name)
908 if value.__doc__ is not None:
909 doc = self.markup(getdoc(value), self.preformat)
910 push('<dd><tt>%s</tt></dd>\n' % doc)
911 push('</dl>\n')
913 return ''.join(results)
915 def docproperty(self, object, name=None, mod=None, cl=None):
916 """Produce html documentation for a property."""
917 return self._docdescriptor(name, object, mod)
919 def docother(self, object, name=None, mod=None, *ignored):
920 """Produce HTML documentation for a data object."""
921 lhs = name and '<strong>%s</strong> = ' % name or ''
922 return lhs + self.repr(object)
924 def docdata(self, object, name=None, mod=None, cl=None):
925 """Produce html documentation for a data descriptor."""
926 return self._docdescriptor(name, object, mod)
928 def index(self, dir, shadowed=None):
929 """Generate an HTML index for a directory of modules."""
930 modpkgs = []
931 if shadowed is None: shadowed = {}
932 for importer, name, ispkg in pkgutil.iter_modules([dir]):
933 modpkgs.append((name, '', ispkg, name in shadowed))
934 shadowed[name] = 1
936 modpkgs.sort()
937 contents = self.multicolumn(modpkgs, self.modpkglink)
938 return self.bigsection(dir, '#ffffff', '#ee77aa', contents)
940 # -------------------------------------------- text documentation generator
942 class TextRepr(Repr):
943 """Class for safely making a text representation of a Python object."""
944 def __init__(self):
945 Repr.__init__(self)
946 self.maxlist = self.maxtuple = 20
947 self.maxdict = 10
948 self.maxstring = self.maxother = 100
950 def repr1(self, x, level):
951 if hasattr(type(x), '__name__'):
952 methodname = 'repr_' + join(split(type(x).__name__), '_')
953 if hasattr(self, methodname):
954 return getattr(self, methodname)(x, level)
955 return cram(stripid(repr(x)), self.maxother)
957 def repr_string(self, x, level):
958 test = cram(x, self.maxstring)
959 testrepr = repr(test)
960 if '\\' in test and '\\' not in replace(testrepr, r'\\', ''):
961 # Backslashes are only literal in the string and are never
962 # needed to make any special characters, so show a raw string.
963 return 'r' + testrepr[0] + test + testrepr[0]
964 return testrepr
966 repr_str = repr_string
968 def repr_instance(self, x, level):
969 try:
970 return cram(stripid(repr(x)), self.maxstring)
971 except:
972 return '<%s instance>' % x.__class__.__name__
974 class TextDoc(Doc):
975 """Formatter class for text documentation."""
977 # ------------------------------------------- text formatting utilities
979 _repr_instance = TextRepr()
980 repr = _repr_instance.repr
982 def bold(self, text):
983 """Format a string in bold by overstriking."""
984 return join(map(lambda ch: ch + '\b' + ch, text), '')
986 def indent(self, text, prefix=' '):
987 """Indent text by prepending a given prefix to each line."""
988 if not text: return ''
989 lines = split(text, '\n')
990 lines = map(lambda line, prefix=prefix: prefix + line, lines)
991 if lines: lines[-1] = rstrip(lines[-1])
992 return join(lines, '\n')
994 def section(self, title, contents):
995 """Format a section with a given heading."""
996 return self.bold(title) + '\n' + rstrip(self.indent(contents)) + '\n\n'
998 # ---------------------------------------------- type-specific routines
1000 def formattree(self, tree, modname, parent=None, prefix=''):
1001 """Render in text a class tree as returned by inspect.getclasstree()."""
1002 result = ''
1003 for entry in tree:
1004 if type(entry) is type(()):
1005 c, bases = entry
1006 result = result + prefix + classname(c, modname)
1007 if bases and bases != (parent,):
1008 parents = map(lambda c, m=modname: classname(c, m), bases)
1009 result = result + '(%s)' % join(parents, ', ')
1010 result = result + '\n'
1011 elif type(entry) is type([]):
1012 result = result + self.formattree(
1013 entry, modname, c, prefix + ' ')
1014 return result
1016 def docmodule(self, object, name=None, mod=None):
1017 """Produce text documentation for a given module object."""
1018 name = object.__name__ # ignore the passed-in name
1019 synop, desc = splitdoc(getdoc(object))
1020 result = self.section('NAME', name + (synop and ' - ' + synop))
1022 try:
1023 all = object.__all__
1024 except AttributeError:
1025 all = None
1027 try:
1028 file = inspect.getabsfile(object)
1029 except TypeError:
1030 file = '(built-in)'
1031 result = result + self.section('FILE', file)
1033 docloc = self.getdocloc(object)
1034 if docloc is not None:
1035 result = result + self.section('MODULE DOCS', docloc)
1037 if desc:
1038 result = result + self.section('DESCRIPTION', desc)
1040 classes = []
1041 for key, value in inspect.getmembers(object, inspect.isclass):
1042 # if __all__ exists, believe it. Otherwise use old heuristic.
1043 if (all is not None
1044 or (inspect.getmodule(value) or object) is object):
1045 if visiblename(key, all):
1046 classes.append((key, value))
1047 funcs = []
1048 for key, value in inspect.getmembers(object, inspect.isroutine):
1049 # if __all__ exists, believe it. Otherwise use old heuristic.
1050 if (all is not None or
1051 inspect.isbuiltin(value) or inspect.getmodule(value) is object):
1052 if visiblename(key, all):
1053 funcs.append((key, value))
1054 data = []
1055 for key, value in inspect.getmembers(object, isdata):
1056 if visiblename(key, all):
1057 data.append((key, value))
1059 modpkgs = []
1060 modpkgs_names = set()
1061 if hasattr(object, '__path__'):
1062 for importer, modname, ispkg in pkgutil.iter_modules(object.__path__):
1063 modpkgs_names.add(modname)
1064 if ispkg:
1065 modpkgs.append(modname + ' (package)')
1066 else:
1067 modpkgs.append(modname)
1069 modpkgs.sort()
1070 result = result + self.section(
1071 'PACKAGE CONTENTS', join(modpkgs, '\n'))
1073 # Detect submodules as sometimes created by C extensions
1074 submodules = []
1075 for key, value in inspect.getmembers(object, inspect.ismodule):
1076 if value.__name__.startswith(name + '.') and key not in modpkgs_names:
1077 submodules.append(key)
1078 if submodules:
1079 submodules.sort()
1080 result = result + self.section(
1081 'SUBMODULES', join(submodules, '\n'))
1083 if classes:
1084 classlist = map(lambda key_value: key_value[1], classes)
1085 contents = [self.formattree(
1086 inspect.getclasstree(classlist, 1), name)]
1087 for key, value in classes:
1088 contents.append(self.document(value, key, name))
1089 result = result + self.section('CLASSES', join(contents, '\n'))
1091 if funcs:
1092 contents = []
1093 for key, value in funcs:
1094 contents.append(self.document(value, key, name))
1095 result = result + self.section('FUNCTIONS', join(contents, '\n'))
1097 if data:
1098 contents = []
1099 for key, value in data:
1100 contents.append(self.docother(value, key, name, maxlen=70))
1101 result = result + self.section('DATA', join(contents, '\n'))
1103 if hasattr(object, '__version__'):
1104 version = str(object.__version__)
1105 if version[:11] == '$' + 'Revision: ' and version[-1:] == '$':
1106 version = strip(version[11:-1])
1107 result = result + self.section('VERSION', version)
1108 if hasattr(object, '__date__'):
1109 result = result + self.section('DATE', str(object.__date__))
1110 if hasattr(object, '__author__'):
1111 result = result + self.section('AUTHOR', str(object.__author__))
1112 if hasattr(object, '__credits__'):
1113 result = result + self.section('CREDITS', str(object.__credits__))
1114 return result
1116 def docclass(self, object, name=None, mod=None):
1117 """Produce text documentation for a given class object."""
1118 realname = object.__name__
1119 name = name or realname
1120 bases = object.__bases__
1122 def makename(c, m=object.__module__):
1123 return classname(c, m)
1125 if name == realname:
1126 title = 'class ' + self.bold(realname)
1127 else:
1128 title = self.bold(name) + ' = class ' + realname
1129 if bases:
1130 parents = map(makename, bases)
1131 title = title + '(%s)' % join(parents, ', ')
1133 doc = getdoc(object)
1134 contents = doc and [doc + '\n'] or []
1135 push = contents.append
1137 # List the mro, if non-trivial.
1138 mro = deque(inspect.getmro(object))
1139 if len(mro) > 2:
1140 push("Method resolution order:")
1141 for base in mro:
1142 push(' ' + makename(base))
1143 push('')
1145 # Cute little class to pump out a horizontal rule between sections.
1146 class HorizontalRule:
1147 def __init__(self):
1148 self.needone = 0
1149 def maybe(self):
1150 if self.needone:
1151 push('-' * 70)
1152 self.needone = 1
1153 hr = HorizontalRule()
1155 def spill(msg, attrs, predicate):
1156 ok, attrs = _split_list(attrs, predicate)
1157 if ok:
1158 hr.maybe()
1159 push(msg)
1160 for name, kind, homecls, value in ok:
1161 push(self.document(getattr(object, name),
1162 name, mod, object))
1163 return attrs
1165 def spilldescriptors(msg, attrs, predicate):
1166 ok, attrs = _split_list(attrs, predicate)
1167 if ok:
1168 hr.maybe()
1169 push(msg)
1170 for name, kind, homecls, value in ok:
1171 push(self._docdescriptor(name, value, mod))
1172 return attrs
1174 def spilldata(msg, attrs, predicate):
1175 ok, attrs = _split_list(attrs, predicate)
1176 if ok:
1177 hr.maybe()
1178 push(msg)
1179 for name, kind, homecls, value in ok:
1180 if (hasattr(value, '__call__') or
1181 inspect.isdatadescriptor(value)):
1182 doc = getdoc(value)
1183 else:
1184 doc = None
1185 push(self.docother(getattr(object, name),
1186 name, mod, maxlen=70, doc=doc) + '\n')
1187 return attrs
1189 attrs = filter(lambda data: visiblename(data[0]),
1190 classify_class_attrs(object))
1191 while attrs:
1192 if mro:
1193 thisclass = mro.popleft()
1194 else:
1195 thisclass = attrs[0][2]
1196 attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass)
1198 if thisclass is __builtin__.object:
1199 attrs = inherited
1200 continue
1201 elif thisclass is object:
1202 tag = "defined here"
1203 else:
1204 tag = "inherited from %s" % classname(thisclass,
1205 object.__module__)
1207 # Sort attrs by name.
1208 attrs.sort()
1210 # Pump out the attrs, segregated by kind.
1211 attrs = spill("Methods %s:\n" % tag, attrs,
1212 lambda t: t[1] == 'method')
1213 attrs = spill("Class methods %s:\n" % tag, attrs,
1214 lambda t: t[1] == 'class method')
1215 attrs = spill("Static methods %s:\n" % tag, attrs,
1216 lambda t: t[1] == 'static method')
1217 attrs = spilldescriptors("Data descriptors %s:\n" % tag, attrs,
1218 lambda t: t[1] == 'data descriptor')
1219 attrs = spilldata("Data and other attributes %s:\n" % tag, attrs,
1220 lambda t: t[1] == 'data')
1221 assert attrs == []
1222 attrs = inherited
1224 contents = '\n'.join(contents)
1225 if not contents:
1226 return title + '\n'
1227 return title + '\n' + self.indent(rstrip(contents), ' | ') + '\n'
1229 def formatvalue(self, object):
1230 """Format an argument default value as text."""
1231 return '=' + self.repr(object)
1233 def docroutine(self, object, name=None, mod=None, cl=None):
1234 """Produce text documentation for a function or method object."""
1235 realname = object.__name__
1236 name = name or realname
1237 note = ''
1238 skipdocs = 0
1239 if inspect.ismethod(object):
1240 imclass = object.im_class
1241 if cl:
1242 if imclass is not cl:
1243 note = ' from ' + classname(imclass, mod)
1244 else:
1245 if object.im_self is not None:
1246 note = ' method of %s instance' % classname(
1247 object.im_self.__class__, mod)
1248 else:
1249 note = ' unbound %s method' % classname(imclass,mod)
1250 object = object.im_func
1252 if name == realname:
1253 title = self.bold(realname)
1254 else:
1255 if (cl and realname in cl.__dict__ and
1256 cl.__dict__[realname] is object):
1257 skipdocs = 1
1258 title = self.bold(name) + ' = ' + realname
1259 if inspect.isfunction(object):
1260 args, varargs, varkw, defaults = inspect.getargspec(object)
1261 argspec = inspect.formatargspec(
1262 args, varargs, varkw, defaults, formatvalue=self.formatvalue)
1263 if realname == '<lambda>':
1264 title = self.bold(name) + ' lambda '
1265 argspec = argspec[1:-1] # remove parentheses
1266 else:
1267 argspec = '(...)'
1268 decl = title + argspec + note
1270 if skipdocs:
1271 return decl + '\n'
1272 else:
1273 doc = getdoc(object) or ''
1274 return decl + '\n' + (doc and rstrip(self.indent(doc)) + '\n')
1276 def _docdescriptor(self, name, value, mod):
1277 results = []
1278 push = results.append
1280 if name:
1281 push(self.bold(name))
1282 push('\n')
1283 doc = getdoc(value) or ''
1284 if doc:
1285 push(self.indent(doc))
1286 push('\n')
1287 return ''.join(results)
1289 def docproperty(self, object, name=None, mod=None, cl=None):
1290 """Produce text documentation for a property."""
1291 return self._docdescriptor(name, object, mod)
1293 def docdata(self, object, name=None, mod=None, cl=None):
1294 """Produce text documentation for a data descriptor."""
1295 return self._docdescriptor(name, object, mod)
1297 def docother(self, object, name=None, mod=None, parent=None, maxlen=None, doc=None):
1298 """Produce text documentation for a data object."""
1299 repr = self.repr(object)
1300 if maxlen:
1301 line = (name and name + ' = ' or '') + repr
1302 chop = maxlen - len(line)
1303 if chop < 0: repr = repr[:chop] + '...'
1304 line = (name and self.bold(name) + ' = ' or '') + repr
1305 if doc is not None:
1306 line += '\n' + self.indent(str(doc))
1307 return line
1309 # --------------------------------------------------------- user interfaces
1311 def pager(text):
1312 """The first time this is called, determine what kind of pager to use."""
1313 global pager
1314 pager = getpager()
1315 pager(text)
1317 def getpager():
1318 """Decide what method to use for paging through text."""
1319 if type(sys.stdout) is not types.FileType:
1320 return plainpager
1321 if not sys.stdin.isatty() or not sys.stdout.isatty():
1322 return plainpager
1323 if 'PAGER' in os.environ:
1324 if sys.platform == 'win32': # pipes completely broken in Windows
1325 return lambda text: tempfilepager(plain(text), os.environ['PAGER'])
1326 elif os.environ.get('TERM') in ('dumb', 'emacs'):
1327 return lambda text: pipepager(plain(text), os.environ['PAGER'])
1328 else:
1329 return lambda text: pipepager(text, os.environ['PAGER'])
1330 if os.environ.get('TERM') in ('dumb', 'emacs'):
1331 return plainpager
1332 if sys.platform == 'win32' or sys.platform.startswith('os2'):
1333 return lambda text: tempfilepager(plain(text), 'more <')
1334 if hasattr(os, 'system') and os.system('(less) 2>/dev/null') == 0:
1335 return lambda text: pipepager(text, 'less')
1337 import tempfile
1338 (fd, filename) = tempfile.mkstemp()
1339 os.close(fd)
1340 try:
1341 if hasattr(os, 'system') and os.system('more "%s"' % filename) == 0:
1342 return lambda text: pipepager(text, 'more')
1343 else:
1344 return ttypager
1345 finally:
1346 os.unlink(filename)
1348 def plain(text):
1349 """Remove boldface formatting from text."""
1350 return re.sub('.\b', '', text)
1352 def pipepager(text, cmd):
1353 """Page through text by feeding it to another program."""
1354 pipe = os.popen(cmd, 'w')
1355 try:
1356 pipe.write(text)
1357 pipe.close()
1358 except IOError:
1359 pass # Ignore broken pipes caused by quitting the pager program.
1361 def tempfilepager(text, cmd):
1362 """Page through text by invoking a program on a temporary file."""
1363 import tempfile
1364 filename = tempfile.mktemp()
1365 file = open(filename, 'w')
1366 file.write(text)
1367 file.close()
1368 try:
1369 os.system(cmd + ' "' + filename + '"')
1370 finally:
1371 os.unlink(filename)
1373 def ttypager(text):
1374 """Page through text on a text terminal."""
1375 lines = split(plain(text), '\n')
1376 try:
1377 import tty
1378 fd = sys.stdin.fileno()
1379 old = tty.tcgetattr(fd)
1380 tty.setcbreak(fd)
1381 getchar = lambda: sys.stdin.read(1)
1382 except (ImportError, AttributeError):
1383 tty = None
1384 getchar = lambda: sys.stdin.readline()[:-1][:1]
1386 try:
1387 r = inc = os.environ.get('LINES', 25) - 1
1388 sys.stdout.write(join(lines[:inc], '\n') + '\n')
1389 while lines[r:]:
1390 sys.stdout.write('-- more --')
1391 sys.stdout.flush()
1392 c = getchar()
1394 if c in ('q', 'Q'):
1395 sys.stdout.write('\r \r')
1396 break
1397 elif c in ('\r', '\n'):
1398 sys.stdout.write('\r \r' + lines[r] + '\n')
1399 r = r + 1
1400 continue
1401 if c in ('b', 'B', '\x1b'):
1402 r = r - inc - inc
1403 if r < 0: r = 0
1404 sys.stdout.write('\n' + join(lines[r:r+inc], '\n') + '\n')
1405 r = r + inc
1407 finally:
1408 if tty:
1409 tty.tcsetattr(fd, tty.TCSAFLUSH, old)
1411 def plainpager(text):
1412 """Simply print unformatted text. This is the ultimate fallback."""
1413 sys.stdout.write(plain(text))
1415 def describe(thing):
1416 """Produce a short description of the given thing."""
1417 if inspect.ismodule(thing):
1418 if thing.__name__ in sys.builtin_module_names:
1419 return 'built-in module ' + thing.__name__
1420 if hasattr(thing, '__path__'):
1421 return 'package ' + thing.__name__
1422 else:
1423 return 'module ' + thing.__name__
1424 if inspect.isbuiltin(thing):
1425 return 'built-in function ' + thing.__name__
1426 if inspect.isgetsetdescriptor(thing):
1427 return 'getset descriptor %s.%s.%s' % (
1428 thing.__objclass__.__module__, thing.__objclass__.__name__,
1429 thing.__name__)
1430 if inspect.ismemberdescriptor(thing):
1431 return 'member descriptor %s.%s.%s' % (
1432 thing.__objclass__.__module__, thing.__objclass__.__name__,
1433 thing.__name__)
1434 if inspect.isclass(thing):
1435 return 'class ' + thing.__name__
1436 if inspect.isfunction(thing):
1437 return 'function ' + thing.__name__
1438 if inspect.ismethod(thing):
1439 return 'method ' + thing.__name__
1440 if type(thing) is types.InstanceType:
1441 return 'instance of ' + thing.__class__.__name__
1442 return type(thing).__name__
1444 def locate(path, forceload=0):
1445 """Locate an object by name or dotted path, importing as necessary."""
1446 parts = [part for part in split(path, '.') if part]
1447 module, n = None, 0
1448 while n < len(parts):
1449 nextmodule = safeimport(join(parts[:n+1], '.'), forceload)
1450 if nextmodule: module, n = nextmodule, n + 1
1451 else: break
1452 if module:
1453 object = module
1454 for part in parts[n:]:
1455 try: object = getattr(object, part)
1456 except AttributeError: return None
1457 return object
1458 else:
1459 if hasattr(__builtin__, path):
1460 return getattr(__builtin__, path)
1462 # --------------------------------------- interactive interpreter interface
1464 text = TextDoc()
1465 html = HTMLDoc()
1467 class _OldStyleClass: pass
1468 _OLD_INSTANCE_TYPE = type(_OldStyleClass())
1470 def resolve(thing, forceload=0):
1471 """Given an object or a path to an object, get the object and its name."""
1472 if isinstance(thing, str):
1473 object = locate(thing, forceload)
1474 if not object:
1475 raise ImportError, 'no Python documentation found for %r' % thing
1476 return object, thing
1477 else:
1478 return thing, getattr(thing, '__name__', None)
1480 def render_doc(thing, title='Python Library Documentation: %s', forceload=0):
1481 """Render text documentation, given an object or a path to an object."""
1482 object, name = resolve(thing, forceload)
1483 desc = describe(object)
1484 module = inspect.getmodule(object)
1485 if name and '.' in name:
1486 desc += ' in ' + name[:name.rfind('.')]
1487 elif module and module is not object:
1488 desc += ' in module ' + module.__name__
1489 if type(object) is _OLD_INSTANCE_TYPE:
1490 # If the passed object is an instance of an old-style class,
1491 # document its available methods instead of its value.
1492 object = object.__class__
1493 elif not (inspect.ismodule(object) or
1494 inspect.isclass(object) or
1495 inspect.isroutine(object) or
1496 inspect.isgetsetdescriptor(object) or
1497 inspect.ismemberdescriptor(object) or
1498 isinstance(object, property)):
1499 # If the passed object is a piece of data or an instance,
1500 # document its available methods instead of its value.
1501 object = type(object)
1502 desc += ' object'
1503 return title % desc + '\n\n' + text.document(object, name)
1505 def doc(thing, title='Python Library Documentation: %s', forceload=0):
1506 """Display text documentation, given an object or a path to an object."""
1507 try:
1508 pager(render_doc(thing, title, forceload))
1509 except (ImportError, ErrorDuringImport), value:
1510 print value
1512 def writedoc(thing, forceload=0):
1513 """Write HTML documentation to a file in the current directory."""
1514 try:
1515 object, name = resolve(thing, forceload)
1516 page = html.page(describe(object), html.document(object, name))
1517 file = open(name + '.html', 'w')
1518 file.write(page)
1519 file.close()
1520 print 'wrote', name + '.html'
1521 except (ImportError, ErrorDuringImport), value:
1522 print value
1524 def writedocs(dir, pkgpath='', done=None):
1525 """Write out HTML documentation for all modules in a directory tree."""
1526 if done is None: done = {}
1527 for importer, modname, ispkg in pkgutil.walk_packages([dir], pkgpath):
1528 writedoc(modname)
1529 return
1531 class Helper:
1533 # These dictionaries map a topic name to either an alias, or a tuple
1534 # (label, seealso-items). The "label" is the label of the corresponding
1535 # section in the .rst file under Doc/ and an index into the dictionary
1536 # in pydoc_topics.py.
1538 # CAUTION: if you change one of these dictionaries, be sure to adapt the
1539 # list of needed labels in Doc/tools/sphinxext/pyspecific.py and
1540 # regenerate the pydoc_topics.py file by running
1541 # make pydoc-topics
1542 # in Doc/ and copying the output file into the Lib/ directory.
1544 keywords = {
1545 'and': 'BOOLEAN',
1546 'as': 'with',
1547 'assert': ('assert', ''),
1548 'break': ('break', 'while for'),
1549 'class': ('class', 'CLASSES SPECIALMETHODS'),
1550 'continue': ('continue', 'while for'),
1551 'def': ('function', ''),
1552 'del': ('del', 'BASICMETHODS'),
1553 'elif': 'if',
1554 'else': ('else', 'while for'),
1555 'except': 'try',
1556 'exec': ('exec', ''),
1557 'finally': 'try',
1558 'for': ('for', 'break continue while'),
1559 'from': 'import',
1560 'global': ('global', 'NAMESPACES'),
1561 'if': ('if', 'TRUTHVALUE'),
1562 'import': ('import', 'MODULES'),
1563 'in': ('in', 'SEQUENCEMETHODS2'),
1564 'is': 'COMPARISON',
1565 'lambda': ('lambda', 'FUNCTIONS'),
1566 'not': 'BOOLEAN',
1567 'or': 'BOOLEAN',
1568 'pass': ('pass', ''),
1569 'print': ('print', ''),
1570 'raise': ('raise', 'EXCEPTIONS'),
1571 'return': ('return', 'FUNCTIONS'),
1572 'try': ('try', 'EXCEPTIONS'),
1573 'while': ('while', 'break continue if TRUTHVALUE'),
1574 'with': ('with', 'CONTEXTMANAGERS EXCEPTIONS yield'),
1575 'yield': ('yield', ''),
1577 # Either add symbols to this dictionary or to the symbols dictionary
1578 # directly: Whichever is easier. They are merged later.
1579 _symbols_inverse = {
1580 'STRINGS' : ("'", "'''", "r'", "u'", '"""', '"', 'r"', 'u"'),
1581 'OPERATORS' : ('+', '-', '*', '**', '/', '//', '%', '<<', '>>', '&',
1582 '|', '^', '~', '<', '>', '<=', '>=', '==', '!=', '<>'),
1583 'COMPARISON' : ('<', '>', '<=', '>=', '==', '!=', '<>'),
1584 'UNARY' : ('-', '~'),
1585 'AUGMENTEDASSIGNMENT' : ('+=', '-=', '*=', '/=', '%=', '&=', '|=',
1586 '^=', '<<=', '>>=', '**=', '//='),
1587 'BITWISE' : ('<<', '>>', '&', '|', '^', '~'),
1588 'COMPLEX' : ('j', 'J')
1590 symbols = {
1591 '%': 'OPERATORS FORMATTING',
1592 '**': 'POWER',
1593 ',': 'TUPLES LISTS FUNCTIONS',
1594 '.': 'ATTRIBUTES FLOAT MODULES OBJECTS',
1595 '...': 'ELLIPSIS',
1596 ':': 'SLICINGS DICTIONARYLITERALS',
1597 '@': 'def class',
1598 '\\': 'STRINGS',
1599 '_': 'PRIVATENAMES',
1600 '__': 'PRIVATENAMES SPECIALMETHODS',
1601 '`': 'BACKQUOTES',
1602 '(': 'TUPLES FUNCTIONS CALLS',
1603 ')': 'TUPLES FUNCTIONS CALLS',
1604 '[': 'LISTS SUBSCRIPTS SLICINGS',
1605 ']': 'LISTS SUBSCRIPTS SLICINGS'
1607 for topic, symbols_ in _symbols_inverse.iteritems():
1608 for symbol in symbols_:
1609 topics = symbols.get(symbol, topic)
1610 if topic not in topics:
1611 topics = topics + ' ' + topic
1612 symbols[symbol] = topics
1614 topics = {
1615 'TYPES': ('types', 'STRINGS UNICODE NUMBERS SEQUENCES MAPPINGS '
1616 'FUNCTIONS CLASSES MODULES FILES inspect'),
1617 'STRINGS': ('strings', 'str UNICODE SEQUENCES STRINGMETHODS FORMATTING '
1618 'TYPES'),
1619 'STRINGMETHODS': ('string-methods', 'STRINGS FORMATTING'),
1620 'FORMATTING': ('formatstrings', 'OPERATORS'),
1621 'UNICODE': ('strings', 'encodings unicode SEQUENCES STRINGMETHODS '
1622 'FORMATTING TYPES'),
1623 'NUMBERS': ('numbers', 'INTEGER FLOAT COMPLEX TYPES'),
1624 'INTEGER': ('integers', 'int range'),
1625 'FLOAT': ('floating', 'float math'),
1626 'COMPLEX': ('imaginary', 'complex cmath'),
1627 'SEQUENCES': ('typesseq', 'STRINGMETHODS FORMATTING xrange LISTS'),
1628 'MAPPINGS': 'DICTIONARIES',
1629 'FUNCTIONS': ('typesfunctions', 'def TYPES'),
1630 'METHODS': ('typesmethods', 'class def CLASSES TYPES'),
1631 'CODEOBJECTS': ('bltin-code-objects', 'compile FUNCTIONS TYPES'),
1632 'TYPEOBJECTS': ('bltin-type-objects', 'types TYPES'),
1633 'FRAMEOBJECTS': 'TYPES',
1634 'TRACEBACKS': 'TYPES',
1635 'NONE': ('bltin-null-object', ''),
1636 'ELLIPSIS': ('bltin-ellipsis-object', 'SLICINGS'),
1637 'FILES': ('bltin-file-objects', ''),
1638 'SPECIALATTRIBUTES': ('specialattrs', ''),
1639 'CLASSES': ('types', 'class SPECIALMETHODS PRIVATENAMES'),
1640 'MODULES': ('typesmodules', 'import'),
1641 'PACKAGES': 'import',
1642 'EXPRESSIONS': ('operator-summary', 'lambda or and not in is BOOLEAN '
1643 'COMPARISON BITWISE SHIFTING BINARY FORMATTING POWER '
1644 'UNARY ATTRIBUTES SUBSCRIPTS SLICINGS CALLS TUPLES '
1645 'LISTS DICTIONARIES BACKQUOTES'),
1646 'OPERATORS': 'EXPRESSIONS',
1647 'PRECEDENCE': 'EXPRESSIONS',
1648 'OBJECTS': ('objects', 'TYPES'),
1649 'SPECIALMETHODS': ('specialnames', 'BASICMETHODS ATTRIBUTEMETHODS '
1650 'CALLABLEMETHODS SEQUENCEMETHODS1 MAPPINGMETHODS '
1651 'SEQUENCEMETHODS2 NUMBERMETHODS CLASSES'),
1652 'BASICMETHODS': ('customization', 'cmp hash repr str SPECIALMETHODS'),
1653 'ATTRIBUTEMETHODS': ('attribute-access', 'ATTRIBUTES SPECIALMETHODS'),
1654 'CALLABLEMETHODS': ('callable-types', 'CALLS SPECIALMETHODS'),
1655 'SEQUENCEMETHODS1': ('sequence-types', 'SEQUENCES SEQUENCEMETHODS2 '
1656 'SPECIALMETHODS'),
1657 'SEQUENCEMETHODS2': ('sequence-methods', 'SEQUENCES SEQUENCEMETHODS1 '
1658 'SPECIALMETHODS'),
1659 'MAPPINGMETHODS': ('sequence-types', 'MAPPINGS SPECIALMETHODS'),
1660 'NUMBERMETHODS': ('numeric-types', 'NUMBERS AUGMENTEDASSIGNMENT '
1661 'SPECIALMETHODS'),
1662 'EXECUTION': ('execmodel', 'NAMESPACES DYNAMICFEATURES EXCEPTIONS'),
1663 'NAMESPACES': ('naming', 'global ASSIGNMENT DELETION DYNAMICFEATURES'),
1664 'DYNAMICFEATURES': ('dynamic-features', ''),
1665 'SCOPING': 'NAMESPACES',
1666 'FRAMES': 'NAMESPACES',
1667 'EXCEPTIONS': ('exceptions', 'try except finally raise'),
1668 'COERCIONS': ('coercion-rules','CONVERSIONS'),
1669 'CONVERSIONS': ('conversions', 'COERCIONS'),
1670 'IDENTIFIERS': ('identifiers', 'keywords SPECIALIDENTIFIERS'),
1671 'SPECIALIDENTIFIERS': ('id-classes', ''),
1672 'PRIVATENAMES': ('atom-identifiers', ''),
1673 'LITERALS': ('atom-literals', 'STRINGS BACKQUOTES NUMBERS '
1674 'TUPLELITERALS LISTLITERALS DICTIONARYLITERALS'),
1675 'TUPLES': 'SEQUENCES',
1676 'TUPLELITERALS': ('exprlists', 'TUPLES LITERALS'),
1677 'LISTS': ('typesseq-mutable', 'LISTLITERALS'),
1678 'LISTLITERALS': ('lists', 'LISTS LITERALS'),
1679 'DICTIONARIES': ('typesmapping', 'DICTIONARYLITERALS'),
1680 'DICTIONARYLITERALS': ('dict', 'DICTIONARIES LITERALS'),
1681 'BACKQUOTES': ('string-conversions', 'repr str STRINGS LITERALS'),
1682 'ATTRIBUTES': ('attribute-references', 'getattr hasattr setattr '
1683 'ATTRIBUTEMETHODS'),
1684 'SUBSCRIPTS': ('subscriptions', 'SEQUENCEMETHODS1'),
1685 'SLICINGS': ('slicings', 'SEQUENCEMETHODS2'),
1686 'CALLS': ('calls', 'EXPRESSIONS'),
1687 'POWER': ('power', 'EXPRESSIONS'),
1688 'UNARY': ('unary', 'EXPRESSIONS'),
1689 'BINARY': ('binary', 'EXPRESSIONS'),
1690 'SHIFTING': ('shifting', 'EXPRESSIONS'),
1691 'BITWISE': ('bitwise', 'EXPRESSIONS'),
1692 'COMPARISON': ('comparisons', 'EXPRESSIONS BASICMETHODS'),
1693 'BOOLEAN': ('booleans', 'EXPRESSIONS TRUTHVALUE'),
1694 'ASSERTION': 'assert',
1695 'ASSIGNMENT': ('assignment', 'AUGMENTEDASSIGNMENT'),
1696 'AUGMENTEDASSIGNMENT': ('augassign', 'NUMBERMETHODS'),
1697 'DELETION': 'del',
1698 'PRINTING': 'print',
1699 'RETURNING': 'return',
1700 'IMPORTING': 'import',
1701 'CONDITIONAL': 'if',
1702 'LOOPING': ('compound', 'for while break continue'),
1703 'TRUTHVALUE': ('truth', 'if while and or not BASICMETHODS'),
1704 'DEBUGGING': ('debugger', 'pdb'),
1705 'CONTEXTMANAGERS': ('context-managers', 'with'),
1708 def __init__(self, input, output):
1709 self.input = input
1710 self.output = output
1712 def __repr__(self):
1713 if inspect.stack()[1][3] == '?':
1714 self()
1715 return ''
1716 return '<pydoc.Helper instance>'
1718 def __call__(self, request=None):
1719 if request is not None:
1720 self.help(request)
1721 else:
1722 self.intro()
1723 self.interact()
1724 self.output.write('''
1725 You are now leaving help and returning to the Python interpreter.
1726 If you want to ask for help on a particular object directly from the
1727 interpreter, you can type "help(object)". Executing "help('string')"
1728 has the same effect as typing a particular string at the help> prompt.
1729 ''')
1731 def interact(self):
1732 self.output.write('\n')
1733 while True:
1734 try:
1735 request = self.getline('help> ')
1736 if not request: break
1737 except (KeyboardInterrupt, EOFError):
1738 break
1739 request = strip(replace(request, '"', '', "'", ''))
1740 if lower(request) in ('q', 'quit'): break
1741 self.help(request)
1743 def getline(self, prompt):
1744 """Read one line, using raw_input when available."""
1745 if self.input is sys.stdin:
1746 return raw_input(prompt)
1747 else:
1748 self.output.write(prompt)
1749 self.output.flush()
1750 return self.input.readline()
1752 def help(self, request):
1753 if type(request) is type(''):
1754 if request == 'help': self.intro()
1755 elif request == 'keywords': self.listkeywords()
1756 elif request == 'symbols': self.listsymbols()
1757 elif request == 'topics': self.listtopics()
1758 elif request == 'modules': self.listmodules()
1759 elif request[:8] == 'modules ':
1760 self.listmodules(split(request)[1])
1761 elif request in self.symbols: self.showsymbol(request)
1762 elif request in self.keywords: self.showtopic(request)
1763 elif request in self.topics: self.showtopic(request)
1764 elif request: doc(request, 'Help on %s:')
1765 elif isinstance(request, Helper): self()
1766 else: doc(request, 'Help on %s:')
1767 self.output.write('\n')
1769 def intro(self):
1770 self.output.write('''
1771 Welcome to Python %s! This is the online help utility.
1773 If this is your first time using Python, you should definitely check out
1774 the tutorial on the Internet at http://docs.python.org/tutorial/.
1776 Enter the name of any module, keyword, or topic to get help on writing
1777 Python programs and using Python modules. To quit this help utility and
1778 return to the interpreter, just type "quit".
1780 To get a list of available modules, keywords, or topics, type "modules",
1781 "keywords", or "topics". Each module also comes with a one-line summary
1782 of what it does; to list the modules whose summaries contain a given word
1783 such as "spam", type "modules spam".
1784 ''' % sys.version[:3])
1786 def list(self, items, columns=4, width=80):
1787 items = items[:]
1788 items.sort()
1789 colw = width / columns
1790 rows = (len(items) + columns - 1) / columns
1791 for row in range(rows):
1792 for col in range(columns):
1793 i = col * rows + row
1794 if i < len(items):
1795 self.output.write(items[i])
1796 if col < columns - 1:
1797 self.output.write(' ' + ' ' * (colw-1 - len(items[i])))
1798 self.output.write('\n')
1800 def listkeywords(self):
1801 self.output.write('''
1802 Here is a list of the Python keywords. Enter any keyword to get more help.
1804 ''')
1805 self.list(self.keywords.keys())
1807 def listsymbols(self):
1808 self.output.write('''
1809 Here is a list of the punctuation symbols which Python assigns special meaning
1810 to. Enter any symbol to get more help.
1812 ''')
1813 self.list(self.symbols.keys())
1815 def listtopics(self):
1816 self.output.write('''
1817 Here is a list of available topics. Enter any topic name to get more help.
1819 ''')
1820 self.list(self.topics.keys())
1822 def showtopic(self, topic, more_xrefs=''):
1823 try:
1824 import pydoc_topics
1825 except ImportError:
1826 self.output.write('''
1827 Sorry, topic and keyword documentation is not available because the
1828 module "pydoc_topics" could not be found.
1829 ''')
1830 return
1831 target = self.topics.get(topic, self.keywords.get(topic))
1832 if not target:
1833 self.output.write('no documentation found for %s\n' % repr(topic))
1834 return
1835 if type(target) is type(''):
1836 return self.showtopic(target, more_xrefs)
1838 label, xrefs = target
1839 try:
1840 doc = pydoc_topics.topics[label]
1841 except KeyError:
1842 self.output.write('no documentation found for %s\n' % repr(topic))
1843 return
1844 pager(strip(doc) + '\n')
1845 if more_xrefs:
1846 xrefs = (xrefs or '') + ' ' + more_xrefs
1847 if xrefs:
1848 import StringIO, formatter
1849 buffer = StringIO.StringIO()
1850 formatter.DumbWriter(buffer).send_flowing_data(
1851 'Related help topics: ' + join(split(xrefs), ', ') + '\n')
1852 self.output.write('\n%s\n' % buffer.getvalue())
1854 def showsymbol(self, symbol):
1855 target = self.symbols[symbol]
1856 topic, _, xrefs = target.partition(' ')
1857 self.showtopic(topic, xrefs)
1859 def listmodules(self, key=''):
1860 if key:
1861 self.output.write('''
1862 Here is a list of matching modules. Enter any module name to get more help.
1864 ''')
1865 apropos(key)
1866 else:
1867 self.output.write('''
1868 Please wait a moment while I gather a list of all available modules...
1870 ''')
1871 modules = {}
1872 def callback(path, modname, desc, modules=modules):
1873 if modname and modname[-9:] == '.__init__':
1874 modname = modname[:-9] + ' (package)'
1875 if find(modname, '.') < 0:
1876 modules[modname] = 1
1877 def onerror(modname):
1878 callback(None, modname, None)
1879 ModuleScanner().run(callback, onerror=onerror)
1880 self.list(modules.keys())
1881 self.output.write('''
1882 Enter any module name to get more help. Or, type "modules spam" to search
1883 for modules whose descriptions contain the word "spam".
1884 ''')
1886 help = Helper(sys.stdin, sys.stdout)
1888 class Scanner:
1889 """A generic tree iterator."""
1890 def __init__(self, roots, children, descendp):
1891 self.roots = roots[:]
1892 self.state = []
1893 self.children = children
1894 self.descendp = descendp
1896 def next(self):
1897 if not self.state:
1898 if not self.roots:
1899 return None
1900 root = self.roots.pop(0)
1901 self.state = [(root, self.children(root))]
1902 node, children = self.state[-1]
1903 if not children:
1904 self.state.pop()
1905 return self.next()
1906 child = children.pop(0)
1907 if self.descendp(child):
1908 self.state.append((child, self.children(child)))
1909 return child
1912 class ModuleScanner:
1913 """An interruptible scanner that searches module synopses."""
1915 def run(self, callback, key=None, completer=None, onerror=None):
1916 if key: key = lower(key)
1917 self.quit = False
1918 seen = {}
1920 for modname in sys.builtin_module_names:
1921 if modname != '__main__':
1922 seen[modname] = 1
1923 if key is None:
1924 callback(None, modname, '')
1925 else:
1926 desc = split(__import__(modname).__doc__ or '', '\n')[0]
1927 if find(lower(modname + ' - ' + desc), key) >= 0:
1928 callback(None, modname, desc)
1930 for importer, modname, ispkg in pkgutil.walk_packages(onerror=onerror):
1931 if self.quit:
1932 break
1933 if key is None:
1934 callback(None, modname, '')
1935 else:
1936 loader = importer.find_module(modname)
1937 if hasattr(loader,'get_source'):
1938 import StringIO
1939 desc = source_synopsis(
1940 StringIO.StringIO(loader.get_source(modname))
1941 ) or ''
1942 if hasattr(loader,'get_filename'):
1943 path = loader.get_filename(modname)
1944 else:
1945 path = None
1946 else:
1947 module = loader.load_module(modname)
1948 desc = (module.__doc__ or '').splitlines()[0]
1949 path = getattr(module,'__file__',None)
1950 if find(lower(modname + ' - ' + desc), key) >= 0:
1951 callback(path, modname, desc)
1953 if completer:
1954 completer()
1956 def apropos(key):
1957 """Print all the one-line module summaries that contain a substring."""
1958 def callback(path, modname, desc):
1959 if modname[-9:] == '.__init__':
1960 modname = modname[:-9] + ' (package)'
1961 print modname, desc and '- ' + desc
1962 try: import warnings
1963 except ImportError: pass
1964 else: warnings.filterwarnings('ignore') # ignore problems during import
1965 ModuleScanner().run(callback, key)
1967 # --------------------------------------------------- web browser interface
1969 def serve(port, callback=None, completer=None):
1970 import BaseHTTPServer, mimetools, select
1972 # Patch up mimetools.Message so it doesn't break if rfc822 is reloaded.
1973 class Message(mimetools.Message):
1974 def __init__(self, fp, seekable=1):
1975 Message = self.__class__
1976 Message.__bases__[0].__bases__[0].__init__(self, fp, seekable)
1977 self.encodingheader = self.getheader('content-transfer-encoding')
1978 self.typeheader = self.getheader('content-type')
1979 self.parsetype()
1980 self.parseplist()
1982 class DocHandler(BaseHTTPServer.BaseHTTPRequestHandler):
1983 def send_document(self, title, contents):
1984 try:
1985 self.send_response(200)
1986 self.send_header('Content-Type', 'text/html')
1987 self.end_headers()
1988 self.wfile.write(html.page(title, contents))
1989 except IOError: pass
1991 def do_GET(self):
1992 path = self.path
1993 if path[-5:] == '.html': path = path[:-5]
1994 if path[:1] == '/': path = path[1:]
1995 if path and path != '.':
1996 try:
1997 obj = locate(path, forceload=1)
1998 except ErrorDuringImport, value:
1999 self.send_document(path, html.escape(str(value)))
2000 return
2001 if obj:
2002 self.send_document(describe(obj), html.document(obj, path))
2003 else:
2004 self.send_document(path,
2005 'no Python documentation found for %s' % repr(path))
2006 else:
2007 heading = html.heading(
2008 '<big><big><strong>Python: Index of Modules</strong></big></big>',
2009 '#ffffff', '#7799ee')
2010 def bltinlink(name):
2011 return '<a href="%s.html">%s</a>' % (name, name)
2012 names = filter(lambda x: x != '__main__',
2013 sys.builtin_module_names)
2014 contents = html.multicolumn(names, bltinlink)
2015 indices = ['<p>' + html.bigsection(
2016 'Built-in Modules', '#ffffff', '#ee77aa', contents)]
2018 seen = {}
2019 for dir in sys.path:
2020 indices.append(html.index(dir, seen))
2021 contents = heading + join(indices) + '''<p align=right>
2022 <font color="#909090" face="helvetica, arial"><strong>
2023 pydoc</strong> by Ka-Ping Yee &lt;ping@lfw.org&gt;</font>'''
2024 self.send_document('Index of Modules', contents)
2026 def log_message(self, *args): pass
2028 class DocServer(BaseHTTPServer.HTTPServer):
2029 def __init__(self, port, callback):
2030 host = (sys.platform == 'mac') and '127.0.0.1' or 'localhost'
2031 self.address = ('', port)
2032 self.url = 'http://%s:%d/' % (host, port)
2033 self.callback = callback
2034 self.base.__init__(self, self.address, self.handler)
2036 def serve_until_quit(self):
2037 import select
2038 self.quit = False
2039 while not self.quit:
2040 rd, wr, ex = select.select([self.socket.fileno()], [], [], 1)
2041 if rd: self.handle_request()
2043 def server_activate(self):
2044 self.base.server_activate(self)
2045 if self.callback: self.callback(self)
2047 DocServer.base = BaseHTTPServer.HTTPServer
2048 DocServer.handler = DocHandler
2049 DocHandler.MessageClass = Message
2050 try:
2051 try:
2052 DocServer(port, callback).serve_until_quit()
2053 except (KeyboardInterrupt, select.error):
2054 pass
2055 finally:
2056 if completer: completer()
2058 # ----------------------------------------------------- graphical interface
2060 def gui():
2061 """Graphical interface (starts web server and pops up a control window)."""
2062 class GUI:
2063 def __init__(self, window, port=7464):
2064 self.window = window
2065 self.server = None
2066 self.scanner = None
2068 import Tkinter
2069 self.server_frm = Tkinter.Frame(window)
2070 self.title_lbl = Tkinter.Label(self.server_frm,
2071 text='Starting server...\n ')
2072 self.open_btn = Tkinter.Button(self.server_frm,
2073 text='open browser', command=self.open, state='disabled')
2074 self.quit_btn = Tkinter.Button(self.server_frm,
2075 text='quit serving', command=self.quit, state='disabled')
2077 self.search_frm = Tkinter.Frame(window)
2078 self.search_lbl = Tkinter.Label(self.search_frm, text='Search for')
2079 self.search_ent = Tkinter.Entry(self.search_frm)
2080 self.search_ent.bind('<Return>', self.search)
2081 self.stop_btn = Tkinter.Button(self.search_frm,
2082 text='stop', pady=0, command=self.stop, state='disabled')
2083 if sys.platform == 'win32':
2084 # Trying to hide and show this button crashes under Windows.
2085 self.stop_btn.pack(side='right')
2087 self.window.title('pydoc')
2088 self.window.protocol('WM_DELETE_WINDOW', self.quit)
2089 self.title_lbl.pack(side='top', fill='x')
2090 self.open_btn.pack(side='left', fill='x', expand=1)
2091 self.quit_btn.pack(side='right', fill='x', expand=1)
2092 self.server_frm.pack(side='top', fill='x')
2094 self.search_lbl.pack(side='left')
2095 self.search_ent.pack(side='right', fill='x', expand=1)
2096 self.search_frm.pack(side='top', fill='x')
2097 self.search_ent.focus_set()
2099 font = ('helvetica', sys.platform == 'win32' and 8 or 10)
2100 self.result_lst = Tkinter.Listbox(window, font=font, height=6)
2101 self.result_lst.bind('<Button-1>', self.select)
2102 self.result_lst.bind('<Double-Button-1>', self.goto)
2103 self.result_scr = Tkinter.Scrollbar(window,
2104 orient='vertical', command=self.result_lst.yview)
2105 self.result_lst.config(yscrollcommand=self.result_scr.set)
2107 self.result_frm = Tkinter.Frame(window)
2108 self.goto_btn = Tkinter.Button(self.result_frm,
2109 text='go to selected', command=self.goto)
2110 self.hide_btn = Tkinter.Button(self.result_frm,
2111 text='hide results', command=self.hide)
2112 self.goto_btn.pack(side='left', fill='x', expand=1)
2113 self.hide_btn.pack(side='right', fill='x', expand=1)
2115 self.window.update()
2116 self.minwidth = self.window.winfo_width()
2117 self.minheight = self.window.winfo_height()
2118 self.bigminheight = (self.server_frm.winfo_reqheight() +
2119 self.search_frm.winfo_reqheight() +
2120 self.result_lst.winfo_reqheight() +
2121 self.result_frm.winfo_reqheight())
2122 self.bigwidth, self.bigheight = self.minwidth, self.bigminheight
2123 self.expanded = 0
2124 self.window.wm_geometry('%dx%d' % (self.minwidth, self.minheight))
2125 self.window.wm_minsize(self.minwidth, self.minheight)
2126 self.window.tk.willdispatch()
2128 import threading
2129 threading.Thread(
2130 target=serve, args=(port, self.ready, self.quit)).start()
2132 def ready(self, server):
2133 self.server = server
2134 self.title_lbl.config(
2135 text='Python documentation server at\n' + server.url)
2136 self.open_btn.config(state='normal')
2137 self.quit_btn.config(state='normal')
2139 def open(self, event=None, url=None):
2140 url = url or self.server.url
2141 try:
2142 import webbrowser
2143 webbrowser.open(url)
2144 except ImportError: # pre-webbrowser.py compatibility
2145 if sys.platform == 'win32':
2146 os.system('start "%s"' % url)
2147 elif sys.platform == 'mac':
2148 try: import ic
2149 except ImportError: pass
2150 else: ic.launchurl(url)
2151 else:
2152 rc = os.system('netscape -remote "openURL(%s)" &' % url)
2153 if rc: os.system('netscape "%s" &' % url)
2155 def quit(self, event=None):
2156 if self.server:
2157 self.server.quit = 1
2158 self.window.quit()
2160 def search(self, event=None):
2161 key = self.search_ent.get()
2162 self.stop_btn.pack(side='right')
2163 self.stop_btn.config(state='normal')
2164 self.search_lbl.config(text='Searching for "%s"...' % key)
2165 self.search_ent.forget()
2166 self.search_lbl.pack(side='left')
2167 self.result_lst.delete(0, 'end')
2168 self.goto_btn.config(state='disabled')
2169 self.expand()
2171 import threading
2172 if self.scanner:
2173 self.scanner.quit = 1
2174 self.scanner = ModuleScanner()
2175 threading.Thread(target=self.scanner.run,
2176 args=(self.update, key, self.done)).start()
2178 def update(self, path, modname, desc):
2179 if modname[-9:] == '.__init__':
2180 modname = modname[:-9] + ' (package)'
2181 self.result_lst.insert('end',
2182 modname + ' - ' + (desc or '(no description)'))
2184 def stop(self, event=None):
2185 if self.scanner:
2186 self.scanner.quit = 1
2187 self.scanner = None
2189 def done(self):
2190 self.scanner = None
2191 self.search_lbl.config(text='Search for')
2192 self.search_lbl.pack(side='left')
2193 self.search_ent.pack(side='right', fill='x', expand=1)
2194 if sys.platform != 'win32': self.stop_btn.forget()
2195 self.stop_btn.config(state='disabled')
2197 def select(self, event=None):
2198 self.goto_btn.config(state='normal')
2200 def goto(self, event=None):
2201 selection = self.result_lst.curselection()
2202 if selection:
2203 modname = split(self.result_lst.get(selection[0]))[0]
2204 self.open(url=self.server.url + modname + '.html')
2206 def collapse(self):
2207 if not self.expanded: return
2208 self.result_frm.forget()
2209 self.result_scr.forget()
2210 self.result_lst.forget()
2211 self.bigwidth = self.window.winfo_width()
2212 self.bigheight = self.window.winfo_height()
2213 self.window.wm_geometry('%dx%d' % (self.minwidth, self.minheight))
2214 self.window.wm_minsize(self.minwidth, self.minheight)
2215 self.expanded = 0
2217 def expand(self):
2218 if self.expanded: return
2219 self.result_frm.pack(side='bottom', fill='x')
2220 self.result_scr.pack(side='right', fill='y')
2221 self.result_lst.pack(side='top', fill='both', expand=1)
2222 self.window.wm_geometry('%dx%d' % (self.bigwidth, self.bigheight))
2223 self.window.wm_minsize(self.minwidth, self.bigminheight)
2224 self.expanded = 1
2226 def hide(self, event=None):
2227 self.stop()
2228 self.collapse()
2230 import Tkinter
2231 try:
2232 root = Tkinter.Tk()
2233 # Tk will crash if pythonw.exe has an XP .manifest
2234 # file and the root has is not destroyed explicitly.
2235 # If the problem is ever fixed in Tk, the explicit
2236 # destroy can go.
2237 try:
2238 gui = GUI(root)
2239 root.mainloop()
2240 finally:
2241 root.destroy()
2242 except KeyboardInterrupt:
2243 pass
2245 # -------------------------------------------------- command-line interface
2247 def ispath(x):
2248 return isinstance(x, str) and find(x, os.sep) >= 0
2250 def cli():
2251 """Command-line interface (looks at sys.argv to decide what to do)."""
2252 import getopt
2253 class BadUsage: pass
2255 # Scripts don't get the current directory in their path by default.
2256 scriptdir = os.path.dirname(sys.argv[0])
2257 if scriptdir in sys.path:
2258 sys.path.remove(scriptdir)
2259 sys.path.insert(0, '.')
2261 try:
2262 opts, args = getopt.getopt(sys.argv[1:], 'gk:p:w')
2263 writing = 0
2265 for opt, val in opts:
2266 if opt == '-g':
2267 gui()
2268 return
2269 if opt == '-k':
2270 apropos(val)
2271 return
2272 if opt == '-p':
2273 try:
2274 port = int(val)
2275 except ValueError:
2276 raise BadUsage
2277 def ready(server):
2278 print 'pydoc server ready at %s' % server.url
2279 def stopped():
2280 print 'pydoc server stopped'
2281 serve(port, ready, stopped)
2282 return
2283 if opt == '-w':
2284 writing = 1
2286 if not args: raise BadUsage
2287 for arg in args:
2288 if ispath(arg) and not os.path.exists(arg):
2289 print 'file %r does not exist' % arg
2290 break
2291 try:
2292 if ispath(arg) and os.path.isfile(arg):
2293 arg = importfile(arg)
2294 if writing:
2295 if ispath(arg) and os.path.isdir(arg):
2296 writedocs(arg)
2297 else:
2298 writedoc(arg)
2299 else:
2300 help.help(arg)
2301 except ErrorDuringImport, value:
2302 print value
2304 except (getopt.error, BadUsage):
2305 cmd = os.path.basename(sys.argv[0])
2306 print """pydoc - the Python documentation tool
2308 %s <name> ...
2309 Show text documentation on something. <name> may be the name of a
2310 Python keyword, topic, function, module, or package, or a dotted
2311 reference to a class or function within a module or module in a
2312 package. If <name> contains a '%s', it is used as the path to a
2313 Python source file to document. If name is 'keywords', 'topics',
2314 or 'modules', a listing of these things is displayed.
2316 %s -k <keyword>
2317 Search for a keyword in the synopsis lines of all available modules.
2319 %s -p <port>
2320 Start an HTTP server on the given port on the local machine.
2322 %s -g
2323 Pop up a graphical interface for finding and serving documentation.
2325 %s -w <name> ...
2326 Write out the HTML documentation for a module to a file in the current
2327 directory. If <name> contains a '%s', it is treated as a filename; if
2328 it names a directory, documentation is written for all the contents.
2329 """ % (cmd, os.sep, cmd, cmd, cmd, cmd, os.sep)
2331 if __name__ == '__main__': cli()