Merge pull request #480 from satra/enh/deprecation

enh: added deprecation related metadata to traitedspec

Author: chrisgorgo

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 deprecation metadata to traits
 
 Release 0.6.0 (Jun 30, 2012)
 ============================

doc/devel/interface_specs.rst

@@ -262,7 +262,37 @@ 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.
-	
+
+``deprecated``
+    This is metadata for removing or renaming an input field from a spec.::
+
+        class RealignInputSpec(BaseInterfaceInputSpec):
+            jobtype = traits.Enum('estwrite', 'estimate', 'write',
+                                  deprecated='0.8',
+                                  desc='one of: estimate, write, estwrite',
+                                  usedefault=True)
+
+    In the above example this means that the `jobtype` input is deprecated and
+    will be removed in version 0.8. Deprecation should be set to two versions
+    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
+
+        class RealignInputSpec(BaseInterfaceInputSpec):
+            jobtype = traits.Enum('estwrite', 'estimate', 'write',
+                                  deprecated='0.8', new_name='job_type',
+                                  desc='one of: estimate, write, estwrite',
+                                  usedefault=True)
+            job_type = traits.Enum('estwrite', 'estimate', 'write',
+                                  desc='one of: estimate, write, estwrite',
+                                  usedefault=True)
+
+    In the above example, the `jobtype` field is being renamed to `job_type`.
+    When `new_name` is provided it must exist as a trait, otherwise an exception
+    will be raised.
+
 CommandLine
 ^^^^^^^^^^^
 

nipype/interfaces/base.py

@@ -28,7 +28,10 @@
 from ..utils.filemanip import (md5, hash_infile, FileNotFoundError,
                                hash_timestamp)
 from ..utils.misc import is_container, trim
-from .. import config, logging
+from .. import config, logging, LooseVersion
+from .. import __version__
+
+nipype_version = LooseVersion(__version__)
 
 iflogger = logging.getLogger('interface')
 
@@ -326,6 +329,10 @@ def _generate_handlers(self):
         requires = self.trait_names(**has_requires)
         for elem in requires:
             self.on_trait_change(self._requires_warn, elem)
+        has_deprecation = dict(deprecated=lambda t: t is not None)
+        deprecated = self.trait_names(**has_deprecation)
+        for elem in deprecated:
+            self.on_trait_change(self._deprecated_warn, elem)
 
     def _xor_warn(self, obj, name, old, new):
         """ Generates warnings for xor traits
@@ -347,7 +354,7 @@ def _xor_warn(self, obj, name, old, new):
     def _requires_warn(self, obj, name, old, new):
         """Part of the xor behavior
         """
-        if new:
+        if isdefined(new):
             trait_spec = self.traits()[name]
             msg = None
             for trait_name in trait_spec.requires:
@@ -358,6 +365,30 @@ def _requires_warn(self, obj, name, old, new):
             if msg:
                 warn(msg)
 
+    def _deprecated_warn(self, obj, name, old, new):
+        """Checks if a user assigns a value to a deprecated trait
+        """
+        if isdefined(new):
+            trait_spec = self.traits()[name]
+            msg1 = ('Input %s in interface %s is deprecated.') % (name,
+                                  self.__class__.__name__.split('InputSpec')[0])
+            msg2 = ('Will be removed or raise an error as of release %s') % \
+                                                           trait_spec.deprecated
+            self.trait_set(trait_change_notify=False, **{'%s' % name: Undefined})
+            if trait_spec.new_name:
+                if trait_spec.new_name not in self.copyable_trait_names():
+                    raise TraitError(msg1 + ' Replacement trait %s not found' %
+                                     trait_spec.new_name)
+                msg3 = 'It has been replaced by %s.' % trait_spec.new_name
+            else:
+                msg3 = ''
+            msg = ' '.join((msg1, msg2, msg3))
+            if LooseVersion(str(trait_spec.deprecated)) < nipype_version:
+                raise TraitError(msg)
+            else:
+                warn(msg)
+
+
     def _hash_infile(self, adict, key):
         """ Inject file hashes into adict[key]"""
         stuff = adict[key]

nipype/interfaces/tests/test_base.py

@@ -132,6 +132,32 @@ class MyInterface(nib.BaseInterface):
     myif.inputs.kung = 2
     yield assert_equal, myif.inputs.kung, 2.0
 
+def test_deprecation():
+    class DeprecationSpec1(nib.TraitedSpec):
+        foo = nib.traits.Int(deprecated='0.1')
+    spec_instance = DeprecationSpec1()
+    set_foo = lambda : setattr(spec_instance, 'foo', 1)
+    yield assert_raises, nib.TraitError, set_foo
+    class DeprecationSpec1numeric(nib.TraitedSpec):
+        foo = nib.traits.Int(deprecated=0.1)
+    spec_instance = DeprecationSpec1numeric()
+    set_foo = lambda : setattr(spec_instance, 'foo', 1)
+    yield assert_raises, nib.TraitError, set_foo
+    class DeprecationSpec2(nib.TraitedSpec):
+        foo = nib.traits.Int(deprecated='100', new_name='bar')
+    spec_instance = DeprecationSpec2()
+    set_foo = lambda : setattr(spec_instance, 'foo', 1)
+    yield assert_raises, nib.TraitError, set_foo
+    class DeprecationSpec3(nib.TraitedSpec):
+        foo = nib.traits.Int(deprecated='1000', new_name='bar')
+        bar = nib.traits.Int()
+    spec_instance = DeprecationSpec3()
+    not_raised = True
+    try:
+        spec_instance.foo = 1
+    except nib.TraitError:
+        not_raised = False
+    yield assert_true, not_raised
 
 def checknose():
     """check version of nose for known incompatability"""