More filter spec

Signed-off-by: Stew Francis <[email protected]>

Author: stewartfrancis

plugins/doc_fragments/cmci.py

@@ -163,7 +163,7 @@ class ModuleDocFragment(object):
           - Filters can be nested. At most four nesting layers are allowed.
           - When supplying the C(attribute) option, you must also supply a
             C(value) for the filter.  You can also override the default operator
-            with the C(=) option.
+            of C(=) with the C(operator) option.
           - For examples, see M(cmci_get)
         type: dict
         required: false
@@ -176,6 +176,7 @@ class ModuleDocFragment(object):
                 nested filter expression can be either an C(attribute), C(and)
                 or C(or) complex filter expression.
             type: list
+            elements: dict
             required: false
           or:
             description:
@@ -185,6 +186,7 @@ class ModuleDocFragment(object):
                 nested filter expression can be either an C(attribute), C(and)
                 or C(or) complex filter expression.
             type: list
+            elements: dict
             required: false
           attribute:
             description:
@@ -227,6 +229,7 @@ class ModuleDocFragment(object):
                 as documented in the resource table reference, for example,
                 L(PROGDEF resource table reference,
                 https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGDEFtab.html).
+            type: str
             required: false
       get_parameters:
         description: >
@@ -239,6 +242,7 @@ class ModuleDocFragment(object):
           as found in the L(PROGDEF resource table reference,
           https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.6.0/reference-cpsm-restables/cpsm-restables/PROGDEFtab.html).
         type: list
+        elements: dict
         suboptions:
           name:
             description: Parameter name available for the GET operation.

plugins/module_utils/cmci.py

@@ -8,8 +8,7 @@
 
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib,\
     env_fallback
-from typing import Optional, Dict, Any
-from itertools import chain
+from typing import Optional, Dict, Any, List
 from collections import OrderedDict
 from sys import version_info
 import re
@@ -49,74 +48,49 @@
 GET_PARAMETERS = 'get_parameters'
 
 
-def _attribute_arguments(required):
-    return [
-        ('attribute', {
-            'type': 'str',
-            'required': required
-        }),
-        ('operator', {
-            'type': 'str',
-            'required': False,
-            'default': 'EQ',
-            'choices': ['<', '<=', '=', '>', '>=', '¬=', '==', '!=', 'EQ', 'NE',
-                        'LT', 'LE', 'GE', 'GT', 'IS']
-        }),
-        ('value', {
-            'type': 'str',
-            'required': required
-        })
-    ]
-
-
-def _cf_node(options):  # type: ([(str, Any)]) -> [(str, Any)]
-
-    sub = dict(chain(
-        options,
-        [
-            ('type', 'list'),
-            ('elements', 'dict')
-        ]
-    ))
-
-    return [
-        ('required', False),
-        ('required_together', [
+def _complex_filter():
+    return {
+        'type': 'dict',
+        'required': False,
+        'required_together': [
             ('attribute', 'value')
-        ]),
-        ('required_one_of', [
+        ],
+        'required_one_of': [
             ('attribute', 'and', 'or')
-        ]),
-        ('mutually_exclusive', [
-            ('attribute', 'and', 'or'),
-            ('and', 'operator'),
-            ('and', 'value'),
-            ('or', 'operator'),
-            ('or', 'value')
-        ]),
-        ('options', dict(chain(
-            _attribute_arguments(False),
-            [
-                ('and', sub),
-                ('or', sub)
-            ]
-        )))
-    ]
-
-
-def _complex_filter():
-    return dict(chain(
-        _cf_node(
-            _cf_node(
-                _cf_node(
-                    _cf_node([
-                        ('options', dict(_attribute_arguments(True)))
-                    ])
-                )
-            )
-        ),
-        [('type', 'dict')]
-    ))
+        ],
+        'required_by': {
+            'operator': 'attribute'
+        },
+        'mutually_exclusive': [
+            ('attribute', 'and', 'or')
+        ],
+        'options': {
+            'attribute': {
+                'type': 'str',
+                'required': False
+            },
+            'operator': {
+                'type': 'str',
+                'required': False,
+                'choices': ['<', '<=', '=', '>', '>=', '¬=', '==', '!=', 'EQ',
+                            'NE', 'LT', 'LE', 'GE', 'GT', 'IS']
+            },
+            'value': {
+                'type': 'str',
+                'required': False
+            },
+            'and': {
+                'type': 'list',
+                'elements': 'dict',
+                'required': False
+            },
+            'or': {
+                'type': 'list',
+                'elements': 'dict',
+                'required': False
+            }
+        }
+    }
 
 
 def parameters_argument(name):  # type: (str) -> Dict[str, Any]
@@ -410,6 +384,7 @@ def init_url(self):  # type: () -> str
     def init_request_params(self):  # type: () -> Optional[Dict[str, str]]
         return None
 
+    # TODO: why do we have this and/or parsing twice?
     def get_resources_request_params(self):  # type: () -> Dict[str, str]
         # get, delete, put will all need CRITERIA{}
         request_params = OrderedDict({})
@@ -440,17 +415,19 @@ def get_resources_request_params(self):  # type: () -> Dict[str, str]
                 attribute_item = complex_filter['attribute']
 
                 if and_item is not None:
-                    complex_filter_string = _get_filter(
+                    complex_filter_string = self._get_filter(
                         and_item,
                         complex_filter_string,
-                        ' AND '
+                        ' AND ',
+                        ' -> and'
                     )
 
                 if or_item is not None:
-                    complex_filter_string = _get_filter(
+                    complex_filter_string = self._get_filter(
                         or_item,
                         complex_filter_string,
-                        ' OR '
+                        ' OR ',
+                        ' -> or'
                     )
 
                 if attribute_item is not None:
@@ -605,6 +582,74 @@ def append_attributes(self, element):
                 {'@' + key: value for key, value in items}
             )
 
+    def _get_filter(self, list_of_filters, complex_filter_string, joiner, path):
+        #  type: (List[Dict], str, str, str) -> str
+        for i in list_of_filters:
+            and_item = i.get('and')
+            or_item = i.get('or')
+            attribute = i.get('attribute')
+            op = i.get('operator')
+
+            if op and not attribute:
+                self._fail(
+                    "missing parameter(s) required by 'operator': attribute"
+                )
+
+            # Validate mutually exclusive parameters
+            if (and_item and or_item) or (and_item and attribute) or \
+                    (or_item and attribute):
+                self._fail(
+                    'parameters are mutually exclusive: attribute|and|or found '
+                    'in resources -> complex_filter' + path
+                )
+
+            if and_item is not None:
+                and_filter_string = self._get_filter(
+                    and_item,
+                    '',
+                    ' AND ',
+                    path + ' -> and'
+                )
+                complex_filter_string = _append_filter_string(
+                    complex_filter_string,
+                    and_filter_string, joiner
+                )
+            if or_item is not None:
+                or_filter_string = self._get_filter(
+                    or_item,
+                    '',
+                    ' OR ',
+                    path + ' -> or'
+                )
+                complex_filter_string = _append_filter_string(
+                    complex_filter_string,
+                    or_filter_string, joiner
+                )
+            if attribute is not None:
+                operator = _convert_filter_operator(op)
+                value = i.get('value')
+
+                if value is None:
+                    self._fail(
+                        'parameters are required together: attribute, value '
+                        'found in resources -> complex_filter' + path)
+
+                if operator == '¬=':
+                    # Provides a filter string in the format NOT(FOO=='BAR')
+                    attribute_filter_string = \
+                        'NOT(' + attribute + '==' + '\'' + value + '\'' + ')'
+                else:
+                    attribute_filter_string = \
+                        attribute + operator + '\'' + value + '\''
+
+                complex_filter_string = _append_filter_string(
+                    complex_filter_string,
+                    attribute_filter_string,
+                    joiner
+                )
+
+        return complex_filter_string
+
     def _fail(self, msg):  # type: (str) -> None
         self._module.fail_json(msg=msg, **self.result)
 
@@ -617,7 +662,7 @@ def _convert_filter_operator(operator):
         return '<'
     if operator in ['<=', 'LE']:
         return '<='
-    if operator in ['=', 'EQ']:
+    if operator in ['=', 'EQ', None]:
         return '='
     if operator in ['>=', 'GE']:
         return '>='
@@ -629,45 +674,6 @@ def _convert_filter_operator(operator):
         return '=='
 
 
-def _get_filter(list_of_filters, complex_filter_string, joiner):
-    for i in list_of_filters:
-        and_item = i.get('and')
-        or_item = i.get('or')
-        attribute = i.get('attribute')
-
-        if and_item is not None:
-            and_filter_string = _get_filter(and_item, '', ' AND ')
-            complex_filter_string = _append_filter_string(
-                complex_filter_string,
-                and_filter_string, joiner
-            )
-        if or_item is not None:
-            or_filter_string = _get_filter(or_item, '', ' OR ')
-            complex_filter_string = _append_filter_string(
-                complex_filter_string,
-                or_filter_string, joiner
-            )
-        if attribute is not None:
-            operator = _convert_filter_operator(i.get('operator'))
-            value = i.get('value')
-
-            if operator == '¬=':
-                # Provides a filter string in the format NOT(FOO=='BAR')
-                attribute_filter_string =\
-                    'NOT(' + attribute + '==' + '\'' + value + '\'' + ')'
-            else:
-                attribute_filter_string = \
-                    attribute + operator + '\'' + value + '\''
-
-            complex_filter_string = _append_filter_string(
-                complex_filter_string,
-                attribute_filter_string,
-                joiner
-            )
-
-    return complex_filter_string
-
-
 def _append_filter_string(existing, to_append, joiner=' AND '):
     # joiner is ' AND ' or ' OR '
     if not existing:

tests/sanity/ignore-2.10.txt

@@ -1,34 +1,6 @@
 docs/make.bat line-endings!skip # Windows batch file requires windows line endings
 plugins/modules/cmci_get.py validate-modules:missing-gplv3-license # Licence is Apache-2.0
-plugins/modules/cmci_get.py validate-modules:doc-choices-do-not-match-spec # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_get.py validate-modules:doc-default-does-not-match-spec # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_get.py validate-modules:missing-suboption-docs # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_get.py validate-modules:parameter-type-not-in-doc # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_get.py validate-modules:undocumented-parameter # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_get.py validate-modules:doc-elements-mismatch # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_get.py validate-modules:doc-required-mismatch # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
 plugins/modules/cmci_action.py validate-modules:missing-gplv3-license # Licence is Apache-2.0
-plugins/modules/cmci_action.py validate-modules:doc-choices-do-not-match-spec # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_action.py validate-modules:doc-default-does-not-match-spec # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_action.py validate-modules:missing-suboption-docs # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_action.py validate-modules:parameter-type-not-in-doc # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_action.py validate-modules:undocumented-parameter # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_action.py validate-modules:doc-elements-mismatch # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_action.py validate-modules:doc-required-mismatch # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
 plugins/modules/cmci_create.py validate-modules:missing-gplv3-license # Licence is Apache-2.0
 plugins/modules/cmci_delete.py validate-modules:missing-gplv3-license # Licence is Apache-2.0
-plugins/modules/cmci_delete.py validate-modules:doc-choices-do-not-match-spec # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_delete.py validate-modules:doc-default-does-not-match-spec # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_delete.py validate-modules:missing-suboption-docs # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_delete.py validate-modules:parameter-type-not-in-doc # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_delete.py validate-modules:undocumented-parameter # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_delete.py validate-modules:doc-elements-mismatch # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_delete.py validate-modules:doc-required-mismatch # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_update.py validate-modules:missing-gplv3-license # Licence is Apache-2.0
-plugins/modules/cmci_update.py validate-modules:doc-choices-do-not-match-spec # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_update.py validate-modules:doc-default-does-not-match-spec # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_update.py validate-modules:missing-suboption-docs # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_update.py validate-modules:parameter-type-not-in-doc # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_update.py validate-modules:undocumented-parameter # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_update.py validate-modules:doc-elements-mismatch # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
-plugins/modules/cmci_update.py validate-modules:doc-required-mismatch # We have a complex_filter DSL as part of our plugin YAML.  The same config is accepted 4 levels deep.  We only include the (quite long) documentation for this at the highest level, which causes this error
+plugins/modules/cmci_update.py validate-modules:missing-gplv3-license # Licence is Apache-2.0