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. .. autofunction:: connect
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.
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.
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. .. autofunction:: connect
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.
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.
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: |
|
---|---|
Raises: | |
Raises: |
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: |
|
---|---|
Raises: | |
Returns: | The decoded response from PuppetDB |
Return type: | dict or list |
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: |
|
---|---|
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 |
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 |
Query for a specific metrc.
Parameters: | metric (string) – The name of the metric we want. |
---|---|
Returns: | The return of _query(). |
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. |
---|
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: |
|
---|---|
Raises: | |
Returns: | The decoded response from PuppetDB |
Return type: | dict or list |
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: |
|
---|---|
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 |
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 |
Query for facts limited by either name, value and/or query. This will yield a single Fact object at a time.
Query for a specific metrc.
Parameters: | metric (string) – The name of the metric we want. |
---|---|
Returns: | The return of _query(). |
Query for nodes by either name or query. If both aren’t provided this will return a list of all nodes.
Parameters: |
|
---|---|
Returns: | A generator yieling Nodes. |
Return type: |
Query for resources limited by either type and/or title or query. This will yield a Resources object for every returned resource.
The total-count of the last request to PuppetDB if enabled as parameter in _query method
:returns Number of total results :rtype int
The version of the API we’re querying against.
Returns: | Current API version. |
---|---|
Return type: | string |
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. |
---|
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: |
|
---|---|
Raises: | |
Returns: | The decoded response from PuppetDB |
Return type: | dict or list |
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: |
|
---|---|
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 |
Get event counts from puppetdb
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 |
Get event counts from puppetdb
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.
Query for facts limited by either name, value and/or query. This will yield a single Fact object at a time.
Query for a specific metrc.
Parameters: | metric (string) – The name of the metric we want. |
---|---|
Returns: | The return of _query(). |
Query for nodes by either name or query. If both aren’t provided this will return a list of all nodes. This method also fetches the nodes status and event counts of the latest report from puppetdb.
Parameters: |
|
---|---|
Returns: | A generator yieling Nodes. |
Return type: |
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.
Query for resources limited by either type and/or title or query. This will yield a Resources object for every returned resource.
The total-count of the last request to PuppetDB if enabled as parameter in _query method
:returns Number of total results :rtype int
The version of the API we’re querying against.
Returns: | Current API version. |
---|---|
Return type: | string |
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.
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.
Parameters: |
|
---|---|
Variables: |
|
his object represents a fact.
Parameters: |
|
---|---|
Variables: |
|
This object represents a resource.
Parameters: |
|
---|---|
Variables: |
|
This object represents an event.
Parameters: |
|
---|---|
Variables: |
|
This object represents a report.
Parameters: |
|
---|---|
Variables: |
|
This object represents a compiled catalog from puppet. It contains Resource and Edge object that represent the dependency graph.
Parameters: |
|
---|---|
Variables: |
|
This object represents the connection between two Resource objects
Parameters: |
|
---|---|
Variables: |
|
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.
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.
Bases: pypuppetdb.errors.APIError
Triggers when using the connect() function and providing it with an unknown API version.
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.
Bases: pypuppetdb.errors.APIError
Will be thrown when we did recieve a response but the response is empty.
A few functions that are used across this library have been put into their own utils module.