Add new-style JSON field presence checks

Add `Present` and `Absent` classes and deprecate `Exists`.

Author: srittau

CHANGELOG.md

@@ -7,11 +7,17 @@ python-asserts adheres to [semantic versioning](https://semver.org/).
 ### Added
 
 - Add support for Python 3.12.
+- Add `Present` and `Absent` for absence checks in `assert_json_subset()`.
 
 ### Removed
 
 - Drop support for Python 3.7.
 
+### Deprecated
+
+- Deprecate `Exists` in favor of `Present` and `Absent` in
+  `assert_json_subset()`.
+
 ## [0.12.0]
 
 ### Added

asserts/__init__.py

@@ -29,6 +29,8 @@
 from typing import Any, Callable, Set
 from warnings import WarningMessage, catch_warnings
 
+from typing_extensions import deprecated
+
 
 def fail(msg=None):
     """Raise an AssertionError with the given message.
@@ -1354,8 +1356,8 @@ def assert_json_subset(first, second):
     ...
     json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
 
-    In objects, the special name `Exists` can be used to check for the
-    existence or non-existence of a specific key:
+    In objects, the special classes `Present` and `Absent` can be used to
+    check for the presence or absence of a specific key:
 
     >>> assert_json_subset({Exists("foo"): True}, '{"foo": "bar"}')
     >>> assert_json_subset({Exists("foo"): True}, '{}')
@@ -1401,6 +1403,8 @@ def assert_(self):
             self._assert_dicts_equal()
         elif isinstance(self._expected, list):
             self._assert_arrays_equal()
+        elif _is_present(self._expected):
+            pass
         else:
             self._assert_fundamental_values_equal()
 
@@ -1413,6 +1417,8 @@ def _types_differ(self):
             return self._actual is not None
         elif isinstance(self._expected, (int, float)):
             return not isinstance(self._actual, (int, float))
+        elif _is_present(self._expected):
+            return False
         for type_ in [bool, str, _Str, list, dict]:
             if isinstance(self._expected, type_):
                 return not isinstance(self._actual, type_)
@@ -1436,24 +1442,29 @@ def _assert_all_expected_keys_in_actual_dict(self) -> None:
 
     def _assert_no_wrong_keys(self) -> None:
         for name in self._expected:
+            if isinstance(name, str) and _is_absent(self._expected[name]):
+                if name in self._actual:
+                    self._raise_assertion_error(
+                        f"spurious member '{name}' in object {{path}}"
+                    )
             if isinstance(name, Exists) and not self._expected[name]:
                 if name.member_name in self._actual:
                     self._raise_assertion_error(
-                        f"spurious member '{name.member_name}' in "
-                        f"object {{path}}"
+                        f"spurious member '{name.member_name}' in object {{path}}"
                     )
 
     def _assert_dict_values_equal(self) -> None:
         for name in self._expected:
-            if isinstance(name, str):
+            if isinstance(name, str) and not _is_absent(self._expected[name]):
                 self._assert_json_value_equals_with_item(name)
 
     @property
     def _expected_key_names(self) -> Set[str]:
         keys: Set[str] = set()
         for k in self._expected.keys():
             if isinstance(k, str):
-                keys.add(k)
+                if not _is_absent(self._expected[k]):
+                    keys.add(k)
             elif isinstance(k, Exists) and self._expected[k]:
                 keys.add(k.member_name)
         return keys
@@ -1523,6 +1534,23 @@ def append(self, item):
         return _JSONPath("{0}[{1}]".format(self._path, repr(item)))
 
 
+class Present:
+    """Helper class for presence checks in assert_json_subset()."""
+
+
+def _is_present(o: object) -> bool:
+    return o is Present or isinstance(o, Present)
+
+
+class Absent:
+    """Helper class for absence checks in assert_json_subset()."""
+
+
+def _is_absent(o: object) -> bool:
+    return o is Absent or isinstance(o, Absent)
+
+
+@deprecated("Use Present and Absent instead.")
 class Exists:
     """Helper class for existence checks in assert_json_subset()."""
 

asserts/__init__.pyi

@@ -5,6 +5,8 @@ from re import Pattern
 from types import TracebackType
 from typing import Any, Generic, NoReturn, TypeVar
 
+from typing_extensions import deprecated
+
 _E = TypeVar("_E", bound=BaseException)
 _S = TypeVar("_S")
 
@@ -163,6 +165,10 @@ def assert_json_subset(
     second: dict[str, Any] | list[Any] | str | bytes,
 ) -> None: ...
 
+class Present: ...
+class Absent: ...
+
+@deprecated("Use Present and Absent instead.")
 class Exists:
     member_name: str
     def __init__(self, member_name: str) -> None: ...

poetry.lock

@@ -23,6 +23,7 @@ include = ["*/py.typed", "*.pyi"]
 
 [tool.poetry.dependencies]
 python = ">=3.8.1"
+typing-extensions = "^4.10.0"
 
 [tool.poetry.group.dev.dependencies]
 mypy = "~1.9.0"

pyproject.toml

@@ -6,10 +6,12 @@
 from datetime import datetime, timedelta
 from json import JSONDecodeError
 from unittest import TestCase
-from warnings import catch_warnings, warn
+from warnings import catch_warnings, simplefilter, warn
 
 from asserts import (
+    Absent,
     Exists,
+    Present,
     assert_almost_equal,
     assert_between,
     assert_boolean_false,
@@ -1483,18 +1485,50 @@ def test_assert_json_subset__element_name_not_str(self) -> None:
         ):
             assert_json_subset({12: 34}, "{}")
 
-    def test_assert_json_subset__existence_check(self) -> None:
+    def test_assert_json_subset__presence_check(self) -> None:
         with assert_succeeds(AssertionError):
-            assert_json_subset({Exists("foo"): True}, {"foo": "bar"})
+            assert_json_subset({"foo": Present}, {"foo": "bar"})
+        with assert_succeeds(AssertionError):
+            assert_json_subset({"foo": Present()}, {"foo": "bar"})
+        with assert_raises_regex(
+            AssertionError,
+            r"element 'foo' missing from element \$",
+        ):
+            assert_json_subset({"foo": Present}, {})
         with assert_raises_regex(
             AssertionError,
             r"element 'foo' missing from element \$",
         ):
-            assert_json_subset({Exists("foo"): True}, {})
+            assert_json_subset({"foo": Present()}, {})
+        with assert_succeeds(AssertionError):
+            assert_json_subset({"foo": Absent}, {})
         with assert_succeeds(AssertionError):
-            assert_json_subset({Exists("foo"): False}, {})
+            assert_json_subset({"foo": Absent()}, {})
         with assert_raises_regex(
             AssertionError,
             r"spurious member 'foo' in object \$",
         ):
-            assert_json_subset({Exists("foo"): False}, {"foo": "bar"})
+            assert_json_subset({"foo": Absent}, {"foo": "bar"})
+        with assert_raises_regex(
+            AssertionError,
+            r"spurious member 'foo' in object \$",
+        ):
+            assert_json_subset({"foo": Absent()}, {"foo": "bar"})
+
+    def test_assert_json_subset__existence_check_old(self) -> None:
+        with catch_warnings(category=DeprecationWarning):
+            simplefilter("ignore")
+            with assert_succeeds(AssertionError):
+                assert_json_subset({Exists("foo"): True}, {"foo": "bar"})
+            with assert_raises_regex(
+                AssertionError,
+                r"element 'foo' missing from element \$",
+            ):
+                assert_json_subset({Exists("foo"): True}, {})
+            with assert_succeeds(AssertionError):
+                assert_json_subset({Exists("foo"): False}, {})
+            with assert_raises_regex(
+                AssertionError,
+                r"spurious member 'foo' in object \$",
+            ):
+                assert_json_subset({Exists("foo"): False}, {"foo": "bar"})