Grammar

Query grammar definition.

class cumin.grammar.Backend(keyword, name, cls)

Bases: tuple

collections.namedtuple() that define a Backend object.

Keyword Arguments
  • keyword (str) -- The backend keyword to be used in the grammar.

  • name (str) -- The backend name.

  • cls (BaseQuery) -- The backend class object.

cls

See the Keyword Arguments description.

keyword

See the Keyword Arguments description.

name

See the Keyword Arguments description.

cumin.grammar.get_registered_backends(external=())[source]

Get a mapping of all the registered backends with their keyword.

Parameters

external (list, tuple, optional) -- external backend modules to register.

Returns

A dictionary with a {keyword: Backend object} mapping for each available backend.

Return type

dict

Raises

cumin.CuminError -- If unable to register a backend.

cumin.grammar.grammar(backend_keys)[source]

Define the main multi-query grammar.

Cumin provides a user-friendly generic query language that allows to combine the results of subqueries for multiple backends:

  • Each query part can be composed with the others using boolean operators and, or, and not, xor.

  • Multiple query parts can be grouped together with parentheses (, ).

  • Specific backend query I{backend-specific query syntax}, where I is an identifier for the specific backend.

  • Alias replacement, according to aliases defined in the configuration file A:group1.

  • The identifier A is reserved for the aliases replacement and cannot be used to identify a backend.

  • A complex query example: (D{host1 or host2} and (P{R:Class = Role::MyClass} and not A:group1)) or D{host3}

Backus-Naur form (BNF) of the grammar:

      <grammar> ::= <item> | <item> <boolean> <grammar>
         <item> ::= <backend_query> | <alias> | "(" <grammar> ")"
<backend_query> ::= <backend> "{" <query> "}"
        <alias> ::= A:<alias_name>
      <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.

Parameters

backend_keys (list) -- list of the GRAMMAR_PREFIX for each registered backend.

Returns

the grammar parser.

Return type

pyparsing.ParserElement