Backends

Abstract backend.

exception cumin.backends.InvalidQueryError

Bases: CuminError

Custom exception class for invalid queries.

class cumin.backends.BaseQuery(config)

Bases: object

abstract Query abstract class.

All backends query classes must inherit, directly or indirectly, from this one.

Query constructor.

Parameters:

config (dict) -- a dictionary with the parsed configuration file.

grammar = NoMatch

derived classes must define their own pyparsing grammar and set this class attribute accordingly.

Type:

pyparsing.ParserElement

execute(query_string)

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

abstract _execute()

Execute the already parsed query and return the NodeSet of FQDN hostnames that matches.

Returns:

with the FQDNs of the matching hosts.

Return type:

ClusterShell.NodeSet.NodeSet

abstract _parse_token(token)

Recursively interpret the tokens returned by the grammar parsing.

Parameters:

token (pyparsing.ParseResults) -- a single token returned by the grammar parsing.

_build(query_string)

Parse the query string according to the grammar and build the query for later execution.

Parameters:

query_string (str) -- the query string to be parsed.

class cumin.backends.BaseQueryAggregator(config)

Bases: BaseQuery

abstract Query aggregator abstract class.

Add to cumin.backends.BaseQuery the capability of aggregating query subgroups and sub tokens into a unified result using common boolean operators for sets: and, or, and not and xor. The class has a stack-like structure that must be populated by the derived classes while building the query. On execution the stack is traversed and the results are aggreagated together based on subgroups and boolean operators.

Query aggregator constructor, initialize the stack.

Parameters:

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

_build(query_string)

Override parent method to reset the stack and log it.

Parameters:

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

_execute()

Concrete implementation of parent abstract method.

Parameters:

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

_open_subgroup()

Handle subgroup opening.

_close_subgroup()

Handle subgroup closing.

abstract _parse_token(token)

Re-define abstract method from parent abstract class.

Parameters:

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

static _get_stack_element()

Return an empty stack element.

Returns:

the dictionary with an empty stack element.

Return type:

dict

_loop_stack(hosts, stack_element)

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.

_aggregate_hosts(hosts, element_hosts, bool_operator)

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.

Available backends

• Direct
  • grammar()
  • DirectQuery
    • DirectQuery.grammar
    • DirectQuery._parse_token()
  • GRAMMAR_PREFIX
  • query_class
• KnownHosts
  • grammar()
  • KnownHostsLineError
  • KnownHostsSkippedLineError
  • KnownHostsQuery
    • KnownHostsQuery.grammar
    • KnownHostsQuery._build()
    • KnownHostsQuery._execute()
    • KnownHostsQuery._parse_token()
    • KnownHostsQuery._load_known_hosts()
    • KnownHostsQuery.parse_known_hosts_line()
    • KnownHostsQuery.parse_line_hosts()
  • GRAMMAR_PREFIX
  • query_class
• OpenStack
  • grammar()
  • _get_keystone_session()
  • _get_nova_client()
  • OpenStackQuery
    • OpenStackQuery.grammar
    • OpenStackQuery._get_default_search_params()
    • OpenStackQuery._build()
    • OpenStackQuery._execute()
    • OpenStackQuery._parse_token()
    • OpenStackQuery._get_projects()
    • OpenStackQuery._get_project_hosts()
  • GRAMMAR_PREFIX
  • query_class
• PuppetDB
  • CATEGORIES
  • OPERATORS
  • ParsedString
    • ParsedString.capwords()
    • ParsedString.replace()
  • grammar()
  • PuppetDBQuery
    • PuppetDBQuery.base_url_template
    • PuppetDBQuery.endpoints
    • PuppetDBQuery.category_prefixes
    • PuppetDBQuery.grammar
    • PuppetDBQuery.endpoint
    • PuppetDBQuery._open_subgroup()
    • PuppetDBQuery._close_subgroup()
    • PuppetDBQuery._get_grouped_tokens()
    • PuppetDBQuery._build()
    • PuppetDBQuery._execute()
    • PuppetDBQuery._add_category()
    • PuppetDBQuery._add_hosts()
    • PuppetDBQuery._parse_token()
    • PuppetDBQuery._get_resource_query()
    • PuppetDBQuery._get_special_resource_query()
    • PuppetDBQuery._get_query_string()
    • PuppetDBQuery._add_bool()
    • PuppetDBQuery._api_call()
  • GRAMMAR_PREFIX
  • query_class