Create dictutils and add 'flatten_dict_to_keypairs'

This function has been shared at least kwapi and all Telemetry projects
including ceilometer, aodh, panko and gnocchi. As a generator, it produces
sequence of keypairs for nested dictionaries. It seems to be good moving it
to the common shared code.

So add an initial dictutils and tests for it.

Change-Id: Ibd7c2ce4ef9c2608910b26169a804eb463759c7f

doc/source/api/dictutils.rst

@@ -0,0 +1,6 @@
+===========
+ dictutils
+===========
+
+.. automodule:: oslo_utils.dictutils
+   :members:

doc/source/index.rst

@@ -18,6 +18,7 @@ API Documentation
 .. toctree::
    :maxdepth: 2
 
+   api/dictutils
    api/encodeutils
    api/eventletutils
    api/excutils

oslo_utils/dictutils.py

@@ -0,0 +1,31 @@
+# Copyright (c) 2016 EasyStack Inc.
+# All Rights Reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+import six
+
+
+def flatten_dict_to_keypairs(d, separator=':'):
+    """Generator that produces sequence of keypairs for nested dictionaries.
+
+    :param d: dictionaries which may be nested
+    :param separator: symbol between names
+    """
+    for name, value in sorted(six.iteritems(d)):
+        if isinstance(value, dict):
+            for subname, subvalue in flatten_dict_to_keypairs(value,
+                                                              separator):
+                yield ('%s%s%s' % (name, separator, subname), subvalue)
+        else:
+            yield name, value

oslo_utils/tests/test_dictutils.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2016 EasyStack Inc.
+# All Rights Reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+
+from oslotest import base as test_base
+
+from oslo_utils import dictutils as du
+
+
+class DictUtilsTestCase(test_base.BaseTestCase):
+
+    def test_flatten_dict_to_keypairs(self):
+        data = {'a': 'A', 'b': 'B',
+                'nested': {'a': 'A', 'b': 'B'}}
+        pairs = list(du.flatten_dict_to_keypairs(data))
+        self.assertEqual([('a', 'A'), ('b', 'B'),
+                          ('nested:a', 'A'), ('nested:b', 'B')],
+                         pairs)
+
+    def test_flatten_dict_to_keypairs_with_separator(self):
+        data = {'a': 'A', 'b': 'B',
+                'nested': {'a': 'A', 'b': 'B'}}
+        pairs = list(du.flatten_dict_to_keypairs(data, separator='.'))
+        self.assertEqual([('a', 'A'), ('b', 'B'),
+                          ('nested.a', 'A'), ('nested.b', 'B')],
+                         pairs)