Skip to content


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


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


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 : 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


Bases: OptionGroup

An OptionGroup with support for configfile section names

add_option(*args, **kwargs)

Extract configfile section info


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)


Checks filehandle for help functions


Extend to allow docstring as description


Allow multiple epilog parts


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


Formatting for help in rst format


Formatting for help in rst format


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


Retrieve options from the environment: prefix_longopt.upper()


Return the prefix to use for options passed through the environment


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 help as a configfile.


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


Print help in MarkDown format


Print help in rst format


Print a shortened help (no longopts)


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


Return usage and set try to set autogenerated description.


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


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.


Set the autocompletion magic via optcomplete


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.


Return default options


Break the options dict by prefix; return nested dict.


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 all options that set with prefix. Return a dict. The keys are stripped of the prefix.


Get all options from section. Return a dict.


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


Parse configfiles


Parse the options


Some additional processing


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.


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


Bases: GeneralOption

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



General Option option dict



short description of main options



longer description of main options



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


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


General Option option dict



short description of main options



longer description of main options



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



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