Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-01 22:21:35 +00:00
Code Issues Projects Releases Packages Wiki Activity

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

Browse source 
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.
This commit is contained in:
Ka-Ping Yee 2003-03-28 16:35:51 +00:00
parent b38bbbd387
commit d9e213eeca
1 changed files with 77 additions and 54 deletions
Download patch file Download diff file Expand all files Collapse all files

131
Lib/pydoc.py
View file

@ -44,7 +44,7 @@ class or function within a module or module in a package. If the
# 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):
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 @@ def page(self, title, contents):
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 @@ def heading(self, title, fgcol, bgcol, extras=''):
><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,8 +536,9 @@ def docmodule(self, object, name=None, mod=None, *ignored):
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:
classes.append((key, value)) if visiblename(key):
cdict[key] = cdict[value] = '#' + key classes.append((key, value))
cdict[key] = cdict[value] = '#' + key
for key, value in classes: for key, value in classes:
for base in value.__bases__: for base in value.__bases__:
key, modname = base.__name__, base.__module__ key, modname = base.__name__, base.__module__
@ -542,12 +550,13 @@ def docmodule(self, object, name=None, mod=None, *ignored):
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:
funcs.append((key, value)) if visiblename(key):
fdict[key] = '#-' + key funcs.append((key, value))
if inspect.isfunction(value): fdict[value] = fdict[key] fdict[key] = '#-' + 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,11 +569,12 @@ def docmodule(self, object, name=None, mod=None, *ignored):
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 and modname not in modnames: if modname != '__init__':
modpkgs.append((modname, name, 0, 0)) if modname and modname not in modnames:
modnames.append(modname) modpkgs.append((modname, name, 0, 0))
elif ispackage(path): modnames.append(modname)
modpkgs.append((file, name, 1, 0)) elif ispackage(path):
modpkgs.append((file, name, 1, 0))
modpkgs.sort() modpkgs.sort()
contents = self.multicolumn(modpkgs, self.modpkglink) contents = self.multicolumn(modpkgs, self.modpkglink)
result = result + self.bigsection( result = result + self.bigsection(
@ -658,12 +668,12 @@ def spillproperties(msg, attrs, predicate):
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 @@ def spilldata(msg, attrs, predicate):
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,26 +720,29 @@ def spilldata(msg, attrs, predicate):
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'
# Sort attrs by name. # Sort attrs by name.
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 @@ def spilldata(msg, attrs, predicate):
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 @@ def docmodule(self, object, name=None, mod=None):
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:
classes.append((key, value)) if visiblename(key):
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:
funcs.append((key, value)) if visiblename(key):
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,10 +966,11 @@ def docmodule(self, object, name=None, mod=None):
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 and modname not in modpkgs: if modname != '__init__':
modpkgs.append(modname) if modname and modname not in modpkgs:
elif ispackage(path): modpkgs.append(modname)
modpkgs.append(file + ' (package)') elif ispackage(path):
modpkgs.append(file + ' (package)')
modpkgs.sort() modpkgs.sort()
result = result + self.section( result = result + self.section(
'PACKAGE CONTENTS', join(modpkgs, '\n')) 'PACKAGE CONTENTS', join(modpkgs, '\n'))
@ -1052,17 +1069,16 @@ def spillproperties(msg, attrs, predicate):
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 @@ def spilldata(msg, attrs, predicate):
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 @@ def spilldata(msg, attrs, predicate):
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 @@ def spilldata(msg, attrs, predicate):
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):
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):
elif os.path.isfile(path): elif os.path.isfile(path):
modname = inspect.getmodulename(path) modname = inspect.getmodulename(path)
if modname: if modname:
modname = pkgpath + modname if modname == '__init__':
if not modname in done: modname = pkgpath[:-1] # remove trailing period
else:
modname = pkgpath + modname
if modname not in done:
done[modname] = 1 done[modname] = 1
writedoc(modname) writedoc(modname)