engine

This module contains the primary externally facing API for the package.

Functions

resolve_attribute(thing, name)[source]

A replacement resolver function for looking up symbols as members of thing. This is effectively the same as thing.name. The thing object can be a namedtuple, a custom Python class or any other object. Each of the members of thing must be of a compatible data type.

Warning

This effectively exposes all members of thing. If any members are sensitive, then a custom resolver should be used that checks name against a whitelist of attributes that are allowed to be accessed.

Parameters:
  • thing – The object on which the name attribute will be accessed.
  • name (str) – The symbol name that is being resolved.
Returns:

The value for the corresponding attribute name.

resolve_item(thing, name)[source]

A resolver function for looking up symbols as items from an object (thing) which supports the Mapping interface, such as a dictionary. This is effectively the same as thing['name']. Each of the values in thing must be of a compatible data type.

Parameters:
  • thing – The object from which the name item will be accessed.
  • name (str) – The symbol name that is being resolved.
Returns:

The value for the corresponding attribute name.

to_default_resolver(resolver, default_value=None)[source]

Convert the specified resolver function (such as resolve_attribute() or resolve_item()) into one which returns the specified default_value when the symbol fails to resolve. Converted resolver functions will not raise SymbolResolutionError, instead they will return the default value.

New in version 1.1.0.

Parameters:
  • resolver (function) – The resolver function to convert.
  • default_value – The Python value to use as the default for symbols which can not be resolved.
Returns:

A new resolver function.

Return type:

function

to_recursive_resolver(resolver)[source]

Convert the specified resolver function (such as resolve_attribute() or resolve_item()) into one which splits the symbol name on dots and recursively resolves each one on the specified thing parameter.

New in version 1.1.0.

Parameters:resolver (function) – The resolver function to convert.
Returns:A new resolver function.
Return type:function
type_resolver_from_dict(dictionary)[source]

Return a function suitable for use as the type_resolver for a Context instance from a dictionary. If any of the values within the dictionary are not of a compatible data type, a TypeError will be raised. Additionally, the resulting function will raise a SymbolResolutionError if the symbol name does not exist within the dictionary.

Parameters:dictionary (dict) – A dictionary (or any other object which supports the Mapping interface) from which to create the callback function.
Returns:The callback function.
Return type:function

Classes

class Context(regex_flags=0, resolver=None, type_resolver=None, default_timezone='local')[source]

Bases: object

An object defining the context for a rule’s evaluation. This can be used to change the behavior of certain aspects of the rule such as how symbols are resolved and what regex flags should be used.

__init__(regex_flags=0, resolver=None, type_resolver=None, default_timezone='local')[source]
Parameters:
  • regex_flags (int) – The flags to provide to functions in the re module.
  • resolver – An optional callback function to use in place of resolve().
  • type_resolver – An optional callback function to use in place of resolve_type().
  • default_timezone (str, tzinfo) – The default timezone to apply to datetime instances which do not have one specified. This is necessary for comparison operations. The value should either be a tzinfo instance, or a string. If default_timzezone is a string it must be one of the specially supported (case-insensitive) values of “local” or “utc”.
regex_flags = None

The flags to provide to the match() and search() functions when matching or searching for patterns.

resolve(thing, name, scope=None)[source]

The method to use for resolving symbols names to values. This function must return a compatible value for the specified symbol name. When a scope is defined, this function handles the resolution itself, however when the scope is None the resolver specified in __init__() is used which defaults to resolve_item(). This function must return a compatible value for the specified symbol name.

Parameters:
  • thing – The object from which the name item will be accessed.
  • name (str) – The symbol name that is being resolved.
Returns:

The value for the corresponding attribute name.

resolve_type(name)[source]

A method for providing type hints while the rule is being generated. This can be used to ensure that all symbol names are valid and that the types are appropriate for the operations being performed. It must then return one of the compatible data type constants if the symbol is valid or raise an exception. The default behavior is to return UNDEFINED for all symbols.

Parameters:name (str) – The symbol name to provide a type hint for.
Returns:The type of the specified symbol
symbols = None

The symbols that are referred to by the rule. Some or all of these will need to be resolved at evaluation time. This attribute can be used after a rule is generated to ensure that all symbols are valid before it is evaluated.

class Rule(text, context=None)[source]

Bases: object

A rule which parses a string with a logical expression and can then evaluate an arbitrary object for whether or not it matches based on the constraints of the expression.

__init__(text, context=None)[source]
Parameters:
  • text (str) – The text of the logical expression.
  • context (Context) – The context to use for evaluating the expression on arbitrary objects. This can be used to change the default behavior. The default context is Context but any object providing the same interface (such as a subclass) can be used.
evaluate(thing)[source]

Evaluate the rule against the specified thing and return the value. This can be used to, for example, apply the symbol resolver.

Parameters:thing – The object on which to apply the rule.
Returns:The value the rule evaluates to. Unlike the matches() method, this is not necessarily a boolean.
filter(things)[source]

A convenience function for iterating over things and yielding each member that matches() return True for.

Parameters:things – The collection of objects to iterate over.
classmethod is_valid(text, context=None)[source]

Test whether or not the rule is syntactically correct. This verifies the grammar is well structured and that there are no type compatibility issues regarding literals or symbols with known types (see resolve_type() for specifying symbol type information).

Parameters:
  • text (str) – The text of the logical expression.
  • context – The context as would be passed to the __init__() method. This can be used for specifying symbol type information.
Returns:

Whether or not the expression is well formed and appears valid.

Return type:

bool

matches(thing)[source]

Evaluate the rule against the specified thing. This will either return whether thing matches, or an exception will be raised.

Parameters:thing – The object on which to apply the rule.
Returns:Whether or not the rule matches.
Return type:bool
parser = <rule_engine.parser.Parser object>

The Parser instance that will be used for parsing the rule text into a compatible abstract syntax tree (AST) for evaluation.

to_graphviz()[source]

Generate a diagram of the parsed rule’s AST using GraphViz.

Returns:The rule diagram.
Return type:graphviz.Digraph