Development

Code Structure

Query and global grammar

The cumin.query.Query class is the one taking care of replacing the aliases, building and executing the query parts with their respective backends and aggregating the results using the global grammar defined in cumin.grammar.grammar(). Once a query is executed, it returns a ClusterShell.NodeSet.NodeSet with the FQDN of all the hosts that matches the selection.

Backends

All the backends share a minimal common interface that is defined in the cumin.backends.BaseQuery class and they are instantiated by the Query class when building and executing the query. Each backend module need to define a query_class module variable that is a pointer to the backend class for dynamic instantiation and a GRAMMAR_PREFIX constant string that is the identifier to be used in the main query syntax to identify the backend. A is a reserved GRAMMAR_PREFIX used in the main grammar for aliases. Some backends are optional, in the sense that their dependencies are not installed automatically, they are available as an extras_require when installing from pip or as Suggested in the Debian package.

Given that the pyparsing library used to define the backend grammars uses a BNF-like style, for the details of the tokens not specified in each backend BNF, see directly the code in the grammar function in the backend module.

Running tests

The tox utility, a wrapper around virtualenv, is used to run the tests. To list the default environements that will be executed when running tox without parameters, run:

tox -lv

To list all the available environments:

tox -av

To run one specific environment only:

tox -e flake8

It's possible to pass extra arguments to the underlying environment:

# Run only tests in a specific file:
tox -e unit -- -k test_puppetdb.py

# Run only one specific test:
tox -e unit -- -k test_invalid_grammars

Integration tests are also available, but are not run by default by tox. They depends on a running Docker instance. To run them:

tox -e integration