1.. _developer:
2
3Developer Guide
4===============
5
6.. module:: pypuppetdb
7
8This part of the documentation covers all the interfaces of PyPuppetDB.
9It will cover how the API is set up and how to configure which version of
10the API to use.
11
12Lazy objects
13------------
14
15.. note::
16
17   Reading in the response from PuppetDB is currently greedy, it will read in
18   the complete response no matter the size. This will change once streaming
19   and pagination support are added to PuppetDB's endpoints.
20
21In order for pypuppetdb to be able to deal with big datasets those functions
22that are expected to return more than a single item are implemented as
23generators.
24
25This is usually the case for functions with a plural name like
26:func:`~pypuppetdb.api.QueryAPI.nodes` or :func:`~pypuppetdb.api.QueryAPI.facts`.
27
28Because of this we'll only query PuppetDB once you start iterating over the
29generator object. Until that time not a single request is fired at PuppetDB.
30
31Most singular functions are implemented by calling their plural counterpart
32and then iterating over the generator, immediately exhausting the generator
33and returning a single/the first object.
34
35
36API and BaseAPI classes
37-----------------------
38
39The starting point for the library is the :func:`connect` method used to set up a
40connection with PuppetDB.
41
42.. autofunction:: connect
43
44This method returns the ``API`` class instance.
45
46That class is built using mixins from the endpoint-specific classes, such as
47``PqlAPI`` (see the next section for more info about them).
48
49All the endpoint-specific classes inherit from the abstract ``BaseAPI`` class
50which contains the logic shared by all the endpoints, such as:
51
52* connecting to the PuppetDB (in the constructor),
53* disconnecting from the PuppetDB (``disconnect()``),
54* ``_query()`` and ``_make_request()`` that prepare and make HTTP(S) requests
55  to PuppetDB,
56
57
58Endpoint classes
59----------------
60
61The supported PuppetDB endpoint types are implemented in classes with
62corresponding names:
63
64* pdb/query/v4 - ``PqlAPI``
65* pdb/query/v4/* - ``QueryAPI``
66* pdb/cmd/v1 - ``CommandAPI``
67* status/v1/** - ``StatusAPI``
68* pdb/meta/v1* - ``MetadataAPI``
69* metrics/* - ``MetricsAPI``
70
71
72PqlAPI
73^^^^^^
74
75.. autoclass:: pypuppetdb.api.PqlAPI
76   :members:
77   :private-members:
78
79QueryAPI
80^^^^^^^^
81
82.. autoclass:: pypuppetdb.api.QueryAPI
83   :members:
84   :private-members:
85
86CommandAPI
87^^^^^^^^^^
88
89.. autoclass:: pypuppetdb.api.CommandAPI
90   :members:
91   :private-members:
92
93StatusAPI
94^^^^^^^^^
95
96.. autoclass:: pypuppetdb.api.StatusAPI
97   :members:
98   :private-members:
99
100MetadataAPI
101^^^^^^^^^^^
102
103.. autoclass:: pypuppetdb.api.MetadataAPI
104   :members:
105   :private-members:
106
107MetricsAPI
108^^^^^^^^^^
109
110.. autoclass:: pypuppetdb.api.MetricsAPI
111   :members:
112   :private-members:
113
114
115Types
116-----
117
118In order to facilitate working with the API most methods like
119:meth:`~pypuppetdb.api.QueryAPI.nodes` don't return the decoded
120JSON response but return an object representation of the querried
121endpoints data.
122
123.. autoclass:: pypuppetdb.types.Node
124   :members:
125.. autoclass:: pypuppetdb.types.Fact
126.. autoclass:: pypuppetdb.types.Resource
127.. autoclass:: pypuppetdb.types.Event
128.. autoclass:: pypuppetdb.types.Report
129   :members:
130.. autoclass:: pypuppetdb.types.Catalog
131   :members:
132.. autoclass:: pypuppetdb.types.Edge
133.. autoclass:: pypuppetdb.types.Inventory
134
135Errors
136------
137
138Unfortunately things can go haywire. PuppetDB might not be reachable
139or complain about our query, requests might have to wait too long to
140receive a response or the body is just too big to handle.
141
142In that case, we'll throw an exception at you.
143
144.. autoexception:: pypuppetdb.errors.APIError
145.. autoexception:: pypuppetdb.errors.ImproperlyConfiguredError
146   :show-inheritance:
147.. autoexception:: pypuppetdb.errors.DoesNotComputeError
148   :show-inheritance:
149.. autoexception:: pypuppetdb.errors.EmptyResponseError
150   :show-inheritance:
151
152Query Builder
153-------------
154
155With the increasing complexities of some queries it can be very difficult
156to maintain query strings as string objects. The 0.3.0 release introduces
157a new feature called the Query Builder which removes the need of string
158object concatenation into an Object-Oriented fashion.
159
160In order to create the following query:
161
162``'["and", ["=", "facts_environment", "production"], ["=", "catalog_environment", "production"]]'``
163
164Users can use the following code block to create the same thing:
165
166.. code-block:: python
167
168   >>> from pypuppetdb.QueryBuilder import *
169   >>> op = AndOperator()
170   >>> op.add(EqualOperator("facts_environment", "production"))
171   >>> op.add(EqualOperator("catalog_environment", "production"))
172
173The ``op`` object can then be directly input to the query parameter of any
174PuppetDB call.
175
176.. code-block:: python
177
178   >>> pypuppetdb.nodes(query=op)
179
180.. autoclass:: pypuppetdb.QueryBuilder.BinaryOperator
181   :members:
182.. autoclass:: pypuppetdb.QueryBuilder.EqualsOperator
183.. autoclass:: pypuppetdb.QueryBuilder.GreaterOperator
184.. autoclass:: pypuppetdb.QueryBuilder.LessOperator
185.. autoclass:: pypuppetdb.QueryBuilder.GreaterEqualOperator
186.. autoclass:: pypuppetdb.QueryBuilder.LessEqualOperator
187.. autoclass:: pypuppetdb.QueryBuilder.RegexOperator
188.. autoclass:: pypuppetdb.QueryBuilder.RegexArrayOperator
189.. autoclass:: pypuppetdb.QueryBuilder.NullOperator
190.. autoclass:: pypuppetdb.QueryBuilder.BooleanOperator
191   :members:
192.. autoclass:: pypuppetdb.QueryBuilder.AndOperator
193.. autoclass:: pypuppetdb.QueryBuilder.OrOperator
194.. autoclass:: pypuppetdb.QueryBuilder.NotOperator
195.. autoclass:: pypuppetdb.QueryBuilder.ExtractOperator
196   :members:
197.. autoclass:: pypuppetdb.QueryBuilder.FunctionOperator
198   :members:
199.. autoclass:: pypuppetdb.QueryBuilder.SubqueryOperator
200   :members:
201.. autoclass:: pypuppetdb.QueryBuilder.InOperator
202   :members:
203.. autoclass:: pypuppetdb.QueryBuilder.FromOperator
204   :members:
205
206Utilities
207---------
208
209A few functions that are used across this library have been put
210into their own :mod:`utils` module.
211
212.. autoclass::    pypuppetdb.utils.UTC
213.. autofunction:: pypuppetdb.utils.json_to_datetime
214.. autofunction:: pypuppetdb.utils.versioncmp
215