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://www.python.org/doc/current/lib/
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.
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.
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
57 from string
import expandtabs
, find
, join
, lower
, split
, strip
, rfind
, rstrip
59 from collections
import deque
61 # Python 2.3 compatibility
66 # --------------------------------------------------------- common routines
69 """Convert sys.path into a list of absolute, existing, unique paths."""
73 dir = os
.path
.abspath(dir or '.')
74 normdir
= os
.path
.normcase(dir)
75 if normdir
not in normdirs
and os
.path
.isdir(dir):
77 normdirs
.append(normdir
)
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 ''
86 """Split a doc string into a synopsis line (if any) and the rest."""
87 lines
= split(strip(doc
), '\n')
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
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."""
110 text
= join(split(text
, pairs
[0]), pairs
[1])
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
:]
122 _re_stripid
= re
.compile(r
' at 0x[0-9a-f]{6,16}(>+)$', re
.IGNORECASE
)
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
)
130 def _is_some_method(obj
):
131 return inspect
.ismethod(obj
) or inspect
.ismethoddescriptor(obj
)
135 for key
, value
in inspect
.getmembers(cl
, _is_some_method
):
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
)
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)])
160 def visiblename(name
, all
=None):
161 """Decide whether to show documentation on a variable."""
162 # Certain special names are redundant.
163 if name
in ('__builtins__', '__doc__', '__file__', '__path__',
164 '__module__', '__name__', '__slots__'): return 0
165 # Private names are hidden, but special names are displayed.
166 if name
.startswith('__') and name
.endswith('__'): return 1
168 # only document that which the programmer exported in __all__
171 return not name
.startswith('_')
173 def classify_class_attrs(object):
174 """Wrap inspect.classify_class_attrs, with fixup for data descriptors."""
175 def fixup((name
, kind
, cls
, value
)):
176 if inspect
.isdatadescriptor(value
):
177 kind
= 'data descriptor'
178 return name
, kind
, cls
, value
179 return map(fixup
, inspect
.classify_class_attrs(object))
181 # ----------------------------------------------------- module manipulation
184 """Guess whether a path refers to a package directory."""
185 if os
.path
.isdir(path
):
186 for ext
in ('.py', '.pyc', '.pyo'):
187 if os
.path
.isfile(os
.path
.join(path
, '__init__' + ext
)):
191 def source_synopsis(file):
192 line
= file.readline()
193 while line
[:1] == '#' or not strip(line
):
194 line
= file.readline()
197 if line
[:4] == 'r"""': line
= line
[1:]
198 if line
[:3] == '"""':
200 if line
[-1:] == '\\': line
= line
[:-1]
201 while not strip(line
):
202 line
= file.readline()
204 result
= strip(split(line
, '"""')[0])
208 def synopsis(filename
, cache
={}):
209 """Get the one-line summary out of a module file."""
210 mtime
= os
.stat(filename
).st_mtime
211 lastupdate
, result
= cache
.get(filename
, (0, None))
212 if lastupdate
< mtime
:
213 info
= inspect
.getmoduleinfo(filename
)
215 file = open(filename
)
217 # module can't be opened, so skip it
219 if info
and 'b' in info
[2]: # binary modules have to be imported
220 try: module
= imp
.load_module('__temp__', file, filename
, info
[1:])
222 result
= (module
.__doc
__ or '').splitlines()[0]
223 del sys
.modules
['__temp__']
224 else: # text modules can be directly examined
225 result
= source_synopsis(file)
227 cache
[filename
] = (mtime
, result
)
230 class ErrorDuringImport(Exception):
231 """Errors that occurred while trying to import something to document it."""
232 def __init__(self
, filename
, (exc
, value
, tb
)):
233 self
.filename
= filename
240 if type(exc
) is types
.ClassType
:
242 return 'problem in %s - %s: %s' % (self
.filename
, exc
, self
.value
)
244 def importfile(path
):
245 """Import a Python source file or compiled file given its path."""
246 magic
= imp
.get_magic()
247 file = open(path
, 'r')
248 if file.read(len(magic
)) == magic
:
249 kind
= imp
.PY_COMPILED
253 filename
= os
.path
.basename(path
)
254 name
, ext
= os
.path
.splitext(filename
)
255 file = open(path
, 'r')
257 module
= imp
.load_module(name
, file, path
, (ext
, 'r', kind
))
259 raise ErrorDuringImport(path
, sys
.exc_info())
263 def safeimport(path
, forceload
=0, cache
={}):
264 """Import a module; handle errors; return None if the module isn't found.
266 If the module *is* found but an exception occurs, it's wrapped in an
267 ErrorDuringImport exception and reraised. Unlike __import__, if a
268 package path is specified, the module at the end of the path is returned,
269 not the package at the beginning. If the optional 'forceload' argument
270 is 1, we reload the module from disk (unless it's a dynamic extension)."""
272 # If forceload is 1 and the module has been previously loaded from
273 # disk, we always have to reload the module. Checking the file's
274 # mtime isn't good enough (e.g. the module could contain a class
275 # that inherits from another module that has changed).
276 if forceload
and path
in sys
.modules
:
277 if path
not in sys
.builtin_module_names
:
278 # Avoid simply calling reload() because it leaves names in
279 # the currently loaded module lying around if they're not
280 # defined in the new source file. Instead, remove the
281 # module from sys.modules and re-import. Also remove any
282 # submodules because they won't appear in the newly loaded
283 # module's namespace if they're already in sys.modules.
284 subs
= [m
for m
in sys
.modules
if m
.startswith(path
+ '.')]
285 for key
in [path
] + subs
:
286 # Prevent garbage collection.
287 cache
[key
] = sys
.modules
[key
]
289 module
= __import__(path
)
291 # Did the error occur before or after the module was found?
292 (exc
, value
, tb
) = info
= sys
.exc_info()
293 if path
in sys
.modules
:
294 # An error occurred while executing the imported module.
295 raise ErrorDuringImport(sys
.modules
[path
].__file
__, info
)
296 elif exc
is SyntaxError:
297 # A SyntaxError occurred before we could execute the module.
298 raise ErrorDuringImport(value
.filename
, info
)
299 elif exc
is ImportError and \
300 split(lower(str(value
)))[:2] == ['no', 'module']:
301 # The module was not found.
304 # Some other error occurred during the importing process.
305 raise ErrorDuringImport(path
, sys
.exc_info())
306 for part
in split(path
, '.')[1:]:
307 try: module
= getattr(module
, part
)
308 except AttributeError: return None
311 # ---------------------------------------------------- formatter base class
314 def document(self
, object, name
=None, *args
):
315 """Generate documentation for an object."""
316 args
= (object, name
) + args
317 # 'try' clause is to attempt to handle the possibility that inspect
318 # identifies something in a way that pydoc itself has issues handling;
319 # think 'super' and how it is a descriptor (which raises the exception
320 # by lacking a __name__ attribute) and an instance.
321 if inspect
.isgetsetdescriptor(object): return self
.docdata(*args
)
322 if inspect
.ismemberdescriptor(object): return self
.docdata(*args
)
324 if inspect
.ismodule(object): return self
.docmodule(*args
)
325 if inspect
.isclass(object): return self
.docclass(*args
)
326 if inspect
.isroutine(object): return self
.docroutine(*args
)
327 except AttributeError:
329 if isinstance(object, property): return self
.docproperty(*args
)
330 return self
.docother(*args
)
332 def fail(self
, object, name
=None, *args
):
333 """Raise an exception for unimplemented types."""
334 message
= "don't know how to document object%s of type %s" % (
335 name
and ' ' + repr(name
), type(object).__name
__)
336 raise TypeError, message
338 docmodule
= docclass
= docroutine
= docother
= docproperty
= docdata
= fail
340 def getdocloc(self
, object):
341 """Return the location of module docs or None"""
344 file = inspect
.getabsfile(object)
348 docloc
= os
.environ
.get("PYTHONDOCS",
349 "http://www.python.org/doc/current/lib")
350 basedir
= os
.path
.join(sys
.exec_prefix
, "lib",
351 "python"+sys
.version
[0:3])
352 if (isinstance(object, type(os
)) and
353 (object.__name
__ in ('errno', 'exceptions', 'gc', 'imp',
354 'marshal', 'posix', 'signal', 'sys',
355 'thread', 'zipimport') or
356 (file.startswith(basedir
) and
357 not file.startswith(os
.path
.join(basedir
, 'site-packages'))))):
358 htmlfile
= "module-%s.html" % object.__name
__
359 if docloc
.startswith("http://"):
360 docloc
= "%s/%s" % (docloc
.rstrip("/"), htmlfile
)
362 docloc
= os
.path
.join(docloc
, htmlfile
)
367 # -------------------------------------------- HTML documentation generator
369 class HTMLRepr(Repr
):
370 """Class for safely making an HTML representation of a Python object."""
373 self
.maxlist
= self
.maxtuple
= 20
375 self
.maxstring
= self
.maxother
= 100
377 def escape(self
, text
):
378 return replace(text
, '&', '&', '<', '<', '>', '>')
380 def repr(self
, object):
381 return Repr
.repr(self
, object)
383 def repr1(self
, x
, level
):
384 if hasattr(type(x
), '__name__'):
385 methodname
= 'repr_' + join(split(type(x
).__name
__), '_')
386 if hasattr(self
, methodname
):
387 return getattr(self
, methodname
)(x
, level
)
388 return self
.escape(cram(stripid(repr(x
)), self
.maxother
))
390 def repr_string(self
, x
, level
):
391 test
= cram(x
, self
.maxstring
)
392 testrepr
= repr(test
)
393 if '\\' in test
and '\\' not in replace(testrepr
, r
'\\', ''):
394 # Backslashes are only literal in the string and are never
395 # needed to make any special characters, so show a raw string.
396 return 'r' + testrepr
[0] + self
.escape(test
) + testrepr
[0]
397 return re
.sub(r
'((\\[\\abfnrtv\'"]|\\[0-9]..|\\x..|\\u....)+)',
398 r'<font color="#c040c0">\1</font>',
399 self
.escape(testrepr
))
401 repr_str
= repr_string
403 def repr_instance(self
, x
, level
):
405 return self
.escape(cram(stripid(repr(x
)), self
.maxstring
))
407 return self
.escape('<%s instance>' % x
.__class
__.__name
__)
409 repr_unicode
= repr_string
412 """Formatter class for HTML documentation."""
414 # ------------------------------------------- HTML formatting utilities
416 _repr_instance
= HTMLRepr()
417 repr = _repr_instance
.repr
418 escape
= _repr_instance
.escape
420 def page(self
, title
, contents
):
421 """Format an HTML page."""
423 <!doctype html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
424 <html><head><title>Python: %s</title>
425 </head><body bgcolor="#f0f0f8">
427 </body></html>''' % (title
, contents
)
429 def heading(self
, title
, fgcol
, bgcol
, extras
=''):
430 """Format a page heading."""
432 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="heading">
434 <td valign=bottom> <br>
435 <font color="%s" face="helvetica, arial"> <br>%s</font></td
436 ><td align=right valign=bottom
437 ><font color="%s" face="helvetica, arial">%s</font></td></tr></table>
438 ''' % (bgcol
, fgcol
, title
, fgcol
, extras
or ' ')
440 def section(self
, title
, fgcol
, bgcol
, contents
, width
=6,
441 prelude
='', marginalia
=None, gap
=' '):
442 """Format a section with a heading."""
443 if marginalia
is None:
444 marginalia
= '<tt>' + ' ' * width
+ '</tt>'
446 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
448 <td colspan=3 valign=bottom> <br>
449 <font color="%s" face="helvetica, arial">%s</font></td></tr>
450 ''' % (bgcol
, fgcol
, title
)
452 result
= result
+ '''
453 <tr bgcolor="%s"><td rowspan=2>%s</td>
454 <td colspan=2>%s</td></tr>
455 <tr><td>%s</td>''' % (bgcol
, marginalia
, prelude
, gap
)
457 result
= result
+ '''
458 <tr><td bgcolor="%s">%s</td><td>%s</td>''' % (bgcol
, marginalia
, gap
)
460 return result
+ '\n<td width="100%%">%s</td></tr></table>' % contents
462 def bigsection(self
, title
, *args
):
463 """Format a section with a big heading."""
464 title
= '<big><strong>%s</strong></big>' % title
465 return self
.section(title
, *args
)
467 def preformat(self
, text
):
468 """Format literal preformatted text."""
469 text
= self
.escape(expandtabs(text
))
470 return replace(text
, '\n\n', '\n \n', '\n\n', '\n \n',
471 ' ', ' ', '\n', '<br>\n')
473 def multicolumn(self
, list, format
, cols
=4):
474 """Format a list of items into a multi-column list."""
476 rows
= (len(list)+cols
-1)/cols
477 for col
in range(cols
):
478 result
= result
+ '<td width="%d%%" valign=top>' % (100/cols
)
479 for i
in range(rows
*col
, rows
*col
+rows
):
481 result
= result
+ format(list[i
]) + '<br>\n'
482 result
= result
+ '</td>'
483 return '<table width="100%%" summary="list"><tr>%s</tr></table>' % result
485 def grey(self
, text
): return '<font color="#909090">%s</font>' % text
487 def namelink(self
, name
, *dicts
):
488 """Make a link for an identifier, given name-to-URL mappings."""
491 return '<a href="%s">%s</a>' % (dict[name
], name
)
494 def classlink(self
, object, modname
):
495 """Make a link for a class."""
496 name
, module
= object.__name
__, sys
.modules
.get(object.__module
__)
497 if hasattr(module
, name
) and getattr(module
, name
) is object:
498 return '<a href="%s.html#%s">%s</a>' % (
499 module
.__name
__, name
, classname(object, modname
))
500 return classname(object, modname
)
502 def modulelink(self
, object):
503 """Make a link for a module."""
504 return '<a href="%s.html">%s</a>' % (object.__name
__, object.__name
__)
506 def modpkglink(self
, (name
, path
, ispackage
, shadowed
)):
507 """Make a link for a module or package to display in an index."""
509 return self
.grey(name
)
511 url
= '%s.%s.html' % (path
, name
)
513 url
= '%s.html' % name
515 text
= '<strong>%s</strong> (package)' % name
518 return '<a href="%s">%s</a>' % (url
, text
)
520 def markup(self
, text
, escape
=None, funcs
={}, classes
={}, methods
={}):
521 """Mark up some plain text, given a context of symbols to look for.
522 Each context dictionary maps object names to anchor names."""
523 escape
= escape
or self
.escape
526 pattern
= re
.compile(r
'\b((http|ftp)://\S+[\w/]|'
531 match
= pattern
.search(text
, here
)
533 start
, end
= match
.span()
534 results
.append(escape(text
[here
:start
]))
536 all
, scheme
, rfc
, pep
, selfdot
, name
= match
.groups()
538 url
= escape(all
).replace('"', '"')
539 results
.append('<a href="%s">%s</a>' % (url
, url
))
541 url
= 'http://www.rfc-editor.org/rfc/rfc%d.txt' % int(rfc
)
542 results
.append('<a href="%s">%s</a>' % (url
, escape(all
)))
544 url
= 'http://www.python.org/peps/pep-%04d.html' % int(pep
)
545 results
.append('<a href="%s">%s</a>' % (url
, escape(all
)))
546 elif text
[end
:end
+1] == '(':
547 results
.append(self
.namelink(name
, methods
, funcs
, classes
))
549 results
.append('self.<strong>%s</strong>' % name
)
551 results
.append(self
.namelink(name
, classes
))
553 results
.append(escape(text
[here
:]))
554 return join(results
, '')
556 # ---------------------------------------------- type-specific routines
558 def formattree(self
, tree
, modname
, parent
=None):
559 """Produce HTML for a class tree as given by inspect.getclasstree()."""
562 if type(entry
) is type(()):
564 result
= result
+ '<dt><font face="helvetica, arial">'
565 result
= result
+ self
.classlink(c
, modname
)
566 if bases
and bases
!= (parent
,):
569 parents
.append(self
.classlink(base
, modname
))
570 result
= result
+ '(' + join(parents
, ', ') + ')'
571 result
= result
+ '\n</font></dt>'
572 elif type(entry
) is type([]):
573 result
= result
+ '<dd>\n%s</dd>\n' % self
.formattree(
575 return '<dl>\n%s</dl>\n' % result
577 def docmodule(self
, object, name
=None, mod
=None, *ignored
):
578 """Produce HTML documentation for a module object."""
579 name
= object.__name
__ # ignore the passed-in name
582 except AttributeError:
584 parts
= split(name
, '.')
586 for i
in range(len(parts
)-1):
588 '<a href="%s.html"><font color="#ffffff">%s</font></a>' %
589 (join(parts
[:i
+1], '.'), parts
[i
]))
590 linkedname
= join(links
+ parts
[-1:], '.')
591 head
= '<big><big><strong>%s</strong></big></big>' % linkedname
593 path
= inspect
.getabsfile(object)
595 if sys
.platform
== 'win32':
597 url
= nturl2path
.pathname2url(path
)
598 filelink
= '<a href="file:%s">%s</a>' % (url
, path
)
600 filelink
= '(built-in)'
602 if hasattr(object, '__version__'):
603 version
= str(object.__version
__)
604 if version
[:11] == '$' + 'Revision: ' and version
[-1:] == '$':
605 version
= strip(version
[11:-1])
606 info
.append('version %s' % self
.escape(version
))
607 if hasattr(object, '__date__'):
608 info
.append(self
.escape(str(object.__date
__)))
610 head
= head
+ ' (%s)' % join(info
, ', ')
611 docloc
= self
.getdocloc(object)
612 if docloc
is not None:
613 docloc
= '<br><a href="%(docloc)s">Module Docs</a>' % locals()
616 result
= self
.heading(
617 head
, '#ffffff', '#7799ee',
618 '<a href=".">index</a><br>' + filelink
+ docloc
)
620 modules
= inspect
.getmembers(object, inspect
.ismodule
)
622 classes
, cdict
= [], {}
623 for key
, value
in inspect
.getmembers(object, inspect
.isclass
):
624 # if __all__ exists, believe it. Otherwise use old heuristic.
625 if (all
is not None or
626 (inspect
.getmodule(value
) or object) is object):
627 if visiblename(key
, all
):
628 classes
.append((key
, value
))
629 cdict
[key
] = cdict
[value
] = '#' + key
630 for key
, value
in classes
:
631 for base
in value
.__bases
__:
632 key
, modname
= base
.__name
__, base
.__module
__
633 module
= sys
.modules
.get(modname
)
634 if modname
!= name
and module
and hasattr(module
, key
):
635 if getattr(module
, key
) is base
:
637 cdict
[key
] = cdict
[base
] = modname
+ '.html#' + key
638 funcs
, fdict
= [], {}
639 for key
, value
in inspect
.getmembers(object, inspect
.isroutine
):
640 # if __all__ exists, believe it. Otherwise use old heuristic.
641 if (all
is not None or
642 inspect
.isbuiltin(value
) or inspect
.getmodule(value
) is object):
643 if visiblename(key
, all
):
644 funcs
.append((key
, value
))
645 fdict
[key
] = '#-' + key
646 if inspect
.isfunction(value
): fdict
[value
] = fdict
[key
]
648 for key
, value
in inspect
.getmembers(object, isdata
):
649 if visiblename(key
, all
):
650 data
.append((key
, value
))
652 doc
= self
.markup(getdoc(object), self
.preformat
, fdict
, cdict
)
653 doc
= doc
and '<tt>%s</tt>' % doc
654 result
= result
+ '<p>%s</p>\n' % doc
656 if hasattr(object, '__path__'):
658 for importer
, modname
, ispkg
in pkgutil
.iter_modules(object.__path
__):
659 modpkgs
.append((modname
, name
, ispkg
, 0))
661 contents
= self
.multicolumn(modpkgs
, self
.modpkglink
)
662 result
= result
+ self
.bigsection(
663 'Package Contents', '#ffffff', '#aa55cc', contents
)
665 contents
= self
.multicolumn(
666 modules
, lambda (key
, value
), s
=self
: s
.modulelink(value
))
667 result
= result
+ self
.bigsection(
668 'Modules', '#fffff', '#aa55cc', contents
)
671 classlist
= map(lambda (key
, value
): value
, classes
)
673 self
.formattree(inspect
.getclasstree(classlist
, 1), name
)]
674 for key
, value
in classes
:
675 contents
.append(self
.document(value
, key
, name
, fdict
, cdict
))
676 result
= result
+ self
.bigsection(
677 'Classes', '#ffffff', '#ee77aa', join(contents
))
680 for key
, value
in funcs
:
681 contents
.append(self
.document(value
, key
, name
, fdict
, cdict
))
682 result
= result
+ self
.bigsection(
683 'Functions', '#ffffff', '#eeaa77', join(contents
))
686 for key
, value
in data
:
687 contents
.append(self
.document(value
, key
))
688 result
= result
+ self
.bigsection(
689 'Data', '#ffffff', '#55aa55', join(contents
, '<br>\n'))
690 if hasattr(object, '__author__'):
691 contents
= self
.markup(str(object.__author
__), self
.preformat
)
692 result
= result
+ self
.bigsection(
693 'Author', '#ffffff', '#7799ee', contents
)
694 if hasattr(object, '__credits__'):
695 contents
= self
.markup(str(object.__credits
__), self
.preformat
)
696 result
= result
+ self
.bigsection(
697 'Credits', '#ffffff', '#7799ee', contents
)
701 def docclass(self
, object, name
=None, mod
=None, funcs
={}, classes
={},
703 """Produce HTML documentation for a class object."""
704 realname
= object.__name
__
705 name
= name
or realname
706 bases
= object.__bases
__
709 push
= contents
.append
711 # Cute little class to pump out a horizontal rule between sections.
712 class HorizontalRule
:
719 hr
= HorizontalRule()
721 # List the mro, if non-trivial.
722 mro
= deque(inspect
.getmro(object))
725 push('<dl><dt>Method resolution order:</dt>\n')
727 push('<dd>%s</dd>\n' % self
.classlink(base
,
731 def spill(msg
, attrs
, predicate
):
732 ok
, attrs
= _split_list(attrs
, predicate
)
736 for name
, kind
, homecls
, value
in ok
:
737 push(self
.document(getattr(object, name
), name
, mod
,
738 funcs
, classes
, mdict
, object))
742 def spilldescriptors(msg
, attrs
, predicate
):
743 ok
, attrs
= _split_list(attrs
, predicate
)
747 for name
, kind
, homecls
, value
in ok
:
748 push(self
._docdescriptor
(name
, value
, mod
))
751 def spilldata(msg
, attrs
, predicate
):
752 ok
, attrs
= _split_list(attrs
, predicate
)
756 for name
, kind
, homecls
, value
in ok
:
757 base
= self
.docother(getattr(object, name
), name
, mod
)
758 if callable(value
) or inspect
.isdatadescriptor(value
):
759 doc
= getattr(value
, "__doc__", None)
763 push('<dl><dt>%s</dl>\n' % base
)
765 doc
= self
.markup(getdoc(value
), self
.preformat
,
766 funcs
, classes
, mdict
)
767 doc
= '<dd><tt>%s</tt>' % doc
768 push('<dl><dt>%s%s</dl>\n' % (base
, doc
))
772 attrs
= filter(lambda (name
, kind
, cls
, value
): visiblename(name
),
773 classify_class_attrs(object))
775 for key
, kind
, homecls
, value
in attrs
:
776 mdict
[key
] = anchor
= '#' + name
+ '-' + key
777 value
= getattr(object, key
)
779 # The value may not be hashable (e.g., a data attr with
780 # a dict or list value).
781 mdict
[value
] = anchor
787 thisclass
= mro
.popleft()
789 thisclass
= attrs
[0][2]
790 attrs
, inherited
= _split_list(attrs
, lambda t
: t
[2] is thisclass
)
792 if thisclass
is __builtin__
.object:
795 elif thisclass
is object:
798 tag
= 'inherited from %s' % self
.classlink(thisclass
,
802 # Sort attrs by name.
804 attrs
.sort(key
=lambda t
: t
[0])
806 attrs
.sort(lambda t1
, t2
: cmp(t1
[0], t2
[0])) # 2.3 compat
808 # Pump out the attrs, segregated by kind.
809 attrs
= spill('Methods %s' % tag
, attrs
,
810 lambda t
: t
[1] == 'method')
811 attrs
= spill('Class methods %s' % tag
, attrs
,
812 lambda t
: t
[1] == 'class method')
813 attrs
= spill('Static methods %s' % tag
, attrs
,
814 lambda t
: t
[1] == 'static method')
815 attrs
= spilldescriptors('Data descriptors %s' % tag
, attrs
,
816 lambda t
: t
[1] == 'data descriptor')
817 attrs
= spilldata('Data and other attributes %s' % tag
, attrs
,
818 lambda t
: t
[1] == 'data')
822 contents
= ''.join(contents
)
825 title
= '<a name="%s">class <strong>%s</strong></a>' % (
828 title
= '<strong>%s</strong> = <a name="%s">class %s</a>' % (
829 name
, name
, realname
)
833 parents
.append(self
.classlink(base
, object.__module
__))
834 title
= title
+ '(%s)' % join(parents
, ', ')
835 doc
= self
.markup(getdoc(object), self
.preformat
, funcs
, classes
, mdict
)
836 doc
= doc
and '<tt>%s<br> </tt>' % doc
838 return self
.section(title
, '#000000', '#ffc8d8', contents
, 3, doc
)
840 def formatvalue(self
, object):
841 """Format an argument default value as text."""
842 return self
.grey('=' + self
.repr(object))
844 def docroutine(self
, object, name
=None, mod
=None,
845 funcs
={}, classes
={}, methods
={}, cl
=None):
846 """Produce HTML documentation for a function or method object."""
847 realname
= object.__name
__
848 name
= name
or realname
849 anchor
= (cl
and cl
.__name
__ or '') + '-' + name
852 if inspect
.ismethod(object):
853 imclass
= object.im_class
855 if imclass
is not cl
:
856 note
= ' from ' + self
.classlink(imclass
, mod
)
858 if object.im_self
is not None:
859 note
= ' method of %s instance' % self
.classlink(
860 object.im_self
.__class
__, mod
)
862 note
= ' unbound %s method' % self
.classlink(imclass
,mod
)
863 object = object.im_func
866 title
= '<a name="%s"><strong>%s</strong></a>' % (anchor
, realname
)
868 if (cl
and realname
in cl
.__dict
__ and
869 cl
.__dict
__[realname
] is object):
870 reallink
= '<a href="#%s">%s</a>' % (
871 cl
.__name
__ + '-' + realname
, realname
)
875 title
= '<a name="%s"><strong>%s</strong></a> = %s' % (
876 anchor
, name
, reallink
)
877 if inspect
.isfunction(object):
878 args
, varargs
, varkw
, defaults
= inspect
.getargspec(object)
879 argspec
= inspect
.formatargspec(
880 args
, varargs
, varkw
, defaults
, formatvalue
=self
.formatvalue
)
881 if realname
== '<lambda>':
882 title
= '<strong>%s</strong> <em>lambda</em> ' % name
883 argspec
= argspec
[1:-1] # remove parentheses
887 decl
= title
+ argspec
+ (note
and self
.grey(
888 '<font face="helvetica, arial">%s</font>' % note
))
891 return '<dl><dt>%s</dt></dl>\n' % decl
894 getdoc(object), self
.preformat
, funcs
, classes
, methods
)
895 doc
= doc
and '<dd><tt>%s</tt></dd>' % doc
896 return '<dl><dt>%s</dt>%s</dl>\n' % (decl
, doc
)
898 def _docdescriptor(self
, name
, value
, mod
):
900 push
= results
.append
903 push('<dl><dt><strong>%s</strong></dt>\n' % name
)
904 if value
.__doc
__ is not None:
905 doc
= self
.markup(getdoc(value
), self
.preformat
)
906 push('<dd><tt>%s</tt></dd>\n' % doc
)
909 return ''.join(results
)
911 def docproperty(self
, object, name
=None, mod
=None, cl
=None):
912 """Produce html documentation for a property."""
913 return self
._docdescriptor
(name
, object, mod
)
915 def docother(self
, object, name
=None, mod
=None, *ignored
):
916 """Produce HTML documentation for a data object."""
917 lhs
= name
and '<strong>%s</strong> = ' % name
or ''
918 return lhs
+ self
.repr(object)
920 def docdata(self
, object, name
=None, mod
=None, cl
=None):
921 """Produce html documentation for a data descriptor."""
922 return self
._docdescriptor
(name
, object, mod
)
924 def index(self
, dir, shadowed
=None):
925 """Generate an HTML index for a directory of modules."""
927 if shadowed
is None: shadowed
= {}
928 for importer
, name
, ispkg
in pkgutil
.iter_modules([dir]):
929 modpkgs
.append((name
, '', ispkg
, name
in shadowed
))
933 contents
= self
.multicolumn(modpkgs
, self
.modpkglink
)
934 return self
.bigsection(dir, '#ffffff', '#ee77aa', contents
)
936 # -------------------------------------------- text documentation generator
938 class TextRepr(Repr
):
939 """Class for safely making a text representation of a Python object."""
942 self
.maxlist
= self
.maxtuple
= 20
944 self
.maxstring
= self
.maxother
= 100
946 def repr1(self
, x
, level
):
947 if hasattr(type(x
), '__name__'):
948 methodname
= 'repr_' + join(split(type(x
).__name
__), '_')
949 if hasattr(self
, methodname
):
950 return getattr(self
, methodname
)(x
, level
)
951 return cram(stripid(repr(x
)), self
.maxother
)
953 def repr_string(self
, x
, level
):
954 test
= cram(x
, self
.maxstring
)
955 testrepr
= repr(test
)
956 if '\\' in test
and '\\' not in replace(testrepr
, r
'\\', ''):
957 # Backslashes are only literal in the string and are never
958 # needed to make any special characters, so show a raw string.
959 return 'r' + testrepr
[0] + test
+ testrepr
[0]
962 repr_str
= repr_string
964 def repr_instance(self
, x
, level
):
966 return cram(stripid(repr(x
)), self
.maxstring
)
968 return '<%s instance>' % x
.__class
__.__name
__
971 """Formatter class for text documentation."""
973 # ------------------------------------------- text formatting utilities
975 _repr_instance
= TextRepr()
976 repr = _repr_instance
.repr
978 def bold(self
, text
):
979 """Format a string in bold by overstriking."""
980 return join(map(lambda ch
: ch
+ '\b' + ch
, text
), '')
982 def indent(self
, text
, prefix
=' '):
983 """Indent text by prepending a given prefix to each line."""
984 if not text
: return ''
985 lines
= split(text
, '\n')
986 lines
= map(lambda line
, prefix
=prefix
: prefix
+ line
, lines
)
987 if lines
: lines
[-1] = rstrip(lines
[-1])
988 return join(lines
, '\n')
990 def section(self
, title
, contents
):
991 """Format a section with a given heading."""
992 return self
.bold(title
) + '\n' + rstrip(self
.indent(contents
)) + '\n\n'
994 # ---------------------------------------------- type-specific routines
996 def formattree(self
, tree
, modname
, parent
=None, prefix
=''):
997 """Render in text a class tree as returned by inspect.getclasstree()."""
1000 if type(entry
) is type(()):
1002 result
= result
+ prefix
+ classname(c
, modname
)
1003 if bases
and bases
!= (parent
,):
1004 parents
= map(lambda c
, m
=modname
: classname(c
, m
), bases
)
1005 result
= result
+ '(%s)' % join(parents
, ', ')
1006 result
= result
+ '\n'
1007 elif type(entry
) is type([]):
1008 result
= result
+ self
.formattree(
1009 entry
, modname
, c
, prefix
+ ' ')
1012 def docmodule(self
, object, name
=None, mod
=None):
1013 """Produce text documentation for a given module object."""
1014 name
= object.__name
__ # ignore the passed-in name
1015 synop
, desc
= splitdoc(getdoc(object))
1016 result
= self
.section('NAME', name
+ (synop
and ' - ' + synop
))
1019 all
= object.__all
__
1020 except AttributeError:
1024 file = inspect
.getabsfile(object)
1027 result
= result
+ self
.section('FILE', file)
1029 docloc
= self
.getdocloc(object)
1030 if docloc
is not None:
1031 result
= result
+ self
.section('MODULE DOCS', docloc
)
1034 result
= result
+ self
.section('DESCRIPTION', desc
)
1037 for key
, value
in inspect
.getmembers(object, inspect
.isclass
):
1038 # if __all__ exists, believe it. Otherwise use old heuristic.
1040 or (inspect
.getmodule(value
) or object) is object):
1041 if visiblename(key
, all
):
1042 classes
.append((key
, value
))
1044 for key
, value
in inspect
.getmembers(object, inspect
.isroutine
):
1045 # if __all__ exists, believe it. Otherwise use old heuristic.
1046 if (all
is not None or
1047 inspect
.isbuiltin(value
) or inspect
.getmodule(value
) is object):
1048 if visiblename(key
, all
):
1049 funcs
.append((key
, value
))
1051 for key
, value
in inspect
.getmembers(object, isdata
):
1052 if visiblename(key
, all
):
1053 data
.append((key
, value
))
1055 if hasattr(object, '__path__'):
1057 for importer
, modname
, ispkg
in pkgutil
.iter_modules(object.__path
__):
1059 modpkgs
.append(modname
+ ' (package)')
1061 modpkgs
.append(modname
)
1064 result
= result
+ self
.section(
1065 'PACKAGE CONTENTS', join(modpkgs
, '\n'))
1068 classlist
= map(lambda (key
, value
): value
, classes
)
1069 contents
= [self
.formattree(
1070 inspect
.getclasstree(classlist
, 1), name
)]
1071 for key
, value
in classes
:
1072 contents
.append(self
.document(value
, key
, name
))
1073 result
= result
+ self
.section('CLASSES', join(contents
, '\n'))
1077 for key
, value
in funcs
:
1078 contents
.append(self
.document(value
, key
, name
))
1079 result
= result
+ self
.section('FUNCTIONS', join(contents
, '\n'))
1083 for key
, value
in data
:
1084 contents
.append(self
.docother(value
, key
, name
, maxlen
=70))
1085 result
= result
+ self
.section('DATA', join(contents
, '\n'))
1087 if hasattr(object, '__version__'):
1088 version
= str(object.__version
__)
1089 if version
[:11] == '$' + 'Revision: ' and version
[-1:] == '$':
1090 version
= strip(version
[11:-1])
1091 result
= result
+ self
.section('VERSION', version
)
1092 if hasattr(object, '__date__'):
1093 result
= result
+ self
.section('DATE', str(object.__date
__))
1094 if hasattr(object, '__author__'):
1095 result
= result
+ self
.section('AUTHOR', str(object.__author
__))
1096 if hasattr(object, '__credits__'):
1097 result
= result
+ self
.section('CREDITS', str(object.__credits
__))
1100 def docclass(self
, object, name
=None, mod
=None):
1101 """Produce text documentation for a given class object."""
1102 realname
= object.__name
__
1103 name
= name
or realname
1104 bases
= object.__bases
__
1106 def makename(c
, m
=object.__module
__):
1107 return classname(c
, m
)
1109 if name
== realname
:
1110 title
= 'class ' + self
.bold(realname
)
1112 title
= self
.bold(name
) + ' = class ' + realname
1114 parents
= map(makename
, bases
)
1115 title
= title
+ '(%s)' % join(parents
, ', ')
1117 doc
= getdoc(object)
1118 contents
= doc
and [doc
+ '\n'] or []
1119 push
= contents
.append
1121 # List the mro, if non-trivial.
1122 mro
= deque(inspect
.getmro(object))
1124 push("Method resolution order:")
1126 push(' ' + makename(base
))
1129 # Cute little class to pump out a horizontal rule between sections.
1130 class HorizontalRule
:
1137 hr
= HorizontalRule()
1139 def spill(msg
, attrs
, predicate
):
1140 ok
, attrs
= _split_list(attrs
, predicate
)
1144 for name
, kind
, homecls
, value
in ok
:
1145 push(self
.document(getattr(object, name
),
1149 def spilldescriptors(msg
, attrs
, predicate
):
1150 ok
, attrs
= _split_list(attrs
, predicate
)
1154 for name
, kind
, homecls
, value
in ok
:
1155 push(self
._docdescriptor
(name
, value
, mod
))
1158 def spilldata(msg
, attrs
, predicate
):
1159 ok
, attrs
= _split_list(attrs
, predicate
)
1163 for name
, kind
, homecls
, value
in ok
:
1164 if callable(value
) or inspect
.isdatadescriptor(value
):
1168 push(self
.docother(getattr(object, name
),
1169 name
, mod
, maxlen
=70, doc
=doc
) + '\n')
1172 attrs
= filter(lambda (name
, kind
, cls
, value
): visiblename(name
),
1173 classify_class_attrs(object))
1176 thisclass
= mro
.popleft()
1178 thisclass
= attrs
[0][2]
1179 attrs
, inherited
= _split_list(attrs
, lambda t
: t
[2] is thisclass
)
1181 if thisclass
is __builtin__
.object:
1184 elif thisclass
is object:
1185 tag
= "defined here"
1187 tag
= "inherited from %s" % classname(thisclass
,
1189 filter(lambda t
: not t
[0].startswith('_'), attrs
)
1191 # Sort attrs by name.
1194 # Pump out the attrs, segregated by kind.
1195 attrs
= spill("Methods %s:\n" % tag
, attrs
,
1196 lambda t
: t
[1] == 'method')
1197 attrs
= spill("Class methods %s:\n" % tag
, attrs
,
1198 lambda t
: t
[1] == 'class method')
1199 attrs
= spill("Static methods %s:\n" % tag
, attrs
,
1200 lambda t
: t
[1] == 'static method')
1201 attrs
= spilldescriptors("Data descriptors %s:\n" % tag
, attrs
,
1202 lambda t
: t
[1] == 'data descriptor')
1203 attrs
= spilldata("Data and other attributes %s:\n" % tag
, attrs
,
1204 lambda t
: t
[1] == 'data')
1208 contents
= '\n'.join(contents
)
1211 return title
+ '\n' + self
.indent(rstrip(contents
), ' | ') + '\n'
1213 def formatvalue(self
, object):
1214 """Format an argument default value as text."""
1215 return '=' + self
.repr(object)
1217 def docroutine(self
, object, name
=None, mod
=None, cl
=None):
1218 """Produce text documentation for a function or method object."""
1219 realname
= object.__name
__
1220 name
= name
or realname
1223 if inspect
.ismethod(object):
1224 imclass
= object.im_class
1226 if imclass
is not cl
:
1227 note
= ' from ' + classname(imclass
, mod
)
1229 if object.im_self
is not None:
1230 note
= ' method of %s instance' % classname(
1231 object.im_self
.__class
__, mod
)
1233 note
= ' unbound %s method' % classname(imclass
,mod
)
1234 object = object.im_func
1236 if name
== realname
:
1237 title
= self
.bold(realname
)
1239 if (cl
and realname
in cl
.__dict
__ and
1240 cl
.__dict
__[realname
] is object):
1242 title
= self
.bold(name
) + ' = ' + realname
1243 if inspect
.isfunction(object):
1244 args
, varargs
, varkw
, defaults
= inspect
.getargspec(object)
1245 argspec
= inspect
.formatargspec(
1246 args
, varargs
, varkw
, defaults
, formatvalue
=self
.formatvalue
)
1247 if realname
== '<lambda>':
1248 title
= self
.bold(name
) + ' lambda '
1249 argspec
= argspec
[1:-1] # remove parentheses
1252 decl
= title
+ argspec
+ note
1257 doc
= getdoc(object) or ''
1258 return decl
+ '\n' + (doc
and rstrip(self
.indent(doc
)) + '\n')
1260 def _docdescriptor(self
, name
, value
, mod
):
1262 push
= results
.append
1265 push(self
.bold(name
))
1267 doc
= getdoc(value
) or ''
1269 push(self
.indent(doc
))
1271 return ''.join(results
)
1273 def docproperty(self
, object, name
=None, mod
=None, cl
=None):
1274 """Produce text documentation for a property."""
1275 return self
._docdescriptor
(name
, object, mod
)
1277 def docdata(self
, object, name
=None, mod
=None, cl
=None):
1278 """Produce text documentation for a data descriptor."""
1279 return self
._docdescriptor
(name
, object, mod
)
1281 def docother(self
, object, name
=None, mod
=None, parent
=None, maxlen
=None, doc
=None):
1282 """Produce text documentation for a data object."""
1283 repr = self
.repr(object)
1285 line
= (name
and name
+ ' = ' or '') + repr
1286 chop
= maxlen
- len(line
)
1287 if chop
< 0: repr = repr[:chop
] + '...'
1288 line
= (name
and self
.bold(name
) + ' = ' or '') + repr
1290 line
+= '\n' + self
.indent(str(doc
))
1293 # --------------------------------------------------------- user interfaces
1296 """The first time this is called, determine what kind of pager to use."""
1302 """Decide what method to use for paging through text."""
1303 if type(sys
.stdout
) is not types
.FileType
:
1305 if not sys
.stdin
.isatty() or not sys
.stdout
.isatty():
1307 if 'PAGER' in os
.environ
:
1308 if sys
.platform
== 'win32': # pipes completely broken in Windows
1309 return lambda text
: tempfilepager(plain(text
), os
.environ
['PAGER'])
1310 elif os
.environ
.get('TERM') in ('dumb', 'emacs'):
1311 return lambda text
: pipepager(plain(text
), os
.environ
['PAGER'])
1313 return lambda text
: pipepager(text
, os
.environ
['PAGER'])
1314 if os
.environ
.get('TERM') in ('dumb', 'emacs'):
1316 if sys
.platform
== 'win32' or sys
.platform
.startswith('os2'):
1317 return lambda text
: tempfilepager(plain(text
), 'more <')
1318 if hasattr(os
, 'system') and os
.system('(less) 2>/dev/null') == 0:
1319 return lambda text
: pipepager(text
, 'less')
1322 (fd
, filename
) = tempfile
.mkstemp()
1325 if hasattr(os
, 'system') and os
.system('more %s' % filename
) == 0:
1326 return lambda text
: pipepager(text
, 'more')
1333 """Remove boldface formatting from text."""
1334 return re
.sub('.\b', '', text
)
1336 def pipepager(text
, cmd
):
1337 """Page through text by feeding it to another program."""
1338 pipe
= os
.popen(cmd
, 'w')
1343 pass # Ignore broken pipes caused by quitting the pager program.
1345 def tempfilepager(text
, cmd
):
1346 """Page through text by invoking a program on a temporary file."""
1348 filename
= tempfile
.mktemp()
1349 file = open(filename
, 'w')
1353 os
.system(cmd
+ ' ' + filename
)
1358 """Page through text on a text terminal."""
1359 lines
= split(plain(text
), '\n')
1362 fd
= sys
.stdin
.fileno()
1363 old
= tty
.tcgetattr(fd
)
1365 getchar
= lambda: sys
.stdin
.read(1)
1366 except (ImportError, AttributeError):
1368 getchar
= lambda: sys
.stdin
.readline()[:-1][:1]
1371 r
= inc
= os
.environ
.get('LINES', 25) - 1
1372 sys
.stdout
.write(join(lines
[:inc
], '\n') + '\n')
1374 sys
.stdout
.write('-- more --')
1379 sys
.stdout
.write('\r \r')
1381 elif c
in ('\r', '\n'):
1382 sys
.stdout
.write('\r \r' + lines
[r
] + '\n')
1385 if c
in ('b', 'B', '\x1b'):
1388 sys
.stdout
.write('\n' + join(lines
[r
:r
+inc
], '\n') + '\n')
1393 tty
.tcsetattr(fd
, tty
.TCSAFLUSH
, old
)
1395 def plainpager(text
):
1396 """Simply print unformatted text. This is the ultimate fallback."""
1397 sys
.stdout
.write(plain(text
))
1399 def describe(thing
):
1400 """Produce a short description of the given thing."""
1401 if inspect
.ismodule(thing
):
1402 if thing
.__name
__ in sys
.builtin_module_names
:
1403 return 'built-in module ' + thing
.__name
__
1404 if hasattr(thing
, '__path__'):
1405 return 'package ' + thing
.__name
__
1407 return 'module ' + thing
.__name
__
1408 if inspect
.isbuiltin(thing
):
1409 return 'built-in function ' + thing
.__name
__
1410 if inspect
.isgetsetdescriptor(thing
):
1411 return 'getset descriptor %s.%s.%s' % (
1412 thing
.__objclass
__.__module
__, thing
.__objclass
__.__name
__,
1414 if inspect
.ismemberdescriptor(thing
):
1415 return 'member descriptor %s.%s.%s' % (
1416 thing
.__objclass
__.__module
__, thing
.__objclass
__.__name
__,
1418 if inspect
.isclass(thing
):
1419 return 'class ' + thing
.__name
__
1420 if inspect
.isfunction(thing
):
1421 return 'function ' + thing
.__name
__
1422 if inspect
.ismethod(thing
):
1423 return 'method ' + thing
.__name
__
1424 if type(thing
) is types
.InstanceType
:
1425 return 'instance of ' + thing
.__class
__.__name
__
1426 return type(thing
).__name
__
1428 def locate(path
, forceload
=0):
1429 """Locate an object by name or dotted path, importing as necessary."""
1430 parts
= [part
for part
in split(path
, '.') if part
]
1432 while n
< len(parts
):
1433 nextmodule
= safeimport(join(parts
[:n
+1], '.'), forceload
)
1434 if nextmodule
: module
, n
= nextmodule
, n
+ 1
1438 for part
in parts
[n
:]:
1439 try: object = getattr(object, part
)
1440 except AttributeError: return None
1443 if hasattr(__builtin__
, path
):
1444 return getattr(__builtin__
, path
)
1446 # --------------------------------------- interactive interpreter interface
1451 class _OldStyleClass
: pass
1452 _OLD_INSTANCE_TYPE
= type(_OldStyleClass())
1454 def resolve(thing
, forceload
=0):
1455 """Given an object or a path to an object, get the object and its name."""
1456 if isinstance(thing
, str):
1457 object = locate(thing
, forceload
)
1459 raise ImportError, 'no Python documentation found for %r' % thing
1460 return object, thing
1462 return thing
, getattr(thing
, '__name__', None)
1464 def render_doc(thing
, title
='Python Library Documentation: %s', forceload
=0):
1465 """Render text documentation, given an object or a path to an object."""
1466 object, name
= resolve(thing
, forceload
)
1467 desc
= describe(object)
1468 module
= inspect
.getmodule(object)
1469 if name
and '.' in name
:
1470 desc
+= ' in ' + name
[:name
.rfind('.')]
1471 elif module
and module
is not object:
1472 desc
+= ' in module ' + module
.__name
__
1473 if type(object) is _OLD_INSTANCE_TYPE
:
1474 # If the passed object is an instance of an old-style class,
1475 # document its available methods instead of its value.
1476 object = object.__class
__
1477 elif not (inspect
.ismodule(object) or
1478 inspect
.isclass(object) or
1479 inspect
.isroutine(object) or
1480 inspect
.isgetsetdescriptor(object) or
1481 inspect
.ismemberdescriptor(object) or
1482 isinstance(object, property)):
1483 # If the passed object is a piece of data or an instance,
1484 # document its available methods instead of its value.
1485 object = type(object)
1487 return title
% desc
+ '\n\n' + text
.document(object, name
)
1489 def doc(thing
, title
='Python Library Documentation: %s', forceload
=0):
1490 """Display text documentation, given an object or a path to an object."""
1492 pager(render_doc(thing
, title
, forceload
))
1493 except (ImportError, ErrorDuringImport
), value
:
1496 def writedoc(thing
, forceload
=0):
1497 """Write HTML documentation to a file in the current directory."""
1499 object, name
= resolve(thing
, forceload
)
1500 page
= html
.page(describe(object), html
.document(object, name
))
1501 file = open(name
+ '.html', 'w')
1504 print 'wrote', name
+ '.html'
1505 except (ImportError, ErrorDuringImport
), value
:
1508 def writedocs(dir, pkgpath
='', done
=None):
1509 """Write out HTML documentation for all modules in a directory tree."""
1510 if done
is None: done
= {}
1511 for importer
, modname
, ispkg
in pkgutil
.walk_packages([dir], pkgpath
):
1519 'assert': ('ref/assert', ''),
1520 'break': ('ref/break', 'while for'),
1521 'class': ('ref/class', 'CLASSES SPECIALMETHODS'),
1522 'continue': ('ref/continue', 'while for'),
1523 'def': ('ref/function', ''),
1524 'del': ('ref/del', 'BASICMETHODS'),
1526 'else': ('ref/if', 'while for'),
1528 'exec': ('ref/exec', ''),
1530 'for': ('ref/for', 'break continue while'),
1532 'global': ('ref/global', 'NAMESPACES'),
1533 'if': ('ref/if', 'TRUTHVALUE'),
1534 'import': ('ref/import', 'MODULES'),
1535 'in': ('ref/comparisons', 'SEQUENCEMETHODS2'),
1537 'lambda': ('ref/lambdas', 'FUNCTIONS'),
1540 'pass': ('ref/pass', ''),
1541 'print': ('ref/print', ''),
1542 'raise': ('ref/raise', 'EXCEPTIONS'),
1543 'return': ('ref/return', 'FUNCTIONS'),
1544 'try': ('ref/try', 'EXCEPTIONS'),
1545 'while': ('ref/while', 'break continue if TRUTHVALUE'),
1546 'with': ('ref/with', 'CONTEXTMANAGERS EXCEPTIONS yield'),
1547 'yield': ('ref/yield', ''),
1551 'TYPES': ('ref/types', 'STRINGS UNICODE NUMBERS SEQUENCES MAPPINGS FUNCTIONS CLASSES MODULES FILES inspect'),
1552 'STRINGS': ('ref/strings', 'str UNICODE SEQUENCES STRINGMETHODS FORMATTING TYPES'),
1553 'STRINGMETHODS': ('lib/string-methods', 'STRINGS FORMATTING'),
1554 'FORMATTING': ('lib/typesseq-strings', 'OPERATORS'),
1555 'UNICODE': ('ref/strings', 'encodings unicode SEQUENCES STRINGMETHODS FORMATTING TYPES'),
1556 'NUMBERS': ('ref/numbers', 'INTEGER FLOAT COMPLEX TYPES'),
1557 'INTEGER': ('ref/integers', 'int range'),
1558 'FLOAT': ('ref/floating', 'float math'),
1559 'COMPLEX': ('ref/imaginary', 'complex cmath'),
1560 'SEQUENCES': ('lib/typesseq', 'STRINGMETHODS FORMATTING xrange LISTS'),
1561 'MAPPINGS': 'DICTIONARIES',
1562 'FUNCTIONS': ('lib/typesfunctions', 'def TYPES'),
1563 'METHODS': ('lib/typesmethods', 'class def CLASSES TYPES'),
1564 'CODEOBJECTS': ('lib/bltin-code-objects', 'compile FUNCTIONS TYPES'),
1565 'TYPEOBJECTS': ('lib/bltin-type-objects', 'types TYPES'),
1566 'FRAMEOBJECTS': 'TYPES',
1567 'TRACEBACKS': 'TYPES',
1568 'NONE': ('lib/bltin-null-object', ''),
1569 'ELLIPSIS': ('lib/bltin-ellipsis-object', 'SLICINGS'),
1570 'FILES': ('lib/bltin-file-objects', ''),
1571 'SPECIALATTRIBUTES': ('lib/specialattrs', ''),
1572 'CLASSES': ('ref/types', 'class SPECIALMETHODS PRIVATENAMES'),
1573 'MODULES': ('lib/typesmodules', 'import'),
1574 'PACKAGES': 'import',
1575 'EXPRESSIONS': ('ref/summary', 'lambda or and not in is BOOLEAN COMPARISON BITWISE SHIFTING BINARY FORMATTING POWER UNARY ATTRIBUTES SUBSCRIPTS SLICINGS CALLS TUPLES LISTS DICTIONARIES BACKQUOTES'),
1576 'OPERATORS': 'EXPRESSIONS',
1577 'PRECEDENCE': 'EXPRESSIONS',
1578 'OBJECTS': ('ref/objects', 'TYPES'),
1579 'SPECIALMETHODS': ('ref/specialnames', 'BASICMETHODS ATTRIBUTEMETHODS CALLABLEMETHODS SEQUENCEMETHODS1 MAPPINGMETHODS SEQUENCEMETHODS2 NUMBERMETHODS CLASSES'),
1580 'BASICMETHODS': ('ref/customization', 'cmp hash repr str SPECIALMETHODS'),
1581 'ATTRIBUTEMETHODS': ('ref/attribute-access', 'ATTRIBUTES SPECIALMETHODS'),
1582 'CALLABLEMETHODS': ('ref/callable-types', 'CALLS SPECIALMETHODS'),
1583 'SEQUENCEMETHODS1': ('ref/sequence-types', 'SEQUENCES SEQUENCEMETHODS2 SPECIALMETHODS'),
1584 'SEQUENCEMETHODS2': ('ref/sequence-methods', 'SEQUENCES SEQUENCEMETHODS1 SPECIALMETHODS'),
1585 'MAPPINGMETHODS': ('ref/sequence-types', 'MAPPINGS SPECIALMETHODS'),
1586 'NUMBERMETHODS': ('ref/numeric-types', 'NUMBERS AUGMENTEDASSIGNMENT SPECIALMETHODS'),
1587 'EXECUTION': ('ref/execmodel', 'NAMESPACES DYNAMICFEATURES EXCEPTIONS'),
1588 'NAMESPACES': ('ref/naming', 'global ASSIGNMENT DELETION DYNAMICFEATURES'),
1589 'DYNAMICFEATURES': ('ref/dynamic-features', ''),
1590 'SCOPING': 'NAMESPACES',
1591 'FRAMES': 'NAMESPACES',
1592 'EXCEPTIONS': ('ref/exceptions', 'try except finally raise'),
1593 'COERCIONS': ('ref/coercion-rules','CONVERSIONS'),
1594 'CONVERSIONS': ('ref/conversions', 'COERCIONS'),
1595 'IDENTIFIERS': ('ref/identifiers', 'keywords SPECIALIDENTIFIERS'),
1596 'SPECIALIDENTIFIERS': ('ref/id-classes', ''),
1597 'PRIVATENAMES': ('ref/atom-identifiers', ''),
1598 'LITERALS': ('ref/atom-literals', 'STRINGS BACKQUOTES NUMBERS TUPLELITERALS LISTLITERALS DICTIONARYLITERALS'),
1599 'TUPLES': 'SEQUENCES',
1600 'TUPLELITERALS': ('ref/exprlists', 'TUPLES LITERALS'),
1601 'LISTS': ('lib/typesseq-mutable', 'LISTLITERALS'),
1602 'LISTLITERALS': ('ref/lists', 'LISTS LITERALS'),
1603 'DICTIONARIES': ('lib/typesmapping', 'DICTIONARYLITERALS'),
1604 'DICTIONARYLITERALS': ('ref/dict', 'DICTIONARIES LITERALS'),
1605 'BACKQUOTES': ('ref/string-conversions', 'repr str STRINGS LITERALS'),
1606 'ATTRIBUTES': ('ref/attribute-references', 'getattr hasattr setattr ATTRIBUTEMETHODS'),
1607 'SUBSCRIPTS': ('ref/subscriptions', 'SEQUENCEMETHODS1'),
1608 'SLICINGS': ('ref/slicings', 'SEQUENCEMETHODS2'),
1609 'CALLS': ('ref/calls', 'EXPRESSIONS'),
1610 'POWER': ('ref/power', 'EXPRESSIONS'),
1611 'UNARY': ('ref/unary', 'EXPRESSIONS'),
1612 'BINARY': ('ref/binary', 'EXPRESSIONS'),
1613 'SHIFTING': ('ref/shifting', 'EXPRESSIONS'),
1614 'BITWISE': ('ref/bitwise', 'EXPRESSIONS'),
1615 'COMPARISON': ('ref/comparisons', 'EXPRESSIONS BASICMETHODS'),
1616 'BOOLEAN': ('ref/Booleans', 'EXPRESSIONS TRUTHVALUE'),
1617 'ASSERTION': 'assert',
1618 'ASSIGNMENT': ('ref/assignment', 'AUGMENTEDASSIGNMENT'),
1619 'AUGMENTEDASSIGNMENT': ('ref/augassign', 'NUMBERMETHODS'),
1621 'PRINTING': 'print',
1622 'RETURNING': 'return',
1623 'IMPORTING': 'import',
1624 'CONDITIONAL': 'if',
1625 'LOOPING': ('ref/compound', 'for while break continue'),
1626 'TRUTHVALUE': ('lib/truth', 'if while and or not BASICMETHODS'),
1627 'DEBUGGING': ('lib/module-pdb', 'pdb'),
1628 'CONTEXTMANAGERS': ('ref/context-managers', 'with'),
1631 def __init__(self
, input, output
):
1633 self
.output
= output
1635 execdir
= os
.path
.dirname(sys
.executable
)
1636 homedir
= os
.environ
.get('PYTHONHOME')
1638 for dir in [os
.environ
.get('PYTHONDOCS'),
1639 homedir
and os
.path
.join(homedir
, 'doc'),
1640 join(execdir
, 'doc'), # for Windows
1641 join(sys
.prefix
, 'doc/python-docs-' + split(sys
.version
)[0]),
1642 join(sys
.prefix
, 'doc/python-' + split(sys
.version
)[0]),
1643 join(sys
.prefix
, 'doc/python-docs-' + sys
.version
[:3]),
1644 join(sys
.prefix
, 'doc/python-' + sys
.version
[:3]),
1645 join(sys
.prefix
, 'Resources/English.lproj/Documentation')]:
1646 if dir and os
.path
.isdir(join(dir, 'lib')):
1649 if dir and os
.path
.isdir(join(dir, 'html', 'lib')):
1650 self
.docdir
= join(dir, 'html')
1654 if inspect
.stack()[1][3] == '?':
1657 return '<pydoc.Helper instance>'
1659 def __call__(self
, request
=None):
1660 if request
is not None:
1665 self
.output
.write('''
1666 You are now leaving help and returning to the Python interpreter.
1667 If you want to ask for help on a particular object directly from the
1668 interpreter, you can type "help(object)". Executing "help('string')"
1669 has the same effect as typing a particular string at the help> prompt.
1673 self
.output
.write('\n')
1676 request
= self
.getline('help> ')
1677 if not request
: break
1678 except (KeyboardInterrupt, EOFError):
1680 request
= strip(replace(request
, '"', '', "'", ''))
1681 if lower(request
) in ('q', 'quit'): break
1684 def getline(self
, prompt
):
1685 """Read one line, using raw_input when available."""
1686 if self
.input is sys
.stdin
:
1687 return raw_input(prompt
)
1689 self
.output
.write(prompt
)
1691 return self
.input.readline()
1693 def help(self
, request
):
1694 if type(request
) is type(''):
1695 if request
== 'help': self
.intro()
1696 elif request
== 'keywords': self
.listkeywords()
1697 elif request
== 'topics': self
.listtopics()
1698 elif request
== 'modules': self
.listmodules()
1699 elif request
[:8] == 'modules ':
1700 self
.listmodules(split(request
)[1])
1701 elif request
in self
.keywords
: self
.showtopic(request
)
1702 elif request
in self
.topics
: self
.showtopic(request
)
1703 elif request
: doc(request
, 'Help on %s:')
1704 elif isinstance(request
, Helper
): self()
1705 else: doc(request
, 'Help on %s:')
1706 self
.output
.write('\n')
1709 self
.output
.write('''
1710 Welcome to Python %s! This is the online help utility.
1712 If this is your first time using Python, you should definitely check out
1713 the tutorial on the Internet at http://www.python.org/doc/tut/.
1715 Enter the name of any module, keyword, or topic to get help on writing
1716 Python programs and using Python modules. To quit this help utility and
1717 return to the interpreter, just type "quit".
1719 To get a list of available modules, keywords, or topics, type "modules",
1720 "keywords", or "topics". Each module also comes with a one-line summary
1721 of what it does; to list the modules whose summaries contain a given word
1722 such as "spam", type "modules spam".
1723 ''' % sys
.version
[:3])
1725 def list(self
, items
, columns
=4, width
=80):
1728 colw
= width
/ columns
1729 rows
= (len(items
) + columns
- 1) / columns
1730 for row
in range(rows
):
1731 for col
in range(columns
):
1732 i
= col
* rows
+ row
1734 self
.output
.write(items
[i
])
1735 if col
< columns
- 1:
1736 self
.output
.write(' ' + ' ' * (colw
-1 - len(items
[i
])))
1737 self
.output
.write('\n')
1739 def listkeywords(self
):
1740 self
.output
.write('''
1741 Here is a list of the Python keywords. Enter any keyword to get more help.
1744 self
.list(self
.keywords
.keys())
1746 def listtopics(self
):
1747 self
.output
.write('''
1748 Here is a list of available topics. Enter any topic name to get more help.
1751 self
.list(self
.topics
.keys())
1753 def showtopic(self
, topic
):
1755 self
.output
.write('''
1756 Sorry, topic and keyword documentation is not available because the Python
1757 HTML documentation files could not be found. If you have installed them,
1758 please set the environment variable PYTHONDOCS to indicate their location.
1760 On the Microsoft Windows operating system, the files can be built by
1761 running "hh -decompile . PythonNN.chm" in the C:\PythonNN\Doc> directory.
1764 target
= self
.topics
.get(topic
, self
.keywords
.get(topic
))
1766 self
.output
.write('no documentation found for %s\n' % repr(topic
))
1768 if type(target
) is type(''):
1769 return self
.showtopic(target
)
1771 filename
, xrefs
= target
1772 filename
= self
.docdir
+ '/' + filename
+ '.html'
1774 file = open(filename
)
1776 self
.output
.write('could not read docs from %s\n' % filename
)
1779 divpat
= re
.compile('<div[^>]*navigat.*?</div.*?>', re
.I | re
.S
)
1780 addrpat
= re
.compile('<address.*?>.*?</address.*?>', re
.I | re
.S
)
1781 document
= re
.sub(addrpat
, '', re
.sub(divpat
, '', file.read()))
1784 import htmllib
, formatter
, StringIO
1785 buffer = StringIO
.StringIO()
1786 parser
= htmllib
.HTMLParser(
1787 formatter
.AbstractFormatter(formatter
.DumbWriter(buffer)))
1788 parser
.start_table
= parser
.do_p
1789 parser
.end_table
= lambda parser
=parser
: parser
.do_p({})
1790 parser
.start_tr
= parser
.do_br
1791 parser
.start_td
= parser
.start_th
= lambda a
, b
=buffer: b
.write('\t')
1792 parser
.feed(document
)
1793 buffer = replace(buffer.getvalue(), '\xa0', ' ', '\n', '\n ')
1794 pager(' ' + strip(buffer) + '\n')
1796 buffer = StringIO
.StringIO()
1797 formatter
.DumbWriter(buffer).send_flowing_data(
1798 'Related help topics: ' + join(split(xrefs
), ', ') + '\n')
1799 self
.output
.write('\n%s\n' % buffer.getvalue())
1801 def listmodules(self
, key
=''):
1803 self
.output
.write('''
1804 Here is a list of matching modules. Enter any module name to get more help.
1809 self
.output
.write('''
1810 Please wait a moment while I gather a list of all available modules...
1814 def callback(path
, modname
, desc
, modules
=modules
):
1815 if modname
and modname
[-9:] == '.__init__':
1816 modname
= modname
[:-9] + ' (package)'
1817 if find(modname
, '.') < 0:
1818 modules
[modname
] = 1
1819 ModuleScanner().run(callback
)
1820 self
.list(modules
.keys())
1821 self
.output
.write('''
1822 Enter any module name to get more help. Or, type "modules spam" to search
1823 for modules whose descriptions contain the word "spam".
1826 help = Helper(sys
.stdin
, sys
.stdout
)
1829 """A generic tree iterator."""
1830 def __init__(self
, roots
, children
, descendp
):
1831 self
.roots
= roots
[:]
1833 self
.children
= children
1834 self
.descendp
= descendp
1840 root
= self
.roots
.pop(0)
1841 self
.state
= [(root
, self
.children(root
))]
1842 node
, children
= self
.state
[-1]
1846 child
= children
.pop(0)
1847 if self
.descendp(child
):
1848 self
.state
.append((child
, self
.children(child
)))
1852 class ModuleScanner
:
1853 """An interruptible scanner that searches module synopses."""
1855 def run(self
, callback
, key
=None, completer
=None):
1856 if key
: key
= lower(key
)
1860 for modname
in sys
.builtin_module_names
:
1861 if modname
!= '__main__':
1864 callback(None, modname
, '')
1866 desc
= split(__import__(modname
).__doc
__ or '', '\n')[0]
1867 if find(lower(modname
+ ' - ' + desc
), key
) >= 0:
1868 callback(None, modname
, desc
)
1870 for importer
, modname
, ispkg
in pkgutil
.walk_packages():
1874 callback(None, modname
, '')
1876 loader
= importer
.find_module(modname
)
1877 if hasattr(loader
,'get_source'):
1879 desc
= source_synopsis(
1880 StringIO
.StringIO(loader
.get_source(modname
))
1882 if hasattr(loader
,'get_filename'):
1883 path
= loader
.get_filename(modname
)
1887 module
= loader
.load_module(modname
)
1888 desc
= (module
.__doc
__ or '').splitlines()[0]
1889 path
= getattr(module
,'__file__',None)
1890 if find(lower(modname
+ ' - ' + desc
), key
) >= 0:
1891 callback(path
, modname
, desc
)
1897 """Print all the one-line module summaries that contain a substring."""
1898 def callback(path
, modname
, desc
):
1899 if modname
[-9:] == '.__init__':
1900 modname
= modname
[:-9] + ' (package)'
1901 print modname
, desc
and '- ' + desc
1902 try: import warnings
1903 except ImportError: pass
1904 else: warnings
.filterwarnings('ignore') # ignore problems during import
1905 ModuleScanner().run(callback
, key
)
1907 # --------------------------------------------------- web browser interface
1909 def serve(port
, callback
=None, completer
=None):
1910 import BaseHTTPServer
, mimetools
, select
1912 # Patch up mimetools.Message so it doesn't break if rfc822 is reloaded.
1913 class Message(mimetools
.Message
):
1914 def __init__(self
, fp
, seekable
=1):
1915 Message
= self
.__class
__
1916 Message
.__bases
__[0].__bases
__[0].__init
__(self
, fp
, seekable
)
1917 self
.encodingheader
= self
.getheader('content-transfer-encoding')
1918 self
.typeheader
= self
.getheader('content-type')
1922 class DocHandler(BaseHTTPServer
.BaseHTTPRequestHandler
):
1923 def send_document(self
, title
, contents
):
1925 self
.send_response(200)
1926 self
.send_header('Content-Type', 'text/html')
1928 self
.wfile
.write(html
.page(title
, contents
))
1929 except IOError: pass
1933 if path
[-5:] == '.html': path
= path
[:-5]
1934 if path
[:1] == '/': path
= path
[1:]
1935 if path
and path
!= '.':
1937 obj
= locate(path
, forceload
=1)
1938 except ErrorDuringImport
, value
:
1939 self
.send_document(path
, html
.escape(str(value
)))
1942 self
.send_document(describe(obj
), html
.document(obj
, path
))
1944 self
.send_document(path
,
1945 'no Python documentation found for %s' % repr(path
))
1947 heading
= html
.heading(
1948 '<big><big><strong>Python: Index of Modules</strong></big></big>',
1949 '#ffffff', '#7799ee')
1950 def bltinlink(name
):
1951 return '<a href="%s.html">%s</a>' % (name
, name
)
1952 names
= filter(lambda x
: x
!= '__main__',
1953 sys
.builtin_module_names
)
1954 contents
= html
.multicolumn(names
, bltinlink
)
1955 indices
= ['<p>' + html
.bigsection(
1956 'Built-in Modules', '#ffffff', '#ee77aa', contents
)]
1959 for dir in sys
.path
:
1960 indices
.append(html
.index(dir, seen
))
1961 contents
= heading
+ join(indices
) + '''<p align=right>
1962 <font color="#909090" face="helvetica, arial"><strong>
1963 pydoc</strong> by Ka-Ping Yee <ping@lfw.org></font>'''
1964 self
.send_document('Index of Modules', contents
)
1966 def log_message(self
, *args
): pass
1968 class DocServer(BaseHTTPServer
.HTTPServer
):
1969 def __init__(self
, port
, callback
):
1970 host
= (sys
.platform
== 'mac') and '127.0.0.1' or 'localhost'
1971 self
.address
= ('', port
)
1972 self
.url
= 'http://%s:%d/' % (host
, port
)
1973 self
.callback
= callback
1974 self
.base
.__init
__(self
, self
.address
, self
.handler
)
1976 def serve_until_quit(self
):
1979 while not self
.quit
:
1980 rd
, wr
, ex
= select
.select([self
.socket
.fileno()], [], [], 1)
1981 if rd
: self
.handle_request()
1983 def server_activate(self
):
1984 self
.base
.server_activate(self
)
1985 if self
.callback
: self
.callback(self
)
1987 DocServer
.base
= BaseHTTPServer
.HTTPServer
1988 DocServer
.handler
= DocHandler
1989 DocHandler
.MessageClass
= Message
1992 DocServer(port
, callback
).serve_until_quit()
1993 except (KeyboardInterrupt, select
.error
):
1996 if completer
: completer()
1998 # ----------------------------------------------------- graphical interface
2001 """Graphical interface (starts web server and pops up a control window)."""
2003 def __init__(self
, window
, port
=7464):
2004 self
.window
= window
2009 self
.server_frm
= Tkinter
.Frame(window
)
2010 self
.title_lbl
= Tkinter
.Label(self
.server_frm
,
2011 text
='Starting server...\n ')
2012 self
.open_btn
= Tkinter
.Button(self
.server_frm
,
2013 text
='open browser', command
=self
.open, state
='disabled')
2014 self
.quit_btn
= Tkinter
.Button(self
.server_frm
,
2015 text
='quit serving', command
=self
.quit
, state
='disabled')
2017 self
.search_frm
= Tkinter
.Frame(window
)
2018 self
.search_lbl
= Tkinter
.Label(self
.search_frm
, text
='Search for')
2019 self
.search_ent
= Tkinter
.Entry(self
.search_frm
)
2020 self
.search_ent
.bind('<Return>', self
.search
)
2021 self
.stop_btn
= Tkinter
.Button(self
.search_frm
,
2022 text
='stop', pady
=0, command
=self
.stop
, state
='disabled')
2023 if sys
.platform
== 'win32':
2024 # Trying to hide and show this button crashes under Windows.
2025 self
.stop_btn
.pack(side
='right')
2027 self
.window
.title('pydoc')
2028 self
.window
.protocol('WM_DELETE_WINDOW', self
.quit
)
2029 self
.title_lbl
.pack(side
='top', fill
='x')
2030 self
.open_btn
.pack(side
='left', fill
='x', expand
=1)
2031 self
.quit_btn
.pack(side
='right', fill
='x', expand
=1)
2032 self
.server_frm
.pack(side
='top', fill
='x')
2034 self
.search_lbl
.pack(side
='left')
2035 self
.search_ent
.pack(side
='right', fill
='x', expand
=1)
2036 self
.search_frm
.pack(side
='top', fill
='x')
2037 self
.search_ent
.focus_set()
2039 font
= ('helvetica', sys
.platform
== 'win32' and 8 or 10)
2040 self
.result_lst
= Tkinter
.Listbox(window
, font
=font
, height
=6)
2041 self
.result_lst
.bind('<Button-1>', self
.select
)
2042 self
.result_lst
.bind('<Double-Button-1>', self
.goto
)
2043 self
.result_scr
= Tkinter
.Scrollbar(window
,
2044 orient
='vertical', command
=self
.result_lst
.yview
)
2045 self
.result_lst
.config(yscrollcommand
=self
.result_scr
.set)
2047 self
.result_frm
= Tkinter
.Frame(window
)
2048 self
.goto_btn
= Tkinter
.Button(self
.result_frm
,
2049 text
='go to selected', command
=self
.goto
)
2050 self
.hide_btn
= Tkinter
.Button(self
.result_frm
,
2051 text
='hide results', command
=self
.hide
)
2052 self
.goto_btn
.pack(side
='left', fill
='x', expand
=1)
2053 self
.hide_btn
.pack(side
='right', fill
='x', expand
=1)
2055 self
.window
.update()
2056 self
.minwidth
= self
.window
.winfo_width()
2057 self
.minheight
= self
.window
.winfo_height()
2058 self
.bigminheight
= (self
.server_frm
.winfo_reqheight() +
2059 self
.search_frm
.winfo_reqheight() +
2060 self
.result_lst
.winfo_reqheight() +
2061 self
.result_frm
.winfo_reqheight())
2062 self
.bigwidth
, self
.bigheight
= self
.minwidth
, self
.bigminheight
2064 self
.window
.wm_geometry('%dx%d' % (self
.minwidth
, self
.minheight
))
2065 self
.window
.wm_minsize(self
.minwidth
, self
.minheight
)
2066 self
.window
.tk
.willdispatch()
2070 target
=serve
, args
=(port
, self
.ready
, self
.quit
)).start()
2072 def ready(self
, server
):
2073 self
.server
= server
2074 self
.title_lbl
.config(
2075 text
='Python documentation server at\n' + server
.url
)
2076 self
.open_btn
.config(state
='normal')
2077 self
.quit_btn
.config(state
='normal')
2079 def open(self
, event
=None, url
=None):
2080 url
= url
or self
.server
.url
2083 webbrowser
.open(url
)
2084 except ImportError: # pre-webbrowser.py compatibility
2085 if sys
.platform
== 'win32':
2086 os
.system('start "%s"' % url
)
2087 elif sys
.platform
== 'mac':
2089 except ImportError: pass
2090 else: ic
.launchurl(url
)
2092 rc
= os
.system('netscape -remote "openURL(%s)" &' % url
)
2093 if rc
: os
.system('netscape "%s" &' % url
)
2095 def quit(self
, event
=None):
2097 self
.server
.quit
= 1
2100 def search(self
, event
=None):
2101 key
= self
.search_ent
.get()
2102 self
.stop_btn
.pack(side
='right')
2103 self
.stop_btn
.config(state
='normal')
2104 self
.search_lbl
.config(text
='Searching for "%s"...' % key
)
2105 self
.search_ent
.forget()
2106 self
.search_lbl
.pack(side
='left')
2107 self
.result_lst
.delete(0, 'end')
2108 self
.goto_btn
.config(state
='disabled')
2113 self
.scanner
.quit
= 1
2114 self
.scanner
= ModuleScanner()
2115 threading
.Thread(target
=self
.scanner
.run
,
2116 args
=(self
.update
, key
, self
.done
)).start()
2118 def update(self
, path
, modname
, desc
):
2119 if modname
[-9:] == '.__init__':
2120 modname
= modname
[:-9] + ' (package)'
2121 self
.result_lst
.insert('end',
2122 modname
+ ' - ' + (desc
or '(no description)'))
2124 def stop(self
, event
=None):
2126 self
.scanner
.quit
= 1
2131 self
.search_lbl
.config(text
='Search for')
2132 self
.search_lbl
.pack(side
='left')
2133 self
.search_ent
.pack(side
='right', fill
='x', expand
=1)
2134 if sys
.platform
!= 'win32': self
.stop_btn
.forget()
2135 self
.stop_btn
.config(state
='disabled')
2137 def select(self
, event
=None):
2138 self
.goto_btn
.config(state
='normal')
2140 def goto(self
, event
=None):
2141 selection
= self
.result_lst
.curselection()
2143 modname
= split(self
.result_lst
.get(selection
[0]))[0]
2144 self
.open(url
=self
.server
.url
+ modname
+ '.html')
2147 if not self
.expanded
: return
2148 self
.result_frm
.forget()
2149 self
.result_scr
.forget()
2150 self
.result_lst
.forget()
2151 self
.bigwidth
= self
.window
.winfo_width()
2152 self
.bigheight
= self
.window
.winfo_height()
2153 self
.window
.wm_geometry('%dx%d' % (self
.minwidth
, self
.minheight
))
2154 self
.window
.wm_minsize(self
.minwidth
, self
.minheight
)
2158 if self
.expanded
: return
2159 self
.result_frm
.pack(side
='bottom', fill
='x')
2160 self
.result_scr
.pack(side
='right', fill
='y')
2161 self
.result_lst
.pack(side
='top', fill
='both', expand
=1)
2162 self
.window
.wm_geometry('%dx%d' % (self
.bigwidth
, self
.bigheight
))
2163 self
.window
.wm_minsize(self
.minwidth
, self
.bigminheight
)
2166 def hide(self
, event
=None):
2173 # Tk will crash if pythonw.exe has an XP .manifest
2174 # file and the root has is not destroyed explicitly.
2175 # If the problem is ever fixed in Tk, the explicit
2182 except KeyboardInterrupt:
2185 # -------------------------------------------------- command-line interface
2188 return isinstance(x
, str) and find(x
, os
.sep
) >= 0
2191 """Command-line interface (looks at sys.argv to decide what to do)."""
2193 class BadUsage
: pass
2195 # Scripts don't get the current directory in their path by default.
2196 scriptdir
= os
.path
.dirname(sys
.argv
[0])
2197 if scriptdir
in sys
.path
:
2198 sys
.path
.remove(scriptdir
)
2199 sys
.path
.insert(0, '.')
2202 opts
, args
= getopt
.getopt(sys
.argv
[1:], 'gk:p:w')
2205 for opt
, val
in opts
:
2218 print 'pydoc server ready at %s' % server
.url
2220 print 'pydoc server stopped'
2221 serve(port
, ready
, stopped
)
2226 if not args
: raise BadUsage
2228 if ispath(arg
) and not os
.path
.exists(arg
):
2229 print 'file %r does not exist' % arg
2232 if ispath(arg
) and os
.path
.isfile(arg
):
2233 arg
= importfile(arg
)
2235 if ispath(arg
) and os
.path
.isdir(arg
):
2241 except ErrorDuringImport
, value
:
2244 except (getopt
.error
, BadUsage
):
2245 cmd
= os
.path
.basename(sys
.argv
[0])
2246 print """pydoc - the Python documentation tool
2249 Show text documentation on something. <name> may be the name of a
2250 Python keyword, topic, function, module, or package, or a dotted
2251 reference to a class or function within a module or module in a
2252 package. If <name> contains a '%s', it is used as the path to a
2253 Python source file to document. If name is 'keywords', 'topics',
2254 or 'modules', a listing of these things is displayed.
2257 Search for a keyword in the synopsis lines of all available modules.
2260 Start an HTTP server on the given port on the local machine.
2263 Pop up a graphical interface for finding and serving documentation.
2266 Write out the HTML documentation for a module to a file in the current
2267 directory. If <name> contains a '%s', it is treated as a filename; if
2268 it names a directory, documentation is written for all the contents.
2269 """ % (cmd
, os
.sep
, cmd
, cmd
, cmd
, cmd
, os
.sep
)
2271 if __name__
== '__main__': cli()