enh: added versioning to traits and interfaces

Author: satra

CHANGES

@@ -6,6 +6,7 @@ Next release
 * ENH: New examples: how to use ANTS template building workflows (smri_ants_build_tmeplate), 
 	  how to set SGE specific options (smri_ants_build_template_new)
 * ENH: added no_flatten option to Merge
+* ENH: added versioning option and checking to traits
 
 Release 0.6.0 (Jun 30, 2012)
 ============================

doc/devel/interface_specs.rst

@@ -262,7 +262,16 @@ Common
 	can be set to either `True` or `False`. `False` indicates that contents 
 	should be symlinked, while `True` indicates that the contents should be 
 	copied over.
-	
+
+``min_ver`` and ``max_ver``
+    These metadata determine if a particular trait will be available when a
+    given version of the underlying interface runs. Note that this check is
+    performed at runtime.::
+
+	    class RealignInputSpec(BaseInterfaceInputSpec):
+	        jobtype = traits.Enum('estwrite', 'estimate', 'write', min_ver=5,
+	                              usedefault=True)
+
 CommandLine
 ^^^^^^^^^^^
 

nipype/interfaces/base.py

@@ -27,7 +27,7 @@
                                has_metadata)
 from ..utils.filemanip import (md5, hash_infile, FileNotFoundError,
                                hash_timestamp)
-from ..utils.misc import is_container, trim
+from ..utils.misc import is_container, trim, str2bool
 from .. import config, logging
 
 iflogger = logging.getLogger('interface')
@@ -602,6 +602,10 @@ def _get_filecopy_info(self):
         """
         raise NotImplementedError
 
+    @property
+    def version(self):
+        raise NotImplementedError
+
 
 class BaseInterfaceInputSpec(TraitedSpec):
     ignore_exception = traits.Bool(False, desc="Print an error message instead \
@@ -628,6 +632,7 @@ class BaseInterface(Interface):
 
     """
     input_spec = BaseInterfaceInputSpec
+    _version = None
 
     def __init__(self, **inputs):
         if not self.input_spec:
@@ -787,6 +792,26 @@ def _check_mandatory_inputs(self):
                                              transient=None).items():
             self._check_requires(spec, name, getattr(self.inputs, name))
 
+    def _check_input_version_requirements(self):
+        """ Raises an exception on version mismatch
+        """
+        version = str(self.version)
+        if not version:
+            return
+        # check minimum version
+        names = self.inputs.trait_names(**dict(min_ver=lambda t: t is not None))
+        for name in names:
+            min_ver = str(self.inputs.traits()[name].min_ver)
+            if min_ver > version:
+                raise Exception('Input %s (%s) (version %s < required %s)' %
+                              (name, self.__class__.__name__, version, min_ver))
+        names = self.inputs.trait_names(**dict(max_ver=lambda t: t is not None))
+        for name in names:
+            max_ver = str(self.inputs.traits()[name].max_ver)
+            if max_ver < version:
+                raise Exception('Input %s (%s) (version %s > required %s)' %
+                              (name, self.__class__.__name__, version, max_ver))
+
     def _run_interface(self, runtime):
         """ Core function that executes interface
         """
@@ -809,6 +834,7 @@ def run(self, **inputs):
         """
         self.inputs.set(**inputs)
         self._check_mandatory_inputs()
+        self._check_input_version_requirements()
         interface = self.__class__
         # initialize provenance tracking
         env = deepcopy(os.environ.data)
@@ -883,6 +909,14 @@ def aggregate_outputs(self, runtime=None, needed_outputs=None):
                         raise error
         return outputs
 
+    @property
+    def version(self):
+        if self._version is None:
+            if str2bool(config.get('execution', 'stop_on_unknown_version')):
+                raise ValueError('Interface %s has no version information' %
+                                 self.__class__.__name__)
+        return self._version
+
 
 class Stream(object):
     """Function to capture stdout and stderr streams with timestamps
@@ -1026,6 +1060,7 @@ class must be instantiated with a command argument
 
     input_spec = CommandLineInputSpec
     _cmd = None
+    _version = None
 
     def __init__(self, command=None, **inputs):
         super(CommandLine, self).__init__(**inputs)
@@ -1069,6 +1104,32 @@ def help(cls, returnhelp=False):
         else:
             print allhelp
 
+    def _get_environ(self):
+        out_environ = {}
+        try:
+            display_var = config.get('execution', 'display_variable')
+            out_environ = {'DISPLAY': display_var}
+        except NoOptionError:
+            pass
+        iflogger.debug(out_environ)
+        if isdefined(self.inputs.environ):
+            out_environ.update(self.inputs.environ)
+        return out_environ
+
+    def version_from_command(self, flag='-v'):
+        cmdname = self.cmd.split()[0]
+        if self._exists_in_path(cmdname):
+            env = deepcopy(os.environ.data)
+            out_environ = self._get_environ()
+            env.update(out_environ)
+            proc = subprocess.Popen(' '.join((cmdname, flag)),
+                                    shell=True,
+                                    env=env,
+                                    stdout=subprocess.PIPE,
+                                    stderr=subprocess.PIPE,
+                                    )
+            o, e = proc.communicate()
+            return o
 
     def _run_interface(self, runtime):
         """Execute command via subprocess
@@ -1085,15 +1146,7 @@ def _run_interface(self, runtime):
         setattr(runtime, 'stdout', None)
         setattr(runtime, 'stderr', None)
         setattr(runtime, 'cmdline', self.cmdline)
-        out_environ = {}
-        try:
-            display_var = config.get('execution', 'display_variable')
-            out_environ = {'DISPLAY': display_var}
-        except NoOptionError:
-            pass
-        iflogger.debug(out_environ)
-        if isdefined(self.inputs.environ):
-            out_environ.update(self.inputs.environ)
+        out_environ = self._get_environ()
         runtime.environ.update(out_environ)
         if not self._exists_in_path(self.cmd.split()[0]):
             raise IOError("%s could not be found on host %s" % (self.cmd.split()[0],

nipype/interfaces/tests/test_base.py

@@ -229,6 +229,64 @@ def _run_interface(self, runtime):
     nib.BaseInterface.input_spec = None
     yield assert_raises, Exception, nib.BaseInterface
 
+def test_version():
+    class InputSpec(nib.TraitedSpec):
+        foo = nib.traits.Int(desc='a random int', min_ver=0.9)
+    class DerivedInterface1(nib.BaseInterface):
+        input_spec = InputSpec
+    obj = DerivedInterface1()
+    not_raised = True
+    try:
+        obj._check_input_version_requirements()
+    except:
+        not_raised = False
+    yield assert_true, not_raised
+    config.set('execution', 'stop_on_unknown_version', True)
+    try:
+        obj._check_input_version_requirements()
+    except:
+        not_raised = False
+    yield assert_false, not_raised
+    config.set_default_config()
+    class InputSpec(nib.TraitedSpec):
+        foo = nib.traits.Int(desc='a random int', min_ver=0.9)
+    class DerivedInterface1(nib.BaseInterface):
+        input_spec = InputSpec
+        _version = 0.8
+    obj = DerivedInterface1()
+    yield assert_raises, Exception, obj._check_input_version_requirements
+    class InputSpec(nib.TraitedSpec):
+        foo = nib.traits.Int(desc='a random int', min_ver=0.9)
+    class DerivedInterface1(nib.BaseInterface):
+        input_spec = InputSpec
+        _version = 0.9
+    obj = DerivedInterface1()
+    not_raised = True
+    try:
+        obj._check_input_version_requirements()
+    except:
+        not_raised = False
+    yield assert_true, not_raised
+    class InputSpec(nib.TraitedSpec):
+        foo = nib.traits.Int(desc='a random int', max_ver=0.7)
+    class DerivedInterface2(nib.BaseInterface):
+        input_spec = InputSpec
+        _version = 0.8
+    obj = DerivedInterface2()
+    yield assert_raises, Exception, obj._check_input_version_requirements
+    class InputSpec(nib.TraitedSpec):
+        foo = nib.traits.Int(desc='a random int', max_ver=0.9)
+    class DerivedInterface1(nib.BaseInterface):
+        input_spec = InputSpec
+        _version = 0.9
+    obj = DerivedInterface1()
+    not_raised = True
+    try:
+        obj._check_input_version_requirements()
+    except:
+        not_raised = False
+    yield assert_true, not_raised
+
 def test_Commandline():
     yield assert_raises, Exception, nib.CommandLine
     ci = nib.CommandLine(command='which')

nipype/utils/config.py

@@ -45,6 +45,7 @@
 stop_on_first_crash = false
 stop_on_first_rerun = false
 use_relative_paths = false
+stop_on_unknown_version = false
 
 [check]
 interval = 1209600