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 Builtins(values, namespace=None, timezone=None)[source]

Bases: collections.abc.Mapping

A class to define and provide variables to within the builtin context of rules. These can be accessed by specifying a symbol name with the $ prefix.

__init__(values, namespace=None, timezone=None)[source]
Parameters
  • values (dict) – A mapping of string keys to be used as symbol names with values of either Python literals or a function which will be called when the symbol is accessed. When using a function, it will be passed a single argument, which is the instance of Builtins.

  • namespace (str) – The namespace of the variables to resolve.

  • timezone (tzinfo) – A timezone to use when resolving timestamps.

classmethod from_defaults(values=None, **kwargs)[source]

Initialize a Builtins instance with a set of default values.

class Context(regex_flags=0, resolver=None, type_resolver=None, default_timezone='local', default_value=UNDEFINED)[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)[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”.

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

builtins = None

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

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

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.

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.

classmethod resolve_attribute_type(object_type, 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