new: Bring Image-related functionality to API parity (#226)

This change adds missing fields to the `Image` object and adds two new
functions:
- `client.image_create_upload(...)` - Creates/returns and image and the
corresponding upload URL
- `client.image_upload(...)` - Takes a BinaryIO stream, creates an
image, and uploads to the image.

These are all of the necessary changes to bring image-related
functionality to API parity.

Author: lgarber-akamai

linode_api4/linode_client.py

@@ -5,6 +5,7 @@
 import os
 import time
 from datetime import datetime
+from typing import Tuple, BinaryIO
 
 import pkg_resources
 import requests
@@ -15,6 +16,7 @@
 
 from .common import SSH_KEY_TYPES, load_and_validate_keys
 from .paginated_list import PaginatedList
+from .util import drop_null_keys
 
 package_version = pkg_resources.require("linode_api4")[0].version
 
@@ -1618,6 +1620,67 @@ def image_create(self, disk, label=None, description=None):
 
         return Image(self, result['id'], result)
 
+    def image_create_upload(self, label: str, region: str, description: str=None) -> Tuple[Image, str]:
+        """
+        Creates a new Image and returns the corresponding upload URL.
+        https://www.linode.com/docs/api/images/#image-upload
+
+        :param label: The label of the Image to create.
+        :type label: str
+        :param region: The region to upload to. Once the image has been created, it can be used in any region.
+        :type region: str
+        :param description: The description for the new Image.
+        :type description: str
+
+        :returns: A tuple containing the new image and the image upload URL.
+        :rtype: (Image, str)
+        """
+        params = {
+            "label": label,
+            "region": region,
+            "description": description
+        }
+
+        result = self.post("/images/upload", data=drop_null_keys(params))
+
+        if "image" not in result:
+            raise UnexpectedResponseError('Unexpected response when creating an '
+                                          'Image upload URL')
+
+        result_image = result["image"]
+        result_url = result["upload_to"]
+
+        return Image(self, result_image["id"], result_image), result_url
+
+    def image_upload(self, label: str, region: str, file: BinaryIO, description: str=None) -> Image:
+        """
+        Creates and uploads a new image.
+        https://www.linode.com/docs/api/images/#image-upload
+
+        :param label: The label of the Image to create.
+        :type label: str
+        :param region: The region to upload to. Once the image has been created, it can be used in any region.
+        :type region: str
+        :param file: The BinaryIO object to upload to the image. This is generally obtained from open("myfile", "rb").
+        :param description: The description for the new Image.
+        :type description: str
+
+        :returns: The resulting image.
+        :rtype: Image
+        """
+
+        image, url = self.image_create_upload(label, region, description=description)
+
+        requests.put(
+            url,
+            headers={"Content-Type": "application/octet-stream"},
+            data=file,
+        )
+
+        image._api_get()
+
+        return image
+
     def domains(self, *filters):
         """
         Retrieves all of the Domains the acting user has access to.

linode_api4/objects/image.py

@@ -11,9 +11,12 @@ class Image(Base):
         "id": Property(identifier=True),
         "label": Property(mutable=True),
         "description": Property(mutable=True),
+        "eol": Property(is_datetime=True),
+        "expiry": Property(is_datetime=True),
         "status": Property(),
         "created": Property(is_datetime=True),
         "created_by": Property(),
+        "updated": Property(is_datetime=True),
         "type": Property(),
         "is_public": Property(),
         "vendor": Property(),

linode_api4/util.py

@@ -0,0 +1,24 @@
+"""
+Contains various utility functions.
+"""
+from typing import Dict, Any
+
+
+def drop_null_keys(data: Dict[Any, Any], recursive=True) -> Dict[Any, Any]:
+    """
+    Traverses a dict and drops any keys that map to None values.
+    """
+
+    if not recursive:
+        return {k: v for k, v in data.items() if v is not None}
+
+    def recursive_helper(value: Any) -> Any:
+        if isinstance(value, dict):
+            return {k: recursive_helper(v) for k, v in value.items() if v is not None}
+
+        if isinstance(value, list):
+            return [recursive_helper(v) for v in value]
+
+        return value
+
+    return recursive_helper(data)

requirements-dev.txt

@@ -0,0 +1,5 @@
+mock>=5.0.0
+tox>=4.4.0
+Sphinx>=6.0.0
+sphinx-autobuild>=2021.3.14
+sphinxcontrib-fulltoc>=1.2.0

requirements.txt

@@ -1,2 +1,3 @@
 httplib2
 enum34
+requests

test/fixtures/images.json

@@ -14,7 +14,10 @@
           "size": 1100,
           "is_public": true,
           "type": "manual",
-          "vendor": "Debian"
+          "vendor": "Debian",
+          "eol": "2026-07-01T04:00:00",
+          "expiry": "2026-08-01T04:00:00",
+          "updated": "2020-07-01T04:00:00"
         },
         {
           "created": "2017-01-01T00:01:01",
@@ -27,7 +30,10 @@
           "size": 1500,
           "is_public": true,
           "type": "manual",
-          "vendor": "Ubuntu"
+          "vendor": "Ubuntu",
+          "eol": "2026-07-01T04:00:00",
+          "expiry": "2026-08-01T04:00:00",
+          "updated": "2020-07-01T04:00:00"
         },
         {
           "created": "2017-01-01T00:01:01",
@@ -40,7 +46,10 @@
           "size": 1500,
           "is_public": true,
           "type": "manual",
-          "vendor": "Fedora"
+          "vendor": "Fedora",
+          "eol": "2026-07-01T04:00:00",
+          "expiry": "2026-08-01T04:00:00",
+          "updated": "2020-07-01T04:00:00"
         },
         {
           "created": "2017-08-20T14:01:01",
@@ -53,7 +62,10 @@
           "size": 650,
           "is_public": false,
           "type": "manual",
-          "vendor": null
+          "vendor": null,
+          "eol": "2026-07-01T04:00:00",
+          "expiry": "2026-08-01T04:00:00",
+          "updated": "2020-07-01T04:00:00"
         }
     ]
 }

test/fixtures/images_private_1337.json

@@ -0,0 +1,16 @@
+{
+    "created": "2021-08-14T22:44:02",
+    "created_by": "someone",
+    "deprecated": false,
+    "description": "very real image upload.",
+    "eol": "2026-07-01T04:00:00",
+    "expiry": null,
+    "id": "private/1337",
+    "is_public": false,
+    "label": "Realest Image Upload",
+    "size": 2500,
+    "status": "available",
+    "type": "manual",
+    "updated": "2021-08-14T22:44:02",
+    "vendor": "Debian"
+}

test/fixtures/images_upload.json

@@ -0,0 +1,19 @@
+{
+    "image": {
+        "created": "2021-08-14T22:44:02",
+        "created_by": "someone",
+        "deprecated": false,
+        "description": "very real image upload.",
+        "eol": "2026-07-01T04:00:00",
+        "expiry": null,
+        "id": "private/1337",
+        "is_public": false,
+        "label": "Realest Image Upload",
+        "size": 2500,
+        "status": "available",
+        "type": "manual",
+        "updated": "2021-08-14T22:44:02",
+        "vendor": "Debian"
+    },
+    "upload_to": "https://linode.com/"
+}

test/objects/image_test.py

@@ -1,8 +1,20 @@
+from datetime import datetime
+from io import BytesIO
+from typing import Any, BinaryIO
+from unittest.mock import patch
+
 from test.base import ClientBaseCase
 
 from linode_api4.objects import Image
 
 
+# A minimal gzipped image that will be accepted by the API
+TEST_IMAGE_CONTENT = (
+    b"\x1F\x8B\x08\x08\xBD\x5C\x91\x60\x00\x03\x74\x65\x73\x74\x2E\x69"
+    b"\x6D\x67\x00\x03\x00\x00\x00\x00\x00\x00\x00\x00\x00"
+)
+
+
 class ImageTest(ClientBaseCase):
     """
     Tests methods of the Image class
@@ -24,3 +36,65 @@ def test_get_image(self):
         self.assertEqual(image.type, "manual")
         self.assertEqual(image.created_by, "linode")
         self.assertEqual(image.size, 1100)
+
+        self.assertEqual(image.eol, datetime(
+            year=2026, month=7, day=1, hour=4, minute=0, second=0
+        ))
+
+        self.assertEqual(image.expiry, datetime(
+            year=2026, month=8, day=1, hour=4, minute=0, second=0
+        ))
+
+        self.assertEqual(image.updated, datetime(
+            year=2020, month=7, day=1, hour=4, minute=0, second=0
+        ))
+
+    def test_image_create_upload(self):
+        """
+        Test that an image upload URL can be created successfully.
+        """
+
+        with self.mock_post("/images/upload") as m:
+            image, url = self.client.image_create_upload(
+                "Realest Image Upload",
+                "us-southeast",
+                description="very real image upload.",
+            )
+
+            self.assertEqual(m.call_url, "/images/upload")
+            self.assertEqual(m.method, "post")
+            self.assertEqual(
+                m.call_data,
+                {
+                    "label": "Realest Image Upload",
+                    "region": "us-southeast",
+                    "description": "very real image upload."
+                }
+            )
+
+        self.assertEqual(image.id, "private/1337")
+        self.assertEqual(image.label, "Realest Image Upload")
+        self.assertEqual(image.description, "very real image upload.")
+
+        self.assertEqual(url, "https://linode.com/")
+
+    def test_image_upload(self):
+        """
+        Test that an image can be uploaded.
+        """
+
+        def put_mock(url: str, data: BinaryIO = None, **kwargs):
+            self.assertEqual(url, "https://linode.com/")
+            self.assertEqual(data.read(), TEST_IMAGE_CONTENT)
+
+        with patch("requests.put", put_mock), self.mock_post("/images/upload"):
+            image = self.client.image_upload(
+                "Realest Image Upload",
+                "us-southeast",
+                BytesIO(TEST_IMAGE_CONTENT),
+                description="very real image upload.",
+            )
+
+        self.assertEqual(image.id, "private/1337")
+        self.assertEqual(image.label, "Realest Image Upload")
+        self.assertEqual(image.description, "very real image upload.")

test/util_test.py

@@ -0,0 +1,66 @@
+import unittest
+
+from linode_api4.util import drop_null_keys
+
+
+class UtilTest(unittest.TestCase):
+    """
+    Tests for utility functions.
+    """
+
+    def test_drop_null_keys_nonrecursive(self):
+        """
+        Tests whether a non-recursive drop_null_keys call works as expected.
+        """
+        value = {
+            "foo": "bar",
+            "test": None,
+            "cool": {
+                "test": "bar",
+                "cool": None,
+            }
+        }
+
+        expected_output = {
+            "foo": "bar",
+            "cool": {
+                "test": "bar",
+                "cool": None
+            }
+        }
+
+        assert drop_null_keys(value, recursive=False) == expected_output
+
+    def test_drop_null_keys_recursive(self):
+        """
+        Tests whether a recursive drop_null_keys call works as expected.
+        """
+
+        value = {
+            "foo": "bar",
+            "test": None,
+            "cool": {
+                "test": "bar",
+                "cool": None,
+                "list": [
+                    {
+                        "foo": "bar",
+                        "test": None
+                    }
+                ]
+            }
+        }
+
+        expected_output = {
+            "foo": "bar",
+            "cool": {
+                "test": "bar",
+                "list": [
+                    {
+                        "foo": "bar",
+                    }
+                ]
+            }
+        }
+
+        assert drop_null_keys(value) == expected_output