Mercurial > cpython-lru_cache-weakref

annotate Lib/pydoc.py @ 58925:eecf1bef052d 2.6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merged revisions 78207 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r78207 | ezio.melotti | 2010-02-17 01:26:09 +0200 (Wed, 17 Feb 2010) | 1 line #7930: fix stripid ........
author Ezio Melotti <ezio.melotti@gmail.com>
date Tue, 16 Feb 2010 23:29:44 +0000
parents c08423d70b9f
children ef6ebc06a786
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1 #!/usr/bin/env python
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
2 # -*- coding: latin-1 -*-
16875
10b84060b7f3 Normalize case of paths in sys.path to avoid duplicates on Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 16833
diff changeset
3 """Generate Python documentation in HTML or text for interactive use.
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
4
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
5 In the Python interpreter, do "from pydoc import help" to provide online
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
6 help. Calling help(thing) on a Python object documents the object.
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
7
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
8 Or, at the shell command line outside of Python:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
9
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
10 Run "pydoc <name>" to show documentation on something. <name> may be
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
11 the name of a function, module, package, or a dotted reference to a
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
12 class or function within a module or module in a package. If the
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
13 argument contains a path segment delimiter (e.g. slash on Unix,
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
14 backslash on Windows) it is treated as the path to a Python source file.
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
15
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
16 Run "pydoc -k <keyword>" to search for a keyword in the synopsis lines
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
17 of all available modules.
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
18
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
19 Run "pydoc -p <port>" to start an HTTP server on a given port on the
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
20 local machine to generate documentation web pages.
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
21
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
22 For platforms without a command line, "pydoc -g" starts the HTTP server
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
23 and also pops up a little window for controlling it.
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
24
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
25 Run "pydoc -w <name>" to write out the HTML documentation for a module
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
26 to a file named "<name>.html".
30396
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
27
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
28 Module docs for core modules are assumed to be in
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
29
44845
27dac16541d9 Adapt pydoc to new doc URLs.
Georg Brandl <georg@python.org>
parents: 44660
diff changeset
30 http://docs.python.org/library/
30396
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
31
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
32 This can be overridden by setting the PYTHONDOCS environment variable
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
33 to a different URL or to a local directory containing the Library
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
34 Reference Manual pages.
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
35 """
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
36
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
37 __author__ = "Ka-Ping Yee <ping@lfw.org>"
16811
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
38 __date__ = "26 February 2001"
35742
1c4d192f1568 Merge ast-branch to head
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 35663
diff changeset
39
16812
580ad685445f Add $Revision: $ tag.
Ka-Ping Yee <ping@zesty.ca>
parents: 16811
diff changeset
40 __version__ = "$Revision$"
33991
f13ce0bb606c Back out rev 1.96; see #1009389.
Martin v. Löwis <martin@v.loewis.de>
parents: 33935
diff changeset
41 __credits__ = """Guido van Rossum, for an excellent programming language.
16818
fd2a869769b2 Acknowledgements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16813
diff changeset
42 Tommy Burnette, the original creator of manpy.
16811
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
43 Paul Prescod, for all his work on onlinehelp.
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
44 Richard Chamberlain, for the first implementation of textdoc.
34299
df380e196c4b SF patch #1094007: Remove witty comment in pydoc.py
Raymond Hettinger <python@rcn.com>
parents: 33991
diff changeset
45 """
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
46
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
47 # Known bugs that can't be fixed here:
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
48 # - imp.load_module() cannot be prevented from clobbering existing
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
49 # loaded modules, so calling synopsis() on a binary module file
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
50 # changes the contents of any existing module with the same name.
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
51 # - If the __file__ attribute on a module is a relative path and
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
52 # the current directory is changed with os.chdir(), an incorrect
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
53 # path will be displayed.
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
54
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
55 import sys, imp, os, re, types, inspect, __builtin__, pkgutil
47221
9fbc41abdd4b Revert the renaming of repr to reprlib.
Brett Cannon <bcannon@gmail.com>
parents: 47183
diff changeset
56 from repr import Repr
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
57 from string import expandtabs, find, join, lower, split, strip, rfind, rstrip
54827
e7371353a302 Merged revisions 73529 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 54377
diff changeset
58 from traceback import extract_tb
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
59 try:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
60 from collections import deque
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
61 except ImportError:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
62 # Python 2.3 compatibility
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
63 class deque(list):
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
64 def popleft(self):
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
65 return self.pop(0)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
66
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
67 # --------------------------------------------------------- common routines
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
68
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
69 def pathdirs():
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
70 """Convert sys.path into a list of absolute, existing, unique paths."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
71 dirs = []
16875
10b84060b7f3 Normalize case of paths in sys.path to avoid duplicates on Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 16833
diff changeset
72 normdirs = []
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
73 for dir in sys.path:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
74 dir = os.path.abspath(dir or '.')
16875
10b84060b7f3 Normalize case of paths in sys.path to avoid duplicates on Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 16833
diff changeset
75 normdir = os.path.normcase(dir)
10b84060b7f3 Normalize case of paths in sys.path to avoid duplicates on Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 16833
diff changeset
76 if normdir not in normdirs and os.path.isdir(dir):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
77 dirs.append(dir)
16875
10b84060b7f3 Normalize case of paths in sys.path to avoid duplicates on Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 16833
diff changeset
78 normdirs.append(normdir)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
79 return dirs
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
80
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
81 def getdoc(object):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
82 """Get the doc string or comments for an object."""
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
83 result = inspect.getdoc(object) or inspect.getcomments(object)
16928
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
84 return result and re.sub('^ *\n', '', rstrip(result)) or ''
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
85
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
86 def splitdoc(doc):
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
87 """Split a doc string into a synopsis line (if any) and the rest."""
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
88 lines = split(strip(doc), '\n')
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
89 if len(lines) == 1:
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
90 return lines[0], ''
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
91 elif len(lines) >= 2 and not rstrip(lines[1]):
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
92 return lines[0], join(lines[2:], '\n')
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
93 return '', join(lines, '\n')
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
94
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
95 def classname(object, modname):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
96 """Get a class name and qualify it with a module name if necessary."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
97 name = object.__name__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
98 if object.__module__ != modname:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
99 name = object.__module__ + '.' + name
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
100 return name
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
101
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
102 def isdata(object):
35277
6ebc423f2d81 That was one too much.
Georg Brandl <georg@python.org>
parents: 35276
diff changeset
103 """Check if an object is of a type that probably means it's data."""
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
104 return not (inspect.ismodule(object) or inspect.isclass(object) or
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
105 inspect.isroutine(object) or inspect.isframe(object) or
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
106 inspect.istraceback(object) or inspect.iscode(object))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
107
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
108 def replace(text, *pairs):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
109 """Do a series of global replacements on a string."""
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
110 while pairs:
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
111 text = join(split(text, pairs[0]), pairs[1])
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
112 pairs = pairs[2:]
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
113 return text
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
114
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
115 def cram(text, maxlen):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
116 """Omit part of a string if needed to make it fit in a maximum length."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
117 if len(text) > maxlen:
25871
cb910c394927 Explicitly use floor division
Raymond Hettinger <python@rcn.com>
parents: 25454
diff changeset
118 pre = max(0, (maxlen-3)//2)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
119 post = max(0, maxlen-3-pre)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
120 return text[:pre] + '...' + text[len(text)-post:]
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
121 return text
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
122
32382
cde2feab7fe0 Change pydoc.stripid() be able to match against 64-bit addresses by having
Brett Cannon <bcannon@gmail.com>
parents: 32380
diff changeset
123 _re_stripid = re.compile(r' at 0x[0-9a-f]{6,16}(>+)$', re.IGNORECASE)
16875
10b84060b7f3 Normalize case of paths in sys.path to avoid duplicates on Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 16833
diff changeset
124 def stripid(text):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
125 """Remove the hexadecimal id from a Python object representation."""
32380
c6ab0f88895a pydoc.stripid() is now case-insensitive for its regex to support platforms that
Brett Cannon <bcannon@gmail.com>
parents: 32321
diff changeset
126 # The behaviour of %p is implementation-dependent in terms of case.
58925
eecf1bef052d Merged revisions 78207 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 57282
diff changeset
127 return _re_stripid.sub(r'\1', text)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
128
32380
c6ab0f88895a pydoc.stripid() is now case-insensitive for its regex to support platforms that
Brett Cannon <bcannon@gmail.com>
parents: 32321
diff changeset
129 def _is_some_method(obj):
c6ab0f88895a pydoc.stripid() is now case-insensitive for its regex to support platforms that
Brett Cannon <bcannon@gmail.com>
parents: 32321
diff changeset
130 return inspect.ismethod(obj) or inspect.ismethoddescriptor(obj)
19989
cec9e25af121 After much thrashing, I believe this is a truly minimal patch to teach
Tim Peters <tim.peters@gmail.com>
parents: 18816
diff changeset
131
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
132 def allmethods(cl):
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
133 methods = {}
19989
cec9e25af121 After much thrashing, I believe this is a truly minimal patch to teach
Tim Peters <tim.peters@gmail.com>
parents: 18816
diff changeset
134 for key, value in inspect.getmembers(cl, _is_some_method):
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
135 methods[key] = 1
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
136 for base in cl.__bases__:
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
137 methods.update(allmethods(base)) # all your base are belong to us
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
138 for key in methods.keys():
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
139 methods[key] = getattr(cl, key)
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
140 return methods
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
141
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
142 def _split_list(s, predicate):
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
143 """Split sequence s via predicate, and return pair ([true], [false]).
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
144
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
145 The return value is a 2-tuple of lists,
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
146 ([x for x in s if predicate(x)],
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
147 [x for x in s if not predicate(x)])
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
148 """
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
149
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
150 yes = []
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
151 no = []
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
152 for x in s:
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
153 if predicate(x):
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
154 yes.append(x)
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
155 else:
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
156 no.append(x)
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
157 return yes, no
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
158
32321
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
159 def visiblename(name, all=None):
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
160 """Decide whether to show documentation on a variable."""
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
161 # Certain special names are redundant.
47873
5d8f47005b73 Issue 3190: pydoc now hides module __package__ attributes
Nick Coghlan <ncoghlan@gmail.com>
parents: 47431
diff changeset
162 _hidden_names = ('__builtins__', '__doc__', '__file__', '__path__',
5d8f47005b73 Issue 3190: pydoc now hides module __package__ attributes
Nick Coghlan <ncoghlan@gmail.com>
parents: 47431
diff changeset
163 '__module__', '__name__', '__slots__', '__package__')
5d8f47005b73 Issue 3190: pydoc now hides module __package__ attributes
Nick Coghlan <ncoghlan@gmail.com>
parents: 47431
diff changeset
164 if name in _hidden_names: return 0
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
165 # Private names are hidden, but special names are displayed.
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
166 if name.startswith('__') and name.endswith('__'): return 1
32321
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
167 if all is not None:
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
168 # only document that which the programmer exported in __all__
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
169 return name in all
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
170 else:
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
171 return not name.startswith('_')
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
172
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
173 def classify_class_attrs(object):
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
174 """Wrap inspect.classify_class_attrs, with fixup for data descriptors."""
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
175 def fixup(data):
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
176 name, kind, cls, value = data
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
177 if inspect.isdatadescriptor(value):
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
178 kind = 'data descriptor'
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
179 return name, kind, cls, value
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
180 return map(fixup, inspect.classify_class_attrs(object))
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
181
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
182 # ----------------------------------------------------- module manipulation
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
183
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
184 def ispackage(path):
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
185 """Guess whether a path refers to a package directory."""
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
186 if os.path.isdir(path):
34545
9d66fba78444 Replace list of constants with tuples of constants.
Raymond Hettinger <python@rcn.com>
parents: 34369
diff changeset
187 for ext in ('.py', '.pyc', '.pyo'):
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
188 if os.path.isfile(os.path.join(path, '__init__' + ext)):
22830
a9dd5e6d6805 Convert a pile of obvious "yes/no" functions to return bool.
Tim Peters <tim.peters@gmail.com>
parents: 22506
diff changeset
189 return True
a9dd5e6d6805 Convert a pile of obvious "yes/no" functions to return bool.
Tim Peters <tim.peters@gmail.com>
parents: 22506
diff changeset
190 return False
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
191
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
192 def source_synopsis(file):
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
193 line = file.readline()
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
194 while line[:1] == '#' or not strip(line):
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
195 line = file.readline()
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
196 if not line: break
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
197 line = strip(line)
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
198 if line[:4] == 'r"""': line = line[1:]
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
199 if line[:3] == '"""':
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
200 line = line[3:]
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
201 if line[-1:] == '\\': line = line[:-1]
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
202 while not strip(line):
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
203 line = file.readline()
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
204 if not line: break
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
205 result = strip(split(line, '"""')[0])
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
206 else: result = None
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
207 return result
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
208
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
209 def synopsis(filename, cache={}):
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
210 """Get the one-line summary out of a module file."""
23625
65cf478950ff Replaced obsolete stat module constants with equivalent attributes
Raymond Hettinger <python@rcn.com>
parents: 23620
diff changeset
211 mtime = os.stat(filename).st_mtime
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
212 lastupdate, result = cache.get(filename, (0, None))
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
213 if lastupdate < mtime:
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
214 info = inspect.getmoduleinfo(filename)
36893
4b347c654635 Fix pydoc.synopsis() so that it doesn't error out with an unreadable
Georg Brandl <georg@python.org>
parents: 36545
diff changeset
215 try:
4b347c654635 Fix pydoc.synopsis() so that it doesn't error out with an unreadable
Georg Brandl <georg@python.org>
parents: 36545
diff changeset
216 file = open(filename)
4b347c654635 Fix pydoc.synopsis() so that it doesn't error out with an unreadable
Georg Brandl <georg@python.org>
parents: 36545
diff changeset
217 except IOError:
4b347c654635 Fix pydoc.synopsis() so that it doesn't error out with an unreadable
Georg Brandl <georg@python.org>
parents: 36545
diff changeset
218 # module can't be opened, so skip it
4b347c654635 Fix pydoc.synopsis() so that it doesn't error out with an unreadable
Georg Brandl <georg@python.org>
parents: 36545
diff changeset
219 return None
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
220 if info and 'b' in info[2]: # binary modules have to be imported
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
221 try: module = imp.load_module('__temp__', file, filename, info[1:])
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
222 except: return None
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
223 result = (module.__doc__ or '').splitlines()[0]
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
224 del sys.modules['__temp__']
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
225 else: # text modules can be directly examined
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
226 result = source_synopsis(file)
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
227 file.close()
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
228 cache[filename] = (mtime, result)
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
229 return result
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
230
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
231 class ErrorDuringImport(Exception):
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
232 """Errors that occurred while trying to import something to document it."""
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
233 def __init__(self, filename, exc_info):
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
234 exc, value, tb = exc_info
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
235 self.filename = filename
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
236 self.exc = exc
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
237 self.value = value
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
238 self.tb = tb
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
239
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
240 def __str__(self):
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
241 exc = self.exc
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
242 if type(exc) is types.ClassType:
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
243 exc = exc.__name__
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
244 return 'problem in %s - %s: %s' % (self.filename, exc, self.value)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
245
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
246 def importfile(path):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
247 """Import a Python source file or compiled file given its path."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
248 magic = imp.get_magic()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
249 file = open(path, 'r')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
250 if file.read(len(magic)) == magic:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
251 kind = imp.PY_COMPILED
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
252 else:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
253 kind = imp.PY_SOURCE
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
254 file.close()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
255 filename = os.path.basename(path)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
256 name, ext = os.path.splitext(filename)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
257 file = open(path, 'r')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
258 try:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
259 module = imp.load_module(name, file, path, (ext, 'r', kind))
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
260 except:
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
261 raise ErrorDuringImport(path, sys.exc_info())
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
262 file.close()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
263 return module
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
264
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
265 def safeimport(path, forceload=0, cache={}):
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
266 """Import a module; handle errors; return None if the module isn't found.
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
267
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
268 If the module *is* found but an exception occurs, it's wrapped in an
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
269 ErrorDuringImport exception and reraised. Unlike __import__, if a
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
270 package path is specified, the module at the end of the path is returned,
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
271 not the package at the beginning. If the optional 'forceload' argument
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
272 is 1, we reload the module from disk (unless it's a dynamic extension)."""
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
273 try:
35838
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
274 # If forceload is 1 and the module has been previously loaded from
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
275 # disk, we always have to reload the module. Checking the file's
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
276 # mtime isn't good enough (e.g. the module could contain a class
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
277 # that inherits from another module that has changed).
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
278 if forceload and path in sys.modules:
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
279 if path not in sys.builtin_module_names:
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
280 # Avoid simply calling reload() because it leaves names in
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
281 # the currently loaded module lying around if they're not
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
282 # defined in the new source file. Instead, remove the
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
283 # module from sys.modules and re-import. Also remove any
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
284 # submodules because they won't appear in the newly loaded
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
285 # module's namespace if they're already in sys.modules.
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
286 subs = [m for m in sys.modules if m.startswith(path + '.')]
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
287 for key in [path] + subs:
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
288 # Prevent garbage collection.
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
289 cache[key] = sys.modules[key]
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
290 del sys.modules[key]
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
291 module = __import__(path)
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
292 except:
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
293 # Did the error occur before or after the module was found?
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
294 (exc, value, tb) = info = sys.exc_info()
23620
a1de0bab5475 SF 563203. Replaced 'has_key()' with 'in'.
Raymond Hettinger <python@rcn.com>
parents: 23501
diff changeset
295 if path in sys.modules:
35806
44fe157255bc fix typos, mostly in comments
Fred Drake <fdrake@acm.org>
parents: 35742
diff changeset
296 # An error occurred while executing the imported module.
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
297 raise ErrorDuringImport(sys.modules[path].__file__, info)
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
298 elif exc is SyntaxError:
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
299 # A SyntaxError occurred before we could execute the module.
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
300 raise ErrorDuringImport(value.filename, info)
54827
e7371353a302 Merged revisions 73529 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 54377
diff changeset
301 elif exc is ImportError and extract_tb(tb)[-1][2]=='safeimport':
e7371353a302 Merged revisions 73529 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 54377
diff changeset
302 # The import error occurred directly in this function,
e7371353a302 Merged revisions 73529 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 54377
diff changeset
303 # which means there is no such module in the path.
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
304 return None
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
305 else:
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
306 # Some other error occurred during the importing process.
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
307 raise ErrorDuringImport(path, sys.exc_info())
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
308 for part in split(path, '.')[1:]:
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
309 try: module = getattr(module, part)
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
310 except AttributeError: return None
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
311 return module
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
312
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
313 # ---------------------------------------------------- formatter base class
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
314
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
315 class Doc:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
316 def document(self, object, name=None, *args):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
317 """Generate documentation for an object."""
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
318 args = (object, name) + args
29409
29760056884a Have pydoc try handling an object as "other" if the object does not act the way
Brett Cannon <bcannon@gmail.com>
parents: 29267
diff changeset
319 # 'try' clause is to attempt to handle the possibility that inspect
29760056884a Have pydoc try handling an object as "other" if the object does not act the way
Brett Cannon <bcannon@gmail.com>
parents: 29267
diff changeset
320 # identifies something in a way that pydoc itself has issues handling;
29760056884a Have pydoc try handling an object as "other" if the object does not act the way
Brett Cannon <bcannon@gmail.com>
parents: 29267
diff changeset
321 # think 'super' and how it is a descriptor (which raises the exception
29760056884a Have pydoc try handling an object as "other" if the object does not act the way
Brett Cannon <bcannon@gmail.com>
parents: 29267
diff changeset
322 # by lacking a __name__ attribute) and an instance.
39226
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
323 if inspect.isgetsetdescriptor(object): return self.docdata(*args)
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
324 if inspect.ismemberdescriptor(object): return self.docdata(*args)
29409
29760056884a Have pydoc try handling an object as "other" if the object does not act the way
Brett Cannon <bcannon@gmail.com>
parents: 29267
diff changeset
325 try:
29760056884a Have pydoc try handling an object as "other" if the object does not act the way
Brett Cannon <bcannon@gmail.com>
parents: 29267
diff changeset
326 if inspect.ismodule(object): return self.docmodule(*args)
29760056884a Have pydoc try handling an object as "other" if the object does not act the way
Brett Cannon <bcannon@gmail.com>
parents: 29267
diff changeset
327 if inspect.isclass(object): return self.docclass(*args)
29760056884a Have pydoc try handling an object as "other" if the object does not act the way
Brett Cannon <bcannon@gmail.com>
parents: 29267
diff changeset
328 if inspect.isroutine(object): return self.docroutine(*args)
29760056884a Have pydoc try handling an object as "other" if the object does not act the way
Brett Cannon <bcannon@gmail.com>
parents: 29267
diff changeset
329 except AttributeError:
29760056884a Have pydoc try handling an object as "other" if the object does not act the way
Brett Cannon <bcannon@gmail.com>
parents: 29267
diff changeset
330 pass
33935
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
331 if isinstance(object, property): return self.docproperty(*args)
28089
14f65d661084 Get rid of many apply() calls.
Guido van Rossum <guido@python.org>
parents: 27904
diff changeset
332 return self.docother(*args)
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
333
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
334 def fail(self, object, name=None, *args):
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
335 """Raise an exception for unimplemented types."""
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
336 message = "don't know how to document object%s of type %s" % (
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
337 name and ' ' + repr(name), type(object).__name__)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
338 raise TypeError, message
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
339
39226
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
340 docmodule = docclass = docroutine = docother = docproperty = docdata = fail
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
341
30396
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
342 def getdocloc(self, object):
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
343 """Return the location of module docs or None"""
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
344
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
345 try:
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
346 file = inspect.getabsfile(object)
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
347 except TypeError:
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
348 file = '(built-in)'
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
349
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
350 docloc = os.environ.get("PYTHONDOCS",
44845
27dac16541d9 Adapt pydoc to new doc URLs.
Georg Brandl <georg@python.org>
parents: 44660
diff changeset
351 "http://docs.python.org/library")
30396
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
352 basedir = os.path.join(sys.exec_prefix, "lib",
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
353 "python"+sys.version[0:3])
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
354 if (isinstance(object, type(os)) and
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
355 (object.__name__ in ('errno', 'exceptions', 'gc', 'imp',
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
356 'marshal', 'posix', 'signal', 'sys',
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
357 'thread', 'zipimport') or
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
358 (file.startswith(basedir) and
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
359 not file.startswith(os.path.join(basedir, 'site-packages'))))):
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
360 if docloc.startswith("http://"):
44845
27dac16541d9 Adapt pydoc to new doc URLs.
Georg Brandl <georg@python.org>
parents: 44660
diff changeset
361 docloc = "%s/%s" % (docloc.rstrip("/"), object.__name__)
30396
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
362 else:
44845
27dac16541d9 Adapt pydoc to new doc URLs.
Georg Brandl <georg@python.org>
parents: 44660
diff changeset
363 docloc = os.path.join(docloc, object.__name__ + ".html")
30396
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
364 else:
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
365 docloc = None
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
366 return docloc
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
367
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
368 # -------------------------------------------- HTML documentation generator
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
369
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
370 class HTMLRepr(Repr):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
371 """Class for safely making an HTML representation of a Python object."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
372 def __init__(self):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
373 Repr.__init__(self)
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
374 self.maxlist = self.maxtuple = 20
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
375 self.maxdict = 10
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
376 self.maxstring = self.maxother = 100
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
377
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
378 def escape(self, text):
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
379 return replace(text, '&', '&amp;', '<', '&lt;', '>', '&gt;')
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
380
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
381 def repr(self, object):
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
382 return Repr.repr(self, object)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
383
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
384 def repr1(self, x, level):
29603
fea8dee27332 (HTML|Text)Repr.repr1: Guard against objects whos types have no __name__
Skip Montanaro <skip@pobox.com>
parents: 29463
diff changeset
385 if hasattr(type(x), '__name__'):
fea8dee27332 (HTML|Text)Repr.repr1: Guard against objects whos types have no __name__
Skip Montanaro <skip@pobox.com>
parents: 29463
diff changeset
386 methodname = 'repr_' + join(split(type(x).__name__), '_')
fea8dee27332 (HTML|Text)Repr.repr1: Guard against objects whos types have no __name__
Skip Montanaro <skip@pobox.com>
parents: 29463
diff changeset
387 if hasattr(self, methodname):
fea8dee27332 (HTML|Text)Repr.repr1: Guard against objects whos types have no __name__
Skip Montanaro <skip@pobox.com>
parents: 29463
diff changeset
388 return getattr(self, methodname)(x, level)
fea8dee27332 (HTML|Text)Repr.repr1: Guard against objects whos types have no __name__
Skip Montanaro <skip@pobox.com>
parents: 29463
diff changeset
389 return self.escape(cram(stripid(repr(x)), self.maxother))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
390
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
391 def repr_string(self, x, level):
16923
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
392 test = cram(x, self.maxstring)
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
393 testrepr = repr(test)
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
394 if '\\' in test and '\\' not in replace(testrepr, r'\\', ''):
16923
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
395 # Backslashes are only literal in the string and are never
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
396 # needed to make any special characters, so show a raw string.
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
397 return 'r' + testrepr[0] + self.escape(test) + testrepr[0]
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
398 return re.sub(r'((\\[\\abfnrtv\'"]|\\[0-9]..|\\x..|\\u....)+)',
16923
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
399 r'<font color="#c040c0">\1</font>',
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
400 self.escape(testrepr))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
401
22169
4d5becc6902b add repr_str as alias for repr_string in both HTMLRepr and TextRepr classes
Skip Montanaro <skip@pobox.com>
parents: 22117
diff changeset
402 repr_str = repr_string
4d5becc6902b add repr_str as alias for repr_string in both HTMLRepr and TextRepr classes
Skip Montanaro <skip@pobox.com>
parents: 22117
diff changeset
403
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
404 def repr_instance(self, x, level):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
405 try:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
406 return self.escape(cram(stripid(repr(x)), self.maxstring))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
407 except:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
408 return self.escape('<%s instance>' % x.__class__.__name__)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
409
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
410 repr_unicode = repr_string
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
411
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
412 class HTMLDoc(Doc):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
413 """Formatter class for HTML documentation."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
414
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
415 # ------------------------------------------- HTML formatting utilities
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
416
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
417 _repr_instance = HTMLRepr()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
418 repr = _repr_instance.repr
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
419 escape = _repr_instance.escape
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
420
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
421 def page(self, title, contents):
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
422 """Format an HTML page."""
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
423 return '''
53034
0327504a4f6a Merged revisions 71443 via svnmerge from
Matthias Klose <doko@ubuntu.com>
parents: 50424
diff changeset
424 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
425 <html><head><title>Python: %s</title>
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
426 </head><body bgcolor="#f0f0f8">
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
427 %s
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
428 </body></html>''' % (title, contents)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
429
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
430 def heading(self, title, fgcol, bgcol, extras=''):
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
431 """Format a page heading."""
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
432 return '''
20783
a2b11d00b697 SF patch #474485: pydoc generates some bad html, from Rich Salz.
Tim Peters <tim.peters@gmail.com>
parents: 20538
diff changeset
433 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="heading">
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
434 <tr bgcolor="%s">
20074
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
435 <td valign=bottom>&nbsp;<br>
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
436 <font color="%s" face="helvetica, arial">&nbsp;<br>%s</font></td
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
437 ><td align=right valign=bottom
17182
5ee3543ea33f Small formatting improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 17181
diff changeset
438 ><font color="%s" face="helvetica, arial">%s</font></td></tr></table>
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
439 ''' % (bgcol, fgcol, title, fgcol, extras or '&nbsp;')
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
440
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
441 def section(self, title, fgcol, bgcol, contents, width=6,
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
442 prelude='', marginalia=None, gap='&nbsp;'):
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
443 """Format a section with a heading."""
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
444 if marginalia is None:
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
445 marginalia = '<tt>' + '&nbsp;' * width + '</tt>'
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
446 result = '''<p>
20783
a2b11d00b697 SF patch #474485: pydoc generates some bad html, from Rich Salz.
Tim Peters <tim.peters@gmail.com>
parents: 20538
diff changeset
447 <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
448 <tr bgcolor="%s">
20074
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
449 <td colspan=3 valign=bottom>&nbsp;<br>
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
450 <font color="%s" face="helvetica, arial">%s</font></td></tr>
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
451 ''' % (bgcol, fgcol, title)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
452 if prelude:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
453 result = result + '''
17182
5ee3543ea33f Small formatting improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 17181
diff changeset
454 <tr bgcolor="%s"><td rowspan=2>%s</td>
5ee3543ea33f Small formatting improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 17181
diff changeset
455 <td colspan=2>%s</td></tr>
5ee3543ea33f Small formatting improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 17181
diff changeset
456 <tr><td>%s</td>''' % (bgcol, marginalia, prelude, gap)
5ee3543ea33f Small formatting improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 17181
diff changeset
457 else:
5ee3543ea33f Small formatting improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 17181
diff changeset
458 result = result + '''
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
459 <tr><td bgcolor="%s">%s</td><td>%s</td>''' % (bgcol, marginalia, gap)
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
460
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
461 return result + '\n<td width="100%%">%s</td></tr></table>' % contents
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
462
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
463 def bigsection(self, title, *args):
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
464 """Format a section with a big heading."""
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
465 title = '<big><strong>%s</strong></big>' % title
28089
14f65d661084 Get rid of many apply() calls.
Guido van Rossum <guido@python.org>
parents: 27904
diff changeset
466 return self.section(title, *args)
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
467
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
468 def preformat(self, text):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
469 """Format literal preformatted text."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
470 text = self.escape(expandtabs(text))
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
471 return replace(text, '\n\n', '\n \n', '\n\n', '\n \n',
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
472 ' ', '&nbsp;', '\n', '<br>\n')
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
473
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
474 def multicolumn(self, list, format, cols=4):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
475 """Format a list of items into a multi-column list."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
476 result = ''
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
477 rows = (len(list)+cols-1)/cols
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
478 for col in range(cols):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
479 result = result + '<td width="%d%%" valign=top>' % (100/cols)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
480 for i in range(rows*col, rows*col+rows):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
481 if i < len(list):
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
482 result = result + format(list[i]) + '<br>\n'
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
483 result = result + '</td>'
20783
a2b11d00b697 SF patch #474485: pydoc generates some bad html, from Rich Salz.
Tim Peters <tim.peters@gmail.com>
parents: 20538
diff changeset
484 return '<table width="100%%" summary="list"><tr>%s</tr></table>' % result
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
485
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
486 def grey(self, text): return '<font color="#909090">%s</font>' % text
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
487
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
488 def namelink(self, name, *dicts):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
489 """Make a link for an identifier, given name-to-URL mappings."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
490 for dict in dicts:
23620
a1de0bab5475 SF 563203. Replaced 'has_key()' with 'in'.
Raymond Hettinger <python@rcn.com>
parents: 23501
diff changeset
491 if name in dict:
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
492 return '<a href="%s">%s</a>' % (dict[name], name)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
493 return name
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
494
17457
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
495 def classlink(self, object, modname):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
496 """Make a link for a class."""
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
497 name, module = object.__name__, sys.modules.get(object.__module__)
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
498 if hasattr(module, name) and getattr(module, name) is object:
17457
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
499 return '<a href="%s.html#%s">%s</a>' % (
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
500 module.__name__, name, classname(object, modname))
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
501 return classname(object, modname)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
502
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
503 def modulelink(self, object):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
504 """Make a link for a module."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
505 return '<a href="%s.html">%s</a>' % (object.__name__, object.__name__)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
506
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
507 def modpkglink(self, data):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
508 """Make a link for a module or package to display in an index."""
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
509 name, path, ispackage, shadowed = data
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
510 if shadowed:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
511 return self.grey(name)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
512 if path:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
513 url = '%s.%s.html' % (path, name)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
514 else:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
515 url = '%s.html' % name
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
516 if ispackage:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
517 text = '<strong>%s</strong>&nbsp;(package)' % name
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
518 else:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
519 text = name
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
520 return '<a href="%s">%s</a>' % (url, text)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
521
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
522 def markup(self, text, escape=None, funcs={}, classes={}, methods={}):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
523 """Mark up some plain text, given a context of symbols to look for.
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
524 Each context dictionary maps object names to anchor names."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
525 escape = escape or self.escape
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
526 results = []
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
527 here = 0
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
528 pattern = re.compile(r'\b((http|ftp)://\S+[\w/]|'
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
529 r'RFC[- ]?(\d+)|'
17230
45cda1b39355 Fix some reloading problems (still more work needed).
Ka-Ping Yee <ping@zesty.ca>
parents: 17184
diff changeset
530 r'PEP[- ]?(\d+)|'
22504
25e2b580b2cf Remove unnecessary \b. It was causing the RE to miss the tailing
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 22169
diff changeset
531 r'(self\.)?(\w+))')
22867
e2f2187c3d2c Partial introduction of bools where appropriate.
Guido van Rossum <guido@python.org>
parents: 22830
diff changeset
532 while True:
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
533 match = pattern.search(text, here)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
534 if not match: break
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
535 start, end = match.span()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
536 results.append(escape(text[here:start]))
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
537
17230
45cda1b39355 Fix some reloading problems (still more work needed).
Ka-Ping Yee <ping@zesty.ca>
parents: 17184
diff changeset
538 all, scheme, rfc, pep, selfdot, name = match.groups()
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
539 if scheme:
22506
e94eddecf330 Quote href properly.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 22504
diff changeset
540 url = escape(all).replace('"', '&quot;')
e94eddecf330 Quote href properly.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 22504
diff changeset
541 results.append('<a href="%s">%s</a>' % (url, url))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
542 elif rfc:
17230
45cda1b39355 Fix some reloading problems (still more work needed).
Ka-Ping Yee <ping@zesty.ca>
parents: 17184
diff changeset
543 url = 'http://www.rfc-editor.org/rfc/rfc%d.txt' % int(rfc)
45cda1b39355 Fix some reloading problems (still more work needed).
Ka-Ping Yee <ping@zesty.ca>
parents: 17184
diff changeset
544 results.append('<a href="%s">%s</a>' % (url, escape(all)))
45cda1b39355 Fix some reloading problems (still more work needed).
Ka-Ping Yee <ping@zesty.ca>
parents: 17184
diff changeset
545 elif pep:
45169
b011366102db Update PEP URL.
Andrew M. Kuchling <amk@amk.ca>
parents: 45014
diff changeset
546 url = 'http://www.python.org/dev/peps/pep-%04d/' % int(pep)
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
547 results.append('<a href="%s">%s</a>' % (url, escape(all)))
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
548 elif text[end:end+1] == '(':
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
549 results.append(self.namelink(name, methods, funcs, classes))
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
550 elif selfdot:
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
551 results.append('self.<strong>%s</strong>' % name)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
552 else:
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
553 results.append(self.namelink(name, classes))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
554 here = end
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
555 results.append(escape(text[here:]))
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
556 return join(results, '')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
557
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
558 # ---------------------------------------------- type-specific routines
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
559
17457
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
560 def formattree(self, tree, modname, parent=None):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
561 """Produce HTML for a class tree as given by inspect.getclasstree()."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
562 result = ''
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
563 for entry in tree:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
564 if type(entry) is type(()):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
565 c, bases = entry
20074
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
566 result = result + '<dt><font face="helvetica, arial">'
17457
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
567 result = result + self.classlink(c, modname)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
568 if bases and bases != (parent,):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
569 parents = []
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
570 for base in bases:
17457
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
571 parents.append(self.classlink(base, modname))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
572 result = result + '(' + join(parents, ', ') + ')'
20074
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
573 result = result + '\n</font></dt>'
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
574 elif type(entry) is type([]):
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
575 result = result + '<dd>\n%s</dd>\n' % self.formattree(
17457
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
576 entry, modname, c)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
577 return '<dl>\n%s</dl>\n' % result
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
578
20538
fe1b6ce4eb93 SF bug [#472347] pydoc and properties.
Tim Peters <tim.peters@gmail.com>
parents: 20125
diff changeset
579 def docmodule(self, object, name=None, mod=None, *ignored):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
580 """Produce HTML documentation for a module object."""
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
581 name = object.__name__ # ignore the passed-in name
32321
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
582 try:
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
583 all = object.__all__
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
584 except AttributeError:
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
585 all = None
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
586 parts = split(name, '.')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
587 links = []
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
588 for i in range(len(parts)-1):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
589 links.append(
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
590 '<a href="%s.html"><font color="#ffffff">%s</font></a>' %
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
591 (join(parts[:i+1], '.'), parts[i]))
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
592 linkedname = join(links + parts[-1:], '.')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
593 head = '<big><big><strong>%s</strong></big></big>' % linkedname
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
594 try:
16928
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
595 path = inspect.getabsfile(object)
17484
7e829dd03f97 Use nturl2path to generate a file: URL to source files in Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 17476
diff changeset
596 url = path
7e829dd03f97 Use nturl2path to generate a file: URL to source files in Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 17476
diff changeset
597 if sys.platform == 'win32':
7e829dd03f97 Use nturl2path to generate a file: URL to source files in Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 17476
diff changeset
598 import nturl2path
7e829dd03f97 Use nturl2path to generate a file: URL to source files in Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 17476
diff changeset
599 url = nturl2path.pathname2url(path)
7e829dd03f97 Use nturl2path to generate a file: URL to source files in Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 17476
diff changeset
600 filelink = '<a href="file:%s">%s</a>' % (url, path)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
601 except TypeError:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
602 filelink = '(built-in)'
16811
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
603 info = []
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
604 if hasattr(object, '__version__'):
16811
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
605 version = str(object.__version__)
16813
c3fb044d7e6f Fix $Revision$ processing so it doesn't get eaten by CVS!
Ka-Ping Yee <ping@zesty.ca>
parents: 16812
diff changeset
606 if version[:11] == '$' + 'Revision: ' and version[-1:] == '$':
c3fb044d7e6f Fix $Revision$ processing so it doesn't get eaten by CVS!
Ka-Ping Yee <ping@zesty.ca>
parents: 16812
diff changeset
607 version = strip(version[11:-1])
16875
10b84060b7f3 Normalize case of paths in sys.path to avoid duplicates on Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 16833
diff changeset
608 info.append('version %s' % self.escape(version))
16811
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
609 if hasattr(object, '__date__'):
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
610 info.append(self.escape(str(object.__date__)))
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
611 if info:
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
612 head = head + ' (%s)' % join(info, ', ')
30396
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
613 docloc = self.getdocloc(object)
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
614 if docloc is not None:
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
615 docloc = '<br><a href="%(docloc)s">Module Docs</a>' % locals()
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
616 else:
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
617 docloc = ''
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
618 result = self.heading(
30396
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
619 head, '#ffffff', '#7799ee',
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
620 '<a href=".">index</a><br>' + filelink + docloc)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
621
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
622 modules = inspect.getmembers(object, inspect.ismodule)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
623
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
624 classes, cdict = [], {}
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
625 for key, value in inspect.getmembers(object, inspect.isclass):
33336
84fbaaa20358 Patch #934356: if a module defines __all__, believe that rather than using
Johannes Gijsbers <jlg@dds.nl>
parents: 33225
diff changeset
626 # if __all__ exists, believe it. Otherwise use old heuristic.
84fbaaa20358 Patch #934356: if a module defines __all__, believe that rather than using
Johannes Gijsbers <jlg@dds.nl>
parents: 33225
diff changeset
627 if (all is not None or
84fbaaa20358 Patch #934356: if a module defines __all__, believe that rather than using
Johannes Gijsbers <jlg@dds.nl>
parents: 33225
diff changeset
628 (inspect.getmodule(value) or object) is object):
32321
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
629 if visiblename(key, all):
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
630 classes.append((key, value))
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
631 cdict[key] = cdict[value] = '#' + key
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
632 for key, value in classes:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
633 for base in value.__bases__:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
634 key, modname = base.__name__, base.__module__
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
635 module = sys.modules.get(modname)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
636 if modname != name and module and hasattr(module, key):
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
637 if getattr(module, key) is base:
23620
a1de0bab5475 SF 563203. Replaced 'has_key()' with 'in'.
Raymond Hettinger <python@rcn.com>
parents: 23501
diff changeset
638 if not key in cdict:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
639 cdict[key] = cdict[base] = modname + '.html#' + key
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
640 funcs, fdict = [], {}
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
641 for key, value in inspect.getmembers(object, inspect.isroutine):
33336
84fbaaa20358 Patch #934356: if a module defines __all__, believe that rather than using
Johannes Gijsbers <jlg@dds.nl>
parents: 33225
diff changeset
642 # if __all__ exists, believe it. Otherwise use old heuristic.
84fbaaa20358 Patch #934356: if a module defines __all__, believe that rather than using
Johannes Gijsbers <jlg@dds.nl>
parents: 33225
diff changeset
643 if (all is not None or
84fbaaa20358 Patch #934356: if a module defines __all__, believe that rather than using
Johannes Gijsbers <jlg@dds.nl>
parents: 33225
diff changeset
644 inspect.isbuiltin(value) or inspect.getmodule(value) is object):
32321
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
645 if visiblename(key, all):
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
646 funcs.append((key, value))
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
647 fdict[key] = '#-' + key
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
648 if inspect.isfunction(value): fdict[value] = fdict[key]
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
649 data = []
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
650 for key, value in inspect.getmembers(object, isdata):
32321
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
651 if visiblename(key, all):
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
652 data.append((key, value))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
653
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
654 doc = self.markup(getdoc(object), self.preformat, fdict, cdict)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
655 doc = doc and '<tt>%s</tt>' % doc
20074
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
656 result = result + '<p>%s</p>\n' % doc
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
657
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
658 if hasattr(object, '__path__'):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
659 modpkgs = []
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
660 for importer, modname, ispkg in pkgutil.iter_modules(object.__path__):
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
661 modpkgs.append((modname, name, ispkg, 0))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
662 modpkgs.sort()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
663 contents = self.multicolumn(modpkgs, self.modpkglink)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
664 result = result + self.bigsection(
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
665 'Package Contents', '#ffffff', '#aa55cc', contents)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
666 elif modules:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
667 contents = self.multicolumn(
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
668 modules, lambda key_value, s=self: s.modulelink(key_value[1]))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
669 result = result + self.bigsection(
45385
3d2ff0146574 #2133: fix HTML color spec.
Georg Brandl <georg@python.org>
parents: 45169
diff changeset
670 'Modules', '#ffffff', '#aa55cc', contents)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
671
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
672 if classes:
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
673 classlist = map(lambda key_value: key_value[1], classes)
17457
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
674 contents = [
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
675 self.formattree(inspect.getclasstree(classlist, 1), name)]
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
676 for key, value in classes:
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
677 contents.append(self.document(value, key, name, fdict, cdict))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
678 result = result + self.bigsection(
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
679 'Classes', '#ffffff', '#ee77aa', join(contents))
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
680 if funcs:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
681 contents = []
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
682 for key, value in funcs:
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
683 contents.append(self.document(value, key, name, fdict, cdict))
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
684 result = result + self.bigsection(
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
685 'Functions', '#ffffff', '#eeaa77', join(contents))
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
686 if data:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
687 contents = []
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
688 for key, value in data:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
689 contents.append(self.document(value, key))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
690 result = result + self.bigsection(
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
691 'Data', '#ffffff', '#55aa55', join(contents, '<br>\n'))
16811
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
692 if hasattr(object, '__author__'):
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
693 contents = self.markup(str(object.__author__), self.preformat)
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
694 result = result + self.bigsection(
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
695 'Author', '#ffffff', '#7799ee', contents)
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
696 if hasattr(object, '__credits__'):
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
697 contents = self.markup(str(object.__credits__), self.preformat)
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
698 result = result + self.bigsection(
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
699 'Credits', '#ffffff', '#7799ee', contents)
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
700
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
701 return result
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
702
20538
fe1b6ce4eb93 SF bug [#472347] pydoc and properties.
Tim Peters <tim.peters@gmail.com>
parents: 20125
diff changeset
703 def docclass(self, object, name=None, mod=None, funcs={}, classes={},
fe1b6ce4eb93 SF bug [#472347] pydoc and properties.
Tim Peters <tim.peters@gmail.com>
parents: 20125
diff changeset
704 *ignored):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
705 """Produce HTML documentation for a class object."""
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
706 realname = object.__name__
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
707 name = name or realname
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
708 bases = object.__bases__
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
709
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
710 contents = []
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
711 push = contents.append
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
712
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
713 # Cute little class to pump out a horizontal rule between sections.
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
714 class HorizontalRule:
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
715 def __init__(self):
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
716 self.needone = 0
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
717 def maybe(self):
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
718 if self.needone:
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
719 push('<hr>\n')
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
720 self.needone = 1
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
721 hr = HorizontalRule()
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
722
20120
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
723 # List the mro, if non-trivial.
31436
63fa60f2d61c * Move collections.deque() in from the sandbox
Raymond Hettinger <python@rcn.com>
parents: 30821
diff changeset
724 mro = deque(inspect.getmro(object))
20120
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
725 if len(mro) > 2:
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
726 hr.maybe()
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
727 push('<dl><dt>Method resolution order:</dt>\n')
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
728 for base in mro:
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
729 push('<dd>%s</dd>\n' % self.classlink(base,
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
730 object.__module__))
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
731 push('</dl>\n')
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
732
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
733 def spill(msg, attrs, predicate):
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
734 ok, attrs = _split_list(attrs, predicate)
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
735 if ok:
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
736 hr.maybe()
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
737 push(msg)
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
738 for name, kind, homecls, value in ok:
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
739 push(self.document(getattr(object, name), name, mod,
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
740 funcs, classes, mdict, object))
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
741 push('\n')
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
742 return attrs
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
743
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
744 def spilldescriptors(msg, attrs, predicate):
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
745 ok, attrs = _split_list(attrs, predicate)
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
746 if ok:
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
747 hr.maybe()
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
748 push(msg)
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
749 for name, kind, homecls, value in ok:
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
750 push(self._docdescriptor(name, value, mod))
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
751 return attrs
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
752
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
753 def spilldata(msg, attrs, predicate):
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
754 ok, attrs = _split_list(attrs, predicate)
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
755 if ok:
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
756 hr.maybe()
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
757 push(msg)
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
758 for name, kind, homecls, value in ok:
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
759 base = self.docother(getattr(object, name), name, mod)
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
760 if (hasattr(value, '__call__') or
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
761 inspect.isdatadescriptor(value)):
23501
62688d6ac387 In both spilldata() functions, pretend that the docstring for
Guido van Rossum <guido@python.org>
parents: 22867
diff changeset
762 doc = getattr(value, "__doc__", None)
62688d6ac387 In both spilldata() functions, pretend that the docstring for
Guido van Rossum <guido@python.org>
parents: 22867
diff changeset
763 else:
62688d6ac387 In both spilldata() functions, pretend that the docstring for
Guido van Rossum <guido@python.org>
parents: 22867
diff changeset
764 doc = None
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
765 if doc is None:
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
766 push('<dl><dt>%s</dl>\n' % base)
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
767 else:
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
768 doc = self.markup(getdoc(value), self.preformat,
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
769 funcs, classes, mdict)
20074
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
770 doc = '<dd><tt>%s</tt>' % doc
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
771 push('<dl><dt>%s%s</dl>\n' % (base, doc))
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
772 push('\n')
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
773 return attrs
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
774
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
775 attrs = filter(lambda data: visiblename(data[0]),
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
776 classify_class_attrs(object))
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
777 mdict = {}
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
778 for key, kind, homecls, value in attrs:
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
779 mdict[key] = anchor = '#' + name + '-' + key
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
780 value = getattr(object, key)
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
781 try:
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
782 # The value may not be hashable (e.g., a data attr with
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
783 # a dict or list value).
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
784 mdict[value] = anchor
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
785 except TypeError:
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
786 pass
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
787
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
788 while attrs:
20124
9c2b9b76a08e List class attrs in MRO order of defining class instead of by alphabetic
Tim Peters <tim.peters@gmail.com>
parents: 20123
diff changeset
789 if mro:
31436
63fa60f2d61c * Move collections.deque() in from the sandbox
Raymond Hettinger <python@rcn.com>
parents: 30821
diff changeset
790 thisclass = mro.popleft()
20124
9c2b9b76a08e List class attrs in MRO order of defining class instead of by alphabetic
Tim Peters <tim.peters@gmail.com>
parents: 20123
diff changeset
791 else:
9c2b9b76a08e List class attrs in MRO order of defining class instead of by alphabetic
Tim Peters <tim.peters@gmail.com>
parents: 20123
diff changeset
792 thisclass = attrs[0][2]
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
793 attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass)
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
794
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
795 if thisclass is __builtin__.object:
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
796 attrs = inherited
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
797 continue
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
798 elif thisclass is object:
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
799 tag = 'defined here'
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
800 else:
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
801 tag = 'inherited from %s' % self.classlink(thisclass,
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
802 object.__module__)
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
803 tag += ':<br>\n'
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
804
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
805 # Sort attrs by name.
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
806 try:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
807 attrs.sort(key=lambda t: t[0])
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
808 except TypeError:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
809 attrs.sort(lambda t1, t2: cmp(t1[0], t2[0])) # 2.3 compat
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
810
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
811 # Pump out the attrs, segregated by kind.
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
812 attrs = spill('Methods %s' % tag, attrs,
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
813 lambda t: t[1] == 'method')
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
814 attrs = spill('Class methods %s' % tag, attrs,
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
815 lambda t: t[1] == 'class method')
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
816 attrs = spill('Static methods %s' % tag, attrs,
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
817 lambda t: t[1] == 'static method')
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
818 attrs = spilldescriptors('Data descriptors %s' % tag, attrs,
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
819 lambda t: t[1] == 'data descriptor')
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
820 attrs = spilldata('Data and other attributes %s' % tag, attrs,
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
821 lambda t: t[1] == 'data')
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
822 assert attrs == []
20124
9c2b9b76a08e List class attrs in MRO order of defining class instead of by alphabetic
Tim Peters <tim.peters@gmail.com>
parents: 20123
diff changeset
823 attrs = inherited
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
824
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
825 contents = ''.join(contents)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
826
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
827 if name == realname:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
828 title = '<a name="%s">class <strong>%s</strong></a>' % (
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
829 name, realname)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
830 else:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
831 title = '<strong>%s</strong> = <a name="%s">class %s</a>' % (
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
832 name, name, realname)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
833 if bases:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
834 parents = []
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
835 for base in bases:
17457
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
836 parents.append(self.classlink(base, object.__module__))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
837 title = title + '(%s)' % join(parents, ', ')
20074
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
838 doc = self.markup(getdoc(object), self.preformat, funcs, classes, mdict)
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
839 doc = doc and '<tt>%s<br>&nbsp;</tt>' % doc
20120
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
840
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
841 return self.section(title, '#000000', '#ffc8d8', contents, 3, doc)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
842
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
843 def formatvalue(self, object):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
844 """Format an argument default value as text."""
20074
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
845 return self.grey('=' + self.repr(object))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
846
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
847 def docroutine(self, object, name=None, mod=None,
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
848 funcs={}, classes={}, methods={}, cl=None):
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
849 """Produce HTML documentation for a function or method object."""
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
850 realname = object.__name__
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
851 name = name or realname
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
852 anchor = (cl and cl.__name__ or '') + '-' + name
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
853 note = ''
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
854 skipdocs = 0
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
855 if inspect.ismethod(object):
17456
3bda59071389 Fix call to ModuleScanner from GUI search interface.
Ka-Ping Yee <ping@zesty.ca>
parents: 17452
diff changeset
856 imclass = object.im_class
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
857 if cl:
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
858 if imclass is not cl:
17457
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
859 note = ' from ' + self.classlink(imclass, mod)
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
860 else:
41175
ca338d563a7a Patch #1194449: correctly detect unbound methods in pydoc.
Georg Brandl <georg@python.org>
parents: 41166
diff changeset
861 if object.im_self is not None:
17457
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
862 note = ' method of %s instance' % self.classlink(
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
863 object.im_self.__class__, mod)
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
864 else:
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
865 note = ' unbound %s method' % self.classlink(imclass,mod)
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
866 object = object.im_func
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
867
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
868 if name == realname:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
869 title = '<a name="%s"><strong>%s</strong></a>' % (anchor, realname)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
870 else:
23620
a1de0bab5475 SF 563203. Replaced 'has_key()' with 'in'.
Raymond Hettinger <python@rcn.com>
parents: 23501
diff changeset
871 if (cl and realname in cl.__dict__ and
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
872 cl.__dict__[realname] is object):
17184
56d195f21b4f Browser compatibility fixes.
Ka-Ping Yee <ping@zesty.ca>
parents: 17182
diff changeset
873 reallink = '<a href="#%s">%s</a>' % (
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
874 cl.__name__ + '-' + realname, realname)
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
875 skipdocs = 1
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
876 else:
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
877 reallink = realname
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
878 title = '<a name="%s"><strong>%s</strong></a> = %s' % (
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
879 anchor, name, reallink)
19993
28ef22a2598e Since inspect.isfunction(obj) is a precondition for calling
Tim Peters <tim.peters@gmail.com>
parents: 19989
diff changeset
880 if inspect.isfunction(object):
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
881 args, varargs, varkw, defaults = inspect.getargspec(object)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
882 argspec = inspect.formatargspec(
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
883 args, varargs, varkw, defaults, formatvalue=self.formatvalue)
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
884 if realname == '<lambda>':
20783
a2b11d00b697 SF patch #474485: pydoc generates some bad html, from Rich Salz.
Tim Peters <tim.peters@gmail.com>
parents: 20538
diff changeset
885 title = '<strong>%s</strong> <em>lambda</em> ' % name
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
886 argspec = argspec[1:-1] # remove parentheses
19993
28ef22a2598e Since inspect.isfunction(obj) is a precondition for calling
Tim Peters <tim.peters@gmail.com>
parents: 19989
diff changeset
887 else:
28ef22a2598e Since inspect.isfunction(obj) is a precondition for calling
Tim Peters <tim.peters@gmail.com>
parents: 19989
diff changeset
888 argspec = '(...)'
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
889
20074
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
890 decl = title + argspec + (note and self.grey(
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
891 '<font face="helvetica, arial">%s</font>' % note))
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
892
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
893 if skipdocs:
20074
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
894 return '<dl><dt>%s</dt></dl>\n' % decl
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
895 else:
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
896 doc = self.markup(
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
897 getdoc(object), self.preformat, funcs, classes, methods)
20074
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
898 doc = doc and '<dd><tt>%s</tt></dd>' % doc
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
899 return '<dl><dt>%s</dt>%s</dl>\n' % (decl, doc)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
900
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
901 def _docdescriptor(self, name, value, mod):
33935
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
902 results = []
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
903 push = results.append
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
904
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
905 if name:
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
906 push('<dl><dt><strong>%s</strong></dt>\n' % name)
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
907 if value.__doc__ is not None:
34618
c99ae8635f3b Use getdoc(object) instead of object.__doc__ to fix indentation problems.
Ka-Ping Yee <ping@zesty.ca>
parents: 34545
diff changeset
908 doc = self.markup(getdoc(value), self.preformat)
33935
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
909 push('<dd><tt>%s</tt></dd>\n' % doc)
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
910 push('</dl>\n')
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
911
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
912 return ''.join(results)
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
913
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
914 def docproperty(self, object, name=None, mod=None, cl=None):
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
915 """Produce html documentation for a property."""
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
916 return self._docdescriptor(name, object, mod)
33935
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
917
20538
fe1b6ce4eb93 SF bug [#472347] pydoc and properties.
Tim Peters <tim.peters@gmail.com>
parents: 20125
diff changeset
918 def docother(self, object, name=None, mod=None, *ignored):
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
919 """Produce HTML documentation for a data object."""
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
920 lhs = name and '<strong>%s</strong> = ' % name or ''
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
921 return lhs + self.repr(object)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
922
39226
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
923 def docdata(self, object, name=None, mod=None, cl=None):
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
924 """Produce html documentation for a data descriptor."""
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
925 return self._docdescriptor(name, object, mod)
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
926
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
927 def index(self, dir, shadowed=None):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
928 """Generate an HTML index for a directory of modules."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
929 modpkgs = []
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
930 if shadowed is None: shadowed = {}
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
931 for importer, name, ispkg in pkgutil.iter_modules([dir]):
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
932 modpkgs.append((name, '', ispkg, name in shadowed))
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
933 shadowed[name] = 1
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
934
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
935 modpkgs.sort()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
936 contents = self.multicolumn(modpkgs, self.modpkglink)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
937 return self.bigsection(dir, '#ffffff', '#ee77aa', contents)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
938
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
939 # -------------------------------------------- text documentation generator
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
940
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
941 class TextRepr(Repr):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
942 """Class for safely making a text representation of a Python object."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
943 def __init__(self):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
944 Repr.__init__(self)
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
945 self.maxlist = self.maxtuple = 20
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
946 self.maxdict = 10
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
947 self.maxstring = self.maxother = 100
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
948
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
949 def repr1(self, x, level):
29603
fea8dee27332 (HTML|Text)Repr.repr1: Guard against objects whos types have no __name__
Skip Montanaro <skip@pobox.com>
parents: 29463
diff changeset
950 if hasattr(type(x), '__name__'):
fea8dee27332 (HTML|Text)Repr.repr1: Guard against objects whos types have no __name__
Skip Montanaro <skip@pobox.com>
parents: 29463
diff changeset
951 methodname = 'repr_' + join(split(type(x).__name__), '_')
fea8dee27332 (HTML|Text)Repr.repr1: Guard against objects whos types have no __name__
Skip Montanaro <skip@pobox.com>
parents: 29463
diff changeset
952 if hasattr(self, methodname):
fea8dee27332 (HTML|Text)Repr.repr1: Guard against objects whos types have no __name__
Skip Montanaro <skip@pobox.com>
parents: 29463
diff changeset
953 return getattr(self, methodname)(x, level)
fea8dee27332 (HTML|Text)Repr.repr1: Guard against objects whos types have no __name__
Skip Montanaro <skip@pobox.com>
parents: 29463
diff changeset
954 return cram(stripid(repr(x)), self.maxother)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
955
16923
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
956 def repr_string(self, x, level):
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
957 test = cram(x, self.maxstring)
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
958 testrepr = repr(test)
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
959 if '\\' in test and '\\' not in replace(testrepr, r'\\', ''):
16923
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
960 # Backslashes are only literal in the string and are never
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
961 # needed to make any special characters, so show a raw string.
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
962 return 'r' + testrepr[0] + test + testrepr[0]
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
963 return testrepr
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
964
22169
4d5becc6902b add repr_str as alias for repr_string in both HTMLRepr and TextRepr classes
Skip Montanaro <skip@pobox.com>
parents: 22117
diff changeset
965 repr_str = repr_string
4d5becc6902b add repr_str as alias for repr_string in both HTMLRepr and TextRepr classes
Skip Montanaro <skip@pobox.com>
parents: 22117
diff changeset
966
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
967 def repr_instance(self, x, level):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
968 try:
16875
10b84060b7f3 Normalize case of paths in sys.path to avoid duplicates on Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 16833
diff changeset
969 return cram(stripid(repr(x)), self.maxstring)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
970 except:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
971 return '<%s instance>' % x.__class__.__name__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
972
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
973 class TextDoc(Doc):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
974 """Formatter class for text documentation."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
975
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
976 # ------------------------------------------- text formatting utilities
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
977
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
978 _repr_instance = TextRepr()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
979 repr = _repr_instance.repr
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
980
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
981 def bold(self, text):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
982 """Format a string in bold by overstriking."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
983 return join(map(lambda ch: ch + '\b' + ch, text), '')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
984
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
985 def indent(self, text, prefix=' '):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
986 """Indent text by prepending a given prefix to each line."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
987 if not text: return ''
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
988 lines = split(text, '\n')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
989 lines = map(lambda line, prefix=prefix: prefix + line, lines)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
990 if lines: lines[-1] = rstrip(lines[-1])
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
991 return join(lines, '\n')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
992
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
993 def section(self, title, contents):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
994 """Format a section with a given heading."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
995 return self.bold(title) + '\n' + rstrip(self.indent(contents)) + '\n\n'
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
996
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
997 # ---------------------------------------------- type-specific routines
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
998
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
999 def formattree(self, tree, modname, parent=None, prefix=''):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1000 """Render in text a class tree as returned by inspect.getclasstree()."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1001 result = ''
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1002 for entry in tree:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1003 if type(entry) is type(()):
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1004 c, bases = entry
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1005 result = result + prefix + classname(c, modname)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1006 if bases and bases != (parent,):
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1007 parents = map(lambda c, m=modname: classname(c, m), bases)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1008 result = result + '(%s)' % join(parents, ', ')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1009 result = result + '\n'
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1010 elif type(entry) is type([]):
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1011 result = result + self.formattree(
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1012 entry, modname, c, prefix + ' ')
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1013 return result
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1014
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1015 def docmodule(self, object, name=None, mod=None):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1016 """Produce text documentation for a given module object."""
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1017 name = object.__name__ # ignore the passed-in name
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
1018 synop, desc = splitdoc(getdoc(object))
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
1019 result = self.section('NAME', name + (synop and ' - ' + synop))
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1020
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1021 try:
32321
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
1022 all = object.__all__
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
1023 except AttributeError:
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
1024 all = None
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
1025
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
1026 try:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1027 file = inspect.getabsfile(object)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1028 except TypeError:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1029 file = '(built-in)'
16928
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
1030 result = result + self.section('FILE', file)
30396
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
1031
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
1032 docloc = self.getdocloc(object)
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
1033 if docloc is not None:
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
1034 result = result + self.section('MODULE DOCS', docloc)
e44a359c898e display link to module docs when it looks like the object module is a core
Skip Montanaro <skip@pobox.com>
parents: 29603
diff changeset
1035
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
1036 if desc:
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
1037 result = result + self.section('DESCRIPTION', desc)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1038
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1039 classes = []
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1040 for key, value in inspect.getmembers(object, inspect.isclass):
33336
84fbaaa20358 Patch #934356: if a module defines __all__, believe that rather than using
Johannes Gijsbers <jlg@dds.nl>
parents: 33225
diff changeset
1041 # if __all__ exists, believe it. Otherwise use old heuristic.
84fbaaa20358 Patch #934356: if a module defines __all__, believe that rather than using
Johannes Gijsbers <jlg@dds.nl>
parents: 33225
diff changeset
1042 if (all is not None
84fbaaa20358 Patch #934356: if a module defines __all__, believe that rather than using
Johannes Gijsbers <jlg@dds.nl>
parents: 33225
diff changeset
1043 or (inspect.getmodule(value) or object) is object):
32321
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
1044 if visiblename(key, all):
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
1045 classes.append((key, value))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1046 funcs = []
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1047 for key, value in inspect.getmembers(object, inspect.isroutine):
33336
84fbaaa20358 Patch #934356: if a module defines __all__, believe that rather than using
Johannes Gijsbers <jlg@dds.nl>
parents: 33225
diff changeset
1048 # if __all__ exists, believe it. Otherwise use old heuristic.
84fbaaa20358 Patch #934356: if a module defines __all__, believe that rather than using
Johannes Gijsbers <jlg@dds.nl>
parents: 33225
diff changeset
1049 if (all is not None or
84fbaaa20358 Patch #934356: if a module defines __all__, believe that rather than using
Johannes Gijsbers <jlg@dds.nl>
parents: 33225
diff changeset
1050 inspect.isbuiltin(value) or inspect.getmodule(value) is object):
32321
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
1051 if visiblename(key, all):
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
1052 funcs.append((key, value))
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1053 data = []
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1054 for key, value in inspect.getmembers(object, isdata):
32321
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
1055 if visiblename(key, all):
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1056 data.append((key, value))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1057
44860
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1058 modpkgs = []
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1059 modpkgs_names = set()
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1060 if hasattr(object, '__path__'):
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1061 for importer, modname, ispkg in pkgutil.iter_modules(object.__path__):
44860
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1062 modpkgs_names.add(modname)
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1063 if ispkg:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1064 modpkgs.append(modname + ' (package)')
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1065 else:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1066 modpkgs.append(modname)
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1067
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1068 modpkgs.sort()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1069 result = result + self.section(
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1070 'PACKAGE CONTENTS', join(modpkgs, '\n'))
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1071
44860
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1072 # Detect submodules as sometimes created by C extensions
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1073 submodules = []
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1074 for key, value in inspect.getmembers(object, inspect.ismodule):
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1075 if value.__name__.startswith(name + '.') and key not in modpkgs_names:
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1076 submodules.append(key)
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1077 if submodules:
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1078 submodules.sort()
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1079 result = result + self.section(
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1080 'SUBMODULES', join(submodules, '\n'))
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1081
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1082 if classes:
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
1083 classlist = map(lambda key_value: key_value[1], classes)
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1084 contents = [self.formattree(
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1085 inspect.getclasstree(classlist, 1), name)]
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1086 for key, value in classes:
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1087 contents.append(self.document(value, key, name))
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1088 result = result + self.section('CLASSES', join(contents, '\n'))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1089
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1090 if funcs:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1091 contents = []
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1092 for key, value in funcs:
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1093 contents.append(self.document(value, key, name))
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1094 result = result + self.section('FUNCTIONS', join(contents, '\n'))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1095
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1096 if data:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1097 contents = []
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1098 for key, value in data:
35663
5611db451a39 bug [ 729103 ] Cannot retrieve name of super object
Georg Brandl <georg@python.org>
parents: 35277
diff changeset
1099 contents.append(self.docother(value, key, name, maxlen=70))
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1100 result = result + self.section('DATA', join(contents, '\n'))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1101
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1102 if hasattr(object, '__version__'):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1103 version = str(object.__version__)
16875
10b84060b7f3 Normalize case of paths in sys.path to avoid duplicates on Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 16833
diff changeset
1104 if version[:11] == '$' + 'Revision: ' and version[-1:] == '$':
10b84060b7f3 Normalize case of paths in sys.path to avoid duplicates on Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 16833
diff changeset
1105 version = strip(version[11:-1])
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1106 result = result + self.section('VERSION', version)
16811
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
1107 if hasattr(object, '__date__'):
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
1108 result = result + self.section('DATE', str(object.__date__))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1109 if hasattr(object, '__author__'):
16811
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
1110 result = result + self.section('AUTHOR', str(object.__author__))
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
1111 if hasattr(object, '__credits__'):
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
1112 result = result + self.section('CREDITS', str(object.__credits__))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1113 return result
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1114
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1115 def docclass(self, object, name=None, mod=None):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1116 """Produce text documentation for a given class object."""
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1117 realname = object.__name__
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1118 name = name or realname
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1119 bases = object.__bases__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1120
20120
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
1121 def makename(c, m=object.__module__):
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
1122 return classname(c, m)
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
1123
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1124 if name == realname:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1125 title = 'class ' + self.bold(realname)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1126 else:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1127 title = self.bold(name) + ' = class ' + realname
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1128 if bases:
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
1129 parents = map(makename, bases)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1130 title = title + '(%s)' % join(parents, ', ')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1131
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1132 doc = getdoc(object)
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1133 contents = doc and [doc + '\n'] or []
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1134 push = contents.append
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1135
20120
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
1136 # List the mro, if non-trivial.
31436
63fa60f2d61c * Move collections.deque() in from the sandbox
Raymond Hettinger <python@rcn.com>
parents: 30821
diff changeset
1137 mro = deque(inspect.getmro(object))
20120
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
1138 if len(mro) > 2:
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
1139 push("Method resolution order:")
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
1140 for base in mro:
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
1141 push(' ' + makename(base))
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
1142 push('')
0176f61af845 Display a class's method resolution order, if it's non-trivial. "Trivial"
Tim Peters <tim.peters@gmail.com>
parents: 20079
diff changeset
1143
20072
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1144 # Cute little class to pump out a horizontal rule between sections.
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1145 class HorizontalRule:
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1146 def __init__(self):
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1147 self.needone = 0
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1148 def maybe(self):
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1149 if self.needone:
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1150 push('-' * 70)
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1151 self.needone = 1
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1152 hr = HorizontalRule()
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1153
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1154 def spill(msg, attrs, predicate):
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1155 ok, attrs = _split_list(attrs, predicate)
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1156 if ok:
20072
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1157 hr.maybe()
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1158 push(msg)
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1159 for name, kind, homecls, value in ok:
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1160 push(self.document(getattr(object, name),
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1161 name, mod, object))
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1162 return attrs
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1163
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1164 def spilldescriptors(msg, attrs, predicate):
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1165 ok, attrs = _split_list(attrs, predicate)
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1166 if ok:
20072
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1167 hr.maybe()
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1168 push(msg)
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1169 for name, kind, homecls, value in ok:
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1170 push(self._docdescriptor(name, value, mod))
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1171 return attrs
20050
6e93a1586800 Try to do for pydoc's GUI mode what the earlier checkin did for text
Tim Peters <tim.peters@gmail.com>
parents: 20048
diff changeset
1172
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1173 def spilldata(msg, attrs, predicate):
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1174 ok, attrs = _split_list(attrs, predicate)
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1175 if ok:
20072
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1176 hr.maybe()
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1177 push(msg)
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1178 for name, kind, homecls, value in ok:
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
1179 if (hasattr(value, '__call__') or
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
1180 inspect.isdatadescriptor(value)):
34618
c99ae8635f3b Use getdoc(object) instead of object.__doc__ to fix indentation problems.
Ka-Ping Yee <ping@zesty.ca>
parents: 34545
diff changeset
1181 doc = getdoc(value)
23501
62688d6ac387 In both spilldata() functions, pretend that the docstring for
Guido van Rossum <guido@python.org>
parents: 22867
diff changeset
1182 else:
62688d6ac387 In both spilldata() functions, pretend that the docstring for
Guido van Rossum <guido@python.org>
parents: 22867
diff changeset
1183 doc = None
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1184 push(self.docother(getattr(object, name),
35663
5611db451a39 bug [ 729103 ] Cannot retrieve name of super object
Georg Brandl <georg@python.org>
parents: 35277
diff changeset
1185 name, mod, maxlen=70, doc=doc) + '\n')
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1186 return attrs
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1187
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
1188 attrs = filter(lambda data: visiblename(data[0]),
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1189 classify_class_attrs(object))
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1190 while attrs:
20124
9c2b9b76a08e List class attrs in MRO order of defining class instead of by alphabetic
Tim Peters <tim.peters@gmail.com>
parents: 20123
diff changeset
1191 if mro:
31436
63fa60f2d61c * Move collections.deque() in from the sandbox
Raymond Hettinger <python@rcn.com>
parents: 30821
diff changeset
1192 thisclass = mro.popleft()
20124
9c2b9b76a08e List class attrs in MRO order of defining class instead of by alphabetic
Tim Peters <tim.peters@gmail.com>
parents: 20123
diff changeset
1193 else:
9c2b9b76a08e List class attrs in MRO order of defining class instead of by alphabetic
Tim Peters <tim.peters@gmail.com>
parents: 20123
diff changeset
1194 thisclass = attrs[0][2]
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1195 attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass)
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1196
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
1197 if thisclass is __builtin__.object:
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
1198 attrs = inherited
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
1199 continue
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
1200 elif thisclass is object:
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1201 tag = "defined here"
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1202 else:
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1203 tag = "inherited from %s" % classname(thisclass,
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1204 object.__module__)
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1205
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1206 # Sort attrs by name.
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
1207 attrs.sort()
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1208
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1209 # Pump out the attrs, segregated by kind.
20072
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1210 attrs = spill("Methods %s:\n" % tag, attrs,
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1211 lambda t: t[1] == 'method')
20072
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1212 attrs = spill("Class methods %s:\n" % tag, attrs,
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1213 lambda t: t[1] == 'class method')
20072
399d777af048 + Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
Tim Peters <tim.peters@gmail.com>
parents: 20051
diff changeset
1214 attrs = spill("Static methods %s:\n" % tag, attrs,
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1215 lambda t: t[1] == 'static method')
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1216 attrs = spilldescriptors("Data descriptors %s:\n" % tag, attrs,
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1217 lambda t: t[1] == 'data descriptor')
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
1218 attrs = spilldata("Data and other attributes %s:\n" % tag, attrs,
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
1219 lambda t: t[1] == 'data')
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1220 assert attrs == []
20124
9c2b9b76a08e List class attrs in MRO order of defining class instead of by alphabetic
Tim Peters <tim.peters@gmail.com>
parents: 20123
diff changeset
1221 attrs = inherited
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1222
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1223 contents = '\n'.join(contents)
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1224 if not contents:
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1225 return title + '\n'
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1226 return title + '\n' + self.indent(rstrip(contents), ' | ') + '\n'
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1227
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1228 def formatvalue(self, object):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1229 """Format an argument default value as text."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1230 return '=' + self.repr(object)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1231
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1232 def docroutine(self, object, name=None, mod=None, cl=None):
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1233 """Produce text documentation for a function or method object."""
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1234 realname = object.__name__
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1235 name = name or realname
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1236 note = ''
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
1237 skipdocs = 0
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1238 if inspect.ismethod(object):
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1239 imclass = object.im_class
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
1240 if cl:
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1241 if imclass is not cl:
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1242 note = ' from ' + classname(imclass, mod)
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
1243 else:
41175
ca338d563a7a Patch #1194449: correctly detect unbound methods in pydoc.
Georg Brandl <georg@python.org>
parents: 41166
diff changeset
1244 if object.im_self is not None:
17457
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
1245 note = ' method of %s instance' % classname(
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
1246 object.im_self.__class__, mod)
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
1247 else:
66a7c8c8dd27 Fix linking to classes (in class tree, and add links on unbound methods).
Ka-Ping Yee <ping@zesty.ca>
parents: 17456
diff changeset
1248 note = ' unbound %s method' % classname(imclass,mod)
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1249 object = object.im_func
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1250
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1251 if name == realname:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1252 title = self.bold(realname)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1253 else:
23620
a1de0bab5475 SF 563203. Replaced 'has_key()' with 'in'.
Raymond Hettinger <python@rcn.com>
parents: 23501
diff changeset
1254 if (cl and realname in cl.__dict__ and
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
1255 cl.__dict__[realname] is object):
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
1256 skipdocs = 1
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1257 title = self.bold(name) + ' = ' + realname
19993
28ef22a2598e Since inspect.isfunction(obj) is a precondition for calling
Tim Peters <tim.peters@gmail.com>
parents: 19989
diff changeset
1258 if inspect.isfunction(object):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1259 args, varargs, varkw, defaults = inspect.getargspec(object)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1260 argspec = inspect.formatargspec(
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1261 args, varargs, varkw, defaults, formatvalue=self.formatvalue)
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1262 if realname == '<lambda>':
36545
1232e87cb816 The names of lambda functions are now properly displayed in pydoc.
Georg Brandl <georg@python.org>
parents: 35838
diff changeset
1263 title = self.bold(name) + ' lambda '
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1264 argspec = argspec[1:-1] # remove parentheses
19993
28ef22a2598e Since inspect.isfunction(obj) is a precondition for calling
Tim Peters <tim.peters@gmail.com>
parents: 19989
diff changeset
1265 else:
28ef22a2598e Since inspect.isfunction(obj) is a precondition for calling
Tim Peters <tim.peters@gmail.com>
parents: 19989
diff changeset
1266 argspec = '(...)'
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1267 decl = title + argspec + note
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1268
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
1269 if skipdocs:
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
1270 return decl + '\n'
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1271 else:
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
1272 doc = getdoc(object) or ''
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
1273 return decl + '\n' + (doc and rstrip(self.indent(doc)) + '\n')
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1274
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1275 def _docdescriptor(self, name, value, mod):
33935
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1276 results = []
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1277 push = results.append
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1278
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1279 if name:
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1280 push(self.bold(name))
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1281 push('\n')
33935
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1282 doc = getdoc(value) or ''
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1283 if doc:
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1284 push(self.indent(doc))
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1285 push('\n')
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1286 return ''.join(results)
33935
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1287
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1288 def docproperty(self, object, name=None, mod=None, cl=None):
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1289 """Produce text documentation for a property."""
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1290 return self._docdescriptor(name, object, mod)
33935
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1291
39226
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1292 def docdata(self, object, name=None, mod=None, cl=None):
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1293 """Produce text documentation for a data descriptor."""
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1294 return self._docdescriptor(name, object, mod)
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1295
35663
5611db451a39 bug [ 729103 ] Cannot retrieve name of super object
Georg Brandl <georg@python.org>
parents: 35277
diff changeset
1296 def docother(self, object, name=None, mod=None, parent=None, maxlen=None, doc=None):
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1297 """Produce text documentation for a data object."""
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1298 repr = self.repr(object)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1299 if maxlen:
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1300 line = (name and name + ' = ' or '') + repr
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1301 chop = maxlen - len(line)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1302 if chop < 0: repr = repr[:chop] + '...'
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1303 line = (name and self.bold(name) + ' = ' or '') + repr
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1304 if doc is not None:
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1305 line += '\n' + self.indent(str(doc))
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1306 return line
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1307
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1308 # --------------------------------------------------------- user interfaces
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1309
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1310 def pager(text):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1311 """The first time this is called, determine what kind of pager to use."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1312 global pager
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1313 pager = getpager()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1314 pager(text)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1315
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1316 def getpager():
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1317 """Decide what method to use for paging through text."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1318 if type(sys.stdout) is not types.FileType:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1319 return plainpager
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1320 if not sys.stdin.isatty() or not sys.stdout.isatty():
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1321 return plainpager
23620
a1de0bab5475 SF 563203. Replaced 'has_key()' with 'in'.
Raymond Hettinger <python@rcn.com>
parents: 23501
diff changeset
1322 if 'PAGER' in os.environ:
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
1323 if sys.platform == 'win32': # pipes completely broken in Windows
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1324 return lambda text: tempfilepager(plain(text), os.environ['PAGER'])
34545
9d66fba78444 Replace list of constants with tuples of constants.
Raymond Hettinger <python@rcn.com>
parents: 34369
diff changeset
1325 elif os.environ.get('TERM') in ('dumb', 'emacs'):
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1326 return lambda text: pipepager(plain(text), os.environ['PAGER'])
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
1327 else:
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1328 return lambda text: pipepager(text, os.environ['PAGER'])
35837
a8649869cb60 Accept patch to resolve SF bug #651124.
Ka-Ping Yee <ping@zesty.ca>
parents: 35806
diff changeset
1329 if os.environ.get('TERM') in ('dumb', 'emacs'):
a8649869cb60 Accept patch to resolve SF bug #651124.
Ka-Ping Yee <ping@zesty.ca>
parents: 35806
diff changeset
1330 return plainpager
22117
1046964896a1 OS/2 more program behaves like Win32 more
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 20783
diff changeset
1331 if sys.platform == 'win32' or sys.platform.startswith('os2'):
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1332 return lambda text: tempfilepager(plain(text), 'more <')
25454
4d367872fcc6 try executing 'less' in a parenthesized subshell - prevents systems like
Skip Montanaro <skip@pobox.com>
parents: 24977
diff changeset
1333 if hasattr(os, 'system') and os.system('(less) 2>/dev/null') == 0:
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1334 return lambda text: pipepager(text, 'less')
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1335
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1336 import tempfile
24710
11c701038805 Massive changes from SF 589982 (tempfile.py rewrite, by Zack
Guido van Rossum <guido@python.org>
parents: 24606
diff changeset
1337 (fd, filename) = tempfile.mkstemp()
11c701038805 Massive changes from SF 589982 (tempfile.py rewrite, by Zack
Guido van Rossum <guido@python.org>
parents: 24606
diff changeset
1338 os.close(fd)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1339 try:
47987
ebe932329246 #3045: fix pydoc behavior for TEMP path with spaces.
Georg Brandl <georg@python.org>
parents: 47873
diff changeset
1340 if hasattr(os, 'system') and os.system('more "%s"' % filename) == 0:
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1341 return lambda text: pipepager(text, 'more')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1342 else:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1343 return ttypager
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1344 finally:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1345 os.unlink(filename)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1346
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1347 def plain(text):
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1348 """Remove boldface formatting from text."""
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1349 return re.sub('.\b', '', text)
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1350
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1351 def pipepager(text, cmd):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1352 """Page through text by feeding it to another program."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1353 pipe = os.popen(cmd, 'w')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1354 try:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1355 pipe.write(text)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1356 pipe.close()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1357 except IOError:
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1358 pass # Ignore broken pipes caused by quitting the pager program.
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1359
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1360 def tempfilepager(text, cmd):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1361 """Page through text by invoking a program on a temporary file."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1362 import tempfile
27743
b331e5e5cc4a SF bug 666444: 'help' makes linefeed only under Win32.
Tim Peters <tim.peters@gmail.com>
parents: 26814
diff changeset
1363 filename = tempfile.mktemp()
b331e5e5cc4a SF bug 666444: 'help' makes linefeed only under Win32.
Tim Peters <tim.peters@gmail.com>
parents: 26814
diff changeset
1364 file = open(filename, 'w')
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1365 file.write(text)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1366 file.close()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1367 try:
47987
ebe932329246 #3045: fix pydoc behavior for TEMP path with spaces.
Georg Brandl <georg@python.org>
parents: 47873
diff changeset
1368 os.system(cmd + ' "' + filename + '"')
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1369 finally:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1370 os.unlink(filename)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1371
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1372 def ttypager(text):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1373 """Page through text on a text terminal."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1374 lines = split(plain(text), '\n')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1375 try:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1376 import tty
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1377 fd = sys.stdin.fileno()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1378 old = tty.tcgetattr(fd)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1379 tty.setcbreak(fd)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1380 getchar = lambda: sys.stdin.read(1)
16819
53e8ebd11620 Macintosh compatibility.
Ka-Ping Yee <ping@zesty.ca>
parents: 16818
diff changeset
1381 except (ImportError, AttributeError):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1382 tty = None
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1383 getchar = lambda: sys.stdin.readline()[:-1][:1]
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1384
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1385 try:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1386 r = inc = os.environ.get('LINES', 25) - 1
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1387 sys.stdout.write(join(lines[:inc], '\n') + '\n')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1388 while lines[r:]:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1389 sys.stdout.write('-- more --')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1390 sys.stdout.flush()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1391 c = getchar()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1392
34545
9d66fba78444 Replace list of constants with tuples of constants.
Raymond Hettinger <python@rcn.com>
parents: 34369
diff changeset
1393 if c in ('q', 'Q'):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1394 sys.stdout.write('\r \r')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1395 break
34545
9d66fba78444 Replace list of constants with tuples of constants.
Raymond Hettinger <python@rcn.com>
parents: 34369
diff changeset
1396 elif c in ('\r', '\n'):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1397 sys.stdout.write('\r \r' + lines[r] + '\n')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1398 r = r + 1
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1399 continue
34545
9d66fba78444 Replace list of constants with tuples of constants.
Raymond Hettinger <python@rcn.com>
parents: 34369
diff changeset
1400 if c in ('b', 'B', '\x1b'):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1401 r = r - inc - inc
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1402 if r < 0: r = 0
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1403 sys.stdout.write('\n' + join(lines[r:r+inc], '\n') + '\n')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1404 r = r + inc
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1405
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1406 finally:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1407 if tty:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1408 tty.tcsetattr(fd, tty.TCSAFLUSH, old)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1409
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1410 def plainpager(text):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1411 """Simply print unformatted text. This is the ultimate fallback."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1412 sys.stdout.write(plain(text))
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1413
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1414 def describe(thing):
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
1415 """Produce a short description of the given thing."""
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1416 if inspect.ismodule(thing):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1417 if thing.__name__ in sys.builtin_module_names:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1418 return 'built-in module ' + thing.__name__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1419 if hasattr(thing, '__path__'):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1420 return 'package ' + thing.__name__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1421 else:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1422 return 'module ' + thing.__name__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1423 if inspect.isbuiltin(thing):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1424 return 'built-in function ' + thing.__name__
39226
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1425 if inspect.isgetsetdescriptor(thing):
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1426 return 'getset descriptor %s.%s.%s' % (
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1427 thing.__objclass__.__module__, thing.__objclass__.__name__,
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1428 thing.__name__)
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1429 if inspect.ismemberdescriptor(thing):
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1430 return 'member descriptor %s.%s.%s' % (
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1431 thing.__objclass__.__module__, thing.__objclass__.__name__,
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1432 thing.__name__)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1433 if inspect.isclass(thing):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1434 return 'class ' + thing.__name__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1435 if inspect.isfunction(thing):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1436 return 'function ' + thing.__name__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1437 if inspect.ismethod(thing):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1438 return 'method ' + thing.__name__
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1439 if type(thing) is types.InstanceType:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1440 return 'instance of ' + thing.__class__.__name__
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1441 return type(thing).__name__
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1442
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1443 def locate(path, forceload=0):
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1444 """Locate an object by name or dotted path, importing as necessary."""
27904
9bdaccd8a908 Fix for SF 686380, from SF patch 686771 by Ping. (errors trying to
Guido van Rossum <guido@python.org>
parents: 27759
diff changeset
1445 parts = [part for part in split(path, '.') if part]
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1446 module, n = None, 0
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1447 while n < len(parts):
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1448 nextmodule = safeimport(join(parts[:n+1], '.'), forceload)
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1449 if nextmodule: module, n = nextmodule, n + 1
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1450 else: break
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1451 if module:
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1452 object = module
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1453 for part in parts[n:]:
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1454 try: object = getattr(object, part)
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1455 except AttributeError: return None
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1456 return object
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1457 else:
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1458 if hasattr(__builtin__, path):
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1459 return getattr(__builtin__, path)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1460
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1461 # --------------------------------------- interactive interpreter interface
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1462
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1463 text = TextDoc()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1464 html = HTMLDoc()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1465
40630
3d79bc6ed6ec Handle old-style instances more gracefully (display documentation on
Ka-Ping Yee <ping@zesty.ca>
parents: 40479
diff changeset
1466 class _OldStyleClass: pass
3d79bc6ed6ec Handle old-style instances more gracefully (display documentation on
Ka-Ping Yee <ping@zesty.ca>
parents: 40479
diff changeset
1467 _OLD_INSTANCE_TYPE = type(_OldStyleClass())
3d79bc6ed6ec Handle old-style instances more gracefully (display documentation on
Ka-Ping Yee <ping@zesty.ca>
parents: 40479
diff changeset
1468
24740
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1469 def resolve(thing, forceload=0):
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1470 """Given an object or a path to an object, get the object and its name."""
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1471 if isinstance(thing, str):
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1472 object = locate(thing, forceload)
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1473 if not object:
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1474 raise ImportError, 'no Python documentation found for %r' % thing
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1475 return object, thing
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1476 else:
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1477 return thing, getattr(thing, '__name__', None)
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1478
41166
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1479 def render_doc(thing, title='Python Library Documentation: %s', forceload=0):
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1480 """Render text documentation, given an object or a path to an object."""
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1481 object, name = resolve(thing, forceload)
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1482 desc = describe(object)
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1483 module = inspect.getmodule(object)
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1484 if name and '.' in name:
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1485 desc += ' in ' + name[:name.rfind('.')]
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1486 elif module and module is not object:
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1487 desc += ' in module ' + module.__name__
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1488 if type(object) is _OLD_INSTANCE_TYPE:
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1489 # If the passed object is an instance of an old-style class,
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1490 # document its available methods instead of its value.
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1491 object = object.__class__
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1492 elif not (inspect.ismodule(object) or
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1493 inspect.isclass(object) or
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1494 inspect.isroutine(object) or
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1495 inspect.isgetsetdescriptor(object) or
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1496 inspect.ismemberdescriptor(object) or
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1497 isinstance(object, property)):
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1498 # If the passed object is a piece of data or an instance,
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1499 # document its available methods instead of its value.
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1500 object = type(object)
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1501 desc += ' object'
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1502 return title % desc + '\n\n' + text.document(object, name)
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1503
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1504 def doc(thing, title='Python Library Documentation: %s', forceload=0):
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1505 """Display text documentation, given an object or a path to an object."""
24740
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1506 try:
41166
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1507 pager(render_doc(thing, title, forceload))
24740
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1508 except (ImportError, ErrorDuringImport), value:
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1509 print value
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1510
24740
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1511 def writedoc(thing, forceload=0):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1512 """Write HTML documentation to a file in the current directory."""
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1513 try:
24740
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1514 object, name = resolve(thing, forceload)
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1515 page = html.page(describe(object), html.document(object, name))
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1516 file = open(name + '.html', 'w')
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1517 file.write(page)
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1518 file.close()
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1519 print 'wrote', name + '.html'
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1520 except (ImportError, ErrorDuringImport), value:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1521 print value
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1522
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1523 def writedocs(dir, pkgpath='', done=None):
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1524 """Write out HTML documentation for all modules in a directory tree."""
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1525 if done is None: done = {}
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1526 for importer, modname, ispkg in pkgutil.walk_packages([dir], pkgpath):
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1527 writedoc(modname)
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1528 return
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1529
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1530 class Helper:
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1531
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1532 # These dictionaries map a topic name to either an alias, or a tuple
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1533 # (label, seealso-items). The "label" is the label of the corresponding
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1534 # section in the .rst file under Doc/ and an index into the dictionary
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1535 # in pydoc_topics.py.
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1536 #
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1537 # CAUTION: if you change one of these dictionaries, be sure to adapt the
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1538 # list of needed labels in Doc/tools/sphinxext/pyspecific.py and
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1539 # regenerate the pydoc_topics.py file by running
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1540 # make pydoc-topics
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1541 # in Doc/ and copying the output file into the Lib/ directory.
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1542
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1543 keywords = {
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1544 'and': 'BOOLEAN',
41147
b89437e3bc8e Patch #1542681: add entries for "with", "as" and "CONTEXTMANAGERS" to
Georg Brandl <georg@python.org>
parents: 40996
diff changeset
1545 'as': 'with',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1546 'assert': ('assert', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1547 'break': ('break', 'while for'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1548 'class': ('class', 'CLASSES SPECIALMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1549 'continue': ('continue', 'while for'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1550 'def': ('function', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1551 'del': ('del', 'BASICMETHODS'),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1552 'elif': 'if',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1553 'else': ('else', 'while for'),
48901
11d8fa3c88d8 #3707: fix inf. recursion in pydoc topic search. Rev'd by Antoine.
Georg Brandl <georg@python.org>
parents: 48141
diff changeset
1554 'except': 'try',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1555 'exec': ('exec', ''),
48901
11d8fa3c88d8 #3707: fix inf. recursion in pydoc topic search. Rev'd by Antoine.
Georg Brandl <georg@python.org>
parents: 48141
diff changeset
1556 'finally': 'try',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1557 'for': ('for', 'break continue while'),
48901
11d8fa3c88d8 #3707: fix inf. recursion in pydoc topic search. Rev'd by Antoine.
Georg Brandl <georg@python.org>
parents: 48141
diff changeset
1558 'from': 'import',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1559 'global': ('global', 'NAMESPACES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1560 'if': ('if', 'TRUTHVALUE'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1561 'import': ('import', 'MODULES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1562 'in': ('in', 'SEQUENCEMETHODS2'),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1563 'is': 'COMPARISON',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1564 'lambda': ('lambda', 'FUNCTIONS'),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1565 'not': 'BOOLEAN',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1566 'or': 'BOOLEAN',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1567 'pass': ('pass', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1568 'print': ('print', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1569 'raise': ('raise', 'EXCEPTIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1570 'return': ('return', 'FUNCTIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1571 'try': ('try', 'EXCEPTIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1572 'while': ('while', 'break continue if TRUTHVALUE'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1573 'with': ('with', 'CONTEXTMANAGERS EXCEPTIONS yield'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1574 'yield': ('yield', ''),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1575 }
50424
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1576 # Either add symbols to this dictionary or to the symbols dictionary
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1577 # directly: Whichever is easier. They are merged later.
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1578 _symbols_inverse = {
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1579 'STRINGS' : ("'", "'''", "r'", "u'", '"""', '"', 'r"', 'u"'),
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1580 'OPERATORS' : ('+', '-', '*', '**', '/', '//', '%', '<<', '>>', '&',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1581 '|', '^', '~', '<', '>', '<=', '>=', '==', '!=', '<>'),
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1582 'COMPARISON' : ('<', '>', '<=', '>=', '==', '!=', '<>'),
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1583 'UNARY' : ('-', '~'),
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1584 'AUGMENTEDASSIGNMENT' : ('+=', '-=', '*=', '/=', '%=', '&=', '|=',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1585 '^=', '<<=', '>>=', '**=', '//='),
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1586 'BITWISE' : ('<<', '>>', '&', '|', '^', '~'),
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1587 'COMPLEX' : ('j', 'J')
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1588 }
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1589 symbols = {
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1590 '%': 'OPERATORS FORMATTING',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1591 '**': 'POWER',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1592 ',': 'TUPLES LISTS FUNCTIONS',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1593 '.': 'ATTRIBUTES FLOAT MODULES OBJECTS',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1594 '...': 'ELLIPSIS',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1595 ':': 'SLICINGS DICTIONARYLITERALS',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1596 '@': 'def class',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1597 '\\': 'STRINGS',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1598 '_': 'PRIVATENAMES',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1599 '__': 'PRIVATENAMES SPECIALMETHODS',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1600 '`': 'BACKQUOTES',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1601 '(': 'TUPLES FUNCTIONS CALLS',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1602 ')': 'TUPLES FUNCTIONS CALLS',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1603 '[': 'LISTS SUBSCRIPTS SLICINGS',
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1604 ']': 'LISTS SUBSCRIPTS SLICINGS'
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1605 }
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1606 for topic, symbols_ in _symbols_inverse.iteritems():
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1607 for symbol in symbols_:
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1608 topics = symbols.get(symbol, topic)
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1609 if topic not in topics:
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1610 topics = topics + ' ' + topic
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1611 symbols[symbol] = topics
17230
45cda1b39355 Fix some reloading problems (still more work needed).
Ka-Ping Yee <ping@zesty.ca>
parents: 17184
diff changeset
1612
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1613 topics = {
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1614 'TYPES': ('types', 'STRINGS UNICODE NUMBERS SEQUENCES MAPPINGS '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1615 'FUNCTIONS CLASSES MODULES FILES inspect'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1616 'STRINGS': ('strings', 'str UNICODE SEQUENCES STRINGMETHODS FORMATTING '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1617 'TYPES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1618 'STRINGMETHODS': ('string-methods', 'STRINGS FORMATTING'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1619 'FORMATTING': ('formatstrings', 'OPERATORS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1620 'UNICODE': ('strings', 'encodings unicode SEQUENCES STRINGMETHODS '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1621 'FORMATTING TYPES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1622 'NUMBERS': ('numbers', 'INTEGER FLOAT COMPLEX TYPES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1623 'INTEGER': ('integers', 'int range'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1624 'FLOAT': ('floating', 'float math'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1625 'COMPLEX': ('imaginary', 'complex cmath'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1626 'SEQUENCES': ('typesseq', 'STRINGMETHODS FORMATTING xrange LISTS'),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1627 'MAPPINGS': 'DICTIONARIES',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1628 'FUNCTIONS': ('typesfunctions', 'def TYPES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1629 'METHODS': ('typesmethods', 'class def CLASSES TYPES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1630 'CODEOBJECTS': ('bltin-code-objects', 'compile FUNCTIONS TYPES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1631 'TYPEOBJECTS': ('bltin-type-objects', 'types TYPES'),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1632 'FRAMEOBJECTS': 'TYPES',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1633 'TRACEBACKS': 'TYPES',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1634 'NONE': ('bltin-null-object', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1635 'ELLIPSIS': ('bltin-ellipsis-object', 'SLICINGS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1636 'FILES': ('bltin-file-objects', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1637 'SPECIALATTRIBUTES': ('specialattrs', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1638 'CLASSES': ('types', 'class SPECIALMETHODS PRIVATENAMES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1639 'MODULES': ('typesmodules', 'import'),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1640 'PACKAGES': 'import',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1641 'EXPRESSIONS': ('operator-summary', 'lambda or and not in is BOOLEAN '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1642 'COMPARISON BITWISE SHIFTING BINARY FORMATTING POWER '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1643 'UNARY ATTRIBUTES SUBSCRIPTS SLICINGS CALLS TUPLES '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1644 'LISTS DICTIONARIES BACKQUOTES'),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1645 'OPERATORS': 'EXPRESSIONS',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1646 'PRECEDENCE': 'EXPRESSIONS',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1647 'OBJECTS': ('objects', 'TYPES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1648 'SPECIALMETHODS': ('specialnames', 'BASICMETHODS ATTRIBUTEMETHODS '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1649 'CALLABLEMETHODS SEQUENCEMETHODS1 MAPPINGMETHODS '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1650 'SEQUENCEMETHODS2 NUMBERMETHODS CLASSES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1651 'BASICMETHODS': ('customization', 'cmp hash repr str SPECIALMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1652 'ATTRIBUTEMETHODS': ('attribute-access', 'ATTRIBUTES SPECIALMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1653 'CALLABLEMETHODS': ('callable-types', 'CALLS SPECIALMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1654 'SEQUENCEMETHODS1': ('sequence-types', 'SEQUENCES SEQUENCEMETHODS2 '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1655 'SPECIALMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1656 'SEQUENCEMETHODS2': ('sequence-methods', 'SEQUENCES SEQUENCEMETHODS1 '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1657 'SPECIALMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1658 'MAPPINGMETHODS': ('sequence-types', 'MAPPINGS SPECIALMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1659 'NUMBERMETHODS': ('numeric-types', 'NUMBERS AUGMENTEDASSIGNMENT '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1660 'SPECIALMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1661 'EXECUTION': ('execmodel', 'NAMESPACES DYNAMICFEATURES EXCEPTIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1662 'NAMESPACES': ('naming', 'global ASSIGNMENT DELETION DYNAMICFEATURES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1663 'DYNAMICFEATURES': ('dynamic-features', ''),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1664 'SCOPING': 'NAMESPACES',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1665 'FRAMES': 'NAMESPACES',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1666 'EXCEPTIONS': ('exceptions', 'try except finally raise'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1667 'COERCIONS': ('coercion-rules','CONVERSIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1668 'CONVERSIONS': ('conversions', 'COERCIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1669 'IDENTIFIERS': ('identifiers', 'keywords SPECIALIDENTIFIERS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1670 'SPECIALIDENTIFIERS': ('id-classes', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1671 'PRIVATENAMES': ('atom-identifiers', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1672 'LITERALS': ('atom-literals', 'STRINGS BACKQUOTES NUMBERS '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1673 'TUPLELITERALS LISTLITERALS DICTIONARYLITERALS'),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1674 'TUPLES': 'SEQUENCES',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1675 'TUPLELITERALS': ('exprlists', 'TUPLES LITERALS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1676 'LISTS': ('typesseq-mutable', 'LISTLITERALS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1677 'LISTLITERALS': ('lists', 'LISTS LITERALS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1678 'DICTIONARIES': ('typesmapping', 'DICTIONARYLITERALS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1679 'DICTIONARYLITERALS': ('dict', 'DICTIONARIES LITERALS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1680 'BACKQUOTES': ('string-conversions', 'repr str STRINGS LITERALS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1681 'ATTRIBUTES': ('attribute-references', 'getattr hasattr setattr '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1682 'ATTRIBUTEMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1683 'SUBSCRIPTS': ('subscriptions', 'SEQUENCEMETHODS1'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1684 'SLICINGS': ('slicings', 'SEQUENCEMETHODS2'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1685 'CALLS': ('calls', 'EXPRESSIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1686 'POWER': ('power', 'EXPRESSIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1687 'UNARY': ('unary', 'EXPRESSIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1688 'BINARY': ('binary', 'EXPRESSIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1689 'SHIFTING': ('shifting', 'EXPRESSIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1690 'BITWISE': ('bitwise', 'EXPRESSIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1691 'COMPARISON': ('comparisons', 'EXPRESSIONS BASICMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1692 'BOOLEAN': ('booleans', 'EXPRESSIONS TRUTHVALUE'),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1693 'ASSERTION': 'assert',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1694 'ASSIGNMENT': ('assignment', 'AUGMENTEDASSIGNMENT'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1695 'AUGMENTEDASSIGNMENT': ('augassign', 'NUMBERMETHODS'),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1696 'DELETION': 'del',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1697 'PRINTING': 'print',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1698 'RETURNING': 'return',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1699 'IMPORTING': 'import',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1700 'CONDITIONAL': 'if',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1701 'LOOPING': ('compound', 'for while break continue'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1702 'TRUTHVALUE': ('truth', 'if while and or not BASICMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1703 'DEBUGGING': ('debugger', 'pdb'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1704 'CONTEXTMANAGERS': ('context-managers', 'with'),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1705 }
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1706
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1707 def __init__(self, input, output):
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1708 self.input = input
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1709 self.output = output
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1710
17471
24e81b43067d Another pass through the topic table to fill in cross references.
Ka-Ping Yee <ping@zesty.ca>
parents: 17470
diff changeset
1711 def __repr__(self):
17476
25f55b2e38ac Use inspect.stack()[1][3] to tell if Helper.__repr__ is called interactively.
Ka-Ping Yee <ping@zesty.ca>
parents: 17475
diff changeset
1712 if inspect.stack()[1][3] == '?':
17471
24e81b43067d Another pass through the topic table to fill in cross references.
Ka-Ping Yee <ping@zesty.ca>
parents: 17470
diff changeset
1713 self()
24e81b43067d Another pass through the topic table to fill in cross references.
Ka-Ping Yee <ping@zesty.ca>
parents: 17470
diff changeset
1714 return ''
17476
25f55b2e38ac Use inspect.stack()[1][3] to tell if Helper.__repr__ is called interactively.
Ka-Ping Yee <ping@zesty.ca>
parents: 17475
diff changeset
1715 return '<pydoc.Helper instance>'
17471
24e81b43067d Another pass through the topic table to fill in cross references.
Ka-Ping Yee <ping@zesty.ca>
parents: 17470
diff changeset
1716
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1717 def __call__(self, request=None):
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1718 if request is not None:
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1719 self.help(request)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1720 else:
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1721 self.intro()
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1722 self.interact()
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1723 self.output.write('''
17770
cc8d148c396a Change some text just a little to avoid font-lock hell.
Fred Drake <fdrake@acm.org>
parents: 17487
diff changeset
1724 You are now leaving help and returning to the Python interpreter.
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1725 If you want to ask for help on a particular object directly from the
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1726 interpreter, you can type "help(object)". Executing "help('string')"
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1727 has the same effect as typing a particular string at the help> prompt.
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1728 ''')
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1729
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1730 def interact(self):
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1731 self.output.write('\n')
22867
e2f2187c3d2c Partial introduction of bools where appropriate.
Guido van Rossum <guido@python.org>
parents: 22830
diff changeset
1732 while True:
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1733 try:
33162
208fe719c749 Use readline/raw_input() in pydoc.Helper.interact if available and self.input
Johannes Gijsbers <jlg@dds.nl>
parents: 32382
diff changeset
1734 request = self.getline('help> ')
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1735 if not request: break
33162
208fe719c749 Use readline/raw_input() in pydoc.Helper.interact if available and self.input
Johannes Gijsbers <jlg@dds.nl>
parents: 32382
diff changeset
1736 except (KeyboardInterrupt, EOFError):
208fe719c749 Use readline/raw_input() in pydoc.Helper.interact if available and self.input
Johannes Gijsbers <jlg@dds.nl>
parents: 32382
diff changeset
1737 break
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1738 request = strip(replace(request, '"', '', "'", ''))
34545
9d66fba78444 Replace list of constants with tuples of constants.
Raymond Hettinger <python@rcn.com>
parents: 34369
diff changeset
1739 if lower(request) in ('q', 'quit'): break
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1740 self.help(request)
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1741
33162
208fe719c749 Use readline/raw_input() in pydoc.Helper.interact if available and self.input
Johannes Gijsbers <jlg@dds.nl>
parents: 32382
diff changeset
1742 def getline(self, prompt):
208fe719c749 Use readline/raw_input() in pydoc.Helper.interact if available and self.input
Johannes Gijsbers <jlg@dds.nl>
parents: 32382
diff changeset
1743 """Read one line, using raw_input when available."""
208fe719c749 Use readline/raw_input() in pydoc.Helper.interact if available and self.input
Johannes Gijsbers <jlg@dds.nl>
parents: 32382
diff changeset
1744 if self.input is sys.stdin:
208fe719c749 Use readline/raw_input() in pydoc.Helper.interact if available and self.input
Johannes Gijsbers <jlg@dds.nl>
parents: 32382
diff changeset
1745 return raw_input(prompt)
208fe719c749 Use readline/raw_input() in pydoc.Helper.interact if available and self.input
Johannes Gijsbers <jlg@dds.nl>
parents: 32382
diff changeset
1746 else:
208fe719c749 Use readline/raw_input() in pydoc.Helper.interact if available and self.input
Johannes Gijsbers <jlg@dds.nl>
parents: 32382
diff changeset
1747 self.output.write(prompt)
208fe719c749 Use readline/raw_input() in pydoc.Helper.interact if available and self.input
Johannes Gijsbers <jlg@dds.nl>
parents: 32382
diff changeset
1748 self.output.flush()
208fe719c749 Use readline/raw_input() in pydoc.Helper.interact if available and self.input
Johannes Gijsbers <jlg@dds.nl>
parents: 32382
diff changeset
1749 return self.input.readline()
208fe719c749 Use readline/raw_input() in pydoc.Helper.interact if available and self.input
Johannes Gijsbers <jlg@dds.nl>
parents: 32382
diff changeset
1750
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1751 def help(self, request):
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1752 if type(request) is type(''):
54377
9b8b60bc0f5b Merged revisions 72966 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 53034
diff changeset
1753 request = request.strip()
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1754 if request == 'help': self.intro()
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1755 elif request == 'keywords': self.listkeywords()
50424
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1756 elif request == 'symbols': self.listsymbols()
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1757 elif request == 'topics': self.listtopics()
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1758 elif request == 'modules': self.listmodules()
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1759 elif request[:8] == 'modules ':
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1760 self.listmodules(split(request)[1])
50424
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1761 elif request in self.symbols: self.showsymbol(request)
23620
a1de0bab5475 SF 563203. Replaced 'has_key()' with 'in'.
Raymond Hettinger <python@rcn.com>
parents: 23501
diff changeset
1762 elif request in self.keywords: self.showtopic(request)
a1de0bab5475 SF 563203. Replaced 'has_key()' with 'in'.
Raymond Hettinger <python@rcn.com>
parents: 23501
diff changeset
1763 elif request in self.topics: self.showtopic(request)
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1764 elif request: doc(request, 'Help on %s:')
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1765 elif isinstance(request, Helper): self()
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1766 else: doc(request, 'Help on %s:')
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1767 self.output.write('\n')
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1768
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1769 def intro(self):
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1770 self.output.write('''
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1771 Welcome to Python %s! This is the online help utility.
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1772
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1773 If this is your first time using Python, you should definitely check out
44845
27dac16541d9 Adapt pydoc to new doc URLs.
Georg Brandl <georg@python.org>
parents: 44660
diff changeset
1774 the tutorial on the Internet at http://docs.python.org/tutorial/.
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1775
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1776 Enter the name of any module, keyword, or topic to get help on writing
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1777 Python programs and using Python modules. To quit this help utility and
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1778 return to the interpreter, just type "quit".
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1779
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1780 To get a list of available modules, keywords, or topics, type "modules",
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1781 "keywords", or "topics". Each module also comes with a one-line summary
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1782 of what it does; to list the modules whose summaries contain a given word
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1783 such as "spam", type "modules spam".
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1784 ''' % sys.version[:3])
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1785
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1786 def list(self, items, columns=4, width=80):
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1787 items = items[:]
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1788 items.sort()
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1789 colw = width / columns
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1790 rows = (len(items) + columns - 1) / columns
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1791 for row in range(rows):
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1792 for col in range(columns):
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1793 i = col * rows + row
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1794 if i < len(items):
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1795 self.output.write(items[i])
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1796 if col < columns - 1:
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1797 self.output.write(' ' + ' ' * (colw-1 - len(items[i])))
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1798 self.output.write('\n')
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1799
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1800 def listkeywords(self):
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1801 self.output.write('''
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1802 Here is a list of the Python keywords. Enter any keyword to get more help.
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1803
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1804 ''')
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1805 self.list(self.keywords.keys())
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1806
50424
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1807 def listsymbols(self):
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1808 self.output.write('''
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1809 Here is a list of the punctuation symbols which Python assigns special meaning
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1810 to. Enter any symbol to get more help.
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1811
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1812 ''')
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1813 self.list(self.symbols.keys())
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1814
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1815 def listtopics(self):
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1816 self.output.write('''
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1817 Here is a list of available topics. Enter any topic name to get more help.
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1818
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1819 ''')
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1820 self.list(self.topics.keys())
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1821
50424
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1822 def showtopic(self, topic, more_xrefs=''):
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1823 try:
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1824 import pydoc_topics
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1825 except ImportError:
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1826 self.output.write('''
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1827 Sorry, topic and keyword documentation is not available because the
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1828 module "pydoc_topics" could not be found.
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1829 ''')
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1830 return
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1831 target = self.topics.get(topic, self.keywords.get(topic))
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1832 if not target:
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1833 self.output.write('no documentation found for %s\n' % repr(topic))
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1834 return
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1835 if type(target) is type(''):
50424
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1836 return self.showtopic(target, more_xrefs)
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1837
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1838 label, xrefs = target
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1839 try:
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1840 doc = pydoc_topics.topics[label]
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1841 except KeyError:
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1842 self.output.write('no documentation found for %s\n' % repr(topic))
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1843 return
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1844 pager(strip(doc) + '\n')
50424
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1845 if more_xrefs:
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1846 xrefs = (xrefs or '') + ' ' + more_xrefs
17472
2888fc60bf9a Word-wrap the list of cross-references.
Ka-Ping Yee <ping@zesty.ca>
parents: 17471
diff changeset
1847 if xrefs:
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1848 import StringIO, formatter
17472
2888fc60bf9a Word-wrap the list of cross-references.
Ka-Ping Yee <ping@zesty.ca>
parents: 17471
diff changeset
1849 buffer = StringIO.StringIO()
2888fc60bf9a Word-wrap the list of cross-references.
Ka-Ping Yee <ping@zesty.ca>
parents: 17471
diff changeset
1850 formatter.DumbWriter(buffer).send_flowing_data(
2888fc60bf9a Word-wrap the list of cross-references.
Ka-Ping Yee <ping@zesty.ca>
parents: 17471
diff changeset
1851 'Related help topics: ' + join(split(xrefs), ', ') + '\n')
2888fc60bf9a Word-wrap the list of cross-references.
Ka-Ping Yee <ping@zesty.ca>
parents: 17471
diff changeset
1852 self.output.write('\n%s\n' % buffer.getvalue())
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1853
50424
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1854 def showsymbol(self, symbol):
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1855 target = self.symbols[symbol]
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1856 topic, _, xrefs = target.partition(' ')
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1857 self.showtopic(topic, xrefs)
df3923c36ec5 Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48901
diff changeset
1858
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1859 def listmodules(self, key=''):
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1860 if key:
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1861 self.output.write('''
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1862 Here is a list of matching modules. Enter any module name to get more help.
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1863
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1864 ''')
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1865 apropos(key)
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1866 else:
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1867 self.output.write('''
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1868 Please wait a moment while I gather a list of all available modules...
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1869
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1870 ''')
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1871 modules = {}
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1872 def callback(path, modname, desc, modules=modules):
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1873 if modname and modname[-9:] == '.__init__':
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1874 modname = modname[:-9] + ' (package)'
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1875 if find(modname, '.') < 0:
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1876 modules[modname] = 1
44660
c73768d977a9 Check in the patch proposed by Ben Hayden (benjhayden) for issue
Ka-Ping Yee <ping@zesty.ca>
parents: 41175
diff changeset
1877 def onerror(modname):
c73768d977a9 Check in the patch proposed by Ben Hayden (benjhayden) for issue
Ka-Ping Yee <ping@zesty.ca>
parents: 41175
diff changeset
1878 callback(None, modname, None)
c73768d977a9 Check in the patch proposed by Ben Hayden (benjhayden) for issue
Ka-Ping Yee <ping@zesty.ca>
parents: 41175
diff changeset
1879 ModuleScanner().run(callback, onerror=onerror)
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1880 self.list(modules.keys())
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1881 self.output.write('''
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1882 Enter any module name to get more help. Or, type "modules spam" to search
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1883 for modules whose descriptions contain the word "spam".
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1884 ''')
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1885
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1886 help = Helper(sys.stdin, sys.stdout)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1887
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1888 class Scanner:
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1889 """A generic tree iterator."""
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1890 def __init__(self, roots, children, descendp):
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1891 self.roots = roots[:]
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1892 self.state = []
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1893 self.children = children
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1894 self.descendp = descendp
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1895
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1896 def next(self):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1897 if not self.state:
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1898 if not self.roots:
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1899 return None
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1900 root = self.roots.pop(0)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1901 self.state = [(root, self.children(root))]
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1902 node, children = self.state[-1]
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1903 if not children:
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1904 self.state.pop()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1905 return self.next()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1906 child = children.pop(0)
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1907 if self.descendp(child):
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1908 self.state.append((child, self.children(child)))
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1909 return child
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1910
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1911
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1912 class ModuleScanner:
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1913 """An interruptible scanner that searches module synopses."""
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1914
44660
c73768d977a9 Check in the patch proposed by Ben Hayden (benjhayden) for issue
Ka-Ping Yee <ping@zesty.ca>
parents: 41175
diff changeset
1915 def run(self, callback, key=None, completer=None, onerror=None):
17442
2d521420db8f Typo fixes and small touches.
Ka-Ping Yee <ping@zesty.ca>
parents: 17441
diff changeset
1916 if key: key = lower(key)
22867
e2f2187c3d2c Partial introduction of bools where appropriate.
Guido van Rossum <guido@python.org>
parents: 22830
diff changeset
1917 self.quit = False
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1918 seen = {}
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1919
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1920 for modname in sys.builtin_module_names:
16928
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
1921 if modname != '__main__':
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
1922 seen[modname] = 1
17442
2d521420db8f Typo fixes and small touches.
Ka-Ping Yee <ping@zesty.ca>
parents: 17441
diff changeset
1923 if key is None:
2d521420db8f Typo fixes and small touches.
Ka-Ping Yee <ping@zesty.ca>
parents: 17441
diff changeset
1924 callback(None, modname, '')
2d521420db8f Typo fixes and small touches.
Ka-Ping Yee <ping@zesty.ca>
parents: 17441
diff changeset
1925 else:
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1926 desc = split(__import__(modname).__doc__ or '', '\n')[0]
17442
2d521420db8f Typo fixes and small touches.
Ka-Ping Yee <ping@zesty.ca>
parents: 17441
diff changeset
1927 if find(lower(modname + ' - ' + desc), key) >= 0:
2d521420db8f Typo fixes and small touches.
Ka-Ping Yee <ping@zesty.ca>
parents: 17441
diff changeset
1928 callback(None, modname, desc)
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1929
44660
c73768d977a9 Check in the patch proposed by Ben Hayden (benjhayden) for issue
Ka-Ping Yee <ping@zesty.ca>
parents: 41175
diff changeset
1930 for importer, modname, ispkg in pkgutil.walk_packages(onerror=onerror):
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1931 if self.quit:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1932 break
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1933 if key is None:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1934 callback(None, modname, '')
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1935 else:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1936 loader = importer.find_module(modname)
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1937 if hasattr(loader,'get_source'):
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1938 import StringIO
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1939 desc = source_synopsis(
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1940 StringIO.StringIO(loader.get_source(modname))
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1941 ) or ''
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1942 if hasattr(loader,'get_filename'):
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1943 path = loader.get_filename(modname)
17442
2d521420db8f Typo fixes and small touches.
Ka-Ping Yee <ping@zesty.ca>
parents: 17441
diff changeset
1944 else:
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1945 path = None
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1946 else:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1947 module = loader.load_module(modname)
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1948 desc = (module.__doc__ or '').splitlines()[0]
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1949 path = getattr(module,'__file__',None)
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1950 if find(lower(modname + ' - ' + desc), key) >= 0:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1951 callback(path, modname, desc)
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1952
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1953 if completer:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1954 completer()
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1955
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1956 def apropos(key):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1957 """Print all the one-line module summaries that contain a substring."""
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1958 def callback(path, modname, desc):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1959 if modname[-9:] == '.__init__':
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1960 modname = modname[:-9] + ' (package)'
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
1961 print modname, desc and '- ' + desc
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
1962 try: import warnings
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
1963 except ImportError: pass
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
1964 else: warnings.filterwarnings('ignore') # ignore problems during import
17442
2d521420db8f Typo fixes and small touches.
Ka-Ping Yee <ping@zesty.ca>
parents: 17441
diff changeset
1965 ModuleScanner().run(callback, key)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1966
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1967 # --------------------------------------------------- web browser interface
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1968
17442
2d521420db8f Typo fixes and small touches.
Ka-Ping Yee <ping@zesty.ca>
parents: 17441
diff changeset
1969 def serve(port, callback=None, completer=None):
17445
f0f0467a3334 Remove forking. Doesn't work in Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 17442
diff changeset
1970 import BaseHTTPServer, mimetools, select
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1971
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1972 # Patch up mimetools.Message so it doesn't break if rfc822 is reloaded.
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1973 class Message(mimetools.Message):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1974 def __init__(self, fp, seekable=1):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1975 Message = self.__class__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1976 Message.__bases__[0].__bases__[0].__init__(self, fp, seekable)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1977 self.encodingheader = self.getheader('content-transfer-encoding')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1978 self.typeheader = self.getheader('content-type')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1979 self.parsetype()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1980 self.parseplist()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1981
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1982 class DocHandler(BaseHTTPServer.BaseHTTPRequestHandler):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1983 def send_document(self, title, contents):
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1984 try:
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1985 self.send_response(200)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1986 self.send_header('Content-Type', 'text/html')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1987 self.end_headers()
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1988 self.wfile.write(html.page(title, contents))
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1989 except IOError: pass
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1990
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1991 def do_GET(self):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1992 path = self.path
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1993 if path[-5:] == '.html': path = path[:-5]
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1994 if path[:1] == '/': path = path[1:]
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1995 if path and path != '.':
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1996 try:
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1997 obj = locate(path, forceload=1)
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
1998 except ErrorDuringImport, value:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1999 self.send_document(path, html.escape(str(value)))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2000 return
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
2001 if obj:
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
2002 self.send_document(describe(obj), html.document(obj, path))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2003 else:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2004 self.send_document(path,
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2005 'no Python documentation found for %s' % repr(path))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2006 else:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2007 heading = html.heading(
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2008 '<big><big><strong>Python: Index of Modules</strong></big></big>',
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2009 '#ffffff', '#7799ee')
16928
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2010 def bltinlink(name):
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2011 return '<a href="%s.html">%s</a>' % (name, name)
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
2012 names = filter(lambda x: x != '__main__',
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
2013 sys.builtin_module_names)
16928
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2014 contents = html.multicolumn(names, bltinlink)
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2015 indices = ['<p>' + html.bigsection(
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2016 'Built-in Modules', '#ffffff', '#ee77aa', contents)]
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2017
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2018 seen = {}
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
2019 for dir in sys.path:
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2020 indices.append(html.index(dir, seen))
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2021 contents = heading + join(indices) + '''<p align=right>
20074
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
2022 <font color="#909090" face="helvetica, arial"><strong>
511776d6d7d8 + Got rid of all instances of <small>. Under IE5, GUI-mode pydoc has
Tim Peters <tim.peters@gmail.com>
parents: 20073
diff changeset
2023 pydoc</strong> by Ka-Ping Yee &lt;ping@lfw.org&gt;</font>'''
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2024 self.send_document('Index of Modules', contents)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2025
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2026 def log_message(self, *args): pass
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2027
17445
f0f0467a3334 Remove forking. Doesn't work in Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 17442
diff changeset
2028 class DocServer(BaseHTTPServer.HTTPServer):
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2029 def __init__(self, port, callback):
16942
af810f08425b Use '127.0.0.1' only on Mac; for other, sane platforms, use 'localhost'.
Ka-Ping Yee <ping@zesty.ca>
parents: 16940
diff changeset
2030 host = (sys.platform == 'mac') and '127.0.0.1' or 'localhost'
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2031 self.address = ('', port)
16942
af810f08425b Use '127.0.0.1' only on Mac; for other, sane platforms, use 'localhost'.
Ka-Ping Yee <ping@zesty.ca>
parents: 16940
diff changeset
2032 self.url = 'http://%s:%d/' % (host, port)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2033 self.callback = callback
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2034 self.base.__init__(self, self.address, self.handler)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2035
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2036 def serve_until_quit(self):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2037 import select
22867
e2f2187c3d2c Partial introduction of bools where appropriate.
Guido van Rossum <guido@python.org>
parents: 22830
diff changeset
2038 self.quit = False
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2039 while not self.quit:
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2040 rd, wr, ex = select.select([self.socket.fileno()], [], [], 1)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2041 if rd: self.handle_request()
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2042
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2043 def server_activate(self):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2044 self.base.server_activate(self)
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2045 if self.callback: self.callback(self)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2046
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2047 DocServer.base = BaseHTTPServer.HTTPServer
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2048 DocServer.handler = DocHandler
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2049 DocHandler.MessageClass = Message
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2050 try:
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2051 try:
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2052 DocServer(port, callback).serve_until_quit()
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2053 except (KeyboardInterrupt, select.error):
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2054 pass
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2055 finally:
17442
2d521420db8f Typo fixes and small touches.
Ka-Ping Yee <ping@zesty.ca>
parents: 17441
diff changeset
2056 if completer: completer()
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2057
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2058 # ----------------------------------------------------- graphical interface
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2059
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2060 def gui():
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2061 """Graphical interface (starts web server and pops up a control window)."""
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2062 class GUI:
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2063 def __init__(self, window, port=7464):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2064 self.window = window
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2065 self.server = None
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2066 self.scanner = None
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2067
47183
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2068 import Tkinter
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2069 self.server_frm = Tkinter.Frame(window)
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2070 self.title_lbl = Tkinter.Label(self.server_frm,
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2071 text='Starting server...\n ')
47183
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2072 self.open_btn = Tkinter.Button(self.server_frm,
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2073 text='open browser', command=self.open, state='disabled')
47183
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2074 self.quit_btn = Tkinter.Button(self.server_frm,
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2075 text='quit serving', command=self.quit, state='disabled')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2076
47183
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2077 self.search_frm = Tkinter.Frame(window)
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2078 self.search_lbl = Tkinter.Label(self.search_frm, text='Search for')
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2079 self.search_ent = Tkinter.Entry(self.search_frm)
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2080 self.search_ent.bind('<Return>', self.search)
47183
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2081 self.stop_btn = Tkinter.Button(self.search_frm,
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2082 text='stop', pady=0, command=self.stop, state='disabled')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2083 if sys.platform == 'win32':
16940
c28dfe5f87a7 The sys.platform identifier for Windows is just 'win32' (for all varieties).
Ka-Ping Yee <ping@zesty.ca>
parents: 16934
diff changeset
2084 # Trying to hide and show this button crashes under Windows.
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2085 self.stop_btn.pack(side='right')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2086
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2087 self.window.title('pydoc')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2088 self.window.protocol('WM_DELETE_WINDOW', self.quit)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2089 self.title_lbl.pack(side='top', fill='x')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2090 self.open_btn.pack(side='left', fill='x', expand=1)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2091 self.quit_btn.pack(side='right', fill='x', expand=1)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2092 self.server_frm.pack(side='top', fill='x')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2093
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2094 self.search_lbl.pack(side='left')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2095 self.search_ent.pack(side='right', fill='x', expand=1)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2096 self.search_frm.pack(side='top', fill='x')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2097 self.search_ent.focus_set()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2098
16940
c28dfe5f87a7 The sys.platform identifier for Windows is just 'win32' (for all varieties).
Ka-Ping Yee <ping@zesty.ca>
parents: 16934
diff changeset
2099 font = ('helvetica', sys.platform == 'win32' and 8 or 10)
47183
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2100 self.result_lst = Tkinter.Listbox(window, font=font, height=6)
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2101 self.result_lst.bind('<Button-1>', self.select)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2102 self.result_lst.bind('<Double-Button-1>', self.goto)
47183
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2103 self.result_scr = Tkinter.Scrollbar(window,
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2104 orient='vertical', command=self.result_lst.yview)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2105 self.result_lst.config(yscrollcommand=self.result_scr.set)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2106
47183
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2107 self.result_frm = Tkinter.Frame(window)
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2108 self.goto_btn = Tkinter.Button(self.result_frm,
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2109 text='go to selected', command=self.goto)
47183
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2110 self.hide_btn = Tkinter.Button(self.result_frm,
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2111 text='hide results', command=self.hide)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2112 self.goto_btn.pack(side='left', fill='x', expand=1)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2113 self.hide_btn.pack(side='right', fill='x', expand=1)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2114
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2115 self.window.update()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2116 self.minwidth = self.window.winfo_width()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2117 self.minheight = self.window.winfo_height()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2118 self.bigminheight = (self.server_frm.winfo_reqheight() +
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2119 self.search_frm.winfo_reqheight() +
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2120 self.result_lst.winfo_reqheight() +
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2121 self.result_frm.winfo_reqheight())
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2122 self.bigwidth, self.bigheight = self.minwidth, self.bigminheight
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2123 self.expanded = 0
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2124 self.window.wm_geometry('%dx%d' % (self.minwidth, self.minheight))
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2125 self.window.wm_minsize(self.minwidth, self.minheight)
26814
7c8af1979e78 Gracefully delay runtime error up to 1s. Add .willdispatch().
Martin v. Löwis <martin@v.loewis.de>
parents: 25986
diff changeset
2126 self.window.tk.willdispatch()
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2127
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2128 import threading
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2129 threading.Thread(
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2130 target=serve, args=(port, self.ready, self.quit)).start()
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2131
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2132 def ready(self, server):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2133 self.server = server
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2134 self.title_lbl.config(
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2135 text='Python documentation server at\n' + server.url)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2136 self.open_btn.config(state='normal')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2137 self.quit_btn.config(state='normal')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2138
16928
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2139 def open(self, event=None, url=None):
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2140 url = url or self.server.url
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2141 try:
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2142 import webbrowser
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2143 webbrowser.open(url)
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2144 except ImportError: # pre-webbrowser.py compatibility
16940
c28dfe5f87a7 The sys.platform identifier for Windows is just 'win32' (for all varieties).
Ka-Ping Yee <ping@zesty.ca>
parents: 16934
diff changeset
2145 if sys.platform == 'win32':
16928
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2146 os.system('start "%s"' % url)
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2147 elif sys.platform == 'mac':
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
2148 try: import ic
16928
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2149 except ImportError: pass
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
2150 else: ic.launchurl(url)
16928
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2151 else:
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2152 rc = os.system('netscape -remote "openURL(%s)" &' % url)
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2153 if rc: os.system('netscape "%s" &' % url)
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2154
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2155 def quit(self, event=None):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2156 if self.server:
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2157 self.server.quit = 1
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2158 self.window.quit()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2159
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2160 def search(self, event=None):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2161 key = self.search_ent.get()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2162 self.stop_btn.pack(side='right')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2163 self.stop_btn.config(state='normal')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2164 self.search_lbl.config(text='Searching for "%s"...' % key)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2165 self.search_ent.forget()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2166 self.search_lbl.pack(side='left')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2167 self.result_lst.delete(0, 'end')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2168 self.goto_btn.config(state='disabled')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2169 self.expand()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2170
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2171 import threading
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2172 if self.scanner:
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2173 self.scanner.quit = 1
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2174 self.scanner = ModuleScanner()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2175 threading.Thread(target=self.scanner.run,
17456
3bda59071389 Fix call to ModuleScanner from GUI search interface.
Ka-Ping Yee <ping@zesty.ca>
parents: 17452
diff changeset
2176 args=(self.update, key, self.done)).start()
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2177
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2178 def update(self, path, modname, desc):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2179 if modname[-9:] == '.__init__':
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2180 modname = modname[:-9] + ' (package)'
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2181 self.result_lst.insert('end',
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2182 modname + ' - ' + (desc or '(no description)'))
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2183
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2184 def stop(self, event=None):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2185 if self.scanner:
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2186 self.scanner.quit = 1
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2187 self.scanner = None
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2188
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2189 def done(self):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2190 self.scanner = None
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2191 self.search_lbl.config(text='Search for')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2192 self.search_lbl.pack(side='left')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2193 self.search_ent.pack(side='right', fill='x', expand=1)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2194 if sys.platform != 'win32': self.stop_btn.forget()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2195 self.stop_btn.config(state='disabled')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2196
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2197 def select(self, event=None):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2198 self.goto_btn.config(state='normal')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2199
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2200 def goto(self, event=None):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2201 selection = self.result_lst.curselection()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2202 if selection:
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2203 modname = split(self.result_lst.get(selection[0]))[0]
16928
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
2204 self.open(url=self.server.url + modname + '.html')
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2205
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2206 def collapse(self):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2207 if not self.expanded: return
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2208 self.result_frm.forget()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2209 self.result_scr.forget()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2210 self.result_lst.forget()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2211 self.bigwidth = self.window.winfo_width()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2212 self.bigheight = self.window.winfo_height()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2213 self.window.wm_geometry('%dx%d' % (self.minwidth, self.minheight))
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2214 self.window.wm_minsize(self.minwidth, self.minheight)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2215 self.expanded = 0
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2216
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2217 def expand(self):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2218 if self.expanded: return
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2219 self.result_frm.pack(side='bottom', fill='x')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2220 self.result_scr.pack(side='right', fill='y')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2221 self.result_lst.pack(side='top', fill='both', expand=1)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2222 self.window.wm_geometry('%dx%d' % (self.bigwidth, self.bigheight))
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2223 self.window.wm_minsize(self.minwidth, self.bigminheight)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2224 self.expanded = 1
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2225
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2226 def hide(self, event=None):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2227 self.stop()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2228 self.collapse()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2229
47183
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2230 import Tkinter
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2231 try:
47183
b53604fad54b Tkinter rename reversal: remove tkinter package, adapt imports and docs.
Georg Brandl <georg@python.org>
parents: 47101
diff changeset
2232 root = Tkinter.Tk()
33225
57a66d700c7c Patch #997284: Allow pydoc to work with XP Themes (.manifest file)
Martin v. Löwis <martin@v.loewis.de>
parents: 33224
diff changeset
2233 # Tk will crash if pythonw.exe has an XP .manifest
57a66d700c7c Patch #997284: Allow pydoc to work with XP Themes (.manifest file)
Martin v. Löwis <martin@v.loewis.de>
parents: 33224
diff changeset
2234 # file and the root has is not destroyed explicitly.
57a66d700c7c Patch #997284: Allow pydoc to work with XP Themes (.manifest file)
Martin v. Löwis <martin@v.loewis.de>
parents: 33224
diff changeset
2235 # If the problem is ever fixed in Tk, the explicit
57a66d700c7c Patch #997284: Allow pydoc to work with XP Themes (.manifest file)
Martin v. Löwis <martin@v.loewis.de>
parents: 33224
diff changeset
2236 # destroy can go.
57a66d700c7c Patch #997284: Allow pydoc to work with XP Themes (.manifest file)
Martin v. Löwis <martin@v.loewis.de>
parents: 33224
diff changeset
2237 try:
57a66d700c7c Patch #997284: Allow pydoc to work with XP Themes (.manifest file)
Martin v. Löwis <martin@v.loewis.de>
parents: 33224
diff changeset
2238 gui = GUI(root)
57a66d700c7c Patch #997284: Allow pydoc to work with XP Themes (.manifest file)
Martin v. Löwis <martin@v.loewis.de>
parents: 33224
diff changeset
2239 root.mainloop()
57a66d700c7c Patch #997284: Allow pydoc to work with XP Themes (.manifest file)
Martin v. Löwis <martin@v.loewis.de>
parents: 33224
diff changeset
2240 finally:
57a66d700c7c Patch #997284: Allow pydoc to work with XP Themes (.manifest file)
Martin v. Löwis <martin@v.loewis.de>
parents: 33224
diff changeset
2241 root.destroy()
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2242 except KeyboardInterrupt:
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2243 pass
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2244
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2245 # -------------------------------------------------- command-line interface
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2246
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2247 def ispath(x):
24740
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
2248 return isinstance(x, str) and find(x, os.sep) >= 0
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2249
16875
10b84060b7f3 Normalize case of paths in sys.path to avoid duplicates on Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 16833
diff changeset
2250 def cli():
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2251 """Command-line interface (looks at sys.argv to decide what to do)."""
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2252 import getopt
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2253 class BadUsage: pass
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2254
57282
c08423d70b9f Merged revisions 76312 via svnmerge from
Nick Coghlan <ncoghlan@gmail.com>
parents: 54827
diff changeset
2255 # Scripts don't get the current directory in their path by default
c08423d70b9f Merged revisions 76312 via svnmerge from
Nick Coghlan <ncoghlan@gmail.com>
parents: 54827
diff changeset
2256 # unless they are run with the '-m' switch
c08423d70b9f Merged revisions 76312 via svnmerge from
Nick Coghlan <ncoghlan@gmail.com>
parents: 54827
diff changeset
2257 if '' not in sys.path:
c08423d70b9f Merged revisions 76312 via svnmerge from
Nick Coghlan <ncoghlan@gmail.com>
parents: 54827
diff changeset
2258 scriptdir = os.path.dirname(sys.argv[0])
c08423d70b9f Merged revisions 76312 via svnmerge from
Nick Coghlan <ncoghlan@gmail.com>
parents: 54827
diff changeset
2259 if scriptdir in sys.path:
c08423d70b9f Merged revisions 76312 via svnmerge from
Nick Coghlan <ncoghlan@gmail.com>
parents: 54827
diff changeset
2260 sys.path.remove(scriptdir)
c08423d70b9f Merged revisions 76312 via svnmerge from
Nick Coghlan <ncoghlan@gmail.com>
parents: 54827
diff changeset
2261 sys.path.insert(0, '.')
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
2262
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2263 try:
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2264 opts, args = getopt.getopt(sys.argv[1:], 'gk:p:w')
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2265 writing = 0
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2266
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2267 for opt, val in opts:
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2268 if opt == '-g':
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2269 gui()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2270 return
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2271 if opt == '-k':
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2272 apropos(val)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2273 return
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2274 if opt == '-p':
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2275 try:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2276 port = int(val)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2277 except ValueError:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2278 raise BadUsage
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2279 def ready(server):
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2280 print 'pydoc server ready at %s' % server.url
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2281 def stopped():
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2282 print 'pydoc server stopped'
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2283 serve(port, ready, stopped)
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2284 return
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2285 if opt == '-w':
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2286 writing = 1
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2287
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2288 if not args: raise BadUsage
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2289 for arg in args:
24740
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
2290 if ispath(arg) and not os.path.exists(arg):
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
2291 print 'file %r does not exist' % arg
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
2292 break
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2293 try:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2294 if ispath(arg) and os.path.isfile(arg):
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2295 arg = importfile(arg)
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2296 if writing:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2297 if ispath(arg) and os.path.isdir(arg):
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2298 writedocs(arg)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2299 else:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2300 writedoc(arg)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2301 else:
29463
74a28f2e94cf Support keyword and topics help in cli(). Fixes #715782.
Martin v. Löwis <martin@v.loewis.de>
parents: 29409
diff changeset
2302 help.help(arg)
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
2303 except ErrorDuringImport, value:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2304 print value
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2305
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2306 except (getopt.error, BadUsage):
30821
ec1a4a29d25d Patch #785689: Use basename in usage. Backported to 2.3.
Martin v. Löwis <martin@v.loewis.de>
parents: 30698
diff changeset
2307 cmd = os.path.basename(sys.argv[0])
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2308 print """pydoc - the Python documentation tool
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2309
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2310 %s <name> ...
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2311 Show text documentation on something. <name> may be the name of a
29463
74a28f2e94cf Support keyword and topics help in cli(). Fixes #715782.
Martin v. Löwis <martin@v.loewis.de>
parents: 29409
diff changeset
2312 Python keyword, topic, function, module, or package, or a dotted
74a28f2e94cf Support keyword and topics help in cli(). Fixes #715782.
Martin v. Löwis <martin@v.loewis.de>
parents: 29409
diff changeset
2313 reference to a class or function within a module or module in a
74a28f2e94cf Support keyword and topics help in cli(). Fixes #715782.
Martin v. Löwis <martin@v.loewis.de>
parents: 29409
diff changeset
2314 package. If <name> contains a '%s', it is used as the path to a
74a28f2e94cf Support keyword and topics help in cli(). Fixes #715782.
Martin v. Löwis <martin@v.loewis.de>
parents: 29409
diff changeset
2315 Python source file to document. If name is 'keywords', 'topics',
74a28f2e94cf Support keyword and topics help in cli(). Fixes #715782.
Martin v. Löwis <martin@v.loewis.de>
parents: 29409
diff changeset
2316 or 'modules', a listing of these things is displayed.
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2317
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2318 %s -k <keyword>
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2319 Search for a keyword in the synopsis lines of all available modules.
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2320
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2321 %s -p <port>
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2322 Start an HTTP server on the given port on the local machine.
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2323
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2324 %s -g
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
2325 Pop up a graphical interface for finding and serving documentation.
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2326
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2327 %s -w <name> ...
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2328 Write out the HTML documentation for a module to a file in the current
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
2329 directory. If <name> contains a '%s', it is treated as a filename; if
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
2330 it names a directory, documentation is written for all the contents.
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2331 """ % (cmd, os.sep, cmd, cmd, cmd, cmd, os.sep)
16875
10b84060b7f3 Normalize case of paths in sys.path to avoid duplicates on Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 16833
diff changeset
2332
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2333 if __name__ == '__main__': cli()