qiBuild documentation

Parsing command line argumentsΒΆ

Before reading this section, please make sure you have read the Extending qiBuild actions tutorial.

Briefly, you should create a file named spam.py looking like:

"""Add some eggs !"""

import qisys.parsers


def configure_parser(parser):
    """Configure parser for this action """
    qisys.parsers.default_parser(parser)
    parser.add_argument("--num-eggs",
      help="Number of eggs to add",
      type=int)
    parser.set_defaults(
      num_eggs=3)

def do(args):
  """Main entry point"""
  qisys.ui.info("adding %i eggs" % args.num_eggs)

Now lets have a look of what happens when you type:

$ qibuild spam --num-eggs=42

You first go through qibuild script, in bin/qibuild

You will see it uses :

modules = qisys.script.action_modules_from_package("qibuild.actions")
qisys.script.root_command_main("qibuild", parser, modules)

The first line will look for every Python module in the qibuild.actions package that contains a do() and a configure_args methods.

The second line will do the main parsing.

Note that the last argument is simply a list of modules.

So if you ever wanted to add an action outside qibuild.actions package, you could do:

import spam
qisys.script.root_command_main("qibuild", parser, modules + [spam])

So what does the root_command_main do?

You can see it takes a parser object as argument.

You should call this function with an argparse.ArgumentParser object.

The parser will then be updated.

parser = argparse.ArgumentParser()
qisys.script.root_command_main("qibuild", parser)

Basically, we will call:

subparsers = parser.add_subparsers(dest="action", title="actions")
action_parser = subparsers.add_parser("spam")
spam.configure_parser(action_parser)

for each module in the list.

Note how we format the help looking using module.__doc__

This means that spam.py contains everything to handle the parsing:

  • The documentation of the action is simply the docstring of the module
  • Specific arguments are added using the configure_parser function of the module

Thus, everything is put in one place, and the --help output is always correct.