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.
Main Interface
What you’ll usually need to do is use the connect() method to set up a
connection with PuppetDB and indicate which version of the API you want to
talk. Additionally it allows you to enable or disable the experimental
features.
-
pypuppetdb.connect(api_version=3, host=u'localhost', port=8080, ssl=False, ssl_key=None, ssl_cert=None, timeout=10)[source]
Connect with PuppetDB. This will return an object allowing you
to query the API through its methods.
Parameters: |
- api_version (int) – Version of the API we’re initialising.
- host (string) – (optional) Hostname or IP of PuppetDB.
- port (int) – (optional) Port on which to talk to PuppetDB.
- ssl (bool) – (optional) Talk with PuppetDB over SSL.
- 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) – (optional) Number of seconds to wait for a response.
|
Raises : | UnsupportedVersionError
|
API objects
The PuppetDB API is versioned. We currently have a v1, v2 and v3.
In order to work with this structure PyPuppetDB consists of a BaseAPI class that factors out identical code between different versions.
Every version of the API has its own class which inherits from our
BaseAPI.
-
pypuppetdb.API_VERSIONS
dict of int:string pairs representing the API version
and it’s URL prefix.
We currently only handle API version 2 though it should be fairly easy to
support version 1 should we want to.
BaseAPI
-
class pypuppetdb.api.BaseAPI(api_version, host=u'localhost', port=8080, ssl=False, ssl_key=None, ssl_cert=None, timeout=10)[source]
This is a Base or Abstract class and is not meant to be instantiated
or used directly.
The BaseAPI object defines a set of methods that can be
reused across different versions of the PuppetDB API. If querying for a
certain resource is done in an identical fashion across different versions
it will be implemented here and should be overridden in their respective
versions if they deviate.
If ssl is set to True but either ssl_key or ssl_cert are None this will raise an error.
When at initialisation api_version isn’t found in API_VERSIONS this will raise an error.
Parameters: |
- api_version (int) – Version of the API we’re initialising.
- host (string) – (optional) Hostname or IP of PuppetDB.
- port (int) – (optional) Port on which to talk to PuppetDB.
- ssl (bool) – (optional) Talk with PuppetDB over SSL.
- 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) – (optional) Number of seconds to wait for a response.
|
Raises : | ImproperlyConfiguredError
|
Raises : | UnsupportedVersionError
|
-
_query(endpoint, path=None, query=None, limit=None, offset=None)[source]
This method actually querries PuppetDB. Provided an endpoint and an
optional path and/or query 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: |
- endpoint (string) – The PuppetDB API endpoint we want to query.
- path (string) – An additional path if we don’t wish to query the bare endpoint.
- query (string) – (optional) A query to further narrow down the resultset.
- limit (int) – (optional) Tell PuppetDB to limit it’s response to this number of objects.
- offset (string) – (optional) Tell PuppetDB to start it’s response from the given offset. This is useful for implementing pagination but is not supported just yet.
|
Raises : | EmptyResponseError
|
Returns: | The decoded response from PuppetDB
|
Return type: | dict or list
|
-
_url(endpoint, path=None)[source]
The complete URL we will end up querying. Depending on the
endpoint we pass in this will result in different URL’s with
different prefixes.
Parameters: |
- endpoint (string) – The PuppetDB API endpoint we want to query.
- path (string) – An additional path if we don’t wish to query the bare endpoint.
|
Returns: | A URL constructed from base_url() with the apropraite API version/prefix and the rest of the path added to it.
|
Return type: | string
|
-
base_url[source]
A base_url that will be used to construct the final
URL we’re going to query against.
Returns: | A URL of the form: proto://host:port. |
Return type: | string |
-
metric(metric)[source]
Query for a specific metrc.
Parameters: | metric (string) – The name of the metric we want. |
Returns: | The return of _query(). |
-
version[source]
The version of the API we’re querying against.
Returns: | Current API version. |
Return type: | string |
v2.API
-
class pypuppetdb.api.v2.API(*args, **kwargs)[source]
Bases: pypuppetdb.api.BaseAPI
The API object for version 2 of the PuppetDB API. This object contains
all v2 specific methods and ways of doing things.
Parameters: | **kwargs – Rest of the keywoard arguments passed on to our parent BaseAPI. |
-
_query(endpoint, path=None, query=None, limit=None, offset=None)
This method actually querries PuppetDB. Provided an endpoint and an
optional path and/or query 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: |
- endpoint (string) – The PuppetDB API endpoint we want to query.
- path (string) – An additional path if we don’t wish to query the bare endpoint.
- query (string) – (optional) A query to further narrow down the resultset.
- limit (int) – (optional) Tell PuppetDB to limit it’s response to this number of objects.
- offset (string) – (optional) Tell PuppetDB to start it’s response from the given offset. This is useful for implementing pagination but is not supported just yet.
|
Raises : | EmptyResponseError
|
Returns: | The decoded response from PuppetDB
|
Return type: | dict or list
|
-
_url(endpoint, path=None)
The complete URL we will end up querying. Depending on the
endpoint we pass in this will result in different URL’s with
different prefixes.
Parameters: |
- endpoint (string) – The PuppetDB API endpoint we want to query.
- path (string) – An additional path if we don’t wish to query the bare endpoint.
|
Returns: | A URL constructed from base_url() with the apropraite API version/prefix and the rest of the path added to it.
|
Return type: | string
|
-
base_url
A base_url that will be used to construct the final
URL we’re going to query against.
Returns: | A URL of the form: proto://host:port. |
Return type: | string |
-
fact_names()[source]
Get a list of all known facts.
-
facts(name=None, value=None, query=None)[source]
Query for facts limited by either name, value and/or query.
This will yield a single Fact object at a time.
-
metric(metric)
Query for a specific metrc.
Parameters: | metric (string) – The name of the metric we want. |
Returns: | The return of _query(). |
-
node(name)[source]
Gets a single node from PuppetDB.
-
nodes(name=None, query=None)[source]
Query for nodes by either name or query. If both aren’t
provided this will return a list of all nodes.
Parameters: |
- name (None or string) – (optional)
- query (None or string) – (optional)
|
Returns: | A generator yieling Nodes.
|
Return type: | pypuppetdb.types.Node
|
-
resources(type_=None, title=None, query=None)[source]
Query for resources limited by either type and/or title or query.
This will yield a Resources object for every returned resource.
-
version
The version of the API we’re querying against.
Returns: | Current API version. |
Return type: | string |
v3.API
-
class pypuppetdb.api.v3.API(*args, **kwargs)[source]
Bases: pypuppetdb.api.BaseAPI
The API object for version 3 of the PuppetDB API. This object contains
all v3 specific methods and ways of doing things.
Parameters: | **kwargs – Rest of the keywoard arguments passed on to our parent BaseAPI. |
-
_query(endpoint, path=None, query=None, limit=None, offset=None)
This method actually querries PuppetDB. Provided an endpoint and an
optional path and/or query 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: |
- endpoint (string) – The PuppetDB API endpoint we want to query.
- path (string) – An additional path if we don’t wish to query the bare endpoint.
- query (string) – (optional) A query to further narrow down the resultset.
- limit (int) – (optional) Tell PuppetDB to limit it’s response to this number of objects.
- offset (string) – (optional) Tell PuppetDB to start it’s response from the given offset. This is useful for implementing pagination but is not supported just yet.
|
Raises : | EmptyResponseError
|
Returns: | The decoded response from PuppetDB
|
Return type: | dict or list
|
-
_url(endpoint, path=None)
The complete URL we will end up querying. Depending on the
endpoint we pass in this will result in different URL’s with
different prefixes.
Parameters: |
- endpoint (string) – The PuppetDB API endpoint we want to query.
- path (string) – An additional path if we don’t wish to query the bare endpoint.
|
Returns: | A URL constructed from base_url() with the apropraite API version/prefix and the rest of the path added to it.
|
Return type: | string
|
-
base_url
A base_url that will be used to construct the final
URL we’re going to query against.
Returns: | A URL of the form: proto://host:port. |
Return type: | string |
-
events(query)[source]
A report is made up of events. This allows to query for events
based on the reprt hash.
This yields an Event object for every returned event.
-
fact_names()[source]
Get a list of all known facts.
-
facts(name=None, value=None, query=None)[source]
Query for facts limited by either name, value and/or query.
This will yield a single Fact object at a time.
-
metric(metric)
Query for a specific metrc.
Parameters: | metric (string) – The name of the metric we want. |
Returns: | The return of _query(). |
-
node(name)[source]
Gets a single node from PuppetDB.
-
nodes(name=None, query=None)[source]
Query for nodes by either name or query. If both aren’t
provided this will return a list of all nodes.
Parameters: |
- name (None or string) – (optional)
- query (None or string) – (optional)
|
Returns: | A generator yieling Nodes.
|
Return type: | pypuppetdb.types.Node
|
-
reports(query)[source]
Get reports for our infrastructure. Currently reports can only
be filtered through a query which requests a specific certname.
If not it will return all reports.
This yields a Report object for every returned report.
-
resources(type_=None, title=None, query=None)[source]
Query for resources limited by either type and/or title or query.
This will yield a Resources object for every returned resource.
-
version
The version of the API we’re querying against.
Returns: | Current API version. |
Return type: | string |
Errors
Unfortunately things can go haywire. PuppetDB might not be reachable
or complain about our query, requests might have to wait too long to
recieve 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: pypuppetdb.errors.APIError
This exception is thrown when the API is initialised
and it detects incompatbile configuration such as SSL turned
on but no certificates provided.
-
exception pypuppetdb.errors.UnsupportedVersionError[source]
Bases: pypuppetdb.errors.APIError
Triggers when using the connect() function and
providing it with an unknown API version.
-
exception pypuppetdb.errors.DoesNotComputeError[source]
Bases: pypuppetdb.errors.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: pypuppetdb.errors.APIError
Will be thrown when we did recieve a response but the
response is empty.