add comments and validation_example_html

Collectl2plotly/Collectl2plotly/Collectl2plotly.py

@@ -34,18 +34,25 @@ DEFAULT_FILTER = 'average'
 
 ### validation Config
 
-# Merger that exist and posible kwargs/parameter
+# Merger that exist and possible kwargs/parameter
+# key   = merger_func name
+# value = dict with kwarguments of merger_func 
+# kwargument dict:
+# key = argument name
+# value = 1. 'type' with a type obj or a tuple of type objs 
+#         or 
+#         2. 'choices' list of possible choices for the kwargument
 MERGER = {
     'x2oneaddition_int': {
         'roundingpoint': {'type':int},
-        'operator': {'type': str, 'choices': ['+', '-', '*', '/', '%']},
+        'operator': {'choices': ['+', '-', '*', '/', '%']},
         'operator_value': {'type': (int, float)},
     },
     'x2oneaddition_float': {
         'roundingpoint': {'type':int},
         'operator': {'type': str, 'choices': ['+', '-', '*', '/', '%']},
         'operator_value': {'type': (int, float)},
-    }
+    },
 }
 
 # validation infos of config
@@ -180,8 +187,11 @@ def is_merger(to_check):
     except ValueError:
         return False, "'{0}' has no right merger structur expected: (name[str], kwargs[dict])".format(to_check)
 
+    #check name and mergerkwargs has right types
     if isinstance(name, str) and isinstance(mergerkwargs, dict):
+        # check is the given merger known
         if name in MERGER:
+            # check every kwarg of the given merger is it known and is right value for it given.
             for kwarg_name, value in mergerkwargs.items():
                 if kwarg_name in MERGER[name]:
                     if 'choices' in MERGER[name][kwarg_name]:
@@ -209,20 +219,25 @@ def check_valid(to_check, validationinfos):
 
     Arguments:
         to_check {unkown} -- object to check is valid
-        validationinfos {dict or type or tuple with types} -- infos what is  needed that to_check is valid
+        validationinfos {validationdict(see comment of VALIDATIONS_INFOS) or type or tuple with types} -- infos what is needed that to_check is valid
 
     Returns:
         (bool, str) -- return true if it is valid, false and error if not
     """
+    # check is validationinfos a validationdict or only a type/tuple of types
     if isinstance(validationinfos, dict):
         if validationinfos['type'] == '__merger__':
             return is_merger(to_check)
         else:
+            # check is given elem expected type
             if isinstance(to_check, validationinfos['type']):
+                # if elem dict check special cases of it
                 if type(to_check) == dict:
+                    # check is elem is empty and is this ok
                     if not validationinfos.get('emptyable', False) and not len(to_check):
                         return False, '{0} can not be empty!'.format(to_check)
 
+                    # check special keys and there values if 'fixed_keys' is given
                     for fixed_name, infos in validationinfos.get('fixed_keys', {}).items():
                         if fixed_name in to_check:
                             if 'validator' in infos:
@@ -233,6 +248,7 @@ def check_valid(to_check, validationinfos):
                         elif infos.get('required', True):
                             return False, '{0} missing key: "{1}"'.format(to_check, fixed_name)
 
+                    # check all keys and there values if 'changing_keys' is given
                     if 'changing_keys' in validationinfos:
                         for key, subvalue in to_check.items():
                             if not isinstance(key, validationinfos['changing_keys']['key_type']):
@@ -243,11 +259,13 @@ def check_valid(to_check, validationinfos):
                                 valid, error_msg =  check_valid(subvalue, validationinfos['changing_keys']['validator'])
                                 if not valid:
                                     return valid, '[{0}] => {1}'.format(key, error_msg)
-
-                if isinstance(to_check, (list, tuple)):
+                # if elem list or tuple check special cases of it                 
+                elif isinstance(to_check, (list, tuple)):
+                    # check is elem is empty and is this ok
                     if not validationinfos.get('emptyable', False) and not len(to_check):
                         return False, '{0} can not be empty!'.format(to_check)
 
+                    # validate all values of tuple/list if 'subvalue_validator' is given
                     if 'subvalue_validator' in validationinfos:
                         for i, subvalue in enumerate(to_check):
                             valid, error_msg = check_valid(subvalue, validationinfos['subvalue_validator'])
@@ -260,9 +278,11 @@ def check_valid(to_check, validationinfos):
                     )
 
     else:
+        # check it is the special case that is the type is '__merger__'
         if validationinfos == '__merger__':
             return is_merger(to_check)
         else:
+            # check is given elem expected type
             if not isinstance(to_check, validationinfos):
                 return False, '{0} is {1} expected: {2}'.format(
                     to_check, type(to_check), validationinfos,
@@ -598,6 +618,7 @@ def build_html(plots_dict):
         with tag('head'):
             with tag('script', src='plotly.js'):
                 pass
+            # build plotly javascipt in html
             with tag('script'):
                 doc.asis("document.onreadystatechange = () => {if (document.readyState === 'complete') {")
                 for name, plots in plots_dict.items():
@@ -615,6 +636,7 @@ def build_html(plots_dict):
                         with tag('li'):
                             with tag('a', href='#'+name):
                                 text(name)
+            # add div for all plots in html
             for name, plots in plots_dict.items():
                 with tag('div', id=name):
                     for i in range(len(plots)):
@@ -663,10 +685,12 @@ def data_from_file(arguments):
     """
     path, collectl, shorten_cmds, coarsest, filtercmds, filtervalue, filtertype, config = arguments
     host = ''
+    # get hostname
     with gzip.open(path, 'r') as f:
         for line in f:
             if line.startswith(b'# Host:'):
                 host = re.search(r'# Host: *([^ ]+)', line.decode()).group(1)
+    
     data, filter_data = parse_file(path, collectl, shorten_cmds, coarsest, config)
 
     filter_infos = None
@@ -722,6 +746,7 @@ def main(source, collectl, plotlypath, destination, configpath,
             print('in destination "collectlplots" already exist')
             exit(1)
 
+    # load custome conf if given
     config_module = default_plot_conf
     if configpath:
         if configpath.endswith('.py'):

collectl_value_validation/html/plotly.js

+../../Collectl2plotly/Collectl2plotly/plotly-latest.min.js
\ No newline at end of file

readme.md

@@ -290,7 +290,7 @@ A merger is a function that merge a values from collectl to existing base value.
 
 ### Add new Merger
 In default it gives only two filter but in value_merger.py it is possible to add more.
-If one merger is added in value_merger.py he must be added in the global var MERGER in Collectl2plotly.py.
+If one merger is added in value_merger.py he must be added in the global variable MERGER in Collectl2plotly.py.
 
 #### Arguments of a merger function
 1. base value is the initial value for merging on it. Normaly has the same type like the return value