Python API

recursive_diff.recursive_diff(lhs: Any, rhs: Any, *, rel_tol: float = 1e-09, abs_tol: float = 0.0, brief_dims: Collection[Hashable] | Literal['all'] = ()) → Iterator[str]

Compare two objects and yield all differences. The two objects must any of:

Special treatment is reserved to different types:

  • floats and ints are compared with tolerance, using math.isclose()

  • NaN equals to NaN

  • bools are only equal to other bools

  • numpy arrays are compared elementwise and with tolerance, also testing the dtype

  • pandas and xarray objects are compared elementwise, with tolerance, and without order. Duplicate indices are not supported.

  • xarray dimensions and variables are compared without order

  • collections (list, tuple, dict, set, frozenset) are recursively descended into

  • generic/unknown objects are compared with ==

Custom classes can be registered to benefit from the above behaviour; see cast().

Parameters:

  • lhs – left-hand-side data structure

  • rhs – right-hand-side data structure

  • rel_tol (float) – relative tolerance when comparing numbers. Applies to floats, integers, and all numpy-based data.

  • abs_tol (float) – absolute tolerance when comparing numbers. Applies to floats, integers, and all numpy-based data.

  • brief_dims –

    One of:

    • collection of strings representing xarray dimensions. If one or more differences are found along one of these dimensions, only one message will be reported, stating the differences count.

    • ”all”, to produce one line only for every xarray variable that differs

    Omit to output a line for every single different cell.

Yields strings containing difference messages, prepended by the path to the point that differs.

recursive_diff.recursive_eq(lhs: Any, rhs: Any, rel_tol: float = 1e-09, abs_tol: float = 0.0) → None

Wrapper around recursive_diff(). Print out all differences and finally assert that there are none.

recursive_diff.cast(obj: object, brief_dims: Collection[Hashable]) → object
recursive_diff.cast(obj: integer, brief_dims: Collection[Hashable]) → int
recursive_diff.cast(obj: floating, brief_dims: Collection[Hashable]) → float
recursive_diff.cast(obj: ndarray, brief_dims: Collection[Hashable]) → dict[str, object]
recursive_diff.cast(obj: Series, brief_dims: Collection[Hashable]) → dict[str, object]
recursive_diff.cast(obj: DataFrame, brief_dims: Collection[Hashable]) → dict[str, object]
recursive_diff.cast(obj: DataArray, brief_dims: Collection[Hashable]) → object
recursive_diff.cast(obj: Dataset, brief_dims: Collection[Hashable]) → dict[str, object]
recursive_diff.cast(obj: MultiIndex, brief_dims: Collection[Hashable]) → dict[str, object]
recursive_diff.cast(obj: RangeIndex, brief_dims: Collection[Hashable]) → RangeIndex
recursive_diff.cast(obj: Index, brief_dims: Collection[Hashable]) → DataArray
recursive_diff.cast(obj: frozenset, brief_dims: Collection[Hashable]) → set
recursive_diff.cast(obj: tuple, brief_dims: Collection[Hashable]) → list

Helper function of recursive_diff().

Cast objects into simpler object types:

The data will be potentially wrapped by a dict to hold the various attributes and marked so that it doesn’t trigger an infinite recursion.

  • Do nothing for any other object types.

Parameters:

  • obj – complex object that must be simplified

  • brief_dims – xarray dimensions that must be compacted. See documentation on recursive_diff().

Returns:

simpler object to compare