SetProgramOptions Class Reference

The SetProgramOptions module is an extension of configparserenhanced.ConfigParserEnhanced which implements handlers for environment variable and environment modules rules in a .ini file.

Supported .ini File Operations

Supported Operations
Operation	Usage	Description
opt-set	`opt-set Param1 [Param2] [ParamN]: VALUE`	Sets a program option.
opt-remove	`opt-remove Param1 [SUBSTR]`	Removes options in the option list that match `Param1`.

API Documentation

SetProgramOptions

SetProgramOptions is a subclass of ConfigParserEnhanced that adds program-option handling capabilities.

Operation: `opt-set`

The opt-set operation can have the following format:

opt-set Param1 [Param2] ... [ParamN] : <value>

Options are processed using gen_option_list() to produce a list or strings representing a command or set of command line options that can be processed by the caller.

These options are added to the options property.

Operation: `opt-remove`

The opt-remove operation can have the following format:

opt-remove Param1 [SUBSTR]

This command is used to remove options that have already been processed and added to the options property.

Option entries are removed according to the rules:

If SUBSTR is not provided, entries are removed if any of its Param options are exactly matched.
If the SUBSTR parameter is included, the matching criteria is relaxed so that an option is removed from the list if any of its parameters contains Param1 (i.e., Param1 is a sub string of any paramter in the option).

Authors:

William C. McLendon III <wcmclen@sandia.gov>

Public API

class setprogramoptions.SetProgramOptions(filename=None)[source]

Bases: ConfigParserEnhanced

__init__(filename=None)[source]

Constructor

Parameters:: filename (str,Path,list) – The .ini file or files to be loaded. If a str or Path is provided then we load only the one file. A list of strings or Path s can also be provided, which will be loaded by ConfigParser’s read() method.

gen_option_list(section, generator='bash') → list[source]

Generate a list of options for a section.

Generates a list of strings that captures the requested operation based on the entries in the .ini file that is stored in options during parsing.

The bash generator will generate a set of ‘bash’ like entries that could be concactenated to generate a bash command.

For example, the .ini section:

[SECTION_A]
opt-set cmake
opt-set -G : Ninja
opt-set /path/to/source/dir

will generate this output:

>>> option_list = parser.gen_option_list("SECTION_A", "bash")
>>> option_list
    [
        'cmake',
        '-G=Ninja',
        '/path/to/source/dir'
    ]

Which can be joined easily to create a bash instruction, such as:

>>> " ".join(option_list)
cmake -G=Ninja

or we could generate a multi-line bash command with continuation lines like this:

>>> " \\\n    ".join(option_list)
cmake \
    -G=Ninja \
    /path/to/source/dir

This can then be executed in a bash shell or saved to a script file that could be executed separately.

Parameters:

section (str) – The section name that contains the options we wish to process.
generator (str) – What kind of generator are we to use to build up our options list? Currently we allow bash but subclasses can define their own functions using the format _gen_option_entry_<generator>(option_entry:dict)

Returns:

A list containing the processed options text.

Return type:

list

property options: dict

The options property contains the set of parsed options that has been processed so far stored as a dictionary. For example, the following .ini snippet:

[SECTION_A]
opt-set cmake
opt-set -G : Ninja

might generate the folllowing result in options:

>>> parser.options
{'SECTION_A':
    [
        {'type': ['opt_set'], 'params': ['cmake'], 'value': None },
        {'type': ['opt_set'], 'params': ['-G'], 'value': 'Ninja' }
    ]
}

would encode the reults of a .ini file section “SECTION_A” which encoded the command: cmake -G Ninja.

This data is used by the gen_option_list method to generate snippets according to the requested generator, such as “bash” or “cmake_fragment”.

Raises:: TypeError – A TypeError can be raised if a non-dictionary is assigned to this property.

property SetProgramOptions.options: dict

The options property contains the set of parsed options that has been processed so far stored as a dictionary. For example, the following .ini snippet:

[SECTION_A]
opt-set cmake
opt-set -G : Ninja

might generate the folllowing result in options:

>>> parser.options
{'SECTION_A':
    [
        {'type': ['opt_set'], 'params': ['cmake'], 'value': None },
        {'type': ['opt_set'], 'params': ['-G'], 'value': 'Ninja' }
    ]
}

would encode the reults of a .ini file section “SECTION_A” which encoded the command: cmake -G Ninja.

This data is used by the gen_option_list method to generate snippets according to the requested generator, such as “bash” or “cmake_fragment”.

Raises:: TypeError – A TypeError can be raised if a non-dictionary is assigned to this property.

Private API

Properties

property SetProgramOptions._data_shared_key: str

Key used by handler_parameters for shared_data

This key is used inside the handler_parameters.shared_data[_data_shared_key] as the place we’re storing the action list and other data associated with the ConfigParserEnhanced parsing of a given root section.

This information is generally copied out during the handler_finalize() into some class property for accessing beyond the search itself.

Currently this just uses the current class name.

Returns:

Default dictionary key internal parser use.

This property returns a string that is used as the default key in handler_parameters.data_shared to bin the data being generated during a search.

This can be used in the handler_finalize() method to extract the shared data captured by the parser before it is discarded at the end of a search.

Return type:

str

Handlers

SetProgramOptions._handler_opt_set(section_name, handler_parameters)

SetProgramOptions._handler_opt_remove(section_name, handler_parameters)

SetProgramOptions.handler_initialize(section_name, handler_parameters)

SetProgramOptions.handler_finalize(section_name, handler_parameters)

SetProgramOptions._initialize_handler_parameters(section_name, handler_parameters) → int[source]

Initialize handler_parameters

Initializes any default settings needed for handler_parameters. Takes the same parameters as handlers.

Parameters:

section_name (str) – The section name string.
handler_parameters (HandlerParameters) – A HandlerParameters object containing the state data we need for this handler.

Called By:

handler_initialize()

Handler Helpers

SetProgramOptions._option_handler_helper_add(section_name: str, handler_parameters) → int[source]

Add an option to the shared data options list

Inserts an option into the handler_parameters.data_shared["{_data_shared_key}"] list, where {_data_shared_key} is generated from the property _data_shared_key. Currently, _data_shared_key returns the class name of the class object.

Operations with the format such as this:

[SECTION NAME]
operation Param1 Param2 ... ParamN : Value

which result in a dict entry:

{
    'type'  : [ operation ],
    'params': [ param1, param2, ... , paramN ],
    'value' : Value
}

this entry is then appended to the handler_parameters.data_shared[{_data_shared_key}] list, where _data_shared_key is generated from the property _data_shared_key.

Currently _data_shared_key returns the current class name, but this can be changed if needed.

Parameters:

section_name (str) – The name of the section being processed.
handler_parameters (HandlerParameters) – The parameters passed to the handler.

Returns:

0 : SUCCESS
[1-10]: Reserved for future use (WARNING)
> 10 : An unknown failure occurred (CRITICAL)

Return type:

int

SetProgramOptions._option_handler_helper_remove(section_name: str, handler_parameters) → int[source]

Removes option(s) from the shared data options list.

Removes an option or options from the handler_parameters.data_shared["{_data_shared_key}"] list, where {_data_shared_key} is generated from the property _data_shared_key. Currently, _data_shared_key returns the class name of the class object.

In this case the format is based on the following .ini snippet:

[SECTION NAME]
<operation> KEYWORD [SUBSTR]

where we remove entries from the shared data options list according to one of the following methods:

Removes entries if one of the parameters matches the provided KEYWORD.
If the optional SUBSTR parameter is provided, then we remove entries if any paramter contains the KEYWORD as either an exact match or a substring.

Parameters:

section_name (str) – The name of the section being processed.
handler_parameters (HandlerParameters) – The parameters passed to the handler.

Returns:

0 : SUCCESS
[1-10]: Reserved for future use (WARNING)
> 10 : An unknown failure occurred (CRITICAL)

Return type:

int

Program Option Handlers

SetProgramOptions._program_option_handler_opt_set_bash(params: list, value: str) → str[source]

Bash generator for opt-set operations.

This method handles the generation of an entry for an opt-set operation when the generator is set to be bash.

Called by: _gen_option_entry().

Returns:: A string containing a generated program option with the parameters concactenated together using the format <param1><param2>...<paramN>=<value> will be returned.
Return type:: str

SetProgramOptions._generic_program_option_handler_bash(params: list, value: str) → str[source]

Generic processer for generic bash options.

This is the simplest kind of option handler for bash-like commands where we just concatenate all the params together and set them equal to the value.

For example:

>>> params = ['-D','SOMEFLAG',':BOOL']
>>> value  = "ON"
>>> _generic_program_option_handler_bash(params,value)
"-DSOMEFLAG:BOOL=ON"

Called by: _program_option_handler_opt_set_bash()

Parameters:

params (list) – A list of strings containing the parameters that would be to the LHS or the = when constructing an option entry.
value (str) – A str that is placed to the RHS of the option assignment expression.

Returns:

A str object representing an option.

Return type:

str

SetProgramOptions._gen_option_entry(option_entry: dict, generator='bash') → str | None[source]

Takes an option_entry and looks for a specialized handler for that option type.

This looks for a method named _program_option_handler_<typename>_<generator> where typename comes from the option_entry['type'] field. For example, if option_entry['type'] is opt_set and generator is bash then we look for a method called _program_option_handler_opt_set_bash(), which is executed and returns the line-item entry for the given option_entry.

Parameters:

option_entry (dict) – A dictionary storing a single option entry.

Returns:

A string containing the single entry for this option or None

None is returned IF the type field in option_entry does not resolve to a proper method and the exception control level is not set sufficiently high to trigger an exception.

Return type:

Union[str,None]

Raises:

ValueError – If we aren’t able to locate the options formatter.

SetProgramOptions Class Reference

Supported .ini File Operations

API Documentation

SetProgramOptions

Operation: opt-set

Operation: opt-remove

Public API

Private API

Properties

Handlers

Handler Helpers

Program Option Handlers

Operation: `opt-set`

Operation: `opt-remove`