ArgParseInator object

class argparseinator.ArgParseInator(add_output=None, argpi_name=None, args=None, auth_phrase=None, auto_exit=None, config=None, default_cmd=None, error=None, ff_prefix=None, formatter_class=None, msg_on_error_only=None, never_single=None, setup=None, write_line_name=None, write_name=None, **argparse_args)[source]

Create a new ArgParseInator object. All parameters should be passed as keyword arguments.

  • add_output - Enable the output option (default: False).
  • argpi_name - Name for the global reference of the Argparseinator instance (default: __argpi__).
  • args - List of argument to pass to the parser (default: None).
  • auth_phrase - Global authorization phrase (default: None).
  • auto_exit - if True ArgParseInator uses the functions return values as exit status code. If the return statment is missing or the return value is None then EXIT_OK will be used (default: True).
  • config - Tuple containing config filename, config factory and optionally a config error handler.
  • default_cmd - Name of the default command to set.
  • error - Error handler to pass to parser.
  • ff_prefix - fromfile_prefix_chars to pass to the parser.
  • formatter_class - A class for customizing the help output.
  • msg_on_error_only - if auto_exit is True, it outputs the command message only if there is an exception.
  • never_single - Force to have one command, even it is the only one (default: False).
  • setup - List of functions (having the ArgParseInator class as parameter) that will be executed after the arguments parsing and just before to execute the command.
  • write_name - Name for the global function which calls ArgParseInator.write() (default: write).
  • write_line_name - Name for the global function which calls ArgParseInator.writeln() (default: writeln).
  • write_mode - default write mode when using add_output (default: wb).
  • show_defaults - If True shows default values for parameters in help (default: True).
  • argparse_args - All standard ArgumentParser parameters.

Parameters

add_output

Automatically append to the top level parser the -o --output optional argument. If the argument is passed the ArgParseInator write() and writeln() methods will write the output to the file.

from argparseinator import ArgParseInator, arg

@arg('string', help="String to write")
def write(string):
    """
    Wrtie a string
    """
    ArgParseInator().writeln(string)

ArgParseInator(add_output=True).check_command()

$ python script.py --output=filename.txt "Hello my name is Luca"

Will create a file named filename.txt containing the line Hello my name is Luca

argpi_name

The Argparseinator instance can be accessed globally via the name __argpi__. Anyway you can change the global name using this parameter.

args

Accepts a list of argument to pass to the top level parser. Every element of the list must be a tuple with positional args and keyword args. Something like this (('-o', '--option'), {'help': 'option', 'default': 'no option'}) but for convenience we use the ap_arg() which simplify things.

from argparseinator import ArgParseInator, arg, ap_arg

@arg('string', help="String to write")
def write(string, prefix):
    """
    print a string
    """
    print prefix, string

ArgParseInator(args=[
    ap_arg('-p', '--prefix', help="string prefix", default="Now Writing..")
]).check_command()

$ python script.py -h

will output

usage: script.py [-h] [-p PREFIX] string

    print a string


positional arguments:
  string                String to write

optional arguments:
  -h, --help            show this help message and exit
  -p PREFIX, --prefix PREFIX
                        string prefix

auth_phrase

Set a global authorization phrase to protect special commands. See Authorize commands (@cmd_auth)

auto_exit

If True ArgParseInator exits just executed the command using the returned value(s) as status code.

If the command function return only a numeric value it will be used as status code exiting the script if the command function returns a tuple with numeric and string value the string will be printed as message.

@arg()
def one():
    # will exit from script with status code 1
    return 1

@arg()
def two():
    # will exit from script with status code 2 and print the message
    # "Error"
    return 2, "Error."

config

It could happen that we need a configuration dictionary or something similare, usually loaded from a file. We can specify a dictionary with the configuration or a tuple to handle the configuration file and optionally a configuration error handler. It will be available as self.cfg if you use a subclass of ArgParseInated or globally using __argpi__.**cfg**

def cfg_factory(filename):
    """Configuration factory"""
    import yaml
    return yaml.load(filename)

def cfgname():
    """Prints name"""
    print __argpi__.cfg['name']

Argparseinator(config=('default.cfg', cfg_factory)).check_command()

never_single

When we have only one decorated function ArgParseInator automatically set it as default and adds all its arguments to the top level parser. We can also tell to ArgParseInator to keep it as a command by setting the never_single parameter to True.

from argparseinator import ArgParseInator, arg

@arg('string', help="String to write")
def write(string):
    """
    Write a string
    """
    print string

ArgParseInator().check_command()

$ python script.py "String to print"
String to print

ArgParseInator(never_single=True).check_command()

$ python script.py write "String to print"
String to print

write_name

Sets the name for the global shortcut write() (see __argpi__, write() and writeln())

@arg()
def write_test():
    w("this is a test.")

ArgParseInator(write_name="w").check_command()

write_line_name

As write_name does, it sets the name for the global shortcut writeln() (see __argpi__, write() and writeln())

default_cmd

When we have multiple commands we can set a default one to be used if ArgParseInator can’t find a valid one in sys.argv

error

Usually if we need to handle argparse error we have to subclass the ArgumentParser and override the error method. With the ArgParseInator we can just pass the handler as error parameter.

def error_hander(self, message):
    """Error handler"""
    print "And the error is ...", message

ArgParseInator(error=error_hander).check_command()

ff_prefix

It’s a shortcut for fromfile_prefix_chars. Note that if its value is True then it automatically uses the @ as fromfile_prefix_chars.

msg_on_error_only

if auto_exit is True, it outputs the command message only if there is an exception.

setup

A list or tuple of functions that will be executed just before executing the command, receives as parameter the ArgParseInator instance.

def setup_1(inator):
    """first setup"""
    inator.args.name = 'Luca'

def setup_2(inator):
    """second setup"""
    inator.args.name = inator.args.name.upper()

ArgParseInator(setup=[setup_1, setup_2]).check_command()

argparse_args

**argparse_args are all the parameters to pass to the ArgumentParser.

Note

The part below is copied from the argparse module page.

  • prog - The name of the program (default: sys.argv[0])
  • usage - The string describing the program usage (default: generated from arguments added to parser)
  • description - Text to display before the argument help (default: none)
  • epilog - Text to display after the argument help (default: none)
  • formatter_class - A class for customizing the help output
  • prefix_chars - The set of characters that prefix optional arguments (default: ‘-‘)
  • fromfile_prefix_chars - The set of characters that prefix files from which additional arguments should be read (default: None)
  • argument_default - The global default value for arguments (default: None)
  • add_help - Add a -h/–help option to the parser (default: True)

Methods

ArgParseInator.check_command(**new_attributes)[source]

Essentially executes the command doing these steps.

  1. Create all the arguments parsers with arguments according with the decorators and classes.
  2. Parse the arguments passed by the command line.
  3. Try to execute the command.
ArgParseInator.write(*strings)[source]

Write to the output (stdout or file, see add_output). If more than a string is passed then it will be written space separated.

ArgParseInator.writeln(*strings)[source]

Exactly as ArgParseInator.write() but appends a newline at the end of the string.

__argpi__, write() and writeln()

Just before executing the command ArgParseInator it adds two global shortcuts for its methods ArgParseInator.write() and ArgParseInator.writeln() respectively write() and writeln() and the global reference to the Singleton instance as __argpi__.

So you can use write() or writeln() instead of `ArgParseInator().write()`, `ArgParseInator().writeln()`. And access directly to the Singleton instance using __argpi__ instead of `ArgParseInator()`.

The two methods names can be changed via the write_name and write_line_name arguments and the global instance name via the argpi_name while instantiating the ArgParseInator.