The begins API — begins 0.8 documentation

begins 0.8 documentation
previous | modules | index

# 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.