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 givenHasProperties
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()
andgenerateArguments()
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.
- parser – An
-
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 thechoices
argument is provided). See theallowStr
parameter forChoice
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 theChoice.getChoices()
method. If explicitly passed in asNone
, the argument will be configured to accept any value. - default – If not
None
, gives the default value. Otherwise, thedefault
attribute of theChoice
object is used. - useAlts – If
True
(the default), alternate values for the choices are added as options (see theChoice
class). n.b. This flag will have no effect ifchoices
is explicitly set toNone
, 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.
- choices – If not
-
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 registeredmatplotlib
colour map name. Otherwise, the parser will accept any string, and assume that theColourMap
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 notNone
, they will be shown in the help text, unless this string is provided.
See the
_String()
documentation for details on the other parameters.- parseStr – If
-
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.
- propCls – A
-
fsleyes_props.cli.
applyArguments
(hasProps, arguments, propNames=None, xformFuncs=None, longArgs=None, **kwargs)¶ Apply arguments to a
HasProperties
instance.Given a
HasProperties
instance and anargparse.Namespace
instance, sets the property values of theHasProperties
instance from the values stored in theNamespace
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 notNone
, 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.- hasProps – The
-
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 givenHasProperties
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 thepropCls
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. IfNone
, and an attribute called_shortArgs
is present on thepropCls
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. IfNone
, and an attribute called_longArgs
is present on thepropCls
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. IfNone
, and an attribute called_propHelp
is present on thepropCls
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). IfNone
, and an attribute called_propExtra
is present on thepropCls
class, the value of that attribute is used instead. - exclude (str) – String containing letters which should not be used as short arguments.
- propCls – A
-
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.- hasProps – The