feat(cli): add competitions init and create commands (#1080)

Wrap kagglesdk 0.1.31's new create_competition RPC behind a
metadata-file flow that mirrors `kaggle datasets {init,create}` and
`kaggle models {init,create}`:

- `kaggle competitions init [folder]` writes a competition-metadata.json
template with INSERT_*_HERE placeholders for the required fields (title,
slug, briefDescription) plus all optional fields.
- `kaggle competitions create -p folder` reads the metadata file,
validates the required fields are filled in, parses the privacy string
into the CompetitionPrivacy enum (and reward.id into RewardTypeId when
supplied), and calls create_competition.

Smoke entry added for `competitions init` (idempotent template write).

Author: bovard

src/kaggle/api/kaggle_api_extended.py

@@ -100,6 +100,8 @@
     ApiListCompetitionPagesResponse,
     ApiCreateCompetitionPageRequest,
     ApiCompetitionPage,
+    ApiCreateCompetitionRequest,
+    ApiCreateCompetitionResponse,
     ApiLaunchCompetitionRequest,
     ApiListCompetitionTopicsRequest,
     ApiListCompetitionTopicsResponse,
@@ -131,12 +133,15 @@
 )
 from kagglesdk.competitions.types.competition_enums import (
     CompetitionListTab,
+    CompetitionPrivacy,
     HostSegment,
     CompetitionSortBy,
     SubmissionGroup,
     SubmissionSortBy,
 )
 
+from kagglesdk.competitions.types.competition import Reward, RewardTypeId
+
 from kagglesdk.common.types.cropped_image_upload import CroppedImageUpload, CroppedImageRectangle
 
 from kagglesdk.datasets.types.dataset_api_service import (
@@ -764,6 +769,7 @@ class KaggleApi:
     KERNEL_METADATA_FILE = "kernel-metadata.json"
     MODEL_METADATA_FILE = "model-metadata.json"
     MODEL_INSTANCE_METADATA_FILE = "model-instance-metadata.json"
+    COMPETITION_METADATA_FILE = "competition-metadata.json"
     MAX_NUM_INBOX_FILES_TO_UPLOAD = 1000
     MAX_UPLOAD_RESUME_ATTEMPTS = 10
 
@@ -2471,6 +2477,130 @@ def competition_launch_cli(
         else:
             print(f'Competition "{competition_name}" launched.')
 
+    def competition_initialize(self, folder: str) -> str:
+        """Initialize a folder with a competition-metadata.json template.
+
+        Args:
+            folder (str): Folder in which to write the template.
+
+        Returns:
+            str: Path to the written metadata file.
+        """
+        if not os.path.isdir(folder):
+            raise ValueError("Invalid folder: " + folder)
+
+        meta_data = {
+            "title": "INSERT_TITLE_HERE",
+            "slug": "INSERT_SLUG_HERE",
+            "briefDescription": "INSERT_BRIEF_DESCRIPTION_HERE",
+            "privacy": "PUBLIC",
+            "disableKernels": False,
+            "hackathon": False,
+            "cloneCompetitionId": None,
+            "cloneExcludeCompetitionData": None,
+            "clonePageNames": None,
+            "licenseId": None,
+            "organizationId": None,
+            "numPrizes": None,
+            "restrictLinkToEmailList": None,
+            "reward": None,
+        }
+        meta_file = os.path.join(folder, self.COMPETITION_METADATA_FILE)
+        with open(meta_file, "w") as f:
+            json.dump(meta_data, f, indent=2)
+
+        print("Competition metadata template written to: " + meta_file)
+        return meta_file
+
+    def competition_initialize_cli(self, folder=None):
+        folder = folder or os.getcwd()
+        self.competition_initialize(folder)
+
+    def competition_create_new(self, folder: str) -> ApiCreateCompetitionResponse:
+        """Create a new competition from ``competition-metadata.json`` in ``folder``.
+
+        Args:
+            folder (str): Folder containing competition-metadata.json.
+
+        Returns:
+            ApiCreateCompetitionResponse: with id, ref, url of the new competition.
+        """
+        if not os.path.isdir(folder):
+            raise ValueError("Invalid folder: " + folder)
+
+        meta_file = os.path.join(folder, self.COMPETITION_METADATA_FILE)
+        if not os.path.isfile(meta_file):
+            raise ValueError("Metadata file not found: " + self.COMPETITION_METADATA_FILE)
+
+        with open(meta_file) as f:
+            meta = json.load(f)
+
+        title = cast(str, self.get_or_fail(meta, "title"))
+        slug = cast(str, self.get_or_fail(meta, "slug"))
+        brief_description = cast(str, self.get_or_fail(meta, "briefDescription"))
+        privacy_str = cast(str, self.get_or_fail(meta, "privacy"))
+
+        if title == "INSERT_TITLE_HERE":
+            raise ValueError("Default title detected, please update competition-metadata.json before creating")
+        if slug == "INSERT_SLUG_HERE":
+            raise ValueError("Default slug detected, please update competition-metadata.json before creating")
+        if brief_description == "INSERT_BRIEF_DESCRIPTION_HERE":
+            raise ValueError(
+                "Default briefDescription detected, please update competition-metadata.json before creating"
+            )
+
+        try:
+            privacy = CompetitionPrivacy[privacy_str.upper()]
+        except KeyError as exc:
+            valid = [n for n in CompetitionPrivacy.__members__ if n != "COMPETITION_PRIVACY_UNSPECIFIED"]
+            raise ValueError(f"Invalid privacy '{privacy_str}'. Valid: {', '.join(valid)}") from exc
+
+        request = ApiCreateCompetitionRequest()
+        request.title = title
+        request.slug = slug
+        request.brief_description = brief_description
+        request.privacy = privacy
+
+        if meta.get("disableKernels") is not None:
+            request.disable_kernels = bool(meta["disableKernels"])
+        if meta.get("hackathon") is not None:
+            request.hackathon = bool(meta["hackathon"])
+        if meta.get("restrictLinkToEmailList") is not None:
+            request.restrict_link_to_email_list = bool(meta["restrictLinkToEmailList"])
+        if meta.get("cloneCompetitionId") is not None:
+            request.clone_competition_id = int(meta["cloneCompetitionId"])
+        if meta.get("cloneExcludeCompetitionData") is not None:
+            request.clone_exclude_competition_data = bool(meta["cloneExcludeCompetitionData"])
+        if meta.get("clonePageNames"):
+            request.clone_page_names = list(meta["clonePageNames"])
+        if meta.get("licenseId") is not None:
+            request.license_id = int(meta["licenseId"])
+        if meta.get("organizationId") is not None:
+            request.organization_id = int(meta["organizationId"])
+        if meta.get("numPrizes") is not None:
+            request.num_prizes = int(meta["numPrizes"])
+        if meta.get("reward") is not None:
+            reward_meta = meta["reward"]
+            reward = Reward()
+            reward_id_str = cast(str, self.get_or_fail(reward_meta, "id"))
+            try:
+                reward.id = RewardTypeId[reward_id_str.upper()]
+            except KeyError as exc:
+                valid = [n for n in RewardTypeId.__members__ if n != "REWARD_TYPE_ID_UNSPECIFIED"]
+                raise ValueError(f"Invalid reward.id '{reward_id_str}'. Valid: {', '.join(valid)}") from exc
+            reward.quantity = int(self.get_or_fail(reward_meta, "quantity"))
+            if reward_meta.get("clarification") is not None:
+                reward.clarification = reward_meta["clarification"]
+            request.reward = reward
+
+        with self.build_kaggle_client() as kaggle:
+            return kaggle.competitions.competition_api_client.create_competition(request)
+
+    def competition_create_new_cli(self, folder=None):
+        folder = folder or os.getcwd()
+        response = self.competition_create_new(folder)
+        print(f"Competition created: {response.url}")
+
     def competition_list_topics(self, competition: str, sort_by: Optional[str] = None, page: Optional[int] = None):
         """List discussion topics for a competition.
 

src/kaggle/cli.py

@@ -490,6 +490,35 @@ def parse_competitions(subparsers) -> None:
     parser_competitions_launch._action_groups.append(parser_competitions_launch_optional)
     parser_competitions_launch.set_defaults(func=api.competition_launch_cli)
 
+    # Competitions init (write competition-metadata.json template)
+    parser_competitions_init = subparsers_competitions.add_parser(
+        "init", formatter_class=argparse.RawTextHelpFormatter, help=Help.command_competitions_init
+    )
+    parser_competitions_init_optional = parser_competitions_init._action_groups.pop()
+    parser_competitions_init_optional.add_argument(
+        "folder",
+        nargs="?",
+        default=None,
+        help="Folder to write competition-metadata.json into (default: current directory).",
+    )
+    parser_competitions_init._action_groups.append(parser_competitions_init_optional)
+    parser_competitions_init.set_defaults(func=api.competition_initialize_cli)
+
+    # Competitions create (read competition-metadata.json and create competition)
+    parser_competitions_create = subparsers_competitions.add_parser(
+        "create", formatter_class=argparse.RawTextHelpFormatter, help=Help.command_competitions_create
+    )
+    parser_competitions_create_optional = parser_competitions_create._action_groups.pop()
+    parser_competitions_create_optional.add_argument(
+        "-p",
+        "--path",
+        dest="folder",
+        required=False,
+        help="Folder containing competition-metadata.json (default: current directory).",
+    )
+    parser_competitions_create._action_groups.append(parser_competitions_create_optional)
+    parser_competitions_create.set_defaults(func=api.competition_create_new_cli)
+
     shared_topics = _get_shared_topics_parser()
     shared_competition_topics = _get_shared_competition_topics_parser()
 
@@ -1998,6 +2027,8 @@ class Help(object):
         "logs",
         "pages",
         "launch",
+        "init",
+        "create",
         "topics",
         "topic-messages",
     ]
@@ -2134,6 +2165,8 @@ class Help(object):
     command_competitions_pages = "List pages for a competition"
     command_competitions_pages_create = "Create a new page on a competition you host"
     command_competitions_launch = "Launch a competition you host, optionally at a future UTC time"
+    command_competitions_init = "Initialize folder with a competition-metadata.json template"
+    command_competitions_create = "Create a new competition from competition-metadata.json"
     command_competitions_topics = "List discussion topics for a competition"
     command_competitions_topic_messages = "List messages within a competition discussion topic"
 

tests/test_commands.sh

@@ -39,7 +39,11 @@ kaggle c pages titanic
 kaggle c pages titanic -v -q
 kaggle c pages titanic --page-name rules --content
 kaggle c pages list titanic --page-name rules
-rm -r titanic.zip tost sample_submission.csv leaders leaderboard.txt
+echo "kaggle competitions init"
+mkdir -p tests/comp-init
+kaggle c init tests/comp-init
+cat tests/comp-init/competition-metadata.json
+rm -r titanic.zip tost sample_submission.csv leaders leaderboard.txt tests/comp-init
 
 echo "kaggle kernels list"
 kaggle k list -m -s Exercise --page-size 5 -p 2 -v  --sort-by dateRun