pypuppetdbquery package

This Python package contains a port of Erik Dalén‘s PuppetDB Query language to Python.

All the user-facing components of this package are intended to be found in this module itself rather than any of the sub-modules.

pypuppetdbquery.parse(s, json=True, mode='nodes', lex_options=None, yacc_options=None)[source]

Parse a PuppetDBQuery-style query and transform it into a PuppetDB “AST” query.

This function is intented to be the primary entry point for this package. It wraps up all the various components of this package into an easy to consume format. The output of this function is designed to be passed directly into pypuppetdb.

For examples of the query syntax see puppet-puppetdbquery and node-puppetdbquery by Erik Dalén.

Parameters:
  • s (str) – The query to parse and transform
  • mode (str) – The PuppetDB endpoint being queried
  • json (bool) – Whether to JSON-encode the PuppetDB AST result
  • lex_options (dict) – Options passed to ply.lex.lex()
  • yacc_options (dict) – Options passed to ply.yacc.yacc()
pypuppetdbquery.query_fact_contents(pdb, s, facts=None, raw=False, lex_options=None, yacc_options=None)[source]

Helper to query PuppetDB for fact contents (i.e. within structured facts) on nodes matching a query string.

Adjusts the query to return only those strucutred fact keys requested in the function call.

The facts listed in the facts list are run through the query parser and treated as “identifier paths”. This means the same rules apply as for within the query language, e.g. foo.bar or foo.* or even foo.~"bar.*".

If raw is False (the default), the return value is a dict with node names as keys containing a dict of flattened fact paths to fact values. If True it returns raw query output: a list of dictionaries (see the PuppetDB fact-contents documentation).

Note

This function can only be used to search deeply within structured facts. It cannot return a whole structured fact, only individual elements within—but you can return all the elements within a structured fact if you want by using a regex match.

Parameters:
  • pdb (pypuppetdb.api.BaseAPI) – pypuppetdb connection to query from
  • s (str) – The query string (may be empty to query all nodes)
  • facts (Sequence) – List of fact paths to search for
  • raw (bool) – Whether to skip post-processing the facts into a dict structure grouped by node
  • lex_options (dict) – Options passed to ply.lex.lex()
  • yacc_options (dict) – Options passed to ply.yacc.yacc()
pypuppetdbquery.query_facts(pdb, s, facts=None, raw=False, lex_options=None, yacc_options=None)[source]

Helper to query PuppetDB for facts on nodes matching a query string.

Adjusts the query to return only those facts requested in the function call.

The fact names included in facts may be names or regular expressions. If the string starts and ends with /, it is considered a regular expression (e.g. /^lsb/).

If raw is False (the default), the return value is a dict with node names as keys containing a dict of fact names to fact values. If True it returns raw pypuppetdb.types.Fact objects as pypuppetdb.api.BaseAPI.nodes() does.

Note

This function can return only full facts, not elements of structured facts. For example, only the whole os fact may be returned but not the os.family key within the larger structured fact. If you need to do this, look at query_fact_contents().

Parameters:
  • pdb (pypuppetdb.api.BaseAPI) – pypuppetdb connection to query from
  • s (str) – The query string (may be empty to query all nodes)
  • facts (Sequence) – List of fact names to search for
  • raw (bool) – Whether to skip post-processing the facts into a dict structure
  • lex_options (dict) – Options passed to ply.lex.lex()
  • yacc_options (dict) – Options passed to ply.yacc.yacc()