Emit warnings to encourage cliff FormattableColumn

cliff has a concept of FormattableColumn which allows CLI implementors
to convert data into human-readable format only when a human-readable
format is requested and keep data unconverted for manchine-readable
formats like JSON or YAML.

Deprecation warnings is now emitted in favor of using FormattableColumn.

Partially implement blueprint osc-formattable-columns
Change-Id: Ia55bc950ecfc666d4a957507beab98eef74390aa
Related-Bug: #1687955

osc_lib/tests/test_utils.py

@@ -393,6 +393,42 @@ class TestUtils(test_utils.TestCase):
         self.assertIn('name', results)
         self.assertIn('size', results)
 
+    def _test_get_item_properties_with_formatter(self, formatters):
+        names = ('id', 'attr')
+        item = fakes.FakeResource(info={'id': 'fake-id', 'attr': ['a', 'b']})
+        res_id, res_attr = utils.get_item_properties(item, names,
+                                                     formatters=formatters)
+        self.assertEqual('fake-id', res_id)
+        return res_attr
+
+    def test_get_item_properties_with_format_func(self):
+        formatters = {'attr': utils.format_list}
+        res_attr = self._test_get_item_properties_with_formatter(formatters)
+        self.assertEqual(utils.format_list(['a', 'b']), res_attr)
+
+    def test_get_item_properties_with_formattable_column(self):
+        formatters = {'attr': format_columns.ListColumn}
+        res_attr = self._test_get_item_properties_with_formatter(formatters)
+        self.assertIsInstance(res_attr, format_columns.ListColumn)
+
+    def _test_get_dict_properties_with_formatter(self, formatters):
+        names = ('id', 'attr')
+        item = {'id': 'fake-id', 'attr': ['a', 'b']}
+        res_id, res_attr = utils.get_dict_properties(item, names,
+                                                     formatters=formatters)
+        self.assertEqual('fake-id', res_id)
+        return res_attr
+
+    def test_get_dict_properties_with_format_func(self):
+        formatters = {'attr': utils.format_list}
+        res_attr = self._test_get_dict_properties_with_formatter(formatters)
+        self.assertEqual(utils.format_list(['a', 'b']), res_attr)
+
+    def test_get_dict_properties_with_formattable_column(self):
+        formatters = {'attr': format_columns.ListColumn}
+        res_attr = self._test_get_dict_properties_with_formatter(formatters)
+        self.assertIsInstance(res_attr, format_columns.ListColumn)
+
 
 class NoUniqueMatch(Exception):
     pass

osc_lib/utils.py

@@ -21,7 +21,9 @@ import logging
 import os
 import six
 import time
+import warnings
 
+from cliff import columns as cliff_columns
 from oslo_utils import importutils
 
 from osc_lib import exceptions
@@ -393,10 +395,19 @@ def get_dict_properties(item, fields, mixed_case_fields=None, formatters=None):
         else:
             field_name = field.lower().replace(' ', '_')
         data = item[field_name] if field_name in item else ''
-        if field in formatters and data is not None:
-            row.append(formatters[field](data))
-        else:
-            row.append(data)
+        if field in formatters:
+            formatter = formatters[field]
+            if issubclass(formatter, cliff_columns.FormattableColumn):
+                data = formatter(data)
+            else:
+                warnings.warn(
+                    'The usage of formatter functions is now discouraged. '
+                    'Consider using cliff.columns.FormattableColumn instead. '
+                    'See reviews linked with bug 1687955 for more detail.',
+                    category=DeprecationWarning)
+                if data is not None:
+                    data = formatter(data)
+        row.append(data)
     return tuple(row)
 
 
@@ -446,10 +457,19 @@ def get_item_properties(item, fields, mixed_case_fields=None, formatters=None):
         else:
             field_name = field.lower().replace(' ', '_')
         data = getattr(item, field_name, '')
-        if field in formatters and data is not None:
-            row.append(formatters[field](data))
-        else:
-            row.append(data)
+        if field in formatters:
+            formatter = formatters[field]
+            if issubclass(formatter, cliff_columns.FormattableColumn):
+                data = formatter(data)
+            else:
+                warnings.warn(
+                    'The usage of formatter functions is now discouraged. '
+                    'Consider using cliff.columns.FormattableColumn instead. '
+                    'See reviews linked with bug 1687955 for more detail.',
+                    category=DeprecationWarning)
+                if data is not None:
+                    data = formatter(data)
+        row.append(data)
     return tuple(row)