funcflow
Subpackages
Tools for composing functions and other callable objects into workflows.
Once you have broken down your workflow into small, modular steps, the tools in this package allow you to parameterize them with everything that is known at program start, and compose them into arbitrarily complex execution graphs that are easy to maintain and to extend.
Important
In order for everything to work smoothly, there is only one thing you will have
to keep in mind when writing the composable building blocks of your workflow.
If a function (or other callable object) is to return nothing, that is, when
it is a side effect, don’t just omit the return
statement, but explicitly
return an empty tuple!
- class Curry(call, *args, **kwargs)[source]
Bases:
ArgRepr
,Generic
Alternative implementation of
functools.partial
with one difference.Positional arguments given at instantiation are appended to those given when instances are called (as opposed to the other way around). Upon subclassing and/or instantiation, annotation with the (return) type of call is recommended.
- Parameters:
call (callable) – Callable object with arbitrary call signature.
*args – Any number of arguments to call call with.
**kwargs – Any number of keyword arguments to call call with.
See also
- __call__(*args, **kwargs)[source]
Execute cached callable with combined args and kwargs.
- Parameters:
*args – Additional arguments are prepended to cached arguments.
**kwargs – Additional keyword arguments are combined with cached keyword arguments, overriding them in case of conflict.
- Returns:
Whatever call returns.
- Return type:
object
- class Fallback(calls, *errors, callback=<function unit>)[source]
Bases:
IndentRepr
,Generic
[P
,T
]Try different options in case a callable fails to process its input.
Upon subclassing and/or instantiation, type annotation with the list of argument types that the callable(s) to try take as input, followed by the common return type(s) of the callable(s), is recommended.
- Parameters:
calls (Callable or iterable) – A single callable or an iterable thereof with the same call signature and return value(s). These will be called, one after the other, with the input arguments to (callable) instances until no error occurs. Providing and empty iterable makes instances simply return their input argument(s).
*errors (Exception class) – Exception classes that are caught and trigger trying the next of the calls. If none are given, all exceptions qualify.
callback (Callable, optional) – Will be called each time one of the calls fails raising one of the errors with (a) the name of the failing callable, (b) a tuple of the arguments it was called with, and (c) the exception it raised. Defaults to unit, which does nothing at all.
- Raises:
TypeError – If calls is neither a callable nor an iterable thereof or callback is not, in fact, callable.
FallbackErrors – If any of the errors does not derive from
Exception
.
- __call__(*args)[source]
Call the cached callables in turn until one does not raise errors.
- Parameters:
*args – Argument(s) to the cached callables.
- Returns:
Whatever the cached callables return.
- Return type:
object
- Raises:
FallbackErrors – If all calls raised one of the errors when called with args.
- class Filter(criterion=None, wrapper=None)[source]
Bases:
ArgRepr
,Generic
Equivalent to a partial of the python builtin
filter
function.Upon subclassing and/or instantiation, type annotation with the type of the elements in the iterator to be filtered and the return type of wrapper is recommended.
- Parameters:
criterion (callable, optional) – Callable accepting one element of an iterable at a time and returning a boolean value for each one of them. Defaults to
None
, which returns the inherent truth values of the object in the iterable.wrapper (type or callable, optional) – If not given, an attempt will be made to return the same type of iterable the callable instance is being called with (by calling its class with a list of the filtered elements). If explicitly given, wrapper will be called with a list of filtered elements. Consequently, the return type will be the (return) type of wrapper.
Note
In contrast to python’s builtin lazy
filter
function, which returns a generator object, the filtered iterable is fully manifested first and only then wrapped.- __call__(iterable)[source]
Filter an iterable according to the specified criterion.
- Parameters:
iterable (Iterable) – An iterable whose elements are to be filtered according to whether the criterion evaluates to
True
orFalse
.- Returns:
Same type as iterable if wrapper was not specified on instantiation or the (return) type of wrapper.
- Return type:
Sequence
- Raises:
FilterError – If calling the criterion on any element of iterable raises an exception or if wrapping the results leads to an exception.
- class Fork(call=(), *calls)[source]
Bases:
IndentRepr
,Generic
[P
,T
]Call any number of callables with the same argument(s).
Generic type annotation of instances is recommended. Provide a list of one or more input types that all callables take, followed by a
tuple
specifying the concatenation of the return types of all callables, ignoring empty tuples. If only a single object remains, the type of that object should be annotated.- Parameters:
call (callable or iterable of callables, optional) – One callable or an iterator of callables to all call with the same arguments. Defaults to an empty tuple.
*calls (callable) – Additional callables to call with the same argument(s).
- Raises:
ForkError – If (any of) call or any of calls are not, in fact, callable.
- __call__(*args)[source]
Call all specified calls with the same argument(s).
- Parameters:
*args – Arguments to call all calls with.
- Returns:
Concatenation of all return values of all calls in order. If only one of the calls returns something other than an empty tuple, that object is returned.
- Return type:
tuple or object
- Raises:
ForkError – When one of the calls raises an exception.
- class Map(transform, wrapper=None)[source]
Bases:
ArgRepr
,Generic
[P
,S
,T
]Equivalent to a partial of the python builtin
map
function.Upon subclassing and/or instantiation, type annotation with a list of the argument type(s) of transform, the return type of call, and the return type of wrapper is recommended.
- Parameters:
transform (callable) – Transforms element(s) of the input iterable(s).
wrapper (type or callable, optional) – If not given, an attempt will be made to return the type of the first iterable the callable instance is being called with (by calling its class with a list of the mapped elements). If explicitly given, wrapper will be called with a list mapped elements. Consequently, the return type will be the (return) type of wrapper.
Note
In contrast to python’s builtin lazy
map
function, which returns a generator object, the mapped iterable is fully manifested first and only then wrapped.- __call__(iterable, *iterables)[source]
Transform the element(s) of the given iterable(s).
- Parameters:
iterable (Iterable) – An iterable of elements to transform.
*iterables (Iterable) – If given, the cached transform is called with the corresponding elements of ìterable and all iterables as arguments.
- Returns:
Same type as iterable if wrapper was not specified on instantiation or the (return) type of wrapper. Note that, as with python’s builtin
map
function, the length of the output sequence is limited by the shortest of the input iterables.- Return type:
Sequence
- Raises:
MapError – If calling the cached transform on any element(s) of the given iterable(s) raises an exception or if wrapping the results leads to an exception.
- class Partial(call, *args, **kwargs)[source]
Bases:
ArgRepr
,Generic
Alternative implementation of
functools.partial
.Positional arguments given when instances are called are appended to those given at instantiation . Upon subclassing and/or instantiation, annotation with the (return) type of call is recommended.
- Parameters:
call (callable) – Callable object with arbitrary call signature.
*args – Any number of arguments to call call with.
**kwargs – Any number of keyword arguments to call call with.
See also
- __call__(*args, **kwargs)[source]
Execute cached callable with combined args and kwargs.
- Parameters:
*args – Additional arguments are appended to cached arguments.
**kwargs – Additional keyword arguments are combined with cached keyword arguments, overriding them in case of conflict.
- Returns:
Whatever call returns.
- Return type:
object
- class Pipe(call=(), *calls)[source]
Bases:
IndentRepr
,Generic
[P
,T
]Chain any number of callable objects into a single callable object.
Arguments passed to the functional composition will be forwarded to the first callable in the chain. Subsequent callables will be called with the return value(s) of the previous callable in the chain. The return value of the functional composition is the return value of the last callable in the chain.
- Parameters:
call (callable or iterable of callables, optional) – One callable or an iterator of callables to chain one after another. Defaults to an empty tuple.
*calls (callable) – Additional callables to chain one after another.
- Raises:
PipeError – If (any of) call or any of calls are not, in fact, callable.
Note
Upon instantiation, the generic class can be type-annotated with the list of argument types of the first callable in the chain, followed by the return type of the last callable.
- __call__(*args)[source]
Call the functional composition this object was instantiated with.
- Parameters:
*args – Arguments to pass to the first callable in calls.
- Returns:
Whatever the last callable of calls returns.
- Return type:
object
- Raises:
PipeError – When one of the callables in the chain raises an exception.
- class Reduce(call, acc=None)[source]
Bases:
ArgRepr
,Generic
Equivalent to a partial of the
functools.reduce
function.Upon subclassing and/or instantiation, type annotation with the return type of call (which must be the same as the type of its first argument as well as the type of the accumulator acc) and the type ot its second argument (which must be the same as the type of the elements in the iterable acted upon) is recommended.
- Parameters:
call (callable) – Callable accepting the current acc and the next element of iterable, returning the updated value of acc.
acc (optional) – Initial value for the accumulator in the reduce operation. If not given calling reduce on an empty iterable will fail. Defaults to
None
.
- class Route(routes=(), call=(), *calls)[source]
Bases:
IndentRepr
,Generic
[P
,T
]Flexibly route arguments to a sequence of callables and collect results.
Generic type annotation of instances is recommended. Provide a list of one or more input types that will be routed to the callables and a
tuple
specifying the concatenation of the return types of all callables, ignoring empty tuples. If only a single object remains, the type of that object should be annotated.- Parameters:
routes (sequence of int or sequence of sequences of int, optional) – Specified as, e.g.,
[2, 0, 1]
means that the first callable will be called with the third argument (index 2), the second with the first, and the third with the second. If callables take more than one argument, routes can be specified as[(2, 0), (), 1]
, which means that the first callable will be called with the third and first arguments, the second with no arguments, and the third with the second argument. Defaults to an empty tuple, meaning that no callables can be specified and, that, therefore, nothing is returned when calling the instance, no matter how many arguments it is called with.call (callable or iterable of callables, optional) – One callable or an iterator of callables that will be called with the arguments according to routes. Defaults to an empty tuple.
*calls (callable) – Additional callables that will be called with the arguments according to routes. Together with call, there must be the same number of callables as there are routes.
- Raises:
RouteError – If the routes cannot be parsed, if the number of routes does not match the number of callables specified with call and calls, or if (any of) call or any of calls is not, in fact, callable.
- __call__(*args)[source]
Distribute arguments according to routes and forward to calls.
- Parameters:
*args – Arguments to be redistributed according to routes among calls. There must be at least n_args arguments. Extras will be ignored.
- Returns:
Concatenation of all return values of all calls in order. If only one of the calls returns something other than an empty tuple, that object is returned.
- Return type:
tuple or object
- Raises:
RouteError – If there are too few arguments to redistribute among calls according to routes or if calling one of the calls fails.
- property n_args
The minimum number of arguments required for calling instances.
- class Safe(call, exception=(), *exceptions)[source]
Bases:
ArgRepr
,Generic
[P
,T
]Wrap callable to catch potential errors and safely return them.
Generic type annotation of instances is recommended. Provide a list of one or more input types that the callable takes, followed by the return type of the callable.
- Parameters:
call (callable) – Callable to wrap.
exception (optional) – Specific exception to catch (or an iterable of exceptions). Defaults to
Exception
.*exceptions – Additional exceptions to catch.
See also
- exception SafeError(error, name, call, call_args)[source]
Bases:
Exception
Special exception to wrap other exceptions.
- Parameters:
error (Exception) – The wrapped exception.
name (str) – A human-readable string representation of the callable that failed.
call (callable) – The callable that failed.
call_args (tuple) – The arguments that call failed with.
See also
- property message
The error message displayed if the exception is actually raised.
- class Split(criterion=None, wrapper=None)[source]
Bases:
ArgRepr
,Generic
Split an iterable of objects into two according to a decision criterion.
Upon subclassing and/or instantiation, type annotation with the type of the elements in the iterator to be filtered and the return type of wrapper is recommended.
- Parameters:
criterion (callable, optional) – The condition is called with one object at a time and must return a boolean value. Objects on which it evaluates to
True
are sorted into one container and those where it evaluates toFalse
end up in a second container. Defaults toNone
, which returns the inherent truth values of the object in the iterable.wrapper (type or callable, optional) – If not given, an attempt will be made to determine the type of the container the callable instance was called with. Whether inferred or explicitly given, wrapper will be called twice, once with a list of a list of the elements that evaluated to
True
and once with those that evaluated toFalse
.
- __call__(iterable)[source]
Split sequence into two according to cached decision criterion.
- Parameters:
iterable (Iterable) – Objects to be split according to the cached (boolean) criterion.
- Returns:
Two sequences of the same type as the input sequence or, if a wrapper was specified, of that type. Objects where the criterion evaluated to
True
are in the first return sequence and those evaluating toFalse
are in the second.- Return type:
tuple
- Raises:
SplitError – If calling the criterion on any element of iterable raises an exception or if wrapping the results leads to an exception.
- class Sum(acc=None)[source]
Bases:
ArgRepr
,Generic
Equivalent to a partial of the python builtin
sum
function.Upon subclassing and/or instantiation, type annotation with the type of the elements in the iterable and the type of the final sum is recommended.
- Parameters:
acc (optional) – The initial value of the sum to which all other elements are added. If not given, calling sum on an empty iterable will fail. Defaults to
None
.
- apply(call, *args)
Call a callable object with the specified arguments.
- Parameters:
call (callable) – The callable object to call with args.
*args – The arguments to call call with.
- Returns:
Whatever call returns.
- Return type:
object
- identity(*args)
Pass through any number of argument(s) doing nothing.
- Parameters:
*args – Argument(s) to pass through.
- Returns:
Called with one argument, this argument is simply passed through. When called with more than one argument, the arguments tuple returned. When called with no argument, an empty tuple is returned.
- Return type:
object or tuple
- unit(*_)
Accepts any number of arguments but always returns and empty tuple.
- Returns:
Empty tuple.
- Return type:
tuple