xotl.tools.fp.prove - Prove validity of values

Proving success or failure of a function call has two main patterns:

1. Predicative: a function call returns one or more values indicating a failure, for example method find in strings returns -1 if the sub-string is not found. In general this pattern considers a set of values as logical Boolean true, an other set false.

   Example:

   index = s.find('x')
   if index >= 0:
       ...    # condition of success
   else:
       ...    # condition of failure
   

2. Disruptive: a function call throws an exception on a failure breaking the normal flow of execution, for example method index in strings.

   Example:

   try:
       index = s.index('x)
   except ValueError:
       ...    # condition of failure
   else:
       ...    # condition of success
   

   The exception object contains the semantics of the “”anomalous condition”. Exception handling can be used as flow control structures for execution context inter-layer processing, or as a termination condition.

Module content

Validity proofs for data values.

There are some basic helper functions:

• predicative() wraps a function in a way that a logical false value is returned on failure. If an exception is raised, it is returned wrapped as an special false value. See Maybe monad for more information.
• vouch() wraps a function in a way that an exception is raised if an invalid value (logical false by default) is returned. This is useful to call functions that use “special” false values to signal a failure.
• enfold() creates a decorator to convert a function to use either the predicative() or the vouch() protocol.

New in version 1.8.0.

xotl.tools.fp.prove.enfold(checker)

Create a decorator to execute a function inner a safety wrapper.

Parameters:checker – Could be any function to enfold, but it’s intended mainly for predicative() or vouch() functions.

In the following example, the semantics of this function can be seen. The definition:

>>> @enfold(predicative)
... def test(x):
...     return 1 <= x <= 10

>>> test(5)
5

It is equivalent to:

>>> def test(x):
...     return 1 <= x <= 10

>>> predicative(test, 5)
5

In other hand:

>>> @enfold(predicative)
... def test(x):
...     return 1 <= x <= 10

>>> test(15)
5

xotl.tools.fp.prove.predicative(function, *args, **kwds)

Call a function in a safety wrapper returning a false value if fail.

This converts any function into a predicate. A predicate can be thought as an operator or function that returns a value that is either true or false.

Predicates are sometimes used to indicate set membership: on certain occasions it is inconvenient or impossible to describe a set by listing all of its elements. Thus, a predicate P(x) will be true or false, depending on whether x belongs to a set.

If the argument function validates its arguments, return a valid true value. There are two special conditions: first, a value treated as false for Python conventions (for example, 0, or an empty string); and second, when an exception is raised; in both cases the predicate will return an instance of Maybe.

xotl.tools.fp.prove.vouch(function, *args, **kwds)

Call a function in a safety wrapper raising an exception if it fails.

When the wrapped function fails, an exception must be raised. A predicate fails when it returns a false value. To avoid treat false values of some types as fails, use Just to return that values wrapped.