add deprecation warnings (#705)

address review comments

update the warning message in the decorator to work with classes

coremltools/converters/caffe/_caffe_converter.py

@@ -178,7 +178,7 @@ def convert(model, image_input_names=[], is_bgr=False,
 
     """
     from ...models import MLModel
-    from ...models.utils import convert_neural_network_weights_to_fp16 as convert_neural_network_weights_to_fp16
+    from ...models.utils import _convert_neural_network_weights_to_fp16
 
     if model_precision not in _VALID_MLMODEL_PRECISION_TYPES:
         raise RuntimeError('Model precision {} is not valid'.format(model_precision))
@@ -197,7 +197,7 @@ def convert(model, image_input_names=[], is_bgr=False,
         pass
 
     if model_precision == _MLMODEL_HALF_PRECISION and model is not None:
-        model = convert_neural_network_weights_to_fp16(model)
+        model = _convert_neural_network_weights_to_fp16(model)
 
     return model
 

coremltools/converters/keras/_keras_converter.py

@@ -11,8 +11,7 @@
 from ...models import datatypes
 from ...models import MLModel as _MLModel
 from ...models import _MLMODEL_FULL_PRECISION, _MLMODEL_HALF_PRECISION, _VALID_MLMODEL_PRECISION_TYPES
-from ...models.utils import convert_neural_network_weights_to_fp16 as convert_neural_network_weights_to_fp16
-from ...models.utils import convert_neural_network_spec_weights_to_fp16 as convert_neural_network_spec_weights_to_fp16
+from ...models.utils import _convert_neural_network_spec_weights_to_fp16
 
 from ..._deps import HAS_KERAS_TF as _HAS_KERAS_TF
 from ..._deps import HAS_KERAS2_TF as _HAS_KERAS2_TF
@@ -588,7 +587,7 @@ def convertToSpec(model,
             'Keras not found or unsupported version or backend found. keras conversion API is disabled.')
 
     if model_precision == _MLMODEL_HALF_PRECISION and model is not None:
-        spec = convert_neural_network_spec_weights_to_fp16(spec)
+        spec = _convert_neural_network_spec_weights_to_fp16(spec)
 
     return spec
 

coremltools/models/_deprecation.py

@@ -0,0 +1,26 @@
+import warnings
+import functools
+
+def deprecated(obj=None, suffix=""):
+    '''
+    Decorator to mark a function or a class as deprecated
+    '''
+
+    def decorator_deprecation_warning(obj):
+        @functools.wraps(obj)
+        def wrapped(*args, **kwargs):
+            if isinstance(obj, type):
+                msg = "Class \"%s\" is deprecated and will be removed in the next release" % obj.__name__
+            else:
+                msg = "Function \"%s\" is deprecated and will be removed in the next release" % obj.__name__
+            if suffix:
+                msg += "; %s" % suffix
+            warnings.warn(msg, category=FutureWarning)
+            return obj(*args, **kwargs)
+        return wrapped
+
+    if obj is None:
+        return decorator_deprecation_warning
+
+    return decorator_deprecation_warning(obj)
+

coremltools/models/model.py

@@ -16,6 +16,7 @@
 from .utils import macos_version as _macos_version
 from .utils import save_spec as _save_spec
 from ..proto import Model_pb2 as _Model_pb2
+from coremltools.models._deprecation import deprecated
 
 _MLMODEL_FULL_PRECISION = 'float32'
 _MLMODEL_HALF_PRECISION = 'float16'
@@ -113,7 +114,7 @@ def _get_proxy_and_spec(filename, use_cpu_only=False):
 
     return None, specification
 
-
+@deprecated
 class NeuralNetworkShaper(object):
     """
     This class computes the intermediate tensor shapes for a neural network model.
@@ -358,6 +359,7 @@ def predict(self, data, useCPUOnly=False, **kwargs):
             else:
                 raise Exception('Unable to load CoreML.framework. Cannot make predictions.')
 
+    @deprecated
     def visualize_spec(self, port=None, input_shape_dict=None, title='CoreML Graph Visualization'):
         """
         Visualize the model.

coremltools/models/neural_network/builder.py

@@ -862,7 +862,7 @@ def inspect_layers(self, last=-1, verbose=False):
         for i, alayer in enumerate(self.nn_spec.layers[::-1]):
             if i >= last:
                 break
-            layer_type, name, in_blobs, out_blobs, params_info = summarize_network_layer_info(alayer)
+            layer_type, name, in_blobs, out_blobs, params_info = _summarize_network_layer_info(alayer)
             print('[Id: {}], Name: {} (Type: {})'.format(n_layers - i - 1, name, layer_type))
             print(' ' * 10 + 'Updatable: {}'.format(alayer.isUpdatable))
             print(' ' * 10 + 'Input blobs: {}'.format(in_blobs))
@@ -924,7 +924,7 @@ def inspect_updatable_layers(self):
         """
         for _, layer in enumerate(self.nn_spec.layers[::-1]):
             if layer.isUpdatable:
-                layer_type, name, in_blobs, out_blobs, _ = summarize_network_layer_info(layer)
+                layer_type, name, in_blobs, out_blobs, _ = _summarize_network_layer_info(layer)
                 print('Name: {} (Type: {})'.format(name, layer_type))
                 print(' ' * 10 + 'Input blobs: {}'.format(in_blobs))
                 print(' ' * 10 + 'Output blobs: {}'.format(out_blobs))

coremltools/models/neural_network/flexible_shape_utils.py

@@ -12,6 +12,7 @@
 from ... import _MINIMUM_FLEXIBLE_SHAPES_SPEC_VERSION
 from ... import _MINIMUM_NDARRAY_SPEC_VERSION
 from ..model import NeuralNetworkShaper
+from coremltools.models._deprecation import deprecated
 
 _SEQUENCE_KEY = 'S'
 _BATCH_KEY = 'B'
@@ -701,7 +702,7 @@ def add_multiarray_ndshape_enumeration(spec, feature_name, enumerated_shapes):
     spec.specificationVersion = max(_MINIMUM_NDARRAY_SPEC_VERSION,
                                     spec.specificationVersion)
 
-
+@deprecated
 def get_allowed_shape_ranges(spec):
     """
     For a given model specification, returns a dictionary with a shape range object for each input feature name.
@@ -717,7 +718,7 @@ def get_allowed_shape_ranges(spec):
     return output
 
 
-
+@deprecated
 def can_allow_multiple_input_shapes(spec):
     """
     Examines a model specification and determines if it can compute results for more than one output shape.

coremltools/models/neural_network/printer.py

@@ -3,16 +3,23 @@
 # Use of this source code is governed by a BSD-3-clause license that can be
 # found in the LICENSE.txt file or at https://opensource.org/licenses/BSD-3-Clause
 
-from .spec_inspection_utils import *
+from .spec_inspection_utils import _get_feature_description_summary, \
+                            _summarize_neural_network_spec_code_style, \
+                            _summarize_neural_network_spec
 
+from coremltools.models._deprecation import deprecated
 
+@deprecated
 def print_network_spec_parameter_info_style(mlmodel_spec, interface_only=False):
+    return _print_network_spec_parameter_info_style(mlmodel_spec, interface_only=interface_only)
+
+def _print_network_spec_parameter_info_style(mlmodel_spec, interface_only=False):
     """ Print the network information summary.
     Args:
     mlmodel_spec : the mlmodel spec
     interface_only : Shows only the input and output of the network
     """
-    inputs, outputs, layers_info = summarize_neural_network_spec(mlmodel_spec)
+    inputs, outputs, layers_info = _summarize_neural_network_spec(mlmodel_spec)
 
     print('Inputs:')
     for i in inputs:
@@ -41,16 +48,19 @@ def print_network_spec_parameter_info_style(mlmodel_spec, interface_only=False):
 
     print('\n')
 
-
+@deprecated
 def print_network_spec_coding_style(mlmodel_spec, interface_only=False):
+    return _print_network_spec_coding_style(mlmodel_spec, interface_only=interface_only)
+
+def _print_network_spec_coding_style(mlmodel_spec, interface_only=False):
     """
     Args:
     mlmodel_spec : the mlmodel spec
     interface_only : Shows only the input and output of the network
     """
 
-    inputs = [(blob.name, get_feature_description_summary(blob)) for blob in mlmodel_spec.description.input]
-    outputs = [(blob.name, get_feature_description_summary(blob)) for blob in mlmodel_spec.description.output]
+    inputs = [(blob.name, _get_feature_description_summary(blob)) for blob in mlmodel_spec.description.input]
+    outputs = [(blob.name, _get_feature_description_summary(blob)) for blob in mlmodel_spec.description.output]
 
     input_names = []
     print('Inputs:')
@@ -83,7 +93,7 @@ def print_network_spec_coding_style(mlmodel_spec, interface_only=False):
         return
 
     print('\n')
-    summarize_neural_network_spec_code_style(nn_spec, input_names=input_names, output_names=output_names)
+    _summarize_neural_network_spec_code_style(nn_spec, input_names=input_names, output_names=output_names)
 
 
 def print_network_spec(mlmodel_spec, interface_only=False, style=''):
@@ -95,6 +105,6 @@ def print_network_spec(mlmodel_spec, interface_only=False, style=''):
     """
 
     if style == 'coding':
-        print_network_spec_coding_style(mlmodel_spec, interface_only=interface_only)
+        _print_network_spec_coding_style(mlmodel_spec, interface_only=interface_only)
     else:
-        print_network_spec_parameter_info_style(mlmodel_spec, interface_only=interface_only)
+        _print_network_spec_parameter_info_style(mlmodel_spec, interface_only=interface_only)

coremltools/models/neural_network/quantization_utils.py

@@ -31,6 +31,8 @@
 from ... import (_MINIMUM_QUANTIZED_MODEL_SPEC_VERSION,
                  _MINIMUM_FP16_SPEC_VERSION)
 
+from coremltools.models._deprecation import deprecated
+
 
 class QuantizedLayerSelector(object):
     """ This is the base class to implement custom selectors to skip certain
@@ -752,7 +754,12 @@ def _lstmwp_to_fp16_lstmwp(lstm_wp, nbits, qm, i_size, o_size, has_peephole=True
             raise Exception('Unknown layer ' + layer_type + ' to be quantized')
 
 
+@deprecated(suffix="instead use 'quantize_weights'.")
 def quantize_spec_weights(spec, nbits, quantization_mode, **kwargs):
+    return _quantize_spec_weights(spec, nbits, quantization_mode, **kwargs)
+
+
+def _quantize_spec_weights(spec, nbits, quantization_mode, **kwargs):
 
     nn_model_types = ['neuralNetwork', 'neuralNetworkClassifier',
                       'neuralNetworkRegressor']
@@ -784,10 +791,10 @@ def quantize_spec_weights(spec, nbits, quantization_mode, **kwargs):
     # Recursively convert all pipeline models
     elif spec.WhichOneof('Type') == 'pipeline':
         for model_spec in spec.pipeline.models:
-            quantize_spec_weights(model_spec, nbits, quantization_mode, **kwargs)
+            _quantize_spec_weights(model_spec, nbits, quantization_mode, **kwargs)
 
     elif spec.WhichOneof('Type') in ['pipelineClassifier', 'pipelineRegressor']:
-        quantize_spec_weights(spec.pipeline, nbits, quantization_mode, **kwargs)
+        _quantize_spec_weights(spec.pipeline, nbits, quantization_mode, **kwargs)
 
     return spec
 
@@ -1149,7 +1156,7 @@ def quantize_weights(full_precision_model,
 
     print("Quantizing using {} quantization".format(quantization_mode))
     spec = full_precision_model.get_spec()
-    qspec = quantize_spec_weights(spec, nbits, qmode, **kwargs)
+    qspec = _quantize_spec_weights(spec, nbits, qmode, **kwargs)
 
     if macos_version() < (10, 14):
         print("WARNING! Unable to return a quantized MLModel instance since"