Merge branch 'master' into enh/rapidart

* master: (24 commits)
  Fix #493
  Fixes #459
  fixed doctests
  changelog
  BF: Fixed several issues with GroupAndStack interface
  DOC: Various clean up an improvements to docstrings.
  DOC: Added example to LookupMeta docstring
  ENH: Allow meta_keys input to LookupMeta be a mapping.
  minor fixes
  doc: added version config info to doc
  enh: added output versioning as well
  BF: Wrap imports of optional deps in try-except block
  STY: Cleanup some long lines.
  ENH: Making interface module name dcmstack to match package
  ENH: Allow control of meta data filtering in DcmStack.
  BF: Fixed bug in CopyMeta
  ENH: Default to 'force=True' when reading DICOM files.
  BF: CopyMeta inputspec and outputspec were undefined.
  WIP: Initial interface to dcmstack package.
  sty: pep8
  ...

Author: satra

CHANGES

@@ -3,11 +3,12 @@ Next release
 
 * ENH: Add basic support for LSF plugin.
 * ENH: New interfaces: ICC, Meshfix, ants.Register, C3dAffineTool, ants.JacobianDeterminant,
-       afni.AutoTcorrelate
+       afni.AutoTcorrelate, DcmStack
 * ENH: New workflows: ants template building (both using 'ANTS' and the new 'antsRegistration')
 * 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
 * ENH: added deprecation metadata to traits
 * ENH: Slicer interfaces were updated to version 4.1
 

doc/devel/interface_specs.rst

@@ -263,7 +263,15 @@ Common
 	should be symlinked, while `True` indicates that the contents should be 
 	copied over.
 
-``deprecated``
+``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)
+``deprecated`` and ``new_name``
     This is metadata for removing or renaming an input field from a spec.::
 
         class RealignInputSpec(BaseInterfaceInputSpec):
@@ -277,8 +285,8 @@ Common
     from current release. Raises `TraitError` after package version crosses the
     deprecation version.
 
-``new_name``
-    For inputs that are being renamed, one can specify the new name of the field.::
+    For inputs that are being renamed, one can specify the new name of the
+    field.::
 
         class RealignInputSpec(BaseInterfaceInputSpec):
             jobtype = traits.Enum('estwrite', 'estimate', 'write',
@@ -293,6 +301,11 @@ Common
     When `new_name` is provided it must exist as a trait, otherwise an exception
     will be raised.
 
+.. note::
+
+   The version information for `min_ver`, `max_ver` and `deprecated` has to be
+   provided as a string. For example, `min_ver='0.1'`.
+
 CommandLine
 ^^^^^^^^^^^
 

doc/users/config_file.rst

@@ -109,6 +109,11 @@ Execution
 	data through (without copying) (possible values: ``true`` and
 	``false``; default value: ``false``)
 
+*stop_on_unknown_version*
+    If this is set to True, an underlying interface will raise an error, when no
+    version information is available. Please notify developers or submit a
+    patch.
+
 Example
 ~~~~~~~
 

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, LooseVersion
 from .. import __version__
 from nipype.utils.filemanip import split_filename
@@ -639,6 +639,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 \
@@ -665,6 +669,7 @@ class BaseInterface(Interface):
 
     """
     input_spec = BaseInterfaceInputSpec
+    _version = None
 
     def __init__(self, **inputs):
         if not self.input_spec:
@@ -824,6 +829,36 @@ def _check_mandatory_inputs(self):
                                              transient=None).items():
             self._check_requires(spec, name, getattr(self.inputs, name))
 
+    def _check_version_requirements(self, trait_object, raise_exception=True):
+        """ Raises an exception on version mismatch
+        """
+        unavailable_traits = []
+        version = LooseVersion(str(self.version))
+        if not version:
+            return
+        # check minimum version
+        names = trait_object.trait_names(**dict(min_ver=lambda t: t is not None))
+        for name in names:
+            min_ver = LooseVersion(str(trait_object.traits()[name].min_ver))
+            if min_ver > version:
+                unavailable_traits.append(name)
+                if not isdefined(getattr(trait_object, name)):
+                    continue
+                if raise_exception:
+                    raise Exception('Trait %s (%s) (version %s < required %s)' %
+                              (name, self.__class__.__name__, version, min_ver))
+        names = trait_object.trait_names(**dict(max_ver=lambda t: t is not None))
+        for name in names:
+            max_ver = LooseVersion(str(trait_object.traits()[name].max_ver))
+            if max_ver < version:
+                unavailable_traits.append(name)
+                if not isdefined(getattr(trait_object, name)):
+                    continue
+                if raise_exception:
+                    raise Exception('Trait %s (%s) (version %s > required %s)' %
+                              (name, self.__class__.__name__, version, max_ver))
+        return unavailable_traits
+
     def _run_interface(self, runtime):
         """ Core function that executes interface
         """
@@ -846,6 +881,7 @@ def run(self, **inputs):
         """
         self.inputs.set(**inputs)
         self._check_mandatory_inputs()
+        self._check_version_requirements(self.inputs)
         interface = self.__class__
         # initialize provenance tracking
         env = deepcopy(os.environ.data)
@@ -905,9 +941,18 @@ def aggregate_outputs(self, runtime=None, needed_outputs=None):
         predicted_outputs = self._list_outputs()
         outputs = self._outputs()
         if predicted_outputs:
+            _unavailable_outputs = []
+            if outputs:
+                _unavailable_outputs = \
+                               self._check_version_requirements(self._outputs())
             for key, val in predicted_outputs.items():
                 if needed_outputs and key not in needed_outputs:
                     continue
+                if key in _unavailable_outputs:
+                    raise KeyError(('Output trait %s not available in version '
+                                    '%s of interface %s. Please inform '
+                                    'developers.') % (key, self.version,
+                                                      self.__class__.__name__))
                 try:
                     setattr(outputs, key, val)
                     _ = getattr(outputs, key)
@@ -920,6 +965,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
@@ -1063,6 +1116,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)
@@ -1106,6 +1160,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
@@ -1122,15 +1202,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],