Deprecate the human format on QemuImgInfo

``human`` format parsing introduced many issue in the past.

Each time qemu will update it's human format output we could be
impacted by their changes and it could introduce new issues on
oslo.utils.

Human format is a human readable format which need to be parsed by
regexes, in other words it's not really a format that machine can
consume natively.

Qemu introduced json output since version 1.3 [1] and this format is
machine readable, for the sake of stability on oslo.utils we decided to
drop the support of the human format and to use json as the unique and
only supported format.

We will reach our goal by following this scenario:
step 1: deprecate the human format
step 2: remove the human format and deprecate the format parameters
step 3: remove the parameter (json all the time)

These changes deprecate the ``human`` format (step 1)

[1] https://wiki.qemu.org/ChangeLog/1.3

Change-Id: Ia8d6cd08a8989395f9b0f9097d2e57757b8cb915

3 files changed, 37 insertions, 8 deletions

diff --git a/oslo_utils/imageutils.py b/oslo_utils/imageutils.py
index fc7b494..8a7fe6e 100644
--- a/oslo_utils/imageutils.py
+++ b/oslo_utils/imageutils.py
@@ -28,6 +28,8 @@ Helper methods to deal with images.
 import json
 import re
 
+import debtcollector
+
 from oslo_utils._i18n import _
 from oslo_utils import strutils
 
@@ -38,8 +40,11 @@ class QemuImgInfo(object):
     The instance of :class:`QemuImgInfo` has properties: `image`,
     `backing_file`, `file_format`, `virtual_size`, `cluster_size`,
     `disk_size`, `snapshots` and `encrypted`.
+
     The parameter format can be set to 'json' or 'human'. With 'json' format
     output, qemu image information will be parsed more easily and readable.
+    However 'human' format support will be dropped in next cycle and only
+    'json' format will be supported. Prefer to use 'json' instead of 'human'.
     """
     BACKING_FILE_RE = re.compile((r"^(.*?)\s*\(actual\s+path\s*:"
                                   r"\s+(.*?)\)\s*$"), re.I)
@@ -61,6 +66,11 @@ class QemuImgInfo(object):
             self.encrypted = details.get('encrypted')
             self.format_specific = details.get('format-specific')
         else:
+            debtcollector.deprecate(
+                'The human format is deprecated and the format parameter '
+                'will be removed. Use explicitly json instead',
+                version="xena",
+                category=FutureWarning)
             details = self._parse(cmd_output or '')
             self.image = details.get('image')
             self.backing_file = details.get('backing_file')
diff --git a/oslo_utils/tests/test_imageutils.py b/oslo_utils/tests/test_imageutils.py
index 6b3a9fa..63e0ee9 100644
--- a/oslo_utils/tests/test_imageutils.py
+++ b/oslo_utils/tests/test_imageutils.py
@@ -13,15 +13,19 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+import warnings
+
 from oslotest import base as test_base
 import testscenarios
 
 from oslo_utils import imageutils
 
+from unittest import mock
+
 load_tests = testscenarios.load_tests_apply_scenarios
 
 
-class ImageUtilsRawTestCase(test_base.BaseTestCase):
+class ImageUtilsHumanRawTestCase(test_base.BaseTestCase):
 
     _image_name = [
         ('disk_config', dict(image_name='disk.config')),
@@ -125,7 +129,8 @@ class ImageUtilsRawTestCase(test_base.BaseTestCase):
         if self.snapshot_count is not None:
             self.assertEqual(len(image_info.snapshots), self.snapshot_count)
 
-    def test_qemu_img_info(self):
+    @mock.patch('debtcollector.deprecate')
+    def test_qemu_img_info_human_format(self, mock_deprecate):
         img_info = self._initialize_img_info()
         if self.garbage_before_snapshot is True:
             img_info = img_info + ('blah BLAH: bb',)
@@ -134,14 +139,16 @@ class ImageUtilsRawTestCase(test_base.BaseTestCase):
         if self.garbage_before_snapshot is False:
             img_info = img_info + ('junk stuff: bbb',)
         example_output = '\n'.join(img_info)
+        warnings.simplefilter("always", FutureWarning)
         image_info = imageutils.QemuImgInfo(example_output)
+        mock_deprecate.assert_called()
         self._base_validation(image_info)
 
 
-ImageUtilsRawTestCase.generate_scenarios()
+ImageUtilsHumanRawTestCase.generate_scenarios()
 
 
-class ImageUtilsQemuTestCase(ImageUtilsRawTestCase):
+class ImageUtilsHumanQemuTestCase(ImageUtilsHumanRawTestCase):
 
     _file_format = [
         ('qcow2', dict(file_format='qcow2')),
@@ -180,7 +187,8 @@ class ImageUtilsQemuTestCase(ImageUtilsRawTestCase):
             cls._qcow2_encrypted,
             cls._qcow2_backing_file)
 
-    def test_qemu_img_info(self):
+    @mock.patch("debtcollector.deprecate")
+    def test_qemu_img_info_human_format(self, mock_deprecate):
         img_info = self._initialize_img_info()
         img_info = img_info + ('cluster_size: %s' % self.cluster_size,)
         if self.backing_file is not None:
@@ -195,7 +203,9 @@ class ImageUtilsQemuTestCase(ImageUtilsRawTestCase):
         if self.garbage_before_snapshot is False:
             img_info = img_info + ('junk stuff: bbb',)
         example_output = '\n'.join(img_info)
+        warnings.simplefilter("always", FutureWarning)
         image_info = imageutils.QemuImgInfo(example_output)
+        mock_deprecate.assert_called()
         self._base_validation(image_info)
         self.assertEqual(image_info.cluster_size, self.exp_cluster_size)
         if self.backing_file is not None:
@@ -205,7 +215,7 @@ class ImageUtilsQemuTestCase(ImageUtilsRawTestCase):
             self.assertEqual(image_info.encrypted, self.encrypted)
 
 
-ImageUtilsQemuTestCase.generate_scenarios()
+ImageUtilsHumanQemuTestCase.generate_scenarios()
 
 
 class ImageUtilsBlankTestCase(test_base.BaseTestCase):
@@ -220,7 +230,8 @@ class ImageUtilsBlankTestCase(test_base.BaseTestCase):
 
 
 class ImageUtilsJSONTestCase(test_base.BaseTestCase):
-    def test_qemu_img_info_json_format(self):
+    @mock.patch("debtcollector.deprecate")
+    def test_qemu_img_info(self, mock_deprecate):
         img_output = '''{
                        "virtual-size": 41126400,
                        "filename": "fake_img",
@@ -230,6 +241,7 @@ class ImageUtilsJSONTestCase(test_base.BaseTestCase):
                        "format-specific": {"data": {"foo": "bar"}}
                       }'''
         image_info = imageutils.QemuImgInfo(img_output, format='json')
+        mock_deprecate.assert_not_called()
         self.assertEqual(41126400, image_info.virtual_size)
         self.assertEqual('fake_img', image_info.image)
         self.assertEqual(65536, image_info.cluster_size)
@@ -237,9 +249,11 @@ class ImageUtilsJSONTestCase(test_base.BaseTestCase):
         self.assertEqual(13168640, image_info.disk_size)
         self.assertEqual("bar", image_info.format_specific["data"]["foo"])
 
-    def test_qemu_img_info_json_format_blank(self):
+    @mock.patch("debtcollector.deprecate")
+    def test_qemu_img_info_blank(self, mock_deprecate):
         img_output = '{}'
         image_info = imageutils.QemuImgInfo(img_output, format='json')
+        mock_deprecate.assert_not_called()
         self.assertIsNone(image_info.virtual_size)
         self.assertIsNone(image_info.image)
         self.assertIsNone(image_info.cluster_size)
diff --git a/releasenotes/notes/drop-imageutils-human-format-support-a89101a36c4dd3cb.yaml b/releasenotes/notes/drop-imageutils-human-format-support-a89101a36c4dd3cb.yaml
new file mode 100644
index 0000000..16b56e5
--- /dev/null
+++ b/releasenotes/notes/drop-imageutils-human-format-support-a89101a36c4dd3cb.yaml
@@ -0,0 +1,5 @@
+---
+deprecations:
+  - |
+    Support for parsing the ``human`` format has been deprecated and will
+    be removed in a future release.