Add assert_dict_superset()

Closes: #19

Author: srittau

NEWS.rst

@@ -5,6 +5,7 @@ API Additions
 -------------
 
 * Add ``assert_dict_equal()``.
+* Add ``assert_dict_superset()``.
 
 Improvements
 ------------

asserts/__init__.py

@@ -357,6 +357,62 @@ def assert_dict_equal(first, second, key_msg_fmt="{msg}",
         assert_equal(first_value, second_value, msg_fmt=msg)
 
 
+def assert_dict_superset(first, second, key_msg_fmt="{msg}",
+                         value_msg_fmt="{msg}"):
+    """Fail unless second dictionary is a superset of the first.
+
+    The second dictionary must contain all keys of the first and their
+    values are equal (or a superset in case of dicts). But the second
+    dictionary can contain additional keys.
+
+    >>> assert_equal({"foo": 5}, {"foo": 5, "bar": 10})
+    >>> assert_equal({"foo": 5}, {})
+    Traceback (most recent call last):
+        ...
+    AssertionError: key 'foo' missing from right dict
+
+    The following key_msg_fmt arguments are supported, if the keys do not
+    match:
+    * msg - the default error message
+    * first - the first dict
+    * second - the second dict
+    * missing_keys - list of keys missing from right
+
+    The following value_msg_fmt arguments are supported, if a value does not
+    match:
+    * msg - the default error message
+    * first - the first dict
+    * second - the second dict
+    * key - the key where the value does not match
+    * first_value - the value in the first dict
+    * second_value - the value in the second dict
+    """
+    first_keys = set(first.keys())
+    second_keys = set(second.keys())
+    missing_keys = list(first_keys - second_keys)
+    if missing_keys:
+        if len(missing_keys) == 1:
+            msg = "key {!r} missing from right dict".format(missing_keys[0])
+        else:
+            keys = ", ".join(sorted(repr(k) for k in missing_keys))
+            msg = "keys {} missing from right dict".format(keys)
+        if key_msg_fmt:
+            msg = key_msg_fmt.format(
+                msg=msg, first=first, second=second, missing_keys=missing_keys)
+        raise AssertionError(msg)
+    for key in first:
+        first_value = first[key]
+        second_value = second[key]
+        msg = "key '{}' differs: {!r} != {!r}".format(
+            key, first_value, second_value)
+        if value_msg_fmt:
+            msg = value_msg_fmt.format(
+                msg=msg, first=first, second=second,
+                key=key, first_value=first_value, second_value=second_value)
+        msg = msg.replace("{", "{{").replace("}", "}}")
+        assert_equal(first_value, second_value, msg_fmt=msg)
+
+
 def assert_less(first, second, msg_fmt="{msg}"):
     """Fail if first is not less than second.
 

asserts/__init__.pyi

@@ -47,6 +47,7 @@ def assert_not_equal(first: Any, second: Any, msg_fmt: Text = ...) -> None: ...
 def assert_almost_equal(first: float, second: float, msg_fmt: Text = ..., places: int = ..., delta: float = ...) -> None: ...
 def assert_not_almost_equal(first: float, second: float, msg_fmt: Text = ..., places: int = ..., delta: float = ...) -> None: ...
 def assert_dict_equal(first: dict, second: dict, key_msg_fmt: Text = ..., value_msg_fmt: Text = ...) -> None: ...
+def assert_dict_superset(first: dict, second: dict, key_msg_fmt: Text = ..., value_msg_fmt: Text = ...) -> None: ...
 def assert_less(first: Any, second: Any, msg_fmt: Text = ...) -> None: ...
 def assert_less_equal(first: Any, second: Any, msg_fmt: Text = ...) -> None: ...
 def assert_greater(first: Any, second: Any, msg_fmt: Text = ...) -> None: ...

test_asserts.py

@@ -16,6 +16,8 @@
     assert_not_equal,
     assert_almost_equal,
     assert_not_almost_equal,
+    assert_dict_equal,
+    assert_dict_superset,
     assert_less,
     assert_less_equal,
     assert_greater,
@@ -37,7 +39,8 @@
     assert_raises_errno,
     assert_succeeds,
     assert_warns,
-    assert_warns_regex, assert_dict_equal)
+    assert_warns_regex,
+)
 
 
 class _DummyObject(object):
@@ -437,6 +440,61 @@ def test_assert_dict_equal__custom_value_message(self):
                               "{key!r};{first_value};{second_value}"
             )
 
+    # assert_dict_superset()
+
+    def test_assert_dict_superset__empty_dicts(self):
+        assert_dict_superset({}, {})
+
+    def test_assert_dict_superset__dicts_are_equal(self):
+        assert_dict_superset({"foo": 5}, {"foo": 5})
+
+    def test_assert_dict_superset__dicts_is_superset(self):
+        assert_dict_superset({"foo": 5}, {"foo": 5, "bar": 10})
+
+    def test_assert_dict_superset__one_key_missing_from_right(self):
+        with _assert_raises_assertion("key 'foo' missing from right dict"):
+            assert_dict_superset({"bar": 10, "foo": 5}, {"bar": 10})
+
+    def test_assert_dict_superset__multiple_keys_missing_from_right(self):
+        with _assert_raises_assertion(
+                "keys 'bar', 'foo' missing from right dict"):
+            assert_dict_superset({"foo": 5, "bar": 10, "baz": 15}, {"baz": 15})
+
+    def test_assert_dict_superset__values_do_not_match(self):
+        with _assert_raises_assertion("key 'foo' differs: 15 != 10"):
+            assert_dict_superset({"foo": 15}, {"foo": 10, "bar": 15})
+
+    def test_assert_dict_superset__not_string_keys(self):
+        with _assert_raises_assertion("key 10 missing from right dict"):
+            assert_dict_superset({10: "foo"}, {})
+        with _assert_raises_assertion(
+                "keys 'foo', 5 missing from right dict"):
+            assert_dict_superset({5: "", "foo": ""}, {})
+
+    def test_assert_dict_superset__message_precedence(self):
+        with _assert_raises_assertion("key 'foo' missing from right dict"):
+            assert_dict_superset({"foo": "", "bar": 5}, {"bar": 1})
+
+    def test_assert_dict_superset__custom_key_message(self):
+        with _assert_raises_assertion(
+                "key 'foo' missing from right dict;"
+                "{'foo': ''};{'bar': ''};['foo']"):
+            assert_dict_superset(
+                {"foo": ""}, {"bar": ""},
+                key_msg_fmt="{msg};{first!r};{second!r};"
+                            "{missing_keys!r}"
+            )
+
+    def test_assert_dict_superset__custom_value_message(self):
+        with _assert_raises_assertion(
+                "key 'foo' differs: 5 != 10;{'foo': 5};{'foo': 10};"
+                "'foo';5;10"):
+            assert_dict_superset(
+                {"foo": 5}, {"foo": 10},
+                value_msg_fmt="{msg};{first!r};{second!r};"
+                              "{key!r};{first_value};{second_value}"
+            )
+
     # assert_less()
 
     def test_assert_less(self):