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

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.