fsleyes_props.cli

Generate command line arguments for a HasProperties instance.

This module provides the following functions:

addParserArguments	Adds arguments to the given argparse.ArgumentParser for the properties of the given HasProperties class or instance.
applyArguments	Apply arguments to a HasProperties instance.
generateArguments	Given a HasProperties instance, generates a list of arguments which could be used to configure another instance in the same way.

The addParserArguments function is used to add arguments to an ArgumentParser object for the properties of a HasProperties class. The simplest way to do so is to allow the addParserArguments function to automatically generate short and long arguments from the property names:

>>> import argparse
>>> import fsleyes_props as props

>>> class MyObj(props.HasProperties):
        intProp  = props.Int()
        boolProp = props.Boolean()

>>> parser = argparse.ArgumentParser('MyObj')
>>> props.addParserArguments(MyObj, parser)

>>> parser.print_help()
usage: MyObj [-h] [-b] [-i INT]

optional arguments:
    -h, --help            show this help message and exit
    -b, --boolProp
    -i INT, --intProp INT

Now, if we have a MyObj instance, and some arguments:

>>> myobj = MyObj()

>>> args = parser.parse_args(['-b', '--intProp', '52'])

>>> print myobj
MyObj
  boolProp = False
   intProp = 0

>>> props.applyArguments(myobj, args)
>>> print myobj
MyObj
  boolProp = True
   intProp = 52

If you want to customise the short and long argument tags, and the help text, for each property, you can pass them in to the addParserArguments function:

>>> shortArgs = {'intProp' : 'r',              'boolProp' : 't'}
>>> longArgs  = {'intProp' : 'TheInt',         'boolProp' : 'someBool'}
>>> propHelp  = {'intProp' : 'Sets int value', 'boolProp' : 'Toggles bool'}

>>> parser = argparse.ArgumentParser('MyObj')
>>> props.addParserArguments(MyObj,
                             parser,
                             shortArgs=shortArgs,
                             longArgs=longArgs,
                             propHelp=propHelp)
>>> parser.print_help()
usage: MyObj [-h] [-t] [-r INT]

optional arguments:
  -h, --help            show this help message and exit
  -t, --someBool        Toggles bool
  -r INT, --TheInt INT  Sets int value

Or, you can add the short and long arguments, and the help text, as specially named class attributes of your HasProperties class or instance:

>>> class MyObj(props.HasProperties):
        intProp  = props.Int()
        boolProp = props.Boolean()
        _shortArgs = {
            'intProp'  : 'r',
            'boolProp' : 't'
        }
        _longArgs = {
            'intProp'  : 'TheInt',
            'boolProp' : 'someBool'
        }
        _propHelp = {
            'intProp' : 'Sets int value',
            'boolProp' : 'Toggles bool'
        }

>>> parser = argparse.ArgumentParser('MyObj')
>>> props.addParserArguments(MyObj, parser)

>>> parser.print_help()
usage: MyObj [-h] [-t] [-r INT]

optional arguments:
  -h, --help            show this help message and exit
  -t, --someBool        Toggles bool
  -r INT, --TheInt INT  Sets int value

>>> args = parser.parse_args('--someBool -r 23413'.split())
>>> myobj = MyObj()
>>> props.applyArguments(myobj, args)
>>> print myobj
MyObj
  boolProp = True
   intProp = 23413

The generateArguments function, as the name suggests, generates command line arguments from a HasProperties instance:

>>> props.generateArguments(myobj)
['--someBool', '--TheInt', '23413']

The generateArguments and applyArguments functions optionally accept a set of transform functions which, for generateArguments, take the value of a property, and return some transformation of that property, suitable to be used as a command line argument value. The transform functions passed to the applyArguments function perform the reverse transformation. Transforms are useful for properties which cannot easily be converted to/from strings, and also for properties where the value you wish users to pass in on the command line does not correspond exactly to the value you wish the property to be given.

For example:

>>> class MyObject(props.HasProperties):
        showBlah = props.Boolean(default=True)

>>> shortArgs = {'showBlah' : 'hb'}
>>> longArgs  = {'showBlah' : 'hideBlah'}
>>> xforms    = {'showBlah' : lambda b : not b }

>>> parser = argparse.ArgumentParser('MyObject')
>>> props.addParserArguments(MyObject,
                             parser,
                             shortArgs=shortArgs,
                             longArgs=longArgs)

>>> myobj = MyObject()
>>> myobj.showBlah = False

>>> props.generateArguments(myobj,
                            shortArgs=shortArgs,
                            longArgs=longArgs,
                            xformFuncs=xforms)
    ['--hideBlah']

In this example, we can use the same transform function for the reverse operation:

>>> myobj2 = MyObject()
>>> args   = parser.parse_args(['--hideBlah'])
>>> props.applyArguments(myobj2,
                         args,
                         xformFuncs=xforms,
                         longArgs=longArgs)
>>> print myobj2
    MyObject
        showBlah = False

The cli module supports the following property types:

_String	Adds an argument to the given parser for the given String property.
_Choice	Adds an argument to the given parser for the given Choice property.
_Boolean	Adds an argument to the given parser for the given Boolean property.
_Int	Adds an argument to the given parser for the given Int property.
_Real	Adds an argument to the given parser for the given Real property.
_Percentage	Adds an argument to the given parser for the given Percentage property.
_Bounds	Adds an argument to the given parser for the given Bounds property.
_Point	Adds an argument to the given parser for the given Point property.
_Colour	Adds an argument to the given parser for the given Colour property.
_ColourMap	Adds an argument to the given parser for the given ColourMap property.

exception fsleyes_props.cli.SkipArgument

Bases: Exception

This exception may be raised by transform functions which are called by applyArguments() and generateArguments() to indicate that the arguemnt should be skipped (i.e. not applied, or not generated).

__module__ = 'fsleyes_props.cli'

__weakref__

list of weak references to the object (if defined)

fsleyes_props.cli._String(parser, propObj, propCls, propName, propHelp, shortArg, longArg, atype=<class 'str'>)

Adds an argument to the given parser for the given String property.

Parameters

• parser – An ArgumentParser instance.

• propCls – A HasProperties class or instance.

• propObj – The PropertyBase class.

• propName – Name of the property.

• propHelp – Custom help text for the property.

• shortArg – String to use as the short argument.

• longArg – String to use as the long argument.

• atype – Data type to expect (defaults to str). This allows the conversion type to be overridden for some, but not all, property types.

fsleyes_props.cli._Choice(parser, propObj, propCls, propName, propHelp, shortArg, longArg, **kwargs)

Adds an argument to the given parser for the given Choice property. See the _String() documentation for details on the parameters.

Only works with Choice properties with string options (unless the choices argument is provided). See the allowStr parameter for Choice instances.

All of the described arguments must be speified as keyword arguments. Any additional arguments will be passed to the ArgumentParser.add_argument method.

Parameters

• choices – If not None, assumed to be list of possible choices for the property. If not provided, the possible choices are taken from the Choice.getChoices() method. If explicitly passed in as None, the argument will be configured to accept any value.

• default – If not None, gives the default value. Otherwise, the default attribute of the Choice object is used.

• useAlts – If True (the default), alternate values for the choices are added as options (see the Choice class). n.b. This flag will have no effect if choices is explicitly set to None, as desrcibed above.

• metavar – If None (the default), the available choices for this property will be shown in the help text. Otherwise, this string will be shown instead.

fsleyes_props.cli._Boolean(parser, propObj, propCls, propName, propHelp, shortArg, longArg)

Adds an argument to the given parser for the given Boolean property. See the _String() documentation for details on the parameters.

fsleyes_props.cli._Int(parser, propObj, propCls, propName, propHelp, shortArg, longArg)

Adds an argument to the given parser for the given Int property. See the _String() documentation for details on the parameters.

fsleyes_props.cli._Real(parser, propObj, propCls, propName, propHelp, shortArg, longArg)

Adds an argument to the given parser for the given Real property. See the _String() documentation for details on the parameters.

fsleyes_props.cli._Percentage(parser, propObj, propCls, propName, propHelp, shortArg, longArg)

Adds an argument to the given parser for the given Percentage property. See the _String() documentation for details on the parameters.

fsleyes_props.cli._Bounds(parser, propObj, propCls, propName, propHelp, shortArg, longArg, atype=None)

Adds an argument to the given parser for the given Bounds property. See the _String() documentation for details on the parameters.

fsleyes_props.cli._Point(parser, propObj, propCls, propName, propHelp, shortArg, longArg)

Adds an argument to the given parser for the given Point property. See the _String() documentation for details on the parameters.

fsleyes_props.cli._Colour(parser, propObj, propCls, propName, propHelp, shortArg, longArg, alpha=True)

Adds an argument to the given parser for the given Colour property. See the _String() documentation for details on the parameters.

fsleyes_props.cli._ColourMap(parser, propObj, propCls, propName, propHelp, shortArg, longArg, parseStr=False, choices=None, metavar=None)

Adds an argument to the given parser for the given ColourMap property.

Parameters

• parseStr – If False (the default), the parser will be configured to parse any registered matplotlib colour map name. Otherwise, the parser will accept any string, and assume that the ColourMap property is set up to accept it.

• choices – This parameter can be used to restrict the values that will be accepted.

• metavar – If choices is not None, they will be shown in the help text, unless this string is provided.

See the _String() documentation for details on the other parameters.

fsleyes_props.cli._getShortArgs(propCls, propNames, exclude='')

Generates unique single-letter argument names for each of the names in the given list of property names. Any letters in the exclude string are not used as short arguments.

Parameters

• propCls – A HasProperties class.

• propNames – List of property names for which short arguments are to be generated.

• exclude – String containing letters which should not be used.

fsleyes_props.cli.applyArguments(hasProps, arguments, propNames=None, xformFuncs=None, longArgs=None, **kwargs)

Apply arguments to a HasProperties instance.

Given a HasProperties instance and an argparse.Namespace instance, sets the property values of the HasProperties instance from the values stored in the Namespace object.

Parameters

• hasProps – The HasProperties instance.

• arguments – The Namespace instance.

• propNames – List of property names to apply. If None, an attempt is made to set all properties. If not None, the property values are set in the order specified by this list.

• xformFuncs – A dictionary of {property name -> function} mappings, which can be used to transform the value given on the command line before it is assigned to the property.

• longArgs – Dict containing {property name : longArg} mappings.

All other keyword arguments are passed through to the xformFuncs functions.

fsleyes_props.cli.addParserArguments(propCls, parser, cliProps=None, shortArgs=None, longArgs=None, propHelp=None, extra=None, exclude='')

Adds arguments to the given argparse.ArgumentParser for the properties of the given HasProperties class or instance.

Parameters

• propCls – A HasProperties class. An instance may alternately be passed in.

• parser – An ArgumentParser to add arguments to.

• cliProps (list) – List containing the names of properties to add arguments for. If None, and an attribute called _cliProps’ is present on the propCls class, the value of that attribute is used. Otherwise an argument is added for all properties.

• shortArgs (dict) – Dict containing {propName: shortArg} mappings, to be used as the short (typically single letter) argument flag for each property. If None, and an attribute called _shortArgs is present on the propCls class, the value of that attribute is used. Otherwise, short arguments are automatically generated for each property.

• longArgs (dict) – Dict containing {propName: longArg} mappings, to be used as the long argument flag for each property. If None, and an attribute called _longArgs is present on the propCls class, the value of that attribute is used. Otherwise, the name of each property is used as its long argument.

• propHelp (dict) – Dict containing {propName: helpString] mappings, to be used as the help text for each property. If None, and an attribute called _propHelp is present on the propCls class, the value of that attribute is used. Otherwise, no help string is used.

• extra (dict) – Any property-specific settings to be passed through to the parser configuration function (see e.g. the _Choice() function). If None, and an attribute called _propExtra is present on the propCls class, the value of that attribute is used instead.

• exclude (str) – String containing letters which should not be used as short arguments.

fsleyes_props.cli.generateArguments(hasProps, useShortArgs=False, xformFuncs=None, cliProps=None, shortArgs=None, longArgs=None, exclude='', **kwargs)

Given a HasProperties instance, generates a list of arguments which could be used to configure another instance in the same way.

Parameters

• hasProps – The HasProperties instance.

• useShortArgs – If True the short argument version is used instead of the long argument version.

• xformFuncs – A dictionary of {property name -> function} mappings, which can be used to perform some arbitrary transformation of property values.

All other keyword arguments are passed through to the xformFuncs functions.

See the addParserArguments() function for descriptions of the other parameters.