Direct

Direct backend.

class cumin.backends.direct.DirectQuery(config)

Bases: cumin.backends.BaseQueryAggregator

DirectQuery query builder.

The direct backend allow to use Cumin without any external dependency for the hosts selection. It allow to write arbitrarily complex queries with subgroups and boolean operators, but each item must be either the hostname itself, or the using host expansion using the powerful ClusterShell.NodeSet.NodeSet syntax.

The typical usage for the direct backend is as a reliable alternative in cases in which the primary host selection mechanism is not working and also for testing the transports without any external backend dependency.

Some query examples:

• Simple selection: host1.domain
• ClusterShell syntax for hosts expansion: host10[10-42].domain,host2010.other-domain
• A complex selection: host100[1-5].domain or (host10[30-40].domain and (host10[10-42].domain and not host33.domain))

__init__(config)

inherited Query aggregator constructor, initialize the stack.

Parameters:according to parent cumin.backends.BaseQuery.__init__().

_aggregate_hosts(hosts, element_hosts, bool_operator)

inherited Aggregate hosts according to their boolean operator.

Parameters:

• hosts (ClusterShell.NodeSet.NodeSet) -- the hosts to update with the results in element_hosts according to the bool_operator. This object is updated in place by reference.
• element_hosts (ClusterShell.NodeSet.NodeSet) -- the additional hosts to aggregate to the results based on the bool_operator.
• bool_operator (str, None) -- the boolean operator to apply while aggregating the two NodeSet. It must be None when adding the first hosts.

_build(query_string)

inherited Override parent method to reset the stack and log it.

Parameters:according to parent cumin.backends.BaseQuery._build().

_close_subgroup()

inherited Handle subgroup closing.

_execute()

inherited Concrete implementation of parent abstract method.

Parameters:according to parent cumin.backends.BaseQuery._execute().

_get_stack_element()

static inherited Return an empty stack element.

Returns:the dictionary with an empty stack element. Return type:dict

_loop_stack(hosts, stack_element)

inherited Loop the stack generated while parsing the query and aggregate the results.

Parameters:

• hosts (ClusterShell.NodeSet.NodeSet) -- the hosts to be updated with the current stack element results. This object is updated in place by reference.
• stack_element (dict) -- the stack element to iterate.

_open_subgroup()

inherited Handle subgroup opening.

_parse_token(token)

Concrete implementation of parent abstract method.

Parameters:according to parent cumin.backends.BaseQueryAggregator._parse_token().

execute(query_string)

inherited Build and execute the query, return the NodeSet of FQDN hostnames that matches.

Parameters:query_string (str) -- the query string to be parsed and executed. Returns:with the FQDNs of the matching hosts. Return type:ClusterShell.NodeSet.NodeSet

grammar = Forward: ...

pyparsing.ParserElement -- load the grammar parser only once in a singleton-like way.

cumin.backends.direct.GRAMMAR_PREFIX = 'D'

str -- the prefix associate to this grammar, to register this backend into the general grammar. Required by the backend auto-loader in cumin.grammar.get_registered_backends().

cumin.backends.direct.grammar()

Define the query grammar.

Backus-Naur form (BNF) of the grammar:

<grammar> ::= <item> | <item> <boolean> <grammar>
   <item> ::= <hosts> | "(" <grammar> ")"
<boolean> ::= "and not" | "and" | "xor" | "or"

Given that the pyparsing library defines the grammar in a BNF-like style, for the details of the tokens not specified above check directly the source code.

Returns:the grammar parser. Return type:pyparsing.ParserElement

cumin.backends.direct.query_class

Required by the backend auto-loader in cumin.grammar.get_registered_backends().

alias of DirectQuery