Merge pull request #1238 from allmightyspiff/advancedFilters

Advanced filters

Author: allmightyspiff

SoftLayer/CLI/call_api.py

@@ -1,4 +1,6 @@
 """Call arbitrary API endpoints."""
+import json
+
 import click
 
 from SoftLayer.CLI import environment
@@ -27,8 +29,7 @@ def _build_filters(_filters):
             if len(top_parts) == 2:
                 break
         else:
-            raise exceptions.CLIAbort('Failed to find valid operation for: %s'
-                                      % _filter)
+            raise exceptions.CLIAbort('Failed to find valid operation for: %s' % _filter)
 
         key, value = top_parts
         current = root
@@ -68,25 +69,60 @@ def _build_python_example(args, kwargs):
     return call_str
 
 
+def _validate_filter(ctx, param, value):  # pylint: disable=unused-argument
+    """Validates a JSON style object filter"""
+    _filter = None
+    if value:
+        try:
+            _filter = json.loads(value)
+            if not isinstance(_filter, dict):
+                raise exceptions.CLIAbort("\"{}\" should be a JSON object, but is a {} instead.".
+                                          format(_filter, type(_filter)))
+        except json.JSONDecodeError as error:
+            raise exceptions.CLIAbort("\"{}\" is not valid JSON. {}".format(value, error))
+
+    return _filter
+
+
+def _validate_parameters(ctx, param, value):  # pylint: disable=unused-argument
+    """Checks if value is a JSON string, and converts it to a datastructure if that is true"""
+
+    validated_values = []
+    for parameter in value:
+        if isinstance(parameter, str):
+            # looks like a JSON string...
+            if '{' in parameter or '[' in parameter:
+                try:
+                    parameter = json.loads(parameter)
+                except json.JSONDecodeError as error:
+                    click.secho("{} looked like json, but was invalid, passing to API as is. {}".
+                                format(parameter, error), fg='red')
+        validated_values.append(parameter)
+    return validated_values
+
+
 @click.command('call', short_help="Call arbitrary API endpoints.")
 @click.argument('service')
 @click.argument('method')
-@click.argument('parameters', nargs=-1)
+@click.argument('parameters', nargs=-1, callback=_validate_parameters)
 @click.option('--id', '_id', help="Init parameter")
 @helpers.multi_option('--filter', '-f', '_filters',
-                      help="Object filters. This should be of the form: "
-                      "'property=value' or 'nested.property=value'. Complex "
-                      "filters like betweenDate are not currently supported.")
+                      help="Object filters. This should be of the form: 'property=value' or 'nested.property=value'."
+                           "Complex filters should use --json-filter.")
 @click.option('--mask', help="String-based object mask")
 @click.option('--limit', type=click.INT, help="Result limit")
 @click.option('--offset', type=click.INT, help="Result offset")
 @click.option('--output-python / --no-output-python',
               help="Show python example code instead of executing the call")
+@click.option('--json-filter', callback=_validate_filter,
+              help="A JSON string to be passed in as the object filter to the API call."
+                   "Remember to use double quotes (\") for variable names. Can NOT be used with --filter.")
 @environment.pass_env
 def cli(env, service, method, parameters, _id, _filters, mask, limit, offset,
-        output_python=False):
+        output_python=False, json_filter=None):
     """Call arbitrary API endpoints with the given SERVICE and METHOD.
 
+    For parameters that require a datatype, use a JSON string for that parameter.
     Example::
 
         slcli call-api Account getObject
@@ -100,12 +136,23 @@ def cli(env, service, method, parameters, _id, _filters, mask, limit, offset,
             --mask=id,hostname,datacenter.name,maxCpu
         slcli call-api Account getVirtualGuests \\
             -f 'virtualGuests.datacenter.name IN dal05,sng01'
+        slcli call-api Account getVirtualGuests \\
+            --json-filter  '{"virtualGuests":{"hostname": {"operation": "^= test"}}}' --limit=10
+        slcli -v call-api SoftLayer_User_Customer addBulkPortalPermission --id=1234567 \\
+            '[{"keyName": "NETWORK_MESSAGE_DELIVERY_MANAGE"}]'
     """
 
+    if _filters and json_filter:
+        raise exceptions.CLIAbort("--filter and --json-filter cannot be used together.")
+
+    object_filter = _build_filters(_filters)
+    if json_filter:
+        object_filter.update(json_filter)
+
     args = [service, method] + list(parameters)
     kwargs = {
         'id': _id,
-        'filter': _build_filters(_filters),
+        'filter': object_filter,
         'mask': mask,
         'limit': limit,
         'offset': offset,

docs/cli/commands.rst

@@ -3,6 +3,14 @@
 Call API
 ========
 
+This function allows you to easily call any API. The format is
+
+`slcli call-api SoftLayer_Service method param1 param2 --id=1234 --mask="mask[id,name]"`
+
+Parameters should be in the order they are presented on sldn.softlayer.com. 
+Any complex parameters (those that link to other datatypes) should be presented as JSON strings. They need to be enclosed in single quotes (`'`), and variables and strings enclosed in double quotes (`"`).
+
+For example: `{"hostname":"test",ssh_keys:[{"id":1234}]}`
 
 .. click:: SoftLayer.CLI.call_api:cli
     :prog: call-api

tests/CLI/modules/call_api_tests.py

@@ -158,8 +158,7 @@ def test_object_table(self):
                              'None': None,
                              'Bool': True}
 
-        result = self.run_command(['call-api', 'Service', 'method'],
-                                  fmt='table')
+        result = self.run_command(['call-api', 'Service', 'method'], fmt='table')
 
         self.assert_no_fail(result)
         # NOTE(kmcdonald): Order is not guaranteed
@@ -179,8 +178,7 @@ def test_object_nested(self):
         result = self.run_command(['call-api', 'Service', 'method'])
 
         self.assert_no_fail(result)
-        self.assertEqual(json.loads(result.output),
-                         {'this': {'is': [{'pretty': 'nested'}]}})
+        self.assertEqual(json.loads(result.output),  {'this': {'is': [{'pretty': 'nested'}]}})
 
     def test_list(self):
         mock = self.set_mock('SoftLayer_Service', 'method')
@@ -208,8 +206,7 @@ def test_list_table(self):
                               'None': None,
                               'Bool': True}]
 
-        result = self.run_command(['call-api', 'Service', 'method'],
-                                  fmt='table')
+        result = self.run_command(['call-api', 'Service', 'method'], fmt='table')
 
         self.assert_no_fail(result)
         self.assertEqual(result.output,
@@ -224,12 +221,10 @@ def test_parameters(self):
         mock = self.set_mock('SoftLayer_Service', 'method')
         mock.return_value = {}
 
-        result = self.run_command(['call-api', 'Service', 'method',
-                                   'arg1', '1234'])
+        result = self.run_command(['call-api', 'Service', 'method', 'arg1', '1234'])
 
         self.assert_no_fail(result)
-        self.assert_called_with('SoftLayer_Service', 'method',
-                                args=('arg1', '1234'))
+        self.assert_called_with('SoftLayer_Service', 'method', args=('arg1', '1234'))
 
     def test_fixture_not_implemented(self):
         service = 'SoftLayer_Test'
@@ -264,3 +259,42 @@ def test_fixture_exception(self):
         self.assertIsInstance(result.exception, SoftLayerAPIError)
         output = '%s::%s fixture is not implemented' % (call_service, call_method)
         self.assertIn(output, result.exception.faultString)
+
+    def test_json_filter_validation(self):
+        json_filter = '{"test":"something"}'
+        result = call_api._validate_filter(None, None, json_filter)
+        self.assertEqual(result['test'], 'something')
+
+        # Valid JSON, but we expect objects, not simple types
+        with pytest.raises(exceptions.CLIAbort):
+            call_api._validate_filter(None, None, '"test"')
+
+        # Invalid JSON
+        with pytest.raises(exceptions.CLIAbort):
+            call_api._validate_filter(None, None, 'test')
+
+        # Empty Request
+        result = call_api._validate_filter(None, None, None)
+        self.assertEqual(None, result)
+
+    def test_json_parameters_validation(self):
+        json_params = ('{"test":"something"}', 'String', 1234, '[{"a":"b"}]', '{funky non [ Json')
+        result = call_api._validate_parameters(None, None, json_params)
+        self.assertEqual(result[0], {"test": "something"})
+        self.assertEqual(result[1], "String")
+        self.assertEqual(result[2], 1234)
+        self.assertEqual(result[3], [{"a": "b"}])
+        self.assertEqual(result[4], "{funky non [ Json")
+
+    def test_filter_with_filter(self):
+        result = self.run_command(['call-api', 'Account', 'getObject', '--filter=nested.property=5432',
+                                   '--json-filter={"test":"something"}'])
+        self.assertEqual(2, result.exit_code)
+        self.assertEqual(result.exception.message, "--filter and --json-filter cannot be used together.")
+        self.assertIsInstance(result.exception, exceptions.CLIAbort)
+
+    def test_json_filter(self):
+        pass
+        result = self.run_command(['call-api', 'Account', 'getObject', '--json-filter={"test":"something"}'])
+        self.assert_no_fail(result)
+        self.assert_called_with('SoftLayer_Account', 'getObject', filter={"test": "something"})