The begins API

Convenience function for starting Python programs

begin.start(func=None, **kwargs)

Return True if called in a module that is executed.

Inspects the ‘__name__’ in the stack frame of the caller, comparing it to ‘__main__’. Thus allowing the Python idiom:

>>> if __name__ == '__main__':
...     pass

To be replace with:

>>> import begin
>>> if begin.start():
...    pass

Can also be used as a decorator to register a function to run after the module has been loaded.

>>> @begin.start
... def main():
...     pass

This also inspects the stack frame of the caller, choosing whether to call function immediately. Any definitions following the function wont be called until after the main function is complete.

If used as a decorator, and the decorated function accepts either positional or keyword arguments, a command line parser will be generated and used to parse command line options.

>>> @begin.start
... def main(first, second=''):
...     pass

This will cause the command line parser to accept two options, the second of which defaults to ‘’.

Default values for command line options can also be set from the current environment, using the uppercased version of an options name. In the example above, the environment variable ‘FIRST’ will set a default value for the first argument.

To use a prefix with expected environment variables (for example, to prevent collisions) give an ‘env_prefix’ argument to the decorator.

>>> @begin.start(env_prefix='PY_')
... def main(first, second=''):
...     pass

The environment variable ‘PY_FIRST’ will be used instead of ‘FIRST’.

Utilities

Utility functions for begins

begin.utils.tobool(value)

Convert a string representation of truth to True or False.

True values are ‘y’, ‘yes’, ‘t’, ‘true’, ‘on’, and ‘1’; false values are ‘n’, ‘no’, ‘f’, ‘false’, ‘off’, and ‘0’. Raises ValueError if ‘value’ is anything else.

begin.utils.tolist(value=None, sep=', ', empty_strings=False)

Convert a string to a list.

The input string is split on the separator character. The default separator is ‘,’. An alternative separator may be passed as the ‘sep’ keyword. If no string value is provided a function is returned that splits a string on the provided separator, or default if none was provided. Any empty strings are removed from the resulting list. This behaviour can be changed by passing True as the ‘empty_strings’ keyword argument.

Help Formatters

Help formatters for use with argparse

class begin.formatters.ArgumentDefaults

Help message formatter which adds default values to argument help.

Based on argparse.ArgumentDefaultsHelpFormatter from Python standard library Copyright 2001-2014 Python Software Foundation; All Rights Reserved

class begin.formatters.RawArguments

Help message formatter which retains formatting of all argument text.

Based on argparse.RawTextHelpFormatter from Python standard library Copyright 2001-2014 Python Software Foundation; All Rights Reserved

class begin.formatters.RawDescription

Help message formatter which retains any formatting in descriptions.

Based on argparse.RawDescriptionHelpFormatter from Python standard library Copyright 2001-2014 Python Software Foundation; All Rights Reserved

class begin.formatters.RemoveSubcommandsLine

Removes line of subcommand names from help output.

Based on Jeppe Ledet-Pederson’s solution for hiding metavar in command listing. http://stackoverflow.com/a/13429281

begin.formatters.compose(*mixins, **kwargs)

Compose a new help formatter class for argparse.

Accepts a variable number of mixin class and uses these as base classes with multiple inheritance against argparse.HelpFormatter to create a new help formatter class.