pyesorex.parameter

Alternatives to the Parameter and ParameterList classes from cpl.ui for use by PyEsoRex.

class pyesorex.parameter.Parameter

Base class.

This base class is an alternative to that provided by PyCPL, providing some additional properties and methods that are helpful for PyEsoRex as well as an alternative string representation. This class is not intended to be instantiated itself, one of the derived classes in this module should be used instead.

See also

cpl.ui.Parameter

Parameter base class from PyCPL

classmethod from_cplui(parameter)

Creates a PyEsoRex parameter object from a cpl.ui.Parameter* object

Parameters:

parameter (cpl.ui.Parameter) – An instance of one of the cpl.ui.Parameter* classes.

set_from_string(string_value)

Set the value of the parameter from a string, performing any necessary conversions.

Uses an appropriate function to convert the string to the data type of the parameter (e.g. float(), int(), true_of_false()) then sets the value with it.

Parameters:

string_value (str) – String containing the new value for the parameter.

See also

get_string_converter

Returns a function to convert a string to the data type of the given parameter.

property cfg_help

Constructs a help string for use in PyEsoRex/recipe configuration files.

If the parameter has env_alias attribute that differs from the parameter name, i.e the parameter can be set with an environment variable, a note will be added to the help string to that effect, otherwise the help string is simply the parameter’s description attribute.

Returns:

Configuration help string.

Return type:

str

property cli_help

Constructs a help string for use in the PyEsoRex command line help.

The command line help string is the came as the config help string, except that the current value of the parameter is appended to the end in square brakets.

Returns:

CLI help string.

Return type:

str

See also

cfg_help

Constructs a help string for use in PyEsoRex/recipe configuration files.

property valtype

String representation of the parameter data type.

class pyesorex.parameter.ParameterEnum(name, description, context, default, alternatives, tag=None, value=None, cli_alias=None, env_alias=None, cfg_alias=None, action=<class 'pyesorex.action.ParameterAction'>, nargs='?', const=True, callback=None)

ParameterEnum class.

This class is an alternative to that provided by PyCPL, adding the option to set the tag, value, cli_alias, env_alias and cfg_alias attributes when creating an instance.

Parameters:

  • name (str) – Name of the parameter.

  • description (str) – Description of the parameter.

  • context (str) – Context of the parameter.

  • default (str or int or bool or float or complex) – Default value for the parameter. The type of this argument is used to set the data type of the parameter.

  • alternatives (sequence of str or int or float) – Sequence containing the allowed values for the parameter.

  • tag (str, optional) – Tag of the parameter.

  • value (str or int or float or complex, optional) – Initial value for the parameter. The type of this argument must match the data type of the parameter. If not given the initial value of the parameter will be equal to default.

  • cli_alias (str, optional) – Alternative name used to refer to the parameter on the command line. If not given will be set to be the same value as name.

  • env_alias (str, optional) – Alternative name used when setting the parameter from environment variables. If not given will be set to be the same value as name.

  • cfg_alias (str, optional) – Alternative name use to refer to the parameter in configuration files. If not given will be set to the same value as name.

  • action (argparse.Action, optional) – Action class to be used when the parameter is being set using command line arguments, default pyesorex.pyesorex.ParameterAction.

  • nargs (str or int, optional) – “Number of args” for the corresponding command line option. Can be an integer >= 0, “?”, “*” or “+”, see the Python Standard Library documentation for argparse.ArgumentParser.add_argument() for details. The default is “?”, i.e. 1 or 0.

  • const (str or int or bool or float or complex, optional) – Value the parameter will be set to if its command line option is used without a following argument, if nargs=”?”, see the Python Standard Library documentation for argparse.ArgumentParser.add_argument() for details. The type of this argument must match the data type of the parameter or be convertable to it by the data type’s constructor, e.g. a string literal for a value of the correct type. The default is True.

  • callback (callable, default=None) – A function of two variables (the Parameter object and the new value) that will be called whenever the parameter value is changed. The callback is called before setting the parameter value so it can be used to validate the new value (raising an Exception to prevent the change of value).

See also

cpl.ui.ParameterEnum

ParameterEnum class from PyCPL

as_dict(defaults=False)

Returns a dict representation suitable for serialisation by json.dump().

Parameters:

defaults (bool, default False) – If True the value linked to the “value” key in the returned dictionary will be set to the parameter’s default value, not its current value.

Returns:

Dictionary containing the key: value pairs required for JSON format config files.

Return type:

dict

property cfg_help

Constructs a help string for use in PyEsoRex/recipe configuration files.

The string starts with the parameter’s description attribute, then if the parameter has env_alias attribute that differs from the parameter name, i.e the parameter can be set with an environment variable, a note will be added to the help string to that effect. Finally the alternative values for the parameter are added to the end of the string.

Returns:

Configuration help string.

Return type:

str

property partype

String representation of the parameter type, in this case ‘value’.

class pyesorex.parameter.ParameterList(initlist=None)

ParameterList class.

This class is an alternative to that provided by PyCPL, adding new methods and a more useful string format useful for PyEsoRex. This class allows parameters to be accessed by integer index, by the parameter name, or by the parameter’s cfg_alias.

Parameters:

parameters (sequence of cpl.ui.Parameter or pyesorex.pyesorex.Parameter, optional) – Initial set of parameters for the parameter list.

See also

cpl.ui.ParameterList

ParameterListClass from PyCPL

Notes

Needed to replace PyCPL ParameterList because that can’t hold the derived Parameter classes from this module. The PyCPL ParameterList isn’t really like a Python list, basically it implement the Sequence interface but adds a custom append instead of implementing __setitem__, __delitem__ and insert as would be required for MutableSequence, then throws in an inefficient alternative __getitem__ for lookup by parameter name instead of index. The closest match is probably subclassing UserList and overriding __getitem__ and __setitem__ to add the lookup by name option.

as_dict()

Return the names and values of the parameters in the list as a dictionary.

Returns:

Dictionary containing the names & values of the parameters in the list.

Return type:

dict

update(other)

Update the values of the parameters in the list from a dictionary, like the update method of Python dictionaries.

Parameters:

other (dict) – Dictionary containing parameters names & new values.

class pyesorex.parameter.ParameterRange(name, description, context, default, min, max, tag=None, value=None, cli_alias=None, env_alias=None, cfg_alias=None, action=<class 'pyesorex.action.ParameterAction'>, nargs='?', const=True, callback=None)

ParameterRange class.

This class is an alternative to that provided by PyCPL, adding the option to set the tag, value, cli_alias, env_alias and cfg_alias attributes when creating an instance.

Parameters:

  • name (str) – Name of the parameter.

  • description (str) – Description of the parameter.

  • context (str) – Context of the parameter.

  • default (str or int or bool or float or complex) – Default value for the parameter. The type of this argument is used to set the data type of the parameter.

  • min (int or float) – Minimum allowable value for the parameter.

  • max (int or float) – Maximum allowable value for the parameter.

  • tag (str, optional) – Tag of the parameter.

  • value (str or int or bool or float or complex, optional) – Initial value for the parameter. The type of this argument must match the data type of the parameter. If not given the initial value of the parameter will be equal to default.

  • cli_alias (str, optional) – Alternative name used to refer to the parameter on the command line. If not given will be set to be the same value as name.

  • env_alias (str, optional) – Alternative name used when setting the parameter from environment variables. If not given will be set to be the same value as name.

  • cfg_alias (str, optional) – Alternative name use to refer to the parameter in configuration files. If not given will be set to the same value as name.

  • action (argparse.Action, optional) – Action class to be used when the parameter is being set using command line arguments, default pyesorex.pyesorex.ParameterAction

  • nargs (str or int, optional) – “Number of args” for the corresponding command line option. Can be an integer >= 0, “?”, “*” or “+”, see the Python Standard Library documentation for argparse.ArgumentParser.add_argument() for details. The default is “?”, i.e. 1 or 0.

  • const (str or int or bool or float or complex, optional) – Value the parameter will be set to if its command line option is used without a following argument, if nargs=”?”, see the Python Standard Library documentation for argparse.ArgumentParser.add_argument() for details. The type of this argument must match the data type of the parameter or be convertable to it by the data type’s constructor, e.g. a string literal for a value of the correct type. The default is True.

  • callback (callable, default=None) – A function of two variables (the Parameter object and the new value) that will be called whenever the parameter value is changed. The callback is called before setting the parameter value so it can be used to validate the new value (raising an Exception to prevent the change of value).

See also

cpl.ui.ParameterRange

ParameterRange class from PyCPL

as_dict(defaults=False)

Returns a dict representation suitable for serialisation by json.dump().

Parameters:

defaults (bool, default False) – If True the value linked to the “value” key in the returned dictionary will be set to the parameter’s default value, not its current value.

Returns:

Dictionary containing the key: value pairs required for JSON format config files.

Return type:

dict

property cfg_help

Constructs a help string for use in PyEsoRex/recipe configuration files.

The string starts with the parameter’s description attribute, then if the parameter has env_alias attribute that differs from the parameter name, i.e the parameter can be set with an environment variable, a note will be added to the help string to that effect. Finally the minimum and maximum values for the parameter are added to the end of the string.

Returns:

Configuration help string.

Return type:

str

property partype

String representation of the parameter type, in this case ‘value’.

property value

Current value of the parameter

class pyesorex.parameter.ParameterValue(name, description, context, default, tag=None, value=None, cli_alias=None, env_alias=None, cfg_alias=None, action=<class 'pyesorex.action.ParameterAction'>, nargs='?', const=True, callback=None)

ParameterValue class.

This class is an alternative to that provided by PyCPL, adding the option to set the tag, value, cli_alias, env_alias and cfg_alias attributes when creating an instance.

Parameters:

  • name (str) – Name of the parameter.

  • description (str) – Description of the parameter.

  • context (str) – Context of the parameter.

  • default (str or int or bool or float or complex) – Default value for the parameter. The type of this argument is used to set the data type of the parameter.

  • tag (str, optional) – Tag of the parameter.

  • value (str or int or bool or float or complex, optional) – Initial value for the parameter. The type of this argument must match the data type of the parameter. If not given the initial value of the parameter will be equal to default.

  • cli_alias (str, optional) – Alternative name used to refer to the parameter on the command line. If not given will be set to be the same value as name.

  • env_alias (str, optional) – Alternative name used when setting the parameter from environment variables. If not given will be set to be the same value as name.

  • cfg_alias (str, optional) – Alternative name use to refer to the parameter in configuration files. If not given will be set to the same value as name.

  • action (argparse.Action, optional) – Action class to be used when the parameter is being set using command line arguments, default pyesorex.pyesorex.ParameterAction.

  • nargs (str or int, optional) – “Number of args” for the corresponding command line option. Can be an integer >= 0, “?”, “*” or “+”, see the Python Standard Library documentation for argparse.ArgumentParser.add_argument() for details. The default is “?”, i.e. 1 or 0.

  • const (str or int or bool or float or complex, optional) – Value the parameter will be set to if its command line option is used without a following argument, if nargs=”?”, see the Python Standard Library documentation for argparse.ArgumentParser.add_argument() for details. The type of this argument must match the data type of the parameter or be convertable to it by the data type’s constructor, e.g. a string literal for a value of the correct type. The default is True.

  • callback (callable, default=None) – A function of two variables (the Parameter object and the new value) that will be called whenever the parameter value is changed. The callback is called before setting the parameter value so it can be used to validate the new value (raising an Exception to prevent the change of value).

See also

cpl.ui.ParameterValue

ParameterValue class from PyCPL

as_dict(defaults=False)

Returns a dict representation suitable for serialisation by json.dump().

Parameters:

defaults (bool, default False) – If True the value linked to the “value” key in the returned dictionary will be set to the parameter’s default value, not its current value.

Returns:

Dictionary containing the key: value pairs required for JSON format config files.

Return type:

dict

property partype

String representation of the parameter type, in this case ‘value’.

property value

current value of the parameter

pyesorex.parameter.get_string_converter(parameter)

Returns a function to convert a string to the data type of the given parameter.

Parameters:

parameter (cpl.ui.Parameter or pyesorex.pyesorex.Parameter) – Parameter object used to determine the required data type.

Returns:

Function that will convert a str argument to the data type needed to set the value of parameter. May be true_of_false, float, int, complex or str.

Return type:

callable

pyesorex.parameter.true_or_false(string)

Converts a string “True” or “False” to the corresponding bool value.

Parameters:

string (str) – String to be converted to a bool. Must be either “True” or “False”, but the case does not matter.

Returns:

The boolean value that was spelled out in string.

Return type:

bool