[PEAK] API help (was RE: Package organization)

[Phillip J. Eby]

At 01:50 PM 12/3/03 -0500, Lynn Ranen wrote:
>The thing I don't like about:
>       from peak.api import *
>is that it makes it very difficult for anyone who doesn't know ALL of peak,
>to figure
>out where the code is for anything (it could be anywhere)

Do you have any suggestions for how it could be improved?

For example, suppose there were a quick reference guide that lists each of 
the packages in each category and gave a one line explanation of each API 
call or class exported by that package.  Would that address the issue you 
bring up?

Also, keep in mind that you can do this:

Python 2.2.2 (#37, Oct 14 2002, 17:02:34) [MSC 32 bit (Intel)] on win32
Type "copyright", "credits" or "license" for more information.
IDLE 0.8 -- press F1 for help
 >>> from peak.api import *
 >>> help(naming.lookup)
Help on function lookup in module peak.naming.api:

lookup(parent, name, default=NOT_GIVEN, **options)
     Look up 'name' in the default initial context for 'parent', w/'options'

     This is just a shortcut for calling::

         naming.InitialContext(parent,**options)[name]

 >>> help(binding.Make)
Help on class Make in module peak.binding.once:

class Make(Attribute)
  |  'Make(recipe)' - Construct a value and cache it
  |
  |  Usage examples::
  |
  |      class MyComponent(binding.Component):
  |
  |          # this makes a new dictionary in each MyComponent instance
  |          aDict = binding.Make(dict)
  |
  |          # this makes an instance of 'thing.Thing' in each MyComponent
  |          aThing = binding.Make("things.Thing")
  |
  |          # 1-argument functions are called with the MyComponent instance
  |          someAttr = binding.Make(lamdba self: self.otherAttr * 2)
  |
  |          # Types and no-argument functions are just called
  |          otherAttr = binding.Make(lambda: 42)
  |
  |  'Make' accepts a 'binding.IRecipe' (or object that's adaptable to 
one), and
  |  uses it to compute the attribute's value.  See the docs for 'Descriptor'
  |  and 'Attribute' for the remaining semantics of this attribute type.

[rest of help deleted]

You'll notice that help() identifies the module where the function or 
class' source code is located.

You can also write a shell script to do this from the command line, e.g.:

#!/bin/sh
python -c "from peak.api import *; help($1)"

Should probably do the trick for a quick reference.  Maybe we should add 
this as a 'peak help' command, e.g.:

#---
from peak.api import *
from peak.running.commands import AbstractCommand, InvocationError

class APIHelp(AbstractCommand):

     usage = "Usage: peak help expression [expr2 expr3...]"

     def _run(self):
         if len(self.argv)>1:
             for arg in self.argv[1:]:
                 help(eval(arg))
         else:
             raise InvocationError("No expression specified")
# ---

If you put this code in a file 'helper.py' on your PYTHONPATH, and type, e.g.:

     peak import:helper.APIHelp naming.IBasicContext

Then you'll get nicely paged help on the IBasicContext interface.  And, if 
you add

[peak.running.shortcuts]
help = importString("helper.APIHelp")

to your PEAK_CONFIG file, you'll be able to use, e.g.:

    peak help binding.IRecipe

to get help on that.

Perhaps we should add this to peak.tools?