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.

property cls
property keyword
property name
cumin.grammar.INTERNAL_BACKEND_PREFIX = 'cumin.backends'

str with the prefix for built-in backends.

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

cumin.grammar._import_backend(module, available_backends)[source]

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