Kaggle CLI: Dataset image upload via datasets metadata --update (#959)

Changes:
- Adds functionality to specify an image file on disk to upload and set
for the dataset, using default crops.
- Updates documentation about new parameters

Local testing:
- [screen](http://screen/78g4ZpYK96QUUh8)
-
[screencast](https://screencast.googleplex.com/cast/NDc2NjU5MjU3ODYxNzM0NHwwMmFjMTc4Yy1jZg)

http://b/500108129

Author: jmasukawa

docs/datasets_metadata.md

@@ -54,6 +54,7 @@ Here's an example containing file metadata:
   ],
   "expectedUpdateFrequency": "monthly",
   "userSpecifiedSources": "World Bank and OECD ([link](http://data.worldbank.org/indicator/NY.GDP.MKTP.CD))",
+  "image": "relative/path/to/new/image.png"
 }
 ```
 
@@ -90,6 +91,10 @@ The following metadata is currently supported:
         * `title`: Field description
         * `type`: Field type. A best-effort list of types will be kept at the bottom of this page, but new types may be added that are not documented here.
   * `keywords`: Contains an array of strings that correspond to an existing tag on Kaggle.  If a specified tag doesn't exist, the upload will continue, but that specific tag won't be added.  
+* `kaggle datasets metadata --update` (update metadata for an existing Dataset) supports all fields mentioned above for `kaggle datasets version`, and additionally:
+  * `expectedUpdateFrequency`: How often you expect to update your dataset with new versions. See [section below](#expected-update-frequencies) for possible values.
+  * `userSpecifiedSources`: An explanation of the source(s) of your dataset. Most basic markdown features are supported for this string.
+  * `image`: A relative file path to a new image file you want to use for your dataset. The path should be relative to the location of the dataset-metadata.json file. See [section below](#images) for more specifics about file types and expected image size.
 
 We will add further metadata processing in upcoming versions of the API.
 
@@ -170,5 +175,45 @@ You can specify the following values for `expectedUpdateFrequency`:
 * `daily`
 * `hourly`
 
-## Sources
-You can report your dataset sources in a markdown string for `userSpecifiedSources`. Most basic markdown features are supported.
+## Images
+You can update your dataset image by providing a relative path from your `datasets-metadata.json` to an image file, using the `image` property.
+
+For example, if your metadata file and image are located at:
+- `/some/path/dataset-metadata.json`
+- `/some/path/image.png`
+
+This property should be specified as:
+```
+"image": "image.png"
+```
+
+If instead, your files were located at:
+- `/some/path/dataset-metadata.json`
+- `/some/path/alternative/path/to/other-image.jpg`
+
+This property should be specified as:
+```
+"image": "alternative/path/to/other-image.jpg"
+```
+
+### Supported image file types and expected dimensions
+
+The following file types are supported:
+
+* `.png`
+* `.jpg`
+* `.jpeg`
+* `.webp`
+
+The image needs to have a minimum width of 560px and a minimum height of 280px.
+
+The same image file will be used for two different crops:
+
+- Header, 2:1 ratio
+  - Crop rectangle: width: 560px, height: 280px, top: 0, left: 0
+  - For an image with dimensions 560px x 280px, this will be the entire rectangular image.
+- Thumbnail, 1:1 ratio
+  - Crop rectangle: width: 280px, height: 280px, top: 0, left: 140px
+  - For an image with dimensions 560px x 280px, this will be a centered 280px square.
+
+While you can upload a larger image than 560px x 280px, the crops as specified above will be applied, and this may not look good. These crops can always be edited in the UI on kaggle.com on the settings page for your dataset.

src/kaggle/api/kaggle_api_extended.py

@@ -25,6 +25,7 @@
 import json  # Needed by mypy.
 import logging
 import os
+from pathlib import Path
 
 import re  # Needed by mypy.
 import shutil
@@ -38,6 +39,7 @@
 from random import random
 
 import bleach
+import mimetypes
 import requests
 import urllib3.exceptions as urllib3_exceptions
 from requests import RequestException
@@ -82,6 +84,8 @@
     SubmissionSortBy,
 )
 
+from kagglesdk.common.types.cropped_image_upload import CroppedImageUpload, CroppedImageRectangle
+
 from kagglesdk.datasets.types.dataset_api_service import (
     ApiListDatasetsRequest,
     ApiListDatasetFilesRequest,
@@ -639,7 +643,6 @@ def with_retry(
         retry_multiplier: float = 1.7,
         randomness_factor: float = 0.5,
     ) -> Callable[[KaggleObject], KaggleObject]:
-
         def retriable_func(*args):
             for i in range(1, max_retries + 1):
                 try:
@@ -1928,6 +1931,13 @@ def dataset_metadata_update(self, dataset, path):
             expected_update_frequency = metadata.get("expectedUpdateFrequency")
             if expected_update_frequency:
                 update_settings.expected_update_frequency = expected_update_frequency
+
+            effective_relative_path_to_image = metadata.get("image")
+            if effective_relative_path_to_image:
+                cropped_image_upload = self._upload_dataset_image_file(effective_path, effective_relative_path_to_image)
+                if cropped_image_upload:
+                    update_settings.image = cropped_image_upload
+
             request = ApiUpdateDatasetMetadataRequest()
             request.owner_slug = owner_slug
             request.dataset_slug = dataset_slug
@@ -1938,6 +1948,53 @@ def dataset_metadata_update(self, dataset, path):
                     [print(error_message) for error_message in response.errors]
                     exit(1)
 
+    def _upload_dataset_image_file(
+        self, metadata_file_path, relative_image_file_path, quiet=False
+    ) -> CroppedImageUpload:
+        image_full_path = os.path.join(metadata_file_path, relative_image_file_path)
+        ext = Path(image_full_path).suffix
+        if ext not in [".jpg", ".jpeg", ".png", ".webp"]:
+            raise ValueError("Image file requires an extension of .jpg, .jpeg, .png, or .webp: %s" % image_full_path)
+
+        if not os.path.isfile(image_full_path):
+            raise ValueError("Image file was not found: %s" % image_full_path)
+
+        file_name = os.path.basename(image_full_path)
+        # Best guess for MIME type based on filename is ok, given we don't trust MIME type in the backend.
+        content_type, _ = mimetypes.guess_type(file_name)
+        with ResumableUploadContext() as upload_context:
+            upload_file = self._upload_file(
+                file_name,
+                image_full_path,
+                ApiBlobType.INBOX,
+                upload_context,
+                quiet,
+                resources=None,
+                content_type=content_type,
+            )
+            if not upload_file:
+                raise ValueError("Error uploading image file: %s" % image_full_path)
+
+            header_image_rect = CroppedImageRectangle()
+            header_image_rect.title = "cover image"
+            header_image_rect.top = 0
+            header_image_rect.left = 0
+            header_image_rect.width = 560
+            header_image_rect.height = 280
+
+            thumbnail_rect = CroppedImageRectangle()
+            thumbnail_rect.title = "thumbnail"
+            thumbnail_rect.top = 0
+            thumbnail_rect.left = 140
+            thumbnail_rect.width = 280
+            thumbnail_rect.height = 280
+
+            cropped_image_upload = CroppedImageUpload()
+            cropped_image_upload.token = upload_file.token
+            cropped_image_upload.crop_rectangles = [header_image_rect, thumbnail_rect]
+
+            return cropped_image_upload
+
     @staticmethod
     def _new_license(name):
         l = SettingsLicense()
@@ -2244,7 +2301,12 @@ def dataset_download_cli(
             self.dataset_download_file(dataset, file_name, path=path, force=force, quiet=quiet, licenses=licenses)
 
     def _upload_blob(
-        self, path: str, quiet: bool, blob_type: ApiBlobType, upload_context: ResumableUploadContext
+        self,
+        path: str,
+        quiet: bool,
+        blob_type: ApiBlobType,
+        upload_context: ResumableUploadContext,
+        content_type: Optional[str] = None,
     ) -> ResumableFileUpload | str | None:
         """Uploads a file.
 
@@ -2253,6 +2315,7 @@ def _upload_blob(
             quiet (bool): Suppress verbose output (default is False).
             blob_type (ApiBlobType): The entity to which the file/blob refers.
             upload_context (ResumableUploadContext): The context for resumable uploads.
+            content_type (str): Optional MIME content type, e.g. "text/plain", "image/png"
 
         Returns:
             Union[ResumableFileUpload, str, None]: A ResumableFileUpload object, a string, or None.
@@ -2266,9 +2329,10 @@ def _upload_blob(
         start_blob_upload_request.name = file_name
         start_blob_upload_request.content_length = content_length
         start_blob_upload_request.last_modified_epoch_seconds = last_modified_epoch_seconds
+        if content_type:
+            start_blob_upload_request.content_type = content_type
 
         file_upload = upload_context.new_resumable_file_upload(path, start_blob_upload_request)
-
         for i in range(0, self.MAX_UPLOAD_RESUME_ATTEMPTS):
             if file_upload.upload_complete:
                 return file_upload
@@ -4902,6 +4966,7 @@ def _upload_file(
         upload_context: ResumableUploadContext,
         quiet: bool,
         resources: Optional[List[Dict[str, Union[str, Dict[str, List[Dict[str, str]]]]]]],
+        content_type: Optional[str] = None,
     ) -> Union[UploadFile, None]:
         """A helper function to upload a single file.
 
@@ -4912,6 +4977,7 @@ def _upload_file(
             upload_context (ResumableUploadContext): The context for resumable uploads.
             quiet (bool): Suppress verbose output.
             resources (Optional[List[Dict[str, Union[str, Dict[str, List[Dict[str, str]]]]]]]): Optional file metadata.
+            content_type (str): Optional MIME content type, e.g. "text/plain", "image/png"
 
         Returns:
             Union[UploadFile, None]: An UploadFile object if the upload was successful, otherwise None.
@@ -4921,7 +4987,7 @@ def _upload_file(
             print("Starting upload for file " + file_name)
 
         content_length = os.path.getsize(full_path)
-        token = self._upload_blob(full_path, quiet, blob_type, upload_context)
+        token = self._upload_blob(full_path, quiet, blob_type, upload_context, content_type)
         if token is None:
             if not quiet:
                 print("Upload unsuccessful: " + file_name)