Query

Query handling: factory and builder.

class cumin.query.Query(config, logger=None)

Bases: cumin.backends.BaseQueryAggregator

Cumin main query class.

It has multi-query capability and allow to use a default backend, if set, without additional syntax. If a default_backend is set in the configuration, it will try to execute the query string first with the default backend and only if the query is not parsable with that backend it will try to execute it with the multi-query grammar.

When a query is executed, a ClusterShell.NodeSet.NodeSet with the FQDN of the matched hosts is returned.

Examples

>>> import cumin
>>> from cumin.query import Query
>>> config = cumin.Config()
>>> hosts = Query(config, logger=logger).execute(query_string)

__init__(config, logger=None)

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(). Raises:cumin.backends.InvalidQueryError -- on internal parsing error.

_query_default_backend(query_string)

Execute the query with the default backend, according to the configuration.

Parameters:query_string (str) -- the query string to be parsed and executed with the default backend. Returns:with the FQDNs of the matching hosts. Return type:ClusterShell.NodeSet.NodeSet Raises:cumin.backends.InvalidQueryError -- if unable to get the default backend from the registered backends.

_replace_alias(token_dict)

Replace any alias in the query in a recursive way, alias can reference other aliases.

Parameters:token_dict (dict) -- the dictionary of the parsed token returned by the grammar parsing. Returns:True if a replacement was made, :py:data`False` otherwise. Return type:bool Raises:cumin.backends.InvalidQueryError -- if unable to replace an alias.

execute(query_string)

Override parent class execute method to implement the multi-query capability.

Parameters:according to parent cumin.backends.BaseQueryAggregator.execute(). Returns:with the FQDNs of the matching hosts. Return type:ClusterShell.NodeSet.NodeSet Raises:cumin.backends.InvalidQueryError -- if unable to parse the query.

grammar = Forward: ...

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