Added find method. #23

README.md

@@ -160,6 +160,7 @@ lng = loc.get_decimal('longitude')
     -   [`clone`](#clone)
     -   [`dump`](#dump)
     -   [`filter`](#filter)
+    -   [`find`](#find)
     -   [`flatten`](#flatten)
     -   [`groupby`](#groupby)
     -   [`invert`](#invert)
@@ -265,6 +266,15 @@ predicate = lambda k, v: v is not None
 f = d.filter(predicate)
 ```
 
+-   #### find
+
+```python
+# Return the first match searching for the given keys/keypaths.
+# If no result found, default value is returned.
+keys = ['a.b.c', 'm.n.o', 'x.y.z']
+f = d.find(keys, default=0)
+```
+
 -   #### flatten
 
 ```python

benedict/core/__init__.py

@@ -4,6 +4,7 @@ from benedict.core.clean import clean
 from benedict.core.clone import clone
 from benedict.core.dump import dump
 from benedict.core.filter import filter
+from benedict.core.find import find
 from benedict.core.flatten import flatten
 from benedict.core.groupby import groupby
 from benedict.core.invert import invert

benedict/core/find.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+
+
+def find(d, keys, default=None):
+    for key in keys:
+        if key in d:
+            return d.get(key, default)
+    return default

benedict/dicts/__init__.py

@@ -4,6 +4,7 @@ from benedict.core import clean as _clean
 from benedict.core import clone as _clone
 from benedict.core import dump as _dump
 from benedict.core import filter as _filter
+from benedict.core import find as _find
 from benedict.core import flatten as _flatten
 from benedict.core import groupby as _groupby
 from benedict.core import invert as _invert
@@ -86,6 +87,13 @@ class benedict(KeypathDict, IODict, ParseDict):
         """
         return _filter(self, predicate)
 
+    def find(self, keys, default=None):
+        """
+        Return the first match searching for the given keys.
+        If no result found, default value is returned.
+        """
+        return _find(self, keys, default)
+
     def flatten(self, separator='_'):
         """
         Return a new flattened dict using the given separator

tests/core/test_find.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+
+from benedict.core import find as _find
+
+import unittest
+
+
+class find_test_case(unittest.TestCase):
+
+    def test_find_with_single_result(self):
+        i = {
+            'a': 1,
+            'b': 2,
+            'c': 3,
+            'd': None,
+        }
+        o = _find(i, ['x', 'y', 'b', 'z'], 5)
+        self.assertEqual(o, 2)
+
+    def test_find_with_multiple_results(self):
+        i = {
+            'a': 1,
+            'b': 2,
+            'c': 3,
+            'd': None,
+        }
+        o = _find(i, ['a', 'x', 'b', 'y'])
+        self.assertEqual(o, 1)
+
+    def test_find_with_no_result(self):
+        i = {
+            'a': 1,
+            'b': 2,
+            'c': 3,
+            'd': None,
+        }
+        o = _find(i, ['x', 'y', 'z'])
+        self.assertEqual(o, None)
+
+    def test_find_with_no_result_and_default(self):
+        i = {
+            'a': 1,
+            'b': 2,
+            'c': 3,
+            'd': None,
+        }
+        o = _find(i, ['x', 'y', 'z'], 5)
+        self.assertEqual(o, 5)

tests/dicts/test_benedict.py

@@ -368,6 +368,21 @@ class benedict_test_case(unittest.TestCase):
         self.assertEqual(f, r)
         self.assertTrue(isinstance(f, benedict))
 
+    def test_filter(self):
+        d = {
+            'a': 1,
+            'b': 2,
+            'c': {
+                'd': {
+                    'e': 3,
+                    'f': 4,
+                }
+            },
+        }
+        b = benedict(d)
+        r = b.find(['x.y.z', 'a.b.c', 'c.d.e'])
+        self.assertEqual(r, 3)
+
     def test_flatten(self):
         d = {
             'a': 1,