RF: replace numpy deprecation decorator with ours

Replace `np.deprecate_with_doc` with `deprecate_with_version`.

There are other deprecations around the code-base that could be
signalled with this decorator.

Author: matthew-brett

nibabel/gifti/gifti.py

@@ -23,6 +23,7 @@
 from ..nifti1 import data_type_codes, xform_codes, intent_codes
 from .util import (array_index_order_codes, gifti_encoding_codes,
                    gifti_endian_codes, KIND2FMT)
+from ..deprecated import deprecate_with_version
 
 # {en,de}codestring in deprecated in Python3, but
 # {en,de}codebytes not available in Python2.
@@ -47,7 +48,10 @@ def from_dict(klass, data_dict):
             meda.data.append(nv)
         return meda
 
-    @np.deprecate_with_doc("Use the metadata property instead.")
+    @deprecate_with_version(
+        'get_metadata method deprecated. '
+        "Use the metadata property instead."
+        '2.1', '4.0')
     def get_metadata(self):
         return self.metadata
 
@@ -156,7 +160,10 @@ def __init__(self, key=0, red=None, green=None, blue=None, alpha=None):
         self.blue = blue
         self.alpha = alpha
 
-    @np.deprecate_with_doc("Use the rgba property instead.")
+    @deprecate_with_version(
+        'get_rgba method deprecated. '
+        "Use the rgba property instead."
+        '2.1', '4.0')
     def get_rgba(self):
         return self.rgba
 
@@ -249,7 +256,9 @@ def print_summary(self):
         print('Affine Transformation Matrix: \n', self.xform)
 
 
-@np.deprecate_with_doc("This is an internal API that will be discontinued.")
+@deprecate_with_version(
+    "data_tag is an internal API that will be discontinued.",
+    '2.1', '4.0')
 def data_tag(dataarray, encoding, datatype, ordering):
     class DataTag(xml.XmlSerializable):
 
@@ -371,16 +380,20 @@ def num_dim(self):
 
     # Setter for backwards compatibility with pymvpa
     @num_dim.setter
+    @deprecate_with_version(
+        "num_dim will be read-only in future versions of nibabel",
+        '2.1', '4.0')
     def num_dim(self, value):
-        warnings.warn(
-            "num_dim will be read-only in future versions of nibabel",
-            DeprecationWarning, stacklevel=2)
         if value != len(self.dims):
             raise ValueError('num_dim value {0} != number of dimensions '
                              'len(self.dims) {1}'
                              .format(value, len(self.dims)))
 
     @classmethod
+    @deprecate_with_version(
+        'from_array method is deprecated. '
+        'Please use GiftiDataArray constructor instead.',
+        '2.1', '4.0')
     def from_array(klass,
                    darray,
                    intent="NIFTI_INTENT_NONE",
@@ -419,10 +432,6 @@ def from_array(klass,
         -------
         da : instance of our own class
         """
-        warnings.warn(
-            "Please use GiftiDataArray constructor instead of from_array "
-            "class method",
-            DeprecationWarning, stacklevel=2)
         return klass(data=darray,
                      intent=intent,
                      datatype=datatype,
@@ -463,7 +472,10 @@ def _to_xml_element(self):
 
         return data_array
 
-    @np.deprecate_with_doc("Use the to_xml() function instead.")
+    @deprecate_with_version(
+        'to_xml_open method deprecated. '
+        'Use the to_xml() function instead.',
+        '2.1', '4.0')
     def to_xml_open(self):
         out = """<DataArray Intent="%s"
 \tDataType="%s"
@@ -487,7 +499,10 @@ def to_xml_open(self):
                       self.ext_offset,
                       )
 
-    @np.deprecate_with_doc("Use the to_xml() function instead.")
+    @deprecate_with_version(
+        'to_xml_close method deprecated. '
+        'Use the to_xml() function instead.',
+        '2.1', '4.0')
     def to_xml_close(self):
         return "</DataArray>\n"
 
@@ -507,7 +522,10 @@ def print_summary(self):
             print('Coordinate System:')
             print(self.coordsys.print_summary())
 
-    @np.deprecate_with_doc("Use the metadata property instead.")
+    @deprecate_with_version(
+        'get_metadata method deprecated. '
+        "Use the metadata property instead."
+        '2.1', '4.0')
     def get_metadata(self):
         return self.meta.metadata
 
@@ -591,11 +609,17 @@ def labeltable(self, labeltable):
             raise TypeError("Not a valid GiftiLabelTable instance")
         self._labeltable = labeltable
 
-    @np.deprecate_with_doc("Use the gifti_img.labeltable property instead.")
+    @deprecate_with_version(
+        'set_labeltable method deprecated. '
+        "Use the gifti_img.labeltable property instead.",
+        '2.1', '4.0')
     def set_labeltable(self, labeltable):
         self.labeltable = labeltable
 
-    @np.deprecate_with_doc("Use the gifti_img.labeltable property instead.")
+    @deprecate_with_version(
+        'get_labeltable method deprecated. '
+        "Use the gifti_img.labeltable property instead.",
+        '2.1', '4.0')
     def get_labeltable(self):
         return self.labeltable
 
@@ -615,11 +639,17 @@ def meta(self, meta):
             raise TypeError("Not a valid GiftiMetaData instance")
         self._meta = meta
 
-    @np.deprecate_with_doc("Use the gifti_img.labeltable property instead.")
+    @deprecate_with_version(
+        'set_meta method deprecated. '
+        "Use the gifti_img.meta property instead.",
+        '2.1', '4.0')
     def set_metadata(self, meta):
         self.meta = meta
 
-    @np.deprecate_with_doc("Use the gifti_img.labeltable property instead.")
+    @deprecate_with_version(
+        'get_meta method deprecated. '
+        "Use the gifti_img.meta property instead.",
+        '2.1', '4.0')
     def get_meta(self):
         return self.meta
 
@@ -651,7 +681,10 @@ def get_arrays_from_intent(self, intent):
         it = intent_codes.code[intent]
         return [x for x in self.darrays if x.intent == it]
 
-    @np.deprecate_with_doc("Use get_arrays_from_intent instead.")
+    @deprecate_with_version(
+        'getArraysFromIntent method deprecated. '
+        "Use get_arrays_from_intent instead.",
+        '2.1', '4.0')
     def getArraysFromIntent(self, intent):
         return self.get_arrays_from_intent(intent)
 

nibabel/gifti/giftiio.py

@@ -10,10 +10,12 @@
 # Stephan Gerhard, Oktober 2010
 ##############
 
-import numpy as np
+from ..deprecated import deprecate_with_version
 
 
-@np.deprecate_with_doc("Use nibabel.load() instead.")
+@deprecate_with_version('giftiio.read function deprecated. '
+                        "Use nibabel.load() instead.",
+                        '2.1', '4.0')
 def read(filename):
     """ Load a Gifti image from a file
 
@@ -31,7 +33,9 @@ def read(filename):
     return load(filename)
 
 
-@np.deprecate_with_doc("Use nibabel.save() instead.")
+@deprecate_with_version('giftiio.write function deprecated. '
+                        "Use nibabel.load() instead.",
+                        '2.1', '4.0')
 def write(image, filename):
     """ Save the current image to a new file
 

nibabel/gifti/parse_gifti_fast.py

@@ -24,6 +24,7 @@
                    gifti_endian_codes)
 from ..nifti1 import data_type_codes, xform_codes, intent_codes
 from ..xmlutils import XmlParser
+from ..deprecated import deprecate_with_version
 
 
 class GiftiParseError(ExpatError):
@@ -342,7 +343,9 @@ def pending_data(self):
 
 class Outputter(GiftiImageParser):
 
-    @np.deprecate_with_doc("Use GiftiImageParser instead.")
+    @deprecate_with_version('Outputter class deprecated. '
+                            "Use GiftiImageParser instead.",
+                            '2.1', '4.0')
     def __init__(self):
         super(Outputter, self).__init__()
 
@@ -351,6 +354,8 @@ def initialize(self):
         self.__init__()
 
 
-@np.deprecate_with_doc("Use GiftiImageParser.parse() instead.")
+@deprecate_with_version('parse_gifti_file deprecated. '
+                        "Use GiftiImageParser.parse() instead.",
+                        '2.1', '4.0')
 def parse_gifti_file(fname=None, fptr=None, buffer_size=None):
     GiftiImageParser(buffer_size=buffer_size).parse(fname=fname, fptr=fptr)

nibabel/gifti/tests/test_gifti.py

@@ -206,17 +206,29 @@ def test_labeltable():
     img.labeltable = new_table
     assert_equal(len(img.labeltable.labels), 2)
 
+    # Test deprecations
+    with clear_and_catch_warnings() as w:
+        warnings.filterwarnings('always', category=DeprecationWarning)
+        newer_table = GiftiLabelTable()
+        newer_table.labels += ['test', 'me', 'again']
+        img.set_labeltable(newer_table)
+        assert_equal(len(w), 1)
+        assert_equal(len(img.get_labeltable().labels), 3)
+        assert_equal(len(w), 2)
+
 
 def test_metadata():
     nvpair = GiftiNVPairs('key', 'value')
-    da = GiftiMetaData(nvpair=nvpair)
-    assert_equal(da.data[0].name, 'key')
-    assert_equal(da.data[0].value, 'value')
+    md = GiftiMetaData(nvpair=nvpair)
+    assert_equal(md.data[0].name, 'key')
+    assert_equal(md.data[0].value, 'value')
     # Test deprecation
     with clear_and_catch_warnings() as w:
         warnings.filterwarnings('always', category=DeprecationWarning)
-        assert_equal(len(GiftiDataArray().get_metadata()), 0)
+        assert_equal(md.get_metadata(), dict(key='value'))
         assert_equal(len(w), 1)
+        assert_equal(len(GiftiDataArray().get_metadata()), 0)
+        assert_equal(len(w), 2)
 
 
 def test_gifti_label_rgba():

nibabel/gifti/tests/test_giftiio.py

@@ -11,7 +11,8 @@
 
 from nose.tools import (assert_true, assert_false, assert_equal,
                         assert_raises)
-from ...testing import clear_and_catch_warnings
+from nibabel.testing import clear_and_catch_warnings
+from nibabel.tmpdirs import InTemporaryDirectory
 
 
 from .test_parse_gifti_fast import (DATA_FILE1, DATA_FILE2, DATA_FILE3,
@@ -29,7 +30,10 @@ def setUp(self):
 def test_read_deprecated():
     with clear_and_catch_warnings() as w:
         warnings.simplefilter('always', DeprecationWarning)
-        from nibabel.gifti.giftiio import read
+        from nibabel.gifti.giftiio import read, write
 
-        read(DATA_FILE1)
+        img = read(DATA_FILE1)
         assert_equal(len(w), 1)
+        with InTemporaryDirectory():
+            write(img, 'test.gii')
+        assert_equal(len(w), 2)

nibabel/loadsave.py

@@ -11,14 +11,14 @@
 
 import os.path as op
 import numpy as np
-import warnings
 
 from .filename_parser import splitext_addext
 from .openers import ImageOpener
 from .filebasedimages import ImageFileError
 from .imageclasses import all_image_classes
 from .arrayproxy import is_proxy
 from .py3k import FileNotFoundError
+from .deprecated import deprecate_with_version
 
 
 def load(filename, **kwargs):
@@ -48,7 +48,9 @@ def load(filename, **kwargs):
                          filename)
 
 
-@np.deprecate
+@deprecate_with_version('guessed_image_type deprecated.'
+                        '2.1',
+                        '4.0')
 def guessed_image_type(filename):
     """ Guess image type from file `filename`
 
@@ -62,8 +64,6 @@ def guessed_image_type(filename):
     image_class : class
         Class corresponding to guessed image type
     """
-    warnings.warn('guessed_image_type is deprecated', DeprecationWarning,
-                  stacklevel=2)
     sniff = None
     for image_klass in all_image_classes:
         is_valid, sniff = image_klass.path_maybe_image(filename, sniff)
@@ -124,8 +124,10 @@ def save(img, filename):
     converted.to_filename(filename)
 
 
-@np.deprecate_with_doc('Please use ``img.dataobj.get_unscaled()`` '
-                       'instead')
+@deprecate_with_version('read_img_data deprecated.'
+                        'Please use ``img.dataobj.get_unscaled()`` instead.'
+                        '2.0.1',
+                        '4.0')
 def read_img_data(img, prefer='scaled'):
     """ Read data from image associated with files
 
@@ -210,7 +212,9 @@ def read_img_data(img, prefer='scaled'):
         return hdr.raw_data_from_fileobj(fileobj)
 
 
-@np.deprecate
+@deprecate_with_version('which_analyze_type deprecated.'
+                        '2.1',
+                        '4.0')
 def which_analyze_type(binaryblock):
     """ Is `binaryblock` from NIfTI1, NIfTI2 or Analyze header?
 
@@ -238,8 +242,6 @@ def which_analyze_type(binaryblock):
     * if ``sizeof_hdr`` is 348 or byteswapped 348 assume Analyze
     * Return None
     """
-    warnings.warn('which_analyze_type is deprecated', DeprecationWarning,
-                  stacklevel=2)
     from .nifti1 import header_dtype
     hdr_struct = np.ndarray(shape=(), dtype=header_dtype, buffer=binaryblock)
     bs_hdr_struct = hdr_struct.byteswap()

nibabel/orientations.py

@@ -13,6 +13,8 @@
 import numpy as np
 import numpy.linalg as npl
 
+from .deprecated import deprecate_with_version
+
 
 class OrientationError(Exception):
     pass
@@ -228,7 +230,10 @@ def inv_ornt_aff(ornt, shape):
     return np.dot(undo_flip, undo_reorder)
 
 
-@np.deprecate_with_doc("Please use inv_ornt_aff instead")
+@deprecate_with_version('orientation_affine deprecated. '
+                        'Please use inv_ornt_aff instead'
+                        '1.3',
+                        '3.0')
 def orientation_affine(ornt, shape):
     return inv_ornt_aff(ornt, shape)