Even though it is sometimes considered to be "unpythonic", there are situations where we have to sanitize the value of a function parameter in one 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 prevent bugs 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 checks
for function arguments, which allow for checking types as well as values of parameters concisely.
This package can be installed from PyPI:
pip install insanity
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
andarg_value
, expect the name of the arg that is being sanitized as 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 aValueError
. - Every check function accepts an optional keyword arg
error_msg
, which allows for specifying an error message that is passed to any error that is raised instead of the standard message.
The most basic among all sanity checks concerns the type of a provided arg, which is implemented by
insanity.sanitize_type
.
To use this function, we simply have to specify the type(s) that the sanitized arg may have:
insanity.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
to
indicate that None
is an allowed value, which is not the case otherwise:
insanity.sanitize_type("some_arg", some_arg, str, none_allowed=True)
Often 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
This function accepts a few optional parameters, but in the most common case, we simply provide the values that the
sanitized arg may have as an Iterable
:
# an arg that may be either 0 or 1, specified as str or int
insanity.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
:
# an arg that may have any value EXCEPT 0 and 1
insanity.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 realized
by Python's standard equality operator ==
.
In any such situation, a custom operator for comparing values may be provided via the keyword arg equality_fn
:
def 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 5
insanity.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 the
sanitized arg may be None
(in addition the the specified admissible values).
When 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
,
which offers the self-explanatory keyword args minimum
, maximum
, min_inclusive
, and max_inclusive
for specifying
admissible intervals of values:
# 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 described
range is prohibited rather than admissible.
The last of the provided sanity checks is for Iterable
s, and is provided by
insanity.sanitize_iterable
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 theIterable
has to have,min_length
: the minimum length of theIterable
,max_length
: the maximum length of theIterable
,none_allowed
: indicates whether the sanitized arg may beNone
, andnone_elements_allowed
: indicates whether the elements of theIterable
may beNone
.
Here is an example that demonstrates the use of this function:
# an arg that needs to be an iterable that contains 10 to 20 numbers
insanity.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 a
performed 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
and
sanitize_value_fn
.