booleano.operations – Boolean Operation Nodes

Boolean operation nodes and utilities.

In other words, this package contains the elements of the parse trees.

Once parsed, the binary expressions are turned into the relevant operation using the classes provided by this package.

class booleano.operations.OperationNode

Base class for the individual elements available in a boolean operation (i.e., operands and operations).

It can also be seen as the base class for each node in the parse trees.

__call__(context)

Evaluate the operation, by passing the context to the inner operands/operators.

Parameter:context (object) – The evaluation context. Returns:The logical value of the operation node. Return type:bool

is_branch()

Check if this is a branch node.

Return type:bool

Branch nodes are those that contain other nodes (operands or operators): All the operators, plus Set, Function and PlaceholderFunction.

is_leaf()

Check if this is a leaf node.

Return type:bool

Leaf nodes are those that don’t contain other nodes (operands or operators): String, Number, Variable and PlaceholderVariable.

is_operand()

Check if this node is an operand.

Return type:bool

is_operator()

Check if this node is an operation.

Return type:bool

Operands

class booleano.operations.operands.Operand

Base class for operands.

Constants

class booleano.operations.operands.constants.Constant(constant_value)

Base class for constant operands.

The only operation that is common to all the constants is equality (see equals()).

Constants don’t rely on the context – they are constant!

Warning

This class is available as the base for the built-in String, Number and Set classes. User-defined constants aren’t supported, but you can assign a name to a constant (see binding).

Parameter:constant_value (object) – The Python value represented by the Booleano constant.

class booleano.operations.String(string)

Constant string.

These constants only support equality operations.

Note

Membership operations aren’t supported

Although both sets and strings are item collections, the former is unordered and the later is ordered. If they were supported, there would some ambiguities to sort out, because users would expect the following operation results:

• "ao" ⊂ "hola" is false: If strings were also sets, then the resulting operation would be {"a", "o"} ⊂ {"h", "o", "l", "a"}, which is true.
• "la" ∈ "hola" is true: If strings were also sets, then the resulting operation would be {"l", "a"} ∈ {"h", "o", "l", "a"}, which would be an invalid operation because the first operand must be an item, not a set. But if we make an exception and take the first operand as an item, the resulting operation would be "la" ∈ {"h", "o", "l", "a"}, which is not true.

The solution to the problems above would involve some magic which contradicts the definition of a set: Take the second operand as an ordered collection. But it’d just cause more trouble, because both operations would be equivalent!

Also, there would be other issues to take into account (or not), like case-sensitivity.

Therefore, if this functionality is needed, developers should create functions to handle it.

Parameter:string (basestring) – The Python string to be represented by this Booleano string.

string will be converted to unicode, so it doesn’t have to be a basestring initially.

class booleano.operations.Number(number)

Numeric constant.

These constants support inequality operations; see greater_than() and less_than().

Parameter:number (object) – The number to be represented, as a Python object.

number is converted into a float internally, so it can be an string initially.

class booleano.operations.Set(*items)

Constant sets.

These constants support membership operations; see contains() and is_subset().

Raises booleano.exc.InvalidOperationError:  If at least one of the items is not an operand.

Classes

Note we’re talking about Booleano classes, not Python classes. These are used in evaluable parsing.

class booleano.operations.operands.classes.Class

Base class for Booleano’s anonymous classes.

The classes are anonymous because the have no notion of binding. From the Wikipedia:

In most languages, a class is bound to a name or identifier upon definition. However, some languages allow classes to be defined without names. Such a class is called an anonymous class (analogous to named vs. anonymous functions).

class booleano.operations.Variable

Developer-defined variable.

class booleano.operations.Function(*arguments)

Base class for calls of developer-defined, n-ary functions.

Instances of this Python class represent calls of the function, not the function itself.

Subclasses must override check_arguments() to verify the validity of the arguments, or to do nothing if it’s not necessary. They must also define required_arguments and optional_arguments.

Raises booleano.exc.BadCallError:  If check_arguments() finds that the arguments are invalid, or if few arguments are passed, or if too much arguments are passed.

check_arguments()

Check if all the arguments are correct.

Raises booleano.exc.BadCallError:  If at least one of the arguments are incorrect.

This method must be overridden in subclasses.

The arguments dictionary will be available in the arguments attribute. If any of them is wrong, this method must raise a BadCallError exception.

check_equivalence(node)

Make sure function node and this function are equivalent.

Parameter:node (Function) – The other function which may be equivalent to this one. Raises AssertionError:  If node is not a function or if it’s a function but doesn’t have the same arguments as this one OR doesn’t have the same names as this one.

all_args

The names of all the arguments, required and optional.

Type:tuple

This is set automatically when the class is defined.

arity

The arity of the function (i.e., the sum of the amount of the required arguments and the amount of optional arguments).

Type:int

This is set automatically when the class is defined.

optional_arguments

The optional arguments along with their default values.

Type:dict

This is a dictionary whose keys are the argument names and the items are their respective default values.

For example, if you have a binary function whose arguments are both optional ("name" and "address"), your function should be defined as:

from booleano.operations import String, Number, Function

class MyFunction(Function):

    # (...)

    optional_arguments = {
        'id': Number(5),
        'name': String("Gustavo"),
        'address': String("Somewhere in Madrid"),
        }

    # (...)

Then when it’s called without these arguments, their default values will be taken.

required_arguments

The names of the required arguments.

Type:tuple

For example, if you have a binary function whose required arguments are "name" and "address", your function should be defined as:

from booleano.operations import Function

class MyFunction(Function):

    # (...)

    required_arguments = ("name", "address")

    # (...)

Placeholder instances

Note we’re talking about placeholders for instances of Booleano classes, not Python class instances. These are used in convertible parsing.

class booleano.operations.operands.placeholders.PlaceholderInstance(name, namespace_parts=None)

Base class for placeholders of Booleano class instances.

Initially, placeholder operands support all the operations. It’s up to the converter to verify if the instance is used correctly.

Parameters:

• name (basestring) – The name for this placeholder.
• namespace_parts (tuple) – The identifiers in the namespace that contains the placeholder.

class booleano.operations.PlaceholderVariable(name, namespace_parts=None)

Placeholder variable.

Parameters:

• name (basestring) – The name for this placeholder.
• namespace_parts (tuple) – The identifiers in the namespace that contains the placeholder.

class booleano.operations.PlaceholderFunction(function_name, namespace_parts=None, *arguments)

Placeholder for a function call.

Parameters:

• function_name (basestring) – The name of the function to be represented.
• namespace_parts (tuple) – The identifiers in the namespace that contains the placeholder function.

Raises BadCallError:  

If one of the arguments is not an Operand.

Operators

Logical connectives

class booleano.operations.Not(operand)

The logical negation (~).

Negate the boolean representation of an operand.

Raises booleano.exc.InvalidOperationError:  If operand doesn’t have a logical value.

class booleano.operations.And(left_operand, right_operand)

The logical conjunction (AND).

Connective that checks if two operations evaluate to True.

With this binary operator, the operands can be actual operands or operations.

Raises booleano.exc.InvalidOperationError:  If left_operand or right_operand doesn’t have logical values.

class booleano.operations.Xor(left_operand, right_operand)

The logical exclusive disjunction (XOR).

Connective that checks if only one, out of two operations, evaluate to True.

With this binary operator, the operands can be actual operands or operations.

Raises booleano.exc.InvalidOperationError:  If left_operand or right_operand doesn’t have logical values.

class booleano.operations.Or(left_operand, right_operand)

The logical inclusive disjunction (OR).

Connective that check if at least one, out of two operations, evaluate to True.

With this binary operator, the operands can be actual operands or operations.

Raises booleano.exc.InvalidOperationError:  If left_operand or right_operand doesn’t have logical values.

Relational operators

class booleano.operations.Equal(left_operand, right_operand)

The equality operator (==).

Checks that two operands are equivalent.

For example: 3 == 3.

Parameters:

• left_operand (booleano.operations.operands.Operand) – The left-hand operand handled by this operator.
• right_operand (booleano.operations.operands.Operand) – The right-hand operand handled by this operator.

Raises booleano.exc.InvalidOperationError:  

If the master operand between left_operand or right_operand doesn’t support equality operations.

class booleano.operations.NotEqual(left_operand, right_operand)

The “not equal to” operator (!=).

Checks that two operands are not equivalent.

For example: 3 != 2.

Parameters:

• left_operand (booleano.operations.operands.Operand) – The left-hand operand handled by this operator.
• right_operand (booleano.operations.operands.Operand) – The right-hand operand handled by this operator.

Raises booleano.exc.InvalidOperationError:  

If the master operand between left_operand or right_operand doesn’t support equality operations.

class booleano.operations.LessThan(left_operand, right_operand)

The “less than” operator (<).

For example: 2 < 3.

class booleano.operations.GreaterThan(left_operand, right_operand)

The “greater than” operator (>).

For example: 3 > 2.

class booleano.operations.LessEqual(left_operand, right_operand)

The “less than or equal to” operator (<=).

For example: 2 <= 3.

class booleano.operations.GreaterEqual(left_operand, right_operand)

The “greater than or equal to” operator (>=).

For example: 2 >= 2.

Membership operators

class booleano.operations.BelongsTo(left_operand, right_operand)

The “belongs to” operator (∈).

For example: "valencia" ∈ {"caracas", "maracay", "valencia"}.

Raises booleano.exc.InvalidOperationError:  If right_operand doesn’t support membership operations.

class booleano.operations.IsSubset(left_operand, right_operand)

The “is a subset of” operator (⊂).

For example: {"valencia", "aragua"} ⊂ {"caracas", "aragua", "valencia"}.

Raises booleano.exc.InvalidOperationError:  If right_operand doesn’t support membership operations.

Parse tree converters

Converters for Booleano parse tree structures (the convertible, not the evaluable ones).

class booleano.operations.converters.BaseConverter

The base class for converters.

All the methods of this class are abstract, except for __call__() and convert().

__call__(root_node)

Convert root_node.

Parameter:root_node (booleano.operations.OperationNode) – The root of the tree to be converted. Returns:The tree converted. Raises booleano.exc.ConversionError:  If the type of root_node is unknown.

If node is a branch, its children will be converted first.

convert(node)

Convert node.

Parameter:node (booleano.operations.OperationNode) – The node to be converted. Returns:The node converted.

If node is a branch, its children will be converted first.

This is the method in charge of calling the right conversion method for the type of node and it should not be called directly (use __call__() instead).

convert_and(master_operand, slave_operand)

Convert AND connective whose left-hand operand is master_operand and right-hand operand is slave_operand.

Parameters:

• master_operand (object) – The left-hand operand, already converted.
• slave_operand (object) – The right-hand operand, already converted.

Return type:

object

convert_belongs_to(master_operand, slave_operand)

Convert “belongs to” operation where the set is master_operand and the element is slave_operand.

Parameters:

• master_operand (object) – The set already converted.
• slave_operand (object) – The element already converted.

Return type:

object

convert_equal(master_operand, slave_operand)

Convert equality operation whose left-hand operand is master_operand and right-hand operand is slave_operand.

Parameters:

• master_operand (object) – The left-hand operand, already converted.
• slave_operand (object) – The right-hand operand, already converted.

Return type:

object

convert_function(name, namespace_parts, *arguments)

Convert the function call to name using the additional positional arguments as the arguments of the call.

Parameters:

• name (basestring) – The name of the function being called.
• namespace_parts (list) – The namespace of the function (if any), represented by the identifiers that make it up.

Return type:

object

The arguments will be received converted.

convert_greater_equal(master_operand, slave_operand)

Convert “greater than or equal to” operation whose left-hand operand is master_operand and right-hand operand is slave_operand.

Parameters:

• master_operand (object) – The left-hand operand, already converted.
• slave_operand (object) – The right-hand operand, already converted.

Return type:

object

convert_greater_than(master_operand, slave_operand)

Convert “greater than” operation whose left-hand operand is master_operand and right-hand operand is slave_operand.

Parameters:

• master_operand (object) – The left-hand operand, already converted.
• slave_operand (object) – The right-hand operand, already converted.

Return type:

object

convert_is_subset(master_operand, slave_operand)

Convert “is subset of” operation where the superset is master_operand and the subset is slave_operand.

Parameters:

• master_operand (object) – The superset already converted.
• slave_operand (object) – The subset already converted.

Return type:

object

convert_less_equal(master_operand, slave_operand)

Convert “less than or equal to” operation whose left-hand operand is master_operand and right-hand operand is slave_operand.

Parameters:

• master_operand (object) – The left-hand operand, already converted.
• slave_operand (object) – The right-hand operand, already converted.

Return type:

object

convert_less_than(master_operand, slave_operand)

Convert “less than” operation whose left-hand operand is master_operand and right-hand operand is slave_operand.

Parameters:

• master_operand (object) – The left-hand operand, already converted.
• slave_operand (object) – The right-hand operand, already converted.

Return type:

object

convert_not(operand)

Convert negation function whose argument is operand.

Parameter:operand (object) – The argument already converted. Return type:object

convert_not_equal(master_operand, slave_operand)

Convert “not equal to” operation whose left-hand operand is master_operand and right-hand operand is slave_operand.

Parameters:

• master_operand (object) – The left-hand operand, already converted.
• slave_operand (object) – The right-hand operand, already converted.

Return type:

object

convert_number(number)

Convert the literal number number.

Parameter:number (float) – The literal number. Return type:object

convert_or(master_operand, slave_operand)

Convert OR connective whose left-hand operand is master_operand and right-hand operand is slave_operand.

Parameters:

• master_operand (object) – The left-hand operand, already converted.
• slave_operand (object) – The right-hand operand, already converted.

Return type:

object

convert_set(*elements)

Convert the literal set with the elements.

Return type:object

convert_string(text)

Convert the literal string text.

Parameter:text (basestring) – The contents of the literal string. Return type:object

convert_variable(name, namespace_parts)

Convert the variable called name.

Parameters:

• name (basestring) – The name of the variable.
• namespace_parts (list) – The namespace of the variable (if any), represented by the identifiers that make it up.

Return type:

object

convert_xor(master_operand, slave_operand)

Convert XOR connective whose left-hand operand is master_operand and right-hand operand is slave_operand.

Parameters:

• master_operand (object) – The left-hand operand, already converted.
• slave_operand (object) – The right-hand operand, already converted.

Return type:

object