pypuppetdb

https://pypuppetdb.readthedocs.io/en/latest/
Admin
pypuppetdb is a Python wrapper around the PuppetDB REST API providing convenience functions and...
Tokens:43,031
Snippets:364
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### environments

Source: https://pypuppetdb.readthedocs.io/en/latest/developer.html

Get all known environments from PuppetDB.

```APIDOC
## environments

### Description
Get all known environments from Puppetdb.

### Parameters
#### Path Parameters
None

#### Query 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`
```

--------------------------------

### Get Resources by Type

Source: https://pypuppetdb.readthedocs.io/en/latest/basics.html

Retrieves all resources of a specified type across the infrastructure. Be cautious with large infrastructures as this can return a huge amount of data.

```python
>>> resources = db.resources('file')
```

--------------------------------

### AST Query for Node Certnames

Source: https://pypuppetdb.readthedocs.io/en/latest/advanced_queries.html

Use the AST query language by passing a query string to methods like `nodes()`. This example demonstrates an AST query equivalent to the PQL query for nodes with the 'operatingsystem' fact set to 'Debian'.

```python
>>> nodes = db.nodes(query="""
["subquery", "facts",
  ["and",
    ["=", "name", "operatingsystem"],
    ["=", "value", "Debian"]
  ]
]
""")
>>> for node in nodes:
>>>     print(node.name)
foo.example.com
bar.example.com


```

--------------------------------

### Get Catalog for Host

Source: https://pypuppetdb.readthedocs.io/en/latest/basics.html

Retrieves the latest catalog for a specified host. The catalog contains all defined Resources and Edges for that host.

```python
>>> catalog = db.catalog('hostname')
>>> for res in catalog.get_resources():
>>>     print(res)
```

--------------------------------

### Get PuppetDB Server Version

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/metadata.html

Retrieves version information about the running PuppetDB server. Returns a string representation of the version.

```python
import logging

from pypuppetdb.api.base import BaseAPI

log = logging.getLogger(__name__)



[docs]class MetadataAPI(BaseAPI):
    """This class provides methods that interact with the `pdb/meta/*`
    PuppetDB API endpoints.
    """


    [docs]    def server_time(self):
        """Get the current time of the clock on the PuppetDB server.
        :returns: An ISO-8091 formatting timestamp.
        :rtype: :obj:`string`
        """
        return self._query("server-time")[self.parameters["server_time"]]



    [docs]    def current_version(self):
        """Get version information about the running PuppetDB server.

        :returns: A string representation of the PuppetDB version.
        :rtype: :obj:`string`
        """
        return self._query("version")["version"]
```

--------------------------------

### PQL Query for Raw Dictionaries

Source: https://pypuppetdb.readthedocs.io/en/latest/advanced_queries.html

When using projections (fields/functions) in a PQL query or querying unsupported types, the result will be a list of dictionaries, similar to direct PuppetDB JSON responses. This example retrieves only certnames.

```python
>>> nodes = db.pql("""
nodes[certname] {
  facts {
    name = "operatingsystem"
    and value = "Debian"
  }
}
""")
>>> for node in nodes:
>>>     print(node)
{'certname': 'foo.example.com'}
{'certname': 'bar.example.com'}


```

--------------------------------

### Get Resource Relationships

Source: https://pypuppetdb.readthedocs.io/en/latest/basics.html

Retrieves all relationships for a specific resource within a host's catalog. This lists linked resources and the relationship type.

```python
>>> catalog = db.catalog('hostname')
>>> resource = catalog.get_resource('Service', 'ntp')
>>> for rel in resource.relationships:
>>>     print(rel)
Class[Ntp] - contains - Service[ntp]
File[/etc/ntp.conf] - notifies - Service[ntp]
File[/etc/ntp.conf] - required-by - Service[ntp]
```

--------------------------------

### Get Single Node

Source: https://pypuppetdb.readthedocs.io/en/latest/basics.html

Retrieves a specific node by its hostname. Use this for direct access to a single node's information.

```python
>>> node = db.node('hostname')
>>> print(node)
hostname
```

--------------------------------

### inventory

Source: https://pypuppetdb.readthedocs.io/en/latest/developer.html

Get Node and Fact information with an alternative query syntax for structured facts. This method returns a generator yielding Inventory.

```APIDOC
## inventory

### Description
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.

### Returns
A generator yielding Inventory.

### Return Type
pypuppetdb.types.Inventory
```

--------------------------------

### catalogs

Source: https://pypuppetdb.readthedocs.io/en/latest/developer.html

Get catalog information from the infrastructure based on path and/or query results. It is recommended to include query and/or paging parameters to prevent large result sets.

```APIDOC
## catalogs

### Description
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
#### Path Parameters
None

#### Query Parameters
* **kwargs** - The rest of the keyword arguments are passed to the _query function.

### Returns
A generator yielding Catalogs.

### Return Type
`pypuppetdb.types.Catalog`
```

--------------------------------

### reports

Source: https://pypuppetdb.readthedocs.io/en/latest/developer.html

Get reports for your infrastructure. It is strongly recommended to include query and/or paging parameters for this endpoint to prevent large result sets. This method returns a generator yielding Reports.

```APIDOC
## reports

### Description
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.

### Returns
A generating yielding Reports.

### Return Type
pypuppetdb.types.Report
```

--------------------------------

### Using the Query Builder

Source: https://pypuppetdb.readthedocs.io/en/latest/developer.html

Demonstrates how to use the Query Builder to construct a query and pass it to the `pypuppetdb.nodes` function.

```APIDOC
## Using the Query Builder

This example shows how to construct a query using the Query Builder and then use it with the `pypuppetdb.nodes` function.

### Code Example

```python
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)
```

### Explanation

The code first imports necessary components from `pypuppetdb.QueryBuilder`. An `AndOperator` is initialized, and then two `EqualOperator` instances are added to it. Finally, the constructed query object `op` is passed to the `query` parameter of the `pypuppetdb.nodes` function.
```

--------------------------------

### fact_names

Source: https://pypuppetdb.readthedocs.io/en/latest/developer.html

Get a list of all known facts available in PuppetDB.

```APIDOC
## fact_names

### Description
Get a list of all known facts.

### Parameters
None

### Returns
A list of dictionaries containing the results.

### Return Type
`list` of `dict`
```

--------------------------------

### Catalog Class Initialization

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/types.html

This code defines the constructor for the Catalog class, which represents a compiled catalog from Puppet. It initializes attributes like node name, version, transaction UUID, and environment.

```python
def __init__(
        self,
        node,
        edges,
        resources,
        version,
        transaction_uuid,
        environment=None,
        code_id=None,
        catalog_uuid=None,
        producer=None,
    ):
        self.node = node
        self.version = version
```

--------------------------------

### node

Source: https://pypuppetdb.readthedocs.io/en/latest/developer.html

Gets a single node from PuppetDB. This method returns an instance of Node.

```APIDOC
## node

### Description
Gets a single node from PuppetDB.

### Parameters
#### Path Parameters
- **name** (string) - The name of the node search.

### Returns
An instance of Node.

### Return Type
pypuppetdb.types.Node
```

--------------------------------

### event_counts

Source: https://pypuppetdb.readthedocs.io/en/latest/developer.html

Get event counts from PuppetDB. This method allows for summarizing events and filtering the results.

```APIDOC
## event_counts

### Description
Get event counts from puppetdb.

### Parameters
#### Path Parameters
None

#### Query 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`
```

--------------------------------

### Connect to PuppetDB from the Same Host

Source: https://pypuppetdb.readthedocs.io/en/latest/connecting.html

Use this when running pypuppetdb on the same machine as PuppetDB. It establishes a default connection.

```python
>>> from pypuppetdb import connect
>>> db = connect()
```

--------------------------------

### Get All Nodes

Source: https://pypuppetdb.readthedocs.io/en/latest/basics.html

Retrieves a generator for all nodes from PuppetDB. Use this when you need to iterate over all known nodes.

```python
>>> nodes = db.nodes()
>>> for node in nodes:
>>>   print(node)
host1
host2
...
```

--------------------------------

### Prepare PQL Query for PuppetDB

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/pql.html

Internal method to prepare a PQL query for PuppetDB. It handles basic validation and URL construction. Actual HTTP request is made by _make_request().

```python
def _pql(self, pql, request_method="GET"):
        """This method prepares a PQL query to PuppetDB. Actual making
        the HTTP request is done by _make_request().

        :param pql: PQL query
        :type pql: :obj:`string`

        :param request_method: (optional) GET or POST, the default is GET

        :raises: :class:`~pypuppetdb.errors.EmptyResponseError`

        :returns: The decoded response from PuppetDB
        :rtype: :obj:`dict` or :obj:`list`
        """

        log.debug(f"_pql called with pql={pql}, request_method={request_method}")

        pql = pql.strip()
        if not pql:
            log.error("Non-empty PQL query is required!")
            raise APIError

        payload = {}

        # PQL queries are made to the same endpoint regardless of the queried entities
        url = self._url("pql")
        payload["query"] = pql

        return self._make_request(url, request_method, payload)
```

--------------------------------

### Resource class initialization

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/types.html

Initializes a Resource object with core attributes like node, name, type, tags, exported status, source file, and line number. Environment and parameters are optional.

```python
def __init__(
        self,
        node,
        name,
        type_,
        tags,
        exported,
        sourcefile,
        sourceline,
        environment=None,
        parameters={},
    ):
        self.node = node
        self.name = name
        self.type_ = type_
        self.tags = tags
        self.exported = exported
        self.sourcefile = sourcefile
        self.sourceline = sourceline
        self.parameters = parameters
        self.relationships = []
        self.environment = environment
        self.__string = f"{self.type_}[{self.name}]"
```

--------------------------------

### Inventory Class Initialization

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/types.html

Initializes an Inventory object with node, time, environment, facts, and trusted data. Converts the time string to a datetime object.

```python
def __init__(self, node, time, environment, facts, trusted):
        self.node = node
        self.time = json_to_datetime(time)
        self.environment = environment
        self.facts = facts
        self.trusted = trusted
        self.__string = self.node
```

--------------------------------

### Get PuppetDB Server Time

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/metadata.html

Retrieves the current time from the PuppetDB server. Returns an ISO-8091 formatted timestamp string.

```python
import logging

from pypuppetdb.api.base import BaseAPI

log = logging.getLogger(__name__)



[docs]class MetadataAPI(BaseAPI):
    """This class provides methods that interact with the `pdb/meta/*`
    PuppetDB API endpoints.
    """


    [docs]    def server_time(self):
        """Get the current time of the clock on the PuppetDB server.
        :returns: An ISO-8091 formatting timestamp.
        :rtype: :obj:`string`
        """
        return self._query("server-time")[self.parameters["server_time"]]
```

--------------------------------

### Subquery for Events with Status Noop

Source: https://pypuppetdb.readthedocs.io/en/latest/advanced_queries.html

Demonstrates building a subquery to select events with a 'noop' status, then extracting certnames. Requires importing QueryBuilder components.

```python
>>> from pypuppetdb.QueryBuilder import *
>>> op = InOperator('certname')
>>> ex = ExtractOperator()
>>> ex.add_field(str('certname'))
>>> sub = SubqueryOperator('events')
>>> sub.add_query(EqualsOperator('status', 'noop'))
>>> ex.add_query(sub)
>>> op.add_query(ex)
>>> print(op)
["in","certname",["extract",["certname"],["select_events",["=", "status", "noop"]]]]
```

--------------------------------

### Query Nodes by Environment

Source: https://pypuppetdb.readthedocs.io/en/latest/advanced_queries.html

Builds a query for the Nodes endpoint to find all nodes belonging to the 'production' environment using AND conditions on catalog and facts environments. Requires importing QueryBuilder components.

```python
>>> from pypuppetdb.QueryBuilder import *
>>> op = AndOperator()
>>> op.add(EqualsOperator('catalog_environment', 'production'))
>>> op.add(EqualsOperator('facts_environment', 'production'))
>>> print(op)
["and",["=", "catalog_environment", "production"],["=", "facts_environment", "production"]]
```

--------------------------------

### Get Facts by Name

Source: https://pypuppetdb.readthedocs.io/en/latest/basics.html

Retrieves all nodes that have a specific fact. This yields Fact objects, each containing the node and its value for the queried fact.

```python
>>> facts = db.facts('osfamily')
>>> for fact in facts:
>>>   print(f"{fact.node} - {fact.value}")
host1 - RedHat
host2 - Debian
```

--------------------------------

### Node Object Initialization

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/types.html

This code constructs a Node object from a dictionary of node data. It processes report status, event counts, and report timestamps to determine node status and reporting age.

```python
return Node(
            query_api,
            name=node["certname"],
            deactivated=node["deactivated"],
            expired=node["expired"],
            report_timestamp=node["report_timestamp"],
            catalog_timestamp=node["catalog_timestamp"],
            facts_timestamp=node["facts_timestamp"],
            status_report=node["status_report"],
            noop=node.get("latest_report_noop"),
            noop_pending=node.get("latest_report_noop_pending"),
            events=node["events"],
            unreported=node.get("unreported"),
            unreported_time=node.get("unreported_time"),
            report_environment=node["report_environment"],
            catalog_environment=node["catalog_environment"],
            facts_environment=node["facts_environment"],
            latest_report_hash=node.get("latest_report_hash"),
            cached_catalog_status=node.get("cached_catalog_status"),
        )
```

--------------------------------

### Get Node Fact

Source: https://pypuppetdb.readthedocs.io/en/latest/basics.html

Retrieves a specific fact for a given node. This method scopes the query to the node, returning only the requested fact.

```python
>>> node = db.node('hostname')
>>> print(node.fact('osfamily').value)
RedHat
```

--------------------------------

### Get PuppetDB Server Status

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/status.html

Use this method to retrieve the current status of the PuppetDB server. It queries the 'status' endpoint of the API.

```python
import logging

from pypuppetdb.api.base import BaseAPI

log = logging.getLogger(__name__)



class StatusAPI(BaseAPI):
    """This class provides methods that interact with the `status/*`
    PuppetDB API endpoints.
    """


    def status(self):
        """Get PuppetDB server status.

        :returns: A dict with the PuppetDB status information
        :rtype: :obj:`dict`
        """
        return self._query("status")

```

--------------------------------

### Fact class initialization

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/types.html

Initializes a Fact object with node, name, value, and an optional environment. Used internally by the library.

```python
def __init__(self, node, name, value, environment=None):
        self.node = node
        self.name = name
        self.value = value
        self.environment = environment
        self.__string = f"{self.name}/{self.node}"
```

--------------------------------

### aggregate_event_counts

Source: https://pypuppetdb.readthedocs.io/en/latest/developer.html

Get event counts from puppetdb aggregated into a single map. This method allows for summarizing events by various criteria and filtering the results.

```APIDOC
## aggregate_event_counts

### Description
Get event counts from puppetdb aggregated into a single map.

### Parameters
#### Path Parameters
None

#### Query 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`
```

--------------------------------

### Query All Environments

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/query.html

Fetches a list of all known environments from PuppetDB. This method returns a list of dictionaries, each representing an environment.

```python
return self._query("environments", **kwargs)
```

--------------------------------

### Node Class Initialization

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/types.html

Initializes a Node object with various timestamps, environments, and status information. Handles conversion of JSON date strings to datetime objects.

```python
self.unreported_time = unreported_time
        self.report_timestamp = report_timestamp
        self.catalog_timestamp = catalog_timestamp
        self.facts_timestamp = facts_timestamp
        self.report_environment = report_environment
        self.catalog_environment = catalog_environment
        self.facts_environment = facts_environment
        self.latest_report_hash = latest_report_hash
        self.cached_catalog_status = cached_catalog_status

        if unreported:
            self.status = "unreported"
        elif noop and noop_pending:
            self.status = "noop"
        else:
            self.status = status_report

        if deactivated is not None:
            self.deactivated = json_to_datetime(deactivated)
        else:
            self.deactivated = False
        if expired is not None:
            self.expired = json_to_datetime(expired)
        else:
            self.expired = False
        if report_timestamp is not None:
            self.report_timestamp = json_to_datetime(report_timestamp)
        else:
            self.report_timestamp = report_timestamp
        if facts_timestamp is not None:
            self.facts_timestamp = json_to_datetime(facts_timestamp)
        else:
            self.facts_timestamp = facts_timestamp
        if catalog_timestamp is not None:
            self.catalog_timestamp = json_to_datetime(catalog_timestamp)
        else:
            self.catalog_timestamp = catalog_timestamp
```

--------------------------------

### Create Resource object from dictionary

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/types.html

Creates a Resource object from a dictionary. Extracts 'certname' for the node attribute.

```python
return Resource(
            node=resource["certname"],

```

--------------------------------

### Get a Single Node by Name

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/query.html

Fetches a specific node from PuppetDB using its name. This is a convenience method that calls the `nodes` query with the name as a path.

```python
nodes = self.nodes(path=name)
return next(node for node in nodes)
```

--------------------------------

### Inventory Class Factory Method

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/types.html

Creates an Inventory object from a dictionary, mapping dictionary keys to constructor arguments. Assumes the input dictionary has keys like 'certname', 'timestamp', 'environment', 'facts', and 'trusted'.

```python
@staticmethod
    def create_from_dict(inv):
        return Inventory(
            node=inv["certname"],
            time=inv["timestamp"],
            environment=inv["environment"],
            facts=inv["facts"],
            trusted=inv["trusted"],
        )
```

--------------------------------

### pypuppetdb.types.Report

Source: https://pypuppetdb.readthedocs.io/en/latest/developer.html

Represents a report generated by a Puppet agent run. It contains details about the agent run, including start and end times, status, and version information.

```APIDOC
## Class: pypuppetdb.types.Report

### Description
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.
* **status** (`string`) – (Optional) The status of the agent run.
* **metrics** (`dict`) – (Optional) Metrics collected during the agent run.
* **logs** (`dict`) – (Optional) Logs generated during the agent run.
* **environment** (`string`) – (Optional) The environment the agent ran in.
* **noop** (`bool`) – (Optional) Whether the agent ran in noop mode.
* **noop_pending** (`bool`) – (Optional) Whether noop mode was pending.
* **code_id** (`string`) – (Optional) The code ID of the catalog.
* **catalog_uuid** (`string`) – (Optional) The UUID of the catalog.
* **cached_catalog_status** (`string`) – (Optional) The status of the cached catalog.
* **producer** (`string`) – (Optional) The producer of the catalog.
```

--------------------------------

### List all available metrics

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/metrics.html

This method lists all available metrics when no specific metric name is provided and the API version is 'v2'.

```APIDOC
## metrics-list

### Description
List all available metrics.

### Method
GET

### Endpoint
/metrics/v2/metrics

### Parameters
This endpoint does not accept any parameters.

### Response
#### Success Response (200)
- **value** (list) - A list of available metric names.

### Request Example
```python
pdb.metrics().metric()
```

### Response Example
```json
{
  "value": [
    "puppetlabs.puppetdb.http.server:type=Clojurepiece,name=request-time",
    "puppetlabs.puppetdb.command:type=global,name=received-commands"
  ]
}
```
```

--------------------------------

### Query with Array Input

Source: https://pypuppetdb.readthedocs.io/en/latest/advanced_queries.html

Constructs an 'in' query to find nodes whose certnames are present in a provided list of server names. Requires importing QueryBuilder components.

```python
>>> from pypuppetdb.QueryBuilder import *
>>> op = InOperator('certname')
>>> op.add_array(["prod1.server.net", "prod2.server.net"])
>>> print(op)
["in","certname",["array", ['prod1.server.net', 'prod2.server.net']]]
```

--------------------------------

### Query Environments

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/query.html

Retrieves a list of all known environments from PuppetDB.

```APIDOC
## environments

### Description
Get all known environments from Puppetdb.

### Returns
- A list of dictionaries containing the results.
- Type: list of dict
```

--------------------------------

### Connect to PuppetDB

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb.html

Establishes a connection to PuppetDB. This function returns an object that can be used to query the API. It supports various connection parameters including host, port, SSL configuration, and authentication.

```python
from pypuppetdb import connect

db = connect()
```

--------------------------------

### Escape Metric Name for URL

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/metrics.html

Escapes metric names to be safely used in GET requests for the v2 metrics API, which is backed by Jolokia. Follows Jolokia's escaping rules.

```python
metric = metric.replace("!", r"!!")
metric = metric.replace("/", r"!/")
metric = metric.replace('"', r'!"')
return metric
```

--------------------------------

### Node Class Initialization

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/types.html

Initializes a Node object with various attributes representing a node's state and metadata. This is used internally by the pypuppetdb library.

```python
def __init__(
        self,
        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,
    ):
        self.name = name
        self.events = events
```

--------------------------------

### pypuppetdb API Connection Function

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb.html

The `connect` function initializes and returns an API object for interacting with PuppetDB. It accepts numerous parameters for configuring the connection, including host, port, SSL settings, and authentication credentials.

```python
import logging

from pypuppetdb.api import API

logging.getLogger(__name__).addHandler(logging.NullHandler())

def 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,
):
    """Connect with PuppetDB. This will return an object allowing you
    to query the API through its methods.

    :param host: (Default: 'localhost;) Hostname or IP of PuppetDB.
    :type host: :obj:`string`

    :param port: (Default: '8080') Port on which to talk to PuppetDB.
    :type port: :obj:`int`

    :param ssl_verify: (optional) Verify PuppetDB server certificate.
    :type ssl_verify: :obj:`bool` or :obj:`string` True, False or filesystem \
            path to CA certificate.

    :param ssl_key: (optional) Path to our client secret key.
    :type ssl_key: :obj:`None` or :obj:`string` representing a filesystem\
            path.

    :param ssl_cert: (optional) Path to our client certificate.
    :type ssl_cert: :obj:`None` or :obj:`string` representing a filesystem\
            path.

    :param timeout: (Default: 10) Number of seconds to wait for a response.
    :type timeout: :obj:`int`

    :param protocol: (optional) Explicitly specify the protocol to be used
            (especially handy when using HTTPS with ssl_verify=False and
            without certs)
    :type protocol: :obj:`None` or :obj:`string`

    :param url_path: (Default: '/') The URL path where PuppetDB is served
    :type url_path: :obj:`None` or :obj:`string`

    :param username: (optional) The username to use for HTTP basic
            authentication
    :type username: :obj:`None` or :obj:`string`

    :param password: (optional) The password to use for HTTP basic
            authentication
    :type password: :obj:`None` or :obj:`string`

    :param token: (optional) The x-auth token to use for X-Authentication
    :type token: :obj:`None` or :obj:`string`
    """
    return API(
        host=host,
        port=port,
        timeout=timeout,
        ssl_verify=ssl_verify,
        ssl_key=ssl_key,
        ssl_cert=ssl_cert,
        protocol=protocol,
        url_path=url_path,
        username=username,
        password=password,
        token=token,
    )

```

--------------------------------

### Type Name Capitalization and De-pluralization

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/pql.html

This code snippet demonstrates how to capitalize a type name and remove a trailing 's' to get a singular form, which is then used to retrieve the corresponding Python type class from `pypuppetdb.types`. It includes error handling for unsupported types.

```python
            # class name is capitalized
            type_name = type_name_lowercase.capitalize()

            # depluralize - remove trailing "s"
            if type_name.endswith("s"):
                type_name_singular = type_name[:-1]
            else:
                type_name_singular = type_name

            log.debug(f"Type name: {type_name_singular}")
            try:
                type_class = getattr(pypuppetdb.types, type_name_singular)
                return type_class
            except AttributeError:
                log.debug(
                    f"PQL returns entities of a type {type_name_singular},"
                    f" but it is not supported by this library yet."
                )
                return None
        else:
            log.debug("No match!")
            return None
```

--------------------------------

### Constructing an AND Query with pypuppetdb

Source: https://pypuppetdb.readthedocs.io/en/latest/developer.html

Use this to build an 'AND' query with multiple conditions. The resulting operator object can be directly passed to PuppetDB calls.

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

```python
>>> pypuppetdb.nodes(query=op)
```

--------------------------------

### CommandAPI._cmd

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/command.html

Internal method for posting commands to PuppetDB. It handles URL construction, parameter generation (including checksum), and request execution.

```APIDOC
## CommandAPI._cmd

### Description
This private method handles the core logic of sending commands to PuppetDB. It constructs the request URL, prepares parameters such as command version and checksum, and sends the POST request. It also manages error handling for timeouts, connection errors, and HTTP errors.

### Method Signature
`_cmd(command: str, payload: dict) -> Union[dict, list]`

### Parameters
- **command** (str) - The PuppetDB Command to execute.
- **payload** (dict) - The payload, in wire format, specific to the command.

### Raises
- :class:`~pypuppetdb.errors.APIError`
- :class:`~pypuppetdb.errors.EmptyResponseError`

### Returns
- The decoded response from PuppetDB.
- :obj:`dict` or :obj:`list`
```

--------------------------------

### Query from Different Entities with FromOperator

Source: https://pypuppetdb.readthedocs.io/en/latest/advanced_queries.html

Builds a query using FromOperator to access 'fact_contents' and filter by network interface MAC address, then extracts certnames. Requires importing QueryBuilder components.

```python
>>> op = InOperator('certname')
>>> ex = ExtractOperator()
>>> ex.add_field('certname')
>>> fr = FromOperator('fact_contents')
>>> nd = AndOperator()
>>> nd.add(EqualsOperator("path", ["networking", "eth0", "macaddresses", 0]))
>>> nd.add(EqualsOperator("value", "aa:bb:cc:dd:ee:00"))
>>> ex.add_query(nd)
>>> fr.add_query(ex)
>>> op.add_query(fr)
>>> print(op)
["in","certname",["from","fact_contents",["extract",["certname"],["and",["=", "path", ['networking', 'eth0', 'macaddresses', 0]],["=", "value", "aa:bb:cc:dd:ee:00"]]]]]
```

--------------------------------

### connect

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb.html

Establishes a connection to the PuppetDB API. This function returns an object that can be used to query the API through its methods.

```APIDOC
## connect

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

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **host** (string) - Optional - Default: 'localhost' - Hostname or IP of PuppetDB.
- **port** (int) - Optional - Default: '8080' - Port on which to talk to PuppetDB.
- **ssl_verify** (bool or string) - Optional - Verify PuppetDB server certificate. Can be True, False or a filesystem path to CA certificate.
- **ssl_key** (None or string) - Optional - Path to our client secret key.
- **ssl_cert** (None or string) - Optional - Path to our client certificate.
- **timeout** (int) - Optional - 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) - Optional - 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.

### Request Example
```python
from pypuppetdb import connect
db = connect(host='puppetdb.example.com', port=8080, ssl_verify=False)
```

### Response
#### Success Response (200)
Returns an API object that allows querying PuppetDB.

#### Response Example
```python
# Example of the returned object (not a direct output)
<pypuppetdb.api.API object at 0x...>
```
```

--------------------------------

### CommandAPI.cmd

Source: https://pypuppetdb.readthedocs.io/en/latest/developer.html

Posts commands to PuppetDB. Accepts a command and its payload, then sends a request to PuppetDB. Returns the decoded response or raises an error for HTTP status codes.

```APIDOC
## POST /pdb/cmd/

### Description
Posts commands to PuppetDB.

### Method
POST

### Endpoint
/pdb/cmd/

### Parameters
#### Request Body
- **command** (dict) - The PuppetDB Command to execute.
- **payload** (dict) - The payload, in wire format, specific to the command.

### Response
#### Success Response (200)
- **response** (dict or list) - The decoded response from PuppetDB.

### Raises
- EmptyResponseError
```

--------------------------------

### Configure pypuppetdb for SSL/TLS Connection

Source: https://pypuppetdb.readthedocs.io/en/latest/connecting.html

Connect to PuppetDB securely using SSL/TLS by providing paths to your private key, public certificate, and the CA root certificate. Specify the host and port for the PuppetDB instance.

```python
>>> db = connect(ssl_key='/path/to/private.pem', ssl_cert='/path/to/public.pem',
>>>              ssl_verify='/path/to/ca_crt.pem', host='puppetdb.example.com',
>>>              port=8081)
```

--------------------------------

### Initialize FromOperator

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/QueryBuilder.html

Use FromOperator to query the root endpoint or subqueries into other entities. Ensure the endpoint is valid.

```python
fr = FromOperator("facts")
fr.add_query(EqualsOperator("foo", "bar"))
fr.add_order_by(["certname"])
fr.add_limit(10)
```

--------------------------------

### Report Class Initialization

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/types.html

Initializes a Report object with data from PuppetDB. It processes various parameters including node information, timestamps, and report status, converting string timestamps to datetime objects.

```python
def __init__(
        self,
        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,
    ):
        self.node = node
        self.hash_ = hash_
        self.start = json_to_datetime(start)
        self.end = json_to_datetime(end)
        self.received = json_to_datetime(received)
        self.version = version
        self.format_ = format_
        self.agent_version = agent_version
        self.run_time = self.end - self.start
        self.transaction = transaction
        self.environment = environment
        self.status = "noop" if noop and noop_pending else status
        self.metrics = metrics
        self.logs = logs
        self.code_id = code_id
        self.catalog_uuid = catalog_uuid
        self.cached_catalog_status = cached_catalog_status
        self.producer = producer
        self.__string = f"{self.hash_}"

        self.__api = api
```

--------------------------------

### Current Version

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/metadata.html

Retrieves version information about the running PuppetDB server.

```APIDOC
## current_version

### Description
Get version information about the running PuppetDB server.

### Method
GET

### Endpoint
/pdb/meta/v1/version

### Response
#### Success Response (200)
- **version** (string) - A string representation of the PuppetDB version.

### Response Example
{
  "version": "6.15.0"
}
```

--------------------------------

### Connect to PuppetDB with Basic Authentication

Source: https://pypuppetdb.readthedocs.io/en/latest/connecting.html

Connect to PuppetDB using plain HTTPS with HTTP Basic Authentication. This requires a reverse proxy for SSL termination and authentication. Specify protocol, host, port, username, and password.

```python
>>> db = connect(protocol='https', host='puppetdb.example.com',
>>>              port=443, username='foo', password='bar')
```

--------------------------------

### Build an AND Query

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/QueryBuilder.html

Use AndOperator to create queries where all conditions must be met. Add individual criteria using the add method.

```python
op = AndOperator()
op.add(EqualsOperator("catalog_environment", "production"))
op.add(EqualsOperator("facts_environment", "production"))
```

--------------------------------

### Internal command execution logic

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/command.html

The `_cmd` method is an internal helper for posting commands to PuppetDB. It constructs the request URL, validates the command against supported versions, calculates a SHA1 checksum of the payload, and sends a POST request. It includes error handling for timeouts, connection errors, and HTTP errors.

```python
import hashlib
import json
import logging

import requests

from pypuppetdb.api.base import BaseAPI, COMMAND_VERSION, ERROR_STRINGS
from pypuppetdb.errors import APIError, EmptyResponseError

log = logging.getLogger(__name__) 



class CommandAPI(BaseAPI):
    """This class provides methods that interact with the `pdb/cmd/*`
    PuppetDB API endpoints.
    """

    def command(self, command, payload):
        return self._cmd(command, payload)


    def _cmd(self, command, payload):
        """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.

        :param command: The PuppetDB Command we want to execute.
        :type command: :obj:`string`

        :param command: The payload, in wire format, specific to the command.
        :type command: :obj:`dict`

        :raises: :class:`~pypuppetdb.errors.EmptyResponseError`

        :returns: The decoded response from PuppetDB
        :rtype: :obj:`dict` or :obj:`list`
        """
        log.debug("_cmd called with command: {}, data: {}".format(command, payload))

        url = self._url("cmd")

        if command not in COMMAND_VERSION:
            log.error(
                "Only {} supported, {} unsupported".format(
                    list(COMMAND_VERSION.keys()), command
                )
            )
            raise APIError

        params = {
            "command": command,
            "version": COMMAND_VERSION[command],
            "certname": payload["certname"],
            "checksum": hashlib.sha1(str(payload).encode("utf-8")).hexdigest(),  # nosec
        }

        try:
            r = self.session.post(
                url,
                params=params,
                data=json.dumps(payload, default=str),
                verify=self.ssl_verify,
                cert=(self.ssl_cert, self.ssl_key),
                timeout=self.timeout,
            )

            r.raise_for_status()

            json_body = r.json()
            if json_body is not None:
                return json_body
            else:
                del json_body
                raise EmptyResponseError

        except requests.exceptions.Timeout:
            log.error(
                "{} {}:{} over {}.".format(
                    ERROR_STRINGS["timeout"],
                    self.host,
                    self.port,
                    self.protocol.upper(),
                )
            )
            raise
        except requests.exceptions.ConnectionError:
            log.error(
                "{} {}:{} over {}.".format(
                    ERROR_STRINGS["refused"],
                    self.host,
                    self.port,
                    self.protocol.upper(),
                )
            )
            raise
        except requests.exceptions.HTTPError as err:
            log.error(
                "{} {}:{} over {}.".format(
                    err.response.text, self.host, self.port, self.protocol.upper()
                )
            )
            raise

```

--------------------------------

### Resource Object

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/types.html

Represents a resource declared in a Puppet manifest. It includes attributes such as node, name, type, exported status, source file and line, parameters, and environment. The `create_from_dict` static method facilitates object creation from a dictionary.

```APIDOC
## Resource

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

:param node: The hostname this resource is located on.
:type node: :obj:`string`
:param name: The name of the resource in the Puppet manifest.
:type name: :obj:`string`
:param type_: Type of the Puppet resource.
:type type_: :obj:`string`
:param tags: Tags associated with this resource.
:type tags: :obj:`list`
:param exported: If it's an exported resource.
:type exported: :obj:`bool`
:param sourcefile: The Puppet manifest this resource is declared in.
:type sourcefile: :obj:`string`
:param sourceline: The line this resource is declared at.
:type sourceline: :obj:`int`
:param parameters: (Optional) The parameters this resource has been declared with.
:type parameters: :obj:`dict`
:param environment: (Optional) The environment of the node associated with this resource.
:type environment: :obj:`string`

:ivar node: The hostname this resources is located on.
:ivar name: The name of the resource in the Puppet manifest.
:ivar type_: The type of Puppet resource.
:ivar exported: :obj:`bool` if the resource is exported.
:ivar sourcefile: The Puppet manifest this resource is declared in.
:ivar sourceline: The line this resource is declared at.
:ivar parameters: :obj:`dict` with key:value pairs of parameters.
:ivar relationships: :obj:`list` Contains all relationships to other resources
:ivar environment: :obj:`string` The environment of the node associated with this resource.

### Static Methods

#### create_from_dict(resource)

Creates a Resource object from a dictionary.

:param resource: A dictionary containing resource data.
:return: A Resource object.

### Instance Methods

#### __init__(node, name, type_, tags, exported, sourcefile, sourceline, environment=None, parameters={})

Initializes a Resource object.

#### __repr__()

Returns the string representation of the Resource object.

#### __str__()

Returns the string representation of the Resource object.
```

--------------------------------

### Create Report object from dictionary

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/types.html

Instantiates a Report object using data from a dictionary. Handles optional fields like 'noop' and 'noop_pending'.

```python
return Report(
            api=query_api,
            node=report["certname"],
            hash_=report["hash"],
            start=report["start_time"],
            end=report["end_time"],
            received=report["receive_time"],
            version=report["configuration_version"],
            format_=report["report_format"],
            agent_version=report["puppet_version"],
            transaction=report["transaction_uuid"],
            environment=report["environment"],
            status=report["status"],
            noop=report.get("noop"),
            noop_pending=report.get("noop_pending"),
            metrics=report["metrics"]["data"],
            logs=report["logs"]["data"],
            code_id=report.get("code_id"),
            catalog_uuid=report.get("catalog_uuid"),
            cached_catalog_status=report.get("cached_catalog_status"),
        )
```

--------------------------------

### Resources

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/query.html

Queries for resources, optionally limited by type and/or title.

```APIDOC
## GET /resources

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

### Method
GET

### Endpoint
/resources

### Parameters
#### Query Parameters
- **type_** (string) - Optional - The resource type.
- **title** (string) - Optional - The name of the resource as declared as the 'namevar' in the Puppet Manifests. This parameter requires the `type_` parameter be set.
- **kwargs** (dict) - Optional - The rest of the keyword arguments are passed to the _query function.

### Response
#### Success Response (200)
- **results** (generator of Resource) - A generator yielding Resources.

### Response Example
{
  "example": "[ { \"certname\": \"host1.example.com\", \"type\": \"Package\", \"title\": \"nginx\", \"exported\": false, \"parameters\": { \"ensure\": \"present\" } } ]"
}
```

--------------------------------

### PQL Query Execution

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/pql.html

This method allows you to execute a PQL query against the PuppetDB API. It handles the preparation and execution of the query, returning the results.

```APIDOC
## pql(pql, with_status=False, unreported=2, with_event_numbers=True)

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

### Parameters
#### Path Parameters
None

#### Query Parameters
- **pql** (string) - Required - PQL query
- **with_status** (bool) - 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** (bool) - 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.

### Request Example
```python
# Example usage (assuming 'pdb' is an instance of pypuppetdb.Client)
pdb.pql('nodes[certname, active] { active = true }')
```

### Response
#### Success Response (200)
- A generator yielding elements of a rich type or plain dicts.
```

--------------------------------

### Submit a command to PuppetDB

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/api/command.html

Use the `command` method to send a command and its payload to PuppetDB. This method handles the underlying API request, including constructing the URL, setting parameters, and serializing the payload.

```python
command_api.command(command='some_command', payload={'certname': 'test.example.com', 'some_data': 'value'})

```

--------------------------------

### Inventory Class String Conversion

Source: https://pypuppetdb.readthedocs.io/en/latest/_modules/pypuppetdb/types.html

Defines the string conversion for the Inventory object, returning the node's certname.

```python
def __str__(self):
        return "{}".format(self.__string)
```
Tokens:
Raw