new: Add support for explicit nullable arguments (#421)

## 📝 Description

This change allows users to specify `null` as a value for fields that
are marked as `nullable` in the API spec. This is useful for situations
where the API may have certain functionality tied to having a certain
value be explicitly `null` (e.g. RDNS resets)

e.g.
```bash
linode-cli networking ip-update --rdns null 127.0.0.1
```

**NOTE: This will need to be partially reworked after the spec parser
refactor, but the change should be relatively straightforward.**

Resolves #266 

## ✔️ How to Test

```
make testunit
```

Author: lgarber-akamai

linodecli/api_request.py

@@ -14,7 +14,7 @@
 
 from linodecli.helpers import API_CA_PATH
 
-from .baked.operation import OpenAPIOperation
+from .baked.operation import ExplicitNullValue, OpenAPIOperation
 from .helpers import handle_url_overrides
 
 
@@ -199,7 +199,19 @@ def _build_request_body(ctx, operation, parsed_args) -> Optional[str]:
             parsed_args, operation.allowed_defaults, operation.action
         )
 
-    to_json = {k: v for k, v in vars(parsed_args).items() if v is not None}
+    to_json = {}
+
+    for k, v in vars(parsed_args).items():
+        # Skip null values
+        if v is None:
+            continue
+
+        # Explicitly include ExplicitNullValues
+        if isinstance(v, ExplicitNullValue):
+            to_json[k] = None
+            continue
+
+        to_json[k] = v
 
     expanded_json = {}
 

linodecli/baked/operation.py

@@ -8,6 +8,7 @@
 import re
 from getpass import getpass
 from os import environ, path
+from typing import List, Tuple
 
 from linodecli.baked.request import OpenAPIFilteringRequest, OpenAPIRequest
 from linodecli.baked.response import OpenAPIResponse
@@ -49,6 +50,31 @@ def parse_dict(value):
 }
 
 
+# pylint: disable=too-few-public-methods
+class ExplicitNullValue:
+    """
+    A special type class used to explicitly pass null values to the API.
+    """
+
+
+def wrap_parse_nullable_value(arg_type):
+    """
+    A helper function to parse `null` as None for nullable CLI args.
+    This is intended to be called and passed to the `type=` kwarg for ArgumentParser.add_argument.
+    """
+
+    def type_func(value):
+        if not value:
+            return None
+
+        if value == "null":
+            return ExplicitNullValue()
+
+        return TYPES[arg_type](value)
+
+    return type_func
+
+
 class ListArgumentAction(argparse.Action):
     """
     This action is intended to be used only with list arguments.
@@ -294,93 +320,93 @@ def process_response_json(
         json = self.response_model.fix_json(json)
         handler.print(self.response_model, json)
 
-    def parse_args(
-        self, args
-    ):  # pylint: disable=too-many-locals,too-many-branches,too-many-statements
-        """
-        Given sys.argv after the operation name, parse args based on the params
-        and args of this operation
-        """
-        list_items = []
+    def _add_args_filter(self, parser):
+        # build args for filtering
+        for attr in self.response_model.attrs:
+            if not attr.filterable:
+                continue
+
+            expected_type = TYPES[attr.datatype]
+            if expected_type == list:
+                parser.add_argument(
+                    "--" + attr.name,
+                    type=TYPES[attr.item_type],
+                    metavar=attr.name,
+                    action="append",
+                    nargs="?",
+                )
+            else:
+                parser.add_argument(
+                    "--" + attr.name,
+                    type=expected_type,
+                    metavar=attr.name,
+                )
 
-        #  build an argparse
-        parser = argparse.ArgumentParser(
-            prog=f"linode-cli {self.command} {self.action}",
-            description=self.summary,
-        )
-        for param in self.params:
-            parser.add_argument(
-                param.name, metavar=param.name, type=TYPES[param.type]
-            )
+    def _add_args_post_put(self, parser) -> List[Tuple[str, str]]:
+        list_items = []
 
-        if self.method == "get":
-            # build args for filtering
-            for attr in self.response_model.attrs:
-                if attr.filterable:
-                    expected_type = TYPES[attr.datatype]
-                    if expected_type == list:
-                        parser.add_argument(
-                            "--" + attr.name,
-                            type=TYPES[attr.item_type],
-                            metavar=attr.name,
-                            action="append",
-                            nargs="?",
-                        )
-                    else:
-                        parser.add_argument(
-                            "--" + attr.name,
-                            type=expected_type,
-                            metavar=attr.name,
-                        )
+        # build args for body JSON
+        for arg in self.args:
+            if arg.read_only:
+                continue
 
-        elif self.method in ("post", "put"):
-            # build args for body JSON
-            for arg in self.args:
-                if arg.read_only:
-                    continue
-                if arg.datatype == "array":
-                    # special handling for input arrays
+            arg_type = (
+                arg.item_type if arg.datatype == "array" else arg.datatype
+            )
+            arg_type_handler = TYPES[arg_type]
+
+            if arg.nullable:
+                arg_type_handler = wrap_parse_nullable_value(arg_type)
+
+            if arg.datatype == "array":
+                # special handling for input arrays
+                parser.add_argument(
+                    "--" + arg.path,
+                    metavar=arg.name,
+                    action="append",
+                    type=arg_type_handler,
+                )
+            elif arg.list_item:
+                parser.add_argument(
+                    "--" + arg.path,
+                    metavar=arg.name,
+                    action=ListArgumentAction,
+                    type=arg_type_handler,
+                )
+                list_items.append((arg.path, arg.prefix))
+            else:
+                if arg.datatype == "string" and arg.format == "password":
+                    # special case - password input
                     parser.add_argument(
                         "--" + arg.path,
-                        metavar=arg.name,
-                        action="append",
-                        type=TYPES[arg.item_type],
+                        nargs="?",
+                        action=PasswordPromptAction,
                     )
-                elif arg.list_item:
+                elif arg.datatype == "string" and arg.format in (
+                    "file",
+                    "ssl-cert",
+                    "ssl-key",
+                ):
                     parser.add_argument(
                         "--" + arg.path,
                         metavar=arg.name,
-                        action=ListArgumentAction,
-                        type=TYPES[arg.datatype],
+                        action=OptionalFromFileAction,
+                        type=arg_type_handler,
                     )
-                    list_items.append((arg.path, arg.prefix))
                 else:
-                    if arg.datatype == "string" and arg.format == "password":
-                        # special case - password input
-                        parser.add_argument(
-                            "--" + arg.path,
-                            nargs="?",
-                            action=PasswordPromptAction,
-                        )
-                    elif arg.datatype == "string" and arg.format in (
-                        "file",
-                        "ssl-cert",
-                        "ssl-key",
-                    ):
-                        parser.add_argument(
-                            "--" + arg.path,
-                            metavar=arg.name,
-                            action=OptionalFromFileAction,
-                            type=TYPES[arg.datatype],
-                        )
-                    else:
-                        parser.add_argument(
-                            "--" + arg.path,
-                            metavar=arg.name,
-                            type=TYPES[arg.datatype],
-                        )
-
-        parsed = parser.parse_args(args)
+                    parser.add_argument(
+                        "--" + arg.path,
+                        metavar=arg.name,
+                        type=arg_type_handler,
+                    )
+
+        return list_items
+
+    @staticmethod
+    def _handle_list_items(
+        list_items,
+        parsed,
+    ):  # pylint: disable=too-many-locals,too-many-branches,too-many-statements
         lists = {}
         # group list items as expected
         for arg_name, list_name in list_items:
@@ -441,3 +467,28 @@ def parse_args(
             parsed = argparse.Namespace(**parsed)
 
         return parsed
+
+    def parse_args(self, args):
+        """
+        Given sys.argv after the operation name, parse args based on the params
+        and args of this operation
+        """
+
+        #  build an argparse
+        parser = argparse.ArgumentParser(
+            prog=f"linode-cli {self.command} {self.action}",
+            description=self.summary,
+        )
+        for param in self.params:
+            parser.add_argument(
+                param.name, metavar=param.name, type=TYPES[param.type]
+            )
+
+        list_items = []
+
+        if self.method == "get":
+            self._add_args_filter(parser)
+        elif self.method in ("post", "put"):
+            list_items = self._add_args_post_put(parser)
+
+        return self._handle_list_items(list_items, parser.parse_args(args))

linodecli/baked/request.py

@@ -65,6 +65,9 @@ def __init__(
         #: The path of the path element in the schema.
         self.prefix = prefix
 
+        #: Whether null is an acceptable value for this attribute
+        self.nullable = schema.nullable
+
         # handle the type for list values if this is an array
         if self.datatype == "array" and schema.items:
             self.item_type = schema.items.type

tests/fixtures/api_request_test_foobar_post.yaml

@@ -85,3 +85,15 @@ components:
           x-linode-filterable: true
           type: string
           description: The region
+        nullable_int:
+          type: integer
+          nullable: true
+          description: An arbitrary nullable int
+        nullable_string:
+          type: string
+          nullable: true
+          description: An arbitrary nullable string
+        nullable_float:
+          type: number
+          nullable: true
+          description: An arbitrary nullable float

tests/unit/test_api_request.py

@@ -11,6 +11,7 @@
 import requests
 
 from linodecli import api_request
+from linodecli.baked.operation import ExplicitNullValue
 
 
 class TestAPIRequest:
@@ -56,17 +57,74 @@ def test_request_debug_info(self):
     def test_build_request_body(self, mock_cli, create_operation):
         create_operation.allowed_defaults = ["region", "engine"]
         create_operation.action = "mysql-create"
+
         result = api_request._build_request_body(
             mock_cli,
             create_operation,
-            SimpleNamespace(generic_arg="foo", region=None, engine=None),
+            SimpleNamespace(
+                generic_arg="foo",
+                region=None,
+                engine=None,
+            ),
+        )
+        assert (
+            json.dumps(
+                {
+                    "generic_arg": "foo",
+                    "region": "us-southeast",
+                    "engine": "mysql/8.0.26",
+                }
+            )
+            == result
+        )
+
+    def test_build_request_body_null_field(self, mock_cli, create_operation):
+        create_operation.allowed_defaults = ["region", "engine"]
+        create_operation.action = "mysql-create"
+        result = api_request._build_request_body(
+            mock_cli,
+            create_operation,
+            SimpleNamespace(
+                generic_arg="foo",
+                region=None,
+                engine=None,
+                nullable_int=ExplicitNullValue(),
+            ),
+        )
+        assert (
+            json.dumps(
+                {
+                    "generic_arg": "foo",
+                    "region": "us-southeast",
+                    "engine": "mysql/8.0.26",
+                    "nullable_int": None,
+                }
+            )
+            == result
+        )
+
+    def test_build_request_body_non_null_field(
+        self, mock_cli, create_operation
+    ):
+        create_operation.allowed_defaults = ["region", "engine"]
+        create_operation.action = "mysql-create"
+        result = api_request._build_request_body(
+            mock_cli,
+            create_operation,
+            SimpleNamespace(
+                generic_arg="foo",
+                region=None,
+                engine=None,
+                nullable_int=12345,
+            ),
         )
         assert (
             json.dumps(
                 {
                     "generic_arg": "foo",
                     "region": "us-southeast",
                     "engine": "mysql/8.0.26",
+                    "nullable_int": 12345,
                 }
             )
             == result