Package: insanity
in-sanity=========Even though it is sometimes considered to be "unpythonic", there are situations where we have to sanitize the value of afunction parameter in some way or the other.A common example is the implementation of complicated mathematical models, e.g., for machine learning.In a case like this, making assumptions about an arg explicit (by means of a sanity check) can often help to preventbugs that are hard to find otherwise.However, sanitizing parameters is tedious, and, on top of that, often inflates our code unnecessarily.Therefore, to alleviate this sometimes necessary chore, the package `insanity` implements various common sanity checksfor function arguments, which allow for checking types as well as values of parameters concisely.Installation------------This package can be installed from PyPI:```pip install insanity```Available Sanity Checks-----------------------The package `insanity` provides four basic sanity checks, which cover most of the commonly performed examinations.All of the according check functions have a few things in common:- The first two positional args, called `arg_name` and `arg_value`, expect the name of the arg that is being sanitizedas well as the actual value that has been handed for it.- Check functions do not provide any return values, but rather signal a failed sanity check by raising either a`TypeError` or a `ValueError`.- Every check function accepts an optional keyword arg `error_msg`, which allows for specifying an error message that ispassed to any error that is raised instead of the standard message.### Type ChecksThe most basic among all sanity checks concerns the type of a provided arg, which is implemented by[`insanity.sanitize_type`](src/main/python/insanity/sanity_checks.py#L352).To use this function, we simply have to specify the type(s) that the sanitized arg may have:```pythoninsanity.sanitize_type("some_arg", some_arg, int)insanity.sanitize_type("some_arg", some_arg, [int, float])  # multiple types allowed```If we need to sanitize optional args that are `None` by default, then we may use the keyword arg `none_allowed` toindicate that `None` is an allowed value, which is not the case otherwise:```pythoninsanity.sanitize_type("some_arg", some_arg, str, none_allowed=True)```### Checking for Exhaustive ValuesOften times, an arg needs to have one out of a fixed number of possible values.In this case, args can be sanitized by means of[`insanity.sanitize_value`](src/main/python/insanity/sanity_checks.py#L458)This function accepts a few optional parameters, but in the most common case, we simply provide the values that thesanitized arg may have as an `Iterable`:```python# an arg that may be either 0 or 1, specified as str or intinsanity.sanitize_value("some_arg", some_arg, [0, 1, "0", "1"])```Alternatively, one may specify prohibited rather than admissible values.This is possible by providing the keyword arg `complement`:```python# an arg that may have any value EXCEPT 0 and 1insanity.sanitize_value("some_arg", some_arg, [0, 1], complement=True)```There are a few rare cases in which we need to make use of a different notion of equality than the one that is realizedby Python's standard equality operator `==`.In any such situation, a custom operator for comparing values may be provided via the keyword arg `equality_fn`:```pythondef eq_mod_5(x: int, y: int) -> bool:"""Computes whether two integers are equal modulo 5."""return (x - y) % 5 == 0# an arg that needs to be divisible by 5insanity.sanitize_value("some_arg",some_arg,0,equality_fn=eq_mod_5,error_msg="The arg is not divisible by 5!")```Finally, notice that `sanitize_value` again accepts the optional keyword arg `none_allowed` for indicating that thesanitized arg may be `None` (in addition the the specified admissible values).### Checking RangesWhen we work with numbers, then we frequently have to ensure that args are within a certain range.To that end, we can use[`insanity.sanitize_range`](src/main/python/insanity/sanity_checks.py#L245),which offers the self-explanatory keyword args `minimum`, `maximum`, `min_inclusive`, and `max_inclusive` for specifyingadmissible intervals of values:```python# an arg that has to be in the half-closed interval [0, 1)insanity.sanitize_range("some_arg", some_arg, minimum=0, maximum=1, min_inclusive=True, max_inclusive=False)```Just like `sanitize_value`, `sanitize_range` accepts the keyword arg `complement` for indicating that the describedrange is prohibited rather than admissible.### Sanitizing IterablesThe last of the provided sanity checks is for `Iterable`s, and is provided by[`insanity.sanitize_iterable`](src/main/python/insanity/sanity_checks.py#L67)This function accepts the following optional keyword args:- `elements_type`: the type(s) that the elements may have,- `target_length`: defines the exact length that the `Iterable` has to have,- `min_length`: the minimum length of the `Iterable`,- `max_length`: the maximum length of the `Iterable`,- `none_allowed`: indicates whether the sanitized arg may be `None`, and- `none_elements_allowed`: indicates whether the elements of the `Iterable` may be `None`.Here is an example that demonstrates the use of this function:```python# an arg that needs to be an iterable that contains 10 to 20 numbersinsanity.sanitize_iterable("some_arg",some_arg,elements_type=[int, float],min_length=10,max_length=20)```To perform more comprehensive checks of the elements of an `Iterable`, `sanitize_iterable` provides the keyword arg`element_check_fn`, which expects a function that, if provided, is applied to every element contained.Any such custom check function should, like the ones provided by this package, raise an appropriate error if aperformed sanity check fails.Notice that custom checks may be used in addition to those provided by `sanitized_iterable`.Furthermore, the module `insanity.iterable_check_functions` provides two functions that may be provided via`element_check_fn`, and that resemble the eponymous checks that are described above:[`sanitize_range_fn`](src/main/python/insanity/iterable_check_functions.py#L46) and[`sanitize_value_fn`](src/main/python/insanity/iterable_check_functions.py#L121).