blob: e1e6d80685f0d683107b37ec325e290a9357e903 [file] [log] [blame]
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001#!/usr/bin/env python
Amaury Forgeot d'Arc768db922008-04-24 21:00:04 +00002# -*- coding: latin-1 -*-
Ka-Ping Yee1d384632001-03-01 00:24:32 +00003"""Generate Python documentation in HTML or text for interactive use.
Ka-Ping Yeedd175342001-02-27 14:43:46 +00004
Ka-Ping Yeedd175342001-02-27 14:43:46 +00005In the Python interpreter, do "from pydoc import help" to provide online
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00006help. Calling help(thing) on a Python object documents the object.
7
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00008Or, at the shell command line outside of Python:
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00009
Ka-Ping Yee37f7b382001-03-23 00:12:53 +000010Run "pydoc <name>" to show documentation on something. <name> may be
11the name of a function, module, package, or a dotted reference to a
12class or function within a module or module in a package. If the
13argument contains a path segment delimiter (e.g. slash on Unix,
14backslash on Windows) it is treated as the path to a Python source file.
Ka-Ping Yee66efbc72001-03-01 13:55:20 +000015
Ka-Ping Yee37f7b382001-03-23 00:12:53 +000016Run "pydoc -k <keyword>" to search for a keyword in the synopsis lines
17of all available modules.
Ka-Ping Yee66efbc72001-03-01 13:55:20 +000018
Ka-Ping Yee37f7b382001-03-23 00:12:53 +000019Run "pydoc -p <port>" to start an HTTP server on a given port on the
20local machine to generate documentation web pages.
Ka-Ping Yee66efbc72001-03-01 13:55:20 +000021
Ka-Ping Yee37f7b382001-03-23 00:12:53 +000022For platforms without a command line, "pydoc -g" starts the HTTP server
23and also pops up a little window for controlling it.
24
25Run "pydoc -w <name>" to write out the HTML documentation for a module
26to a file named "<name>.html".
Skip Montanaro4997a692003-09-10 16:47:51 +000027
28Module docs for core modules are assumed to be in
29
Georg Brandl86def6c2008-01-21 20:36:10 +000030 http://docs.python.org/library/
Skip Montanaro4997a692003-09-10 16:47:51 +000031
32This can be overridden by setting the PYTHONDOCS environment variable
33to a different URL or to a local directory containing the Library
34Reference Manual pages.
Ka-Ping Yee66efbc72001-03-01 13:55:20 +000035"""
Ka-Ping Yeedd175342001-02-27 14:43:46 +000036
37__author__ = "Ka-Ping Yee <ping@lfw.org>"
Ka-Ping Yee6f3f9a42001-02-27 22:42:36 +000038__date__ = "26 February 2001"
Jeremy Hylton3e0055f2005-10-20 19:59:25 +000039
Ka-Ping Yee09d7d9a2001-02-27 22:43:48 +000040__version__ = "$Revision$"
Martin v. Löwis6fe8f192004-11-14 10:21:04 +000041__credits__ = """Guido van Rossum, for an excellent programming language.
Ka-Ping Yee5e2b1732001-02-27 23:35:09 +000042Tommy Burnette, the original creator of manpy.
Ka-Ping Yee6f3f9a42001-02-27 22:42:36 +000043Paul Prescod, for all his work on onlinehelp.
44Richard Chamberlain, for the first implementation of textdoc.
Raymond Hettingered2dbe32005-01-01 07:51:01 +000045"""
Ka-Ping Yeedd175342001-02-27 14:43:46 +000046
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +000047# 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.
Ka-Ping Yee66efbc72001-03-01 13:55:20 +000054
Georg Brandl1a3284e2007-12-02 09:40:06 +000055import sys, imp, os, re, inspect, builtins, pkgutil
Alexandre Vassalotti1f2ba4b2008-05-16 07:12:44 +000056from reprlib import Repr
Benjamin Petersond76c8da2009-06-28 17:35:48 +000057from traceback import extract_tb as _extract_tb
Thomas Wouters49fd7fa2006-04-21 10:40:58 +000058try:
59 from collections import deque
60except ImportError:
61 # Python 2.3 compatibility
62 class deque(list):
63 def popleft(self):
64 return self.pop(0)
Ka-Ping Yeedd175342001-02-27 14:43:46 +000065
66# --------------------------------------------------------- common routines
67
Ka-Ping Yeedd175342001-02-27 14:43:46 +000068def pathdirs():
69 """Convert sys.path into a list of absolute, existing, unique paths."""
70 dirs = []
Ka-Ping Yee1d384632001-03-01 00:24:32 +000071 normdirs = []
Ka-Ping Yeedd175342001-02-27 14:43:46 +000072 for dir in sys.path:
73 dir = os.path.abspath(dir or '.')
Ka-Ping Yee1d384632001-03-01 00:24:32 +000074 normdir = os.path.normcase(dir)
75 if normdir not in normdirs and os.path.isdir(dir):
Ka-Ping Yeedd175342001-02-27 14:43:46 +000076 dirs.append(dir)
Ka-Ping Yee1d384632001-03-01 00:24:32 +000077 normdirs.append(normdir)
Ka-Ping Yeedd175342001-02-27 14:43:46 +000078 return dirs
79
80def getdoc(object):
81 """Get the doc string or comments for an object."""
Ka-Ping Yee3bda8792001-03-23 13:17:50 +000082 result = inspect.getdoc(object) or inspect.getcomments(object)
Neal Norwitz9d72bb42007-04-17 08:48:32 +000083 return result and re.sub('^ *\n', '', result.rstrip()) or ''
Ka-Ping Yeedd175342001-02-27 14:43:46 +000084
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +000085def splitdoc(doc):
86 """Split a doc string into a synopsis line (if any) and the rest."""
Neal Norwitz9d72bb42007-04-17 08:48:32 +000087 lines = doc.strip().split('\n')
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +000088 if len(lines) == 1:
89 return lines[0], ''
Neal Norwitz9d72bb42007-04-17 08:48:32 +000090 elif len(lines) >= 2 and not lines[1].rstrip():
91 return lines[0], '\n'.join(lines[2:])
92 return '', '\n'.join(lines)
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +000093
Ka-Ping Yeedd175342001-02-27 14:43:46 +000094def 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
100
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000101def isdata(object):
Georg Brandl94432422005-07-22 21:52:25 +0000102 """Check if an object is of a type that probably means it's data."""
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000103 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))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000106
107def replace(text, *pairs):
108 """Do a series of global replacements on a string."""
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +0000109 while pairs:
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000110 text = pairs[1].join(text.split(pairs[0]))
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +0000111 pairs = pairs[2:]
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000112 return text
113
114def cram(text, maxlen):
115 """Omit part of a string if needed to make it fit in a maximum length."""
116 if len(text) > maxlen:
Raymond Hettingerfca3bb62002-10-21 04:44:11 +0000117 pre = max(0, (maxlen-3)//2)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000118 post = max(0, maxlen-3-pre)
119 return text[:pre] + '...' + text[len(text)-post:]
120 return text
121
Brett Cannon84601f12004-06-19 01:22:48 +0000122_re_stripid = re.compile(r' at 0x[0-9a-f]{6,16}(>+)$', re.IGNORECASE)
Ka-Ping Yee1d384632001-03-01 00:24:32 +0000123def stripid(text):
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000124 """Remove the hexadecimal id from a Python object representation."""
Brett Cannonc6c1f472004-06-19 01:02:51 +0000125 # The behaviour of %p is implementation-dependent in terms of case.
Ezio Melottibf839b92010-02-16 23:32:24 +0000126 return _re_stripid.sub(r'\1', text)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000127
Brett Cannonc6c1f472004-06-19 01:02:51 +0000128def _is_some_method(obj):
129 return inspect.ismethod(obj) or inspect.ismethoddescriptor(obj)
Tim Peters536d2262001-09-20 05:13:38 +0000130
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000131def allmethods(cl):
132 methods = {}
Tim Peters536d2262001-09-20 05:13:38 +0000133 for key, value in inspect.getmembers(cl, _is_some_method):
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000134 methods[key] = 1
135 for base in cl.__bases__:
136 methods.update(allmethods(base)) # all your base are belong to us
137 for key in methods.keys():
138 methods[key] = getattr(cl, key)
139 return methods
140
Tim Petersfa26f7c2001-09-24 08:05:11 +0000141def _split_list(s, predicate):
142 """Split sequence s via predicate, and return pair ([true], [false]).
143
144 The return value is a 2-tuple of lists,
145 ([x for x in s if predicate(x)],
146 [x for x in s if not predicate(x)])
147 """
148
Tim Peters28355492001-09-23 21:29:55 +0000149 yes = []
150 no = []
Tim Petersfa26f7c2001-09-24 08:05:11 +0000151 for x in s:
152 if predicate(x):
153 yes.append(x)
Tim Peters28355492001-09-23 21:29:55 +0000154 else:
Tim Petersfa26f7c2001-09-24 08:05:11 +0000155 no.append(x)
Tim Peters28355492001-09-23 21:29:55 +0000156 return yes, no
157
Skip Montanaroa5616d22004-06-11 04:46:12 +0000158def visiblename(name, all=None):
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000159 """Decide whether to show documentation on a variable."""
160 # Certain special names are redundant.
Benjamin Peterson41181742008-07-02 20:22:54 +0000161 _hidden_names = ('__builtins__', '__doc__', '__file__', '__path__',
162 '__module__', '__name__', '__slots__', '__package__')
163 if name in _hidden_names: return 0
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000164 # Private names are hidden, but special names are displayed.
165 if name.startswith('__') and name.endswith('__'): return 1
Skip Montanaroa5616d22004-06-11 04:46:12 +0000166 if all is not None:
167 # only document that which the programmer exported in __all__
168 return name in all
169 else:
170 return not name.startswith('_')
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000171
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +0000172def classify_class_attrs(object):
173 """Wrap inspect.classify_class_attrs, with fixup for data descriptors."""
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000174 results = []
175 for (name, kind, cls, value) in inspect.classify_class_attrs(object):
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +0000176 if inspect.isdatadescriptor(value):
177 kind = 'data descriptor'
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000178 results.append((name, kind, cls, value))
179 return results
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +0000180
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000181# ----------------------------------------------------- module manipulation
182
183def ispackage(path):
184 """Guess whether a path refers to a package directory."""
185 if os.path.isdir(path):
Raymond Hettingerdbecd932005-02-06 06:57:08 +0000186 for ext in ('.py', '.pyc', '.pyo'):
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000187 if os.path.isfile(os.path.join(path, '__init__' + ext)):
Tim Petersbc0e9102002-04-04 22:55:58 +0000188 return True
189 return False
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000190
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000191def source_synopsis(file):
192 line = file.readline()
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000193 while line[:1] == '#' or not line.strip():
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000194 line = file.readline()
195 if not line: break
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000196 line = line.strip()
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000197 if line[:4] == 'r"""': line = line[1:]
198 if line[:3] == '"""':
199 line = line[3:]
200 if line[-1:] == '\\': line = line[:-1]
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000201 while not line.strip():
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000202 line = file.readline()
203 if not line: break
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000204 result = line.split('"""')[0].strip()
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000205 else: result = None
206 return result
207
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000208def synopsis(filename, cache={}):
209 """Get the one-line summary out of a module file."""
Raymond Hettinger32200ae2002-06-01 19:51:15 +0000210 mtime = os.stat(filename).st_mtime
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000211 lastupdate, result = cache.get(filename, (0, None))
212 if lastupdate < mtime:
213 info = inspect.getmoduleinfo(filename)
Georg Brandl26fd2e12006-03-08 09:34:53 +0000214 try:
215 file = open(filename)
216 except IOError:
217 # module can't be opened, so skip it
218 return None
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000219 if info and 'b' in info[2]: # binary modules have to be imported
220 try: module = imp.load_module('__temp__', file, filename, info[1:])
221 except: return None
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000222 result = (module.__doc__ or '').splitlines()[0]
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000223 del sys.modules['__temp__']
224 else: # text modules can be directly examined
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000225 result = source_synopsis(file)
226 file.close()
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000227 cache[filename] = (mtime, result)
228 return result
229
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000230class ErrorDuringImport(Exception):
231 """Errors that occurred while trying to import something to document it."""
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000232 def __init__(self, filename, exc_info):
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000233 self.filename = filename
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000234 self.exc, self.value, self.tb = exc_info
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000235
236 def __str__(self):
Guido van Rossuma01a8b62007-05-27 09:20:14 +0000237 exc = self.exc.__name__
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000238 return 'problem in %s - %s: %s' % (self.filename, exc, self.value)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000239
240def importfile(path):
241 """Import a Python source file or compiled file given its path."""
242 magic = imp.get_magic()
243 file = open(path, 'r')
244 if file.read(len(magic)) == magic:
245 kind = imp.PY_COMPILED
246 else:
247 kind = imp.PY_SOURCE
248 file.close()
249 filename = os.path.basename(path)
250 name, ext = os.path.splitext(filename)
251 file = open(path, 'r')
252 try:
253 module = imp.load_module(name, file, path, (ext, 'r', kind))
254 except:
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000255 raise ErrorDuringImport(path, sys.exc_info())
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000256 file.close()
257 return module
258
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000259def safeimport(path, forceload=0, cache={}):
260 """Import a module; handle errors; return None if the module isn't found.
261
262 If the module *is* found but an exception occurs, it's wrapped in an
263 ErrorDuringImport exception and reraised. Unlike __import__, if a
264 package path is specified, the module at the end of the path is returned,
265 not the package at the beginning. If the optional 'forceload' argument
266 is 1, we reload the module from disk (unless it's a dynamic extension)."""
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000267 try:
Ka-Ping Yee9a2dcf82005-11-05 05:04:41 +0000268 # If forceload is 1 and the module has been previously loaded from
269 # disk, we always have to reload the module. Checking the file's
270 # mtime isn't good enough (e.g. the module could contain a class
271 # that inherits from another module that has changed).
272 if forceload and path in sys.modules:
273 if path not in sys.builtin_module_names:
Guido van Rossume7ba4952007-06-06 23:52:48 +0000274 # Remove the module from sys.modules and re-import to try
275 # and avoid problems with partially loaded modules.
276 # Also remove any submodules because they won't appear
277 # in the newly loaded module's namespace if they're already
278 # in sys.modules.
Ka-Ping Yee9a2dcf82005-11-05 05:04:41 +0000279 subs = [m for m in sys.modules if m.startswith(path + '.')]
280 for key in [path] + subs:
281 # Prevent garbage collection.
282 cache[key] = sys.modules[key]
283 del sys.modules[key]
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000284 module = __import__(path)
285 except:
286 # Did the error occur before or after the module was found?
287 (exc, value, tb) = info = sys.exc_info()
Raymond Hettinger54f02222002-06-01 14:18:47 +0000288 if path in sys.modules:
Fred Drakedb390c12005-10-28 14:39:47 +0000289 # An error occurred while executing the imported module.
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000290 raise ErrorDuringImport(sys.modules[path].__file__, info)
291 elif exc is SyntaxError:
292 # A SyntaxError occurred before we could execute the module.
293 raise ErrorDuringImport(value.filename, info)
Benjamin Petersond76c8da2009-06-28 17:35:48 +0000294 elif exc is ImportError and _extract_tb(tb)[-1][2]=='safeimport':
295 # The import error occurred directly in this function,
296 # which means there is no such module in the path.
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000297 return None
298 else:
299 # Some other error occurred during the importing process.
300 raise ErrorDuringImport(path, sys.exc_info())
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000301 for part in path.split('.')[1:]:
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000302 try: module = getattr(module, part)
303 except AttributeError: return None
304 return module
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000305
306# ---------------------------------------------------- formatter base class
307
308class Doc:
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000309 def document(self, object, name=None, *args):
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000310 """Generate documentation for an object."""
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000311 args = (object, name) + args
Brett Cannon28a4f0f2003-06-11 23:38:55 +0000312 # 'try' clause is to attempt to handle the possibility that inspect
313 # identifies something in a way that pydoc itself has issues handling;
314 # think 'super' and how it is a descriptor (which raises the exception
315 # by lacking a __name__ attribute) and an instance.
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000316 if inspect.isgetsetdescriptor(object): return self.docdata(*args)
317 if inspect.ismemberdescriptor(object): return self.docdata(*args)
Brett Cannon28a4f0f2003-06-11 23:38:55 +0000318 try:
319 if inspect.ismodule(object): return self.docmodule(*args)
320 if inspect.isclass(object): return self.docclass(*args)
321 if inspect.isroutine(object): return self.docroutine(*args)
322 except AttributeError:
323 pass
Johannes Gijsbers8de645a2004-11-07 19:16:05 +0000324 if isinstance(object, property): return self.docproperty(*args)
Guido van Rossum68468eb2003-02-27 20:14:51 +0000325 return self.docother(*args)
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000326
327 def fail(self, object, name=None, *args):
328 """Raise an exception for unimplemented types."""
329 message = "don't know how to document object%s of type %s" % (
330 name and ' ' + repr(name), type(object).__name__)
Collin Winterce36ad82007-08-30 01:19:48 +0000331 raise TypeError(message)
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000332
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000333 docmodule = docclass = docroutine = docother = docproperty = docdata = fail
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000334
Skip Montanaro4997a692003-09-10 16:47:51 +0000335 def getdocloc(self, object):
336 """Return the location of module docs or None"""
337
338 try:
339 file = inspect.getabsfile(object)
340 except TypeError:
341 file = '(built-in)'
342
343 docloc = os.environ.get("PYTHONDOCS",
Georg Brandl86def6c2008-01-21 20:36:10 +0000344 "http://docs.python.org/library")
Skip Montanaro4997a692003-09-10 16:47:51 +0000345 basedir = os.path.join(sys.exec_prefix, "lib",
346 "python"+sys.version[0:3])
347 if (isinstance(object, type(os)) and
348 (object.__name__ in ('errno', 'exceptions', 'gc', 'imp',
349 'marshal', 'posix', 'signal', 'sys',
Georg Brandl2067bfd2008-05-25 13:05:15 +0000350 '_thread', 'zipimport') or
Skip Montanaro4997a692003-09-10 16:47:51 +0000351 (file.startswith(basedir) and
Brian Curtin0d8a1dd2010-03-31 03:22:46 +0000352 not file.startswith(os.path.join(basedir, 'site-packages')))) and
Brian Curtin1f03f6e2010-04-01 04:06:54 +0000353 object.__name__ not in ('xml.etree', 'test.pydoc_mod')):
Skip Montanaro4997a692003-09-10 16:47:51 +0000354 if docloc.startswith("http://"):
Georg Brandl86def6c2008-01-21 20:36:10 +0000355 docloc = "%s/%s" % (docloc.rstrip("/"), object.__name__)
Skip Montanaro4997a692003-09-10 16:47:51 +0000356 else:
Georg Brandl86def6c2008-01-21 20:36:10 +0000357 docloc = os.path.join(docloc, object.__name__ + ".html")
Skip Montanaro4997a692003-09-10 16:47:51 +0000358 else:
359 docloc = None
360 return docloc
361
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000362# -------------------------------------------- HTML documentation generator
363
364class HTMLRepr(Repr):
365 """Class for safely making an HTML representation of a Python object."""
366 def __init__(self):
367 Repr.__init__(self)
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000368 self.maxlist = self.maxtuple = 20
369 self.maxdict = 10
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000370 self.maxstring = self.maxother = 100
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000371
372 def escape(self, text):
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +0000373 return replace(text, '&', '&amp;', '<', '&lt;', '>', '&gt;')
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000374
375 def repr(self, object):
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000376 return Repr.repr(self, object)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000377
378 def repr1(self, x, level):
Skip Montanaro0fe8fce2003-06-27 15:45:41 +0000379 if hasattr(type(x), '__name__'):
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000380 methodname = 'repr_' + '_'.join(type(x).__name__.split())
Skip Montanaro0fe8fce2003-06-27 15:45:41 +0000381 if hasattr(self, methodname):
382 return getattr(self, methodname)(x, level)
383 return self.escape(cram(stripid(repr(x)), self.maxother))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000384
385 def repr_string(self, x, level):
Ka-Ping Yeea2fe1032001-03-02 01:19:14 +0000386 test = cram(x, self.maxstring)
387 testrepr = repr(test)
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +0000388 if '\\' in test and '\\' not in replace(testrepr, r'\\', ''):
Ka-Ping Yeea2fe1032001-03-02 01:19:14 +0000389 # Backslashes are only literal in the string and are never
390 # needed to make any special characters, so show a raw string.
391 return 'r' + testrepr[0] + self.escape(test) + testrepr[0]
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +0000392 return re.sub(r'((\\[\\abfnrtv\'"]|\\[0-9]..|\\x..|\\u....)+)',
Raymond Hettinger95f285c2009-02-24 23:41:47 +0000393 r'<font color="#c040c0">\1</font>',
Ka-Ping Yeea2fe1032001-03-02 01:19:14 +0000394 self.escape(testrepr))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000395
Skip Montanarodf708782002-03-07 22:58:02 +0000396 repr_str = repr_string
397
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000398 def repr_instance(self, x, level):
399 try:
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000400 return self.escape(cram(stripid(repr(x)), self.maxstring))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000401 except:
402 return self.escape('<%s instance>' % x.__class__.__name__)
403
404 repr_unicode = repr_string
405
406class HTMLDoc(Doc):
407 """Formatter class for HTML documentation."""
408
409 # ------------------------------------------- HTML formatting utilities
410
411 _repr_instance = HTMLRepr()
412 repr = _repr_instance.repr
413 escape = _repr_instance.escape
414
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000415 def page(self, title, contents):
416 """Format an HTML page."""
Georg Brandl388faac2009-04-10 08:31:48 +0000417 return '''\
Georg Brandle6066942009-04-10 08:28:28 +0000418<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000419<html><head><title>Python: %s</title>
Georg Brandl388faac2009-04-10 08:31:48 +0000420<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
Raymond Hettinger95f285c2009-02-24 23:41:47 +0000421</head><body bgcolor="#f0f0f8">
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000422%s
423</body></html>''' % (title, contents)
424
425 def heading(self, title, fgcol, bgcol, extras=''):
426 """Format a page heading."""
427 return '''
Tim Peters59ed4482001-10-31 04:20:26 +0000428<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="heading">
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000429<tr bgcolor="%s">
Tim Peters2306d242001-09-25 03:18:32 +0000430<td valign=bottom>&nbsp;<br>
431<font color="%s" face="helvetica, arial">&nbsp;<br>%s</font></td
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000432><td align=right valign=bottom
Ka-Ping Yee987ec902001-03-23 13:35:45 +0000433><font color="%s" face="helvetica, arial">%s</font></td></tr></table>
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000434 ''' % (bgcol, fgcol, title, fgcol, extras or '&nbsp;')
435
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000436 def section(self, title, fgcol, bgcol, contents, width=6,
437 prelude='', marginalia=None, gap='&nbsp;'):
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000438 """Format a section with a heading."""
439 if marginalia is None:
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +0000440 marginalia = '<tt>' + '&nbsp;' * width + '</tt>'
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000441 result = '''<p>
Tim Peters59ed4482001-10-31 04:20:26 +0000442<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000443<tr bgcolor="%s">
Tim Peters2306d242001-09-25 03:18:32 +0000444<td colspan=3 valign=bottom>&nbsp;<br>
445<font color="%s" face="helvetica, arial">%s</font></td></tr>
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000446 ''' % (bgcol, fgcol, title)
447 if prelude:
448 result = result + '''
Ka-Ping Yee987ec902001-03-23 13:35:45 +0000449<tr bgcolor="%s"><td rowspan=2>%s</td>
450<td colspan=2>%s</td></tr>
451<tr><td>%s</td>''' % (bgcol, marginalia, prelude, gap)
452 else:
453 result = result + '''
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000454<tr><td bgcolor="%s">%s</td><td>%s</td>''' % (bgcol, marginalia, gap)
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000455
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +0000456 return result + '\n<td width="100%%">%s</td></tr></table>' % contents
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000457
458 def bigsection(self, title, *args):
459 """Format a section with a big heading."""
Raymond Hettinger95f285c2009-02-24 23:41:47 +0000460 title = '<big><strong>%s</strong></big>' % title
Guido van Rossum68468eb2003-02-27 20:14:51 +0000461 return self.section(title, *args)
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000462
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000463 def preformat(self, text):
464 """Format literal preformatted text."""
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000465 text = self.escape(text.expandtabs())
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +0000466 return replace(text, '\n\n', '\n \n', '\n\n', '\n \n',
467 ' ', '&nbsp;', '\n', '<br>\n')
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000468
469 def multicolumn(self, list, format, cols=4):
470 """Format a list of items into a multi-column list."""
471 result = ''
Guido van Rossumc1f779c2007-07-03 08:25:58 +0000472 rows = (len(list)+cols-1)//cols
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000473 for col in range(cols):
Guido van Rossumc1f779c2007-07-03 08:25:58 +0000474 result = result + '<td width="%d%%" valign=top>' % (100//cols)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000475 for i in range(rows*col, rows*col+rows):
476 if i < len(list):
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000477 result = result + format(list[i]) + '<br>\n'
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000478 result = result + '</td>'
Tim Peters59ed4482001-10-31 04:20:26 +0000479 return '<table width="100%%" summary="list"><tr>%s</tr></table>' % result
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000480
Raymond Hettinger95f285c2009-02-24 23:41:47 +0000481 def grey(self, text): return '<font color="#909090">%s</font>' % text
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000482
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000483 def namelink(self, name, *dicts):
484 """Make a link for an identifier, given name-to-URL mappings."""
485 for dict in dicts:
Raymond Hettinger54f02222002-06-01 14:18:47 +0000486 if name in dict:
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000487 return '<a href="%s">%s</a>' % (dict[name], name)
488 return name
489
Ka-Ping Yeeb7a48302001-04-12 20:39:14 +0000490 def classlink(self, object, modname):
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000491 """Make a link for a class."""
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000492 name, module = object.__name__, sys.modules.get(object.__module__)
493 if hasattr(module, name) and getattr(module, name) is object:
Ka-Ping Yeeb7a48302001-04-12 20:39:14 +0000494 return '<a href="%s.html#%s">%s</a>' % (
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000495 module.__name__, name, classname(object, modname))
496 return classname(object, modname)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000497
498 def modulelink(self, object):
499 """Make a link for a module."""
500 return '<a href="%s.html">%s</a>' % (object.__name__, object.__name__)
501
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000502 def modpkglink(self, modpkginfo):
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000503 """Make a link for a module or package to display in an index."""
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000504 name, path, ispackage, shadowed = modpkginfo
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000505 if shadowed:
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000506 return self.grey(name)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000507 if path:
508 url = '%s.%s.html' % (path, name)
509 else:
510 url = '%s.html' % name
511 if ispackage:
Raymond Hettinger95f285c2009-02-24 23:41:47 +0000512 text = '<strong>%s</strong>&nbsp;(package)' % name
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000513 else:
514 text = name
515 return '<a href="%s">%s</a>' % (url, text)
516
517 def markup(self, text, escape=None, funcs={}, classes={}, methods={}):
518 """Mark up some plain text, given a context of symbols to look for.
519 Each context dictionary maps object names to anchor names."""
520 escape = escape or self.escape
521 results = []
522 here = 0
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000523 pattern = re.compile(r'\b((http|ftp)://\S+[\w/]|'
524 r'RFC[- ]?(\d+)|'
Ka-Ping Yeef78a81b2001-03-27 08:13:42 +0000525 r'PEP[- ]?(\d+)|'
Neil Schemenauerd69711c2002-03-24 23:02:07 +0000526 r'(self\.)?(\w+))')
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000527 while True:
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000528 match = pattern.search(text, here)
529 if not match: break
530 start, end = match.span()
531 results.append(escape(text[here:start]))
532
Ka-Ping Yeef78a81b2001-03-27 08:13:42 +0000533 all, scheme, rfc, pep, selfdot, name = match.groups()
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000534 if scheme:
Neil Schemenauercddc1a02002-03-24 23:11:21 +0000535 url = escape(all).replace('"', '&quot;')
536 results.append('<a href="%s">%s</a>' % (url, url))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000537 elif rfc:
Ka-Ping Yeef78a81b2001-03-27 08:13:42 +0000538 url = 'http://www.rfc-editor.org/rfc/rfc%d.txt' % int(rfc)
539 results.append('<a href="%s">%s</a>' % (url, escape(all)))
540 elif pep:
Christian Heimes2202f872008-02-06 14:31:34 +0000541 url = 'http://www.python.org/dev/peps/pep-%04d/' % int(pep)
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000542 results.append('<a href="%s">%s</a>' % (url, escape(all)))
543 elif text[end:end+1] == '(':
544 results.append(self.namelink(name, methods, funcs, classes))
545 elif selfdot:
Raymond Hettinger95f285c2009-02-24 23:41:47 +0000546 results.append('self.<strong>%s</strong>' % name)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000547 else:
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000548 results.append(self.namelink(name, classes))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000549 here = end
550 results.append(escape(text[here:]))
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000551 return ''.join(results)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000552
553 # ---------------------------------------------- type-specific routines
554
Ka-Ping Yeeb7a48302001-04-12 20:39:14 +0000555 def formattree(self, tree, modname, parent=None):
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000556 """Produce HTML for a class tree as given by inspect.getclasstree()."""
557 result = ''
558 for entry in tree:
559 if type(entry) is type(()):
560 c, bases = entry
Raymond Hettinger95f285c2009-02-24 23:41:47 +0000561 result = result + '<dt><font face="helvetica, arial">'
Ka-Ping Yeeb7a48302001-04-12 20:39:14 +0000562 result = result + self.classlink(c, modname)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000563 if bases and bases != (parent,):
564 parents = []
565 for base in bases:
Ka-Ping Yeeb7a48302001-04-12 20:39:14 +0000566 parents.append(self.classlink(base, modname))
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000567 result = result + '(' + ', '.join(parents) + ')'
Raymond Hettinger95f285c2009-02-24 23:41:47 +0000568 result = result + '\n</font></dt>'
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000569 elif type(entry) is type([]):
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000570 result = result + '<dd>\n%s</dd>\n' % self.formattree(
Ka-Ping Yeeb7a48302001-04-12 20:39:14 +0000571 entry, modname, c)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000572 return '<dl>\n%s</dl>\n' % result
573
Tim Peters8dd7ade2001-10-18 19:56:17 +0000574 def docmodule(self, object, name=None, mod=None, *ignored):
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000575 """Produce HTML documentation for a module object."""
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000576 name = object.__name__ # ignore the passed-in name
Skip Montanaroa5616d22004-06-11 04:46:12 +0000577 try:
578 all = object.__all__
579 except AttributeError:
580 all = None
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000581 parts = name.split('.')
Ka-Ping Yee66efbc72001-03-01 13:55:20 +0000582 links = []
583 for i in range(len(parts)-1):
584 links.append(
Raymond Hettinger95f285c2009-02-24 23:41:47 +0000585 '<a href="%s.html"><font color="#ffffff">%s</font></a>' %
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000586 ('.'.join(parts[:i+1]), parts[i]))
587 linkedname = '.'.join(links + parts[-1:])
Raymond Hettinger95f285c2009-02-24 23:41:47 +0000588 head = '<big><big><strong>%s</strong></big></big>' % linkedname
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000589 try:
Ka-Ping Yee239432a2001-03-02 02:45:08 +0000590 path = inspect.getabsfile(object)
Ka-Ping Yee6191a232001-04-13 15:00:27 +0000591 url = path
592 if sys.platform == 'win32':
593 import nturl2path
594 url = nturl2path.pathname2url(path)
595 filelink = '<a href="file:%s">%s</a>' % (url, path)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000596 except TypeError:
597 filelink = '(built-in)'
Ka-Ping Yee6f3f9a42001-02-27 22:42:36 +0000598 info = []
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000599 if hasattr(object, '__version__'):
Ka-Ping Yee6f3f9a42001-02-27 22:42:36 +0000600 version = str(object.__version__)
Ka-Ping Yee40c49912001-02-27 22:46:01 +0000601 if version[:11] == '$' + 'Revision: ' and version[-1:] == '$':
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000602 version = version[11:-1].strip()
Ka-Ping Yee1d384632001-03-01 00:24:32 +0000603 info.append('version %s' % self.escape(version))
Ka-Ping Yee6f3f9a42001-02-27 22:42:36 +0000604 if hasattr(object, '__date__'):
605 info.append(self.escape(str(object.__date__)))
606 if info:
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000607 head = head + ' (%s)' % ', '.join(info)
Skip Montanaro4997a692003-09-10 16:47:51 +0000608 docloc = self.getdocloc(object)
609 if docloc is not None:
610 docloc = '<br><a href="%(docloc)s">Module Docs</a>' % locals()
611 else:
612 docloc = ''
Ka-Ping Yee66efbc72001-03-01 13:55:20 +0000613 result = self.heading(
Skip Montanaro4997a692003-09-10 16:47:51 +0000614 head, '#ffffff', '#7799ee',
615 '<a href=".">index</a><br>' + filelink + docloc)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000616
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000617 modules = inspect.getmembers(object, inspect.ismodule)
618
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000619 classes, cdict = [], {}
620 for key, value in inspect.getmembers(object, inspect.isclass):
Johannes Gijsbers4c11f602004-08-30 14:13:04 +0000621 # if __all__ exists, believe it. Otherwise use old heuristic.
622 if (all is not None or
623 (inspect.getmodule(value) or object) is object):
Skip Montanaroa5616d22004-06-11 04:46:12 +0000624 if visiblename(key, all):
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000625 classes.append((key, value))
626 cdict[key] = cdict[value] = '#' + key
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000627 for key, value in classes:
628 for base in value.__bases__:
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000629 key, modname = base.__name__, base.__module__
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000630 module = sys.modules.get(modname)
631 if modname != name and module and hasattr(module, key):
632 if getattr(module, key) is base:
Raymond Hettinger54f02222002-06-01 14:18:47 +0000633 if not key in cdict:
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000634 cdict[key] = cdict[base] = modname + '.html#' + key
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000635 funcs, fdict = [], {}
636 for key, value in inspect.getmembers(object, inspect.isroutine):
Johannes Gijsbers4c11f602004-08-30 14:13:04 +0000637 # if __all__ exists, believe it. Otherwise use old heuristic.
638 if (all is not None or
639 inspect.isbuiltin(value) or inspect.getmodule(value) is object):
Skip Montanaroa5616d22004-06-11 04:46:12 +0000640 if visiblename(key, all):
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000641 funcs.append((key, value))
642 fdict[key] = '#-' + key
643 if inspect.isfunction(value): fdict[value] = fdict[key]
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000644 data = []
645 for key, value in inspect.getmembers(object, isdata):
Skip Montanaroa5616d22004-06-11 04:46:12 +0000646 if visiblename(key, all):
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000647 data.append((key, value))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000648
649 doc = self.markup(getdoc(object), self.preformat, fdict, cdict)
650 doc = doc and '<tt>%s</tt>' % doc
Tim Peters2306d242001-09-25 03:18:32 +0000651 result = result + '<p>%s</p>\n' % doc
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000652
653 if hasattr(object, '__path__'):
654 modpkgs = []
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000655 for importer, modname, ispkg in pkgutil.iter_modules(object.__path__):
656 modpkgs.append((modname, name, ispkg, 0))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000657 modpkgs.sort()
658 contents = self.multicolumn(modpkgs, self.modpkglink)
659 result = result + self.bigsection(
660 'Package Contents', '#ffffff', '#aa55cc', contents)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000661 elif modules:
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000662 contents = self.multicolumn(
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000663 modules, lambda t: self.modulelink(t[1]))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000664 result = result + self.bigsection(
Christian Heimes7131fd92008-02-19 14:21:46 +0000665 'Modules', '#ffffff', '#aa55cc', contents)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000666
667 if classes:
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000668 classlist = [value for (key, value) in classes]
Ka-Ping Yeeb7a48302001-04-12 20:39:14 +0000669 contents = [
670 self.formattree(inspect.getclasstree(classlist, 1), name)]
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000671 for key, value in classes:
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +0000672 contents.append(self.document(value, key, name, fdict, cdict))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000673 result = result + self.bigsection(
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000674 'Classes', '#ffffff', '#ee77aa', ' '.join(contents))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000675 if funcs:
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000676 contents = []
677 for key, value in funcs:
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +0000678 contents.append(self.document(value, key, name, fdict, cdict))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000679 result = result + self.bigsection(
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000680 'Functions', '#ffffff', '#eeaa77', ' '.join(contents))
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000681 if data:
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000682 contents = []
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000683 for key, value in data:
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000684 contents.append(self.document(value, key))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000685 result = result + self.bigsection(
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000686 'Data', '#ffffff', '#55aa55', '<br>\n'.join(contents))
Ka-Ping Yee6f3f9a42001-02-27 22:42:36 +0000687 if hasattr(object, '__author__'):
688 contents = self.markup(str(object.__author__), self.preformat)
689 result = result + self.bigsection(
690 'Author', '#ffffff', '#7799ee', contents)
Ka-Ping Yee6f3f9a42001-02-27 22:42:36 +0000691 if hasattr(object, '__credits__'):
692 contents = self.markup(str(object.__credits__), self.preformat)
693 result = result + self.bigsection(
694 'Credits', '#ffffff', '#7799ee', contents)
695
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000696 return result
697
Tim Peters8dd7ade2001-10-18 19:56:17 +0000698 def docclass(self, object, name=None, mod=None, funcs={}, classes={},
699 *ignored):
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000700 """Produce HTML documentation for a class object."""
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000701 realname = object.__name__
702 name = name or realname
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000703 bases = object.__bases__
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000704
Tim Petersb47879b2001-09-24 04:47:19 +0000705 contents = []
706 push = contents.append
707
Tim Petersfa26f7c2001-09-24 08:05:11 +0000708 # Cute little class to pump out a horizontal rule between sections.
709 class HorizontalRule:
710 def __init__(self):
711 self.needone = 0
712 def maybe(self):
713 if self.needone:
714 push('<hr>\n')
715 self.needone = 1
716 hr = HorizontalRule()
717
Tim Petersc86f6ca2001-09-26 21:31:51 +0000718 # List the mro, if non-trivial.
Raymond Hettinger756b3f32004-01-29 06:37:52 +0000719 mro = deque(inspect.getmro(object))
Tim Petersc86f6ca2001-09-26 21:31:51 +0000720 if len(mro) > 2:
721 hr.maybe()
722 push('<dl><dt>Method resolution order:</dt>\n')
723 for base in mro:
724 push('<dd>%s</dd>\n' % self.classlink(base,
725 object.__module__))
726 push('</dl>\n')
727
Tim Petersb47879b2001-09-24 04:47:19 +0000728 def spill(msg, attrs, predicate):
Tim Petersfa26f7c2001-09-24 08:05:11 +0000729 ok, attrs = _split_list(attrs, predicate)
Tim Petersb47879b2001-09-24 04:47:19 +0000730 if ok:
Tim Petersfa26f7c2001-09-24 08:05:11 +0000731 hr.maybe()
Tim Petersb47879b2001-09-24 04:47:19 +0000732 push(msg)
733 for name, kind, homecls, value in ok:
734 push(self.document(getattr(object, name), name, mod,
735 funcs, classes, mdict, object))
736 push('\n')
737 return attrs
738
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +0000739 def spilldescriptors(msg, attrs, predicate):
Tim Petersfa26f7c2001-09-24 08:05:11 +0000740 ok, attrs = _split_list(attrs, predicate)
Tim Petersb47879b2001-09-24 04:47:19 +0000741 if ok:
Tim Petersfa26f7c2001-09-24 08:05:11 +0000742 hr.maybe()
Tim Petersb47879b2001-09-24 04:47:19 +0000743 push(msg)
744 for name, kind, homecls, value in ok:
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +0000745 push(self._docdescriptor(name, value, mod))
Tim Petersb47879b2001-09-24 04:47:19 +0000746 return attrs
747
Tim Petersfa26f7c2001-09-24 08:05:11 +0000748 def spilldata(msg, attrs, predicate):
749 ok, attrs = _split_list(attrs, predicate)
Tim Petersb47879b2001-09-24 04:47:19 +0000750 if ok:
Tim Petersfa26f7c2001-09-24 08:05:11 +0000751 hr.maybe()
Tim Petersb47879b2001-09-24 04:47:19 +0000752 push(msg)
753 for name, kind, homecls, value in ok:
754 base = self.docother(getattr(object, name), name, mod)
Guido van Rossumd59da4b2007-05-22 18:11:13 +0000755 if hasattr(value, '__call__') or inspect.isdatadescriptor(value):
Guido van Rossum5e355b22002-05-21 20:56:15 +0000756 doc = getattr(value, "__doc__", None)
757 else:
758 doc = None
Tim Petersb47879b2001-09-24 04:47:19 +0000759 if doc is None:
760 push('<dl><dt>%s</dl>\n' % base)
761 else:
762 doc = self.markup(getdoc(value), self.preformat,
763 funcs, classes, mdict)
Tim Peters2306d242001-09-25 03:18:32 +0000764 doc = '<dd><tt>%s</tt>' % doc
Tim Petersb47879b2001-09-24 04:47:19 +0000765 push('<dl><dt>%s%s</dl>\n' % (base, doc))
766 push('\n')
767 return attrs
768
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000769 attrs = [(name, kind, cls, value)
770 for name, kind, cls, value in classify_class_attrs(object)
771 if visiblename(name)]
772
Tim Petersb47879b2001-09-24 04:47:19 +0000773 mdict = {}
774 for key, kind, homecls, value in attrs:
775 mdict[key] = anchor = '#' + name + '-' + key
776 value = getattr(object, key)
777 try:
778 # The value may not be hashable (e.g., a data attr with
779 # a dict or list value).
780 mdict[value] = anchor
781 except TypeError:
782 pass
783
Tim Petersfa26f7c2001-09-24 08:05:11 +0000784 while attrs:
Tim Peters351e3622001-09-27 03:29:51 +0000785 if mro:
Raymond Hettinger756b3f32004-01-29 06:37:52 +0000786 thisclass = mro.popleft()
Tim Peters351e3622001-09-27 03:29:51 +0000787 else:
788 thisclass = attrs[0][2]
Tim Petersfa26f7c2001-09-24 08:05:11 +0000789 attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass)
790
Georg Brandl1a3284e2007-12-02 09:40:06 +0000791 if thisclass is builtins.object:
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000792 attrs = inherited
793 continue
794 elif thisclass is object:
795 tag = 'defined here'
Tim Petersb47879b2001-09-24 04:47:19 +0000796 else:
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000797 tag = 'inherited from %s' % self.classlink(thisclass,
798 object.__module__)
Tim Petersb47879b2001-09-24 04:47:19 +0000799 tag += ':<br>\n'
800
801 # Sort attrs by name.
Raymond Hettingerd4cb56d2008-01-30 02:55:10 +0000802 attrs.sort(key=lambda t: t[0])
Tim Petersb47879b2001-09-24 04:47:19 +0000803
804 # Pump out the attrs, segregated by kind.
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000805 attrs = spill('Methods %s' % tag, attrs,
Tim Petersb47879b2001-09-24 04:47:19 +0000806 lambda t: t[1] == 'method')
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000807 attrs = spill('Class methods %s' % tag, attrs,
Tim Petersb47879b2001-09-24 04:47:19 +0000808 lambda t: t[1] == 'class method')
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000809 attrs = spill('Static methods %s' % tag, attrs,
Tim Petersb47879b2001-09-24 04:47:19 +0000810 lambda t: t[1] == 'static method')
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +0000811 attrs = spilldescriptors('Data descriptors %s' % tag, attrs,
812 lambda t: t[1] == 'data descriptor')
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000813 attrs = spilldata('Data and other attributes %s' % tag, attrs,
Tim Petersfa26f7c2001-09-24 08:05:11 +0000814 lambda t: t[1] == 'data')
Tim Petersb47879b2001-09-24 04:47:19 +0000815 assert attrs == []
Tim Peters351e3622001-09-27 03:29:51 +0000816 attrs = inherited
Tim Petersb47879b2001-09-24 04:47:19 +0000817
818 contents = ''.join(contents)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000819
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000820 if name == realname:
821 title = '<a name="%s">class <strong>%s</strong></a>' % (
822 name, realname)
823 else:
824 title = '<strong>%s</strong> = <a name="%s">class %s</a>' % (
825 name, name, realname)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000826 if bases:
827 parents = []
828 for base in bases:
Ka-Ping Yeeb7a48302001-04-12 20:39:14 +0000829 parents.append(self.classlink(base, object.__module__))
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000830 title = title + '(%s)' % ', '.join(parents)
Tim Peters2306d242001-09-25 03:18:32 +0000831 doc = self.markup(getdoc(object), self.preformat, funcs, classes, mdict)
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000832 doc = doc and '<tt>%s<br>&nbsp;</tt>' % doc
Tim Petersc86f6ca2001-09-26 21:31:51 +0000833
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +0000834 return self.section(title, '#000000', '#ffc8d8', contents, 3, doc)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000835
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000836 def formatvalue(self, object):
837 """Format an argument default value as text."""
Tim Peters2306d242001-09-25 03:18:32 +0000838 return self.grey('=' + self.repr(object))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000839
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +0000840 def docroutine(self, object, name=None, mod=None,
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000841 funcs={}, classes={}, methods={}, cl=None):
Ka-Ping Yee66efbc72001-03-01 13:55:20 +0000842 """Produce HTML documentation for a function or method object."""
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000843 realname = object.__name__
844 name = name or realname
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000845 anchor = (cl and cl.__name__ or '') + '-' + name
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000846 note = ''
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000847 skipdocs = 0
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000848 if inspect.ismethod(object):
Christian Heimesff737952007-11-27 10:40:20 +0000849 imclass = object.__self__.__class__
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000850 if cl:
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +0000851 if imclass is not cl:
Ka-Ping Yeeb7a48302001-04-12 20:39:14 +0000852 note = ' from ' + self.classlink(imclass, mod)
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000853 else:
Christian Heimesff737952007-11-27 10:40:20 +0000854 if object.__self__ is not None:
Ka-Ping Yeeb7a48302001-04-12 20:39:14 +0000855 note = ' method of %s instance' % self.classlink(
Christian Heimesff737952007-11-27 10:40:20 +0000856 object.__self__.__class__, mod)
Ka-Ping Yeeb7a48302001-04-12 20:39:14 +0000857 else:
858 note = ' unbound %s method' % self.classlink(imclass,mod)
Christian Heimesff737952007-11-27 10:40:20 +0000859 object = object.__func__
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000860
861 if name == realname:
862 title = '<a name="%s"><strong>%s</strong></a>' % (anchor, realname)
863 else:
Raymond Hettinger54f02222002-06-01 14:18:47 +0000864 if (cl and realname in cl.__dict__ and
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000865 cl.__dict__[realname] is object):
Ka-Ping Yeee280c062001-03-23 14:05:53 +0000866 reallink = '<a href="#%s">%s</a>' % (
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000867 cl.__name__ + '-' + realname, realname)
868 skipdocs = 1
869 else:
870 reallink = realname
871 title = '<a name="%s"><strong>%s</strong></a> = %s' % (
872 anchor, name, reallink)
Tim Peters4bcfa312001-09-20 06:08:24 +0000873 if inspect.isfunction(object):
Guido van Rossum2e65f892007-02-28 22:03:49 +0000874 args, varargs, kwonlyargs, kwdefaults, varkw, defaults, ann = \
875 inspect.getfullargspec(object)
Ka-Ping Yee66efbc72001-03-01 13:55:20 +0000876 argspec = inspect.formatargspec(
Guido van Rossum2e65f892007-02-28 22:03:49 +0000877 args, varargs, kwonlyargs, kwdefaults, varkw, defaults, ann,
878 formatvalue=self.formatvalue,
879 formatannotation=inspect.formatannotationrelativeto(object))
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000880 if realname == '<lambda>':
Tim Peters59ed4482001-10-31 04:20:26 +0000881 title = '<strong>%s</strong> <em>lambda</em> ' % name
Guido van Rossum2e65f892007-02-28 22:03:49 +0000882 # XXX lambda's won't usually have func_annotations['return']
883 # since the syntax doesn't support but it is possible.
884 # So removing parentheses isn't truly safe.
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000885 argspec = argspec[1:-1] # remove parentheses
Tim Peters4bcfa312001-09-20 06:08:24 +0000886 else:
887 argspec = '(...)'
Ka-Ping Yee66efbc72001-03-01 13:55:20 +0000888
Tim Peters2306d242001-09-25 03:18:32 +0000889 decl = title + argspec + (note and self.grey(
890 '<font face="helvetica, arial">%s</font>' % note))
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000891
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000892 if skipdocs:
Tim Peters2306d242001-09-25 03:18:32 +0000893 return '<dl><dt>%s</dt></dl>\n' % decl
Ka-Ping Yee3bda8792001-03-23 13:17:50 +0000894 else:
895 doc = self.markup(
896 getdoc(object), self.preformat, funcs, classes, methods)
Tim Peters2306d242001-09-25 03:18:32 +0000897 doc = doc and '<dd><tt>%s</tt></dd>' % doc
898 return '<dl><dt>%s</dt>%s</dl>\n' % (decl, doc)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000899
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +0000900 def _docdescriptor(self, name, value, mod):
Johannes Gijsbers8de645a2004-11-07 19:16:05 +0000901 results = []
902 push = results.append
903
904 if name:
905 push('<dl><dt><strong>%s</strong></dt>\n' % name)
906 if value.__doc__ is not None:
Ka-Ping Yeebba6acc2005-02-19 22:58:26 +0000907 doc = self.markup(getdoc(value), self.preformat)
Johannes Gijsbers8de645a2004-11-07 19:16:05 +0000908 push('<dd><tt>%s</tt></dd>\n' % doc)
Johannes Gijsbers8de645a2004-11-07 19:16:05 +0000909 push('</dl>\n')
910
911 return ''.join(results)
912
913 def docproperty(self, object, name=None, mod=None, cl=None):
914 """Produce html documentation for a property."""
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +0000915 return self._docdescriptor(name, object, mod)
Johannes Gijsbers8de645a2004-11-07 19:16:05 +0000916
Tim Peters8dd7ade2001-10-18 19:56:17 +0000917 def docother(self, object, name=None, mod=None, *ignored):
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000918 """Produce HTML documentation for a data object."""
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +0000919 lhs = name and '<strong>%s</strong> = ' % name or ''
920 return lhs + self.repr(object)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000921
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000922 def docdata(self, object, name=None, mod=None, cl=None):
923 """Produce html documentation for a data descriptor."""
924 return self._docdescriptor(name, object, mod)
925
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000926 def index(self, dir, shadowed=None):
927 """Generate an HTML index for a directory of modules."""
928 modpkgs = []
929 if shadowed is None: shadowed = {}
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000930 for importer, name, ispkg in pkgutil.iter_modules([dir]):
931 modpkgs.append((name, '', ispkg, name in shadowed))
932 shadowed[name] = 1
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000933
934 modpkgs.sort()
935 contents = self.multicolumn(modpkgs, self.modpkglink)
936 return self.bigsection(dir, '#ffffff', '#ee77aa', contents)
937
938# -------------------------------------------- text documentation generator
939
940class TextRepr(Repr):
941 """Class for safely making a text representation of a Python object."""
942 def __init__(self):
943 Repr.__init__(self)
Ka-Ping Yeedec96e92001-04-13 09:55:49 +0000944 self.maxlist = self.maxtuple = 20
945 self.maxdict = 10
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000946 self.maxstring = self.maxother = 100
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000947
948 def repr1(self, x, level):
Skip Montanaro0fe8fce2003-06-27 15:45:41 +0000949 if hasattr(type(x), '__name__'):
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000950 methodname = 'repr_' + '_'.join(type(x).__name__.split())
Skip Montanaro0fe8fce2003-06-27 15:45:41 +0000951 if hasattr(self, methodname):
952 return getattr(self, methodname)(x, level)
953 return cram(stripid(repr(x)), self.maxother)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000954
Ka-Ping Yeea2fe1032001-03-02 01:19:14 +0000955 def repr_string(self, x, level):
956 test = cram(x, self.maxstring)
957 testrepr = repr(test)
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +0000958 if '\\' in test and '\\' not in replace(testrepr, r'\\', ''):
Ka-Ping Yeea2fe1032001-03-02 01:19:14 +0000959 # Backslashes are only literal in the string and are never
960 # needed to make any special characters, so show a raw string.
961 return 'r' + testrepr[0] + test + testrepr[0]
962 return testrepr
963
Skip Montanarodf708782002-03-07 22:58:02 +0000964 repr_str = repr_string
965
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000966 def repr_instance(self, x, level):
967 try:
Ka-Ping Yee1d384632001-03-01 00:24:32 +0000968 return cram(stripid(repr(x)), self.maxstring)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000969 except:
970 return '<%s instance>' % x.__class__.__name__
971
972class TextDoc(Doc):
973 """Formatter class for text documentation."""
974
975 # ------------------------------------------- text formatting utilities
976
977 _repr_instance = TextRepr()
978 repr = _repr_instance.repr
979
980 def bold(self, text):
981 """Format a string in bold by overstriking."""
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000982 return ''.join(map(lambda ch: ch + '\b' + ch, text))
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000983
984 def indent(self, text, prefix=' '):
985 """Indent text by prepending a given prefix to each line."""
986 if not text: return ''
Collin Winter72e110c2007-07-17 00:27:30 +0000987 lines = [prefix + line for line in text.split('\n')]
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000988 if lines: lines[-1] = lines[-1].rstrip()
989 return '\n'.join(lines)
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000990
991 def section(self, title, contents):
992 """Format a section with a given heading."""
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000993 clean_contents = self.indent(contents).rstrip()
994 return self.bold(title) + '\n' + clean_contents + '\n\n'
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000995
996 # ---------------------------------------------- type-specific routines
997
Ka-Ping Yee37f7b382001-03-23 00:12:53 +0000998 def formattree(self, tree, modname, parent=None, prefix=''):
Ka-Ping Yeedd175342001-02-27 14:43:46 +0000999 """Render in text a class tree as returned by inspect.getclasstree()."""
1000 result = ''
1001 for entry in tree:
1002 if type(entry) is type(()):
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001003 c, bases = entry
1004 result = result + prefix + classname(c, modname)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001005 if bases and bases != (parent,):
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001006 parents = map(lambda c, m=modname: classname(c, m), bases)
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001007 result = result + '(%s)' % ', '.join(parents)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001008 result = result + '\n'
1009 elif type(entry) is type([]):
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001010 result = result + self.formattree(
1011 entry, modname, c, prefix + ' ')
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001012 return result
1013
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001014 def docmodule(self, object, name=None, mod=None):
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001015 """Produce text documentation for a given module object."""
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001016 name = object.__name__ # ignore the passed-in name
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +00001017 synop, desc = splitdoc(getdoc(object))
1018 result = self.section('NAME', name + (synop and ' - ' + synop))
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001019
1020 try:
Skip Montanaroa5616d22004-06-11 04:46:12 +00001021 all = object.__all__
1022 except AttributeError:
1023 all = None
1024
1025 try:
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001026 file = inspect.getabsfile(object)
1027 except TypeError:
1028 file = '(built-in)'
Ka-Ping Yee239432a2001-03-02 02:45:08 +00001029 result = result + self.section('FILE', file)
Skip Montanaro4997a692003-09-10 16:47:51 +00001030
1031 docloc = self.getdocloc(object)
1032 if docloc is not None:
1033 result = result + self.section('MODULE DOCS', docloc)
1034
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +00001035 if desc:
1036 result = result + self.section('DESCRIPTION', desc)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001037
1038 classes = []
1039 for key, value in inspect.getmembers(object, inspect.isclass):
Johannes Gijsbers4c11f602004-08-30 14:13:04 +00001040 # if __all__ exists, believe it. Otherwise use old heuristic.
1041 if (all is not None
1042 or (inspect.getmodule(value) or object) is object):
Skip Montanaroa5616d22004-06-11 04:46:12 +00001043 if visiblename(key, all):
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +00001044 classes.append((key, value))
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001045 funcs = []
1046 for key, value in inspect.getmembers(object, inspect.isroutine):
Johannes Gijsbers4c11f602004-08-30 14:13:04 +00001047 # if __all__ exists, believe it. Otherwise use old heuristic.
1048 if (all is not None or
1049 inspect.isbuiltin(value) or inspect.getmodule(value) is object):
Skip Montanaroa5616d22004-06-11 04:46:12 +00001050 if visiblename(key, all):
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +00001051 funcs.append((key, value))
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001052 data = []
1053 for key, value in inspect.getmembers(object, isdata):
Skip Montanaroa5616d22004-06-11 04:46:12 +00001054 if visiblename(key, all):
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001055 data.append((key, value))
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001056
Christian Heimes1af737c2008-01-23 08:24:23 +00001057 modpkgs = []
1058 modpkgs_names = set()
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001059 if hasattr(object, '__path__'):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001060 for importer, modname, ispkg in pkgutil.iter_modules(object.__path__):
Christian Heimes1af737c2008-01-23 08:24:23 +00001061 modpkgs_names.add(modname)
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001062 if ispkg:
1063 modpkgs.append(modname + ' (package)')
1064 else:
1065 modpkgs.append(modname)
1066
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001067 modpkgs.sort()
1068 result = result + self.section(
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001069 'PACKAGE CONTENTS', '\n'.join(modpkgs))
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001070
Christian Heimes1af737c2008-01-23 08:24:23 +00001071 # Detect submodules as sometimes created by C extensions
1072 submodules = []
1073 for key, value in inspect.getmembers(object, inspect.ismodule):
1074 if value.__name__.startswith(name + '.') and key not in modpkgs_names:
1075 submodules.append(key)
1076 if submodules:
1077 submodules.sort()
1078 result = result + self.section(
Amaury Forgeot d'Arc768db922008-04-24 21:00:04 +00001079 'SUBMODULES', '\n'.join(submodules))
Christian Heimes1af737c2008-01-23 08:24:23 +00001080
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001081 if classes:
Guido van Rossum1bc535d2007-05-15 18:46:22 +00001082 classlist = [value for key, value in classes]
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001083 contents = [self.formattree(
1084 inspect.getclasstree(classlist, 1), name)]
1085 for key, value in classes:
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001086 contents.append(self.document(value, key, name))
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001087 result = result + self.section('CLASSES', '\n'.join(contents))
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001088
1089 if funcs:
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001090 contents = []
1091 for key, value in funcs:
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001092 contents.append(self.document(value, key, name))
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001093 result = result + self.section('FUNCTIONS', '\n'.join(contents))
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001094
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001095 if data:
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001096 contents = []
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001097 for key, value in data:
Georg Brandl8b813db2005-10-01 16:32:31 +00001098 contents.append(self.docother(value, key, name, maxlen=70))
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001099 result = result + self.section('DATA', '\n'.join(contents))
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001100
1101 if hasattr(object, '__version__'):
1102 version = str(object.__version__)
Ka-Ping Yee1d384632001-03-01 00:24:32 +00001103 if version[:11] == '$' + 'Revision: ' and version[-1:] == '$':
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001104 version = version[11:-1].strip()
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001105 result = result + self.section('VERSION', version)
Ka-Ping Yee6f3f9a42001-02-27 22:42:36 +00001106 if hasattr(object, '__date__'):
1107 result = result + self.section('DATE', str(object.__date__))
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001108 if hasattr(object, '__author__'):
Ka-Ping Yee6f3f9a42001-02-27 22:42:36 +00001109 result = result + self.section('AUTHOR', str(object.__author__))
1110 if hasattr(object, '__credits__'):
1111 result = result + self.section('CREDITS', str(object.__credits__))
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001112 return result
1113
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001114 def docclass(self, object, name=None, mod=None):
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001115 """Produce text documentation for a given class object."""
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001116 realname = object.__name__
1117 name = name or realname
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001118 bases = object.__bases__
1119
Tim Petersc86f6ca2001-09-26 21:31:51 +00001120 def makename(c, m=object.__module__):
1121 return classname(c, m)
1122
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001123 if name == realname:
1124 title = 'class ' + self.bold(realname)
1125 else:
1126 title = self.bold(name) + ' = class ' + realname
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001127 if bases:
Ka-Ping Yee3bda8792001-03-23 13:17:50 +00001128 parents = map(makename, bases)
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001129 title = title + '(%s)' % ', '.join(parents)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001130
1131 doc = getdoc(object)
Tim Peters28355492001-09-23 21:29:55 +00001132 contents = doc and [doc + '\n'] or []
1133 push = contents.append
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001134
Tim Petersc86f6ca2001-09-26 21:31:51 +00001135 # List the mro, if non-trivial.
Raymond Hettinger756b3f32004-01-29 06:37:52 +00001136 mro = deque(inspect.getmro(object))
Tim Petersc86f6ca2001-09-26 21:31:51 +00001137 if len(mro) > 2:
1138 push("Method resolution order:")
1139 for base in mro:
1140 push(' ' + makename(base))
1141 push('')
1142
Tim Petersf4aad8e2001-09-24 22:40:47 +00001143 # Cute little class to pump out a horizontal rule between sections.
1144 class HorizontalRule:
1145 def __init__(self):
1146 self.needone = 0
1147 def maybe(self):
1148 if self.needone:
1149 push('-' * 70)
1150 self.needone = 1
1151 hr = HorizontalRule()
1152
Tim Peters28355492001-09-23 21:29:55 +00001153 def spill(msg, attrs, predicate):
Tim Petersfa26f7c2001-09-24 08:05:11 +00001154 ok, attrs = _split_list(attrs, predicate)
Tim Peters28355492001-09-23 21:29:55 +00001155 if ok:
Tim Petersf4aad8e2001-09-24 22:40:47 +00001156 hr.maybe()
Tim Peters28355492001-09-23 21:29:55 +00001157 push(msg)
1158 for name, kind, homecls, value in ok:
1159 push(self.document(getattr(object, name),
1160 name, mod, object))
1161 return attrs
1162
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +00001163 def spilldescriptors(msg, attrs, predicate):
Tim Petersfa26f7c2001-09-24 08:05:11 +00001164 ok, attrs = _split_list(attrs, predicate)
Tim Peters28355492001-09-23 21:29:55 +00001165 if ok:
Tim Petersf4aad8e2001-09-24 22:40:47 +00001166 hr.maybe()
Tim Peters28355492001-09-23 21:29:55 +00001167 push(msg)
1168 for name, kind, homecls, value in ok:
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +00001169 push(self._docdescriptor(name, value, mod))
Tim Peters28355492001-09-23 21:29:55 +00001170 return attrs
Tim Petersb47879b2001-09-24 04:47:19 +00001171
Tim Petersfa26f7c2001-09-24 08:05:11 +00001172 def spilldata(msg, attrs, predicate):
1173 ok, attrs = _split_list(attrs, predicate)
Tim Peters28355492001-09-23 21:29:55 +00001174 if ok:
Tim Petersf4aad8e2001-09-24 22:40:47 +00001175 hr.maybe()
Tim Peters28355492001-09-23 21:29:55 +00001176 push(msg)
1177 for name, kind, homecls, value in ok:
Guido van Rossumd59da4b2007-05-22 18:11:13 +00001178 if hasattr(value, '__call__') or inspect.isdatadescriptor(value):
Ka-Ping Yeebba6acc2005-02-19 22:58:26 +00001179 doc = getdoc(value)
Guido van Rossum5e355b22002-05-21 20:56:15 +00001180 else:
1181 doc = None
Tim Peters28355492001-09-23 21:29:55 +00001182 push(self.docother(getattr(object, name),
Georg Brandl8b813db2005-10-01 16:32:31 +00001183 name, mod, maxlen=70, doc=doc) + '\n')
Tim Peters28355492001-09-23 21:29:55 +00001184 return attrs
1185
Guido van Rossum1bc535d2007-05-15 18:46:22 +00001186 attrs = [(name, kind, cls, value)
1187 for name, kind, cls, value in classify_class_attrs(object)
1188 if visiblename(name)]
1189
Tim Petersfa26f7c2001-09-24 08:05:11 +00001190 while attrs:
Tim Peters351e3622001-09-27 03:29:51 +00001191 if mro:
Raymond Hettinger756b3f32004-01-29 06:37:52 +00001192 thisclass = mro.popleft()
Tim Peters351e3622001-09-27 03:29:51 +00001193 else:
1194 thisclass = attrs[0][2]
Tim Petersfa26f7c2001-09-24 08:05:11 +00001195 attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass)
1196
Georg Brandl1a3284e2007-12-02 09:40:06 +00001197 if thisclass is builtins.object:
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +00001198 attrs = inherited
1199 continue
1200 elif thisclass is object:
Tim Peters28355492001-09-23 21:29:55 +00001201 tag = "defined here"
1202 else:
Tim Petersfa26f7c2001-09-24 08:05:11 +00001203 tag = "inherited from %s" % classname(thisclass,
1204 object.__module__)
Tim Peters28355492001-09-23 21:29:55 +00001205
1206 # Sort attrs by name.
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +00001207 attrs.sort()
Tim Peters28355492001-09-23 21:29:55 +00001208
1209 # Pump out the attrs, segregated by kind.
Tim Petersf4aad8e2001-09-24 22:40:47 +00001210 attrs = spill("Methods %s:\n" % tag, attrs,
Tim Peters28355492001-09-23 21:29:55 +00001211 lambda t: t[1] == 'method')
Tim Petersf4aad8e2001-09-24 22:40:47 +00001212 attrs = spill("Class methods %s:\n" % tag, attrs,
Tim Peters28355492001-09-23 21:29:55 +00001213 lambda t: t[1] == 'class method')
Tim Petersf4aad8e2001-09-24 22:40:47 +00001214 attrs = spill("Static methods %s:\n" % tag, attrs,
Tim Peters28355492001-09-23 21:29:55 +00001215 lambda t: t[1] == 'static method')
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +00001216 attrs = spilldescriptors("Data descriptors %s:\n" % tag, attrs,
1217 lambda t: t[1] == 'data descriptor')
Ka-Ping Yeed9e213e2003-03-28 16:35:51 +00001218 attrs = spilldata("Data and other attributes %s:\n" % tag, attrs,
1219 lambda t: t[1] == 'data')
Tim Peters28355492001-09-23 21:29:55 +00001220 assert attrs == []
Tim Peters351e3622001-09-27 03:29:51 +00001221 attrs = inherited
Tim Peters28355492001-09-23 21:29:55 +00001222
1223 contents = '\n'.join(contents)
1224 if not contents:
1225 return title + '\n'
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001226 return title + '\n' + self.indent(contents.rstrip(), ' | ') + '\n'
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001227
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001228 def formatvalue(self, object):
1229 """Format an argument default value as text."""
1230 return '=' + self.repr(object)
1231
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001232 def docroutine(self, object, name=None, mod=None, cl=None):
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00001233 """Produce text documentation for a function or method object."""
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001234 realname = object.__name__
1235 name = name or realname
1236 note = ''
Ka-Ping Yee3bda8792001-03-23 13:17:50 +00001237 skipdocs = 0
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001238 if inspect.ismethod(object):
Christian Heimesff737952007-11-27 10:40:20 +00001239 imclass = object.__self__.__class__
Ka-Ping Yee3bda8792001-03-23 13:17:50 +00001240 if cl:
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001241 if imclass is not cl:
1242 note = ' from ' + classname(imclass, mod)
Ka-Ping Yee3bda8792001-03-23 13:17:50 +00001243 else:
Christian Heimesff737952007-11-27 10:40:20 +00001244 if object.__self__ is not None:
Ka-Ping Yeeb7a48302001-04-12 20:39:14 +00001245 note = ' method of %s instance' % classname(
Christian Heimesff737952007-11-27 10:40:20 +00001246 object.__self__.__class__, mod)
Ka-Ping Yeeb7a48302001-04-12 20:39:14 +00001247 else:
1248 note = ' unbound %s method' % classname(imclass,mod)
Christian Heimesff737952007-11-27 10:40:20 +00001249 object = object.__func__
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001250
1251 if name == realname:
1252 title = self.bold(realname)
1253 else:
Raymond Hettinger54f02222002-06-01 14:18:47 +00001254 if (cl and realname in cl.__dict__ and
Ka-Ping Yee3bda8792001-03-23 13:17:50 +00001255 cl.__dict__[realname] is object):
1256 skipdocs = 1
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001257 title = self.bold(name) + ' = ' + realname
Tim Peters4bcfa312001-09-20 06:08:24 +00001258 if inspect.isfunction(object):
Guido van Rossum2e65f892007-02-28 22:03:49 +00001259 args, varargs, varkw, defaults, kwonlyargs, kwdefaults, ann = \
1260 inspect.getfullargspec(object)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001261 argspec = inspect.formatargspec(
Guido van Rossum2e65f892007-02-28 22:03:49 +00001262 args, varargs, varkw, defaults, kwonlyargs, kwdefaults, ann,
1263 formatvalue=self.formatvalue,
1264 formatannotation=inspect.formatannotationrelativeto(object))
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001265 if realname == '<lambda>':
Georg Brandl501dd0d2006-02-17 09:45:40 +00001266 title = self.bold(name) + ' lambda '
Guido van Rossum2e65f892007-02-28 22:03:49 +00001267 # XXX lambda's won't usually have func_annotations['return']
1268 # since the syntax doesn't support but it is possible.
1269 # So removing parentheses isn't truly safe.
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001270 argspec = argspec[1:-1] # remove parentheses
Tim Peters4bcfa312001-09-20 06:08:24 +00001271 else:
1272 argspec = '(...)'
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001273 decl = title + argspec + note
1274
Ka-Ping Yee3bda8792001-03-23 13:17:50 +00001275 if skipdocs:
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001276 return decl + '\n'
Ka-Ping Yee3bda8792001-03-23 13:17:50 +00001277 else:
1278 doc = getdoc(object) or ''
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001279 return decl + '\n' + (doc and self.indent(doc).rstrip() + '\n')
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001280
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +00001281 def _docdescriptor(self, name, value, mod):
Johannes Gijsbers8de645a2004-11-07 19:16:05 +00001282 results = []
1283 push = results.append
1284
1285 if name:
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +00001286 push(self.bold(name))
1287 push('\n')
Johannes Gijsbers8de645a2004-11-07 19:16:05 +00001288 doc = getdoc(value) or ''
1289 if doc:
1290 push(self.indent(doc))
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +00001291 push('\n')
1292 return ''.join(results)
Johannes Gijsbers8de645a2004-11-07 19:16:05 +00001293
1294 def docproperty(self, object, name=None, mod=None, cl=None):
1295 """Produce text documentation for a property."""
Johannes Gijsbers9ddb3002005-01-08 20:16:43 +00001296 return self._docdescriptor(name, object, mod)
Johannes Gijsbers8de645a2004-11-07 19:16:05 +00001297
Thomas Wouters0e3f5912006-08-11 14:57:12 +00001298 def docdata(self, object, name=None, mod=None, cl=None):
1299 """Produce text documentation for a data descriptor."""
1300 return self._docdescriptor(name, object, mod)
1301
Georg Brandl8b813db2005-10-01 16:32:31 +00001302 def docother(self, object, name=None, mod=None, parent=None, maxlen=None, doc=None):
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001303 """Produce text documentation for a data object."""
1304 repr = self.repr(object)
1305 if maxlen:
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001306 line = (name and name + ' = ' or '') + repr
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001307 chop = maxlen - len(line)
1308 if chop < 0: repr = repr[:chop] + '...'
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001309 line = (name and self.bold(name) + ' = ' or '') + repr
Tim Peters28355492001-09-23 21:29:55 +00001310 if doc is not None:
1311 line += '\n' + self.indent(str(doc))
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001312 return line
1313
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001314# --------------------------------------------------------- user interfaces
1315
1316def pager(text):
1317 """The first time this is called, determine what kind of pager to use."""
1318 global pager
1319 pager = getpager()
1320 pager(text)
1321
1322def getpager():
1323 """Decide what method to use for paging through text."""
Guido van Rossuma01a8b62007-05-27 09:20:14 +00001324 if not hasattr(sys.stdout, "isatty"):
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001325 return plainpager
1326 if not sys.stdin.isatty() or not sys.stdout.isatty():
1327 return plainpager
Raymond Hettinger54f02222002-06-01 14:18:47 +00001328 if 'PAGER' in os.environ:
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +00001329 if sys.platform == 'win32': # pipes completely broken in Windows
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001330 return lambda text: tempfilepager(plain(text), os.environ['PAGER'])
Raymond Hettingerdbecd932005-02-06 06:57:08 +00001331 elif os.environ.get('TERM') in ('dumb', 'emacs'):
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001332 return lambda text: pipepager(plain(text), os.environ['PAGER'])
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +00001333 else:
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001334 return lambda text: pipepager(text, os.environ['PAGER'])
Ka-Ping Yeea487e4e2005-11-05 04:49:18 +00001335 if os.environ.get('TERM') in ('dumb', 'emacs'):
1336 return plainpager
Andrew MacIntyre54e0eab2002-03-03 03:12:30 +00001337 if sys.platform == 'win32' or sys.platform.startswith('os2'):
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001338 return lambda text: tempfilepager(plain(text), 'more <')
Skip Montanarod404bee2002-09-26 21:44:57 +00001339 if hasattr(os, 'system') and os.system('(less) 2>/dev/null') == 0:
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001340 return lambda text: pipepager(text, 'less')
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001341
1342 import tempfile
Guido van Rossum3b0a3292002-08-09 16:38:32 +00001343 (fd, filename) = tempfile.mkstemp()
1344 os.close(fd)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001345 try:
Georg Brandl3dbca812008-07-23 16:10:53 +00001346 if hasattr(os, 'system') and os.system('more "%s"' % filename) == 0:
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001347 return lambda text: pipepager(text, 'more')
1348 else:
1349 return ttypager
1350 finally:
1351 os.unlink(filename)
1352
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001353def plain(text):
1354 """Remove boldface formatting from text."""
1355 return re.sub('.\b', '', text)
1356
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001357def pipepager(text, cmd):
1358 """Page through text by feeding it to another program."""
1359 pipe = os.popen(cmd, 'w')
1360 try:
1361 pipe.write(text)
1362 pipe.close()
1363 except IOError:
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001364 pass # Ignore broken pipes caused by quitting the pager program.
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001365
1366def tempfilepager(text, cmd):
1367 """Page through text by invoking a program on a temporary file."""
1368 import tempfile
Tim Peters550e4e52003-02-07 01:53:46 +00001369 filename = tempfile.mktemp()
1370 file = open(filename, 'w')
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001371 file.write(text)
1372 file.close()
1373 try:
Georg Brandl3dbca812008-07-23 16:10:53 +00001374 os.system(cmd + ' "' + filename + '"')
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001375 finally:
1376 os.unlink(filename)
1377
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001378def ttypager(text):
1379 """Page through text on a text terminal."""
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001380 lines = plain(text).split('\n')
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001381 try:
1382 import tty
1383 fd = sys.stdin.fileno()
1384 old = tty.tcgetattr(fd)
1385 tty.setcbreak(fd)
1386 getchar = lambda: sys.stdin.read(1)
Ka-Ping Yee457aab22001-02-27 23:36:29 +00001387 except (ImportError, AttributeError):
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001388 tty = None
1389 getchar = lambda: sys.stdin.readline()[:-1][:1]
1390
1391 try:
1392 r = inc = os.environ.get('LINES', 25) - 1
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001393 sys.stdout.write('\n'.join(lines[:inc]) + '\n')
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001394 while lines[r:]:
1395 sys.stdout.write('-- more --')
1396 sys.stdout.flush()
1397 c = getchar()
1398
Raymond Hettingerdbecd932005-02-06 06:57:08 +00001399 if c in ('q', 'Q'):
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001400 sys.stdout.write('\r \r')
1401 break
Raymond Hettingerdbecd932005-02-06 06:57:08 +00001402 elif c in ('\r', '\n'):
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001403 sys.stdout.write('\r \r' + lines[r] + '\n')
1404 r = r + 1
1405 continue
Raymond Hettingerdbecd932005-02-06 06:57:08 +00001406 if c in ('b', 'B', '\x1b'):
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001407 r = r - inc - inc
1408 if r < 0: r = 0
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001409 sys.stdout.write('\n' + '\n'.join(lines[r:r+inc]) + '\n')
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001410 r = r + inc
1411
1412 finally:
1413 if tty:
1414 tty.tcsetattr(fd, tty.TCSAFLUSH, old)
1415
1416def plainpager(text):
1417 """Simply print unformatted text. This is the ultimate fallback."""
1418 sys.stdout.write(plain(text))
1419
1420def describe(thing):
Ka-Ping Yee3bda8792001-03-23 13:17:50 +00001421 """Produce a short description of the given thing."""
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001422 if inspect.ismodule(thing):
1423 if thing.__name__ in sys.builtin_module_names:
1424 return 'built-in module ' + thing.__name__
1425 if hasattr(thing, '__path__'):
1426 return 'package ' + thing.__name__
1427 else:
1428 return 'module ' + thing.__name__
1429 if inspect.isbuiltin(thing):
1430 return 'built-in function ' + thing.__name__
Thomas Wouters0e3f5912006-08-11 14:57:12 +00001431 if inspect.isgetsetdescriptor(thing):
1432 return 'getset descriptor %s.%s.%s' % (
1433 thing.__objclass__.__module__, thing.__objclass__.__name__,
1434 thing.__name__)
1435 if inspect.ismemberdescriptor(thing):
1436 return 'member descriptor %s.%s.%s' % (
1437 thing.__objclass__.__module__, thing.__objclass__.__name__,
1438 thing.__name__)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001439 if inspect.isclass(thing):
1440 return 'class ' + thing.__name__
1441 if inspect.isfunction(thing):
1442 return 'function ' + thing.__name__
1443 if inspect.ismethod(thing):
1444 return 'method ' + thing.__name__
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001445 return type(thing).__name__
1446
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001447def locate(path, forceload=0):
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001448 """Locate an object by name or dotted path, importing as necessary."""
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001449 parts = [part for part in path.split('.') if part]
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001450 module, n = None, 0
1451 while n < len(parts):
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001452 nextmodule = safeimport('.'.join(parts[:n+1]), forceload)
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001453 if nextmodule: module, n = nextmodule, n + 1
1454 else: break
1455 if module:
1456 object = module
1457 for part in parts[n:]:
1458 try: object = getattr(object, part)
1459 except AttributeError: return None
1460 return object
1461 else:
Georg Brandl1a3284e2007-12-02 09:40:06 +00001462 if hasattr(builtins, path):
1463 return getattr(builtins, path)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001464
1465# --------------------------------------- interactive interpreter interface
1466
1467text = TextDoc()
1468html = HTMLDoc()
1469
Ka-Ping Yee45daeb02002-08-11 15:11:33 +00001470def 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:
Collin Winterce36ad82007-08-30 01:19:48 +00001475 raise ImportError('no Python documentation found for %r' % thing)
Ka-Ping Yee45daeb02002-08-11 15:11:33 +00001476 return object, thing
1477 else:
1478 return thing, getattr(thing, '__name__', None)
1479
Guido van Rossumd8faa362007-04-27 19:54:29 +00001480def 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__
Amaury Forgeot d'Arc768db922008-04-24 21:00:04 +00001489
1490 if not (inspect.ismodule(object) or
Guido van Rossumd8faa362007-04-27 19:54:29 +00001491 inspect.isclass(object) or
1492 inspect.isroutine(object) or
1493 inspect.isgetsetdescriptor(object) or
1494 inspect.ismemberdescriptor(object) or
1495 isinstance(object, property)):
1496 # If the passed object is a piece of data or an instance,
1497 # document its available methods instead of its value.
1498 object = type(object)
1499 desc += ' object'
1500 return title % desc + '\n\n' + text.document(object, name)
1501
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001502def doc(thing, title='Python Library Documentation: %s', forceload=0):
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001503 """Display text documentation, given an object or a path to an object."""
Ka-Ping Yee45daeb02002-08-11 15:11:33 +00001504 try:
Guido van Rossumd8faa362007-04-27 19:54:29 +00001505 pager(render_doc(thing, title, forceload))
Guido van Rossumb940e112007-01-10 16:19:56 +00001506 except (ImportError, ErrorDuringImport) as value:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001507 print(value)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001508
Ka-Ping Yee45daeb02002-08-11 15:11:33 +00001509def writedoc(thing, forceload=0):
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001510 """Write HTML documentation to a file in the current directory."""
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001511 try:
Ka-Ping Yee45daeb02002-08-11 15:11:33 +00001512 object, name = resolve(thing, forceload)
1513 page = html.page(describe(object), html.document(object, name))
Georg Brandl388faac2009-04-10 08:31:48 +00001514 file = open(name + '.html', 'w', encoding='utf-8')
Ka-Ping Yee45daeb02002-08-11 15:11:33 +00001515 file.write(page)
1516 file.close()
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001517 print('wrote', name + '.html')
Guido van Rossumb940e112007-01-10 16:19:56 +00001518 except (ImportError, ErrorDuringImport) as value:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001519 print(value)
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001520
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001521def writedocs(dir, pkgpath='', done=None):
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001522 """Write out HTML documentation for all modules in a directory tree."""
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001523 if done is None: done = {}
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001524 for importer, modname, ispkg in pkgutil.walk_packages([dir], pkgpath):
1525 writedoc(modname)
1526 return
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001527
1528class Helper:
Georg Brandl6b38daa2008-06-01 21:05:17 +00001529
1530 # These dictionaries map a topic name to either an alias, or a tuple
1531 # (label, seealso-items). The "label" is the label of the corresponding
1532 # section in the .rst file under Doc/ and an index into the dictionary
Georg Brandl5617db82009-04-27 16:28:57 +00001533 # in pydoc_data/topics.py.
Georg Brandl6b38daa2008-06-01 21:05:17 +00001534 #
1535 # CAUTION: if you change one of these dictionaries, be sure to adapt the
1536 # list of needed labels in Doc/tools/sphinxext/pyspecific.py and
Georg Brandl5617db82009-04-27 16:28:57 +00001537 # regenerate the pydoc_data/topics.py file by running
Georg Brandl6b38daa2008-06-01 21:05:17 +00001538 # make pydoc-topics
1539 # in Doc/ and copying the output file into the Lib/ directory.
1540
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001541 keywords = {
1542 'and': 'BOOLEAN',
Guido van Rossumd8faa362007-04-27 19:54:29 +00001543 'as': 'with',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001544 'assert': ('assert', ''),
1545 'break': ('break', 'while for'),
1546 'class': ('class', 'CLASSES SPECIALMETHODS'),
1547 'continue': ('continue', 'while for'),
1548 'def': ('function', ''),
1549 'del': ('del', 'BASICMETHODS'),
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001550 'elif': 'if',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001551 'else': ('else', 'while for'),
Georg Brandl0d855392008-08-30 19:53:05 +00001552 'except': 'try',
1553 'finally': 'try',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001554 'for': ('for', 'break continue while'),
Georg Brandl0d855392008-08-30 19:53:05 +00001555 'from': 'import',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001556 'global': ('global', 'NAMESPACES'),
1557 'if': ('if', 'TRUTHVALUE'),
1558 'import': ('import', 'MODULES'),
Georg Brandl22fff432009-10-27 20:19:02 +00001559 'in': ('in', 'SEQUENCEMETHODS'),
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001560 'is': 'COMPARISON',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001561 'lambda': ('lambda', 'FUNCTIONS'),
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001562 'not': 'BOOLEAN',
1563 'or': 'BOOLEAN',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001564 'pass': ('pass', ''),
1565 'raise': ('raise', 'EXCEPTIONS'),
1566 'return': ('return', 'FUNCTIONS'),
1567 'try': ('try', 'EXCEPTIONS'),
1568 'while': ('while', 'break continue if TRUTHVALUE'),
1569 'with': ('with', 'CONTEXTMANAGERS EXCEPTIONS yield'),
1570 'yield': ('yield', ''),
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001571 }
Georg Brandldb7b6b92009-01-01 15:53:14 +00001572 # Either add symbols to this dictionary or to the symbols dictionary
1573 # directly: Whichever is easier. They are merged later.
1574 _symbols_inverse = {
1575 'STRINGS' : ("'", "'''", "r'", "b'", '"""', '"', 'r"', 'b"'),
1576 'OPERATORS' : ('+', '-', '*', '**', '/', '//', '%', '<<', '>>', '&',
1577 '|', '^', '~', '<', '>', '<=', '>=', '==', '!=', '<>'),
1578 'COMPARISON' : ('<', '>', '<=', '>=', '==', '!=', '<>'),
1579 'UNARY' : ('-', '~'),
1580 'AUGMENTEDASSIGNMENT' : ('+=', '-=', '*=', '/=', '%=', '&=', '|=',
1581 '^=', '<<=', '>>=', '**=', '//='),
1582 'BITWISE' : ('<<', '>>', '&', '|', '^', '~'),
1583 'COMPLEX' : ('j', 'J')
1584 }
1585 symbols = {
1586 '%': 'OPERATORS FORMATTING',
1587 '**': 'POWER',
1588 ',': 'TUPLES LISTS FUNCTIONS',
1589 '.': 'ATTRIBUTES FLOAT MODULES OBJECTS',
1590 '...': 'ELLIPSIS',
1591 ':': 'SLICINGS DICTIONARYLITERALS',
1592 '@': 'def class',
1593 '\\': 'STRINGS',
1594 '_': 'PRIVATENAMES',
1595 '__': 'PRIVATENAMES SPECIALMETHODS',
1596 '`': 'BACKQUOTES',
1597 '(': 'TUPLES FUNCTIONS CALLS',
1598 ')': 'TUPLES FUNCTIONS CALLS',
1599 '[': 'LISTS SUBSCRIPTS SLICINGS',
1600 ']': 'LISTS SUBSCRIPTS SLICINGS'
1601 }
1602 for topic, symbols_ in _symbols_inverse.items():
1603 for symbol in symbols_:
1604 topics = symbols.get(symbol, topic)
1605 if topic not in topics:
1606 topics = topics + ' ' + topic
1607 symbols[symbol] = topics
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001608
1609 topics = {
Georg Brandl6b38daa2008-06-01 21:05:17 +00001610 'TYPES': ('types', 'STRINGS UNICODE NUMBERS SEQUENCES MAPPINGS '
1611 'FUNCTIONS CLASSES MODULES FILES inspect'),
1612 'STRINGS': ('strings', 'str UNICODE SEQUENCES STRINGMETHODS '
1613 'FORMATTING TYPES'),
1614 'STRINGMETHODS': ('string-methods', 'STRINGS FORMATTING'),
1615 'FORMATTING': ('formatstrings', 'OPERATORS'),
1616 'UNICODE': ('strings', 'encodings unicode SEQUENCES STRINGMETHODS '
1617 'FORMATTING TYPES'),
1618 'NUMBERS': ('numbers', 'INTEGER FLOAT COMPLEX TYPES'),
1619 'INTEGER': ('integers', 'int range'),
1620 'FLOAT': ('floating', 'float math'),
1621 'COMPLEX': ('imaginary', 'complex cmath'),
1622 'SEQUENCES': ('typesseq', 'STRINGMETHODS FORMATTING range LISTS'),
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001623 'MAPPINGS': 'DICTIONARIES',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001624 'FUNCTIONS': ('typesfunctions', 'def TYPES'),
1625 'METHODS': ('typesmethods', 'class def CLASSES TYPES'),
1626 'CODEOBJECTS': ('bltin-code-objects', 'compile FUNCTIONS TYPES'),
1627 'TYPEOBJECTS': ('bltin-type-objects', 'types TYPES'),
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001628 'FRAMEOBJECTS': 'TYPES',
1629 'TRACEBACKS': 'TYPES',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001630 'NONE': ('bltin-null-object', ''),
1631 'ELLIPSIS': ('bltin-ellipsis-object', 'SLICINGS'),
1632 'FILES': ('bltin-file-objects', ''),
1633 'SPECIALATTRIBUTES': ('specialattrs', ''),
1634 'CLASSES': ('types', 'class SPECIALMETHODS PRIVATENAMES'),
1635 'MODULES': ('typesmodules', 'import'),
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001636 'PACKAGES': 'import',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001637 'EXPRESSIONS': ('operator-summary', 'lambda or and not in is BOOLEAN '
1638 'COMPARISON BITWISE SHIFTING BINARY FORMATTING POWER '
1639 'UNARY ATTRIBUTES SUBSCRIPTS SLICINGS CALLS TUPLES '
1640 'LISTS DICTIONARIES'),
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001641 'OPERATORS': 'EXPRESSIONS',
1642 'PRECEDENCE': 'EXPRESSIONS',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001643 'OBJECTS': ('objects', 'TYPES'),
1644 'SPECIALMETHODS': ('specialnames', 'BASICMETHODS ATTRIBUTEMETHODS '
Georg Brandl22fff432009-10-27 20:19:02 +00001645 'CALLABLEMETHODS SEQUENCEMETHODS MAPPINGMETHODS '
1646 'NUMBERMETHODS CLASSES'),
Mark Dickinsona56c4672009-01-27 18:17:45 +00001647 'BASICMETHODS': ('customization', 'hash repr str SPECIALMETHODS'),
Georg Brandl6b38daa2008-06-01 21:05:17 +00001648 'ATTRIBUTEMETHODS': ('attribute-access', 'ATTRIBUTES SPECIALMETHODS'),
1649 'CALLABLEMETHODS': ('callable-types', 'CALLS SPECIALMETHODS'),
Georg Brandl22fff432009-10-27 20:19:02 +00001650 'SEQUENCEMETHODS': ('sequence-types', 'SEQUENCES SEQUENCEMETHODS '
Georg Brandl6b38daa2008-06-01 21:05:17 +00001651 'SPECIALMETHODS'),
1652 'MAPPINGMETHODS': ('sequence-types', 'MAPPINGS SPECIALMETHODS'),
1653 'NUMBERMETHODS': ('numeric-types', 'NUMBERS AUGMENTEDASSIGNMENT '
1654 'SPECIALMETHODS'),
1655 'EXECUTION': ('execmodel', 'NAMESPACES DYNAMICFEATURES EXCEPTIONS'),
1656 'NAMESPACES': ('naming', 'global ASSIGNMENT DELETION DYNAMICFEATURES'),
1657 'DYNAMICFEATURES': ('dynamic-features', ''),
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001658 'SCOPING': 'NAMESPACES',
1659 'FRAMES': 'NAMESPACES',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001660 'EXCEPTIONS': ('exceptions', 'try except finally raise'),
1661 'CONVERSIONS': ('conversions', ''),
1662 'IDENTIFIERS': ('identifiers', 'keywords SPECIALIDENTIFIERS'),
1663 'SPECIALIDENTIFIERS': ('id-classes', ''),
1664 'PRIVATENAMES': ('atom-identifiers', ''),
1665 'LITERALS': ('atom-literals', 'STRINGS NUMBERS TUPLELITERALS '
1666 'LISTLITERALS DICTIONARYLITERALS'),
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001667 'TUPLES': 'SEQUENCES',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001668 'TUPLELITERALS': ('exprlists', 'TUPLES LITERALS'),
1669 'LISTS': ('typesseq-mutable', 'LISTLITERALS'),
1670 'LISTLITERALS': ('lists', 'LISTS LITERALS'),
1671 'DICTIONARIES': ('typesmapping', 'DICTIONARYLITERALS'),
1672 'DICTIONARYLITERALS': ('dict', 'DICTIONARIES LITERALS'),
1673 'ATTRIBUTES': ('attribute-references', 'getattr hasattr setattr ATTRIBUTEMETHODS'),
Georg Brandl22fff432009-10-27 20:19:02 +00001674 'SUBSCRIPTS': ('subscriptions', 'SEQUENCEMETHODS'),
1675 'SLICINGS': ('slicings', 'SEQUENCEMETHODS'),
Georg Brandl6b38daa2008-06-01 21:05:17 +00001676 'CALLS': ('calls', 'EXPRESSIONS'),
1677 'POWER': ('power', 'EXPRESSIONS'),
1678 'UNARY': ('unary', 'EXPRESSIONS'),
1679 'BINARY': ('binary', 'EXPRESSIONS'),
1680 'SHIFTING': ('shifting', 'EXPRESSIONS'),
1681 'BITWISE': ('bitwise', 'EXPRESSIONS'),
1682 'COMPARISON': ('comparisons', 'EXPRESSIONS BASICMETHODS'),
1683 'BOOLEAN': ('booleans', 'EXPRESSIONS TRUTHVALUE'),
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001684 'ASSERTION': 'assert',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001685 'ASSIGNMENT': ('assignment', 'AUGMENTEDASSIGNMENT'),
1686 'AUGMENTEDASSIGNMENT': ('augassign', 'NUMBERMETHODS'),
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001687 'DELETION': 'del',
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001688 'RETURNING': 'return',
1689 'IMPORTING': 'import',
1690 'CONDITIONAL': 'if',
Georg Brandl6b38daa2008-06-01 21:05:17 +00001691 'LOOPING': ('compound', 'for while break continue'),
1692 'TRUTHVALUE': ('truth', 'if while and or not BASICMETHODS'),
1693 'DEBUGGING': ('debugger', 'pdb'),
1694 'CONTEXTMANAGERS': ('context-managers', 'with'),
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001695 }
1696
Georg Brandle5d518f2010-08-01 19:09:07 +00001697 def __init__(self, input=None, output=None):
1698 self._input = input
1699 self._output = output
1700
1701 input = property(lambda self: self._input or sys.stdin)
1702 output = property(lambda self: self._output or sys.stdout)
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001703
Ka-Ping Yee79c009d2001-04-13 10:53:25 +00001704 def __repr__(self):
Ka-Ping Yee9bc576b2001-04-13 13:57:31 +00001705 if inspect.stack()[1][3] == '?':
Ka-Ping Yee79c009d2001-04-13 10:53:25 +00001706 self()
1707 return ''
Ka-Ping Yee9bc576b2001-04-13 13:57:31 +00001708 return '<pydoc.Helper instance>'
Ka-Ping Yee79c009d2001-04-13 10:53:25 +00001709
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001710 def __call__(self, request=None):
1711 if request is not None:
1712 self.help(request)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001713 else:
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001714 self.intro()
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001715 self.interact()
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001716 self.output.write('''
Fred Drakee61967f2001-05-10 18:41:02 +00001717You are now leaving help and returning to the Python interpreter.
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001718If you want to ask for help on a particular object directly from the
1719interpreter, you can type "help(object)". Executing "help('string')"
1720has the same effect as typing a particular string at the help> prompt.
1721''')
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001722
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001723 def interact(self):
1724 self.output.write('\n')
Guido van Rossum8ca162f2002-04-07 06:36:23 +00001725 while True:
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001726 try:
Johannes Gijsberse7691d32004-08-17 13:21:53 +00001727 request = self.getline('help> ')
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001728 if not request: break
Johannes Gijsberse7691d32004-08-17 13:21:53 +00001729 except (KeyboardInterrupt, EOFError):
1730 break
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001731 request = replace(request, '"', '', "'", '').strip()
1732 if request.lower() in ('q', 'quit'): break
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001733 self.help(request)
1734
Johannes Gijsberse7691d32004-08-17 13:21:53 +00001735 def getline(self, prompt):
Guido van Rossum7c086c02008-01-02 03:52:38 +00001736 """Read one line, using input() when appropriate."""
Johannes Gijsberse7691d32004-08-17 13:21:53 +00001737 if self.input is sys.stdin:
Guido van Rossum7c086c02008-01-02 03:52:38 +00001738 return input(prompt)
Johannes Gijsberse7691d32004-08-17 13:21:53 +00001739 else:
1740 self.output.write(prompt)
1741 self.output.flush()
1742 return self.input.readline()
1743
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001744 def help(self, request):
1745 if type(request) is type(''):
R. David Murray1f1b9d32009-05-27 20:56:59 +00001746 request = request.strip()
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001747 if request == 'help': self.intro()
1748 elif request == 'keywords': self.listkeywords()
Georg Brandldb7b6b92009-01-01 15:53:14 +00001749 elif request == 'symbols': self.listsymbols()
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001750 elif request == 'topics': self.listtopics()
1751 elif request == 'modules': self.listmodules()
1752 elif request[:8] == 'modules ':
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001753 self.listmodules(request.split()[1])
Georg Brandldb7b6b92009-01-01 15:53:14 +00001754 elif request in self.symbols: self.showsymbol(request)
Raymond Hettinger54f02222002-06-01 14:18:47 +00001755 elif request in self.keywords: self.showtopic(request)
1756 elif request in self.topics: self.showtopic(request)
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001757 elif request: doc(request, 'Help on %s:')
1758 elif isinstance(request, Helper): self()
1759 else: doc(request, 'Help on %s:')
1760 self.output.write('\n')
1761
1762 def intro(self):
1763 self.output.write('''
1764Welcome to Python %s! This is the online help utility.
1765
1766If this is your first time using Python, you should definitely check out
Georg Brandl86def6c2008-01-21 20:36:10 +00001767the tutorial on the Internet at http://docs.python.org/tutorial/.
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001768
1769Enter the name of any module, keyword, or topic to get help on writing
1770Python programs and using Python modules. To quit this help utility and
1771return to the interpreter, just type "quit".
1772
1773To get a list of available modules, keywords, or topics, type "modules",
1774"keywords", or "topics". Each module also comes with a one-line summary
1775of what it does; to list the modules whose summaries contain a given word
1776such as "spam", type "modules spam".
1777''' % sys.version[:3])
1778
1779 def list(self, items, columns=4, width=80):
Guido van Rossum486364b2007-06-30 05:01:58 +00001780 items = list(sorted(items))
1781 colw = width // columns
1782 rows = (len(items) + columns - 1) // columns
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001783 for row in range(rows):
1784 for col in range(columns):
1785 i = col * rows + row
1786 if i < len(items):
1787 self.output.write(items[i])
1788 if col < columns - 1:
Guido van Rossum486364b2007-06-30 05:01:58 +00001789 self.output.write(' ' + ' ' * (colw - 1 - len(items[i])))
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001790 self.output.write('\n')
1791
1792 def listkeywords(self):
1793 self.output.write('''
1794Here is a list of the Python keywords. Enter any keyword to get more help.
1795
1796''')
1797 self.list(self.keywords.keys())
1798
Georg Brandldb7b6b92009-01-01 15:53:14 +00001799 def listsymbols(self):
1800 self.output.write('''
1801Here is a list of the punctuation symbols which Python assigns special meaning
1802to. Enter any symbol to get more help.
1803
1804''')
1805 self.list(self.symbols.keys())
1806
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001807 def listtopics(self):
1808 self.output.write('''
1809Here is a list of available topics. Enter any topic name to get more help.
1810
1811''')
1812 self.list(self.topics.keys())
1813
Georg Brandldb7b6b92009-01-01 15:53:14 +00001814 def showtopic(self, topic, more_xrefs=''):
Georg Brandl6b38daa2008-06-01 21:05:17 +00001815 try:
Georg Brandl5617db82009-04-27 16:28:57 +00001816 import pydoc_data.topics
Georg Brandl6b38daa2008-06-01 21:05:17 +00001817 except ImportError:
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001818 self.output.write('''
Georg Brandl6b38daa2008-06-01 21:05:17 +00001819Sorry, topic and keyword documentation is not available because the
Georg Brandl5617db82009-04-27 16:28:57 +00001820module "pydoc_data.topics" could not be found.
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001821''')
1822 return
1823 target = self.topics.get(topic, self.keywords.get(topic))
1824 if not target:
1825 self.output.write('no documentation found for %s\n' % repr(topic))
1826 return
1827 if type(target) is type(''):
Georg Brandldb7b6b92009-01-01 15:53:14 +00001828 return self.showtopic(target, more_xrefs)
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001829
Georg Brandl6b38daa2008-06-01 21:05:17 +00001830 label, xrefs = target
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001831 try:
Georg Brandl5617db82009-04-27 16:28:57 +00001832 doc = pydoc_data.topics.topics[label]
Georg Brandl6b38daa2008-06-01 21:05:17 +00001833 except KeyError:
1834 self.output.write('no documentation found for %s\n' % repr(topic))
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001835 return
Georg Brandl6b38daa2008-06-01 21:05:17 +00001836 pager(doc.strip() + '\n')
Georg Brandldb7b6b92009-01-01 15:53:14 +00001837 if more_xrefs:
1838 xrefs = (xrefs or '') + ' ' + more_xrefs
Ka-Ping Yeeda793892001-04-13 11:02:51 +00001839 if xrefs:
Georg Brandl6b38daa2008-06-01 21:05:17 +00001840 import io, formatter
Guido van Rossum34d19282007-08-09 01:03:29 +00001841 buffer = io.StringIO()
Ka-Ping Yeeda793892001-04-13 11:02:51 +00001842 formatter.DumbWriter(buffer).send_flowing_data(
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001843 'Related help topics: ' + ', '.join(xrefs.split()) + '\n')
Ka-Ping Yeeda793892001-04-13 11:02:51 +00001844 self.output.write('\n%s\n' % buffer.getvalue())
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001845
Georg Brandldb7b6b92009-01-01 15:53:14 +00001846 def showsymbol(self, symbol):
1847 target = self.symbols[symbol]
1848 topic, _, xrefs = target.partition(' ')
1849 self.showtopic(topic, xrefs)
1850
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001851 def listmodules(self, key=''):
1852 if key:
1853 self.output.write('''
1854Here is a list of matching modules. Enter any module name to get more help.
1855
1856''')
1857 apropos(key)
1858 else:
1859 self.output.write('''
1860Please wait a moment while I gather a list of all available modules...
1861
1862''')
1863 modules = {}
1864 def callback(path, modname, desc, modules=modules):
1865 if modname and modname[-9:] == '.__init__':
1866 modname = modname[:-9] + ' (package)'
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001867 if modname.find('.') < 0:
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001868 modules[modname] = 1
Christian Heimesd32ed6f2008-01-14 18:49:24 +00001869 def onerror(modname):
1870 callback(None, modname, None)
1871 ModuleScanner().run(callback, onerror=onerror)
Ka-Ping Yee35cf0a32001-04-12 19:53:52 +00001872 self.list(modules.keys())
1873 self.output.write('''
1874Enter any module name to get more help. Or, type "modules spam" to search
1875for modules whose descriptions contain the word "spam".
1876''')
1877
Georg Brandle5d518f2010-08-01 19:09:07 +00001878help = Helper()
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001879
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00001880class Scanner:
1881 """A generic tree iterator."""
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001882 def __init__(self, roots, children, descendp):
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00001883 self.roots = roots[:]
1884 self.state = []
1885 self.children = children
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001886 self.descendp = descendp
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00001887
1888 def next(self):
1889 if not self.state:
1890 if not self.roots:
1891 return None
1892 root = self.roots.pop(0)
1893 self.state = [(root, self.children(root))]
1894 node, children = self.state[-1]
1895 if not children:
1896 self.state.pop()
1897 return self.next()
1898 child = children.pop(0)
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00001899 if self.descendp(child):
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00001900 self.state.append((child, self.children(child)))
1901 return child
1902
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001903
1904class ModuleScanner:
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00001905 """An interruptible scanner that searches module synopses."""
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00001906
Christian Heimesd32ed6f2008-01-14 18:49:24 +00001907 def run(self, callback, key=None, completer=None, onerror=None):
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001908 if key: key = key.lower()
Guido van Rossum8ca162f2002-04-07 06:36:23 +00001909 self.quit = False
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00001910 seen = {}
1911
1912 for modname in sys.builtin_module_names:
Ka-Ping Yee239432a2001-03-02 02:45:08 +00001913 if modname != '__main__':
1914 seen[modname] = 1
Ka-Ping Yee66246962001-04-12 11:59:50 +00001915 if key is None:
1916 callback(None, modname, '')
1917 else:
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001918 name = __import__(modname).__doc__ or ''
1919 desc = name.split('\n')[0]
1920 name = modname + ' - ' + desc
1921 if name.lower().find(key) >= 0:
Ka-Ping Yee66246962001-04-12 11:59:50 +00001922 callback(None, modname, desc)
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00001923
Christian Heimesd32ed6f2008-01-14 18:49:24 +00001924 for importer, modname, ispkg in pkgutil.walk_packages(onerror=onerror):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001925 if self.quit:
1926 break
1927 if key is None:
1928 callback(None, modname, '')
1929 else:
Georg Brandl126c8792009-04-05 15:05:48 +00001930 try:
1931 loader = importer.find_module(modname)
1932 except SyntaxError:
1933 # raised by tests for bad coding cookies or BOM
1934 continue
1935 if hasattr(loader, 'get_source'):
Amaury Forgeot d'Arc9196dc62008-06-19 20:54:32 +00001936 try:
1937 source = loader.get_source(modname)
1938 except UnicodeDecodeError:
1939 if onerror:
1940 onerror(modname)
1941 continue
Guido van Rossum34d19282007-08-09 01:03:29 +00001942 import io
Amaury Forgeot d'Arc9196dc62008-06-19 20:54:32 +00001943 desc = source_synopsis(io.StringIO(source)) or ''
Georg Brandl126c8792009-04-05 15:05:48 +00001944 if hasattr(loader, 'get_filename'):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001945 path = loader.get_filename(modname)
Ka-Ping Yee66246962001-04-12 11:59:50 +00001946 else:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001947 path = None
1948 else:
Amaury Forgeot d'Arc9196dc62008-06-19 20:54:32 +00001949 try:
1950 module = loader.load_module(modname)
1951 except ImportError:
1952 if onerror:
1953 onerror(modname)
1954 continue
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001955 desc = (module.__doc__ or '').splitlines()[0]
1956 path = getattr(module,'__file__',None)
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001957 name = modname + ' - ' + desc
1958 if name.lower().find(key) >= 0:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00001959 callback(path, modname, desc)
1960
1961 if completer:
1962 completer()
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001963
1964def apropos(key):
1965 """Print all the one-line module summaries that contain a substring."""
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00001966 def callback(path, modname, desc):
1967 if modname[-9:] == '.__init__':
1968 modname = modname[:-9] + ' (package)'
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001969 print(modname, desc and '- ' + desc)
Amaury Forgeot d'Arc9196dc62008-06-19 20:54:32 +00001970 def onerror(modname):
1971 pass
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +00001972 try: import warnings
1973 except ImportError: pass
1974 else: warnings.filterwarnings('ignore') # ignore problems during import
Amaury Forgeot d'Arc9196dc62008-06-19 20:54:32 +00001975 ModuleScanner().run(callback, key, onerror=onerror)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001976
1977# --------------------------------------------------- web browser interface
1978
Ka-Ping Yee66246962001-04-12 11:59:50 +00001979def serve(port, callback=None, completer=None):
Georg Brandl83e9f4c2008-06-12 18:52:31 +00001980 import http.server, email.message, select
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001981
Georg Brandl24420152008-05-26 16:32:26 +00001982 class DocHandler(http.server.BaseHTTPRequestHandler):
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001983 def send_document(self, title, contents):
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00001984 try:
1985 self.send_response(200)
Georg Brandl825fc8b2008-01-19 20:44:32 +00001986 self.send_header('Content-Type', 'text/html; charset=UTF-8')
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00001987 self.end_headers()
Georg Brandl825fc8b2008-01-19 20:44:32 +00001988 self.wfile.write(html.page(title, contents).encode('utf-8'))
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00001989 except IOError: pass
Ka-Ping Yeedd175342001-02-27 14:43:46 +00001990
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:
Ka-Ping Yeedec96e92001-04-13 09:55:49 +00001997 obj = locate(path, forceload=1)
Guido van Rossumb940e112007-01-10 16:19:56 +00001998 except ErrorDuringImport as value:
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00001999 self.send_document(path, html.escape(str(value)))
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002000 return
Ka-Ping Yee3bda8792001-03-23 13:17:50 +00002001 if obj:
2002 self.send_document(describe(obj), html.document(obj, path))
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002003 else:
2004 self.send_document(path,
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00002005'no Python documentation found for %s' % repr(path))
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002006 else:
2007 heading = html.heading(
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002008'<big><big><strong>Python: Index of Modules</strong></big></big>',
2009'#ffffff', '#7799ee')
Ka-Ping Yee239432a2001-03-02 02:45:08 +00002010 def bltinlink(name):
2011 return '<a href="%s.html">%s</a>' % (name, name)
Georg Brandl661b0a12008-01-27 18:16:00 +00002012 names = [x for x in sys.builtin_module_names if x != '__main__']
2013 contents = html.multicolumn(names, bltinlink)
Ka-Ping Yee239432a2001-03-02 02:45:08 +00002014 indices = ['<p>' + html.bigsection(
2015 'Built-in Modules', '#ffffff', '#ee77aa', contents)]
2016
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002017 seen = {}
Thomas Wouters49fd7fa2006-04-21 10:40:58 +00002018 for dir in sys.path:
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002019 indices.append(html.index(dir, seen))
Neal Norwitz9d72bb42007-04-17 08:48:32 +00002020 contents = heading + ' '.join(indices) + '''<p align=right>
Tim Peters2306d242001-09-25 03:18:32 +00002021<font color="#909090" face="helvetica, arial"><strong>
2022pydoc</strong> by Ka-Ping Yee &lt;ping@lfw.org&gt;</font>'''
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002023 self.send_document('Index of Modules', contents)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002024
2025 def log_message(self, *args): pass
2026
Georg Brandl24420152008-05-26 16:32:26 +00002027 class DocServer(http.server.HTTPServer):
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002028 def __init__(self, port, callback):
Ka-Ping Yeedb8ed152001-03-02 05:58:17 +00002029 host = (sys.platform == 'mac') and '127.0.0.1' or 'localhost'
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00002030 self.address = ('', port)
Ka-Ping Yeedb8ed152001-03-02 05:58:17 +00002031 self.url = 'http://%s:%d/' % (host, port)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002032 self.callback = callback
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002033 self.base.__init__(self, self.address, self.handler)
2034
2035 def serve_until_quit(self):
2036 import select
Guido van Rossum8ca162f2002-04-07 06:36:23 +00002037 self.quit = False
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002038 while not self.quit:
2039 rd, wr, ex = select.select([self.socket.fileno()], [], [], 1)
2040 if rd: self.handle_request()
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002041
2042 def server_activate(self):
2043 self.base.server_activate(self)
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002044 if self.callback: self.callback(self)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002045
Georg Brandl24420152008-05-26 16:32:26 +00002046 DocServer.base = http.server.HTTPServer
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002047 DocServer.handler = DocHandler
Georg Brandl83e9f4c2008-06-12 18:52:31 +00002048 DocHandler.MessageClass = email.message.Message
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002049 try:
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00002050 try:
2051 DocServer(port, callback).serve_until_quit()
2052 except (KeyboardInterrupt, select.error):
2053 pass
2054 finally:
Ka-Ping Yee66246962001-04-12 11:59:50 +00002055 if completer: completer()
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002056
2057# ----------------------------------------------------- graphical interface
2058
2059def gui():
2060 """Graphical interface (starts web server and pops up a control window)."""
2061 class GUI:
2062 def __init__(self, window, port=7464):
2063 self.window = window
2064 self.server = None
2065 self.scanner = None
2066
Georg Brandl14fc4272008-05-17 18:39:55 +00002067 import tkinter
2068 self.server_frm = tkinter.Frame(window)
2069 self.title_lbl = tkinter.Label(self.server_frm,
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002070 text='Starting server...\n ')
Georg Brandl14fc4272008-05-17 18:39:55 +00002071 self.open_btn = tkinter.Button(self.server_frm,
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002072 text='open browser', command=self.open, state='disabled')
Georg Brandl14fc4272008-05-17 18:39:55 +00002073 self.quit_btn = tkinter.Button(self.server_frm,
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002074 text='quit serving', command=self.quit, state='disabled')
2075
Georg Brandl14fc4272008-05-17 18:39:55 +00002076 self.search_frm = tkinter.Frame(window)
2077 self.search_lbl = tkinter.Label(self.search_frm, text='Search for')
2078 self.search_ent = tkinter.Entry(self.search_frm)
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002079 self.search_ent.bind('<Return>', self.search)
Georg Brandl14fc4272008-05-17 18:39:55 +00002080 self.stop_btn = tkinter.Button(self.search_frm,
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002081 text='stop', pady=0, command=self.stop, state='disabled')
2082 if sys.platform == 'win32':
Ka-Ping Yeec92cdf72001-03-02 05:54:35 +00002083 # Trying to hide and show this button crashes under Windows.
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002084 self.stop_btn.pack(side='right')
2085
2086 self.window.title('pydoc')
2087 self.window.protocol('WM_DELETE_WINDOW', self.quit)
2088 self.title_lbl.pack(side='top', fill='x')
2089 self.open_btn.pack(side='left', fill='x', expand=1)
2090 self.quit_btn.pack(side='right', fill='x', expand=1)
2091 self.server_frm.pack(side='top', fill='x')
2092
2093 self.search_lbl.pack(side='left')
2094 self.search_ent.pack(side='right', fill='x', expand=1)
2095 self.search_frm.pack(side='top', fill='x')
2096 self.search_ent.focus_set()
2097
Ka-Ping Yeec92cdf72001-03-02 05:54:35 +00002098 font = ('helvetica', sys.platform == 'win32' and 8 or 10)
Georg Brandl14fc4272008-05-17 18:39:55 +00002099 self.result_lst = tkinter.Listbox(window, font=font, height=6)
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002100 self.result_lst.bind('<Button-1>', self.select)
2101 self.result_lst.bind('<Double-Button-1>', self.goto)
Georg Brandl14fc4272008-05-17 18:39:55 +00002102 self.result_scr = tkinter.Scrollbar(window,
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002103 orient='vertical', command=self.result_lst.yview)
2104 self.result_lst.config(yscrollcommand=self.result_scr.set)
2105
Georg Brandl14fc4272008-05-17 18:39:55 +00002106 self.result_frm = tkinter.Frame(window)
2107 self.goto_btn = tkinter.Button(self.result_frm,
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002108 text='go to selected', command=self.goto)
Georg Brandl14fc4272008-05-17 18:39:55 +00002109 self.hide_btn = tkinter.Button(self.result_frm,
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002110 text='hide results', command=self.hide)
2111 self.goto_btn.pack(side='left', fill='x', expand=1)
2112 self.hide_btn.pack(side='right', fill='x', expand=1)
2113
2114 self.window.update()
2115 self.minwidth = self.window.winfo_width()
2116 self.minheight = self.window.winfo_height()
2117 self.bigminheight = (self.server_frm.winfo_reqheight() +
2118 self.search_frm.winfo_reqheight() +
2119 self.result_lst.winfo_reqheight() +
2120 self.result_frm.winfo_reqheight())
2121 self.bigwidth, self.bigheight = self.minwidth, self.bigminheight
2122 self.expanded = 0
2123 self.window.wm_geometry('%dx%d' % (self.minwidth, self.minheight))
2124 self.window.wm_minsize(self.minwidth, self.minheight)
Martin v. Löwis5b26abb2002-12-28 09:23:09 +00002125 self.window.tk.willdispatch()
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002126
2127 import threading
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00002128 threading.Thread(
2129 target=serve, args=(port, self.ready, self.quit)).start()
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002130
2131 def ready(self, server):
2132 self.server = server
2133 self.title_lbl.config(
2134 text='Python documentation server at\n' + server.url)
2135 self.open_btn.config(state='normal')
2136 self.quit_btn.config(state='normal')
2137
Ka-Ping Yee239432a2001-03-02 02:45:08 +00002138 def open(self, event=None, url=None):
2139 url = url or self.server.url
2140 try:
2141 import webbrowser
2142 webbrowser.open(url)
2143 except ImportError: # pre-webbrowser.py compatibility
Ka-Ping Yeec92cdf72001-03-02 05:54:35 +00002144 if sys.platform == 'win32':
Ka-Ping Yee239432a2001-03-02 02:45:08 +00002145 os.system('start "%s"' % url)
2146 elif sys.platform == 'mac':
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +00002147 try: import ic
Ka-Ping Yee239432a2001-03-02 02:45:08 +00002148 except ImportError: pass
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +00002149 else: ic.launchurl(url)
Ka-Ping Yee239432a2001-03-02 02:45:08 +00002150 else:
2151 rc = os.system('netscape -remote "openURL(%s)" &' % url)
2152 if rc: os.system('netscape "%s" &' % url)
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002153
2154 def quit(self, event=None):
2155 if self.server:
2156 self.server.quit = 1
2157 self.window.quit()
2158
2159 def search(self, event=None):
2160 key = self.search_ent.get()
2161 self.stop_btn.pack(side='right')
2162 self.stop_btn.config(state='normal')
2163 self.search_lbl.config(text='Searching for "%s"...' % key)
2164 self.search_ent.forget()
2165 self.search_lbl.pack(side='left')
2166 self.result_lst.delete(0, 'end')
2167 self.goto_btn.config(state='disabled')
2168 self.expand()
2169
2170 import threading
2171 if self.scanner:
2172 self.scanner.quit = 1
2173 self.scanner = ModuleScanner()
2174 threading.Thread(target=self.scanner.run,
Ka-Ping Yee6dcfa382001-04-12 20:27:31 +00002175 args=(self.update, key, self.done)).start()
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002176
2177 def update(self, path, modname, desc):
2178 if modname[-9:] == '.__init__':
2179 modname = modname[:-9] + ' (package)'
2180 self.result_lst.insert('end',
2181 modname + ' - ' + (desc or '(no description)'))
2182
2183 def stop(self, event=None):
2184 if self.scanner:
2185 self.scanner.quit = 1
2186 self.scanner = None
2187
2188 def done(self):
2189 self.scanner = None
2190 self.search_lbl.config(text='Search for')
2191 self.search_lbl.pack(side='left')
2192 self.search_ent.pack(side='right', fill='x', expand=1)
2193 if sys.platform != 'win32': self.stop_btn.forget()
2194 self.stop_btn.config(state='disabled')
2195
2196 def select(self, event=None):
2197 self.goto_btn.config(state='normal')
2198
2199 def goto(self, event=None):
2200 selection = self.result_lst.curselection()
2201 if selection:
Neal Norwitz9d72bb42007-04-17 08:48:32 +00002202 modname = self.result_lst.get(selection[0]).split()[0]
Ka-Ping Yee239432a2001-03-02 02:45:08 +00002203 self.open(url=self.server.url + modname + '.html')
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002204
2205 def collapse(self):
2206 if not self.expanded: return
2207 self.result_frm.forget()
2208 self.result_scr.forget()
2209 self.result_lst.forget()
2210 self.bigwidth = self.window.winfo_width()
2211 self.bigheight = self.window.winfo_height()
2212 self.window.wm_geometry('%dx%d' % (self.minwidth, self.minheight))
2213 self.window.wm_minsize(self.minwidth, self.minheight)
2214 self.expanded = 0
2215
2216 def expand(self):
2217 if self.expanded: return
2218 self.result_frm.pack(side='bottom', fill='x')
2219 self.result_scr.pack(side='right', fill='y')
2220 self.result_lst.pack(side='top', fill='both', expand=1)
2221 self.window.wm_geometry('%dx%d' % (self.bigwidth, self.bigheight))
2222 self.window.wm_minsize(self.minwidth, self.bigminheight)
2223 self.expanded = 1
2224
2225 def hide(self, event=None):
2226 self.stop()
2227 self.collapse()
2228
Georg Brandl14fc4272008-05-17 18:39:55 +00002229 import tkinter
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002230 try:
Georg Brandl14fc4272008-05-17 18:39:55 +00002231 root = tkinter.Tk()
Martin v. Löwise09bd932004-08-22 16:13:26 +00002232 # Tk will crash if pythonw.exe has an XP .manifest
2233 # file and the root has is not destroyed explicitly.
2234 # If the problem is ever fixed in Tk, the explicit
2235 # destroy can go.
2236 try:
2237 gui = GUI(root)
2238 root.mainloop()
2239 finally:
2240 root.destroy()
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002241 except KeyboardInterrupt:
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002242 pass
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002243
2244# -------------------------------------------------- command-line interface
2245
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00002246def ispath(x):
Neal Norwitz9d72bb42007-04-17 08:48:32 +00002247 return isinstance(x, str) and x.find(os.sep) >= 0
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00002248
Ka-Ping Yee1d384632001-03-01 00:24:32 +00002249def cli():
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002250 """Command-line interface (looks at sys.argv to decide what to do)."""
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002251 import getopt
Guido van Rossum756aa932007-04-07 03:04:01 +00002252 class BadUsage(Exception): pass
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002253
Nick Coghlanb830a232009-11-15 23:27:31 +00002254 # Scripts don't get the current directory in their path by default
2255 # unless they are run with the '-m' switch
2256 if '' not in sys.path:
2257 scriptdir = os.path.dirname(sys.argv[0])
2258 if scriptdir in sys.path:
2259 sys.path.remove(scriptdir)
2260 sys.path.insert(0, '.')
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002261
Ka-Ping Yee3bda8792001-03-23 13:17:50 +00002262 try:
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002263 opts, args = getopt.getopt(sys.argv[1:], 'gk:p:w')
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002264 writing = 0
2265
2266 for opt, val in opts:
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002267 if opt == '-g':
2268 gui()
2269 return
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002270 if opt == '-k':
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002271 apropos(val)
2272 return
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002273 if opt == '-p':
2274 try:
2275 port = int(val)
2276 except ValueError:
2277 raise BadUsage
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002278 def ready(server):
Guido van Rossumbe19ed72007-02-09 05:37:30 +00002279 print('pydoc server ready at %s' % server.url)
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00002280 def stopped():
Guido van Rossumbe19ed72007-02-09 05:37:30 +00002281 print('pydoc server stopped')
Ka-Ping Yee9aa0d902001-04-12 10:50:23 +00002282 serve(port, ready, stopped)
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002283 return
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002284 if opt == '-w':
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002285 writing = 1
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002286
2287 if not args: raise BadUsage
2288 for arg in args:
Ka-Ping Yee45daeb02002-08-11 15:11:33 +00002289 if ispath(arg) and not os.path.exists(arg):
Guido van Rossumbe19ed72007-02-09 05:37:30 +00002290 print('file %r does not exist' % arg)
Ka-Ping Yee45daeb02002-08-11 15:11:33 +00002291 break
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002292 try:
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00002293 if ispath(arg) and os.path.isfile(arg):
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002294 arg = importfile(arg)
Ka-Ping Yee37f7b382001-03-23 00:12:53 +00002295 if writing:
2296 if ispath(arg) and os.path.isdir(arg):
2297 writedocs(arg)
2298 else:
2299 writedoc(arg)
2300 else:
Martin v. Löwisb8c084e2003-06-14 09:03:46 +00002301 help.help(arg)
Guido van Rossumb940e112007-01-10 16:19:56 +00002302 except ErrorDuringImport as value:
Guido van Rossumbe19ed72007-02-09 05:37:30 +00002303 print(value)
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002304
2305 except (getopt.error, BadUsage):
Martin v. Löwisf9b08b82003-10-31 13:05:21 +00002306 cmd = os.path.basename(sys.argv[0])
Guido van Rossumbe19ed72007-02-09 05:37:30 +00002307 print("""pydoc - the Python documentation tool
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002308
2309%s <name> ...
2310 Show text documentation on something. <name> may be the name of a
Martin v. Löwisb8c084e2003-06-14 09:03:46 +00002311 Python keyword, topic, function, module, or package, or a dotted
2312 reference to a class or function within a module or module in a
2313 package. If <name> contains a '%s', it is used as the path to a
2314 Python source file to document. If name is 'keywords', 'topics',
2315 or 'modules', a listing of these things is displayed.
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002316
2317%s -k <keyword>
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002318 Search for a keyword in the synopsis lines of all available modules.
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002319
2320%s -p <port>
2321 Start an HTTP server on the given port on the local machine.
2322
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002323%s -g
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +00002324 Pop up a graphical interface for finding and serving documentation.
Ka-Ping Yeedd175342001-02-27 14:43:46 +00002325
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002326%s -w <name> ...
2327 Write out the HTML documentation for a module to a file in the current
Ka-Ping Yee5a804ed2001-04-10 11:46:02 +00002328 directory. If <name> contains a '%s', it is treated as a filename; if
2329 it names a directory, documentation is written for all the contents.
Guido van Rossumbe19ed72007-02-09 05:37:30 +00002330""" % (cmd, os.sep, cmd, cmd, cmd, cmd, os.sep))
Ka-Ping Yee1d384632001-03-01 00:24:32 +00002331
Ka-Ping Yee66efbc72001-03-01 13:55:20 +00002332if __name__ == '__main__': cli()