Skip to content

Data frame & array assertions

Equality assertions for pandas / polars data frames and numpy arrays (requires the data extra).

Fluent assertions for pandas/polars frames and numpy arrays (optional [data] extra).

is_frame_equal 

is_frame_equal(expected: object, **options: Any) -> Self

Asserts that a pandas/polars DataFrame or Series equals expected.

Delegates to the owning library's own assert_frame_equal / assert_series_equal, so all comparison semantics (dtype strictness, row/column order, tolerance, categoricals, ...) are the library's. Any keyword options are passed straight through.

Parameters:

Name Type Description Default
expected object

the expected frame/series (same library as val)

 required
**options Any

keyword options forwarded to the library's assert_frame_equal / assert_series_equal (e.g. check_dtype=False, check_exact=False, rtol=1e-3)

 {}

Examples:

Usage:

import pandas as pd

assert_that(pd.DataFrame({"a": [1, 2]})).is_frame_equal(pd.DataFrame({"a": [1, 2]}))
assert_that(actual).is_frame_equal(expected, check_dtype=False)

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if the frames/series are not equal (carrying the library's own diff message)
TypeError

if val is not a pandas or polars DataFrame/Series
ImportError

if the owning library is not installed
Source code in assertpy2/dataframe.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def is_frame_equal(self, expected: object, **options: Any) -> Self:
    """Asserts that a pandas/polars ``DataFrame`` or ``Series`` equals *expected*.

    Delegates to the owning library's own ``assert_frame_equal`` / ``assert_series_equal``, so all
    comparison semantics (dtype strictness, row/column order, tolerance, categoricals, ...) are the
    library's.  Any keyword options are passed straight through.

    Args:
        expected: the expected frame/series (same library as val)
        **options: keyword options forwarded to the library's ``assert_frame_equal`` /
            ``assert_series_equal`` (e.g. ``check_dtype=False``, ``check_exact=False``, ``rtol=1e-3``)

    Examples:
        Usage:

            import pandas as pd

            assert_that(pd.DataFrame({"a": [1, 2]})).is_frame_equal(pd.DataFrame({"a": [1, 2]}))
            assert_that(actual).is_frame_equal(expected, check_dtype=False)

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

    Raises:
        AssertionError: if the frames/series are not equal (carrying the library's own diff message)
        TypeError: if val is not a pandas or polars ``DataFrame``/``Series``
        ImportError: if the owning library is not installed
    """
    actual = self.val
    root = type(actual).__module__.split(".", 1)[0]
    if root not in _FRAME_ROOTS:
        raise TypeError(
            f"is_frame_equal() expects a pandas or polars DataFrame/Series, but was <{type(actual).__name__}>."
        )
    library, testing = _load(root)
    if isinstance(actual, library.Series):
        assert_equal, label = testing.assert_series_equal, "Series"
    else:
        assert_equal, label = testing.assert_frame_equal, "DataFrame"
    try:
        assert_equal(actual, expected, **options)
    except AssertionError as exc:
        return self.error(f"Expected the {label} to equal the expected one, but they differ:\n{exc}")
    return self

is_array_equal 

is_array_equal(expected: object) -> Self

Asserts that val equals expected element-wise, via numpy's assert_array_equal.

Works on any array-likes numpy can coerce (ndarray, nested lists, ...); shape and every element must match exactly (with NaN treated as equal, per numpy).

Parameters:

Name Type Description Default
expected object

the expected array-like

 required

Examples:

Usage:

import numpy as np

assert_that(np.array([1, 2, 3])).is_array_equal(np.array([1, 2, 3]))

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if the arrays are not equal (carrying numpy's own diff message)
ImportError

if numpy is not installed
Source code in assertpy2/dataframe.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def is_array_equal(self, expected: object) -> Self:
    """Asserts that val equals *expected* element-wise, via numpy's ``assert_array_equal``.

    Works on any array-likes numpy can coerce (``ndarray``, nested lists, ...); shape and every
    element must match exactly (with ``NaN`` treated as equal, per numpy).

    Args:
        expected: the expected array-like

    Examples:
        Usage:

            import numpy as np

            assert_that(np.array([1, 2, 3])).is_array_equal(np.array([1, 2, 3]))

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

    Raises:
        AssertionError: if the arrays are not equal (carrying numpy's own diff message)
        ImportError: if numpy is not installed
    """
    _, testing = _load("numpy")
    try:
        testing.assert_array_equal(self.val, expected)
    except AssertionError as exc:
        return self.error(f"Expected the arrays to be equal, but they differ:\n{exc}")
    return self

is_array_close_to 

is_array_close_to(
    expected: object,
    *,
    rtol: float = 1e-05,
    atol: float = 1e-08,
    equal_nan: bool = False,
) -> Self

Asserts that val is element-wise close to expected, via numpy's assert_allclose.

The float-tolerant counterpart to is_array_equal(), for comparing computed arrays.

Parameters:

Name Type Description Default
expected object

the expected array-like

 required
rtol float

relative tolerance (numpy default 1e-05)

 1e-05
atol float

absolute tolerance (numpy default 1e-08)

 1e-08
equal_nan bool

whether NaN in the same position compares equal

 False

Examples:

Usage:

import numpy as np

assert_that(np.array([1.0, 2.0])).is_array_close_to(np.array([1.0, 2.0000001]))

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if the arrays are not close (carrying numpy's own diff message)
ImportError

if numpy is not installed
Source code in assertpy2/dataframe.py 
121
122
123
124
125
126
127
128
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
def is_array_close_to(
    self, expected: object, *, rtol: float = 1e-05, atol: float = 1e-08, equal_nan: bool = False
) -> Self:
    """Asserts that val is element-wise close to *expected*, via numpy's ``assert_allclose``.

    The float-tolerant counterpart to [`is_array_equal()`][assertpy2.dataframe.DataFrameMixin.is_array_equal],
    for comparing computed arrays.

    Args:
        expected: the expected array-like
        rtol: relative tolerance (numpy default ``1e-05``)
        atol: absolute tolerance (numpy default ``1e-08``)
        equal_nan: whether ``NaN`` in the same position compares equal

    Examples:
        Usage:

            import numpy as np

            assert_that(np.array([1.0, 2.0])).is_array_close_to(np.array([1.0, 2.0000001]))

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

    Raises:
        AssertionError: if the arrays are not close (carrying numpy's own diff message)
        ImportError: if numpy is not installed
    """
    _, testing = _load("numpy")
    try:
        testing.assert_allclose(self.val, expected, rtol=rtol, atol=atol, equal_nan=equal_nan)
    except AssertionError as exc:
        return self.error(f"Expected the arrays to be close, but they differ:\n{exc}")
    return self