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 anamedtuple
, 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 asthing['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()
orresolve_item()
) into one which returns the specified default_value when the symbol fails to resolve. Converted resolver functions will not raiseSymbolResolutionError
, 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()
orresolve_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, aTypeError
will be raised. Additionally, the resulting function will raise aSymbolResolutionError
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 todatetime
instances which do not have one specified. This is necessary for comparison operations. The value should either be atzinfo
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 (int) – The flags to provide to functions in the
-
regex_flags
= None¶ The flags to provide to the
match()
andsearch()
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 toresolve_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.
-
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:
-
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
-