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 assertpy2/dict.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
def contains_key(self, *keys: object) -> Self:
    """Asserts the val is a dict and contains the given key or keys.

    Alias for [`contains()`][assertpy2.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 assertpy2/dict.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
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()`][assertpy2.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 assertpy2/dict.py 
66
67
68
69
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
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 value not in self.val.values()]
    if missing:
        return self.error(
            f"Expected <{self.val}> to contain values {self._fmt_items(values)},"
            f" but did not contain {self._fmt_items(missing)}."
        )
    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 assertpy2/dict.py 
 97
 98
 99
100
101
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
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 value in self.val.values()]
        if found:
            return self.error(
                f"Expected <{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, **kwargs) -> 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
Source code in assertpy2/dict.py 
129
130
131
132
133
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
def contains_entry(self, *args, **kwargs) -> 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
    """
    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:
            raise TypeError("given entry arg must be a dict")
        if len(entry) != 1:
            raise ValueError("given entry args must contain exactly one key-value pair")
        entry_key = next(iter(entry))
        if entry_key not in self.val:
            missing.append(entry)  # bad key
        elif self.val[entry_key] != entry[entry_key]:
            missing.append(entry)  # bad val
    if missing:
        return self.error(
            f"Expected <{self.val}> to contain entries {self._fmt_items(entries)},"
            f" but did not contain {self._fmt_items(missing)}."
        )
    return self

does_not_contain_entry 

does_not_contain_entry(*args, **kwargs) -> 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 assertpy2/dict.py 
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
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
def does_not_contain_entry(self, *args, **kwargs) -> 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:
            raise TypeError("given entry arg must be a dict")
        if len(entry) != 1:
            raise ValueError("given entry args must contain exactly one key-value pair")
        entry_key = next(iter(entry))
        if entry_key in self.val and entry[entry_key] == self.val[entry_key]:
            found.append(entry)
    if found:
        return self.error(
            f"Expected <{self.val}> to not contain entries {self._fmt_items(entries)},"
            f" but did contain {self._fmt_items(found)}."
        )
    return self