Support bulk subs creation in client and add --bulk to CLI to invoke it

Author: goldenberg

planet/cli/subscriptions.py

@@ -151,6 +151,11 @@ async def list_subscriptions_cmd(ctx,
 
 @subscriptions.command(name="create")  # type: ignore
 @click.argument("request", type=types.JSON())
+@click.option(
+    "--bulk",
+    is_flag=True,
+    help="Bulk create many subscriptions using a feature collection reference.",
+)
 @click.option(
     "--hosting",
     type=click.Choice([
@@ -198,9 +203,14 @@ async def create_subscription_cmd(ctx, request, pretty, **kwargs):
         hosting_info = sentinel_hub(collection_id, create_configuration)
         request["hosting"] = hosting_info
 
-    async with subscriptions_client(ctx) as client:
-        sub = await client.create_subscription(request)
-        echo_json(sub, pretty)
+    if kwargs.get("bulk"):
+        async with subscriptions_client(ctx) as client:
+            _ = await client.bulk_create_subscriptions([request])
+            # Bulk create returns no response, so we don't echo anything
+    else:
+        async with subscriptions_client(ctx) as client:
+            sub = await client.create_subscription(request)
+            echo_json(sub, pretty)
 
 
 @subscriptions.command(name='cancel')  # type: ignore

planet/clients/subscriptions.py

@@ -1,7 +1,7 @@
 """Planet Subscriptions API Python client."""
 
 import logging
-from typing import Any, AsyncIterator, Awaitable, Dict, Optional, Sequence, TypeVar
+from typing import Any, AsyncIterator, Awaitable, Dict, Optional, Sequence, TypeVar, List
 
 from typing_extensions import Literal
 
@@ -203,6 +203,37 @@ async def create_subscription(self, request: dict) -> dict:
             sub = resp.json()
             return sub
 
+    async def bulk_create_subscriptions(self, requests: List[dict]) -> None:
+        """
+        Create multiple subscriptions in bulk. Currently, the list of requests can only contain one item.
+
+        Args:
+            requests (List[dict]): A list of dictionaries where each dictionary
+            represents a subscription to be created.
+
+        Raises:
+            APIError: If the API returns an error response.
+            ClientError: If there is an issue with the client request.
+
+        Returns:
+            None: The bulk create endpoint returns an empty body, so no value
+            is returned.
+        """
+        try:
+            url = f'{self._base_url}/bulk'
+            _ = await self._session.request(method='POST',
+                                            url=url,
+                                            json={'subscriptions': requests})
+        # Forward APIError. We don't strictly need this clause, but it
+        # makes our intent clear.
+        except APIError:
+            raise
+        except ClientError:  # pragma: no cover
+            raise
+        else:
+            # The bulk create endpoint returns an empty body so don't attempt to parse it
+            return
+
     async def cancel_subscription(self, subscription_id: str) -> None:
         """Cancel a Subscription.
 

planet/sync/subscriptions.py

@@ -1,6 +1,6 @@
 """Planet Subscriptions API Python client."""
 
-from typing import Any, Dict, Iterator, Optional, Sequence, Union
+from typing import Any, Dict, Iterator, Optional, Sequence, Union, List
 
 from typing_extensions import Literal
 
@@ -136,6 +136,22 @@ def create_subscription(self, request: Dict) -> Dict:
         return self._client._call_sync(
             self._client.create_subscription(request))
 
+    def bulk_create_subscriptions(self, requests: List[Dict]) -> None:
+        """Bulk create subscriptions.
+
+        Args:
+            request (List[dict]): list of descriptions of a bulk creation.
+
+        Returns:
+            None
+
+        Raises:
+            APIError: on an API server error.
+            ClientError: on a client error.
+        """
+        return self._client._call_sync(
+            self._client.bulk_create_subscriptions(requests))
+
     def cancel_subscription(self, subscription_id: str) -> None:
         """Cancel a Subscription.