mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-29 05:05:03 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

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

95
Lib/pydoc.py
View file

@ -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):
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):
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 }
><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 }
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 }
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 }
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 }
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 }
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 }
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 }
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 }
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):
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):
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):
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):
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):
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):
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:
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)