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.