Mercurial > cpython-lru_cache-weakref

annotate Lib/pydoc.py @ 54294:dba767bc3155 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
remove mention of old ctypes version
author Benjamin Peterson <benjamin@python.org>
date Sat, 23 May 2009 20:59:09 +0000
parents 64110c0ad530
children 154ca377f53c
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
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
58 try:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
59 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
60 except ImportError:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
61 # 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
62 class deque(list):
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
63 def popleft(self):
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
64 return self.pop(0)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
65
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
66 # --------------------------------------------------------- common routines
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
67
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
68 def pathdirs():
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
69 """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
70 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
71 normdirs = []
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
72 for dir in sys.path:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
73 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
74 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
75 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
76 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
77 normdirs.append(normdir)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
78 return dirs
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
79
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
80 def getdoc(object):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
81 """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
82 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
83 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
84
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
85 def splitdoc(doc):
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
86 """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
87 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
88 if len(lines) == 1:
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
89 return lines[0], ''
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
90 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
91 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
92 return '', join(lines, '\n')
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
93
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
94 def classname(object, modname):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
95 """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
96 name = object.__name__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
97 if object.__module__ != modname:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
98 name = object.__module__ + '.' + name
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
99 return name
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
100
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
101 def isdata(object):
35277
6ebc423f2d81 That was one too much.
Georg Brandl <georg@python.org>
parents: 35276
diff changeset
102 """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
103 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
104 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
105 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
106
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
107 def replace(text, *pairs):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
108 """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
109 while pairs:
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
110 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
111 pairs = pairs[2:]
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
112 return text
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
113
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
114 def cram(text, maxlen):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
115 """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
116 if len(text) > maxlen:
25871
cb910c394927 Explicitly use floor division
Raymond Hettinger <python@rcn.com>
parents: 25454
diff changeset
117 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
118 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
119 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
120 return text
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
121
32382
cde2feab7fe0 Change pydoc.stripid() be able to match against 64-bit addresses by having
Brett Cannon <bcannon@gmail.com>
parents: 32380
diff changeset
122 _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
123 def stripid(text):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
124 """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
125 # The behaviour of %p is implementation-dependent in terms of case.
c6ab0f88895a pydoc.stripid() is now case-insensitive for its regex to support platforms that
Brett Cannon <bcannon@gmail.com>
parents: 32321
diff changeset
126 if _re_stripid.search(repr(Exception)):
c6ab0f88895a pydoc.stripid() is now case-insensitive for its regex to support platforms that
Brett Cannon <bcannon@gmail.com>
parents: 32321
diff changeset
127 return _re_stripid.sub(r'\1', text)
16875
10b84060b7f3 Normalize case of paths in sys.path to avoid duplicates on Windows.
Ka-Ping Yee <ping@zesty.ca>
parents: 16833
diff changeset
128 return text
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
129
32380
c6ab0f88895a pydoc.stripid() is now case-insensitive for its regex to support platforms that
Brett Cannon <bcannon@gmail.com>
parents: 32321
diff changeset
130 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
131 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
132
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
133 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
134 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
135 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
136 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
137 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
138 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
139 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
140 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
141 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
142
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
143 def _split_list(s, predicate):
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
144 """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
145
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
146 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
147 ([x for x in s if predicate(x)],
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
148 [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
149 """
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
150
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
151 yes = []
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
152 no = []
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
153 for x in s:
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
154 if predicate(x):
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
155 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
156 else:
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
157 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
158 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
159
32321
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
160 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
161 """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
162 # Certain special names are redundant.
47873
5d8f47005b73 Issue 3190: pydoc now hides module __package__ attributes
Nick Coghlan <ncoghlan@gmail.com>
parents: 47431
diff changeset
163 _hidden_names = ('__builtins__', '__doc__', '__file__', '__path__',
5d8f47005b73 Issue 3190: pydoc now hides module __package__ attributes
Nick Coghlan <ncoghlan@gmail.com>
parents: 47431
diff changeset
164 '__module__', '__name__', '__slots__', '__package__')
5d8f47005b73 Issue 3190: pydoc now hides module __package__ attributes
Nick Coghlan <ncoghlan@gmail.com>
parents: 47431
diff changeset
165 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
166 # 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
167 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
168 if all is not None:
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
169 # 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
170 return name in all
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
171 else:
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
172 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
173
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
174 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
175 """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
176 def fixup(data):
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
177 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
178 if inspect.isdatadescriptor(value):
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
179 kind = 'data descriptor'
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
180 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
181 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
182
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
183 # ----------------------------------------------------- module manipulation
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
184
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
185 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
186 """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
187 if os.path.isdir(path):
34545
9d66fba78444 Replace list of constants with tuples of constants.
Raymond Hettinger <python@rcn.com>
parents: 34369
diff changeset
188 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
189 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
190 return True
a9dd5e6d6805 Convert a pile of obvious "yes/no" functions to return bool.
Tim Peters <tim.peters@gmail.com>
parents: 22506
diff changeset
191 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
192
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
193 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
194 line = file.readline()
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
195 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
196 line = file.readline()
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
197 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
198 line = strip(line)
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
199 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
200 if line[:3] == '"""':
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
201 line = line[3:]
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
202 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
203 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
204 line = file.readline()
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
205 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
206 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
207 else: result = None
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
208 return result
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
209
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
210 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
211 """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
212 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
213 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
214 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
215 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
216 try:
4b347c654635 Fix pydoc.synopsis() so that it doesn't error out with an unreadable
Georg Brandl <georg@python.org>
parents: 36545
diff changeset
217 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
218 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
219 # 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
220 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
221 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
222 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
223 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
224 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
225 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
226 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
227 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
228 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
229 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
230 return result
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
231
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
232 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
233 """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
234 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
235 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
236 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
237 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
238 self.value = value
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
239 self.tb = tb
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
240
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
241 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
242 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
243 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
244 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
245 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
246
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
247 def importfile(path):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
248 """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
249 magic = imp.get_magic()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
250 file = open(path, 'r')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
251 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
252 kind = imp.PY_COMPILED
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
253 else:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
254 kind = imp.PY_SOURCE
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
255 file.close()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
256 filename = os.path.basename(path)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
257 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
258 file = open(path, 'r')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
259 try:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
260 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
261 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
262 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
263 file.close()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
264 return module
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
265
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
266 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
267 """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
268
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
269 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
270 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
271 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
272 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
273 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
274 try:
35838
49baf8b04681 Fix SF bug #417833 (pydoc HTTP reload failure) by removing from
Ka-Ping Yee <ping@zesty.ca>
parents: 35837
diff changeset
275 # 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
276 # 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
277 # 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
278 # 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
279 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
280 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
281 # 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
282 # 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
283 # 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
284 # 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
285 # 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
286 # 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
287 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
288 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
289 # 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
290 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
291 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
292 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
293 except:
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
294 # 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
295 (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
296 if path in sys.modules:
35806
44fe157255bc fix typos, mostly in comments
Fred Drake <fdrake@acm.org>
parents: 35742
diff changeset
297 # 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
298 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
299 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
300 # 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
301 raise ErrorDuringImport(value.filename, info)
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
302 elif exc is ImportError and \
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
303 split(lower(str(value)))[:2] == ['no', 'module']:
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
304 # The module was not found.
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
305 return None
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
306 else:
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
307 # 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
308 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
309 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
310 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
311 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
312 return module
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
313
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
314 # ---------------------------------------------------- formatter base class
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
315
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
316 class Doc:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
317 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
318 """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
319 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
320 # '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
321 # 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
322 # 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
323 # 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
324 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
325 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
326 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
327 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
328 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
329 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
330 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
331 pass
33935
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
332 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
333 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
334
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
335 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
336 """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
337 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
338 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
339 raise TypeError, message
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
340
39226
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
341 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
342
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
343 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
344 """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
345
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 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
347 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
348 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
349 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
350
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
351 docloc = os.environ.get("PYTHONDOCS",
44845
27dac16541d9 Adapt pydoc to new doc URLs.
Georg Brandl <georg@python.org>
parents: 44660
diff changeset
352 "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
353 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
354 "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
355 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
356 (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
357 '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
358 '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
359 (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
360 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
361 if docloc.startswith("http://"):
44845
27dac16541d9 Adapt pydoc to new doc URLs.
Georg Brandl <georg@python.org>
parents: 44660
diff changeset
362 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
363 else:
44845
27dac16541d9 Adapt pydoc to new doc URLs.
Georg Brandl <georg@python.org>
parents: 44660
diff changeset
364 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
365 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
366 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
367 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
368
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
369 # -------------------------------------------- HTML documentation generator
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
370
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
371 class HTMLRepr(Repr):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
372 """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
373 def __init__(self):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
374 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
375 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
376 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
377 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
378
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
379 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
380 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
381
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
382 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
383 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
384
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
385 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
386 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
387 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
388 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
389 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
390 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
391
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
392 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
393 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
394 testrepr = repr(test)
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
395 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
396 # 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
397 # 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
398 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
399 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
400 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
401 self.escape(testrepr))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
402
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
403 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
404
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
405 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
406 try:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
407 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
408 except:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
409 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
410
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
411 repr_unicode = repr_string
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
412
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
413 class HTMLDoc(Doc):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
414 """Formatter class for HTML documentation."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
415
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
416 # ------------------------------------------- HTML formatting utilities
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
417
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
418 _repr_instance = HTMLRepr()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
419 repr = _repr_instance.repr
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
420 escape = _repr_instance.escape
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
421
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
422 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
423 """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
424 return '''
53034
0327504a4f6a Merged revisions 71443 via svnmerge from
Matthias Klose <doko@ubuntu.com>
parents: 50424
diff changeset
425 <!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
426 <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
427 </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
428 %s
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
429 </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
430
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
431 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
432 """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
433 return '''
20783
a2b11d00b697 SF patch #474485: pydoc generates some bad html, from Rich Salz.
Tim Peters <tim.peters@gmail.com>
parents: 20538
diff changeset
434 <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
435 <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
436 <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
437 <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
438 ><td align=right valign=bottom
17182
5ee3543ea33f Small formatting improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 17181
diff changeset
439 ><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
440 ''' % (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
441
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
442 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
443 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
444 """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
445 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
446 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
447 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
448 <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
449 <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
450 <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
451 <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
452 ''' % (bgcol, fgcol, title)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
453 if prelude:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
454 result = result + '''
17182
5ee3543ea33f Small formatting improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 17181
diff changeset
455 <tr bgcolor="%s"><td rowspan=2>%s</td>
5ee3543ea33f Small formatting improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 17181
diff changeset
456 <td colspan=2>%s</td></tr>
5ee3543ea33f Small formatting improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 17181
diff changeset
457 <tr><td>%s</td>''' % (bgcol, marginalia, prelude, gap)
5ee3543ea33f Small formatting improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 17181
diff changeset
458 else:
5ee3543ea33f Small formatting improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 17181
diff changeset
459 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
460 <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
461
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
462 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
463
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
464 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
465 """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
466 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
467 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
468
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
469 def preformat(self, text):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
470 """Format literal preformatted text."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
471 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
472 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
473 ' ', '&nbsp;', '\n', '<br>\n')
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
474
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
475 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
476 """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
477 result = ''
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
478 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
479 for col in range(cols):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
480 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
481 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
482 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
483 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
484 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
485 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
486
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
487 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
488
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
489 def namelink(self, name, *dicts):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
490 """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
491 for dict in dicts:
23620
a1de0bab5475 SF 563203. Replaced 'has_key()' with 'in'.
Raymond Hettinger <python@rcn.com>
parents: 23501
diff changeset
492 if name in dict:
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
493 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
494 return name
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
495
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
496 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
497 """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
498 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
499 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
500 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
501 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
502 return classname(object, modname)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
503
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
504 def modulelink(self, object):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
505 """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
506 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
507
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
508 def modpkglink(self, data):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
509 """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
510 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
511 if shadowed:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
512 return self.grey(name)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
513 if path:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
514 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
515 else:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
516 url = '%s.html' % name
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
517 if ispackage:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
518 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
519 else:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
520 text = name
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
521 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
522
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
523 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
524 """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
525 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
526 escape = escape or self.escape
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
527 results = []
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
528 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
529 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
530 r'RFC[- ]?(\d+)|'
17230
45cda1b39355 Fix some reloading problems (still more work needed).
Ka-Ping Yee <ping@zesty.ca>
parents: 17184
diff changeset
531 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
532 r'(self\.)?(\w+))')
22867
e2f2187c3d2c Partial introduction of bools where appropriate.
Guido van Rossum <guido@python.org>
parents: 22830
diff changeset
533 while True:
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
534 match = pattern.search(text, here)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
535 if not match: break
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
536 start, end = match.span()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
537 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
538
17230
45cda1b39355 Fix some reloading problems (still more work needed).
Ka-Ping Yee <ping@zesty.ca>
parents: 17184
diff changeset
539 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
540 if scheme:
22506
e94eddecf330 Quote href properly.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 22504
diff changeset
541 url = escape(all).replace('"', '&quot;')
e94eddecf330 Quote href properly.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 22504
diff changeset
542 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
543 elif rfc:
17230
45cda1b39355 Fix some reloading problems (still more work needed).
Ka-Ping Yee <ping@zesty.ca>
parents: 17184
diff changeset
544 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
545 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
546 elif pep:
45169
b011366102db Update PEP URL.
Andrew M. Kuchling <amk@amk.ca>
parents: 45014
diff changeset
547 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
548 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
549 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
550 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
551 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
552 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
553 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
554 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
555 here = end
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
556 results.append(escape(text[here:]))
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
557 return join(results, '')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
558
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
559 # ---------------------------------------------- type-specific routines
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
560
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
561 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
562 """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
563 result = ''
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
564 for entry in tree:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
565 if type(entry) is type(()):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
566 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
567 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
568 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
569 if bases and bases != (parent,):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
570 parents = []
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
571 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
572 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
573 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
574 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
575 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
576 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
577 entry, modname, c)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
578 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
579
20538
fe1b6ce4eb93 SF bug [#472347] pydoc and properties.
Tim Peters <tim.peters@gmail.com>
parents: 20125
diff changeset
580 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
581 """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
582 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
583 try:
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
584 all = object.__all__
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
585 except AttributeError:
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
586 all = None
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
587 parts = split(name, '.')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
588 links = []
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
589 for i in range(len(parts)-1):
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
590 links.append(
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
591 '<a href="%s.html"><font color="#ffffff">%s</font></a>' %
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
592 (join(parts[:i+1], '.'), parts[i]))
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
593 linkedname = join(links + parts[-1:], '.')
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
594 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
595 try:
16928
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
596 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
597 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
598 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
599 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
600 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
601 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
602 except TypeError:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
603 filelink = '(built-in)'
16811
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
604 info = []
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
605 if hasattr(object, '__version__'):
16811
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
606 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
607 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
608 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
609 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
610 if hasattr(object, '__date__'):
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
611 info.append(self.escape(str(object.__date__)))
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
612 if info:
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
613 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
614 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
615 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
616 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
617 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
618 docloc = ''
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
619 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
620 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
621 '<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
622
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
623 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
624
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
625 classes, cdict = [], {}
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
626 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
627 # 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
628 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
629 (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
630 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
631 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
632 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
633 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
634 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
635 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
636 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
637 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
638 if getattr(module, key) is base:
23620
a1de0bab5475 SF 563203. Replaced 'has_key()' with 'in'.
Raymond Hettinger <python@rcn.com>
parents: 23501
diff changeset
639 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
640 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
641 funcs, fdict = [], {}
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
642 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
643 # 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
644 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
645 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
646 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
647 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
648 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
649 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
650 data = []
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
651 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
652 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
653 data.append((key, value))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
654
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
655 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
656 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
657 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
658
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
659 if hasattr(object, '__path__'):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
660 modpkgs = []
37821
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
661 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
662 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
663 modpkgs.sort()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
664 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
665 result = result + self.bigsection(
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
666 'Package Contents', '#ffffff', '#aa55cc', contents)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
667 elif modules:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
668 contents = self.multicolumn(
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
669 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
670 result = result + self.bigsection(
45385
3d2ff0146574 #2133: fix HTML color spec.
Georg Brandl <georg@python.org>
parents: 45169
diff changeset
671 'Modules', '#ffffff', '#aa55cc', contents)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
672
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
673 if classes:
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
674 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
675 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
676 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
677 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
678 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
679 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
680 '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
681 if funcs:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
682 contents = []
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
683 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
684 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
685 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
686 '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
687 if data:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
688 contents = []
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
689 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
690 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
691 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
692 '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
693 if hasattr(object, '__author__'):
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
694 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
695 result = result + self.bigsection(
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
696 'Author', '#ffffff', '#7799ee', contents)
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
697 if hasattr(object, '__credits__'):
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
698 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
699 result = result + self.bigsection(
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
700 'Credits', '#ffffff', '#7799ee', contents)
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
701
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
702 return result
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
703
20538
fe1b6ce4eb93 SF bug [#472347] pydoc and properties.
Tim Peters <tim.peters@gmail.com>
parents: 20125
diff changeset
704 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
705 *ignored):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
706 """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
707 realname = object.__name__
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
708 name = name or realname
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
709 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
710
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 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
712 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
713
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
714 # 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
715 class HorizontalRule:
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
716 def __init__(self):
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
717 self.needone = 0
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
718 def maybe(self):
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
719 if self.needone:
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
720 push('<hr>\n')
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
721 self.needone = 1
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
722 hr = HorizontalRule()
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
723
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
724 # List the mro, if non-trivial.
31436
63fa60f2d61c * Move collections.deque() in from the sandbox
Raymond Hettinger <python@rcn.com>
parents: 30821
diff changeset
725 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
726 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
727 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
728 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
729 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
730 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
731 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
732 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
733
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
734 def spill(msg, attrs, predicate):
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
735 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
736 if ok:
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
737 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
738 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
739 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
740 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
741 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
742 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
743 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
744
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
745 def spilldescriptors(msg, attrs, predicate):
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
746 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
747 if ok:
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
748 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
749 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
750 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
751 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
752 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
753
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
754 def spilldata(msg, attrs, predicate):
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
755 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
756 if ok:
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
757 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
758 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
759 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
760 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
761 if (hasattr(value, '__call__') or
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
762 inspect.isdatadescriptor(value)):
23501
62688d6ac387 In both spilldata() functions, pretend that the docstring for
Guido van Rossum <guido@python.org>
parents: 22867
diff changeset
763 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
764 else:
62688d6ac387 In both spilldata() functions, pretend that the docstring for
Guido van Rossum <guido@python.org>
parents: 22867
diff changeset
765 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
766 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
767 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
768 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
769 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
770 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
771 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
772 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
773 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
774 return attrs
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
775
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
776 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
777 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
778 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
779 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
780 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
781 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
782 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
783 # 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
784 # 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
785 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
786 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
787 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
788
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
789 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
790 if mro:
31436
63fa60f2d61c * Move collections.deque() in from the sandbox
Raymond Hettinger <python@rcn.com>
parents: 30821
diff changeset
791 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
792 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
793 thisclass = attrs[0][2]
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
794 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
795
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
796 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
797 attrs = inherited
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
798 continue
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
799 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
800 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
801 else:
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
802 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
803 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
804 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
805
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
806 # 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
807 try:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
808 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
809 except TypeError:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
810 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
811
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
812 # 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
813 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
814 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
815 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
816 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
817 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
818 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
819 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
820 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
821 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
822 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
823 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
824 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
825
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
826 contents = ''.join(contents)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
827
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
828 if name == realname:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
829 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
830 name, realname)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
831 else:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
832 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
833 name, name, realname)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
834 if bases:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
835 parents = []
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
836 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
837 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
838 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
839 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
840 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
841
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
842 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
843
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
844 def formatvalue(self, object):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
845 """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
846 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
847
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
848 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
849 funcs={}, classes={}, methods={}, cl=None):
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
850 """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
851 realname = object.__name__
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
852 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
853 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
854 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
855 skipdocs = 0
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
856 if inspect.ismethod(object):
17456
3bda59071389 Fix call to ModuleScanner from GUI search interface.
Ka-Ping Yee <ping@zesty.ca>
parents: 17452
diff changeset
857 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
858 if cl:
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
859 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
860 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
861 else:
41175
ca338d563a7a Patch #1194449: correctly detect unbound methods in pydoc.
Georg Brandl <georg@python.org>
parents: 41166
diff changeset
862 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
863 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
864 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
865 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
866 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
867 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
868
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
869 if name == realname:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
870 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
871 else:
23620
a1de0bab5475 SF 563203. Replaced 'has_key()' with 'in'.
Raymond Hettinger <python@rcn.com>
parents: 23501
diff changeset
872 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
873 cl.__dict__[realname] is object):
17184
56d195f21b4f Browser compatibility fixes.
Ka-Ping Yee <ping@zesty.ca>
parents: 17182
diff changeset
874 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
875 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
876 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
877 else:
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
878 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
879 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
880 anchor, name, reallink)
19993
28ef22a2598e Since inspect.isfunction(obj) is a precondition for calling
Tim Peters <tim.peters@gmail.com>
parents: 19989
diff changeset
881 if inspect.isfunction(object):
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
882 args, varargs, varkw, defaults = inspect.getargspec(object)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
883 argspec = inspect.formatargspec(
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
884 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
885 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
886 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
887 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
888 else:
28ef22a2598e Since inspect.isfunction(obj) is a precondition for calling
Tim Peters <tim.peters@gmail.com>
parents: 19989
diff changeset
889 argspec = '(...)'
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
890
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
891 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
892 '<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
893
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
894 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
895 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
896 else:
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
897 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
898 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
899 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
900 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
901
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
902 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
903 results = []
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
904 push = results.append
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
905
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
906 if name:
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
907 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
908 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
909 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
910 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
911 push('</dl>\n')
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
912
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
913 return ''.join(results)
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
914
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
915 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
916 """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
917 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
918
20538
fe1b6ce4eb93 SF bug [#472347] pydoc and properties.
Tim Peters <tim.peters@gmail.com>
parents: 20125
diff changeset
919 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
920 """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
921 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
922 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
923
39226
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
924 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
925 """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
926 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
927
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
928 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
929 """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
930 modpkgs = []
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
931 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
932 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
933 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
934 shadowed[name] = 1
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
935
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
936 modpkgs.sort()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
937 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
938 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
939
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
940 # -------------------------------------------- text documentation generator
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
941
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
942 class TextRepr(Repr):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
943 """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
944 def __init__(self):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
945 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
946 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
947 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
948 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
949
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
950 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
951 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
952 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
953 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
954 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
955 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
956
16923
5ab4da6ad4fc Use imp.get_suffixes to determine a module name in modulename(file).
Ka-Ping Yee <ping@zesty.ca>
parents: 16908
diff changeset
957 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
958 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
959 testrepr = repr(test)
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
960 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
961 # 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
962 # 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
963 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
964 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
965
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
966 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
967
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
968 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
969 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
970 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
971 except:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
972 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
973
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
974 class TextDoc(Doc):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
975 """Formatter class for text documentation."""
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
976
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
977 # ------------------------------------------- text formatting utilities
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
978
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
979 _repr_instance = TextRepr()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
980 repr = _repr_instance.repr
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
981
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
982 def bold(self, text):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
983 """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
984 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
985
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
986 def indent(self, text, prefix=' '):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
987 """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
988 if not text: return ''
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
989 lines = split(text, '\n')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
990 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
991 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
992 return join(lines, '\n')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
993
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
994 def section(self, title, contents):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
995 """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
996 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
997
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
998 # ---------------------------------------------- type-specific routines
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
999
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1000 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
1001 """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
1002 result = ''
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1003 for entry in tree:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1004 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
1005 c, bases = entry
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1006 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
1007 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
1008 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
1009 result = result + '(%s)' % join(parents, ', ')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1010 result = result + '\n'
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1011 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
1012 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
1013 entry, modname, c, prefix + ' ')
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1014 return result
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1015
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1016 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
1017 """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
1018 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
1019 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
1020 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
1021
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1022 try:
32321
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
1023 all = object.__all__
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
1024 except AttributeError:
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
1025 all = None
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
1026
b0f454f558e5 Respect a module's __all__ attribute. Closes #969938.
Skip Montanaro <skip@pobox.com>
parents: 32288
diff changeset
1027 try:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1028 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
1029 except TypeError:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1030 file = '(built-in)'
16928
02e097f72d47 Clean up the handling of getsourcefile/getabsfile.
Ka-Ping Yee <ping@zesty.ca>
parents: 16923
diff changeset
1031 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
1032
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 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
1034 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
1035 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
1036
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
1037 if desc:
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
1038 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
1039
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1040 classes = []
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1041 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
1042 # 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
1043 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
1044 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
1045 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
1046 classes.append((key, value))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1047 funcs = []
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1048 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
1049 # 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
1050 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
1051 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
1052 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
1053 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
1054 data = []
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1055 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
1056 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
1057 data.append((key, value))
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1058
44860
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1059 modpkgs = []
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1060 modpkgs_names = set()
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1061 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
1062 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
1063 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
1064 if ispkg:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1065 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
1066 else:
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1067 modpkgs.append(modname)
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1068
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1069 modpkgs.sort()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1070 result = result + self.section(
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1071 'PACKAGE CONTENTS', join(modpkgs, '\n'))
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1072
44860
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1073 # 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
1074 submodules = []
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1075 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
1076 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
1077 submodules.append(key)
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1078 if submodules:
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1079 submodules.sort()
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1080 result = result + self.section(
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1081 'SUBMODULES', join(submodules, '\n'))
c3d9e57e71f2 #1715: include sub-extension modules in pydoc text output.
Georg Brandl <georg@python.org>
parents: 44845
diff changeset
1082
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1083 if classes:
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
1084 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
1085 contents = [self.formattree(
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1086 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
1087 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
1088 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
1089 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
1090
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1091 if funcs:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1092 contents = []
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1093 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
1094 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
1095 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
1096
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1097 if data:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1098 contents = []
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1099 for key, value in data:
35663
5611db451a39 bug [ 729103 ] Cannot retrieve name of super object
Georg Brandl <georg@python.org>
parents: 35277
diff changeset
1100 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
1101 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
1102
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1103 if hasattr(object, '__version__'):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1104 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
1105 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
1106 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
1107 result = result + self.section('VERSION', version)
16811
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
1108 if hasattr(object, '__date__'):
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
1109 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
1110 if hasattr(object, '__author__'):
16811
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
1111 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
1112 if hasattr(object, '__credits__'):
1d1bf6813ee5 Add display of $Revision $ and credits.
Ka-Ping Yee <ping@zesty.ca>
parents: 16791
diff changeset
1113 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
1114 return result
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1115
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1116 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
1117 """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
1118 realname = object.__name__
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1119 name = name or realname
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1120 bases = object.__bases__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1121
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
1122 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
1123 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
1124
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1125 if name == realname:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1126 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
1127 else:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1128 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
1129 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
1130 parents = map(makename, bases)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1131 title = title + '(%s)' % join(parents, ', ')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1132
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1133 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
1134 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
1135 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
1136
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
1137 # List the mro, if non-trivial.
31436
63fa60f2d61c * Move collections.deque() in from the sandbox
Raymond Hettinger <python@rcn.com>
parents: 30821
diff changeset
1138 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
1139 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
1140 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
1141 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
1142 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
1143 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
1144
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
1145 # 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
1146 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
1147 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
1148 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
1149 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
1150 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
1151 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
1152 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
1153 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
1154
20048
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1155 def spill(msg, attrs, predicate):
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1156 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
1157 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
1158 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
1159 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
1160 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
1161 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
1162 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
1163 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
1164
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1165 def spilldescriptors(msg, attrs, predicate):
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1166 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
1167 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
1168 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
1169 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
1170 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
1171 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
1172 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
1173
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1174 def spilldata(msg, attrs, predicate):
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1175 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
1176 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
1177 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
1178 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
1179 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
1180 if (hasattr(value, '__call__') or
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
1181 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
1182 doc = getdoc(value)
23501
62688d6ac387 In both spilldata() functions, pretend that the docstring for
Guido van Rossum <guido@python.org>
parents: 22867
diff changeset
1183 else:
62688d6ac387 In both spilldata() functions, pretend that the docstring for
Guido van Rossum <guido@python.org>
parents: 22867
diff changeset
1184 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
1185 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
1186 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
1187 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
1188
48141
4e6a0ae1a8e7 Silence SyntaxWarning and DeprecationWarning in pydoc triggered by tuple
Brett Cannon <bcannon@gmail.com>
parents: 47987
diff changeset
1189 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
1190 classify_class_attrs(object))
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1191 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
1192 if mro:
31436
63fa60f2d61c * Move collections.deque() in from the sandbox
Raymond Hettinger <python@rcn.com>
parents: 30821
diff changeset
1193 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
1194 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
1195 thisclass = attrs[0][2]
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1196 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
1197
28420
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
1198 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
1199 attrs = inherited
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
1200 continue
30d1c848d2b0 Hide private names beginning with _ (but don't hide __special__ names).
Ka-Ping Yee <ping@zesty.ca>
parents: 28124
diff changeset
1201 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
1202 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
1203 else:
20051
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1204 tag = "inherited from %s" % classname(thisclass,
4966cf793b44 More work on class display:
Tim Peters <tim.peters@gmail.com>
parents: 20050
diff changeset
1205 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
1206
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1207 # 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
1208 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
1209
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1210 # 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
1211 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
1212 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
1213 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
1214 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
1215 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
1216 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
1217 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
1218 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
1219 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
1220 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
1221 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
1222 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
1223
6310837ca534 Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
Tim Peters <tim.peters@gmail.com>
parents: 19993
diff changeset
1224 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
1225 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
1226 return title + '\n'
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1227 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
1228
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1229 def formatvalue(self, object):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1230 """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
1231 return '=' + self.repr(object)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1232
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1233 def docroutine(self, object, name=None, mod=None, cl=None):
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
1234 """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
1235 realname = object.__name__
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1236 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
1237 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
1238 skipdocs = 0
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1239 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
1240 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
1241 if cl:
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1242 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
1243 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
1244 else:
41175
ca338d563a7a Patch #1194449: correctly detect unbound methods in pydoc.
Georg Brandl <georg@python.org>
parents: 41166
diff changeset
1245 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
1246 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
1247 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
1248 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
1249 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
1250 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
1251
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1252 if name == realname:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1253 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
1254 else:
23620
a1de0bab5475 SF 563203. Replaced 'has_key()' with 'in'.
Raymond Hettinger <python@rcn.com>
parents: 23501
diff changeset
1255 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
1256 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
1257 skipdocs = 1
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1258 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
1259 if inspect.isfunction(object):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1260 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
1261 argspec = inspect.formatargspec(
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1262 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
1263 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
1264 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
1265 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
1266 else:
28ef22a2598e Since inspect.isfunction(obj) is a precondition for calling
Tim Peters <tim.peters@gmail.com>
parents: 19989
diff changeset
1267 argspec = '(...)'
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1268 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
1269
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
1270 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
1271 return decl + '\n'
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1272 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
1273 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
1274 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
1275
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1276 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
1277 results = []
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1278 push = results.append
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1279
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1280 if name:
34369
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1281 push(self.bold(name))
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1282 push('\n')
33935
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1283 doc = getdoc(value) or ''
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1284 if doc:
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1285 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
1286 push('\n')
ff73e15a3fb9 Patch #936774: unify the display of data descriptors, including slots,
Johannes Gijsbers <jlg@dds.nl>
parents: 34299
diff changeset
1287 return ''.join(results)
33935
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1288
ab73217730db Patch #1061931 / bug #971872: factor out part of spillproperties, so
Johannes Gijsbers <jlg@dds.nl>
parents: 33336
diff changeset
1289 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
1290 """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
1291 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
1292
39226
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1293 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
1294 """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
1295 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
1296
35663
5611db451a39 bug [ 729103 ] Cannot retrieve name of super object
Georg Brandl <georg@python.org>
parents: 35277
diff changeset
1297 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
1298 """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
1299 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
1300 if maxlen:
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1301 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
1302 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
1303 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
1304 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
1305 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
1306 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
1307 return line
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1308
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1309 # --------------------------------------------------------- user interfaces
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1310
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1311 def pager(text):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1312 """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
1313 global pager
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1314 pager = getpager()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1315 pager(text)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1316
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1317 def getpager():
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1318 """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
1319 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
1320 return plainpager
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1321 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
1322 return plainpager
23620
a1de0bab5475 SF 563203. Replaced 'has_key()' with 'in'.
Raymond Hettinger <python@rcn.com>
parents: 23501
diff changeset
1323 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
1324 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
1325 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
1326 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
1327 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
1328 else:
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1329 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
1330 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
1331 return plainpager
22117
1046964896a1 OS/2 more program behaves like Win32 more
Andrew MacIntyre <andymac@bullseye.apana.org.au>
parents: 20783
diff changeset
1332 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
1333 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
1334 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
1335 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
1336
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1337 import tempfile
24710
11c701038805 Massive changes from SF 589982 (tempfile.py rewrite, by Zack
Guido van Rossum <guido@python.org>
parents: 24606
diff changeset
1338 (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
1339 os.close(fd)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1340 try:
47987
ebe932329246 #3045: fix pydoc behavior for TEMP path with spaces.
Georg Brandl <georg@python.org>
parents: 47873
diff changeset
1341 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
1342 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
1343 else:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1344 return ttypager
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1345 finally:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1346 os.unlink(filename)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1347
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1348 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
1349 """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
1350 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
1351
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1352 def pipepager(text, cmd):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1353 """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
1354 pipe = os.popen(cmd, 'w')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1355 try:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1356 pipe.write(text)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1357 pipe.close()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1358 except IOError:
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1359 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
1360
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1361 def tempfilepager(text, cmd):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1362 """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
1363 import tempfile
27743
b331e5e5cc4a SF bug 666444: 'help' makes linefeed only under Win32.
Tim Peters <tim.peters@gmail.com>
parents: 26814
diff changeset
1364 filename = tempfile.mktemp()
b331e5e5cc4a SF bug 666444: 'help' makes linefeed only under Win32.
Tim Peters <tim.peters@gmail.com>
parents: 26814
diff changeset
1365 file = open(filename, 'w')
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1366 file.write(text)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1367 file.close()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1368 try:
47987
ebe932329246 #3045: fix pydoc behavior for TEMP path with spaces.
Georg Brandl <georg@python.org>
parents: 47873
diff changeset
1369 os.system(cmd + ' "' + filename + '"')
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1370 finally:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1371 os.unlink(filename)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1372
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1373 def ttypager(text):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1374 """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
1375 lines = split(plain(text), '\n')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1376 try:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1377 import tty
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1378 fd = sys.stdin.fileno()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1379 old = tty.tcgetattr(fd)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1380 tty.setcbreak(fd)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1381 getchar = lambda: sys.stdin.read(1)
16819
53e8ebd11620 Macintosh compatibility.
Ka-Ping Yee <ping@zesty.ca>
parents: 16818
diff changeset
1382 except (ImportError, AttributeError):
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1383 tty = None
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1384 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
1385
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1386 try:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1387 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
1388 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
1389 while lines[r:]:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1390 sys.stdout.write('-- more --')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1391 sys.stdout.flush()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1392 c = getchar()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1393
34545
9d66fba78444 Replace list of constants with tuples of constants.
Raymond Hettinger <python@rcn.com>
parents: 34369
diff changeset
1394 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
1395 sys.stdout.write('\r \r')
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1396 break
34545
9d66fba78444 Replace list of constants with tuples of constants.
Raymond Hettinger <python@rcn.com>
parents: 34369
diff changeset
1397 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
1398 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
1399 r = r + 1
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1400 continue
34545
9d66fba78444 Replace list of constants with tuples of constants.
Raymond Hettinger <python@rcn.com>
parents: 34369
diff changeset
1401 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
1402 r = r - inc - inc
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1403 if r < 0: r = 0
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1404 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
1405 r = r + inc
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1406
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1407 finally:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1408 if tty:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1409 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
1410
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1411 def plainpager(text):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1412 """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
1413 sys.stdout.write(plain(text))
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1414
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1415 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
1416 """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
1417 if inspect.ismodule(thing):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1418 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
1419 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
1420 if hasattr(thing, '__path__'):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1421 return 'package ' + thing.__name__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1422 else:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1423 return 'module ' + thing.__name__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1424 if inspect.isbuiltin(thing):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1425 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
1426 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
1427 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
1428 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
1429 thing.__name__)
28cdd43e0569 Patch #1520294: Support for getset and member descriptors in types.py,
Barry Warsaw <barry@python.org>
parents: 37821
diff changeset
1430 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
1431 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
1432 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
1433 thing.__name__)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1434 if inspect.isclass(thing):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1435 return 'class ' + thing.__name__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1436 if inspect.isfunction(thing):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1437 return 'function ' + thing.__name__
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1438 if inspect.ismethod(thing):
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1439 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
1440 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
1441 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
1442 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
1443
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1444 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
1445 """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
1446 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
1447 module, n = None, 0
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1448 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
1449 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
1450 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
1451 else: break
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1452 if module:
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1453 object = module
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1454 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
1455 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
1456 except AttributeError: return None
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1457 return object
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1458 else:
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1459 if hasattr(__builtin__, path):
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
1460 return getattr(__builtin__, path)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1461
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1462 # --------------------------------------- interactive interpreter interface
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1463
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1464 text = TextDoc()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1465 html = HTMLDoc()
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1466
40630
3d79bc6ed6ec Handle old-style instances more gracefully (display documentation on
Ka-Ping Yee <ping@zesty.ca>
parents: 40479
diff changeset
1467 class _OldStyleClass: pass
3d79bc6ed6ec Handle old-style instances more gracefully (display documentation on
Ka-Ping Yee <ping@zesty.ca>
parents: 40479
diff changeset
1468 _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
1469
24740
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1470 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
1471 """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
1472 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
1473 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
1474 if not object:
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1475 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
1476 return object, thing
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1477 else:
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1478 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
1479
41166
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1480 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
1481 """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
1482 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
1483 desc = describe(object)
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1484 module = inspect.getmodule(object)
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1485 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
1486 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
1487 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
1488 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
1489 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
1490 # 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
1491 # 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
1492 object = object.__class__
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1493 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
1494 inspect.isclass(object) or
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1495 inspect.isroutine(object) or
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1496 inspect.isgetsetdescriptor(object) or
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1497 inspect.ismemberdescriptor(object) or
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1498 isinstance(object, property)):
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1499 # 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
1500 # 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
1501 object = type(object)
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1502 desc += ' object'
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1503 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
1504
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1505 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
1506 """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
1507 try:
41166
4a79dd15ba59 Patch #1530482: add pydoc.render_doc() which returns the documentation
Georg Brandl <georg@python.org>
parents: 41147
diff changeset
1508 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
1509 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
1510 print value
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1511
24740
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1512 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
1513 """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
1514 try:
24740
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1515 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
1516 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
1517 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
1518 file.write(page)
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1519 file.close()
10391d58d184 Extend stripid() to handle strings ending in more than one '>'.
Ka-Ping Yee <ping@zesty.ca>
parents: 24710
diff changeset
1520 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
1521 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
1522 print value
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
1523
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1524 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
1525 """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
1526 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
1527 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
1528 writedoc(modname)
3135648026c4 Second phase of refactoring for runpy, pkgutil, pydoc, and setuptools
Phillip J. Eby <pje@telecommunity.com>
parents: 36893
diff changeset
1529 return
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1530
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1531 class Helper:
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1532
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1533 # 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
1534 # (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
1535 # section in the .rst file under Doc/ and an index into the dictionary
53461
64110c0ad530 Move pydoc_topics module to its own subdirectory, so that no generated code is in Lib/.
Georg Brandl <georg@python.org>
parents: 53034
diff changeset
1536 # in pydoc_data/topics.py.
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1537 #
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1538 # 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
1539 # list of needed labels in Doc/tools/sphinxext/pyspecific.py and
53461
64110c0ad530 Move pydoc_topics module to its own subdirectory, so that no generated code is in Lib/.
Georg Brandl <georg@python.org>
parents: 53034
diff changeset
1540 # regenerate the pydoc_data/topics.py file by running
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1541 # make pydoc-topics
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1542 # 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
1543
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1544 keywords = {
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1545 'and': 'BOOLEAN',
41147
b89437e3bc8e Patch #1542681: add entries for "with", "as" and "CONTEXTMANAGERS" to
Georg Brandl <georg@python.org>
parents: 40996
diff changeset
1546 'as': 'with',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1547 'assert': ('assert', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1548 '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
1549 '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
1550 '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
1551 'def': ('function', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1552 '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
1553 'elif': 'if',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1554 '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
1555 'except': 'try',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1556 '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
1557 'finally': 'try',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1558 '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
1559 'from': 'import',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1560 'global': ('global', 'NAMESPACES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1561 'if': ('if', 'TRUTHVALUE'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1562 'import': ('import', 'MODULES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1563 '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
1564 'is': 'COMPARISON',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1565 '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
1566 'not': 'BOOLEAN',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1567 'or': 'BOOLEAN',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1568 'pass': ('pass', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1569 'print': ('print', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1570 'raise': ('raise', 'EXCEPTIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1571 'return': ('return', 'FUNCTIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1572 'try': ('try', 'EXCEPTIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1573 '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
1574 '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
1575 'yield': ('yield', ''),
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1576 }
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
1577 # 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
1578 # 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
1579 _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
1580 '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
1581 '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
1582 '|', '^', '~', '<', '>', '<=', '>=', '==', '!=', '<>'),
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 '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
1584 '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
1585 '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
1586 '^=', '<<=', '>>=', '**=', '//='),
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 '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
1588 '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
1589 }
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 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
1591 '%': '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
1592 '**': '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
1593 ',': '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
1594 '.': '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
1595 '...': '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
1596 ':': '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
1597 '@': '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
1598 '\\': '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
1599 '_': '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
1600 '__': '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
1601 '`': '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
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 ')': '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
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 ']': '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
1606 }
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 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
1608 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
1609 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
1610 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
1611 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
1612 symbols[symbol] = topics
17230
45cda1b39355 Fix some reloading problems (still more work needed).
Ka-Ping Yee <ping@zesty.ca>
parents: 17184
diff changeset
1613
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1614 topics = {
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1615 '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
1616 '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
1617 '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
1618 'TYPES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1619 '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
1620 'FORMATTING': ('formatstrings', 'OPERATORS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1621 '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
1622 'FORMATTING TYPES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1623 '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
1624 '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
1625 '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
1626 '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
1627 '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
1628 'MAPPINGS': 'DICTIONARIES',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1629 '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
1630 '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
1631 '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
1632 '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
1633 'FRAMEOBJECTS': 'TYPES',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1634 'TRACEBACKS': 'TYPES',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1635 '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
1636 '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
1637 '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
1638 'SPECIALATTRIBUTES': ('specialattrs', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1639 '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
1640 '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
1641 'PACKAGES': 'import',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1642 '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
1643 '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
1644 '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
1645 '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
1646 'OPERATORS': 'EXPRESSIONS',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1647 'PRECEDENCE': 'EXPRESSIONS',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1648 'OBJECTS': ('objects', 'TYPES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1649 '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
1650 'CALLABLEMETHODS SEQUENCEMETHODS1 MAPPINGMETHODS '
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1651 'SEQUENCEMETHODS2 NUMBERMETHODS CLASSES'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1652 '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
1653 '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
1654 '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
1655 '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
1656 'SPECIALMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1657 '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
1658 'SPECIALMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1659 '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
1660 '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
1661 'SPECIALMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1662 '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
1663 '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
1664 '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
1665 'SCOPING': 'NAMESPACES',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1666 'FRAMES': 'NAMESPACES',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1667 '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
1668 '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
1669 'CONVERSIONS': ('conversions', 'COERCIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1670 '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
1671 'SPECIALIDENTIFIERS': ('id-classes', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1672 'PRIVATENAMES': ('atom-identifiers', ''),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1673 '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
1674 '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
1675 'TUPLES': 'SEQUENCES',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1676 '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
1677 '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
1678 '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
1679 'DICTIONARIES': ('typesmapping', 'DICTIONARYLITERALS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1680 '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
1681 '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
1682 '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
1683 'ATTRIBUTEMETHODS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1684 'SUBSCRIPTS': ('subscriptions', 'SEQUENCEMETHODS1'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1685 'SLICINGS': ('slicings', 'SEQUENCEMETHODS2'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1686 'CALLS': ('calls', 'EXPRESSIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1687 'POWER': ('power', 'EXPRESSIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1688 'UNARY': ('unary', 'EXPRESSIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1689 'BINARY': ('binary', 'EXPRESSIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1690 'SHIFTING': ('shifting', 'EXPRESSIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1691 'BITWISE': ('bitwise', 'EXPRESSIONS'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1692 '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
1693 '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
1694 'ASSERTION': 'assert',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1695 'ASSIGNMENT': ('assignment', 'AUGMENTEDASSIGNMENT'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1696 '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
1697 'DELETION': 'del',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1698 'PRINTING': 'print',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1699 'RETURNING': 'return',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1700 'IMPORTING': 'import',
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1701 'CONDITIONAL': 'if',
47431
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1702 '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
1703 '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
1704 'DEBUGGING': ('debugger', 'pdb'),
c0d616f0ad86 Generate pydoc's topic help from the reST docs via Sphinx'
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
1705 '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
1706 }
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1707
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1708 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
1709 self.input = input
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1710 self.output = output
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1711
17471
24e81b43067d Another pass through the topic table to fill in cross references.
Ka-Ping Yee <ping@zesty.ca>
parents: 17470
diff changeset
1712 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
1713 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
1714 self()
24e81b43067d Another pass through the topic table to fill in cross references.
Ka-Ping Yee <ping@zesty.ca>
parents: 17470
diff changeset
1715 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
1716 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
1717
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1718 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
1719 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
1720 self.help(request)
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
1721 else:
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1722 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
1723 self.interact()
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1724 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
1725 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
1726 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
1727 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
1728 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
1729 ''')
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1730
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1731 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
1732 self.output.write('\n')
22867
e2f2187c3d2c Partial introduction of bools where appropriate.
Guido van Rossum <guido@python.org>
parents: 22830
diff changeset
1733 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
1734 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
1735 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
1736 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
1737 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
1738 break
17470
b4e2b8e9f1e6 Make force-loading optional; don't force-load in interactive mode.
Ka-Ping Yee <ping@zesty.ca>
parents: 17457
diff changeset
1739 request = strip(replace(request, '"', '', "'", ''))
34545
9d66fba78444 Replace list of constants with tuples of constants.
Raymond Hettinger <python@rcn.com>
parents: 34369
diff changeset
1740 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
1741 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
1742
33162
208fe719c749 Use readline/raw_input() in pydoc.Helper.interact if available and self.input
Johannes Gijsbers <jlg@dds.nl>
parents: 32382
diff changeset
1743 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
1744 """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
1745 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
1746 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
1747 else:
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.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
1749 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
1750 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
1751
17452
1a2fd5c4dcf5 Added a big new Helper class to provide interactive help!
Ka-Ping Yee <ping@zesty.ca>
parents: 17447
diff changeset
1752 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
1753 if type(request) is type(''):
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:
53461
64110c0ad530 Move pydoc_topics module to its own subdirectory, so that no generated code is in Lib/.
Georg Brandl <georg@python.org>
parents: 53034
diff changeset
1824 import pydoc_data.topics
47431
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
53461
64110c0ad530 Move pydoc_topics module to its own subdirectory, so that no generated code is in Lib/.
Georg Brandl <georg@python.org>
parents: 53034
diff changeset
1828 module "pydoc_data.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:
53461
64110c0ad530 Move pydoc_topics module to its own subdirectory, so that no generated code is in Lib/.
Georg Brandl <georg@python.org>
parents: 53034
diff changeset
1840 doc = pydoc_data.topics.topics[label]
47431
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
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
2255 # Scripts don't get the current directory in their path by default.
17230
45cda1b39355 Fix some reloading problems (still more work needed).
Ka-Ping Yee <ping@zesty.ca>
parents: 17184
diff changeset
2256 scriptdir = os.path.dirname(sys.argv[0])
45cda1b39355 Fix some reloading problems (still more work needed).
Ka-Ping Yee <ping@zesty.ca>
parents: 17184
diff changeset
2257 if scriptdir in sys.path:
45cda1b39355 Fix some reloading problems (still more work needed).
Ka-Ping Yee <ping@zesty.ca>
parents: 17184
diff changeset
2258 sys.path.remove(scriptdir)
17181
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
2259 sys.path.insert(0, '.')
7916d32aa081 Show inherited methods, with hyperlinks to the base class they came from.
Ka-Ping Yee <ping@zesty.ca>
parents: 17163
diff changeset
2260
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2261 try:
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2262 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
2263 writing = 0
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2264
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2265 for opt, val in opts:
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2266 if opt == '-g':
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2267 gui()
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2268 return
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2269 if opt == '-k':
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2270 apropos(val)
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2271 return
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2272 if opt == '-p':
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2273 try:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2274 port = int(val)
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2275 except ValueError:
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2276 raise BadUsage
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2277 def ready(server):
17441
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2278 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
2279 def stopped():
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2280 print 'pydoc server stopped'
74b9fb1c9633 Properly qualify methods inherited from classes in other modules.
Ka-Ping Yee <ping@zesty.ca>
parents: 17372
diff changeset
2281 serve(port, ready, stopped)
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2282 return
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2283 if opt == '-w':
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2284 writing = 1
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2285
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2286 if not args: raise BadUsage
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2287 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
2288 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
2289 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
2290 break
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2291 try:
17163
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2292 if ispath(arg) and os.path.isfile(arg):
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2293 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
2294 if writing:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2295 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
2296 writedocs(arg)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2297 else:
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2298 writedoc(arg)
ad683f20bb14 Fixes for various issues reported and discovered since Python 9:
Ka-Ping Yee <ping@zesty.ca>
parents: 17055
diff changeset
2299 else:
29463
74a28f2e94cf Support keyword and topics help in cli(). Fixes #715782.
Martin v. Löwis <martin@v.loewis.de>
parents: 29409
diff changeset
2300 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
2301 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
2302 print value
16791
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2303
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2304 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
2305 cmd = os.path.basename(sys.argv[0])
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2306 print """pydoc - the Python documentation tool
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2307
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2308 %s <name> ...
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2309 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
2310 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
2311 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
2312 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
2313 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
2314 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
2315
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2316 %s -k <keyword>
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2317 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
2318
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2319 %s -p <port>
a89f783c133a pydoc: text and HTML documentation generator for interactive use
Ka-Ping Yee <ping@zesty.ca>
parents:
diff changeset
2320 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
2321
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2322 %s -g
17371
e843eee7a33e Fix synopsis() so it can handle binary module files.
Ka-Ping Yee <ping@zesty.ca>
parents: 17230
diff changeset
2323 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
2324
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2325 %s -w <name> ...
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2326 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
2327 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
2328 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
2329 """ % (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
2330
16897
74a9d0a4231a Docstring improvements.
Ka-Ping Yee <ping@zesty.ca>
parents: 16875
diff changeset
2331 if __name__ == '__main__': cli()