Numeric assertions

Assertions for int, float, and complex values.

Numeric assertions mixin.

is_zero

is_zero() -> Self

Asserts that val is numeric and is zero.

Examples:

Usage:

assert_that(0).is_zero()

Returns:

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

Raises:

Type	Description
AssertionError	if val is not zero

Source code in assertpy2/numeric.py

def is_zero(self) -> Self:
    """Asserts that val is numeric and is zero.

    Examples:
        Usage:

            assert_that(0).is_zero()

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

    Raises:
        AssertionError: if val is **not** zero
    """
    self._validate_number()
    return self.is_equal_to(0)

is_not_zero

is_not_zero() -> Self

Asserts that val is numeric and is not zero.

Examples:

Usage:

assert_that(1).is_not_zero()
assert_that(123.4).is_not_zero()

Returns:

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

Raises:

Type	Description
AssertionError	if val is zero

Source code in assertpy2/numeric.py

def is_not_zero(self) -> Self:
    """Asserts that val is numeric and is *not* zero.

    Examples:
        Usage:

            assert_that(1).is_not_zero()
            assert_that(123.4).is_not_zero()

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

    Raises:
        AssertionError: if val **is** zero
    """
    self._validate_number()
    return self.is_not_equal_to(0)

is_nan

is_nan() -> Self

Asserts that val is real number and is NaN (not a number).

Examples:

Usage:

assert_that(float('nan')).is_nan()
assert_that(float('inf') * 0).is_nan()

Returns:

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

Raises:

Type	Description
AssertionError	if val is not NaN

Source code in assertpy2/numeric.py

def is_nan(self) -> Self:
    """Asserts that val is real number and is ``NaN`` (not a number).

    Examples:
        Usage:

            assert_that(float('nan')).is_nan()
            assert_that(float('inf') * 0).is_nan()

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

    Raises:
        AssertionError: if val is **not** NaN
    """
    self._validate_number()
    self._validate_real()
    if not math.isnan(self.val):
        return self.error(f"Expected <{self.val}> to be <NaN>, but was not.")
    return self

is_not_nan

is_not_nan() -> Self

Asserts that val is real number and is not NaN (not a number).

Examples:

Usage:

assert_that(0).is_not_nan()
assert_that(123.4).is_not_nan()
assert_that(float('inf')).is_not_nan()

Returns:

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

Raises:

Type	Description
AssertionError	if val is NaN

Source code in assertpy2/numeric.py

def is_not_nan(self) -> Self:
    """Asserts that val is real number and is *not* ``NaN`` (not a number).

    Examples:
        Usage:

            assert_that(0).is_not_nan()
            assert_that(123.4).is_not_nan()
            assert_that(float('inf')).is_not_nan()

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

    Raises:
        AssertionError: if val **is** NaN
    """
    self._validate_number()
    self._validate_real()
    if math.isnan(self.val):
        return self.error("Expected not <NaN>, but was.")
    return self

is_inf

is_inf() -> Self

Asserts that val is real number and is Inf (infinity).

Examples:

Usage:

assert_that(float('inf')).is_inf()
assert_that(float('inf') * 1).is_inf()

Returns:

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

Raises:

Type	Description
AssertionError	if val is not Inf

Source code in assertpy2/numeric.py

def is_inf(self) -> Self:
    """Asserts that val is real number and is ``Inf`` (infinity).

    Examples:
        Usage:

            assert_that(float('inf')).is_inf()
            assert_that(float('inf') * 1).is_inf()

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

    Raises:
        AssertionError: if val is **not** Inf
    """
    self._validate_number()
    self._validate_real()
    if not math.isinf(self.val):
        return self.error(f"Expected <{self.val}> to be <Inf>, but was not.")
    return self

is_not_inf

is_not_inf() -> Self

Asserts that val is real number and is not Inf (infinity).

Examples:

Usage:

assert_that(0).is_not_inf()
assert_that(123.4).is_not_inf()
assert_that(float('nan')).is_not_inf()

Returns:

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

Raises:

Type	Description
AssertionError	if val is Inf

Source code in assertpy2/numeric.py

def is_not_inf(self) -> Self:
    """Asserts that val is real number and is *not* ``Inf`` (infinity).

    Examples:
        Usage:

            assert_that(0).is_not_inf()
            assert_that(123.4).is_not_inf()
            assert_that(float('nan')).is_not_inf()

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

    Raises:
        AssertionError: if val **is** Inf
    """
    self._validate_number()
    self._validate_real()
    if math.isinf(self.val):
        return self.error("Expected not <Inf>, but was.")
    return self

is_greater_than

is_greater_than(other: object) -> Self

Asserts that val is numeric and is greater than other.

Parameters:

Name	Type	Description	Default
other	object	the other date, expected to be less than val	required

Examples:

Usage:

assert_that(1).is_greater_than(0)
assert_that(123.4).is_greater_than(111.1)

For dates, behavior is identical to is_after():

import datetime

today = datetime.datetime.now()
yesterday = today - datetime.timedelta(days=1)

assert_that(today).is_greater_than(yesterday)

Returns:

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

Raises:

Type	Description
AssertionError	if val is not greater than other

Source code in assertpy2/numeric.py

def is_greater_than(self, other: object) -> Self:
    """Asserts that val is numeric and is greater than other.

    Args:
        other: the other date, expected to be less than val

    Examples:
        Usage:

            assert_that(1).is_greater_than(0)
            assert_that(123.4).is_greater_than(111.1)

        For dates, behavior is identical to [`is_after()`][assertpy2.date.DateMixin.is_after]:

            import datetime

            today = datetime.datetime.now()
            yesterday = today - datetime.timedelta(days=1)

            assert_that(today).is_greater_than(yesterday)

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

    Raises:
        AssertionError: if val is **not** greater than other
    """
    self._validate_compareable(other)
    if self.val <= other:
        return self.error(
            f"Expected <{_fmt_operand(self.val)}> to be greater than <{_fmt_operand(other)}>, but was not."
        )
    return self

is_greater_than_or_equal_to

is_greater_than_or_equal_to(other: object) -> Self

Asserts that val is numeric and is greater than or equal to other.

Parameters:

Name	Type	Description	Default
other	object	the other date, expected to be less than or equal to val	required

Examples:

Usage:

assert_that(1).is_greater_than_or_equal_to(0)
assert_that(1).is_greater_than_or_equal_to(1)
assert_that(123.4).is_greater_than_or_equal_to(111.1)

For dates, behavior is identical to is_after() except when equal:

import datetime

today = datetime.datetime.now()
yesterday = today - datetime.timedelta(days=1)

assert_that(today).is_greater_than_or_equal_to(yesterday)
assert_that(today).is_greater_than_or_equal_to(today)

Returns:

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

Raises:

Type	Description
AssertionError	if val is not greater than or equal to other

Source code in assertpy2/numeric.py

def is_greater_than_or_equal_to(self, other: object) -> Self:
    """Asserts that val is numeric and is greater than or equal to other.

    Args:
        other: the other date, expected to be less than or equal to val

    Examples:
        Usage:

            assert_that(1).is_greater_than_or_equal_to(0)
            assert_that(1).is_greater_than_or_equal_to(1)
            assert_that(123.4).is_greater_than_or_equal_to(111.1)

        For dates, behavior is identical to [`is_after()`][assertpy2.date.DateMixin.is_after] *except* when equal:

            import datetime

            today = datetime.datetime.now()
            yesterday = today - datetime.timedelta(days=1)

            assert_that(today).is_greater_than_or_equal_to(yesterday)
            assert_that(today).is_greater_than_or_equal_to(today)

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

    Raises:
        AssertionError: if val is **not** greater than or equal to other
    """
    self._validate_compareable(other)
    if self.val < other:
        return self.error(
            f"Expected <{_fmt_operand(self.val)}> to be greater than or equal to"
            f" <{_fmt_operand(other)}>, but was not."
        )
    return self

is_less_than

is_less_than(other: object) -> Self

Asserts that val is numeric and is less than other.

Parameters:

Name	Type	Description	Default
other	object	the other date, expected to be greater than val	required

Examples:

Usage:

assert_that(0).is_less_than(1)
assert_that(123.4).is_less_than(555.5)

For dates, behavior is identical to is_before():

import datetime

today = datetime.datetime.now()
yesterday = today - datetime.timedelta(days=1)

assert_that(yesterday).is_less_than(today)

Returns:

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

Raises:

Type	Description
AssertionError	if val is not less than other

Source code in assertpy2/numeric.py

def is_less_than(self, other: object) -> Self:
    """Asserts that val is numeric and is less than other.

    Args:
        other: the other date, expected to be greater than val

    Examples:
        Usage:

            assert_that(0).is_less_than(1)
            assert_that(123.4).is_less_than(555.5)

        For dates, behavior is identical to [`is_before()`][assertpy2.date.DateMixin.is_before]:

            import datetime

            today = datetime.datetime.now()
            yesterday = today - datetime.timedelta(days=1)

            assert_that(yesterday).is_less_than(today)

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

    Raises:
        AssertionError: if val is **not** less than other
    """
    self._validate_compareable(other)
    if self.val >= other:
        return self.error(
            f"Expected <{_fmt_operand(self.val)}> to be less than <{_fmt_operand(other)}>, but was not."
        )
    return self

is_less_than_or_equal_to

is_less_than_or_equal_to(other: object) -> Self

Asserts that val is numeric and is less than or equal to other.

Parameters:

Name	Type	Description	Default
other	object	the other date, expected to be greater than or equal to val	required

Examples:

Usage:

assert_that(1).is_less_than_or_equal_to(0)
assert_that(1).is_less_than_or_equal_to(1)
assert_that(123.4).is_less_than_or_equal_to(100.0)

For dates, behavior is identical to is_before() except when equal:

import datetime

today = datetime.datetime.now()
yesterday = today - datetime.timedelta(days=1)

assert_that(yesterday).is_less_than_or_equal_to(today)
assert_that(today).is_less_than_or_equal_to(today)

Returns:

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

Raises:

Type	Description
AssertionError	if val is not less than or equal to other

Source code in assertpy2/numeric.py

def is_less_than_or_equal_to(self, other: object) -> Self:
    """Asserts that val is numeric and is less than or equal to other.

    Args:
        other: the other date, expected to be greater than or equal to val

    Examples:
        Usage:

            assert_that(1).is_less_than_or_equal_to(0)
            assert_that(1).is_less_than_or_equal_to(1)
            assert_that(123.4).is_less_than_or_equal_to(100.0)

        For dates, behavior is identical to [`is_before()`][assertpy2.date.DateMixin.is_before]
        *except* when equal:

            import datetime

            today = datetime.datetime.now()
            yesterday = today - datetime.timedelta(days=1)

            assert_that(yesterday).is_less_than_or_equal_to(today)
            assert_that(today).is_less_than_or_equal_to(today)

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

    Raises:
        AssertionError: if val is **not** less than or equal to other
    """
    self._validate_compareable(other)
    if self.val > other:
        return self.error(
            f"Expected <{_fmt_operand(self.val)}> to be less than or equal to <{_fmt_operand(other)}>, but was not."
        )
    return self

is_positive

is_positive() -> Self

Asserts that val is numeric and is greater than zero.

Examples:

Usage:

assert_that(1).is_positive()
assert_that(123.4).is_positive()

Returns:

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

Raises:

Type	Description
AssertionError	if val is not positive

Source code in assertpy2/numeric.py

def is_positive(self) -> Self:
    """Asserts that val is numeric and is greater than zero.

    Examples:
        Usage:

            assert_that(1).is_positive()
            assert_that(123.4).is_positive()

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

    Raises:
        AssertionError: if val is **not** positive
    """
    return self.is_greater_than(0)

is_negative

is_negative() -> Self

Asserts that val is numeric and is less than zero.

Examples:

Usage:

assert_that(-1).is_negative()
assert_that(-123.4).is_negative()

Returns:

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

Raises:

Type	Description
AssertionError	if val is not negative

Source code in assertpy2/numeric.py

def is_negative(self) -> Self:
    """Asserts that val is numeric and is less than zero.

    Examples:
        Usage:

            assert_that(-1).is_negative()
            assert_that(-123.4).is_negative()

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

    Raises:
        AssertionError: if val is **not** negative
    """
    return self.is_less_than(0)

is_between

is_between(low: object, high: object) -> Self

Asserts that val is numeric and is between low and high.

Parameters:

Name	Type	Description	Default
low	object	the low value	required
high	object	the high value	required

Examples:

Usage:

assert_that(1).is_between(0, 2)
assert_that(123.4).is_between(111.1, 222.2)

For dates, works as expected:

import datetime

today = datetime.datetime.now()
middle = today - datetime.timedelta(hours=12)
yesterday = today - datetime.timedelta(days=1)

assert_that(middle).is_between(yesterday, today)

Returns:

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

Raises:

Type	Description
AssertionError	if val is not between low and high

Source code in assertpy2/numeric.py

def is_between(self, low: object, high: object) -> Self:
    """Asserts that val is numeric and is between low and high.

    Args:
        low: the low value
        high: the high value

    Examples:
        Usage:

            assert_that(1).is_between(0, 2)
            assert_that(123.4).is_between(111.1, 222.2)

        For dates, works as expected:

            import datetime

            today = datetime.datetime.now()
            middle = today - datetime.timedelta(hours=12)
            yesterday = today - datetime.timedelta(days=1)

            assert_that(middle).is_between(yesterday, today)

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

    Raises:
        AssertionError: if val is **not** between low and high
    """
    val_type = type(self.val)
    self._validate_between_args(val_type, low, high)

    if self.val < low or self.val > high:
        return self.error(
            f"Expected <{_fmt_operand(self.val)}> to be between"
            f" <{_fmt_operand(low)}> and <{_fmt_operand(high)}>, but was not."
        )
    return self

is_not_between

is_not_between(low: object, high: object) -> Self

Asserts that val is numeric and is not between low and high.

Parameters:

Name	Type	Description	Default
low	object	the low value	required
high	object	the high value	required

Examples:

Usage:

assert_that(1).is_not_between(2, 3)
assert_that(1.1).is_not_between(2.2, 3.3)

Returns:

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

Raises:

Type	Description
AssertionError	if val is between low and high

Source code in assertpy2/numeric.py

def is_not_between(self, low: object, high: object) -> Self:
    """Asserts that val is numeric and is *not* between low and high.

    Args:
        low: the low value
        high: the high value

    Examples:
        Usage:

            assert_that(1).is_not_between(2, 3)
            assert_that(1.1).is_not_between(2.2, 3.3)

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

    Raises:
        AssertionError: if val **is** between low and high
    """
    val_type = type(self.val)
    self._validate_between_args(val_type, low, high)

    if low <= self.val <= high:
        return self.error(
            f"Expected <{_fmt_operand(self.val)}> to not be between"
            f" <{_fmt_operand(low)}> and <{_fmt_operand(high)}>, but was."
        )
    return self

is_even

is_even() -> Self

Asserts that val is an integer and is even.

Examples:

Usage:

assert_that(0).is_even()
assert_that(2).is_even()
assert_that(-4).is_even()

Returns:

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

Raises:

Type	Description
AssertionError	if val is not even

Source code in assertpy2/numeric.py

def is_even(self) -> Self:
    """Asserts that val is an integer and is even.

    Examples:
        Usage:

            assert_that(0).is_even()
            assert_that(2).is_even()
            assert_that(-4).is_even()

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

    Raises:
        AssertionError: if val is **not** even
    """
    self._validate_int()
    if self.val % 2 != 0:
        return self.error(f"Expected <{self.val}> to be even, but was not.")
    return self

is_odd

is_odd() -> Self

Asserts that val is an integer and is odd.

Examples:

Usage:

assert_that(1).is_odd()
assert_that(3).is_odd()
assert_that(-5).is_odd()

Returns:

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

Raises:

Type	Description
AssertionError	if val is not odd

Source code in assertpy2/numeric.py

def is_odd(self) -> Self:
    """Asserts that val is an integer and is odd.

    Examples:
        Usage:

            assert_that(1).is_odd()
            assert_that(3).is_odd()
            assert_that(-5).is_odd()

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

    Raises:
        AssertionError: if val is **not** odd
    """
    self._validate_int()
    if self.val % 2 == 0:
        return self.error(f"Expected <{self.val}> to be odd, but was not.")
    return self

is_divisible_by

is_divisible_by(divisor: int) -> Self

Asserts that val is an integer and is divisible by divisor.

Parameters:

Name	Type	Description	Default
divisor	int	the divisor to check against (must be a non-zero integer)	required

Examples:

Usage:

assert_that(10).is_divisible_by(5)
assert_that(12).is_divisible_by(3)

Returns:

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

Raises:

Type	Description
AssertionError	if val is not divisible by divisor

Source code in assertpy2/numeric.py

def is_divisible_by(self, divisor: int) -> Self:
    """Asserts that val is an integer and is divisible by divisor.

    Args:
        divisor: the divisor to check against (must be a non-zero integer)

    Examples:
        Usage:

            assert_that(10).is_divisible_by(5)
            assert_that(12).is_divisible_by(3)

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

    Raises:
        AssertionError: if val is **not** divisible by divisor
    """
    self._validate_int()
    if isinstance(divisor, bool) or not isinstance(divisor, int):
        raise TypeError(f"given divisor arg must be an integer, got {type(divisor).__name__}")
    if divisor == 0:
        raise ValueError("given divisor arg must not be zero")
    if self.val % divisor != 0:
        return self.error(f"Expected <{self.val}> to be divisible by <{divisor}>, but was not.")
    return self

is_close_to

is_close_to(other, tolerance) -> Self

Asserts that val is numeric and is close to other within tolerance.

Parameters:

Name	Type	Description	Default
other	object	the other value, expected to be close to val within tolerance	required
tolerance	object	the tolerance	required

Examples:

Usage:

assert_that(123).is_close_to(100, 25)
assert_that(123.4).is_close_to(123, 0.5)

For dates, works as expected:

import datetime

today = datetime.datetime.now()
yesterday = today - datetime.timedelta(days=1)

assert_that(today).is_close_to(yesterday, datetime.timedelta(hours=36))

Returns:

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

Raises:

Type	Description
AssertionError	if val is not close to other within tolerance

Source code in assertpy2/numeric.py

def is_close_to(self, other, tolerance) -> Self:
    """Asserts that val is numeric and is close to other within tolerance.

    Args:
        other (object): the other value, expected to be close to val within tolerance
        tolerance (object): the tolerance

    Examples:
        Usage:

            assert_that(123).is_close_to(100, 25)
            assert_that(123.4).is_close_to(123, 0.5)

        For dates, works as expected:

            import datetime

            today = datetime.datetime.now()
            yesterday = today - datetime.timedelta(days=1)

            assert_that(today).is_close_to(yesterday, datetime.timedelta(hours=36))

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

    Raises:
        AssertionError: if val is **not** close to other within tolerance
    """
    self._validate_close_to_args(self.val, other, tolerance)

    if not isinstance(self.val, datetime.datetime) and (math.isnan(self.val) or math.isnan(other)):
        return self.error(
            f"Expected <{self.val}> to be close to <{other}> within tolerance <{tolerance}>, but was not."
        )
    if self.val < (other - tolerance) or self.val > (other + tolerance):
        if isinstance(self.val, datetime.datetime):
            return self.error(
                f"Expected <{_fmt_operand(self.val)}> to be close to"
                f" <{_fmt_operand(other)}> within tolerance"
                f" <{_fmt_tolerance(tolerance)}>, but was not."
            )
        else:
            return self.error(
                f"Expected <{self.val}> to be close to <{other}> within tolerance <{tolerance}>, but was not."
            )
    return self

is_not_close_to

is_not_close_to(other, tolerance) -> Self

Asserts that val is numeric and is not close to other within tolerance.

Parameters:

Name	Type	Description	Default
other	object	the other value	required
tolerance	object	the tolerance	required

Examples:

Usage:

assert_that(123).is_not_close_to(100, 22)
assert_that(123.4).is_not_close_to(123, 0.1)

Returns:

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

Raises:

Type	Description
AssertionError	if val is close to other within tolerance

Source code in assertpy2/numeric.py

def is_not_close_to(self, other, tolerance) -> Self:
    """Asserts that val is numeric and is *not* close to other within tolerance.

    Args:
        other (object): the other value
        tolerance (object): the tolerance

    Examples:
        Usage:

            assert_that(123).is_not_close_to(100, 22)
            assert_that(123.4).is_not_close_to(123, 0.1)

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

    Raises:
        AssertionError: if val **is** close to other within tolerance
    """
    self._validate_close_to_args(self.val, other, tolerance)

    if (other - tolerance) <= self.val <= (other + tolerance):
        if isinstance(self.val, datetime.datetime):
            return self.error(
                f"Expected <{_fmt_operand(self.val)}> to not be close to"
                f" <{_fmt_operand(other)}> within tolerance"
                f" <{_fmt_tolerance(tolerance)}>, but was."
            )
        else:
            return self.error(
                f"Expected <{self.val}> to not be close to <{other}> within tolerance <{tolerance}>, but was."
            )
    return self