some docstrings for "charts.py"
lgz committed
Oct 18, 2017 at 17:11 UTC
109ca79014838ce070b845f17cfc57992ba05bbb
1 file changed
+44
-13
python.d/python_modules/bases/charts.py
+44
-13
@@ -30,6 +30,12 @@ RUNTIME_CHART_CREATE = "CHART netdata.runtime_{job_name} '' 'Execution time for
30
31
def create_runtime_chart(func):
32
"""
33
+ Calls a wrapped function, then prints runtime chart to stdout.
34
+
35
+ Used as a decorator for SimpleService.create() method.
36
+ The whole point of making 'create runtime chart' functionality as a decorator was
37
+ to help users who re-implements create() in theirs classes.
38
+
39
:param func: class method
40
:return:
41
"""
@@ -43,11 +49,24 @@ def create_runtime_chart(func):
49
return wrapper
50
51
46
-class DuplicateError(Exception):
47
- pass
52
+class ChartError(Exception):
53
+ """Base-class for all exceptions raised by this module"""
54
+
55
+
56
+class DuplicateChartError(ChartError):
57
+ """Raised when user re-adds a chart that has already been added"""
58
+
59
+
60
+class DuplicateDimensionError(ChartError):
61
+ """Raised when user re-adds a dimension that has already been added"""
62
63
64
class Charts:
65
+ """Represent a collection of charts
66
+
67
+ All charts stored in a dict.
68
+ Chart is a instance of Chart class.
69
+ Charts adding must be done using Charts.add_chart() method only"""
70
def __init__(self, job_name, priority, update_every):
71
"""
72
:param job_name: <bound method>
@@ -92,13 +111,16 @@ class Charts:
111
112
def add_chart(self, params):
113
"""
114
+ Create Chart instance and add it to the dict
115
+
116
+ Manually adds job name, priority and update_every to params.
117
:param params: <list>
118
:return:
119
"""
120
params = [self.job_name()] + params
121
chart_id = params[1]
122
if chart_id in self.charts:
101
- raise DuplicateError('{chart} already in charts'.format(chart=chart_id))
123
+ raise DuplicateChartError('{chart} already in charts'.format(chart=chart_id))
124
else:
125
new_chart = Chart(params)
126
new_chart.params['update_every'] = self.update_every
@@ -109,12 +131,15 @@ class Charts:
131
132
133
class Chart:
134
+ """Represent a chart"""
135
def __init__(self, params):
136
"""
137
:param params: <list>
138
"""
116
- if not (params and isinstance(params, list) and len(params) >= 8):
117
- raise ValueError('Chart params must be a list with 7 items')
139
+ if not isinstance(params, list):
140
+ raise TypeError("'chart' must be a list type")
141
+ if not len(params) >= 8:
142
+ raise ValueError('invalid value for "chart", must be {0}'.format(CHART_PARAMS))
143
144
self.params = dict(zip(CHART_PARAMS, (p or str() for p in params)))
145
self.name = '{type}.{id}'.format(type=self.params['type'],
@@ -151,8 +176,8 @@ class Chart:
176
:return:
177
"""
178
if dimension[0] in [repr(d) for d in self.dimensions]:
154
- raise DuplicateError('{dimension} already in {chart} dimensions'.format(dimension=dimension[0],
155
- chart=self.name))
179
+ raise DuplicateDimensionError('{dimension} already in {chart} dimensions'.format(dimension=dimension[0],
180
+ chart=self.name))
181
self.dimensions.append(Dimension(dimension))
182
183
def add_dimension_and_push_chart(self, dimension):
@@ -161,8 +186,8 @@ class Chart:
186
:return:
187
"""
188
if dimension[0] in [repr(d) for d in self.dimensions]:
164
- raise DuplicateError('{dimension} already in {chart} dimensions'.format(dimension=dimension[0],
165
- chart=self.name))
189
+ raise DuplicateDimensionError('{dimension} already in {chart} dimensions'.format(dimension=dimension[0],
190
+ chart=self.name))
191
dimension = Dimension(dimension)
192
self.dimensions.append(dimension)
193
safe_print(self.create(dimension))
@@ -195,12 +220,15 @@ class Chart:
220
221
222
class Dimension:
223
+ """Represent a dimension"""
224
def __init__(self, params):
225
"""
226
:param params: <list>
227
"""
202
- if not (params and isinstance(params, list)):
203
- raise ValueError('Dimension params must be a not empty list')
228
+ if not isinstance(params, list):
229
+ raise TypeError("'dimension' must be a list type")
230
+ if not params:
231
+ raise ValueError('invalid value for "dimension", must be {0}'.format(DIMENSION_PARAMS))
232
233
self.params = dict(zip(DIMENSION_PARAMS, (p or str() for p in params)))
234
self.params['name'] = self.params.get('name') or self.params['id']
@@ -229,12 +257,15 @@ class Dimension:
257
258
259
class ChartVariable:
260
+ """Represent a chart variable"""
261
def __init__(self, params):
262
"""
263
:param params: <list>
264
"""
236
- if not (params and isinstance(params, list)):
237
- raise ValueError('Variable params must be a not empty list')
265
+ if not isinstance(params, list):
266
+ raise TypeError("'variable' must be a list type")
267
+ if not params:
268
+ raise ValueError('invalid value for "variable", must be: {0}'.format(VARIABLE_PARAMS))
269
270
self.params = dict(zip(VARIABLE_PARAMS, params))
271
self.params.setdefault('value', None)