Welcome to the AssertionLib documentation

Contents:

https://readthedocs.org/projects/assertionlib/badge/?version=latest

AssertionLib

A package for performing assertions and providing informative exception messages.

Installation

PyPi: pip install AssertionLib
GitHub: pip install git+https://github.com/nlesc-nano/AssertionLib

Usage

A comprehensive overview of all available assertion methods is provided in the documentation. A few examples of some basic assertion:

>>> import numpy as np
>>> from assertionlib import assertion

# Assert the output of specific callables
>>> assertion.eq(5, 5)  # 5 == 5
>>> assertion.lt(5, 6)  # 5 < 6
>>> assertion.gt(6, 5)  # 5 > 6
>>> assertion.isinstance(5, int)
>>> assertion.hasattr(5, '__init__')
>>> assertion.any([False, False, True])
>>> assertion.isfinite(1.0)

# Simply assert a value
>>> assertion(5 == 5)
>>> assertion(isinstance(5, int))

# Apply post-processing before conducting the assertion
>>> ar_large = np.ones(10)
>>> ar_small = np.zeros(10)
>>> assertion.gt(ar_large, ar_small, post_process=np.all)  # all(ar_large > ar_small)

# Perform an assertion which will raise an AssertionError
>>> assertion.eq(5, 6, message='Fancy custom error message')  # 5 == 6
Traceback (most recent call last):
  ...
AssertionError: output = eq(a, b); assert output

exception: AssertionError = AssertionError('Fancy custom error message')

output: bool = False
a: int = 5
b: int = 6

A few examples of AssertionErrors raised due to incorrect method signatures:

>>> from assertionlib import assertion

>>> assertion.len(5)
Traceback (most recent call last):
  ...
AssertionError: output = len(obj); assert output

exception: TypeError = TypeError("object of type 'int' has no len()")

output: NoneType = None
obj: int = 5

>>> from assertionlib import assertion

>>> assertion.eq(5, 5, 5, 5)
Traceback (most recent call last):
  ...
AssertionError: output = eq(a, b, _a, _b); assert output

exception: TypeError = TypeError('eq expected 2 arguments, got 4')

output: NoneType = None
a: int = 5
b: int = 5
_a: int = 5
_b: int = 5

A demonstration of the exception parameter. Providing an exception type will assert that the provided exception is raised during/before the assertion process:

>>> from assertionlib import assertion

>>> len(5)
Traceback (most recent call last):
  ...
TypeError: object of type 'int' has no len()

>>> from assertionlib import assertion

>>> assertion.len(5, exception=TypeError)  # i.e. len(5) should raise a TypeError
>>> assertion.len([5], exception=TypeError)
Traceback (most recent call last):
  ...
AssertionError: output = len(obj); assert output

exception: AssertionError = AssertionError("Failed to raise 'TypeError'")

output: int = 1
obj: list = [5]

Lastly, the output of custom callables can be asserted in one of the following two ways, supplying the callable to AssertionManager.assert() or creating a custom assertion method and adding it to an instance with AssertionManager.add_to_instance():

>>> from assertionlib import assertion

>>> def my_fancy_func(a: object) -> bool:
...     return False

# Approach #1, supply to-be asserted callable to assertion.assert_()
>>> assertion.assert_(my_fancy_func, 5)
Traceback (most recent call last):
  ...
AssertionError: output = my_fancy_func(a); assert output

exception: AssertionError = AssertionError(None)

output: bool = False
a: int = 5

>>> from assertionlib import assertion

# Approach #2, permanantly add a new bound method using assertion.add_to_instance()
>>> assertion.add_to_instance(my_fancy_func)
>>> assertion.my_fancy_func(5)
Traceback (most recent call last):
  ...
AssertionError: output = my_fancy_func(a); assert output

exception: AssertionError = AssertionError(None)

output: bool = False
a: int = 5

API

`assertionlib`

A package for performing assertion operations.

`assertionlib.dataclass`

A class with a number of generic pre-defined (magic) methods inspired by the builtin dataclasses module introduced in Python 3.7.

`assertionlib.functions`

Various functions related to the assertionlib.AssertionManager class.

`assertionlib.manager`

A module containing the actual assertionlib.AssertionManager class.

`assertionlib.ndrepr`

A module for holding the assertionlib.NDRepr class, a subclass of the builtin reprlib.Repr class.

Index

assertionlib.manager

A module containing the actual AssertionManager class.

Index

`assertion`	An instance of `AssertionManager`.
`AssertionManager`(repr_instance)	A class for performing assertions and providing informative exception messages.
`AssertionManager.assert_`(func, *args[, ...])	Perform the following assertion: `assert func(args, *kwargs)`.
`AssertionManager.__call__`(value, *[, ...])	Equivalent to `assert value`.
`AssertionManager.add_to_instance`(func[, ...])	Add a new custom assertion method to this instance.

Assertions based on the builtin operator module.

`AssertionManager.abs`	Perform the following assertion: `assert abs(a)`.
`AssertionManager.add`	Perform the following assertion: `assert add(a, b)`.
`AssertionManager.and_`	Perform the following assertion: `assert and_(a, b)`.
`AssertionManager.concat`	Perform the following assertion: `assert concat(a, b)`.
`AssertionManager.contains`	Perform the following assertion: `assert contains(a, b)`.
`AssertionManager.countOf`	Perform the following assertion: `assert countOf(a, b)`.
`AssertionManager.eq`	Perform the following assertion: `assert eq(a, b)`.
`AssertionManager.floordiv`	Perform the following assertion: `assert floordiv(a, b)`.
`AssertionManager.ge`	Perform the following assertion: `assert ge(a, b)`.
`AssertionManager.getitem`	Perform the following assertion: `assert getitem(a, b)`.
`AssertionManager.gt`	Perform the following assertion: `assert gt(a, b)`.
`AssertionManager.index`	Perform the following assertion: `assert index(a)`.
`AssertionManager.indexOf`	Perform the following assertion: `assert indexOf(a, b)`.
`AssertionManager.inv`	Perform the following assertion: `assert inv(a)`.
`AssertionManager.invert`	Perform the following assertion: `assert invert(a)`.
`AssertionManager.is_`	Perform the following assertion: `assert is_(a, b)`.
`AssertionManager.is_not`	Perform the following assertion: `assert is_not(a, b)`.
`AssertionManager.le`	Perform the following assertion: `assert le(a, b)`.
`AssertionManager.lshift`	Perform the following assertion: `assert lshift(a, b)`.
`AssertionManager.lt`	Perform the following assertion: `assert lt(a, b)`.
`AssertionManager.matmul`	Perform the following assertion: `assert matmul(a, b)`.
`AssertionManager.mod`	Perform the following assertion: `assert mod(a, b)`.
`AssertionManager.mul`	Perform the following assertion: `assert mul(a, b)`.
`AssertionManager.ne`	Perform the following assertion: `assert ne(a, b)`.
`AssertionManager.neg`	Perform the following assertion: `assert neg(a)`.
`AssertionManager.not_`	Perform the following assertion: `assert not_(a)`.
`AssertionManager.or_`	Perform the following assertion: `assert or_(a, b)`.
`AssertionManager.pos`	Perform the following assertion: `assert pos(a)`.
`AssertionManager.pow`	Perform the following assertion: `assert pow(a, b)`.
`AssertionManager.rshift`	Perform the following assertion: `assert rshift(a, b)`.
`AssertionManager.sub`	Perform the following assertion: `assert sub(a, b)`.
`AssertionManager.truediv`	Perform the following assertion: `assert truediv(a, b)`.
`AssertionManager.truth`	Perform the following assertion: `assert truth(a)`.
`AssertionManager.length_hint`	Perform the following assertion: `assert length_hint(obj, default=default)`.

Assertions based on the builtin os.path module.

`AssertionManager.isabs`	Perform the following assertion: `assert isabs(s)`.
`AssertionManager.isdir`	Perform the following assertion: `assert isdir(s)`.
`AssertionManager.isfile`	Perform the following assertion: `assert isfile(path)`.
`AssertionManager.islink`	Perform the following assertion: `assert islink(path)`.
`AssertionManager.ismount`	Perform the following assertion: `assert ismount(path)`.

Assertions based on the builtin math module.

`AssertionManager.allclose`	Perform the following assertion: `assert isclose(a, b, rel_tol=rel_tol, abs_tol=abs_tol)`.
`AssertionManager.isclose`	Perform the following assertion: `assert isclose(a, b, rel_tol=rel_tol, abs_tol=abs_tol)`.
`AssertionManager.isfinite`	Perform the following assertion: `assert isfinite(x)`.
`AssertionManager.isinf`	Perform the following assertion: `assert isinf(x)`.
`AssertionManager.isnan`	Perform the following assertion: `assert isnan(x)`.

Assertions based on the builtin builtins module.

`AssertionManager.callable`	Perform the following assertion: `assert callable(obj)`.
`AssertionManager.hasattr`	Perform the following assertion: `assert hasattr(obj, name)`.
`AssertionManager.isinstance`	Perform the following assertion: `assert isinstance(obj, class_or_tuple)`.
`AssertionManager.issubclass`	Perform the following assertion: `assert issubclass(cls, class_or_tuple)`.
`AssertionManager.len`	Perform the following assertion: `assert len(obj)`.
`AssertionManager.any`	Perform the following assertion: `assert any(iterable)`.
`AssertionManager.all`	Perform the following assertion: `assert all(iterable)`.
`AssertionManager.isdisjoint`	Perform the following assertion: `assert isdisjoint(a, b)`.
`AssertionManager.issuperset`	Perform the following assertion: `assert issuperset(a, b)`.
`AssertionManager.issubset`	Perform the following assertion: `assert issubset(a, b)`.
`AssertionManager.round`	Perform the following assertion: `assert round(number, ndigits=ndigits)`.

Miscellaneous assertions.

`AssertionManager.len_eq`	Perform the following assertion: `assert len_eq(a, b)`.
`AssertionManager.str_eq`	Perform the following assertion: `assert str_eq(a, b, str_converter=str_converter)`.
`AssertionManager.shape_eq`	Perform the following assertion: `assert shape_eq(a, b)`.
`AssertionManager.function_eq`	Perform the following assertion: `assert function_eq(func1, func2)`.

API

assertionlib.manager.assertion : AssertionManager: An instance of AssertionManager.

class assertionlib.manager.AssertionManager(repr_instance: ~typing.Optional[~reprlib.Repr] = <assertionlib.ndrepr.NDRepr object>)[source]

A class for performing assertions and providing informative exception messages.

A number of usage examples are provided in the the documentation.

Parameters:: repr_instance (reprlib.Repr, optional) – An instance of reprlib.Repr for formatting Exception messages. The passed instance should have access to a bound callable by the name of repr, which in turn should produce a string representation of any passed objects. If None, default the builtin repr() function. See also AssertionManager.repr_instance.

repr_instance

An instance of reprlib.Repr for formatting Exception messages. The passed instance should have access to a bound callable by the name of repr, which in turn should produce a string representation of passed objects. If None, default the builtin repr() function.

Type:: reprlib.Repr, optional

repr_fallback

A fallback value in case AssertionManager.repr_instance is None.

Type:: Callable[[Any], str]

maxstring_fallback

A fallback value in case AssertionManager.repr_instance is None.

Type:: int

AssertionManager.assert_(func: Callable[[...], T], *args: Any, invert: bool = False, exception: Optional[Type[Exception]] = None, post_process: Optional[Callable[[T], Any]] = None, message: Optional[str] = None, **kwargs: Any) → None[source]

Perform the following assertion: assert func(*args, **kwargs).

Examples

For example assert 5 == 5 is equivalent to AssertionManager().assert_(operator.eq, 5, 5).

Parameters:

func (Callable[..., T]) – The callable whose output will be evaluated.
*args (Any) – Positional arguments for func.

Keyword Arguments:

invert (bool, optional) – If True, invert the output of the assertion: assert not func(*args, **kwargs).
exception (type [Exception], optional) – Assert that exception is raised during/before the assertion operation. The only dissalowed value is AssertionError.
post_process (Callable[[T], bool], optional) – Apply post-processing to the to-be asserted data before asserting aforementioned data. Example functions would be the likes of any() and all().
message (str, optional) – A custom error message to-be passed to the assert statement.
**kwargs (Any, optional) – Keyword arguments for func.

Return type:

`NDRepr.repr_float`	Create a `str` representation of a `float` instance.
`NDRepr.repr_Exception`	Create a `str` representation of an :exc`Exception` instance.
`NDRepr.repr_Signature`	Create a `str` representation of a `Signature` instance.
`NDRepr.repr_method`	Create a `str` representation of a bound method.
`NDRepr.repr_method_descriptor`	Create a `str` representation of an unbound method.
`NDRepr.repr_function`	Create a `str` representation of a function.
`NDRepr.repr_builtin_function_or_method`	Create a `str` representation of a builtin function or method.
`NDRepr.repr_type`	Create a `str` representation of a `type` object.
`NDRepr.repr_module`	Create a `str` representation of a module.
`NDRepr.repr_dict_keys`	Create a `str` representation of a `KeysView`.
`NDRepr.repr_dict_values`	Create a `str` representation of a `ValuesView`.
`NDRepr.repr_dict_items`	Create a `str` representation of a `ItemsView`.
`NDRepr.repr_Molecule`	Create a `str` representation of a `plams.Molecule` instance.
`NDRepr.repr_Settings`	Create a `str` representation of a `plams.Settings` instance.
`NDRepr.repr_Atom`	Create a `str` representation of a `plams.Atom` instance.
`NDRepr.repr_Bond`	Create a `str` representation of a `plams.Bond` instance.
`NDRepr.repr_ndarray`	Create a `str` representation of a `numpy.ndarray` instance.
`NDRepr.repr_DataFrame`	Create a `str` representation of a `pandas.DataFrame` instance.
`NDRepr.repr_Series`	Create a `str` representation of a `pandas.Series` instance.
`NDRepr.repr_Dataset`	Create a `str` representation of a `h5py.Dataset` instance.

`AbstractDataClass`()	A dataclass with a number of generic pre-defined (magic) methods.
`AbstractDataClass.__repr__`()	Return a (machine readable) string representation of this instance.
`AbstractDataClass.__eq__`(value)	Check if this instance is equivalent to value.
`AbstractDataClass.__hash__`()	Return the hash of this instance.
`AbstractDataClass.__copy__`()	Return a shallow copy of this instance; see `AbstractDataClass.copy()`.
`AbstractDataClass.__deepcopy__`([memo])	Return a deep copy of this instance; see `AbstractDataClass.copy()`.".
`AbstractDataClass.copy`([deep])	Return a shallow or deep copy of this instance.
`AbstractDataClass.as_dict`([return_private])	Construct a dictionary from this instance with all non-private instance variables.
`AbstractDataClass.from_dict`(dct)	Construct a instance of this objects' class from a dictionary with keyword arguments.
`AbstractDataClass.inherit_annotations`()	A decorator for inheriting annotations and docstrings.

`get_sphinx_domain`(func[, module_mapping])	Create a Sphinx domain for func.
`create_assertion_doc`(func)	Create a new NumPy style assertion docstring from the docstring of func.
`bind_callable`(class_type, func[, name, warn])	Take a callable and use it to create a new assertion method for class_type.
`to_positional`(func)	Decorate a function's `__signature__` such that all positional-or-keyword arguments are changed to either positional- or keyword-only.

`len_eq`(a, b, /)	Check if the length of a is equivalent to b: `len(a) == b`.
`str_eq`(a, b, /, *[, str_converter])	Check if the string-representation of a is equivalent to b: `repr(a) == b`.
`shape_eq`(a, b, /)	Check if the shapes of a and b are equivalent: `a.shape == getattr(b, 'shape', b)`.
`isdisjoint`(a, b, /)	Check if a has no elements in b.
`issuperset`(a, b, /)	Check if a contains all elements from b.
`issubset`(a, b, /)	Check if b contains all elements in a.
`function_eq`(func1, func2, /)	Check if two functions are equivalent by checking if their `__code__` is identical.

Welcome to the AssertionLib documentation

AssertionLib

Installation

Usage

API

assertionlib

assertionlib.dataclass

assertionlib.functions

assertionlib.manager

assertionlib.ndrepr

Index

assertionlib.manager

Index

API

Assertions based on the builtin operator module

Assertions based on the builtin os.path module

Assertions based on the builtin math module

Assertions based on the builtin builtins module

Miscellaneous assertions

assertionlib.ndrepr

Index

API

assertionlib.dataclass

Index

API

assertionlib.functions

Index

API

assertionlib.assertion_functions

Index

API

`assertionlib`

`assertionlib.dataclass`

`assertionlib.functions`

`assertionlib.manager`

`assertionlib.ndrepr`

Assertions based on the builtin `operator` module

Assertions based on the builtin `os.path` module

Assertions based on the builtin `math` module

Assertions based on the builtin `builtins` module