Direct

Direct backend.

class cumin.backends.direct.DirectQuery(config)[source]

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)

static inherited Query aggregator constructor, initialize the stack.

Parameters

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

_aggregate_hosts(hosts, element_hosts, bool_operator)

static 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)

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

Parameters

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

_close_subgroup()

static inherited Handle subgroup closing.

_execute()

static inherited Concrete implementation of parent abstract method.

Parameters

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

static _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)

static 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()

static inherited Handle subgroup opening.

_parse_token(token)[source]

Concrete implementation of parent abstract method.

Parameters

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

execute(query_string)

static 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: ...

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

Type

pyparsing.ParserElement

cumin.backends.direct.GRAMMAR_PREFIX = 'D'

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().

Type

str

cumin.backends.direct.grammar()[source]

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 cumin.backends.direct.DirectQuery