A short tutorial on begins — begins 0.8 documentation

begins 0.8 documentation
previous | next | modules | index

# A short tutorial on begins

The purpose of begins is to help you to easily create command line applications without distracting you from the purpose of you application. Let’s create an application together to demonstrate some of the features of begins. Our application will generate a series of famous Monty Python quotes.

First we will create a minimal structure for our application.:

    import begin
    @begin.start
    def run():
        "Monty Python quotes for all"

This application will run. It doesn’t need any `__name__ == "__main__"` magic. It even has help output when it’s run with the `-h` flag.

Now lets make it do something more interesting.:

    import begin
    @begin.start
    def run(name='Arthur', quest='Holy Grail', colour='blue', *knights):
        "Monty Python quotes for all"

Now our application accepts three command line flags and zero or more positional arguments. The command line flags all have default values that can be over ridden.

Currently all these options relate to different Monty Python quotes. Let us separate these into separate sub-commands.:

    import begin
    @begin.subcommand
    def name(answer):
        "What is your name?"

    @begin.subcommand
    def quest(answer):
        "What is your quest?"

    @begin.subcommand
    def colour(answer):
        "What is your favourite colour?"

    @begin.start
    def run():
        pass

Now our application has three sub-commands that require exactly one positional argument. However, you may have noticed there is currently no output. We will change that now. One way to fix this is to use `print` statements `print()` functions. We are not going to do that. Instead, we are going to configure logging.:

    import begin
    import logging

    @begin.subcommand
    def name(answer):
        "What is your name?"
        logging.info(answer)

    @begin.subcommand
    def quest(answer):
        "What is your quest?"
        logging.info(answer)

    @begin.subcommand
    def colour(answer):
        "What is your favourite colour?"
        logging.info(answer)

    @begin.start
    @begin.logging
    def run():
        pass

Now our application does something useful. But, it can only answer one question at a time. We can ask begins to accept multiple subcommands using a separator. We will ignore the sub-command definitions for brevity.:

    # Sub-commands not shown for brevity.

    @begin.start(cmd_delim='--')
    @begin.logging
    def run():
        pass

Lastly, let us create a new sub-command that takes a number instead of a string.:

    @begin.subcommand
    @begin.convert(speed=int)
    def swallows(speed):
        "What is the wing speed of an unladden swallow?"
        logging.info("%d mph", speed)

You may have noticed the introduction of the `begin.convert` decorator. If the sub-command was not decorated in this way the `speed` argument would be a string. This would cause the sub-command to fail. The `begin.convert` decorator ensures that the `speed` argument will be converted to an integer first.

This is the end for this little tutorial. To learn more about begins you can continue reading with the user Guide to using begins.