Matchers

The composable matchers exposed by the match namespace. Call them as match.greater_than(5), match.is_uuid(), and so on, then combine with &, |, and ~. See the Matchers guide for usage, composition, and custom matchers.

Factory namespace for creating matcher instances.

Usage:

from assertpy2 import match

assert_that(value).satisfies(match.greater_than(5) & match.less_than(10))
assert_that(items).each(match.is_positive())

equal_to staticmethod

equal_to(expected: object) -> EqualToMatcher

Matcher for a value equal to expected.

Source code in assertpy2/matchers.py

@staticmethod
def equal_to(expected: object) -> EqualToMatcher:
    """Matcher for a value equal to ``expected``."""
    return EqualToMatcher(expected)

greater_than staticmethod

greater_than(val: object) -> GreaterThanMatcher

Matcher for a value greater than val.

Source code in assertpy2/matchers.py

@staticmethod
def greater_than(val: object) -> GreaterThanMatcher:
    """Matcher for a value greater than ``val``."""
    return GreaterThanMatcher(val)

greater_than_or_equal_to staticmethod

greater_than_or_equal_to(
    val: object,
) -> GreaterThanOrEqualToMatcher

Matcher for a value greater than or equal to val.

Source code in assertpy2/matchers.py

@staticmethod
def greater_than_or_equal_to(val: object) -> GreaterThanOrEqualToMatcher:
    """Matcher for a value greater than or equal to ``val``."""
    return GreaterThanOrEqualToMatcher(val)

less_than staticmethod

less_than(val: object) -> LessThanMatcher

Matcher for a value less than val.

Source code in assertpy2/matchers.py

@staticmethod
def less_than(val: object) -> LessThanMatcher:
    """Matcher for a value less than ``val``."""
    return LessThanMatcher(val)

less_than_or_equal_to staticmethod

less_than_or_equal_to(
    val: object,
) -> LessThanOrEqualToMatcher

Matcher for a value less than or equal to val.

Source code in assertpy2/matchers.py

@staticmethod
def less_than_or_equal_to(val: object) -> LessThanOrEqualToMatcher:
    """Matcher for a value less than or equal to ``val``."""
    return LessThanOrEqualToMatcher(val)

between staticmethod

between(low: object, high: object) -> BetweenMatcher

Matcher for a value in the inclusive range low to high.

Source code in assertpy2/matchers.py

@staticmethod
def between(low: object, high: object) -> BetweenMatcher:
    """Matcher for a value in the inclusive range ``low`` to ``high``."""
    return BetweenMatcher(low, high)

close_to staticmethod

close_to(
    expected: object, tolerance: object
) -> CloseToMatcher

Matcher for a value within tolerance of expected (abs(value - expected) <= tolerance).

Parameters:

Name	Type	Description	Default
expected	object	the target value	required
tolerance	object	the maximum allowed absolute difference from expected	required

Source code in assertpy2/matchers.py

@staticmethod
def close_to(expected: object, tolerance: object) -> CloseToMatcher:
    """Matcher for a value within ``tolerance`` of ``expected`` (``abs(value - expected) <= tolerance``).

    Args:
        expected: the target value
        tolerance: the maximum allowed absolute difference from ``expected``
    """
    return CloseToMatcher(expected, tolerance)

is_none staticmethod

is_none() -> IsNoneMatcher

Matcher for None.

Source code in assertpy2/matchers.py

@staticmethod
def is_none() -> IsNoneMatcher:
    """Matcher for ``None``."""
    return IsNoneMatcher()

is_not_none staticmethod

is_not_none() -> IsNotNoneMatcher

Matcher for any value that is not None.

Source code in assertpy2/matchers.py

@staticmethod
def is_not_none() -> IsNotNoneMatcher:
    """Matcher for any value that is not ``None``."""
    return IsNotNoneMatcher()

is_instance_of staticmethod

is_instance_of(expected_type: type) -> IsInstanceOfMatcher

Matcher for an instance of expected_type (via isinstance).

Source code in assertpy2/matchers.py

@staticmethod
def is_instance_of(expected_type: type) -> IsInstanceOfMatcher:
    """Matcher for an instance of ``expected_type`` (via ``isinstance``)."""
    return IsInstanceOfMatcher(expected_type)

is_truthy staticmethod

is_truthy() -> IsTruthyMatcher

Matcher for a truthy value.

Source code in assertpy2/matchers.py

@staticmethod
def is_truthy() -> IsTruthyMatcher:
    """Matcher for a truthy value."""
    return IsTruthyMatcher()

is_falsy staticmethod

is_falsy() -> IsFalsyMatcher

Matcher for a falsy value.

Source code in assertpy2/matchers.py

@staticmethod
def is_falsy() -> IsFalsyMatcher:
    """Matcher for a falsy value."""
    return IsFalsyMatcher()

has_length staticmethod

has_length(length: int) -> HasLengthMatcher

Matcher for a value whose len() equals length.

Source code in assertpy2/matchers.py

@staticmethod
def has_length(length: int) -> HasLengthMatcher:
    """Matcher for a value whose ``len()`` equals ``length``."""
    return HasLengthMatcher(length)

is_empty staticmethod

is_empty() -> IsEmptyMatcher

Matcher for an empty value (len() == 0).

Source code in assertpy2/matchers.py

@staticmethod
def is_empty() -> IsEmptyMatcher:
    """Matcher for an empty value (``len() == 0``)."""
    return IsEmptyMatcher()

is_not_empty staticmethod

is_not_empty() -> IsNotEmptyMatcher

Matcher for a non-empty value (len() > 0).

Source code in assertpy2/matchers.py

@staticmethod
def is_not_empty() -> IsNotEmptyMatcher:
    """Matcher for a non-empty value (``len() > 0``)."""
    return IsNotEmptyMatcher()

is_positive staticmethod

is_positive() -> IsPositiveMatcher

Matcher for a value greater than zero.

Source code in assertpy2/matchers.py

@staticmethod
def is_positive() -> IsPositiveMatcher:
    """Matcher for a value greater than zero."""
    return IsPositiveMatcher()

is_negative staticmethod

is_negative() -> IsNegativeMatcher

Matcher for a value less than zero.

Source code in assertpy2/matchers.py

@staticmethod
def is_negative() -> IsNegativeMatcher:
    """Matcher for a value less than zero."""
    return IsNegativeMatcher()

is_zero staticmethod

is_zero() -> IsZeroMatcher

Matcher for a value equal to zero.

Source code in assertpy2/matchers.py

@staticmethod
def is_zero() -> IsZeroMatcher:
    """Matcher for a value equal to zero."""
    return IsZeroMatcher()

is_even staticmethod

is_even() -> IsEvenMatcher

Matcher for an even integer.

Source code in assertpy2/matchers.py

@staticmethod
def is_even() -> IsEvenMatcher:
    """Matcher for an even integer."""
    return IsEvenMatcher()

is_odd staticmethod

is_odd() -> IsOddMatcher

Matcher for an odd integer.

Source code in assertpy2/matchers.py

@staticmethod
def is_odd() -> IsOddMatcher:
    """Matcher for an odd integer."""
    return IsOddMatcher()

is_divisible_by staticmethod

is_divisible_by(divisor: int) -> IsDivisibleByMatcher

Matcher for an integer divisible by divisor.

Source code in assertpy2/matchers.py

@staticmethod
def is_divisible_by(divisor: int) -> IsDivisibleByMatcher:
    """Matcher for an integer divisible by ``divisor``."""
    return IsDivisibleByMatcher(divisor)

is_callable staticmethod

is_callable() -> IsCallableMatcher

Matcher for a callable object.

Source code in assertpy2/matchers.py

@staticmethod
def is_callable() -> IsCallableMatcher:
    """Matcher for a callable object."""
    return IsCallableMatcher()

is_in staticmethod

is_in(*values: object) -> IsInMatcher

Matcher for a value present in values.

Parameters:

Name	Type	Description	Default
*values	object	the candidate values; the matched value must equal one of them	()

Source code in assertpy2/matchers.py

@staticmethod
def is_in(*values: object) -> IsInMatcher:
    """Matcher for a value present in ``values``.

    Args:
        *values: the candidate values; the matched value must equal one of them
    """
    return IsInMatcher(*values)

has_property staticmethod

has_property(
    name: str, matcher: Matcher | None = None
) -> HasPropertyMatcher

Matcher for an object with attribute name, optionally matching matcher.

Parameters:

Name	Type	Description	Default
name	str	the attribute name the object must have	required
matcher	Matcher | None	optional matcher the attribute value must satisfy; if None, only the presence of the attribute is checked	None

Source code in assertpy2/matchers.py

@staticmethod
def has_property(name: str, matcher: Matcher | None = None) -> HasPropertyMatcher:
    """Matcher for an object with attribute ``name``, optionally matching ``matcher``.

    Args:
        name: the attribute name the object must have
        matcher: optional matcher the attribute value must satisfy; if ``None``,
            only the presence of the attribute is checked
    """
    return HasPropertyMatcher(name, matcher)

contains_string staticmethod

contains_string(substring: str) -> ContainsStringMatcher

Matcher for a string containing substring.

Source code in assertpy2/matchers.py

@staticmethod
def contains_string(substring: str) -> ContainsStringMatcher:
    """Matcher for a string containing ``substring``."""
    return ContainsStringMatcher(substring)

matches_regex staticmethod

matches_regex(pattern: str) -> MatchesRegexMatcher

Matcher for a string in which pattern is found (re.search).

Source code in assertpy2/matchers.py

@staticmethod
def matches_regex(pattern: str) -> MatchesRegexMatcher:
    """Matcher for a string in which ``pattern`` is found (``re.search``)."""
    return MatchesRegexMatcher(pattern)

starts_with staticmethod

starts_with(prefix: str) -> StartsWithMatcher

Matcher for a string starting with prefix.

Source code in assertpy2/matchers.py

@staticmethod
def starts_with(prefix: str) -> StartsWithMatcher:
    """Matcher for a string starting with ``prefix``."""
    return StartsWithMatcher(prefix)

ends_with staticmethod

ends_with(suffix: str) -> EndsWithMatcher

Matcher for a string ending with suffix.

Source code in assertpy2/matchers.py

@staticmethod
def ends_with(suffix: str) -> EndsWithMatcher:
    """Matcher for a string ending with ``suffix``."""
    return EndsWithMatcher(suffix)

all_of staticmethod

all_of(*matchers: Matcher) -> AllOfMatcher

Matcher that holds when every one of matchers matches (the & operator).

Source code in assertpy2/matchers.py

@staticmethod
def all_of(*matchers: Matcher) -> AllOfMatcher:
    """Matcher that holds when every one of ``matchers`` matches (the ``&`` operator)."""
    return AllOfMatcher(*matchers)

any_of staticmethod

any_of(*matchers: Matcher) -> AnyOfMatcher

Matcher that holds when at least one of matchers matches (the | operator).

Source code in assertpy2/matchers.py

@staticmethod
def any_of(*matchers: Matcher) -> AnyOfMatcher:
    """Matcher that holds when at least one of ``matchers`` matches (the ``|`` operator)."""
    return AnyOfMatcher(*matchers)

not_ staticmethod

not_(matcher: Matcher) -> NotMatcher

Matcher that inverts matcher (the ~ operator).

Source code in assertpy2/matchers.py

@staticmethod
def not_(matcher: Matcher) -> NotMatcher:
    """Matcher that inverts ``matcher`` (the ``~`` operator)."""
    return NotMatcher(matcher)

ignore staticmethod

ignore() -> IgnoreMatcher

Matcher that accepts anything; useful as a placeholder in structure specs.

Source code in assertpy2/matchers.py

@staticmethod
def ignore() -> IgnoreMatcher:
    """Matcher that accepts anything; useful as a placeholder in ``structure`` specs."""
    return IgnoreMatcher()

is_uuid staticmethod

is_uuid() -> IsUuidMatcher

Matcher for a string parseable as a UUID.

Source code in assertpy2/matchers.py

@staticmethod
def is_uuid() -> IsUuidMatcher:
    """Matcher for a string parseable as a UUID."""
    return IsUuidMatcher()

is_non_empty_string staticmethod

is_non_empty_string() -> IsNonEmptyStringMatcher

Matcher for a non-empty string.

Source code in assertpy2/matchers.py

@staticmethod
def is_non_empty_string() -> IsNonEmptyStringMatcher:
    """Matcher for a non-empty string."""
    return IsNonEmptyStringMatcher()

each_item staticmethod

each_item(matcher: Matcher) -> EachMatcher

Matcher for an iterable whose every item matches matcher.

Parameters:

Name	Type	Description	Default
matcher	Matcher	the matcher each item of the iterable must satisfy; a non-iterable value never matches	required

Source code in assertpy2/matchers.py

@staticmethod
def each_item(matcher: Matcher) -> EachMatcher:
    """Matcher for an iterable whose every item matches ``matcher``.

    Args:
        matcher: the matcher each item of the iterable must satisfy; a non-iterable
            value never matches
    """
    return EachMatcher(matcher)

structure staticmethod

structure(spec: dict[Any, Any]) -> StructureMatcher

Matcher for a dict matching spec.

Parameters:

Name	Type	Description	Default
spec	dict[Any, Any]	dict whose values are matchers, raw values (compared with ==), or nested dict specs. Keys present in the value but absent from the spec are ignored.	required

Examples:

Usage:

assert_that(user).satisfies(
    match.structure({"id": match.is_instance_of(int), "name": "Alice"})
)

Source code in assertpy2/matchers.py

@staticmethod
def structure(spec: dict[Any, Any]) -> StructureMatcher:
    """Matcher for a dict matching ``spec``.

    Args:
        spec: dict whose values are matchers, raw values (compared with ``==``),
            or nested dict specs. Keys present in the value but absent from the spec are ignored.

    Examples:
        Usage:

            assert_that(user).satisfies(
                match.structure({"id": match.is_instance_of(int), "name": "Alice"})
            )
    """
    return StructureMatcher(spec)