Hacking BE

Adding commands

To write a plugin, you simply create a new file in the libbe/command/ directory. Take a look at one of the simpler plugins (e.g. libbe.command.remove) for an example of how that looks, and to start getting a feel for the libbe interface.

See libbe.command.base for the definition of the important classes Option, Argument, Command, InputOutput, StorageCallbacks, and UserInterface. You’ll be subclassing Command for your command, but all those classes will be important.

Command completion

BE implements a general framework to make it easy to support command completion for arbitrary plugins. In order to support this system, any of your completable Argument instances (in your command’s .options or .args) should be initialized with some valid completion_callback function. Some common cases are defined in libbe.command.util. If you need more flexibility, see libbe.command.list‘s --sort option for an example of extensions via libbe.command.util.Completer, or write a custom completion function from scratch.

Adding user interfaces

Take a look at libbe.ui.command_line for an example. Basically you’ll need to setup a UserInterface instance for running commands. More details to come after I write an HTML UI...

Testing

Run any tests in your module with:

be$ python test.py <python.module.name>

for example:

be$ python test.py libbe.command.merge

For a definition of “any tests”, see test.py‘s add_module_tests() function.

Note that you will need to run make before testing a clean BE branch to auto-generate required files like libbe/_version.py.

Profiling

Find out which 20 calls take the most cumulative time (time of execution + childrens’ times):

$ python -m cProfile -o profile be [command] [args]
$ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats(20)"

If you want to find out who’s calling your expensive function (e.g. libbe.util.subproc.invoke()), try:

$ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_callers(20)"

You can also toss:

import sys, traceback
print >> sys.stderr, '-'*60, '\n', '\n'.join(traceback.format_stack()[-10:])

into the function itself for a depth-first caller list.

For a more top-down approach, try:

$ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_callees(20)"