booleano.parser – Boolean expressions parser

Parser of boolean expressions.

Grammar definition

class booleano.parser.Grammar(settings=None, generators=None, **tokens)

Adaptive grammar.

Instances of this class contain the properties of the grammar, but are not able to generate a parser based on the represented grammar – that is a Parser‘s job.

Parameters:
  • settings (dict) – The grammar settings to be overridden, if any.
  • generators (dict) – The custom Pyparsing generators for some of the elements in the grammar, if any.
Raises booleano.exc.GrammarError:
 

If at least one of the settings, generators or tokens are not valid.

Keyword arguments represent the tokens to be overridden.

get_custom_generator(generator_name)

Return the generator identified by generator_name.

Parameter:generator_name (basestring) – The name of the generator to be retrieved.
Returns:The generator value or None if it’s not been set.
Raises booleano.exc.GrammarError:
 If the generator_name is unknown.
get_setting(setting_name)

Return the value of setting identified by setting_name.

Parameter:setting_name (basestring) – The name of the setting to be retrieved.
Returns:The setting value.
Raises booleano.exc.GrammarError:
 If the setting_name is unknown.
get_token(token_name)

Return the token called token_name.

Parameter:token_name (basestring) – The name/key of the token to be returned.
Returns:The requested token.
Return type:basestring
Raises booleano.exc.GrammarError:
 If the token_name is unknown.

If the token doesn’t have a custom value, the default value will be returned instead.

set_custom_generator(generator_name, generator)

Set the generator called generator_name to the custom callable generator.

Parameters:
  • generator_name (basestring) – The name of the generator to be overridden.
  • generator – The custom generator (a Python callable).
Raises booleano.exc.GrammarError:
 

If the generator_name is unknown.

set_setting(setting_name, setting)

Set the setting called setting_name to the custom value setting.

Parameters:
  • setting_name (basestring) – The name of the setting to be customized.
  • setting (basestring) – The new value of the setting.
Raises booleano.exc.GrammarError:
 

If the setting_name is unknown or setting is an invalid value for setting_name.

Settings whose expected value is a Python boolean are not validated.

set_token(token_name, token)

Set the token called token_name to the custom value token.

Parameters:
  • token_name (basestring) – The name of the token to be customized.
  • token (basestring) – The new value of the token.
Raises booleano.exc.GrammarError:
 

If the token_name is unknown.

default_settings
The default settings for the grammar.
default_tokens
The default tokens.
known_generators
The known/valid generators.

Test utilities

class booleano.parser.testutils.BaseGrammarTest(*args, **kwargs)

Base test case for a grammar and the expressions its parser could handle.

Subclasses must define all the following attributes for the test case to work.

grammar

An instance of the grammar to be tested. This attribute must be set in the subclasses, like this:

from booleano.parser import Grammar

class TestMyGrammar(BaseGrammarTest):

    grammar = Grammar(ne="<>")
Type:booleano.parser.Grammar
expressions

A dictionary with all the valid expressions recognized by the grammar, where each key is the expression itself and its item is the mock representation of the operation.

Type:dict
badformed_expressions

A list of expressions that are bad-formed in the grammar.

Type:list
single_operands

A dictionary where the key is an expression that contains a single operand (i.e., no operator) and the item is the root node of the expected parse tree.

Type:dict
invalid_operands

A list of expressions which contain a single operand and it is invalid.

Type:list

Scope definition / name binding

class booleano.parser.Bind(global_name, operand, **names)

Operand binder.

Each instance is a name binding, which assigns an identifier to an operand (even in different languages).

Parameters:

Additional keyword arguments represent the translations of the global_name into other languages.

get_localized_name(locale)

Return the localized name of the identifier in locale.

Parameter:locale (basestring) – The locale of the name.
Returns:The name of the identifier in locale; if it’s not defined, the global name is returned.
Return type:basestring
class booleano.parser.SymbolTable(global_name, objects, *subtables, **names)

Symbol table.

Symbol tables wrap bound operands (aka, “bindings”).

Parameters:
  • global_name (basestring) – The name of the symbol table (excludes parent symbol tables, if any).
  • objects (list) – List of bound operands available in this symbol table.
Raises booleano.exc.ScopeError:
 

If an object/subtable is already included or already belongs to another symbol table.

Additional positional arguments represent the sub-tables of this symbol table.

Additional keyword arguments represent the other names this table can take in different locales.

add_object(obj)

Add the obj object to this symbol table.

Parameter:obj (Bind) – The bound operand to be added.
Raises booleano.exc.ScopeError:
 If obj is already included or it already belongs to another symbol table.
add_subtable(table)

Include table in the child tables of this symbol table.

Parameter:table (SymbolTable) – The symbol table to be added.
Raises booleano.exc.ScopeError:
 If table is already included or it already belongs to another symbol table.
get_localized_name(locale)

Return the localized name of the identifier in locale.

Parameter:locale (basestring) – The locale of the name.
Returns:The name of the identifier in locale; if it’s not defined, the global name is returned.
Return type:basestring
get_namespace(locale=None)

Extract the namespace for this symbol table in the locale.

Parameters:
  • locale – The locale of the namespace; if None, the global names will be used instead.
  • locale – basestring
Returns:

The namespace in locale.

Return type:

booleano.parser.scope.Namespace

validate_scope()

Make sure there’s no name clash in the symbol table.

Raises booleano.exc.ScopeError:
 If a name clash in found, either in the global names or with the localized names.

Users may want to run this in their test suite, instead of in production, for performance reasons.

Note that it’s perfectly valid for one object and one sub-table to have the same name in the parent symbol table.

class booleano.parser.scope.Namespace(objects, subnamespaces={})

A namespace for a given locale.

This is not aimed at end-users, it should only be used internally in Booleano.

The parser only deals with this, not with the symbol table directly.

A symbol table has one namespace per locale.

Parameters:
  • objects (dict) – The objects that belong to the table.
  • subnamespaces (dict) – The namespaces under this namespace, if any.

Parse managers

A parse manager controls the parsers to be used in a single kind of expression, with one parser per supported grammar.

class booleano.parser.EvaluableParseManager(symbol_table, generic_grammar, cache_limit=0, **localized_grammars)

Parsing manager for evaluable operations.

It manages evaluable parsers.

Parameters:
  • symbol_table (SymbolTable) – The symbol table for the supported expressions.
  • generic_grammar (Grammar) – The default grammar.
  • cache_limit (int) – The maximum amount of expressions to be cached internally (use None for no limit or 0 to disable caching).

Additional keyword arguments, if any, will be used as custom grammars where each key represents the locale of the grammar in the value.

add_parser(locale, grammar)

Create a parser for grammar and store it.

Parameters:
  • locale (basestring) – The locale of the grammar.
  • grammar (Grammar) – The grammar of the parser to be created.
evaluate(expression, locale, context)

Parse expression and return its evaluation result with context.

Parameters:
  • expression (basestring) – The expression to be parsed.
  • locale (basestring) – The locale of the grammar used by expression.
  • context (object) – The context under which the parse tree of expression has to be evaluated.
Returns:

The result of the evaluation of the parse tree for expression.

Return type:

bool

Raises BadExpressionError:
 

If expression is bad-formed according to the locale grammar.

Raises InvalidOperationError:
 

If expression has an invalid operation.

Raises ScopeError:
 

If expression contains unknown identifiers.

parse(expression, locale=None)

Parse expression and return its parse tree.

Parameters:
  • expression (basestring) – The expression to be parsed.
  • locale (basestring) – The locale of the grammar used by expression (or None if it uses the generic grammar).
Returns:

The parse tree for expression.

Return type:

booleano.parser.trees.ParseTree

Raises booleano.exc.BadExpressionError:
 

If expression is bad-formed according to the grammar locale.

Raises booleano.exc.InvalidOperationError:
 

If expression has an invalid operation.

Raises booleano.exc.ScopeError:
 

If expression contains unknown identifiers.

If caching is enabled and the expression was cached previously, expression won’t be parsed again and its cached parse tree will be returned.

If caching is enabled, but the expression is not cached, it will be parsed and the resulting parse tree will be cached and finally returned.

class booleano.parser.ConvertibleParseManager(generic_grammar, cache_limit=0, **localized_grammars)

Parsing manager for convertible operations.

It manages convertible parsers.

Parameters:
  • generic_grammar (Grammar) – The default grammar.
  • cache_limit (int) – The maximum amount of expressions to be cached internally (use None for no limit or 0 to disable caching).

Additional keyword arguments, if any, will be used as custom grammars where each key represents the locale of the grammar in the value.

add_parser(locale, grammar)

Create a parser for grammar and store it.

Parameters:
  • locale (basestring) – The locale of the grammar.
  • grammar (Grammar) – The grammar of the parser to be created.
parse(expression, locale=None)

Parse expression and return its parse tree.

Parameters:
  • expression (basestring) – The expression to be parsed.
  • locale (basestring) – The locale of the grammar used by expression (or None if it uses the generic grammar).
Returns:

The parse tree for expression.

Return type:

booleano.parser.trees.ParseTree

Raises booleano.exc.BadExpressionError:
 

If expression is bad-formed according to the grammar locale.

Raises booleano.exc.InvalidOperationError:
 

If expression has an invalid operation.

Raises booleano.exc.ScopeError:
 

If expression contains unknown identifiers.

If caching is enabled and the expression was cached previously, expression won’t be parsed again and its cached parse tree will be returned.

If caching is enabled, but the expression is not cached, it will be parsed and the resulting parse tree will be cached and finally returned.

Parsers

Generic Pyparsing-based parser implementation.

class booleano.parser.parsers.Parser(grammar)

Base class for parsers.

Parameter:grammar (booleano.parser.Grammar) – The grammar used by the parser.
class booleano.parser.parsers.EvaluableParser(grammar, namespace)

Evaluable parser.

Parameters:
class booleano.parser.parsers.ConvertibleParser(grammar)

Convertible parser.

Parameter:grammar (booleano.parser.Grammar) – The grammar used by the parser.

Parse trees

Parse trees.

Booleano supports two kinds of parse trees:

  • Evaluable parse trees, which are truth-evaluated against so-called context.
  • Convertible parse trees, which are converted into something else (e.g., SQL “WHERE” clauses) using so-called parse tree converters.
class booleano.parser.trees.ParseTree(root_node)

Bases: object

Base class for parse trees.

Parameter:root_node (booleano.operations.OperationNode) – The root node of the parse tree.
class booleano.parser.trees.EvaluableParseTree(root_node)

Bases: booleano.parser.trees.ParseTree

Truth-evaluable parse tree.

Parameter:root_node (booleano.operations.OperationNode) – The root node of the parse tree.
Raises booleano.exc.InvalidOperationError:
 If the root_node is an operand that doesn’t support logical values.
class booleano.parser.trees.ConvertibleParseTree(root_node)

Bases: booleano.parser.trees.ParseTree

Convertible parse tree.

Parameter:root_node (booleano.operations.OperationNode) – The root node of the parse tree.