generaloption

A class that can be used to generated options to python scripts in a general way.

Authors:

Stijn De Weirdt (Ghent University)
Jens Timmerman (Ghent University)

`ExtOption` ¶

Bases: CompleterOption

Extended options class - enable/disable support

Actions: - shorthelp : hook for shortend help messages - confighelp : hook for configfile-style help messages - store_debuglog : turns on fancylogger debugloglevel - also: 'store_infolog', 'store_warninglog' - add : add value to default (result is default + value) - add_first : add default to value (result is value + default) - extend : alias for add with strlist type - type must support + (add) and one of negate (neg) or slicing (getslice) - add_flex : similar to add / add_first, but replaces the first "empty" element with the default - the empty element is dependent of the type - for {str,path}{list,tuple} this is the empty string - types must support the index method to determine the location of the "empty" element - the replacement uses + - e.g. a strlist type with value "0,,1"` and default [3,4] and action add_flex will use the empty string '' as "empty" element, and will result in [0,3,4,1] (not [0,[3,4],1]) (but also a strlist with value "" and default [3,4] will result in [3,4]; so you can't set an empty list with add_flex) - date : convert into datetime.date - datetime : convert into datetime.datetime - regex: compile str in regexp - store_or_None - set default to None if no option passed, - set to default if option without value passed, - set to value if option with value passed

Types: - strlist, strtuple : convert comma-separated string in a list resp. tuple of strings - pathlist, pathtuple : using os.pathsep, convert pathsep-separated string in a list resp. tuple of strings - the path separator is OS-dependent

`init(*args, **kwargs)` ¶

Add logger to init

`process(opt, value, values, parser)` ¶

Handle option-as-value issues before actually processing option.

`take_action(action, dest, opt, value, values, parser)` ¶

Extended take_action

`ExtOptionGroup` ¶

Bases: OptionGroup

An OptionGroup with support for configfile section names

`add_option(*args, **kwargs)` ¶

Extract configfile section info

`ExtOptionParser` ¶

Bases: OptionParser

Make an option parser that limits the C{-h} / C{--shorthelp} to short opts only, C{-H} / C{--help} for all options.

Pass options through environment. Like:

C{export PROGNAME_SOMEOPTION = value} will generate {--someoption=value}
C{export PROGNAME_OTHEROPTION = 1} will generate {--otheroption}
C{export PROGNAME_OTHEROPTION = 0} (or no or false) won't do anything

distinction is made based on option.action in TYPED_ACTIONS allow C{--enable-} / C{--disable-} (using eg ExtOption option_class)

`init(*args, **kwargs)` ¶

Following named arguments are specific to ExtOptionParser (the remaining ones are passed to the parent OptionParser class)

:param help_to_string: boolean, if True, the help is written
                       to a newly created StingIO instance
:param help_to_file: filehandle, help is written to this filehandle
:param envvar_prefix: string, specify the environment variable prefix
                      to use (if you don't want the default one)
:param process_env_options: boolean, if False, don't check the
                            environment for options (default: True)
:param error_env_options: boolean, if True, use error_env_options_method
                          if an environment variable with correct envvar_prefix
                          exists but does not correspond to an existing option
                          (default: False)
:param error_env_options_method: callable; method to use to report error
                                 in used environment variables (see error_env_options);
                                 accepts string value + additional
                                 string arguments for formatting the message
                                 (default: own log.error method)

`check_help(fh)` ¶

Checks filehandle for help functions

`format_description(formatter)` ¶

Extend to allow docstring as description

`format_epilog(formatter)` ¶

Allow multiple epilog parts

`format_help(formatter=None)` ¶

For py2.4 compatibility reasons (missing epilog). This is the py2.7 / optparse 1.5.3 code

`format_option_mdhelp(formatter=None)` ¶

Formatting for help in rst format

`format_option_rsthelp(formatter=None)` ¶

Formatting for help in rst format

`get_default_values()` ¶

Introduce the ExtValues class with class constant - make it dynamic, otherwise the class constant is shared between multiple instances - class constant is used to avoid _action_taken as option in the dict - only works by using reference to object - same for _logaction_taken

`get_env_options()` ¶

Retrieve options from the environment: prefix_longopt.upper()

`get_env_options_prefix()` ¶

Return the prefix to use for options passed through the environment

`get_option_by_long_name(name)` ¶

Return the option matching the long option name

`is_value_a_commandline_option(opt, value, index=None)` ¶

Determine if value is/could be an option passed via the commandline. If it is, return the reason why (can be used as message); or return None if it isn't.

opt is the option flag to which the value is passed; index is the index of the value on the commandline (if None, it is determined from orig_rargs and rargs)

The method tests for possible ambiguity on the commandline when the parser interprets the argument following an option as a value, whereas it is far more likely that it is (intended as) an option; --longopt=value is never considered ambiguous, regardless of the value.

`print_confighelp(fh=None)` ¶

Print help as a configfile.

`print_help(fh=None)` ¶

Intercept print to file to print to string and remove the ENABLE/DISABLE options from help

`print_mdhelp(fh=None)` ¶

Print help in MarkDown format

`print_rsthelp(fh=None)` ¶

Print help in rst format

`print_shorthelp(fh=None)` ¶

Print a shortened help (no longopts)

`set_description_docstring()` ¶

Try to find the main docstring and add it if description is not None

`set_usage(usage)` ¶

Return usage and set try to set autogenerated description.

`GeneralOption` ¶

Bases: object

'Used-to-be simple' wrapper class for option parsing

Options with go_ prefix are for this class, the remainder is passed to the parser - go_args : use these instead of of sys.argv[1:] - go_columns : specify column width (in columns) - go_useconfigfiles : use configfiles or not (default set by CONFIGFILES_USE) if True, an option --configfiles will be added - go_configfiles : list of configfiles to parse. Uses ConfigParser.read; last file wins - go_configfiles_initenv : section dict of key/value dict; inserted before configfileparsing As a special case, using all uppercase key in DEFAULT section with a case-sensitive configparser can be used to set "constants" for easy interpolation in all sections. - go_loggername : name of logger, default classname - go_mainbeforedefault : set the main options before the default ones - go_autocompleter : dict with named options to pass to the autocomplete call (eg arg_completer) if is None: disable autocompletion; default is {} (ie no extra args passed)

Sections starting with the string 'raw_' in the sectionname will be parsed as raw sections, meaning there will be no interpolation of the strings. This comes in handy if you want to configure strings with templates in them.

Options process order (last one wins) 0. default defined with option 1. value in (last) configfile (last configfile wins) 2. options parsed by option parser In case the ExtOptionParser is used 0. value set through environment variable 1. value set through commandline option

`add_group_parser(opt_dict, description, prefix=None, otherdefaults=None, section_name=None)` ¶

Make a group parser from a dict

@type opt_dict: dict @type description: a 2 element list (short and long description) @section_name: str, the name of the section group in the config file.

PARAMETER	DESCRIPTION
`opt_dict`	options, with the form C{"long_opt" : value}. Value is a C{tuple} containing C{(help,type,action,default(,optional string=short option; list/tuple=choices; dict=add_option kwargs))} help message passed through opt_dict will be extended with type and default If section_name is None, prefix will be used. If prefix is None or '', 'DEFAULT' is used.

`autocomplete()` ¶

Set the autocompletion magic via optcomplete

`configfile_parser_init(initenv=None)` ¶

Initialise the configparser to use.

:param initenv: insert initial environment into the configparser.
    It is a dict of dicts; the first level key is the section name;
    the 2nd level key,value is the key=value.
    All section names, keys and values are converted to strings.

`default_parseoptions()` ¶

Return default options

`dict_by_prefix(merge_empty_prefix=False)` ¶

Break the options dict by prefix; return nested dict.

PARAMETER	DESCRIPTION
	boolean (default False) also (try to) merge the empty prefix in the root of the dict. If there is a non-prefixed optionname that matches a prefix, it will be rejected and error will be logged. TYPE: `merge_empty_prefix`

`generate_cmd_line(ignore=None, add_default=None)` ¶

Create the commandline options that would create the current self.options. The result is sorted on the destination names.

:param ignore : regex on destination :param add_default : print value that are equal to default

`get_options_by_prefix(prefix)` ¶

Get all options that set with prefix. Return a dict. The keys are stripped of the prefix.

`get_options_by_section(section)` ¶

Get all options from section. Return a dict.

`main_options()` ¶

Create the main options automatically

`make_option_metavar(longopt, details)` ¶

Generate the metavar for option longopt @type longopt: str @type details: tuple

`make_options_option_name_and_destination(prefix, key)` ¶

Make the options option name

`parseconfigfiles()` ¶

Parse configfiles

`parseoptions(options_list=None)` ¶

Parse the options

`postprocess()` ¶

Some additional processing

`set_go_debug()` ¶

Check if debug options are on and then set fancylogger to debug. This is not the default way to set debug, it enables debug logging in an earlier stage to debug generaloption itself.

`validate()` ¶

Final step, allows for validating the options and/or args

`SimpleOption` ¶

Bases: GeneralOption

`init(go_dict=None, descr=None, short_groupdescr=None, long_groupdescr=None, config_files=None)` ¶

Initialisation

PARAMETER	DESCRIPTION
`go_dict`	General Option option dict DEFAULT: `None`
`short_groupdescr`	short description of main options DEFAULT: `None`
`long_groupdescr`	longer description of main options DEFAULT: `None`
`config_files`	list of configfiles to read options from a general options dict has as key the long option name, and is followed by a list/tuple mandatory are 4 elements : option help, type, action, default a 5th element is optional and is the short help name (if any) the generated help will include the docstring DEFAULT: `None`

`check_str_list_tuple(option, opt, value)` ¶

check function for strlist and strtuple type assumes value is comma-separated list returns list or tuple of strings

`get_empty_add_flex(allvalues, self=None)` ¶

Return the empty element for add_flex action for allvalues

`set_columns(cols=None)` ¶

Set os.environ COLUMNS variable - only if it is not set already

`simple_option(go_dict=None, descr=None, short_groupdescr=None, long_groupdescr=None, config_files=None)` ¶

A function that returns a single level GeneralOption option parser

PARAMETER	DESCRIPTION
`go_dict`	General Option option dict DEFAULT: `None`
`short_groupdescr`	short description of main options DEFAULT: `None`
`long_groupdescr`	longer description of main options DEFAULT: `None`
`config_files`	list of configfiles to read options from a general options dict has as key the long option name, and is followed by a list/tuple mandatory are 4 elements : option help, type, action, default a 5th element is optional and is the short help name (if any) the generated help will include the docstring DEFAULT: `None`

`what_str_list_tuple(name)` ¶

Given name, return separator, class and helptext wrt separator. (Currently supports strlist, strtuple, pathlist, pathtuple)

generaloption

ExtOption ¶

__init__(*args, **kwargs) ¶

process(opt, value, values, parser) ¶

take_action(action, dest, opt, value, values, parser) ¶

ExtOptionGroup ¶

add_option(*args, **kwargs) ¶

ExtOptionParser ¶

__init__(*args, **kwargs) ¶

check_help(fh) ¶

format_description(formatter) ¶

format_epilog(formatter) ¶

format_help(formatter=None) ¶

format_option_mdhelp(formatter=None) ¶

format_option_rsthelp(formatter=None) ¶

get_default_values() ¶

get_env_options() ¶

get_env_options_prefix() ¶

get_option_by_long_name(name) ¶

is_value_a_commandline_option(opt, value, index=None) ¶

print_confighelp(fh=None) ¶

print_help(fh=None) ¶

print_mdhelp(fh=None) ¶

print_rsthelp(fh=None) ¶

print_shorthelp(fh=None) ¶

set_description_docstring() ¶

set_usage(usage) ¶

GeneralOption ¶

add_group_parser(opt_dict, description, prefix=None, otherdefaults=None, section_name=None) ¶

autocomplete() ¶

configfile_parser_init(initenv=None) ¶

default_parseoptions() ¶

dict_by_prefix(merge_empty_prefix=False) ¶

generate_cmd_line(ignore=None, add_default=None) ¶

get_options_by_prefix(prefix) ¶

get_options_by_section(section) ¶

main_options() ¶

make_option_metavar(longopt, details) ¶

make_options_option_name_and_destination(prefix, key) ¶

parseconfigfiles() ¶

parseoptions(options_list=None) ¶

postprocess() ¶

set_go_debug() ¶

validate() ¶

SimpleOption ¶

__init__(go_dict=None, descr=None, short_groupdescr=None, long_groupdescr=None, config_files=None) ¶

check_str_list_tuple(option, opt, value) ¶

get_empty_add_flex(allvalues, self=None) ¶

set_columns(cols=None) ¶

simple_option(go_dict=None, descr=None, short_groupdescr=None, long_groupdescr=None, config_files=None) ¶

what_str_list_tuple(name) ¶

`ExtOption` ¶

`init(*args, **kwargs)` ¶

`process(opt, value, values, parser)` ¶

`take_action(action, dest, opt, value, values, parser)` ¶

`ExtOptionGroup` ¶

`add_option(*args, **kwargs)` ¶

`ExtOptionParser` ¶

`init(*args, **kwargs)` ¶

`check_help(fh)` ¶

`format_description(formatter)` ¶

`format_epilog(formatter)` ¶

`format_help(formatter=None)` ¶

`format_option_mdhelp(formatter=None)` ¶

`format_option_rsthelp(formatter=None)` ¶

`get_default_values()` ¶

`get_env_options()` ¶

`get_env_options_prefix()` ¶

`get_option_by_long_name(name)` ¶

`is_value_a_commandline_option(opt, value, index=None)` ¶

`print_confighelp(fh=None)` ¶

`print_help(fh=None)` ¶

`print_mdhelp(fh=None)` ¶

`print_rsthelp(fh=None)` ¶

`print_shorthelp(fh=None)` ¶

`set_description_docstring()` ¶

`set_usage(usage)` ¶

`GeneralOption` ¶

`add_group_parser(opt_dict, description, prefix=None, otherdefaults=None, section_name=None)` ¶

`autocomplete()` ¶

`configfile_parser_init(initenv=None)` ¶

`default_parseoptions()` ¶

`dict_by_prefix(merge_empty_prefix=False)` ¶

`generate_cmd_line(ignore=None, add_default=None)` ¶

`get_options_by_prefix(prefix)` ¶

`get_options_by_section(section)` ¶

`main_options()` ¶

`make_option_metavar(longopt, details)` ¶

`make_options_option_name_and_destination(prefix, key)` ¶

`parseconfigfiles()` ¶

`parseoptions(options_list=None)` ¶

`postprocess()` ¶

`set_go_debug()` ¶

`validate()` ¶

`SimpleOption` ¶

`init(go_dict=None, descr=None, short_groupdescr=None, long_groupdescr=None, config_files=None)` ¶

`check_str_list_tuple(option, opt, value)` ¶

`get_empty_add_flex(allvalues, self=None)` ¶

`set_columns(cols=None)` ¶

`simple_option(go_dict=None, descr=None, short_groupdescr=None, long_groupdescr=None, config_files=None)` ¶

`what_str_list_tuple(name)` ¶