Options

class sofia_redux.scan.configuration.options.Options(allow_error=False, verbose=True)

Bases: ABC

Initialize an Options object.

The Options contain a ConfigObj as the container for any given configuration. There is also handling provided for cases when a configuration functionality results in an error. These may be emitted as log messages if verbose is True, or raised as errors if allow_error is False.

Since all configuration values are stored as strings, there are special handling methods to retrieve the desired value type such as integers, strings, angles, or time.

Parameters:

allow_errorbool, optional

If True, allow poorly formatted options to be skipped rather than raising an error.

verbosebool, optional

If True, issues a warning when a poorly option is encountered.

Attributes Summary

append_keys
is_empty	Return True if the options contain any key-values.
size	Return the number of available options.

Methods Summary

clear()	Clear all options.
copy()	Return a copy of the options.
get(key[, default, unalias])	Retrieve the given key value from the options.
get_bool(key[, default, unalias])	Return a boolean value from the options for the given key.
get_dms_angle(key[, default, unalias])	Return a degree:minutes:seconds angle for the given options key.
get_float(key[, default, unalias])	Return a float value from the options for the given key.
get_float_list(key[, delimiter, default, ...])	Return a list of floats from the options for the given key.
get_hms_time(key[, angle, default, unalias])	Return a hour:minutes:seconds angle for the given options key.
get_int(key[, default, unalias])	Return an integer value from the options for the given key.
get_int_list(key[, delimiter, default, ...])	Return a list of integers from the options for the given key.
get_list(key[, default, unalias])	Return a list value from the options for the given key.
get_range(key[, default, is_positive, unalias])	Return a Range value from the options for the given key.
get_sign(key[, default, unalias])	Return an integer representation of a sign value in the options.
get_string(key[, default, unalias])	Return a string value from the options for the given key.
get_string_list(key[, delimiter, default, ...])	Return a list of strings from the options for the given key.
handle_error(msg[, error_class])	Handle an error.
merge_options(current, new)	Merge new options into the current options.
options_to_dict(options[, add_singular])	Converts a single command to a dictionary.
stringify(dictionary)	Set all values in a nested dictionary to strings.
update(options)	Update the stored options with another.

Attributes Documentation

append_keys = ()

is_empty

Return True if the options contain any key-values.

Returns:

bool

size

Return the number of available options.

Returns:

n_optionsint

Methods Documentation

clear()

Clear all options.

Returns:

None

copy()

Return a copy of the options.

Returns:

Options

get(key, default=None, unalias=True)

Retrieve the given key value from the options.

Parameters:

keystr

The name of the value to retrieve.

defaultobject, optional

The value to return if the options do not contain the given key.

unaliasbool, optional

If True, unalias the key before attempting retrieval.

Returns:

valuestr

The retrieved value. Note that all ConfigObj values are strings.

get_bool(key, default=False, unalias=True)

Return a boolean value from the options for the given key.

Parameters:

keystr

The name of the options value to retrieve.

defaultbool, optional

The default value to return if key does not exist in the options.

unaliasbool, optional

If True, unalias the key before attempting retrieval.

Returns:

valuebool

get_dms_angle(key, default=nan, unalias=True)

Return a degree:minutes:seconds angle for the given options key.

Parameters:

keystr

The name of the options value to retrieve. The value should be expected to be parsable as a degree:minutes:second angle according to utils.parse_angle().

defaultint or float or units.Quantity, optional

The default angle to return in cases where the value cannot be parsed correctly

unaliasbool, optional

If True, unalias the key before attempting retrieval.

Returns:

valueunits.Quantity

The resolved angle in degrees.

get_float(key, default=nan, unalias=True)

Return a float value from the options for the given key.

Parameters:

keystr

The name of the options value to retrieve.

defaultfloat, optional

The default value to return if key does not exist in the options.

unaliasbool, optional

If True, unalias the key before attempting retrieval.

Returns:

valuefloat

get_float_list(key, delimiter=',', default=None, unalias=True)

Return a list of floats from the options for the given key.

Parameters:

keystr

The name of the options value to retrieve.

delimiterstr, optional

The string delimiter used to separate one element from the next.

defaultlist, optional

The default value to return if key does not exist in the options.

unaliasbool, optional

If True, unalias the key before attempting retrieval.

Returns:

valuelist (float)

get_hms_time(key, angle=False, default=nan, unalias=True)

Return a hour:minutes:seconds angle for the given options key.

Parameters:

keystr

The name of the options value to retrieve. The value should be expected to be parsable as a degree:minutes:second angle according to utils.parse_angle().

anglebool, optional

If True, return an hour angle unit instead of hour unit.

defaultint or float or units.Quantity, optional

The default angle to return in cases where the value cannot be parsed correctly

unaliasbool, optional

If True, unalias the key before attempting retrieval.

Returns:

timeunits.Quantity

The resolved time in hours, or as an hour angle.

get_int(key, default=0, unalias=True)

Return an integer value from the options for the given key.

Parameters:

keystr

The name of the options value to retrieve.

defaultint, optional

The default value to return if key does not exist in the options.

unaliasbool, optional

If True, unalias the key before attempting retrieval.

Returns:

valueint

get_int_list(key, delimiter=',', default=None, unalias=True, is_positive=False)

Return a list of integers from the options for the given key.

Parameters:

keystr

The name of the options value to retrieve.

delimiterstr, optional

The string delimiter used to separate one element from the next.

defaultlist, optional

The default value to return if key does not exist in the options.

unaliasbool, optional

If True, unalias the key before attempting retrieval.

is_positivebool, optional

If True, ranges may be specified using both ‘:’ and ‘-’ characters in a string. Otherwise, the ‘-’ character will imply a negative value.

Returns:

valuelist (int)

get_list(key, default=None, unalias=True)

Return a list value from the options for the given key.

Parameters:

keystr

The name of the options value to retrieve.

defaultlist, optional

The default value to return if key does not exist in the options.

unaliasbool, optional

If True, unalias the key before attempting retrieval.

Returns:

valuelist

get_range(key, default=<sofia_redux.scan.utilities.range.Range object> (-inf -> inf), is_positive=False, unalias=True)

Return a Range value from the options for the given key.

Parameters:

keystr

The name of the options value to retrieve.

defaultRange, optional

The default value to return if key does not exist in the options.

is_positivebool, optional

If True, all values in the range are considered positive and any ‘-’ character in spec will be treated as a delimiter rather than a minus sign.

unaliasbool, optional

If True, unalias the key before attempting retrieval.

Returns:

valueRange

get_sign(key, default=0, unalias=True)

Return an integer representation of a sign value in the options.

Parameters:

keystr

The name of the options value to retrieve.

defaultint, optional

The default sign to return.

unaliasbool, optional

If True, unalias the key before attempting retrieval.

Returns:

signint

1 for a positive sign, -1 for a negative sign, and 0 for no sign.

get_string(key, default=None, unalias=True)

Return a string value from the options for the given key.

Parameters:

keystr

The name of the options value to retrieve.

defaultstr, optional

The default value to return if key does not exist in the options.

unaliasbool, optional

If True, unalias the key before attempting retrieval.

Returns:

valuestr

get_string_list(key, delimiter=',', default=None, unalias=True)

Return a list of strings from the options for the given key.

Parameters:

keystr

The name of the options value to retrieve.

delimiterstr, optional

The string delimiter used to separate one element from the next.

defaultlist, optional

The default value to return if key does not exist in the options.

unaliasbool, optional

If True, unalias the key before attempting retrieval.

Returns:

valuelist (str)

handle_error(msg, error_class=<class 'ValueError'>)

Handle an error.

If errors are allowed, will emit a log WARNING message and return if verbose is set. If errors are not allowed, raises an error.

Parameters:

msgstr

The message to emit by via log or in the raised error.

error_classclass (BaseException)

The error type to raise.

Returns:

None

Raises:

BaseException

If errors are not permitted.

classmethod merge_options(current, new)

Merge new options into the current options.

Merging new conditions into the currently existing options is slightly complicated. Command key values must be appended to any currently existing commands keys in the current conditions as a list. There is also additional handling in place to ensure conditions are updated appropriately since branches may also contain specific values rather than just a simply dictionary of values. E.g., if we currently have {‘sky’: True} and we want to add the options {‘sky’: {‘gain’: ‘0.3:3’}} then the output options should be: {‘sky’: {‘value’: True, ‘gain’:’0.3:3’}}}.

Parameters:

currentConfigObj

newdict or ConfigObj

Returns:

None

static options_to_dict(options, add_singular=True)

Converts a single command to a dictionary.

Parameters:

optionsstr or dict or configobj.ConfigObj

The options to convert to a dict.

add_singularbool, optional

If True, and a string option just consists of the name, allow it to be added to the configuration as {‘add’: option} to be parsed accordingly during configuration validation. Otherwise, None will be returned

Returns:

dict_optionsdict or None

A dictionary or None if the options could not be parsed.

classmethod stringify(dictionary)

Set all values in a nested dictionary to strings.

Parameters:

dictionarydict

Returns:

dict

update(options)

Update the stored options with another.

Parameters:

optionsdict or ConfigObj

The configuration options to read and parse.

Returns:

None