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__')

[Ron Adam]

Michele Simionato wrote:

Ron Adam:

Sound great! Adding a command line parser, I'm going to add a brief ^---------------------------^

That part should have been deleted, I meant your whole program sounded
good, not just that part. :-)
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

I got this one covered, just haven't done it yet. ;-)

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).
Good idea, I think I'll follow your lead. Currently my file are not too
organized.
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 ;)
Thats part of what I'm trying to resolve, the doc strings a lot of time
isn't enough by itself or is missing. So I'm trying to build up a
complete enough record so if there is no doc string, at least some sense
of what it is can be figured out without a lot browsing or looking at
the source code.

Then to enable different searches by subject and keywords on these
instead of by package or module.
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

That's a nice format. It took me a while before I realized the whole
page *is* the output and not a part of it as I expected.

Did you use the inspect module to get the class/function name and args?

BTW, I presume you're aware that the "source links" on the web page link
to your computer and not to a file on the web site. Just letting know
in case it was an over site.

Cheers,
_Ron

Ps... I like your physics link page. :)

[Scott David Daniels]

Ron Adam wrote:

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

The advantage is more in using a function that prints as it goes
rather than building up a large string to print. I would call the
print function at the bottom (with None as the print destination),
rather than printing the result of calling the string function.

I just did the StringIO thing to show you that printing as you go
needn't mean you cannot get the string value without duplicating code.

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

[Ron Adam]

Scott David Daniels wrote:

Ron Adam wrote:

...What would be the advantage of using StringIO over list.append with
''.join()?
The advantage is more in using a function that prints as it goes
rather than building up a large string to print. I would call the
print function at the bottom (with None as the print destination),
rather than printing the result of calling the string function.

The reason I return the string to the calling function instead of
printing it, is the person using it may not want to print it. They may
want to send it to a file, or process it further before printing it.
Same with the individual records.
I just did the StringIO thing to show you that printing as you go
needn't mean you cannot get the string value without duplicating code.

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

I've used IO Streams,(">>" and "<<"), before in C, where I was
continually reading to and writing from a buffer as I went. (Back when
memory was often smaller than most files.)

I haven't played around with the StringIO module yet, and this will
probably be more of a database application rather than just formatting
input for output. So for now the strings operations are fine until I
better decide how they will get used.

Maybe further down the road I'll convert them to, or have a need for
serialized objects, so I'll keep the STringIO module in mind. :-)

Cheers,
_Ron

[Michele Simionato]

Ron Adam:

Thats part of what I'm trying to resolve, the doc strings a lot of time isn't enough by itself or is missing. So I'm trying to build up a
complete enough record so if there is no doc string, at least some sense of what it is can be figured out without a lot browsing or looking at
the source code.
I have a command line option so I can decide if I want to display only
the
documented objects or every object, including the ones without
docstring.
I could add an option to tell "minidoc" to interpret docstrings are
plain
text, not restructured text; however I don't want to do that (part of
the reason for "minidoc" is to force me to write good reST docstrings
in my own modules).
Then to enable different searches by subject and keywords on these
instead of by package or module.
Well, my browser has a CTRL-F functionality ;)
That's a nice format. It took me a while before I realized the whole
page *is* the output and not a part of it as I expected.
You should see how nice is the PDF when printed ;)
Did you use the inspect module to get the class/function name and args?

Yes, the inspect module is amazing.
BTW, I presume you're aware that the "source links" on the web page link to your computer and not to a file on the web site. Just letting know in case it was an over site.
Yes, I am aware of it, it was on purpose ;)
Cheers,
_Ron Ps... I like your physics link page. :)

That page is old, I am no more in physics, but I still have that
account for free
and I am lazy, so I am keeping it ;)

Michele Simionato

[Michele Simionato]

These days I use generators instead of StringIO, i.e.
instead of

print >> out, mystring

I just write

yield mystring

and then I "".join the generator.

Michele Simionato

[Ron Adam]

Michele Simionato wrote:

Ron Adam:

Thats part of what I'm trying to resolve, the doc strings a lot of

time

isn't enough by itself or is missing. So I'm trying to build up a
complete enough record so if there is no doc string, at least some

sense

of what it is can be figured out without a lot browsing or looking at
the source code.

I have a command line option so I can decide if I want to display only
the
documented objects or every object, including the ones without
docstring.
I could add an option to tell "minidoc" to interpret docstrings are
plain
text, not restructured text; however I don't want to do that (part of
the reason for "minidoc" is to force me to write good reST docstrings
in my own modules).

If it works, don't fix it. ;-)

Then to enable different searches by subject and keywords on these
instead of by package or module.

Well, my browser has a CTRL-F functionality ;)

I recently switched over to using the GVIMs Cream version as an editor,
So it should be possible to map a function key to grab the import
statements from the currently edited document, feed the imported module
names to quickref and capture the output in a window for searching in
the same way.

It will be fun to play around with once I get back from a week long trip
starting Thursday.

in case it was an over site.

Yes, I am aware of it, it was on purpose ;)

I was pretty sure it was.

Ps... I like your physics link page. :)

That page is old, I am no more in physics, but I still have that
account for free
and I am lazy, so I am keeping it ;)

Michele Simionato

I'm not in physics in *any* way, but I have a few pet theories (more
like opinions really). So I like to check what's going on and see if
anyone or anything proves or disproves them. ;-)