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

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,15 @@ 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:
+            links = await client.bulk_create_subscriptions([request])
+            # Bulk create returns just a link to an endpoint to list created subscriptions.
+            echo_json(links, pretty)
+    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,34 @@ async def create_subscription(self, request: dict) -> dict:
             sub = resp.json()
             return sub
 
+    async def bulk_create_subscriptions(self, requests: List[dict]) -> Dict:
+        """
+        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:
+            The response including a _links key to the list endpoint for use finding the created subscriptions.
+        """
+        try:
+            url = f'{self._base_url}/bulk'
+            resp = 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:
+            return resp.json()
+
     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]) -> Dict:
+        """Bulk create subscriptions.
+
+        Args:
+            request (List[dict]): list of descriptions of a bulk creation.
+
+        Returns:
+            response including link to list of created subscriptions
+
+        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.
 

tests/integration/test_subscriptions_api.py

@@ -122,6 +122,17 @@ def modify_response(request):
 create_mock.route(M(url=TEST_URL),
                   method='POST').mock(side_effect=modify_response)
 
+bulk_create_mock = respx.mock()
+bulk_create_mock.route(
+    M(url=f'{TEST_URL}/bulk'), method='POST'
+).mock(return_value=Response(
+    200,
+    json={
+        '_links': {
+            'list': f'{TEST_URL}/subscriptions/v1?created={datetime.now().isoformat()}/&geom_ref=pl:features:test_features&name=test-sub'
+        }
+    }))
+
 update_mock = respx.mock()
 update_mock.route(M(url=f'{TEST_URL}/test'),
                   method='PUT').mock(side_effect=modify_response)
@@ -334,6 +345,18 @@ async def test_create_subscription_success():
         assert sub['name'] == 'test'
 
 
+@pytest.mark.anyio
+@bulk_create_mock
+async def test_bulk_create_subscription_success():
+    """Bulk subscription is created, description has the expected items."""
+    async with Session() as session:
+        client = SubscriptionsClient(session, base_url=TEST_URL)
+        resp = await client.bulk_create_subscriptions([{
+            'name': 'test', 'delivery': 'yes, please', 'source': 'test'
+        }])
+        assert '/subscriptions/v1?' in resp['_links']['list']
+
+
 @create_mock
 def test_create_subscription_success_sync():
     """Subscription is created, description has the expected items."""