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.

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', default_value=UNDEFINED, decimal_context=None)[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', default_value=UNDEFINED, decimal_context=None)[source]
Parameters:

  • regex_flags (int) – The flags to provide to functions in the re module when calling either the match() or search() functions for comparison expressions.

  • resolver – An optional callback function to use in place of resolve().

  • type_resolver (function, dict) – 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”.

  • default_value – The default value to return when resolving either a missing symbol or attribute.

  • decimal_context – A specific decimal.Context object to use for evaluation of FLOAT values. The default value will be taken from the current thread and will be used by all evaluations using this Context regardless of the decimal context of the thread which evaluates the rule. This causes the rule evaluation to be consistent regardless of the calling thread.

Changed in version 2.0.0: Added the default_value parameter.

Changed in version 2.1.0: If type_resolver is a dictionary, type_resolver_from_dict() will be called on it automatically and the result will be used as the callback.

Changed in version 3.0.0: Added the decimal_context parameter.

assignments(*assignments)[source]

Add the specified assignments to a thread-specific scope. This is used when an assignment originates from an expression.

Parameters:

assignments (Assignment) – The one or more assignments to define.

builtins

An instance of Builtins to provided a default set of builtin symbol values.

decimal_context

The decimal_context parameter from __init__()

default_timezone

The default_timezone parameter from __init__()

default_value

The default_value parameter from __init__()

regex_flags

The regex_flags parameter from __init__()

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().

If name fails to resolve, this method will raise SymbolResolutionError. It is then up to the caller to determine whether or not it is appropriate to use default_value.

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 symbol name.

resolve_attribute(thing, object_, name)[source]

The method to use for resolving attributes from values. This function must return a compatible value for the specified attribute name.

If name fails to resolve, this method will raise AttributeResolutionError. It is then up to the caller to determine whether or not it is appropriate to use default_value.

Parameters:

  • thing – The object from which the object_ was retrieved.

  • object – The object from which the name attribute will be accessed.

  • name (str) – The attribute name that is being resolved.

Returns:

The value for the corresponding attribute name.

resolve_attribute_type(object_type, name)

The method to use for resolving the data type of an attribute.

Parameters:

  • object_type – The data type of the object that name is an attribute of.

  • name (str) – The name of the attribute to retrieve the data type of.

Returns:

The data type of the specified attribute.

resolve_type(name, scope=None)[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.

  • scope (str) – An optional scope name that identifies from where to resolve the name.

Returns:

The type of the specified symbol.

symbols

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