API reference

compyre

assert_equal(actual, expected, aliases=None, **kwargs)

Equality assertion of the inputs.

Info

This function is a thin wrapper around compyre.api.assert_equal using compyre.default_unpack_fns and compyre.default_equal_fns. See compyre.api.assert_equal for a description of the remaining arguments.

Raises:

Type	Description
AssertionError	If any input pair is not equal.

default_equal_fns()

Return a list of available builtin equality check functions.

Returns:

Type	Description
list[Callable[..., EqualFnResult]]	The following unpacking functions in order if their requirements are met compyre.builtin.equal_fns.numpy_ndarray compyre.builtin.equal_fns.pandas_dataframe compyre.builtin.equal_fns.pandas_series compyre.builtin.equal_fns.torch_tensor compyre.builtin.equal_fns.builtins_number compyre.builtin.equal_fns.builtins_object

default_unpack_fns()

Return a list of available builtin unpacking functions.

Returns:

Type	Description
list[Callable[..., UnpackFnResult]]	The following unpacking functions in order if their requirements are met compyre.builtin.unpack_fns.pydantic_model compyre.builtin.unpack_fns.dataclasses_dataclass compyre.builtin.unpack_fns.collections_ordered_dict compyre.builtin.unpack_fns.collections_mapping compyre.builtin.unpack_fns.collections_sequence

is_equal(actual, expected, aliases=None, **kwargs)

Boolean equality check of the inputs.

Info

This function is a thin wrapper around compyre.api.is_equal using compyre.default_unpack_fns and compyre.default_equal_fns. See compyre.api.is_equal for a description of the remaining arguments.

Returns:

Type	Description
bool	Whether the inputs are equal.

compyre.api

EqualFnResult = bool | None | Exception module-attribute

Return type of an equality function.

• None indicates that the equality function cannot handle the input compyre.api.Pair.
• True indicates that the input compyre.api.Pair is equal.
• Both False and any Exception indicate that the input compyre.api.Pair is not equal, with the latter being able to convey the reason.

UnpackFnResult = Sequence[Pair] | None | Exception module-attribute

Return type of an unpacking function.

• None indicates that the function cannot handle the input compyre.api.Pair.
• Any Exception indicates that the function can generally handle the input compyre.api.Pair, but something is wrong.

CompareError(pair, exception) dataclass

Comparison exception with pair that caused it.

CompyreError

Exception base class for errors originating from compyre.

Pair(index, actual, expected) dataclass

Pair of values to be unpacked or compared for equality with position information.

Attributes:

Name	Type	Description
index	tuple[str | int, ...]	Position of the pair in the overall comparison.
actual	Any	Actual value.
expected	Any	Expected value.

assert_equal(actual, expected, *, unpack_fns, equal_fns, aliases=None, **kwargs)

Equality assertion of the inputs.

Info

See compyre.api.compare for a description of the arguments.

Raises:

Type	Description
CompyreError	If any input pair cannot be handled.
AssertionError	If any input pair is not equal.
Exception	Any exception raised by compyre.api.compare.

compare(actual, expected, *, unpack_fns, equal_fns, aliases=None, **kwargs)

Low-level comparison of the inputs.

The unpack_fns and equal_fns are applied depth-first to the inputs.

Parameters:

Name	Type	Description	Default
actual	Any	Actual input.	required
expected	Any	Expected input.	required
unpack_fns	Sequence[Callable[..., UnpackFnResult]]	Unpacking functions to be used on the inputs. See note below for acceptable signatures.	required
equal_fns	Sequence[Callable[..., EqualFnResult]]	Equality functions to be used on the inputs. See note below for acceptable signatures. If a falsy value is returned, it will be replaced by an AssertionError with a default message.	required
aliases	Mapping[Alias, Any] | None	Aliases and values to be passed to the unpack_fns and equal_fns.	None
**kwargs	Any	Keyword arguments to be passed to the unpack_fns and equal_fns.	{}

Note

The unpack_fns and equal_fns have to be callable with a single compyre.api.Pair as positional argument as well as optionally keyword arguments that will be set by the aliases and kwargs.

Returns:

Type	Description
list[CompareError]	List of all exceptions returned and not raised by the unpack_fns and equal_fns with the index of the corresponding compyre.api.Pair. If all unpack_fns and equal_fns return None, i.e. cannot handle it, a compyre.api.CompyreError is included.

Raises:

Type	Description
TypeError	If the unpack_fns and equal_fns cannot be called as described above.
TypeError	If any parameter of the unpack_fns and equal_fns has no default, but no value was passed through aliases or kwargs.
TypeError	If any value passed to aliases or kwargs is unused by the unpack_fns and equal_fns.

is_equal(actual, expected, *, unpack_fns, equal_fns, aliases=None, **kwargs)

Boolean equality check of the inputs.

Info

See compyre.api.compare for a description of the arguments.

Returns:

Type	Description
bool	Whether the inputs are equal.

Raises:

Type	Description
CompyreError	If any input pair cannot be handled.
Exception	Any exception raised by compyre.api.compare.

compyre.builtin.unpack_fns

collections_mapping(p)

Unpack collections.abc.Mappings.

Parameters:

Name	Type	Description	Default
p	Pair	Pair to be unpacked.	required

Returns:

Type	Description
None	If p.actual and p.expected are not collections.abc.Mappings.
list[Pair]	The actual and expected values of each pair are the corresponding values of the input mappings, while the index is p.index extended by the corresponding key.
ValueError	If the keys of p.actual and p.expected mismatch.

collections_ordered_dict(p)

Unpack collections.OrderedDicts.

Warning

Since a collections.OrderedDict is a collections.abc.Mapping, this function must be placed before compyre.builtin.unpack_fns.collections_mapping or it will be shadowed.

Parameters:

Name	Type	Description	Default
p	Pair	Pair to be unpacked.	required

Returns:

Type	Description
None	If p.actual and p.expected are not collections.abc.Sequences.
list[Pair]	The actual and expected values of each pair are the corresponding values of the inputs, while the index is p.index extended by the corresponding key.
ValueError	If the ordered keys of p.actual and p.expected mismatch.

collections_sequence(p)

Unpack collections.abc.Sequences.

Parameters:

Name	Type	Description	Default
p	Pair	Pair to be unpacked.	required

Returns:

Type	Description
None	If p.actual and p.expected are not collections.abc.Sequences.
list[Pair]	The actual and expected values of each pair are the corresponding items of the input sequences, while the index is p.index extended by the corresponding index.
ValueError	If the length of p.actual and p.expected mismatch.

dataclasses_dataclass(p)

Unpack @dataclasses.dataclasses using dataclasses.asdict.

Parameters:

Name	Type	Description	Default
p	Pair	Pair to be unpacked.	required

Returns:

Type	Description
None	If p.actual and p.expected are not @dataclasses.dataclasses.
list[Pair]	The actual and expected values of each pair are the corresponding values of the input objects, while the index is p.index extended by the corresponding field name.
ValueError	If the fields of p.actual and p.expected mismatch.

pydantic_model(p)

Unpack pydantic.BaseModels using pydantic.BaseModel.model_dump.

Parameters:

Name	Type	Description	Default
p	Pair	Pair to be unpacked.	required

Returns:

Type	Description
None	If p.actual and p.expected are not pydantic.BaseModels.
list[Pair]	The actual and expected values of each pair are the corresponding values of the input models, while the index is p.index extended by the corresponding field name.
ValueError	If the fields of p.actual and p.expected mismatch.
Exception	Any Exception raised by pydantic.BaseModel.model_dump for the input pair.

Raises:

Type	Description
RuntimeError	If pydantic >=2, <3 is not available.

compyre.builtin.equal_fns

builtins_number(p, /, *, rel_tol=1e-09, abs_tol=0.0)

Check equality for int, float, complex numbers using math.isclose or cmath.isclose.

Parameters:

Name	Type	Description	Default
p	Pair	Pair to be compared.	required
rel_tol	float	Relative tolerance. See math.isclose or cmath.isclose for details. Can also be set through compyre.alias.RELATIVE_TOLERANCE.	1e-09
abs_tol	float	Absolute tolerance. See math.isclose or cmath.isclose for details. Can also be set through compyre.alias.ABSOLUTE_TOLERANCE.	0.0

Returns:

Type	Description
None	If p.actual and p.expected are not ints, floats, or complexs.
True	If math.isclose or cmath.isclose returns True for the input pair.
AssertionError	If math.isclose or cmath.isclose returns False for the input pair.

builtins_object(p, /, *, identity_fallback=True)

Check equality for arbitrary objects.

Info

• The equality check is performed as actual == expected
• The identity check is performed as actual is expected

Warning

This function returns a non-None value for any input pair and thus will shadow any other equality function coming after it in the list of equal_fns in compyre.api.compare or related functions.

Parameters:

Name	Type	Description	Default
p	Pair	Pair to be compared.	required
identity_fallback	bool	Whether to perform identity check of p if the equality check raises any Exception.	True

Returns:

Type	Description
True	Whether the equality check, or if identity_fallback is set, the identity check returns True.
AssertionError	Whether the equality check, and if identity_fallback is set, the identity check returns False.
Exception	Any Exception raised by the equality check if identity_fallback is not set.

numpy_ndarray(p, /, *, rtol=1e-07, atol=0.0, equal_nan=True, verbose=True)

Check equality for numpy.ndarrays using numpy.testing.assert_allclose.

Parameters:

Name	Type	Description	Default
p	Pair	Pair to be compared.	required
rtol	float	Relative tolerance. See numpy.testing.assert_allclose for details. Can also be set through compyre.alias.RELATIVE_TOLERANCE.	1e-07
atol	float	Absolute tolerance. See numpy.testing.assert_allclose for details. Can also be set through compyre.alias.ABSOLUTE_TOLERANCE.	0.0
equal_nan	bool	Whether two NaN values are considered equal. Can also be set through compyre.alias.NAN_EQUALITY.	True
verbose	bool	Whether mismatching values are included in the error message.	True

Returns:

Type	Description
None	If p.actual and p.expected are not numpy.ndarrays.
True	If numpy.testing.assert_allclose returns without error for the input pair.
AssertionError	Any AssertionError raised by numpy.testing.assert_allclose for the input pair.

Raises:

Type	Description
RuntimeError	If numpy is not available.

pandas_dataframe(p, /, *, rtol=1e-05, atol=1e-08)

Check equality for pandas.DataFrames using pandas.testing.assert_frame_equal.

Parameters:

Name	Type	Description	Default
p	Pair	Pair to be compared.	required
rtol	float	Relative tolerance. See pandas.testing.assert_frame_equal for details. Can also be set through compyre.alias.RELATIVE_TOLERANCE.	1e-05
atol	float	Absolute tolerance. See pandas.testing.assert_frame_equal for details. Can also be set through compyre.alias.ABSOLUTE_TOLERANCE.	1e-08

Returns:

Type	Description
None	If [p.actual and p.expected are not pandas.DataFrames.
True	If pandas.testing.assert_frame_equal returns without error for the input pair.
AssertionError	Any AssertionError raised by pandas.testing.assert_frame_equal for the input pair.

Raises:

Type	Description
RuntimeError	If pandas is not available.

pandas_series(p, /, *, rtol=1e-05, atol=1e-08)

Check equality for pandas.Seriess using pandas.testing.assert_series_equal.

Parameters:

Name	Type	Description	Default
p	Pair	Pair to be compared.	required
rtol	float	Relative tolerance. See pandas.testing.assert_series_equal for details. Can also be set through compyre.alias.RELATIVE_TOLERANCE.	1e-05
atol	float	Absolute tolerance. See pandas.testing.assert_series_equal for details. Can also be set through compyre.alias.ABSOLUTE_TOLERANCE.	1e-08

Returns:

Type	Description
None	If p.actual and p.expected are not pandas.Seriess.
True	If pandas.testing.assert_series_equal returns without error for the input pair.
AssertionError	Any AssertionError raised by pandas.testing.assert_series_equal for the input pair.

Raises:

Type	Description
RuntimeError	If pandas is not available.

torch_tensor(p, /, *, rtol=None, atol=None, equal_nan=False)

Check equality for torch.Tensors using torch.testing.assert_close.

Parameters:

Name	Type	Description	Default
p	Pair	Pair to be compared.	required
rtol	float | None	Relative tolerance. If specified atol must also be specified. If omitted, default values based on the dtype are selected. See torch.testing.assert_close for details. Can also be set through compyre.alias.RELATIVE_TOLERANCE.	None
atol	float | None	Absolute tolerance. If specified rtol must also be specified. If omitted, default values based on the dtype are selected. See torch.testing.assert_close for details. Can also be set through compyre.alias.ABSOLUTE_TOLERANCE.	None
equal_nan	bool	Whether two NaN values are considered equal. Can also be set through compyre.alias.NAN_EQUALITY.	False

Returns:

Type	Description
None	If p.actual and p.expected are not torch.Tensors.
True	If torch.testing.assert_close returns without error for the input pair.
AssertionError	Any AssertionError raised by torch.testing.assert_close for the input pair.

Raises:

Type	Description
RuntimeError	If torch is not available.

compyre.alias

ABSOLUTE_TOLERANCE = Alias('absolute_tolerance') module-attribute

Alias for absolute tolerances in numerical comparisons.

NAN_EQUALITY = Alias('nan_equality') module-attribute

Alias for NaN equality checking in numerical comparisons.

RELATIVE_TOLERANCE = Alias('relative_tolerance') module-attribute

Alias for relative tolerances in numerical comparisons.

Alias(name='')

Alias class.

Parameters:

Name	Type	Description	Default
name	str	Name of the alias for debugging.	''

compyre.utils

both_isinstance(pair, t)

Check whether both values in a pair are instances of a given type.

Parameters:

Name	Type	Description	Default
pair	Pair	Pair to be checked	required
t	type | tuple[type, ...]	The type or tuple of types to check the pair's values against.	required

Returns:

Type	Description
bool	Whether both p.actual and p.expected are instances of t.

either_isinstance(pair, t)

Check whether either value in a pair is an instance of a given type.

Parameters:

Name	Type	Description	Default
pair	Pair	Pair to be checked	required
t	type | tuple[type, ...]	The type or tuple of types to check the pair's values against.	required

Returns:

Type	Description
bool	Whether either p.actual or p.expected is an instances of t.