applicable 1.1.1

Test callables without raising exceptions

applicable.py

applicable.py is a very basic package with a single function: applicable(). It is simply used to test if a callable can be called with a set of arguments without raising an error.

This package must be used with Python 3.6 or higher.

The signature of applicable() is:

applicable(callable: Callable,
           *args: Any,
           **kwargs: Any,
           ret_result: bool = True,
           ret_exc: bool = True) -> Any

* Note: This is not the actual signature, as you can probably tell. The actual signature (and the one type checkers and other tools will give you) is applicable(callable: Callable, *args: Any, **kwargs: Any). As noted in the docstring (applicable.__doc__), ret_result and ret_exc are special keyword arguments, and it would be preferred that they be used after the callable arguments.

Arguments:

• callable: The callable to be tested
• ret_result: Whether to return callable(*args, **kwargs) upon no error. True by default. If false, applicable() will return True upon no error.
• ret_exc: Type or value to return upon error. Defaults to _FalseException. With the exception of _FalseException (which is returned as _FalseException(exception_instance)), the default value for the type is returned, e.g., int() (which is 0), bool() (False), None if ret_exc is a type. If ret_exc is a value, the value is returned. Changed in version 1.1.0: ret_exc was previously a boolean value specifying whether to return a _FalseException or not.
• args and kwargs: The arguments that are passed to callable().

This function will usually be used in an if statement like the following:

from applicable import applicable

val = applicable(SomeCallable, 'arg!', a_kwarg='kwarg!')
if val == False or isinstance(val, _FalseException):
    # Do somthing with val
else:
    # Do something with the exception; use val.cls for the exception class

More examples, to show the full functionality of applicable() (and _FalseException):

>>> from applicable import applicable
>>> a = applicable(int, '4')
>>> a
4
>>>
>>> a = applicable(int, 'whoops')
>>> a
applicable._FalseException(exc_inst=ValueError(...))
>>> a.cls
<class 'ValueError'>
>>> a.inst
ValueError("invalid literal for int() with base 10: 'whoops'")
>>> bool(a)
False
>>>
>>> a = applicable(complex, 4, imag=3)
>>> a
(4+3j)
>>>
>>> a = applicable(complex, 4, imag=3, ret_result=False)
>>> a
True
>>> a = applicable(int, 'whoops', ret_exc=bool)
>>> a
False
>>> applicable(int, 'whoops', ret_exc=None)
None
>>> applicable(int, 'whoops', ret_exc=4)
4