Fork me on GitHub

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.