Containment assertions

The contains family, shared by strings, collections, dicts, and bytes.

Containment assertions mixin.

contains

contains(*items: object) -> Self

Asserts that val contains the given item or items.

Checks if the collection contains the given item or items using in operator.

Parameters:

Name	Type	Description	Default
*items	object	the item or items expected to be contained	()

Examples:

Usage:

assert_that('foo').contains('f')
assert_that('foo').contains('f', 'oo')
assert_that(['a', 'b']).contains('b', 'a')
assert_that((1, 2, 3)).contains(3, 2, 1)
assert_that({'a': 1, 'b': 2}).contains('b', 'a')  # checks keys
assert_that({'a', 'b'}).contains('b', 'a')
assert_that([1, 2, 3]).is_type_of(list).contains(1, 2).does_not_contain(4, 5)

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 item or items
TypeError	if val is not a container or iterable

Note

Where one item is not found, the failure says what is nearest to it: the closest row among the elements, and on a line under the message why it is not there, where one fact about it says so.

Tip

Use the contains_key() alias when working with dict-like objects to be self-documenting.

See Also

contains_ignoring_case() - for case-insensitive string contains

Source code in assertpy/contains.py

def contains(self, *items: object) -> Self:
    """Asserts that val contains the given item or items.

    Checks if the collection contains the given item or items using ``in`` operator.

    Args:
        *items: the item or items expected to be contained

    Examples:
        Usage:

            assert_that('foo').contains('f')
            assert_that('foo').contains('f', 'oo')
            assert_that(['a', 'b']).contains('b', 'a')
            assert_that((1, 2, 3)).contains(3, 2, 1)
            assert_that({'a': 1, 'b': 2}).contains('b', 'a')  # checks keys
            assert_that({'a', 'b'}).contains('b', 'a')
            assert_that([1, 2, 3]).is_type_of(list).contains(1, 2).does_not_contain(4, 5)

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

    Raises:
        AssertionError: if val does **not** contain the item or items
        TypeError: if val is not a container or iterable

    Note:
        Where one item is not found, the failure says what is nearest to it: the closest row among the elements,
        and on a line under the message why it is not there, where one fact about it says so.

    Tip:
        Use the [`contains_key()`][assertpy.dict.DictMixin.contains_key] alias when working with
        *dict-like* objects to be self-documenting.

    See Also:
        [`contains_ignoring_case()`][assertpy.string.StringMixin.contains_ignoring_case] -
            for case-insensitive string contains
    """
    if len(items) == 0:
        raise ValueError("one or more args must be given")
    # membership is tested once per argument, so a one-shot iterator has to be drained first
    values = searchable(self._drained())
    if not is_searchable(values):
        # left to `in`, Python answers about the operator rather than about the value the assertion was handed
        refuse(self.val, "a container or iterable")
    if len(items) == 1:
        item = items[0]
        if _is_matcher(item):
            if not any(verdict(item.matches(value), subject="the matcher") for value in values):
                diff = DiffResult(
                    kind="contains",
                    entries=[DiffEntry(path="missing", actual=None, absent="actual", expected=item.describe())],
                )
                return self.error(
                    f"Expected <{_capped_format(values)}> to contain item matching {item.describe()}, but did not.",
                    diff=diff,
                    expected=items,
                )
        elif not member(item, values):
            if mapping_shaped(values):
                diff = DiffResult(
                    kind="contains",
                    entries=[DiffEntry(path="missing", actual=None, absent="actual", expected=item)],
                )
                return self.error(
                    f"Expected <{_capped_format(values)}> to contain key <{_capped_format(item)}>, but did not."
                    f"{_why(item, values, _OF_A_KEY)}",
                    diff=diff,
                    expected=items,
                )
            closest = _closest(item, values)
            if closest is not None:
                element, entries = closest
                return self.error(
                    f"Expected <{_capped_format(values)}> to contain item <{_capped_format(item)}>, but did not."
                    f" Closest element <{_capped_format(element)}> differs at {_differences(entries)}."
                    f"{_why(item, values)}",
                    diff=DiffResult(kind="contains", entries=entries),
                    expected=items,
                )
            diff = DiffResult(
                kind="contains", entries=[DiffEntry(path="missing", actual=None, absent="actual", expected=item)]
            )
            in_text = type(values) is str and type(item) is str
            return self.error(
                f"Expected <{_capped_format(values)}> to contain item <{_capped_format(item)}>, but did not."
                f"{under(not_in_text(values, item)) if in_text else _why(item, values)}",
                diff=diff,
                expected=items,
            )
    else:
        missing = missing_items(values, items, _is_matcher)
        if missing:
            missing_desc = [
                missing_item.describe() if _is_matcher(missing_item) else missing_item for missing_item in missing
            ]
            diff = DiffResult(
                kind="contains",
                entries=[
                    DiffEntry(path="missing", actual=None, absent="actual", expected=missing_item)
                    for missing_item in missing_desc
                ],
            )
            if mapping_shaped(values):
                sentence = (
                    f"Expected <{_capped_format(values)}> to contain keys {self._fmt_items(items)},"
                    f" but did not contain key{'' if len(missing) == 1 else 's'} {self._fmt_items(missing_desc)}."
                )
                said = _one_not_found(missing, values, noun=None, roles=_OF_A_KEY)
            else:
                sentence = (
                    f"Expected <{_capped_format(values)}> to contain items {self._fmt_items(items)},"
                    f" but did not contain {self._fmt_items(missing_desc)}."
                )
                said = _one_not_found(missing, values)
            return self.error(sentence + said, diff=diff, expected=items)
    return self

does_not_contain

does_not_contain(*items: object) -> Self

Asserts that val does not contain the given item or items.

Checks if the collection excludes the given item or items using in operator.

Parameters:

Name	Type	Description	Default
*items	object	the item or items expected to be excluded	()

Examples:

Usage:

assert_that('foo').does_not_contain('x')
assert_that(['a', 'b']).does_not_contain('x', 'y')
assert_that((1, 2, 3)).does_not_contain(4, 5)
assert_that({'a': 1, 'b': 2}).does_not_contain('x', 'y')  # checks keys
assert_that({'a', 'b'}).does_not_contain('x', 'y')
assert_that([1, 2, 3]).is_type_of(list).contains(1, 2).does_not_contain(4, 5)

Returns:

Name	Type	Description
AssertionBuilder	Self	returns this instance to chain to the next assertion

Raises:

Type	Description
AssertionError	if val does contain the item or items
TypeError	if val is not a container or iterable

Note

Accepts a Matcher for any item, the same as contains(): the assertion then fails when any item of val matches it.

Tip

Use the does_not_contain_key() alias when working with dict-like objects to be self-documenting.

Source code in assertpy/contains.py

def does_not_contain(self, *items: object) -> Self:
    """Asserts that val does not contain the given item or items.

    Checks if the collection excludes the given item or items using ``in`` operator.

    Args:
        *items: the item or items expected to be excluded

    Examples:
        Usage:

            assert_that('foo').does_not_contain('x')
            assert_that(['a', 'b']).does_not_contain('x', 'y')
            assert_that((1, 2, 3)).does_not_contain(4, 5)
            assert_that({'a': 1, 'b': 2}).does_not_contain('x', 'y')  # checks keys
            assert_that({'a', 'b'}).does_not_contain('x', 'y')
            assert_that([1, 2, 3]).is_type_of(list).contains(1, 2).does_not_contain(4, 5)

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

    Raises:
        AssertionError: if val **does** contain the item or items
        TypeError: if val is not a container or iterable

    Note:
        Accepts a `Matcher` for any item, the same as
        [`contains()`][assertpy.contains.ContainsMixin.contains]: the assertion then fails when any
        item of val matches it.

    Tip:
        Use the [`does_not_contain_key()`][assertpy.dict.DictMixin.does_not_contain_key] alias when working with
        *dict-like* objects to be self-documenting.
    """
    if len(items) == 0:
        raise ValueError("one or more args must be given")
    values = self._drained()
    if not is_searchable(values):
        refuse(self.val, "a container or iterable")
    probes = [item for item in items if not _is_matcher(item)]
    # the index `contains` already builds for the same question: asked one item at a time, each of
    # them walks the whole collection
    searched = _index(values, probes) if len(probes) > 1 else None
    lookup = values if searched is None else searched

    def described(item: object) -> object:
        return item.describe() if _is_matcher(item) else item

    def present(item: object) -> bool:
        # a matcher handed here was compared with `in`, which asks the wrong question
        if _is_matcher(item):
            return any(verdict(item.matches(value), subject="the matcher") for value in values)
        return member(item, lookup)

    if len(items) == 1:
        if present(items[0]):
            return self.error(
                f"Expected <{_capped_format(values)}> to not contain item"
                f" <{_capped_format(described(items[0]))}>, but did."
            )
    else:
        found = [item for item in items if present(item)]
        if found:
            shown = [described(item) for item in items]
            found_shown = [described(item) for item in found]
            return self.error(
                f"Expected <{_capped_format(values)}> to not contain items {self._fmt_items(shown)},"
                f" but did contain {self._fmt_items(found_shown)}."
            )
    return self

contains_only

contains_only(*items: object) -> Self

Asserts that val contains only the given item or items.

Checks if the collection contains only the given item or items using in operator.

Parameters:

Name	Type	Description	Default
*items	object	the only item or items expected to be contained	()

Examples:

Usage:

assert_that('foo').contains_only('f', 'o')
assert_that(['a', 'a', 'b']).contains_only('a', 'b')
assert_that((1, 1, 2)).contains_only(1, 2)
assert_that({'a': 1, 'a': 2, 'b': 3}).contains_only('a', 'b')
assert_that({'a', 'a', 'b'}).contains_only('a', 'b')

Returns:

Name	Type	Description
AssertionBuilder	Self	returns this instance to chain to the next assertion

Raises:

Type	Description
AssertionError	if val contains anything not item or items

Note

Where one item is not found, the failure says what is nearest to it: the closest row among the elements nobody asked for, and on a line under the message why it is not there, where one fact about it says so.

Source code in assertpy/contains.py

def contains_only(self, *items: object) -> Self:
    """Asserts that val contains *only* the given item or items.

    Checks if the collection contains only the given item or items using ``in`` operator.

    Args:
        *items: the *only* item or items expected to be contained

    Examples:
        Usage:

            assert_that('foo').contains_only('f', 'o')
            assert_that(['a', 'a', 'b']).contains_only('a', 'b')
            assert_that((1, 1, 2)).contains_only(1, 2)
            assert_that({'a': 1, 'a': 2, 'b': 3}).contains_only('a', 'b')
            assert_that({'a', 'a', 'b'}).contains_only('a', 'b')

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

    Raises:
        AssertionError: if val contains anything **not** item or items

    Note:
        Where one item is not found, the failure says what is nearest to it: the closest row among the
        elements nobody asked for, and on a line under the message why it is not there, where one fact about
        it says so.
    """
    if len(items) == 0:
        raise ValueError("one or more args must be given")
    # walked twice below and rendered a third time, so a one-shot iterator has to be drained
    values = searchable(self._drained())
    if not is_walkable(values):
        # "only these" has to see every element, and the comprehension answered "object is not iterable"
        refuse(self.val, "iterable")
    extra, missing = only_faults(values, items)
    if extra or missing:
        # both halves at once: reporting only the extras sends the reader to rerun into the other
        faults = []
        entries = []
        had, lacked = _lone_pair(extra, missing) or (self._fmt_items(extra), self._fmt_items(missing))
        if extra:
            faults.append(f"did contain {had}")
            entries += [DiffEntry(path="extra", actual=item, expected=None, absent="expected") for item in extra]
        if missing:
            faults.append(f"did not contain {lacked}")
            entries += [DiffEntry(path="missing", actual=None, absent="actual", expected=item) for item in missing]
        return self.error(
            f"Expected <{_capped_format(values)}> to contain only {self._fmt_items(items)},"
            f" but {' and '.join(faults)}." + _both_ways(extra, missing, values, items),
            diff=DiffResult(kind="contains", entries=entries),
            expected=items,
        )
    return self

contains_sequence

contains_sequence(*items: object) -> Self

Asserts that val contains the given ordered sequence of items.

Checks if the collection contains the given sequence of items using in operator.

Parameters:

Name	Type	Description	Default
*items	object	the sequence of items expected to be contained	()

Examples:

Usage:

assert_that('foo').contains_sequence('f', 'o')
assert_that('foo').contains_sequence('o', 'o')
assert_that(['a', 'b', 'c']).contains_sequence('b', 'c')
assert_that((1, 2, 3)).contains_sequence(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 contains the given sequence of items

Source code in assertpy/contains.py

def contains_sequence(self, *items: object) -> Self:
    """Asserts that val contains the given ordered sequence of items.

    Checks if the collection contains the given sequence of items using ``in`` operator.

    Args:
        *items: the sequence of items expected to be contained

    Examples:
        Usage:

            assert_that('foo').contains_sequence('f', 'o')
            assert_that('foo').contains_sequence('o', 'o')
            assert_that(['a', 'b', 'c']).contains_sequence('b', 'c')
            assert_that((1, 2, 3)).contains_sequence(1, 2)

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

    Raises:
        AssertionError: if val does **not** contains the given sequence of items
    """
    if len(items) == 0:
        raise ValueError("one or more args must be given")
    if isinstance(self.val, str):
        search_start = 0
        for item in items:
            text = require_type(item, str, "a string, to match val", subject=argument("item"))
            found_index = self.val.find(text, search_start)
            if found_index == -1:
                # name where the chain broke: "but did not" makes the reader re-derive it by eye
                matched = items[: items.index(item)]
                trail = f" after {self._fmt_items(matched)}" if matched else ""
                return self.error(
                    f"Expected <{_capped(self.val)}> to contain sequence {self._fmt_items(items)},"
                    f" but <{_capped_format(item)}> was not found{trail}.",
                    expected=items,
                )
            search_start = found_index + len(text)
        return self
    # this walk is by index, which a one-shot iterator does not support at all
    values = self._drained()
    if not isinstance(values, Sequence):
        # the old guard said "not iterable" for both: true for an int, false for a set, which has no order
        require_type(values, Iterable, "iterable")
        refuse(self.val, "a sequence, to contain a sequence")
    try:
        best_prefix = _sequence_break(values, items, answered=any(may_broadcast(item) for item in items))
    except REFUSALS:
        best_prefix = _sequence_break(values, items, answered=True)
    if best_prefix is None:
        return self
    best_prefix = max(best_prefix, _late_run(values, items))
    # the longest run that lined up says where the sequence broke down
    detail = (
        f" The longest run that matched was {self._fmt_items(items[:best_prefix])}."
        if best_prefix
        # X may well be present, just never at a position where the whole sequence still fits
        else f" No run started with <{_capped_format(items[0])}>."
    )
    return self.error(
        f"Expected <{_capped_format(values)}> to contain sequence {self._fmt_items(items)}, but did not.{detail}"
        + _why_absent(items[best_prefix], values),
        expected=items,
    )

contains_duplicates

contains_duplicates() -> Self

Asserts that val is iterable and does contain duplicates.

Examples:

Usage:

assert_that('foo').contains_duplicates()
assert_that(['a', 'a', 'b']).contains_duplicates()
assert_that((1, 1, 2)).contains_duplicates()

Returns:

Name	Type	Description
AssertionBuilder	Self	returns this instance to chain to the next assertion

Raises:

Type	Description
AssertionError	if val does not contain any duplicates

Source code in assertpy/contains.py

def contains_duplicates(self) -> Self:
    """Asserts that val is iterable and *does* contain duplicates.

    Examples:
        Usage:

            assert_that('foo').contains_duplicates()
            assert_that(['a', 'a', 'b']).contains_duplicates()
            assert_that((1, 1, 2)).contains_duplicates()

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

    Raises:
        AssertionError: if val does **not** contain any duplicates
    """
    try:
        values = list(self._walked())
    except TypeError:
        refuse(self.val, "iterable")
    if has_duplicates(values):
        return self
    return self.error(f"Expected <{_capped(self.val)}> to contain duplicates, but did not.")

does_not_contain_duplicates

does_not_contain_duplicates() -> Self

Asserts that val is iterable and does not contain any duplicates.

Examples:

Usage:

assert_that('fox').does_not_contain_duplicates()
assert_that(['a', 'b', 'c']).does_not_contain_duplicates()
assert_that((1, 2, 3)).does_not_contain_duplicates()

Returns:

Name	Type	Description
AssertionBuilder	Self	returns this instance to chain to the next assertion

Raises:

Type	Description
AssertionError	if val does contain duplicates

Source code in assertpy/contains.py

def does_not_contain_duplicates(self) -> Self:
    """Asserts that val is iterable and *does not* contain any duplicates.

    Examples:
        Usage:

            assert_that('fox').does_not_contain_duplicates()
            assert_that(['a', 'b', 'c']).does_not_contain_duplicates()
            assert_that((1, 2, 3)).does_not_contain_duplicates()

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

    Raises:
        AssertionError: if val **does** contain duplicates
    """
    try:
        values = list(self._walked())
    except TypeError:
        refuse(self.val, "iterable")
    if not has_duplicates(values):
        return self
    # "but did" leaves the reader to scan the value for the repeat
    repeated = repeated_counts(values)
    named = [value for value, _total in repeated]
    return self.error(
        f"Expected <{_capped(self.val)}> to not contain duplicates, but {self._fmt_items(named)}"
        f" {'was' if len(named) == 1 else 'were'} repeated.",
        diff=DiffResult(kind="contains", entries=_surplus(repeated)),
    )

is_empty

is_empty() -> Self

Asserts that val is empty.

Examples:

Usage:

assert_that('').is_empty()
assert_that([]).is_empty()
assert_that(()).is_empty()
assert_that({}).is_empty()
assert_that(set()).is_empty()

Returns:

Name	Type	Description
AssertionBuilder	Self	returns this instance to chain to the next assertion

Raises:

Type	Description
AssertionError	if val is not empty

Source code in assertpy/contains.py

def is_empty(self) -> Self:
    """Asserts that val is empty.

    Examples:
        Usage:

            assert_that('').is_empty()
            assert_that([]).is_empty()
            assert_that(()).is_empty()
            assert_that({}).is_empty()
            assert_that(set()).is_empty()

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

    Raises:
        AssertionError: if val is **not** empty
    """
    if sized_len(self.val) != 0:
        if isinstance(self.val, str):
            return self.error(f"Expected <{_capped(self.val)}> to be empty string, but was not.")
        else:
            return self.error(f"Expected <{_capped(self.val)}> to be empty, but was not.")
    return self

is_not_empty

is_not_empty() -> Self

Asserts that val is not empty.

Examples:

Usage:

assert_that('foo').is_not_empty()
assert_that(['a', 'b']).is_not_empty()
assert_that((1, 2, 3)).is_not_empty()
assert_that({'a': 1, 'b': 2}).is_not_empty()
assert_that({'a', 'b'}).is_not_empty()

Returns:

Name	Type	Description
AssertionBuilder	Self	returns this instance to chain to the next assertion

Raises:

Type	Description
AssertionError	if val is empty

Source code in assertpy/contains.py

def is_not_empty(self) -> Self:
    """Asserts that val is *not* empty.

    Examples:
        Usage:

            assert_that('foo').is_not_empty()
            assert_that(['a', 'b']).is_not_empty()
            assert_that((1, 2, 3)).is_not_empty()
            assert_that({'a': 1, 'b': 2}).is_not_empty()
            assert_that({'a', 'b'}).is_not_empty()

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

    Raises:
        AssertionError: if val **is** empty
    """
    if sized_len(self.val) == 0:
        if isinstance(self.val, str):
            return self.error("Expected not empty string, but was empty.")
        else:
            return self.error("Expected not empty, but was empty.")
    return self

contains_exactly

contains_exactly(*items: object) -> Self

Asserts that val contains exactly the given items in the given order.

Unlike contains_only() (which ignores order) and contains_sequence() (which allows extra items), this method requires exact count, items, and order.

Parameters:

Name	Type	Description	Default
*items	object	the items expected, in exact order	()

Examples:

Usage:

assert_that([1, 2, 3]).contains_exactly(1, 2, 3)
assert_that(['a', 'b']).contains_exactly('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 exactly the given items in order

Source code in assertpy/contains.py

def contains_exactly(self, *items: object) -> Self:
    """Asserts that val contains exactly the given items in the given order.

    Unlike [`contains_only()`][assertpy.contains.ContainsMixin.contains_only] (which ignores
    order) and [`contains_sequence()`][assertpy.contains.ContainsMixin.contains_sequence]
    (which allows extra items), this method requires exact count, items, and order.

    Args:
        *items: the items expected, in exact order

    Examples:
        Usage:

            assert_that([1, 2, 3]).contains_exactly(1, 2, 3)
            assert_that(['a', 'b']).contains_exactly('a', 'b')

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

    Raises:
        AssertionError: if val does **not** contain exactly the given items in order
    """
    if len(items) == 0:
        raise ValueError("one or more args must be given")
    try:
        val_list = list(self._walked())
    except TypeError:
        refuse(self.val, "iterable")
    expected_list = list(items)
    if equals(val_list, expected_list):
        return self
    message = f"Expected <{_capped(self.val)}> to contain exactly {self._fmt_items(items)}, but did not."
    entries = _multiset_diff_entries(val_list, expected_list)
    # equal multisets, so only the order differs: name the first position that disagrees
    disagreeing = (
        i
        for i, (found, wanted) in enumerate(zip(val_list, expected_list, strict=True))
        if not _guarded_equal(found, wanted, method="contains_exactly")
    )
    # none, from an `__eq__` that answered the list's question and the rescan's differently
    index = None if entries else next(disagreeing, None)
    if index is None:
        diff = DiffResult(kind="contains", entries=entries)
        message += _both_ways(*_unmatched(entries), val_list, expected_list)
    else:
        message += f" Same items, but the order differs at index {index}."
        diff = DiffResult(
            kind="sequence",
            entries=[_ROOT.index(index).entry(actual=val_list[index], expected=expected_list[index])],
        )
    return self.error(message, diff=diff, expected=items)

contains_exactly_in_any_order

contains_exactly_in_any_order(*items: object) -> Self

Asserts that val contains exactly the given items, in any order.

Like contains_exactly() but ignoring order: val and the given items must be equal as multisets, so duplicates count (each item must occur exactly as many times as given). Unlike contains_only() (which checks membership both ways and ignores counts), an extra duplicate or a missing one fails.

Parameters:

Name	Type	Description	Default
*items	object	the items expected, in any order	()

Examples:

Usage:

assert_that([3, 1, 2]).contains_exactly_in_any_order(1, 2, 3)
assert_that(['b', 'a', 'b']).contains_exactly_in_any_order('a', 'b', 'b')

assert_that([1, 2, 2]).contains_exactly_in_any_order(1, 2)  # fails (extra 2)
assert_that([1, 2]).contains_exactly_in_any_order(1, 2, 2)  # fails (missing 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 exactly the given items in any order
TypeError	if val is not iterable
ValueError	if no items are given

Source code in assertpy/contains.py

def contains_exactly_in_any_order(self, *items: object) -> Self:
    """Asserts that val contains exactly the given items, in any order.

    Like [`contains_exactly()`][assertpy.contains.ContainsMixin.contains_exactly] but ignoring
    order: val and the given items must be equal as multisets, so duplicates count (each item
    must occur exactly as many times as given).  Unlike
    [`contains_only()`][assertpy.contains.ContainsMixin.contains_only] (which checks membership
    both ways and ignores counts), an extra duplicate or a missing one fails.

    Args:
        *items: the items expected, in any order

    Examples:
        Usage:

            assert_that([3, 1, 2]).contains_exactly_in_any_order(1, 2, 3)
            assert_that(['b', 'a', 'b']).contains_exactly_in_any_order('a', 'b', 'b')

            assert_that([1, 2, 2]).contains_exactly_in_any_order(1, 2)  # fails (extra 2)
            assert_that([1, 2]).contains_exactly_in_any_order(1, 2, 2)  # fails (missing 2)

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

    Raises:
        AssertionError: if val does **not** contain exactly the given items in any order
        TypeError: if val is not iterable
        ValueError: if no items are given
    """
    if len(items) == 0:
        raise ValueError("one or more args must be given")
    try:
        val_list = list(self._walked())
    except TypeError:
        refuse(self.val, "iterable")
    entries = _multiset_diff_entries(val_list, list(items))
    if entries:
        return self.error(
            f"Expected <{_capped(self.val)}> to contain exactly {self._fmt_items(items)} in any order, "
            f"but did not." + _both_ways(*_unmatched(entries), val_list, items),
            diff=DiffResult(kind="contains", entries=entries),
            expected=items,
        )
    return self

contains_in_order

contains_in_order(*items: object) -> Self

Asserts that val contains the given items in the given order (as a subsequence).

Items must appear in the given order but do not need to be contiguous. Unlike contains_sequence() which requires contiguous items.

Parameters:

Name	Type	Description	Default
*items	object	the items expected, in order (but not necessarily contiguous)	()

Examples:

Usage:

assert_that([1, 5, 2, 8, 3]).contains_in_order(1, 2, 3)
assert_that(['a', 'x', 'b', 'y', 'c']).contains_in_order('a', 'b', 'c')

Returns:

Name	Type	Description
AssertionBuilder	Self	returns this instance to chain to the next assertion

Raises:

Type	Description
AssertionError	if val does not contain items in the given order

Source code in assertpy/contains.py

def contains_in_order(self, *items: object) -> Self:
    """Asserts that val contains the given items in the given order (as a subsequence).

    Items must appear in the given order but do not need to be contiguous.
    Unlike [`contains_sequence()`][assertpy.contains.ContainsMixin.contains_sequence] which
    requires contiguous items.

    Args:
        *items: the items expected, in order (but not necessarily contiguous)

    Examples:
        Usage:

            assert_that([1, 5, 2, 8, 3]).contains_in_order(1, 2, 3)
            assert_that(['a', 'x', 'b', 'y', 'c']).contains_in_order('a', 'b', 'c')

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

    Raises:
        AssertionError: if val does **not** contain items in the given order
    """
    if len(items) == 0:
        raise ValueError("one or more args must be given")
    try:
        val_list = list(self._walked())
    except TypeError:
        refuse(self.val, "iterable")
    item_index, wanted = 0, items[0]
    for element in val_list:
        # the very object is itself before `==` is asked, as it is to `in`: a NaN the value holds follows
        if element is wanted or equals(element, wanted):
            item_index += 1
            if item_index == len(items):
                break
            wanted = items[item_index]
    if item_index != len(items):
        # item_index counts how many lined up before the run stopped, so the next one is the culprit
        matched = items[:item_index]
        trail = f" after {self._fmt_items(matched)}" if matched else ""
        return self.error(
            f"Expected <{_capped(self.val)}> to contain {self._fmt_items(items)} in order, "
            f"but <{_capped_format(items[item_index])}> did not follow{trail}."
            + _why_absent(items[item_index], val_list),
            expected=items,
        )
    return self

contains_only_once

contains_only_once(*items: object) -> Self

Asserts that val contains each given item exactly once.

Each given item must appear in val with a count of exactly one: an item absent from val is reported as missing, an item occurring more than once is reported as duplicated.

Parameters:

Name	Type	Description	Default
*items	object	the items each expected to occur exactly once	()

Examples:

Usage:

assert_that([1, 2, 3]).contains_only_once(1, 3)
assert_that('foo').contains_only_once('f')

assert_that([1, 2, 2, 3]).contains_only_once(2)  # fails (occurs twice)
assert_that([1, 2, 3]).contains_only_once(4)  # fails (missing)

Returns:

Name	Type	Description
AssertionBuilder	Self	returns this instance to chain to the next assertion

Raises:

Type	Description
AssertionError	if any given item is missing from val or occurs more than once
TypeError	if val is not iterable
ValueError	if no items are given

Source code in assertpy/contains.py

def contains_only_once(self, *items: object) -> Self:
    """Asserts that val contains each given item exactly once.

    Each given item must appear in val with a count of exactly one: an item absent from val is
    reported as missing, an item occurring more than once is reported as duplicated.

    Args:
        *items: the items each expected to occur exactly once

    Examples:
        Usage:

            assert_that([1, 2, 3]).contains_only_once(1, 3)
            assert_that('foo').contains_only_once('f')

            assert_that([1, 2, 2, 3]).contains_only_once(2)  # fails (occurs twice)
            assert_that([1, 2, 3]).contains_only_once(4)  # fails (missing)

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

    Raises:
        AssertionError: if any given item is missing from val or occurs more than once
        TypeError: if val is not iterable
        ValueError: if no items are given
    """
    if len(items) == 0:
        raise ValueError("one or more args must be given")
    try:
        val_list = list(self._walked())
    except TypeError:
        refuse(self.val, "iterable")
    counts = occurrences(val_list, items)
    missing = [item for item, total in zip(items, counts, strict=True) if total == 0]
    repeats = [(item, total) for item, total in zip(items, counts, strict=True) if total > 1]
    duplicated = [item for item, _ in repeats]
    if missing or duplicated:
        entries = [DiffEntry(path="missing", actual=None, absent="actual", expected=item) for item in missing]
        entries.extend(_surplus(repeats))
        problems = []
        if missing:
            problems.append(f"did not contain {self._fmt_items(missing)}")
        if duplicated:
            problems.append(f"contained {self._fmt_items(duplicated)} more than once")
        return self.error(
            f"Expected <{_capped_format(val_list)}> to contain {self._fmt_items(items)} only once,"
            f" but {' and '.join(problems)}." + _one_not_found(missing, val_list),
            diff=DiffResult(kind="contains", entries=entries),
            expected=items,
        )
    return self

is_in

is_in(*items: object) -> Self

Asserts that val is equal to one of the given items.

Parameters:

Name	Type	Description	Default
*items	object	the items expected to contain val	()

Examples:

Usage:

assert_that('foo').is_in('foo', 'bar', 'baz')
assert_that(1).is_in(0, 1, 2, 3)

Returns:

Name	Type	Description
AssertionBuilder	Self	returns this instance to chain to the next assertion

Raises:

Type	Description
AssertionError	if val is not in the given items

Note

The failure says what is nearest to val: the closest row among the given items, and on a line under the message why val is in none of them, where one fact about it says so.

Source code in assertpy/contains.py

def is_in(self, *items: object) -> Self:
    """Asserts that val is equal to one of the given items.

    Args:
        *items: the items expected to contain val

    Examples:
        Usage:

            assert_that('foo').is_in('foo', 'bar', 'baz')
            assert_that(1).is_in(0, 1, 2, 3)

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

    Raises:
        AssertionError: if val is **not** in the given items

    Note:
        The failure says what is nearest to val: the closest row among the given items, and on a line under
        the message why val is in none of them, where one fact about it says so.
    """
    if len(items) == 0:
        raise ValueError("one or more args must be given")
    # identity first, as `in` asks: the very NaN a tuple holds is in it, and `==` alone said no
    if member(self.val, items):
        return self
    roles = Roles("the value", "a given item")
    return self.error(
        f"Expected <{_capped(self.val)}> to be in {self._fmt_items(items)}, but was not."
        + _one_not_found((self.val,), items, noun="item", item_is_actual=True, roles=roles),
        expected=items,
    )

is_not_in

is_not_in(*items: object) -> Self

Asserts that val is not equal to one of the given items.

Parameters:

Name	Type	Description	Default
*items	object	the items expected to exclude val	()

Examples:

Usage:

assert_that('foo').is_not_in('bar', 'baz', 'box')
assert_that(1).is_not_in(-1, -2, -3)

Returns:

Name	Type	Description
AssertionBuilder	Self	returns this instance to chain to the next assertion

Raises:

Type	Description
AssertionError	if val is in the given items

Source code in assertpy/contains.py

def is_not_in(self, *items: object) -> Self:
    """Asserts that val is not equal to one of the given items.

    Args:
        *items: the items expected to exclude val

    Examples:
        Usage:

            assert_that('foo').is_not_in('bar', 'baz', 'box')
            assert_that(1).is_not_in(-1, -2, -3)

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

    Raises:
        AssertionError: if val **is** in the given items
    """
    if len(items) == 0:
        raise ValueError("one or more args must be given")
    if member(self.val, items):
        return self.error(f"Expected <{_capped(self.val)}> to not be in {self._fmt_items(items)}, but was.")
    return self