Quick Reference from module doc strings.

[Ron Adam]

Does anyone have suggestions on how to improve this further?
Cheers,
Ron_Adam

def getobjs(object, dlist=[], lvl=0, maxlevel=1):
""" Retrieve a list of sub objects from an object. """
if object not in dlist:
dlist.append(ob ject)
if lvl<maxlevel:
dobj = dir(eval(object ))
for item in dobj:
try:
dlist = getobjs(object+ '.'+item, dlist, lvl+1)
except:
pass
return dlist

def printdoc(object list):
""" Return a sorted printable quick reference
guide from a list of objects. """
outtext = []
objectlist.sort (lambda x, y: cmp(x.lower(), y.lower()))
for obj in objectlist:
object = eval(obj)
object_type = type(object)
outtext.append( '-'*40+'\n')
outtext.append( str(obj)+'\n')
if hasattr(object, '__module__'):
outtext.append( "Module:"+str(o bject.__module_ _)+'\n')
if hasattr( object,'__class __'):
outtext.append( "Class:"+str(ob ject.__class__) +'\n\n')
else:
outtext.append( "Type:"+str(obj ect_type)+'\n\n ')
if isinstance(obje ct,str):
if len(object)>200 :
s = object[0:200]+"......"
else:
s = object
outtext.append( obj+'=')
if '\n' in s: quotes='"""'
else: quotes ='"'
if len(s)>60: print
outtext.append( quotes+s+quotes +'\n\n')
elif (isinstance(obj ect,str)
or isinstance(obje ct,int)
or isinstance(obje ct,bool)
or isinstance(obje ct,tuple)
or isinstance(obje ct,list)
or isinstance(obje ct,dict)):
s = str(object)
if len(s)<200:
outtext.append( obj+'='+s+'\n\n ')
else:
outtext.append( obj+'='+s[0:200]+'......\n\n')
if hasattr(object, '__doc__'):
if object.__doc__ != type(object).__ doc__:
outtext.append( str(object.__do c__)+'\n\n')
return ''.join(outtext )

def quick_ref(name) :
"""
quick_ref(modul e_name) -> printable string

Generate a sorted quick reference guide from an objects
doc strings. The module_name is a string with the name of
the module or class to get documents string from.

Example:
import os
print quick_ref('os')
"""
objlist = getobjs(name)
return printdoc(objlis t)

if __name__ == "__main__":
#import module before calling in most cases.
print quick_ref('__bu iltins__')

[John Machin]

Ron Adam wrote:

Does anyone have suggestions on how to improve this further?
Not functionally (from me, yet). However if you can bear a stylistic
comment, do read on :-)
elif (isinstance(obj ect,str)
or isinstance(obje ct,int)
or isinstance(obje ct,bool)
or isinstance(obje ct,tuple)
or isinstance(obje ct,list)
or isinstance(obje ct,dict)):

Since Python version 2.2, the 2nd arg of isinstance may be a tuple. You
could define this up front, with a meaningful name:

TYPES_WHICH_wha tever = (str, int, bool, etc etc)

Cheers,
John

[Ron Adam]

John Machin wrote:

Ron Adam wrote:

Does anyone have suggestions on how to improve this further?

Not functionally (from me, yet). However if you can bear a stylistic
comment, do read on :-)

elif (isinstance(obj ect,str)
or isinstance(obje ct,int)
or isinstance(obje ct,bool)
or isinstance(obje ct,tuple)
or isinstance(obje ct,list)
or isinstance(obje ct,dict)):

Since Python version 2.2, the 2nd arg of isinstance may be a tuple. You
could define this up front, with a meaningful name:

TYPES_WHICH_wha tever = (str, int, bool, etc etc)

Cheers,
John

Actually I'm begging for comments, it's the beginning of a project not
the end. So thanks! ;-)

I changed it to:

if type(object)==s tr:
....
elif type(object) in (str,int,bool,t uple,list,dict) :
....

Thanks, I don't need the isinstance(), type works here just as well.

What would it take to make it useful? I'm thinking of putting it to use
in a database where you can get quickly get info by subject and
keywords, not just by module. I'm also thinking of using it to generate
web pages.

As far as the actual content of doc strings for each item, we can submit
requests for improvements where it's needed.

Cheers,
_Ron

[Scott David Daniels]

Ron Adam wrote:

John Machin wrote:

Ron Adam wrote:

Does anyone have suggestions on how to improve this further?
Not functionally (from me, yet). However if you can bear a stylistic
comment, do read on :-)

elif (isinstance(obj ect,str)
or isinstance(obje ct,int)
or isinstance(obje ct,bool)
or isinstance(obje ct,tuple)
or isinstance(obje ct,list)
or isinstance(obje ct,dict)):

Since Python version 2.2, the 2nd arg of isinstance may be a tuple. You
could define this up front, with a meaningful name:

TYPES_WHICH_wha tever = (str, int, bool, etc etc)

Actually I'm begging for comments, it's the beginning of a project not
the end. So thanks! ;-)

I changed it to:

if type(object)==s tr:
....
elif type(object) in (str,int,bool,t uple,list,dict) :
....

Althought object is a horrible name for your own value (there is a builtin
object which you use for defining new-style classes), you probably want:

if isinstance(obje ct, (str,int,bool,t uple,list,dict) ):
...
or (as John Machin was trying to suggest):

if isinstance(obje ct, TYPES_WHICH_wha tever):
...

This allows you to use instances of those builtin types and any
user-defined subtypes.
Thanks, I don't need the isinstance(), type works here just as well.

But the isinstance version is better than the type(...) in ... version.

--Scott David Daniels
Sc***********@A cm.Org

[Ron Adam]

Scott David Daniels wrote:

Althought object is a horrible name for your own value (there is a builtin
object which you use for defining new-style classes), you probably want:
Good point, I agree. It's a bad habit to start, sooner or later it
would cause a problem. I'll find something else to call it.
if isinstance(obje ct, (str,int,bool,t uple,list,dict) ):
...
or (as John Machin was trying to suggest):

if isinstance(obje ct, TYPES_WHICH_wha tever):
...

This allows you to use instances of those builtin types and any
user-defined subtypes.

Thanks, I don't need the isinstance(), type works here just as well.

But the isinstance version is better than the type(...) in ... version.

Ok, done. I didn't think to look it up in the quick reference this
prints out. LOL, Thanks Scott :-)

I'm not sure if isinstance() would make a difference, it doesn't for
__builtins__, but it might in some other modules.
--Scott David Daniels
Sc***********@A cm.Org

Do you have any feature suggestions, additional information that could
go in, something that would extend the content in some way and make it
more useful?

As it stands now, it could be just a module, so you could...
Regards,
_Ron

The current version is now....
# qref.py
"""
Generate a quick reference for a module by analyzing
a modules contents.

Use example:
import qref
import sys
print qref.quickref(" sys")
"""

def getobjs(obj, dlist=[], lvl=0, maxlevel=1):
""" Retreive a list of sub objects from an object. """
if obj not in dlist:
dlist.append(ob j)
if lvl<maxlevel:
dobj = dir(eval(obj))
for item in dobj:
try:
dlist = getobjs(obj+'.' +item, dlist, lvl+1)
except:
pass
return dlist

def printdoc(object list):
""" Return a sorted printable quick reference
guide from a list of objects. """
outtext = []
objectlist.sort (lambda x, y: cmp(x.lower(), y.lower()))
for obj in objectlist:
objt = eval(obj)
objt_type = type(objt)
outtext.append( '-'*40+'\n')
outtext.append( str(obj)+'\n')
if hasattr(objt, '__module__'):
outtext.append( "Module:"+str(o bjt.__module__) +'\n')
if hasattr( objt,'__class__ '):
outtext.append( "Class:"+str(ob jt.__class__)+' \n\n')
else:
outtext.append( "Type:"+str(obj t_type)+'\n\n')
if isinstance(objt ,str):
if len(objt)>200:
s = objt[0:200]+"......"
else:
s = objt
outtext.append( obj+'=')
if '\n' in s: quotes='"""'
else: quotes ='"'
if len(s)>60: print
outtext.append( quotes+s+quotes +'\n\n')
elif isinstance(objt ,(int,bool,tupl e,list,dict)):
s = str(objt)
if len(s)<200:
outtext.append( obj+'='+s+'\n\n ')
else:
outtext.append( obj+'='+s[0:200]+'......\n\n')
if hasattr(objt,'_ _doc__'):
if objt.__doc__ != type(objt).__do c__:
outtext.append( str(objt.__doc_ _)+'\n\n')
outtext.append( '-'*40+'\n')
return ''.join(outtext )

def quickref(name):
"""
quickref(module _name) -> printable string

Generate a sorted quick reference guide from an objects
doc strings. The module_name is a string with the name of
the module or class to get documents string from.

Example:
import os
print quickref('os')
"""
objlist = getobjs(name)
return printdoc(objlis t)

if __name__ == "__main__":
print quickref('__bui ltins__')

[Scott David Daniels]

Ron Adam wrote:

Do you have any feature suggestions, additional information that could
go in, something that would extend the content in some way and make it
more useful?

As it stands now, it could be just a module, so you could...

The style is still a sticking point for me -- too many evals (a nasty
lure for evil-doers).

Recall that sys.modules is a dictionary from module names to modules.

Any python object (including a module) will return attributes listed
in a dir(obj) with getattr(obj, attributename). So, no evals are
needed in this program at all.

I also wonder if you've ever used maxlevel>1. It seems you'd expand
to way too many names to be useful.

Finally, if you use StringIO (or cStringIO), most of your string
construction can be turned into prints in a way similar to:

def printnames(name list, dest=None):
for name in sorted(namelist , key=str.lower):
print >>dest, name

from cStringIO import StringIO

def textnames(namel ist):
hold = StringIO()
printnames(name list, hold)
return hold.getvalue()

--Scott David Daniels
Sc***********@A cm.Org

[Ron Adam]

Scott David Daniels wrote:

Ron Adam wrote:

Do you have any feature suggestions, additional information that could
go in, something that would extend the content in some way and make it
more useful?

As it stands now, it could be just a module, so you could...

The style is still a sticking point for me -- too many evals (a nasty
lure for evil-doers).

I suppose someone could create an "evil" name in a module that would
either cause and error when evaluated or evaluate to something other
than the actual name.
Recall that sys.modules is a dictionary from module names to modules.

Any python object (including a module) will return attributes listed
in a dir(obj) with getattr(obj, attributename). So, no evals are
needed in this program at all.
Thanks for suggesting the concise way to to this. It was a todo item.

I also wonder if you've ever used maxlevel>1. It seems you'd expand
to way too many names to be useful.
Yes, it does quickly explode in some cases, I left the maxlevel keyword
in there because it might be useful as a general function for other
purposes like building a dependency tree for example. I haven't
actually tried that yet, and there's probably better ways to do it.
Finally, if you use StringIO (or cStringIO), most of your string
construction can be turned into prints in a way similar to:

def printnames(name list, dest=None):
for name in sorted(namelist , key=str.lower):
print >>dest, name

from cStringIO import StringIO

def textnames(namel ist):
hold = StringIO()
printnames(name list, hold)
return hold.getvalue()

--Scott David Daniels
Sc***********@A cm.Org

What would be the advantage of using StringIO over list.append with
''.join()?

I rearranged it somewhat to create a dictionary of object docs. I think
this approach will be better for creating lists in different orders
without having to regenerate the whole thing.

This is where it is now... (No evals, better organized overall I think)

Cheers, _Ron
# qref.py
"""
Generate a quick reference for a module by analyzing
a modules contents.
"""

def getobjs(obj, objlist=[]):
"""Retreive a list of sub-object (name,object) pairs
from an object."""
objlist.append( (obj.__name__,o bj))
for name in dir(obj):
obj2 = getattr(obj,nam e)
name = obj.__name__+'. '+name
if (obj2,name) not in objlist:
objlist.append( (name,obj2))
return objlist

def getdocdict(objl ist):
"""Build a dictionary of docs from an list of
(name,object) tuples."""
doc_dict = {}
for item in objlist:
doc_dict[item[0]] = getobjinfo(*ite m)
return doc_dict

def getobjinfo(name ,obj):
"""Build a formated document string from an objects
__doc__ string, and attribues."""
strout = []
strout.append(n ame+'\n')
if hasattr(obj, '__module__'):
strout.append(" Module:"+str(ob j.__module__)+' \n')
if hasattr(obj, '__class__'):
strout.append(s tr(obj.__class_ _))
else:
strout.append(s tr(type(obj)))
strout.append(' \n\n')
if isinstance(obj, str):
if '\n' in obj:
quotes='\n"""'
else:
quotes ='"'
s = name+' = '+quotes+obj+qu otes
if len(s)>200:
s = s[0:200]+"......"
strout.append( s+'\n\n')
elif isinstance(obj, (int,bool,tuple ,list,dict)):
s = name+' = '+str(obj)
if len(s)>200:
s = s[0:200]+"......"
strout.append( s+'\n\n')
if hasattr(obj,'__ doc__'):
d = ''
if obj.__doc__ == None:
d = 'None'
elif obj.__doc__ != type(obj).__doc __:
d = obj.__doc__
elif obj is type(type):
d = obj.__doc__
if d != '':
strout.append(d +'\n\n')
return ''.join(strout)

def quickref(name):
"""
quickref(module _name) -> printable string

Generate a sorted quick reference guide from an objects
doc strings. The module_name is a string with the name of
the module or class to get documents string from.

Example:
import os
print quickref('os')
"""
objlist = getobjs(name)
docs = getdocdict(objl ist)
dlist = docs.keys()
dlist.sort(lamb da x,y: cmp(x.lower(),y .lower()))
outstr = []
outstr.append('-'*40+'\n')
for d in dlist:
outstr.append(d ocs[d])
outstr.append('-'*40+'\n')
return ''.join(outstr)

if __name__ == "__main__":
print quickref(__buil tins__)

[Michele Simionato]

> Do you have any feature suggestions, additional information that
could

go in, something that would extend the content in some way and make it more useful?

I have written something similar which I use all the time. It generates
ReST
output which I can browse with "less" from the command line, as well as
HTML
output and PDF output that I can print. The hard work is done by
docutils, of course.
I have options to specify if I want to least private names or not, and
to specify
if I want an analytical index to be generated or not. Also, the HTML
output
contains hyperlinks to the original source code, so I can see it with
a click.
I can feed to "minidoc" whole packages (it works recursively on
subpackages, so everything is documented).

It was unvaluable in my struggle with Zope.

Michele Simionato

[Ron Adam]

Michele Simionato wrote:

Do you have any feature suggestions, additional information that

could

go in, something that would extend the content in some way and make

it

more useful?

I have written something similar which I use all the time. It generates
ReST
output which I can browse with "less" from the command line, as well as
HTML
output and PDF output that I can print. The hard work is done by
docutils, of course.
I have options to specify if I want to least private names or not, and
to specify
if I want an analytical index to be generated or not. Also, the HTML
output
contains hyperlinks to the original source code, so I can see it with
a click.
I can feed to "minidoc" whole packages (it works recursively on
subpackages, so everything is documented).

It was unvaluable in my struggle with Zope.

Michele Simionato

Hi Michele,

Sound great! Adding a command line parser, I'm going to add a brief
command line parser to it today, but nothing as elaborate as you have
already. Could you post a part of the output as an example? How is the
index built?

The direction I'm going is to build a database/dictionary with each
individual item as a record. Maybe feed it the whole lib directory, then
to be able to generate cross module/package lists by subject or keyword.
I'm not exactly sure how to connect everything together yet. This is
a figure it out as I go project, but I think it's worth trying.

Cheers,
_Ron

[Michele Simionato]

Ron Adam:

Sound great! Adding a command line parser, I'm going to add a brief
command line parser to it today, but nothing as elaborate as you have
already. Could you post a part of the output as an example? How is the index built?

For the command line parser, see
http://aspn.activestate.com/ASPN/Coo.../Recipe/278844

Here is an example of output:

http://www.phyast.pitt.edu/~micheles/python/ms.html

(it is a package called "ms" (as "My Stuff") where I put my utilities).

The system works for module of the standard library too, but since
most of the time they do not have docstrings in reST format, there
are ugly formatting errors. But this is a bug of the standard library,
not of my tool ;)

For the index: "minidoc" associates a footnote number to every name,
and then
prints the names in alphabetical order. You can reach the documentation
for that name with a click.

Michele Simionato