Tutorial

In this tutorial, we’ll write a command that greets people in different ways.

We start with the scaffolding (shebang, imports, …) and with a class that subclasses MainCommand, is instantiated and its method run is called:

#!/usr/bin/env python3
import hazwaz


class Greet(hazwaz.MainCommand):
    """
    Greet people in different ways.
    """


if __name__ == "__main__":
    Greet().run()

Save this in a file called greeter.py and run it, and it will print an help message where you can already see a couple of options, --verbose and debug, as well as the first line of the docstring used as the usage.

Now we add our first subcommand: we write a new class, subclassing Command and writing some code in its main method:

class World(hazwaz.Command):
    """
    Greet the whole world.
    """

    def main(self):
        print("Hello world!")

And we add an instance to the tuple of subcommands in our MainCommand:

class Greet(hazwaz.MainCommand):
    """
    Greet people in different ways.
    """
    commands = (
        World(),
    )

now if we run the program as ./greeter.py we see that there is a possible choice for a positional argument, world, and if we run ./greeter.py world we get, as expected, a greeting Hello world!.

With ./greeter.py world --help we can see the help message for this subcommand, and notice that the first line in the docstring has again been used as the usage notes.

Of course, a subcommand can also have options: we write a second subclass of Command and this time we add some argparser option in the add_arguments method:

class Individual(hazwaz.Command):
    """
    Greet an individual.
    """

    def add_arguments(self, parser):
        parser.add_argument(
            "gretee",
            help="The person to be greeted",
        )

    def main(self):
        print("Hello {}".format(self.args.gretee))

And again we add it to the tuple of subcommands:

class Greet(hazwaz.MainCommand):
    """
    Greet people in different ways.
    """
    commands = (
        World(),
        Individual(),
    )

You can then run the program as ./greeter.py individual Bob to see the new greeting.

add_arguments requires an argparse.ArgumentParser as its second parameter, and uses it to add arbitrary arguments, giving access to all argparse features.