Skip to content

Dict assertions

Assertions for dict values: keys, values, and entries.

Dict assertions mixin.

contains_key 

contains_key(*keys: object) -> Self

Asserts the val is a dict and contains the given key or keys.

Alias for contains().

Checks if the dict contains the given key or keys using in operator.

Parameters:

Name Type Description Default
*keys object

the key or keys expected to be contained

 ()

Examples:

Usage:

assert_that({'a': 1, 'b': 2}).contains_key('a')
assert_that({'a': 1, 'b': 2}).contains_key('a', 'b')

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if val does not contain the key or keys
Source code in assertpy/dict.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def contains_key(self, *keys: object) -> Self:
    """Asserts the val is a dict and contains the given key or keys.

    Alias for [`contains()`][assertpy.contains.ContainsMixin.contains].

    Checks if the dict contains the given key or keys using ``in`` operator.

    Args:
        *keys: the key or keys expected to be contained

    Examples:
        Usage:

            assert_that({'a': 1, 'b': 2}).contains_key('a')
            assert_that({'a': 1, 'b': 2}).contains_key('a', 'b')

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if val does **not** contain the key or keys
    """
    self._require_dict_like(self.val, check_values=False, check_getitem=False)
    return self.contains(*keys)

does_not_contain_key 

does_not_contain_key(*keys: object) -> Self

Asserts the val is a dict and does not contain the given key or keys.

Alias for does_not_contain().

Checks if the dict excludes the given key or keys using in operator.

Parameters:

Name Type Description Default
*keys object

the key or keys expected to be excluded

 ()

Examples:

Usage:

assert_that({'a': 1, 'b': 2}).does_not_contain_key('x')
assert_that({'a': 1, 'b': 2}).does_not_contain_key('x', 'y')

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if val does contain the key or keys
Source code in assertpy/dict.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def does_not_contain_key(self, *keys: object) -> Self:
    """Asserts the val is a dict and does not contain the given key or keys.

    Alias for [`does_not_contain()`][assertpy.contains.ContainsMixin.does_not_contain].

    Checks if the dict excludes the given key or keys using ``in`` operator.

    Args:
        *keys: the key or keys expected to be excluded

    Examples:
        Usage:

            assert_that({'a': 1, 'b': 2}).does_not_contain_key('x')
            assert_that({'a': 1, 'b': 2}).does_not_contain_key('x', 'y')

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if val **does** contain the key or keys
    """
    self._require_dict_like(self.val, check_values=False, check_getitem=False)
    return self.does_not_contain(*keys)

contains_value 

contains_value(*values: object) -> Self

Asserts that val is a dict and contains the given value or values.

Checks if the dict contains the given value or values in any key.

Parameters:

Name Type Description Default
*values object

the value or values expected to be contained

 ()

Examples:

Usage:

assert_that({'a': 1, 'b': 2}).contains_value(1)
assert_that({'a': 1, 'b': 2}).contains_value(1, 2)

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if val does not contain the value or values
Source code in assertpy/dict.py 
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def contains_value(self, *values: object) -> Self:
    """Asserts that val is a dict and contains the given value or values.

    Checks if the dict contains the given value or values in *any* key.

    Args:
        *values: the value or values expected to be contained

    Examples:
        Usage:

            assert_that({'a': 1, 'b': 2}).contains_value(1)
            assert_that({'a': 1, 'b': 2}).contains_value(1, 2)

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if val does **not** contain the value or values
    """
    self._require_dict_like(self.val, check_getitem=False)
    if len(values) == 0:
        raise ValueError("one or more value args must be given")
    missing = [value for value in values if not member(value, self.val.values())]
    if missing:
        return self.error(
            f"Expected <{_capped(self.val)}> to contain values {self._fmt_items(values)},"
            f" but did not contain {self._fmt_items(missing)}." + _value_not_found(self.val, missing),
            expected=values,
        )
    return self

does_not_contain_value 

does_not_contain_value(*values: object) -> Self

Asserts that val is a dict and does not contain the given value or values.

Checks if the dict excludes the given value or values across all keys.

Parameters:

Name Type Description Default
*values object

the value or values expected to be excluded

 ()

Examples:

Usage:

assert_that({'a': 1, 'b': 2}).does_not_contain_value(3)
assert_that({'a': 1, 'b': 2}).does_not_contain_value(3, 4)

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if val does contain the value or values
Source code in assertpy/dict.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def does_not_contain_value(self, *values: object) -> Self:
    """Asserts that val is a dict and does not contain the given value or values.

    Checks if the dict excludes the given value or values across *all* keys.

    Args:
        *values: the value or values expected to be excluded

    Examples:
        Usage:

            assert_that({'a': 1, 'b': 2}).does_not_contain_value(3)
            assert_that({'a': 1, 'b': 2}).does_not_contain_value(3, 4)

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if val **does** contain the value or values
    """
    self._require_dict_like(self.val, check_getitem=False)
    if len(values) == 0:
        raise ValueError("one or more value args must be given")
    else:
        found = [value for value in values if member(value, self.val.values())]
        if found:
            return self.error(
                f"Expected <{_capped(self.val)}> to not contain values {self._fmt_items(values)},"
                f" but did contain {self._fmt_items(found)}."
            )
    return self

contains_entry 

contains_entry(*args: object, **kwargs: object) -> Self

Asserts that val is a dict and contains the given entry or entries.

Checks if the dict contains the given key-value pair or pairs.

Parameters:

Name Type Description Default
*args object

the entry or entries expected to be contained (as {k: v} args)

 ()
**kwargs object

the entry or entries expected to be contained (as k=v kwargs)

 {}

Examples:

Usage:

# using args
assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry({'a': 1})
assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry({'a': 1}, {'b': 2})
assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry({'a': 1}, {'b': 2}, {'c': 3})

# using kwargs
assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry(a=1)
assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry(a=1, b=2)
assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry(a=1, b=2, c=3)

# or args and kwargs
assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry({'c': 3}, a=1, b=2)

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if val does not contain the entry or entries
Note

Where one entry is not found, the failure says what its key holds, or that the key is not there, and on a line under the message why the value held is not the one expected, where one fact says so.

Source code in assertpy/dict.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
def contains_entry(self, *args: object, **kwargs: object) -> Self:
    """Asserts that val is a dict and contains the given entry or entries.

    Checks if the dict contains the given key-value pair or pairs.

    Args:
        *args (object): the entry or entries expected to be contained (as ``{k: v}`` args)
        **kwargs (object): the entry or entries expected to be contained (as ``k=v`` kwargs)

    Examples:
        Usage:

            # using args
            assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry({'a': 1})
            assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry({'a': 1}, {'b': 2})
            assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry({'a': 1}, {'b': 2}, {'c': 3})

            # using kwargs
            assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry(a=1)
            assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry(a=1, b=2)
            assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry(a=1, b=2, c=3)

            # or args and kwargs
            assert_that({'a': 1, 'b': 2, 'c': 3}).contains_entry({'c': 3}, a=1, b=2)


    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if val does **not** contain the entry or entries

    Note:
        Where one entry is not found, the failure says what its key holds, or that the key is not there, and
        on a line under the message why the value held is not the one expected, where one fact says so.
    """
    self._require_dict_like(self.val, check_values=False)
    entries = list(args) + [{key: value} for key, value in kwargs.items()]
    if len(entries) == 0:
        raise ValueError("one or more entry args must be given")
    missing = []
    for entry in entries:
        if type(entry) is not dict:
            refuse(entry, "a dict", subject=argument("entry"))
        # `object` not `dict`: the check above is `type(entry) is dict`, so a subclass is refused here
        pair = cast("dict[Any, Any]", entry)
        if len(pair) != 1:
            raise ValueError("given entry args must contain exactly one key-value pair")
        entry_key = next(iter(pair))
        try:
            if entry_key in self.val and equals(self.val[entry_key], pair[entry_key]):
                continue
        except REFUSALS as refusal:
            found, held = lookup(self.val, entry_key, refusal)
            if found and equals(held, pair[entry_key]):
                continue
        missing.append(pair)
    if missing:
        return self.error(
            f"Expected <{_capped(self.val)}> to contain entries {self._fmt_items(entries)},"
            f" but did not contain {self._fmt_items(missing)}." + _entry_not_found(self.val, missing),
            expected=entries,
        )
    return self

does_not_contain_entry 

does_not_contain_entry(
    *args: object, **kwargs: object
) -> Self

Asserts that val is a dict and does not contain the given entry or entries.

Checks if the dict excludes the given key-value pair or pairs.

Parameters:

Name Type Description Default
*args object

the entry or entries expected to be excluded (as {k: v} args)

 ()
**kwargs object

the entry or entries expected to be excluded (as k=v kwargs)

 {}

Examples:

Usage:

# using args
assert_that({'a': 1, 'b': 2, 'c': 3}).does_not_contain_entry({'a': 2})
assert_that({'a': 1, 'b': 2, 'c': 3}).does_not_contain_entry({'a': 2}, {'x': 4})

# using kwargs
assert_that({'a': 1, 'b': 2, 'c': 3}).does_not_contain_entry(a=2)
assert_that({'a': 1, 'b': 2, 'c': 3}).does_not_contain_entry(a=2, x=4)

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if val does contain the entry or entries
Source code in assertpy/dict.py 
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
def does_not_contain_entry(self, *args: object, **kwargs: object) -> Self:
    """Asserts that val is a dict and does not contain the given entry or entries.

    Checks if the dict excludes the given key-value pair or pairs.

    Args:
        *args (object): the entry or entries expected to be excluded (as ``{k: v}`` args)
        **kwargs (object): the entry or entries expected to be excluded (as ``k=v`` kwargs)

    Examples:
        Usage:

            # using args
            assert_that({'a': 1, 'b': 2, 'c': 3}).does_not_contain_entry({'a': 2})
            assert_that({'a': 1, 'b': 2, 'c': 3}).does_not_contain_entry({'a': 2}, {'x': 4})

            # using kwargs
            assert_that({'a': 1, 'b': 2, 'c': 3}).does_not_contain_entry(a=2)
            assert_that({'a': 1, 'b': 2, 'c': 3}).does_not_contain_entry(a=2, x=4)

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if val **does** contain the entry or entries
    """
    self._require_dict_like(self.val, check_values=False)
    entries = list(args) + [{key: value} for key, value in kwargs.items()]
    if len(entries) == 0:
        raise ValueError("one or more entry args must be given")
    found = []
    for entry in entries:
        if type(entry) is not dict:
            refuse(entry, "a dict", subject=argument("entry"))
        pair = cast("dict[Any, Any]", entry)
        if len(pair) != 1:
            raise ValueError("given entry args must contain exactly one key-value pair")
        entry_key = next(iter(pair))
        try:
            present = entry_key in self.val and equals(self.val[entry_key], pair[entry_key])
        except REFUSALS as refusal:
            held_there, held = lookup(self.val, entry_key, refusal)
            present = held_there and equals(held, pair[entry_key])
        if present:
            found.append(pair)
    if found:
        return self.error(
            f"Expected <{_capped(self.val)}> to not contain entries {self._fmt_items(entries)},"
            f" but did contain {self._fmt_items(found)}."
        )
    return self