Skip to content

C
cpython
Commit d9e213ee authored by Ka-Ping Yee's avatar Ka-Ping Yee
Browse files
Options

Hide private names beginning with _ (but don't hide __special__ names). 

Clean up section headings; make the bars on the left less fat.
Adjust the display of properties slightly.
Don't show stuff inherited from the base 'object' type.
parent b38bbbd3
Show whitespace changes
Inline Side-by-side
Showing with 77 additions and 54 deletions
Lib/pydoc.py
View file @ d9e213ee
...@@ -44,7 +44,7 @@ Mynd you, m ...@@ -44,7 +44,7 @@ Mynd you, m
# the current directory is changed with os.chdir(), an incorrect # the current directory is changed with os.chdir(), an incorrect
# path will be displayed. # path will be displayed.
import sys, imp, os, re, types, inspect import sys, imp, os, re, types, inspect, __builtin__
from repr import Repr from repr import Repr
from string import expandtabs, find, join, lower, split, strip, rfind, rstrip from string import expandtabs, find, join, lower, split, strip, rfind, rstrip
...@@ -142,6 +142,15 @@ def _split_list(s, predicate): ...@@ -142,6 +142,15 @@ def _split_list(s, predicate):
no.append(x) no.append(x)
return yes, no return yes, no
def visiblename(name):
"""Decide whether to show documentation on a variable."""
# Certain special names are redundant.
if name in ['__builtins__', '__doc__', '__file__', '__path__',
'__module__', '__name__']: return 0
# Private names are hidden, but special names are displayed.
if name.startswith('__') and name.endswith('__'): return 1
return not name.startswith('_')
# ----------------------------------------------------- module manipulation # ----------------------------------------------------- module manipulation
def ispackage(path): def ispackage(path):
...@@ -337,9 +346,7 @@ class HTMLDoc(Doc): ...@@ -337,9 +346,7 @@ class HTMLDoc(Doc):
return ''' return '''
<!doctype html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <!doctype html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><title>Python: %s</title> <html><head><title>Python: %s</title>
<style type="text/css"><!-- </head><body bgcolor="#f0f0f8">
TT { font-family: lucidatypewriter, lucida console, courier }
--></style></head><body bgcolor="#f0f0f8">
%s %s
</body></html>''' % (title, contents) </body></html>''' % (title, contents)
...@@ -354,12 +361,12 @@ TT { font-family: lucidatypewriter, lucida console, courier } ...@@ -354,12 +361,12 @@ TT { font-family: lucidatypewriter, lucida console, courier }
><font color="%s" face="helvetica, arial">%s</font></td></tr></table> ><font color="%s" face="helvetica, arial">%s</font></td></tr></table>
''' % (bgcol, fgcol, title, fgcol, extras or '&nbsp;') ''' % (bgcol, fgcol, title, fgcol, extras or '&nbsp;')
def section(self, title, fgcol, bgcol, contents, width=10, def section(self, title, fgcol, bgcol, contents, width=6,
prelude='', marginalia=None, gap='&nbsp;&nbsp;'): prelude='', marginalia=None, gap='&nbsp;'):
"""Format a section with a heading.""" """Format a section with a heading."""
if marginalia is None: if marginalia is None:
marginalia = '<tt>' + '&nbsp;' * width + '</tt>' marginalia = '<tt>' + '&nbsp;' * width + '</tt>'
result = ''' result = '''<p>
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section"> <table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="%s"> <tr bgcolor="%s">
<td colspan=3 valign=bottom>&nbsp;<br> <td colspan=3 valign=bottom>&nbsp;<br>
...@@ -529,6 +536,7 @@ TT { font-family: lucidatypewriter, lucida console, courier } ...@@ -529,6 +536,7 @@ TT { font-family: lucidatypewriter, lucida console, courier }
classes, cdict = [], {} classes, cdict = [], {}
for key, value in inspect.getmembers(object, inspect.isclass): for key, value in inspect.getmembers(object, inspect.isclass):
if (inspect.getmodule(value) or object) is object: if (inspect.getmodule(value) or object) is object:
if visiblename(key):
classes.append((key, value)) classes.append((key, value))
cdict[key] = cdict[value] = '#' + key cdict[key] = cdict[value] = '#' + key
for key, value in classes: for key, value in classes:
...@@ -542,12 +550,13 @@ TT { font-family: lucidatypewriter, lucida console, courier } ...@@ -542,12 +550,13 @@ TT { font-family: lucidatypewriter, lucida console, courier }
funcs, fdict = [], {} funcs, fdict = [], {}
for key, value in inspect.getmembers(object, inspect.isroutine): for key, value in inspect.getmembers(object, inspect.isroutine):
if inspect.isbuiltin(value) or inspect.getmodule(value) is object: if inspect.isbuiltin(value) or inspect.getmodule(value) is object:
if visiblename(key):
funcs.append((key, value)) funcs.append((key, value))
fdict[key] = '#-' + key fdict[key] = '#-' + key
if inspect.isfunction(value): fdict[value] = fdict[key] if inspect.isfunction(value): fdict[value] = fdict[key]
data = [] data = []
for key, value in inspect.getmembers(object, isdata): for key, value in inspect.getmembers(object, isdata):
if key not in ['__builtins__', '__doc__']: if visiblename(key):
data.append((key, value)) data.append((key, value))
doc = self.markup(getdoc(object), self.preformat, fdict, cdict) doc = self.markup(getdoc(object), self.preformat, fdict, cdict)
...@@ -560,6 +569,7 @@ TT { font-family: lucidatypewriter, lucida console, courier } ...@@ -560,6 +569,7 @@ TT { font-family: lucidatypewriter, lucida console, courier }
for file in os.listdir(object.__path__[0]): for file in os.listdir(object.__path__[0]):
path = os.path.join(object.__path__[0], file) path = os.path.join(object.__path__[0], file)
modname = inspect.getmodulename(file) modname = inspect.getmodulename(file)
if modname != '__init__':
if modname and modname not in modnames: if modname and modname not in modnames:
modpkgs.append((modname, name, 0, 0)) modpkgs.append((modname, name, 0, 0))
modnames.append(modname) modnames.append(modname)
...@@ -658,12 +668,12 @@ TT { font-family: lucidatypewriter, lucida console, courier } ...@@ -658,12 +668,12 @@ TT { font-family: lucidatypewriter, lucida console, courier }
doc = self.markup(value.__doc__, self.preformat, doc = self.markup(value.__doc__, self.preformat,
funcs, classes, mdict) funcs, classes, mdict)
push('<dd><tt>%s</tt></dd>\n' % doc) push('<dd><tt>%s</tt></dd>\n' % doc)
for attr, tag in [("fget", " getter"), for attr, tag in [('fget', '<em>get</em>'),
("fset", " setter"), ('fset', '<em>set</em>'),
("fdel", " deleter")]: ('fdel', '<em>delete</em>')]:
func = getattr(value, attr) func = getattr(value, attr)
if func is not None: if func is not None:
base = self.document(func, name + tag, mod, base = self.document(func, tag, mod,
funcs, classes, mdict, object) funcs, classes, mdict, object)
push('<dd>%s</dd>\n' % base) push('<dd>%s</dd>\n' % base)
push('</dl>\n') push('</dl>\n')
...@@ -690,7 +700,8 @@ TT { font-family: lucidatypewriter, lucida console, courier } ...@@ -690,7 +700,8 @@ TT { font-family: lucidatypewriter, lucida console, courier }
push('\n') push('\n')
return attrs return attrs
attrs = inspect.classify_class_attrs(object) attrs = filter(lambda (name, kind, cls, value): visiblename(name),
inspect.classify_class_attrs(object))
mdict = {} mdict = {}
for key, kind, homecls, value in attrs: for key, kind, homecls, value in attrs:
mdict[key] = anchor = '#' + name + '-' + key mdict[key] = anchor = '#' + name + '-' + key
...@@ -709,10 +720,13 @@ TT { font-family: lucidatypewriter, lucida console, courier } ...@@ -709,10 +720,13 @@ TT { font-family: lucidatypewriter, lucida console, courier }
thisclass = attrs[0][2] thisclass = attrs[0][2]
attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass) attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass)
if thisclass is object: if thisclass is __builtin__.object:
tag = "defined here" attrs = inherited
continue
elif thisclass is object:
tag = 'defined here'
else: else:
tag = "inherited from %s" % self.classlink(thisclass, tag = 'inherited from %s' % self.classlink(thisclass,
object.__module__) object.__module__)
tag += ':<br>\n' tag += ':<br>\n'
...@@ -720,15 +734,15 @@ TT { font-family: lucidatypewriter, lucida console, courier } ...@@ -720,15 +734,15 @@ TT { font-family: lucidatypewriter, lucida console, courier }
attrs.sort(lambda t1, t2: cmp(t1[0], t2[0])) attrs.sort(lambda t1, t2: cmp(t1[0], t2[0]))
# Pump out the attrs, segregated by kind. # Pump out the attrs, segregated by kind.
attrs = spill("Methods %s" % tag, attrs, attrs = spill('Methods %s' % tag, attrs,
lambda t: t[1] == 'method') lambda t: t[1] == 'method')
attrs = spill("Class methods %s" % tag, attrs, attrs = spill('Class methods %s' % tag, attrs,
lambda t: t[1] == 'class method') lambda t: t[1] == 'class method')
attrs = spill("Static methods %s" % tag, attrs, attrs = spill('Static methods %s' % tag, attrs,
lambda t: t[1] == 'static method') lambda t: t[1] == 'static method')
attrs = spillproperties("Properties %s" % tag, attrs, attrs = spillproperties('Properties %s' % tag, attrs,
lambda t: t[1] == 'property') lambda t: t[1] == 'property')
attrs = spilldata("Data and non-method functions %s" % tag, attrs, attrs = spilldata('Data and other attributes %s' % tag, attrs,
lambda t: t[1] == 'data') lambda t: t[1] == 'data')
assert attrs == [] assert attrs == []
attrs = inherited attrs = inherited
...@@ -747,9 +761,9 @@ TT { font-family: lucidatypewriter, lucida console, courier } ...@@ -747,9 +761,9 @@ TT { font-family: lucidatypewriter, lucida console, courier }
parents.append(self.classlink(base, object.__module__)) parents.append(self.classlink(base, object.__module__))
title = title + '(%s)' % join(parents, ', ') title = title + '(%s)' % join(parents, ', ')
doc = self.markup(getdoc(object), self.preformat, funcs, classes, mdict) doc = self.markup(getdoc(object), self.preformat, funcs, classes, mdict)
doc = doc and '<tt>%s<br>&nbsp;</tt>' % doc or '&nbsp;' doc = doc and '<tt>%s<br>&nbsp;</tt>' % doc
return self.section(title, '#000000', '#ffc8d8', contents, 5, doc) return self.section(title, '#000000', '#ffc8d8', contents, 3, doc)
def formatvalue(self, object): def formatvalue(self, object):
"""Format an argument default value as text.""" """Format an argument default value as text."""
...@@ -935,14 +949,16 @@ class TextDoc(Doc): ...@@ -935,14 +949,16 @@ class TextDoc(Doc):
classes = [] classes = []
for key, value in inspect.getmembers(object, inspect.isclass): for key, value in inspect.getmembers(object, inspect.isclass):
if (inspect.getmodule(value) or object) is object: if (inspect.getmodule(value) or object) is object:
if visiblename(key):
classes.append((key, value)) classes.append((key, value))
funcs = [] funcs = []
for key, value in inspect.getmembers(object, inspect.isroutine): for key, value in inspect.getmembers(object, inspect.isroutine):
if inspect.isbuiltin(value) or inspect.getmodule(value) is object: if inspect.isbuiltin(value) or inspect.getmodule(value) is object:
if visiblename(key):
funcs.append((key, value)) funcs.append((key, value))
data = [] data = []
for key, value in inspect.getmembers(object, isdata): for key, value in inspect.getmembers(object, isdata):
if key not in ['__builtins__', '__doc__']: if visiblename(key):
data.append((key, value)) data.append((key, value))
if hasattr(object, '__path__'): if hasattr(object, '__path__'):
...@@ -950,6 +966,7 @@ class TextDoc(Doc): ...@@ -950,6 +966,7 @@ class TextDoc(Doc):
for file in os.listdir(object.__path__[0]): for file in os.listdir(object.__path__[0]):
path = os.path.join(object.__path__[0], file) path = os.path.join(object.__path__[0], file)
modname = inspect.getmodulename(file) modname = inspect.getmodulename(file)
if modname != '__init__':
if modname and modname not in modpkgs: if modname and modname not in modpkgs:
modpkgs.append(modname) modpkgs.append(modname)
elif ispackage(path): elif ispackage(path):
...@@ -1052,17 +1069,16 @@ class TextDoc(Doc): ...@@ -1052,17 +1069,16 @@ class TextDoc(Doc):
if doc: if doc:
push(self.indent(doc)) push(self.indent(doc))
need_blank_after_doc = 1 need_blank_after_doc = 1
for attr, tag in [("fget", " getter"), for attr, tag in [('fget', '<get>'),
("fset", " setter"), ('fset', '<set>'),
("fdel", " deleter")]: ('fdel', '<delete>')]:
func = getattr(value, attr) func = getattr(value, attr)
if func is not None: if func is not None:
if need_blank_after_doc: if need_blank_after_doc:
push('') push('')
need_blank_after_doc = 0 need_blank_after_doc = 0
base = self.docother(func, name + tag, mod, 70) base = self.document(func, tag, mod)
push(self.indent(base)) push(self.indent(base))
push('')
return attrs return attrs
def spilldata(msg, attrs, predicate): def spilldata(msg, attrs, predicate):
...@@ -1079,7 +1095,8 @@ class TextDoc(Doc): ...@@ -1079,7 +1095,8 @@ class TextDoc(Doc):
name, mod, 70, doc) + '\n') name, mod, 70, doc) + '\n')
return attrs return attrs
attrs = inspect.classify_class_attrs(object) attrs = filter(lambda (name, kind, cls, value): visiblename(name),
inspect.classify_class_attrs(object))
while attrs: while attrs:
if mro: if mro:
thisclass = mro.pop(0) thisclass = mro.pop(0)
...@@ -1087,14 +1104,18 @@ class TextDoc(Doc): ...@@ -1087,14 +1104,18 @@ class TextDoc(Doc):
thisclass = attrs[0][2] thisclass = attrs[0][2]
attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass) attrs, inherited = _split_list(attrs, lambda t: t[2] is thisclass)
if thisclass is object: if thisclass is __builtin__.object:
attrs = inherited
continue
elif thisclass is object:
tag = "defined here" tag = "defined here"
else: else:
tag = "inherited from %s" % classname(thisclass, tag = "inherited from %s" % classname(thisclass,
object.__module__) object.__module__)
filter(lambda t: not t[0].startswith('_'), attrs)
# Sort attrs by name. # Sort attrs by name.
attrs.sort(lambda t1, t2: cmp(t1[0], t2[0])) attrs.sort()
# Pump out the attrs, segregated by kind. # Pump out the attrs, segregated by kind.
attrs = spill("Methods %s:\n" % tag, attrs, attrs = spill("Methods %s:\n" % tag, attrs,
...@@ -1105,8 +1126,8 @@ class TextDoc(Doc): ...@@ -1105,8 +1126,8 @@ class TextDoc(Doc):
lambda t: t[1] == 'static method') lambda t: t[1] == 'static method')
attrs = spillproperties("Properties %s:\n" % tag, attrs, attrs = spillproperties("Properties %s:\n" % tag, attrs,
lambda t: t[1] == 'property') lambda t: t[1] == 'property')
attrs = spilldata("Data and non-method functions %s:\n" % tag, attrs = spilldata("Data and other attributes %s:\n" % tag, attrs,
attrs, lambda t: t[1] == 'data') lambda t: t[1] == 'data')
assert attrs == [] assert attrs == []
attrs = inherited attrs = inherited
...@@ -1316,7 +1337,6 @@ def locate(path, forceload=0): ...@@ -1316,7 +1337,6 @@ def locate(path, forceload=0):
except AttributeError: return None except AttributeError: return None
return object return object
else: else:
import __builtin__
if hasattr(__builtin__, path): if hasattr(__builtin__, path):
return getattr(__builtin__, path) return getattr(__builtin__, path)
...@@ -1371,8 +1391,11 @@ def writedocs(dir, pkgpath='', done=None): ...@@ -1371,8 +1391,11 @@ def writedocs(dir, pkgpath='', done=None):
elif os.path.isfile(path): elif os.path.isfile(path):
modname = inspect.getmodulename(path) modname = inspect.getmodulename(path)
if modname: if modname:
if modname == '__init__':
modname = pkgpath[:-1] # remove trailing period
else:
modname = pkgpath + modname modname = pkgpath + modname
if not modname in done: if modname not in done:
done[modname] = 1 done[modname] = 1
writedoc(modname) writedoc(modname)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7