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

Alias for field number 2

keyword

Alias for field number 0

name

Alias for field number 1

cumin.grammar.INTERNAL_BACKEND_PREFIX = 'cumin.backends'

str with the prefix for built-in backends.

cumin.grammar.get_registered_backends(external=())

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)

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

cumin.grammar._import_backend(module, available_backends)

Dynamically import a backend for Cumin and validate it.

Parameters:

• module (str) -- the full module name of the backend to register. Must be importable from Python PATH.

• available_backends (dict) -- dictionary with a {keyword: Backend object} mapping for all registered backends.

Returns:

with two elements: (keyword, Backend object) of the imported backend.

Return type:

tuple