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.
- add_output - Enable the output option (default:
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.
- Create all the arguments parsers with arguments according with the decorators and classes.
- Parse the arguments passed by the command line.
- 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.