pynspect.rules module

This module contains implementation of object representations of filtering and query language grammar.

There is a separate class defined for each grammar rule. There are following classes representing all possible constant and variable values (tree leaves, without child nodes):

There are following classes representing various binary and unary operations:

Additionally there is following class representing functions without/with arguments:

Desired hierarchical rule tree can be created either programatically, or by parsing string rules using pynspect.gparser.

Working with rule tree is then done via objects implementing rule tree traverser interface:

  • pynspect.traversers.RuleTreeTraverser

Please refer to module pynspect.traversers for list of currently available RuleTree traversers.

Rule evaluation

  • Logical operations and or xor not exists

    There is no special handling for operands of logical operations. Operand(s) are evaluated in logical expression exactly as they are received, there is no mangling involved.

  • Comparison operations

    All comparison operations are designed to work with lists as both operands. This is because pynspect.jpath.jpath_values() function is used to retrieve variable values and this function always returns list.

    • Operation: is

      Like in the case of logical operations, there is no mangling involved when evaluating this operation. Both operands are compared using Python`s native is operation and result is returned.

    • Operation: in

      In this case left operand is iterated and each value is compared using Python`s native in operation with right operand. First True result wins and operation immediatelly returns True, False is returned otherwise.

    • Any other operation: like eq ne gt ge lt le

      In case of this operation both of the operands are iterated and each one is compared with each other. First True result wins and operation immediatelly returns True, False is returned otherwise.

  • Math operations: + - * / %

    Current math operation implementation supports following options:

    • Both operands are lists of the same length. In this case corresponding elements at certain position within the list are evaluated with given operation. Result is a list.

    • One of the operands is a list, second is scalar value or list of the size 1. In this case given operation is evaluated with each element of the longer list. Result is a list.

    • Operands are lists of the different size. This option is forbidden and the result is None.

  • Functions: func1() func(192.168.1.1)

    Current implementation supports arbitrary functions. The grammar does not in any way enforce or define list of available functions. This task is up to the traverser (pynspect.traversers) that is going to be processing the rule tree.

    Functions can be with or without argument. Functions with argument can take any expression as single argument. Please refer to pynspect.gparser for definition of valid grammar. Following are examples of valid functions, which should ilustrate this peculiarity:

    func()
    func(127.0.0.1)
    func(::1)
    func(2017-01-01T12:00:00Z)
    func(1D00:00:00)
    func(1)
    func(1.1)
    func(Test)
    func(Test.Var)
    func("constant")
    func(sub())
    
    func([127.0.0.1,127.0.0.2])
    func([::1,::2])
    func([2017-01-01T12:00:00Z,2017-02-01T12:00:00Z])
    func([1D00:00:00,2D00:00:00])
    func([1,2])
    func([1.1,2.2])
    func([Test,Another])
    func([Test.Var,Another.Var])
    func(["constant1","constant2"])
    
class pynspect.rules.BinaryOperationRule(operation, left, right)[source]

Bases: OperationRule

Base class for all expression binary operations.

class pynspect.rules.ComparisonBinOpRule(operation, left, right)[source]

Bases: BinaryOperationRule

Base class for all expression comparison binary operations.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.binary_operation_comparison() method with reference to self instance as first argument, with the result of traversing left subtree as second argument and with the result of traversing right subtree as third argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

class pynspect.rules.ConstantRule(value)[source]

Bases: ValueRule

Class representing filtering expression string constants.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.constant() method with reference to self instance as first argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

class pynspect.rules.DatetimeRule(value)[source]

Bases: ConstantRule

Class representing filtering expression datetime constants.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.datetime() method with reference to self instance as first argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

exception pynspect.rules.FilteringRuleException(description)[source]

Bases: Exception

Custom filtering rule specific exception.

This exception will be thrown on module specific errors.

class pynspect.rules.FloatRule(value)[source]

Bases: NumberRule

Class representing filtering expression floating point numerical constants.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.float() method with reference to self instance as first argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

class pynspect.rules.FunctionRule(function, *args)[source]

Bases: Rule

Base class for all expression binary operations.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.function() method with reference to self instance as first argument and with the result of traversing left subtree as second argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

class pynspect.rules.IPV4Rule(value)[source]

Bases: ConstantRule

Class representing filtering expression IPv4 address/range/network constants.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.ipv4() method with reference to self instance as first argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

class pynspect.rules.IPV6Rule(value)[source]

Bases: ConstantRule

Class representing filtering expression IPv6 address/range/network constants.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.ipv6() method with reference to self instance as first argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

class pynspect.rules.IntegerRule(value)[source]

Bases: NumberRule

Class representing filtering expression integer numerical constants.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.integer() method with reference to self instance as first argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

class pynspect.rules.ListRule(rule, next_rule=None)[source]

Bases: ValueRule

Class representing filtering expression list of constants.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.list() method with reference to self instance as first argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

values()[source]

Return true values of the rules in the list.

class pynspect.rules.LogicalBinOpRule(operation, left, right)[source]

Bases: BinaryOperationRule

Base class for all expression logical binary operations.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.binary_operation_logical() method with reference to self instance as first argument, with the result of traversing left subtree as second argument and with the result of traversing right subtree as third argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

class pynspect.rules.MathBinOpRule(operation, left, right)[source]

Bases: BinaryOperationRule

Base class for all expression mathematical binary operations.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.binary_operation_math() method with reference to self instance as first argument, with the result of traversing left subtree as second argument and with the result of traversing right subtree as third argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

class pynspect.rules.NumberRule(value)[source]

Bases: ConstantRule

Base class for all filtering expression numerical constants.

class pynspect.rules.OperationRule[source]

Bases: Rule

Base class for all expression operations (both unary and binary).

class pynspect.rules.Rule[source]

Bases: object

Base class for all filter tree rules.

traverse(traverser, **kwargs)[source]

Mandatory interface for traversing the whole rule tree. This method must call apropriate method of given traverser object with apropriate arguments. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

class pynspect.rules.TimedeltaRule(value)[source]

Bases: ConstantRule

Class representing filtering expression timedelta constants.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.timedelta() method with reference to self instance as first argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

class pynspect.rules.UnaryOperationRule(operation, operand)[source]

Bases: OperationRule

Base class for all expression unary operations.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.binary_operation_logical() method with reference to self instance as first argument and with the result of traversing left subtree as second argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.

class pynspect.rules.ValueRule(value)[source]

Bases: Rule

Base class for all filter tree value rules.

class pynspect.rules.VariableRule(value)[source]

Bases: ValueRule

Class representing filtering expression variables.

traverse(traverser, **kwargs)[source]

Implementation of mandatory interface for traversing the whole rule tree. This method will call the implementation of pynspect.rules.RuleTreeTraverser.variable() method with reference to self instance as first argument. The optional kwargs are passed down to traverser callback as additional arguments and can be used to provide additional data or context.

Parameters
  • traverser (pynspect.rules.RuleTreeTraverser) – Traverser object providing appropriate interface.

  • kwargs (dict) – Additional optional keyword arguments to be passed down to traverser callback.