A simple, generic rules engine. Inspired by Martin Fowler's 2009 blog post.

This package was extracted from Funnel's production code and made open source.

For the story behind its inception, raison d'être, and overall concept, you can watch the talk Rules Rule held by Lennart Fridén at PyCon Sweden 2021.

Install the package funnel_rules_engine version 1.3+ from PyPi. The recommended requirements.txt line is funnel_rules_engine~=1.3.

A combination of a condition and an action, both of which are callables such as functions or lambdas. The callables must have an arity of one. If the conditional returns true given a single object, the action will be called with the same object as its argument.

When creating a rule, it can also be tagged with a list of tags (see RulesEngine.reject and RulesEngine.select).

Special case of Rule where the action always fires. Suitable as a catch-all last rule.

Special case of Rule where None is returned if the condition is met. Useful for halting the execution of .run()

A generic rules engine that accepts a list of Rules and some input to apply the rules to. The rules engine can either apply the first rule that matches (run) or all the rules that matches (run_all). In addition, rules can be evaluated and executed in parallel (run_all_in_parallel). The latter two cases can optionally be lazily executed by returning a generator rather than a list as the result.

For more on rules engines, see Martin Fowler's blog post.

Only apply the first rule that matches and return its result. This is comparable to the behaviour of a structured switch statement or an arbitrary conditional statement.

Apply all rules that match. The result is returned as a list, or as a generator if the optional parameter lazy is passed as True.

Evaluate and apply all rules in parallel. The result is returned as a list, or as a generator if the optional parameter lazy is passed as True.

These methods return a new rules engine containing the rules matching/not matching the given tags.

These are convenience functions for creating simple conditions and actions. They both accept a single value that in the case of when will be used to check equality with the passed state and in the case of then will be returned, ignoring the passed state.