Developer Guide

This part of the documentation covers all the interfaces of PyPuppetDB. It will cover how the API is set up and how to configure which version of the API to use.

Lazy objects

Note

Reading in the response from PuppetDB is currently greedy, it will read in the complete response no matter the size. This will change once streaming and pagination support are added to PuppetDB’s endpoints.

In order for pypuppetdb to be able to deal with big datasets those functions that are expected to return more than a single item are implemented as generators.

This is usually the case for functions with a plural name like nodes() or facts().

Because of this we’ll only query PuppetDB once you start iterating over the generator object. Until that time not a single request is fired at PuppetDB.

Most singular functions are implemented by calling their plural counterpart and then iterating over the generator, immediately exhausting the generator and returning a single/the first object.

API and BaseAPI classes

The starting point for the library is the connect() method used to set up a connection with PuppetDB.

pypuppetdb.connect(host='localhost', port=8080, ssl_verify=False, ssl_key=None, ssl_cert=None, timeout=10, protocol=None, url_path='/', username=None, password=None, token=None)[source]

Connect with PuppetDB. This will return an object allowing you to query the API through its methods.

Parameters:

  • host (string) – (Default: ‘localhost;) Hostname or IP of PuppetDB.

  • port (int) – (Default: ‘8080’) Port on which to talk to PuppetDB.

  • ssl_verify (bool or string True, False or filesystem path to CA certificate.) – (optional) Verify PuppetDB server certificate.

  • ssl_key (None or string representing a filesystem path.) – (optional) Path to our client secret key.

  • ssl_cert (None or string representing a filesystem path.) – (optional) Path to our client certificate.

  • timeout (int) – (Default: 10) Number of seconds to wait for a response.

  • protocol (None or string) – (optional) Explicitly specify the protocol to be used (especially handy when using HTTPS with ssl_verify=False and without certs)

  • url_path (None or string) – (Default: ‘/’) The URL path where PuppetDB is served

  • username (None or string) – (optional) The username to use for HTTP basic authentication

  • password (None or string) – (optional) The password to use for HTTP basic authentication

  • token (None or string) – (optional) The x-auth token to use for X-Authentication

This method returns the API class instance.

That class is built using mixins from the endpoint-specific classes, such as PqlAPI (see the next section for more info about them).

All the endpoint-specific classes inherit from the abstract BaseAPI class which contains the logic shared by all the endpoints, such as:

  • connecting to the PuppetDB (in the constructor),

  • disconnecting from the PuppetDB (disconnect()),

  • _query() and _make_request() that prepare and make HTTP(S) requests to PuppetDB,

Endpoint classes

The supported PuppetDB endpoint types are implemented in classes with corresponding names:

  • pdb/query/v4 - PqlAPI

  • pdb/query/v4/* - QueryAPI

  • pdb/cmd/v1 - CommandAPI

  • status/v1/** - StatusAPI

  • pdb/meta/v1* - MetadataAPI

  • metrics/* - MetricsAPI

PqlAPI

class pypuppetdb.api.PqlAPI(host='localhost', port=8080, ssl_verify=True, ssl_key=None, ssl_cert=None, timeout=10, protocol=None, url_path=None, username=None, password=None, token=None, metric_api_version=None)[source]

This class provides methods that interact with the pdb/query/v4 PuppetDB API endpoint.

static _get_type_from_query(pql)[source]

Gets a rich type of the entities returned by the given PQL query.

Parameters:

pql (string) – PQL query

Returns:

a rich type, if this library supports it otherwise - None

_pql(pql, request_method='GET')[source]

This method prepares a PQL query to PuppetDB. Actual making the HTTP request is done by _make_request().

Parameters:

  • pql (string) – PQL query

  • request_method – (optional) GET or POST, the default is GET

Raises:

EmptyResponseError

Returns:

The decoded response from PuppetDB

Return type:

dict or list

pql(pql, with_status=False, unreported=2, with_event_numbers=True)[source]

Makes a PQL (Puppet Query Language) and tries to cast results to a rich type. If it won’t work, returns plain dicts.

Parameters:

  • pql (string) – PQL query

  • with_status – (optional, only for queries for nodes) include the node status in the returned nodes

  • unreported (None or integer) – (optional, only for queries for nodes) amount of hours when a node gets marked as unreported

  • with_event_numbers – (optional, only for queries for nodes) include the exact number of changed/unchanged/failed/noop events when with_status is set to True. If set to False only “some” string is provided if there are resources with such status in the last report. This provides performance benefits as potentially slow event-counts query is omitted completely.

Returns:

A generator yielding elements of a rich type or plain dicts

QueryAPI

class pypuppetdb.api.QueryAPI(host='localhost', port=8080, ssl_verify=True, ssl_key=None, ssl_cert=None, timeout=10, protocol=None, url_path=None, username=None, password=None, token=None, metric_api_version=None)[source]

This class provides methods that interact with the pdb/query/v4/* PuppetDB API endpoints.

aggregate_event_counts(summarize_by, query=None, count_by=None, count_filter=None)[source]

Get event counts from puppetdb aggregated into a single map.

Parameters:

  • summarize_by (string) – (Required) The object type to be counted on. Valid values are ‘containing_class’, ‘resource’ and ‘certname’ or any comma-separated value thereof.

  • query (string) – (Optional) The PuppetDB query to filter the results. This query is passed to the events endpoint.

  • count_by (string) – (Optional) The object type that is counted when building the counts of ‘successes’, ‘failures’, ‘noops’ and ‘skips’. Support values are ‘certname’ and ‘resource’ (default)

  • count_filter (string) – (Optional) A JSON query that is applied to the event-counts output but before the results are aggregated. Supported operators are =, >, <, >=, and <=. Supported fields are failures, successes, noops, and skips.

Returns:

A dictionary of name/value results.

Return type:

dict

catalog(node)[source]

Get the available catalog for a given node.

Parameters:

node – (Required) The name of the PuppetDB node.

Type:

string

Returns:

An instance of Catalog

Return type:

pypuppetdb.types.Catalog

catalogs(**kwargs)[source]

Get the catalog information from the infrastructure based on path and/or query results. It is strongly recommended to include query and/or paging parameters for this endpoint to prevent large result sets or PuppetDB performance bottlenecks.

Parameters:

**kwargs – The rest of the keyword arguments are passed to the _query function.

Returns:

A generator yielding Catalogs

Return type:

pypuppetdb.types.Catalog

edges(**kwargs)[source]

Get the known catalog edges, formed between two resources.

Parameters:

**kwargs – The rest of the keyword arguments are passed to the _query function.

Returns:

A generating yielding Edges.

Return type:

pypuppetdb.types.Edge

environments(**kwargs)[source]

Get all known environments from Puppetdb.

Parameters:

**kwargs – The rest of the keyword arguments are passed to the _query function.

Returns:

A list of dictionaries containing the results.

Return type:

list of dict

event_counts(summarize_by, **kwargs)[source]

Get event counts from puppetdb.

Parameters:

  • summarize_by (string) – (Required) The object type to be counted on. Valid values are ‘containing_class’, ‘resource’ and ‘certname’.

  • count_by (string) – (Optional) The object type that is counted when building the counts of ‘successes’, ‘failures’, ‘noops’ and ‘skips’. Support values are ‘certname’ and ‘resource’ (default)

  • count_filter (string) – (Optional) A JSON query that is applied to the event-counts output but before the results are aggregated. Supported operators are =, >, <, >=, and <=. Supported fields are failures, successes, noops, and skips.

  • **kwargs – The rest of the keyword arguments are passed to the _query function.

Returns:

A list of dictionaries containing the results.

Return type:

list

events(**kwargs)[source]

A report is made up of events which can be queried either individually or based on their associated report hash. It is strongly recommended to include query and/or paging parameters for this endpoint to prevent large result sets or PuppetDB performance bottlenecks.

Parameters:

**kwargs – The rest of the keyword arguments are passed to the _query function

Returns:

A generator yielding Events

Return type:

pypuppetdb.types.Event

fact_contents(**kwargs)[source]

To complement fact_paths(), this endpoint provides the capability to descend into structured facts and retreive the values associated with fact paths.

Parameters:

**kwargs – The rest of the keyword arguments are passed to the _query function.

Returns:

A list of dictionaries containg the results.

Return type:

list of dict

fact_names()[source]

Get a list of all known facts.

fact_paths(**kwargs)[source]

Fact Paths are intended to be a counter-part of the fact-names endpoint. It provides increased granularity around structured facts and may be used for building GUI autocompletions or other applications that require a basic top-level view of fact paths.

Parameters:

**kwargs – The rest of the keyword arguments are passed to the _query function.

Returns:

A list of dictionaries containg the results.

Return type:

list of dict

facts(name=None, value=None, **kwargs)[source]

Query for facts limited by either name, value and/or query.

Parameters:

  • name (string) – (Optional) Only return facts that match this name.

  • value (string) – (Optional) Only return facts of name thatmatch this value. Use of this parameter requires the nameparameter be set.

  • **kwargs – The rest of the keyword arguments are passed to the _query function

Returns:

A generator yielding Facts.

Return type:

pypuppetdb.types.Fact

factsets(**kwargs)[source]

Returns a set of all facts or for a single certname.

Parameters:

**kwargs – The rest of the keyword arguments are passed to the _query function.

Returns:

A list of dictionaries containg the results.

Return type:

list of dict

inventory(**kwargs)[source]

Get Node and Fact information with an alternative query syntax for structured facts instead of using the facts, fact-contents and factsets endpoints for many fact-related queries.

Parameters:

**kwargs – The rest of the keyword arguments are passed to the _query function.

Returns:

A generator yielding Inventory

Return type:

pypuppetdb.types.Inventory

node(name)[source]

Gets a single node from PuppetDB.

Parameters:

name (string) – The name of the node search.

Returns:

An instance of Node

Return type:

pypuppetdb.types.Node

nodes(unreported=2, with_status=False, with_event_numbers=True, **kwargs)[source]

Query for nodes by either name or query. If both aren’t provided this will return a list of all nodes. This method also (optionally) fetches the nodes status and (optionally) event counts of the latest report from puppetdb.

Parameters:

  • with_status – (optional) include the node status in thereturned nodes

  • unreported (None or integer) – (optional) amount of hours when a node gets marked as unreported

  • with_event_numbers – (optional) include the exact number ofchanged/unchanged/failed/noop events whenwith_status is set to True. If set to False only “some” string is provided if there are resources with such status in the last report. This provides performance benefits as potentially slow event-counts query is omitted completely.

  • **kwargs – The rest of the keyword arguments are passed to the _query function

Returns:

A generator yieling Nodes.

Return type:

pypuppetdb.types.Node

reports(**kwargs)[source]

Get reports for our infrastructure. It is strongly recommended to include query and/or paging parameters for this endpoint to prevent large result sets and potential PuppetDB performance bottlenecks.

Parameters:

**kwargs – The rest of the keyword arguments are passed to the _query function

Returns:

A generating yielding Reports

Return type:

pypuppetdb.types.Report

resources(type_=None, title=None, **kwargs)[source]

Query for resources limited by either type and/or title or query. This will yield a Resources object for every returned resource.

Parameters:

  • type (string) – (Optional) The resource type. This can be any resource type referenced inhttps://puppet.com/docs/puppet/7/type.html

  • title (string) – (Optional) The name of the resource as declared as the ‘namevar’ in the Puppet Manifests. This parameter requires thetype_ parameter be set.

  • **kwargs – The rest of the keyword arguments are passed to the _query function

Returns:

A generator yielding Resources

Return type:

pypuppetdb.types.Resource

CommandAPI

class pypuppetdb.api.CommandAPI(host='localhost', port=8080, ssl_verify=True, ssl_key=None, ssl_cert=None, timeout=10, protocol=None, url_path=None, username=None, password=None, token=None, metric_api_version=None)[source]

This class provides methods that interact with the pdb/cmd/* PuppetDB API endpoints.

_cmd(command, payload)[source]

This method posts commands to PuppetDB. Provided a command and payload it will fire a request at PuppetDB. If PuppetDB can be reached and answers within the timeout we’ll decode the response and give it back or raise for the HTTP Status Code PuppetDB gave back.

Parameters:

  • command (dict) – The PuppetDB Command we want to execute.

  • command – The payload, in wire format, specific to the command.

Raises:

EmptyResponseError

Returns:

The decoded response from PuppetDB

Return type:

dict or list

StatusAPI

class pypuppetdb.api.StatusAPI(host='localhost', port=8080, ssl_verify=True, ssl_key=None, ssl_cert=None, timeout=10, protocol=None, url_path=None, username=None, password=None, token=None, metric_api_version=None)[source]

This class provides methods that interact with the status/* PuppetDB API endpoints.

status()[source]

Get PuppetDB server status.

Returns:

A dict with the PuppetDB status information

Return type:

dict

MetadataAPI

class pypuppetdb.api.MetadataAPI(host='localhost', port=8080, ssl_verify=True, ssl_key=None, ssl_cert=None, timeout=10, protocol=None, url_path=None, username=None, password=None, token=None, metric_api_version=None)[source]

This class provides methods that interact with the pdb/meta/* PuppetDB API endpoints.

current_version()[source]

Get version information about the running PuppetDB server.

Returns:

A string representation of the PuppetDB version.

Return type:

string

server_time()[source]

Get the current time of the clock on the PuppetDB server. :returns: An ISO-8091 formatting timestamp. :rtype: string

MetricsAPI

class pypuppetdb.api.MetricsAPI(host='localhost', port=8080, ssl_verify=True, ssl_key=None, ssl_cert=None, timeout=10, protocol=None, url_path=None, username=None, password=None, token=None, metric_api_version=None)[source]

This class provides methods that interact with the metrics/* PuppetDB API endpoints.

static _escape_metric_name(metric)[source]

Escapes metric names so they can be used in GET requests as part of the URL. The new (as of v2) metrics API is backed by the Jolokia library. The escpaing rules for Jolokia GET requests can be found here: https://jolokia.org/reference/html/protocol.html#escape-rules

Parameters:

metric (string) – The name of the metric we want to escape.

Returns:

The escaped version of the metric name, safe for use in metric GET queries.

metric(metric=None, version=None)[source]

Query for a specific metric.

Parameters:

  • metric (string) – The name of the metric we want.

  • version (string) – The version of the metric API to query. Valid values: ‘v1’, ‘v2’ If not specified, then the value of self.metric_api_version will be used.

Returns:

The return of _query().

Types

In order to facilitate working with the API most methods like nodes() don’t return the decoded JSON response but return an object representation of the querried endpoints data.

class pypuppetdb.types.Node(api, name, deactivated=None, expired=None, report_timestamp=None, catalog_timestamp=None, facts_timestamp=None, status_report=None, noop=False, noop_pending=False, events=None, unreported=False, unreported_time=None, report_environment='production', catalog_environment='production', facts_environment='production', latest_report_hash=None, cached_catalog_status=None)[source]

This object represents a node. It additionally has some helper methods so that you can query for resources or facts directly from the node scope. Unless otherwise specified all parameters are required.

Parameters:

  • api (pypuppetdb.api.BaseAPI) – API object.

  • name (string) – Hostname of this node.

  • deactivated (string formatted as %Y-%m-%dT%H:%M:%S.%fZ) – (default None) Time this node was deactivated at.

  • report_timestamp (string formatted as %Y-%m-%dT%H:%M:%S.%fZ) – (default None) Time of the last report.

  • catalog_timestamp (string formatted as %Y-%m-%dT%H:%M:%S.%fZ) – (default None) Time the last time a catalog was compiled.

  • facts_timestamp (string formatted as %Y-%m-%dT%H:%M:%S.%fZ) – (default None) Time the last time facts were collected.

  • status_report – (default None) Status of latest report from the node changed | unchanged | failed

  • noop (bool) – (Default False) A flag indicating whether the latest report of the node was produced by a noop run.

  • noop_pending (bool) – (Default False) A flag indicating whether the latest report of the node had pending changes produced by a noop run.

  • events (dict) – (default None) Counted events from latest Report

  • unreported – (default False) if node is considered unreported

  • unreported_time (string) – (default None) Time since last report

  • report_environment (string) – (default ‘production’) The environment of the last received report for this node

  • catalog_environment (string) – (default ‘production’) The environment of the last received catalog for this node

  • facts_environment (string) – (default ‘production’) The environment of the last received fact set for this node

  • latest_report_hash (string) – The hash of the latest report from this node, is only available in PuppetDB 3.2 and later

  • cached_catalog_status (string) – Cached catalog status of the last puppet run on this node, possible values are ‘explicitly_requested’, ‘on_failure’, ‘not_used’ or None.

Variables:

  • name – Hostname of this node.

  • deactivated – datetime.datetime when this host was deactivated or False.

  • report_timestamp – datetime.datetime when the last run occured or None.

  • catalog_timestamp – datetime.datetime last time a catalog was compiled or None.

  • facts_timestamp – datetime.datetime last time when facts were collected or None.

  • report_environment – string the environment of the last received report for this node.

  • catalog_environment – string the environment of the last received catalog for this node.

  • facts_environment – string the environment of the last received fact set for this node.

  • latest_report_hash – string the hash value of the latest report the current node reported. Available in PuppetDB 3.2 and later.

  • cached_catalog_status – string the status of the cached catalog from the last puppet run.

fact(name)[source]

Get a single fact from this node.

facts(query=None, **kwargs)[source]

Get all facts of this node. Additional arguments may also be specified that will be passed to the query function.

reports(**kwargs)[source]

Get all reports for this node. Additional arguments may also be specified that will be passed to the query function.

resource(type_, title, **kwargs)[source]

Get a resource matching the supplied type and title. Additional arguments may also be specified that will be passed to the query function.

resources(type_=None, title=None, **kwargs)[source]

Get all resources of this node or all resources of the specified type. Additional arguments may also be specified that will be passed to the query function.

class pypuppetdb.types.Fact(node, name, value, environment=None)[source]

This object represents a fact. Unless otherwise specified all parameters are required.

Parameters:

  • node (string) – The hostname this fact was collected from.

  • name (string) – The fact’s name, such as ‘osfamily’

  • value (string or int or dict) – The fact’s value, such as ‘Debian’

  • environment (string) – (Optional) The fact’s environment, such as ‘production’

Variables:

  • node – string holding the hostname.

  • name – string holding the fact’s name.

  • value – string or int or dict holding the fact’s value.

  • environment – string holding the fact’s environment

class pypuppetdb.types.Resource(node, name, type_, tags, exported, sourcefile, sourceline, environment=None, parameters={})[source]

This object represents a resource. Unless otherwise specified all parameters are required.

Parameters:

  • node (string) – The hostname this resource is located on.

  • name (string) – The name of the resource in the Puppet manifest.

  • type (string) – Type of the Puppet resource.

  • tags (list) – Tags associated with this resource.

  • exported (bool) – If it’s an exported resource.

  • sourcefile (string) – The Puppet manifest this resource is declared in.

  • sourceline (int) – The line this resource is declared at.

  • parameters (dict) – (Optional) The parameters this resource has been declared with.

  • environment (string) – (Optional) The environment of the node associated with this resource.

Variables:

  • node – The hostname this resources is located on.

  • name – The name of the resource in the Puppet manifest.

  • type – The type of Puppet resource.

  • exported – bool if the resource is exported.

  • sourcefile – The Puppet manifest this resource is declared in.

  • sourceline – The line this resource is declared at.

  • parameters – dict with key:value pairs of parameters.

  • relationships – list Contains all relationships to other resources

  • environment – string The environment of the node associated with this resource.

class pypuppetdb.types.Event(node, status, timestamp, hash_, title, property_, message, new_value, old_value, type_, class_, execution_path, source_file, line_number)[source]

This object represents an event. Unless otherwise specified all parameters are required.

Parameters:

  • node (string) – The hostname of the node this event fired on.

  • status (string) – The status for the event.

  • timestamp (string formatted as %Y-%m-%dT%H:%M:%S.%fZ) – A timestamp of when this event occured.

  • hash (string) – The hash of the report that contains this event.

  • title (string) – The resource title this event was fired for.

  • property (string) – The property of the resource this event was fired for.

  • message (string) – A message associated with this event.

  • new_value (string) – The new value/state of the resource.

  • old_value (string) – The old value/state of the resource.

  • type (string) – The type of the resource this event fired for.

  • class (string) – The class responsible for running this event.

  • execution_path (string) – The path used to reach this particular resource.

  • source_file (string) – The puppet source code file containing the class.

  • line_number (int) – The line number in the source file containing the definition responsible for triggering this event.

Variables:

  • node – A string of this event’s node certname.

  • status – A string of this event’s status.

  • failed – The bool equivalent of status.

  • timestamp – A datetime.datetime of when this event happend.

  • node – The hostname of the machine this event occured on.

  • hash – The hash of this event.

  • item – dict with information about the item/resource this event was triggered for.

class pypuppetdb.types.Report(api, node, hash_, start, end, received, version, format_, agent_version, transaction, status=None, metrics={}, logs={}, environment=None, noop=False, noop_pending=False, code_id=None, catalog_uuid=None, cached_catalog_status=None, producer=None)[source]

This object represents a report. Unless otherwise specified all parameters are required.

Parameters:

  • api (pypuppetdb.api.BaseAPI) – API object

  • node (string) – The hostname of the node this report originated on.

  • hash (string) – A string uniquely identifying this report.

  • start (string formatted as %Y-%m-%dT%H:%M:%S.%fZ) – The start time of the agent run.

  • end (string formatted as %Y-%m-%dT%H:%M:%S.%fZ) – The time the agent finished its run.

  • received (string formatted as %Y-%m-%dT%H:%M:%S.%fZ) – The time PuppetDB received the report.

  • version (string) – The catalog / configuration version.

  • format (int) – The catalog format version.

  • agent_version (string) – The Puppet agent version.

  • transaction (string) – The UUID of this transaction.

  • environment (string) – (Optional) The environment assigned to the node that submitted this report.

  • status (string) – (Optional) The status associated to this report’s node.

  • noop (bool) – (Default False) A flag indicating weather the report was produced by a noop run.

  • noop_pending (bool) – (Default False) A flag indicating weather the report had pending changes produced by a noop run.

  • metrics (list containing dict with Metrics) – (Optional) All metrics associated with this report.

  • logs (list containing dict of logs) – (Optional) All logs associated with this report.

  • code_id (string) – (Optional) Ties the catalog to the Puppet Code that generated the catalog.

  • catalog_uuid (string) – (Optional) Ties the report to the catalog used from that Puppet run.

  • cached_catalog_status (string) – (Optional) Identifies if the Puppet run used a cached catalog and weather or not it was used due to an error. Can be one of ‘explicitly_requested’, ‘on_failure’, ‘not_used’ not ‘null’.

  • producer (string) – (Optional) The certname of the Puppet Server that sent the report to PuppetDB

Variables:

  • node – The hostname this report originated from.

  • hash – Unique identifier of this report.

  • start – datetime.datetime when the Puppet agent run started.

  • end – datetime.datetime when the Puppet agent run ended.

  • received – datetime.datetime when the report finished uploading.

  • version – string catalog configuration version.

  • format – int catalog format version.

  • agent_version – string Puppet Agent version.

  • run_time – datetime.timedelta of end - start.

  • transaction – UUID identifying this transaction.

  • environment – The environment assigned to the node that submitted this report.

  • status – The status associated to this report’s node.

  • metrics – list containing dict of all metrics associated with this report.

  • logs – list containing dict of all logs associated with this report.

  • code_id – string used to tie a catalog to the Puppet Code which generated the catalog.

  • catalog_uuid – string used to tie this report to the catalog used on this Puppet run.

  • cached_catalog_status – string identifying if this Puppet run used a cached catalog, if so weather it was a result of an error or otherwise.

  • producer – string representing the certname of the Puppet Server that sent the report to PuppetDB

events(**kwargs)[source]

Get all events for this report. Additional arguments may also be specified that will be passed to the query function.

class pypuppetdb.types.Catalog(node, edges, resources, version, transaction_uuid, environment=None, code_id=None, catalog_uuid=None, producer=None)[source]

This object represents a compiled catalog from puppet. It contains Resource and Edge object that represent the dependency graph. Unless otherwise specified all parameters are required.

Parameters:

  • node (string) – Name of the host

  • edges (list containing dict of pypuppetdb.types.Edge) – Edges returned from Catalog data

  • resources (dict of pypuppetdb.types.Resource) – pypuppetdb.types.Resource managed as of this Catalog.

  • version (string) – Catalog version from Puppet (unique for each node)

  • transaction_uuid (string) – A string used to match the catalog with the corresponding report that was issued during the same puppet run

  • environment (string) – The environment associated with the catalog’s certname.

  • code_id (string) – The string used to tie this catalog to the Puppet code which generated the catalog.

  • catalog_uuid (string) – Universally unique identifier of this catalog.

  • producer (string) – The certname of the Puppet Server that sent the catalog to PuppetDB

Variables:

  • node – string Name of the host

  • version – string Catalog version from Puppet (unique for each node)

  • transaction_uuid – string used to match the catalog with corresponding report

  • edges – list of Edge The source Resource object of the relationship

  • environment – string Environment associated with the catalog’s certname

  • code_id – string ties the catalog to the Puppet code that generated the catalog

  • catalog_uuid – string uniquely identifying this catalog.

  • producer – string of the Puppet Server that sent the catalog to PuppetDB

class pypuppetdb.types.Edge(source, target, relationship, node=None)[source]

This object represents the connection between two Resource objects. Unless otherwise specified all parameters are required.

Parameters:

  • source (pypuppetdb.Resource) – The source Resource object of the relationship

  • target (pypuppetdb.Resource) – The target Resource object of the relationship

  • relationship (string) – Name of the Puppet Resource Relationship

  • node (string) – The certname of the node that owns this Relationship

Variables:

  • source – Resource The source Resource object

  • target – Resource The target Resource object

  • relationship – string Name of the Puppet Resource relationship

  • node – string The name of the node that owns this relationship

class pypuppetdb.types.Inventory(node, time, environment, facts, trusted)[source]

This object represents a Node Inventory entry returned from the Inventory endpoint.

Parameters:

  • node (string) – The certname of the node associated with the inventory.

  • time (string formatted as %Y-%m-%dT%H:%M:%S.%fZ) – The time at which PuppetDB received the facts in the inventory.

  • environment (string) – The environment associated with the inventory’s certname.

  • facts (dict) – The dictionary of key-value pairs for the nodes assosciated facts.

  • trusted (dict) – The trusted data from the node.

Variables:

  • node – The certname of the node associated with the inventory.

  • time – The time at which PuppetDB received the facts in the inventory.

  • environment – The environment associated with the inventory’s certname.

  • facts – The dictionary of key-value pairs for the nodes assosciated facts.

  • trusted – The trusted data from the node.

Errors

Unfortunately things can go haywire. PuppetDB might not be reachable or complain about our query, requests might have to wait too long to receive a response or the body is just too big to handle.

In that case, we’ll throw an exception at you.

exception pypuppetdb.errors.APIError[source]

Our base exception the other errors inherit from.

exception pypuppetdb.errors.ImproperlyConfiguredError[source]

Bases: APIError

This exception is thrown when the API is initialised and it detects incompatible configuration such as SSL turned on but no certificates provided.

exception pypuppetdb.errors.DoesNotComputeError[source]

Bases: APIError

This error will be thrown when a function is called with an incompatible set of optional parameters. This is the ‘you are being a naughty developer, go read the docs’ error.

exception pypuppetdb.errors.EmptyResponseError[source]

Bases: APIError

Will be thrown when we did receive a response but the response is empty.

Query Builder

With the increasing complexities of some queries it can be very difficult to maintain query strings as string objects. The 0.3.0 release introduces a new feature called the Query Builder which removes the need of string object concatenation into an Object-Oriented fashion.

In order to create the following query:

'["and", ["=", "facts_environment", "production"], ["=", "catalog_environment", "production"]]'

Users can use the following code block to create the same thing:

>>> from pypuppetdb.QueryBuilder import *
>>> op = AndOperator()
>>> op.add(EqualOperator("facts_environment", "production"))
>>> op.add(EqualOperator("catalog_environment", "production"))

The op object can then be directly input to the query parameter of any PuppetDB call.

>>> pypuppetdb.nodes(query=op)
class pypuppetdb.QueryBuilder.BinaryOperator(operator, field, value)[source]

This is a parent helper class used to create PuppetDB AST queries for single key-value pairs for the available operators.

It is possible to directly declare the various types of queries from this class. For instance the code BinaryOperator(‘=’, ‘certname’, ‘node1.example.com’) generates the PuppetDB query ‘[“=”, “certname”, “node1.example.com”]’. It is preferred to use the child classes as they may have restrictions specific to that operator.

See https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#binary-operators for more information.

Parameters:

  • operator (string) – The binary query operation performed. There is no value checking on this field.

  • field (any) – The PuppetDB endpoint query field. See endpoint documentation for valid values.

  • value (any) – The values of the field to match, or not match.

class pypuppetdb.QueryBuilder.EqualsOperator(field, value)[source]

Builds an equality filter based on the supplied field-value pair as described https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#equality.

In order to create the following query:

[“=”, “environment”, “production”]

The following code can be used.

EqualsOperator(‘environment’, ‘production’)

Parameters:

  • field (any) – The PuppetDB endpoint query field. See endpoint documentation for valid values.

  • value (any) – The value of the field to match, or not match.

class pypuppetdb.QueryBuilder.GreaterOperator(field, value)[source]

Builds a greater-than filter based on the supplied field-value pair as described https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#greater-than.

In order to create the following query:

[“>”, “catalog_timestamp”, “2016-06-01 00:00:00”]

The following code can be used.

GreaterOperator(‘catalog_timestamp’, datetime.datetime(2016, 06, 01))

Parameters:

  • field (any) – The PuppetDB endpoint query field. See endpoint documentation for valid values.

  • value (Number, timestamp or array) – Matches if the field is greater than this value.

class pypuppetdb.QueryBuilder.LessOperator(field, value)[source]

Builds a less-than filter based on the supplied field-value pair as described https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#less-than.

In order to create the following query:

[“<”, “catalog_timestamp”, “2016-06-01 00:00:00”]

The following code can be used.

LessOperator(‘catalog_timestamp’, datetime.datetime(2016, 06, 01))

Parameters:

  • field (any) – The PuppetDB endpoint query field. See endpoint documentation for valid values.

  • value (Number, timestamp or array) – Matches if the field is less than this value.

class pypuppetdb.QueryBuilder.GreaterEqualOperator(field, value)[source]

Builds a greater-than or equal-to filter based on the supplied field-value pair as described https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#greater-than-or-equal-to.

In order to create the following query:

[“>=”, “facts_timestamp”, “2016-06-01 00:00:00”]

The following code can be used.

GreaterEqualOperator(‘facts_timestamp’, datetime.datetime(2016, 06, 01))

Parameters:

  • field (any) – The PuppetDB endpoint query field. See endpoint documentation for valid values.

  • value (Number, timestamp or array) – Matches if the field is greater than or equal to this value.

class pypuppetdb.QueryBuilder.LessEqualOperator(field, value)[source]

Builds a less-than or equal-to filter based on the supplied field-value pair as described https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#less-than-or-equal-to.

In order to create the following query:

[“<=”, “facts_timestamp”, “2016-06-01 00:00:00”]

The following code can be used.

LessEqualOperator(‘facts_timestamp’, datetime.datetime(2016, 06, 01))

Parameters:

  • field (any) – The PuppetDB endpoint query field. See endpoint documentation for valid values.

  • value (Number, timestamp or array) – Matches if the field is less than or equal to this value.

class pypuppetdb.QueryBuilder.RegexOperator(field, value)[source]

Builds a regular expression filter based on the supplied field-value pair as described https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#regexp-match.

In order to create the following query:

[“~”, “certname”, “wwwd+.example.com”]

The following code can be used.

RegexOperator(‘certname’, ‘wwwd+.example.com’)

Parameters:

  • field (any) – The PuppetDB endpoint query field. See endpoint documentation for valid values.

  • value (string) – Matches if the field matches this regular expression.

class pypuppetdb.QueryBuilder.RegexArrayOperator(field, value)[source]

Builds a regular expression array filter based on the supplied field-value pair. This query only works on fields with paths as described https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#regexp-array-match.

In order to create the following query:

[“~”, “path”, [“networking”, “eth.*”, “macaddress”]]

The following code can be used.

RegexArrayOperator(‘path’, [“networking”, “eth.*”, “macaddress”])

Parameters:

  • field (any) – The PuppetDB endpoint query field. See endpoint documentation for valid values.

  • value (list) – Matches if the field matches this regular expression.

class pypuppetdb.QueryBuilder.NullOperator(field, value)[source]

Builds a null filter based on the field and boolean value pair as described https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#null-is-null. This filter only works on field that may be null. Value may only be True or False.

In order to create the following query:

[“null?”, “deactivated”, true]

The following code can be used.

NullOperator(‘deactivated’, True)

Parameters:

  • field (any) – The PuppetDB endpoint query field. See endpoint documentation for valid values.

  • value (bool) – Matches if the field value is null (if True) or not null (if False)

class pypuppetdb.QueryBuilder.BooleanOperator(operator)[source]

This is a parent helper class used to create PuppetDB AST queries for available boolean queries.

It is possible to directly declare a boolean query from this class. For instance the code BooleanOperator(“and”) will create an empty query ‘[“and”,]’. An error will be raised if there are no queries added via add()

See https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#binary-operators for more information.

Parameters:

operator (string) – The boolean query operation to perform.

class pypuppetdb.QueryBuilder.AndOperator[source]

Builds an AND boolean filter. Only results that match ALL criteria from the included query strings will be returned from PuppetDB. Full documentation is available https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#and

In order to create the following query:

[“and”,

[“=”, “catalog_environment”, “production”], [“=”, “facts_environment”, “production”]]

The following code can be used:

op = AndOperator() op.add(EqualsOperator(“catalog_environment”, “production”)) op.add(EqualsOperator(“facts_environment”, “production”))

class pypuppetdb.QueryBuilder.OrOperator[source]

Builds an OR boolean filter. Only results that match ANY criteria from the included query strings will be returned from PuppetDB. Full documentation is available https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#or.

In order to create the following query:

[“or”, [“=”, “name”, “hostname”], [“=”, “name”, “architecture”]]

The following code can be used:

op = OrOperator() op.add(EqualsOperator(“name”, “hostname”)) op.add(EqualsOperator(“name”, “architecture”))

class pypuppetdb.QueryBuilder.NotOperator[source]

Builds a NOT boolean filter. Only results that DO NOT match criteria from the included query strings will be returned from PuppetDB. Full documentation is available https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#not

Unlike the other Boolean Operator objects this operator only accepts a single query string.

In order to create the following query:

[“not”, [“=”, “osfamily”, “RedHat”]]

The following code can be used.

op = NotOperator() op.add(EqualsOperator(“osfamily”, “RedHat”))

class pypuppetdb.QueryBuilder.ExtractOperator[source]

Queries that either do not or cannot require all the key-value pairs from an endpoint can use the Extract Operator as described in https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#projection-operators.

The syntax of this operator requires a function and/or a list of fields, an optional standard query and an optional group by clause including a list of fields.

class pypuppetdb.QueryBuilder.FunctionOperator(function, field=None, fmt=None)[source]

Performs an aggregate function on the result of a subquery, full documentation is available at https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#function. This object can only be used in the field list or group by list of an ExtractOperator object.

Parameters:

  • function (str) – The name of the function to perform.

  • field (str) – The name of the field to perform the function on. All functions with the exception of count require this value.

class pypuppetdb.QueryBuilder.SubqueryOperator(endpoint)[source]

Performs a subquery to another puppetDB object, full documentation is available at https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#subquery-operators This object must be used in combination with the InOperator according to documentation.

Parameters:

endpoint – The name of the subquery object

class pypuppetdb.QueryBuilder.InOperator(field)[source]

Performs boolean compare between a field a subquery result https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#subquery-operators This object must be used in combination with the SubqueryOperator according to documentation.

Parameters:

field – The name of the subquery object

class pypuppetdb.QueryBuilder.FromOperator(endpoint)[source]

From contextual operator that allows for queries on the root endpoint or subqueries into other entities: https://puppet.com/docs/puppetdb/7/api/query/v4/ast.html#from

Ex.) fr = FromOperator(“facts”) fr.add_query(EqualsOperator(“foo”, “bar”)) fr.add_order_by([“certname”]) fr.add_limit(10)

note: only supports single entity From operations

Utilities

A few functions that are used across this library have been put into their own utils module.

class pypuppetdb.utils.UTC[source]
pypuppetdb.utils.json_to_datetime(date)[source]

Tranforms a JSON datetime string into a timezone aware datetime object with a UTC tzinfo object.

Parameters:

date (string) – The datetime representation.

Returns:

A timezone aware datetime object.

Return type:

datetime.datetime