Add support for new subscriptions summary endpoints (#1098)

* add support for new subscriptions summary endpoints

* fix summary cli tests

* split client function into two separate for different return structs

Author: charcey

docs/cli/cli-subscriptions.md

@@ -555,4 +555,19 @@ planet subscriptions request \
 ```
 
 For more information on Sentinel Hub hosting, see the [Subscriptions API documentation](https://developers.planet.com/docs/subscriptions/delivery/#delivery-to-sentinel-hub-collection) and the [Linking Planet User to Sentinel Hub User
-](https://support.planet.com/hc/en-us/articles/16550358397469-Linking-Planet-User-to-Sentinel-Hub-User) support post.
+](https://support.planet.com/hc/en-us/articles/16550358397469-Linking-Planet-User-to-Sentinel-Hub-User) support post.
+
+
+#### Summaries
+
+You can get two types of summaries using the CLI.
+
+The first is a summary of all subscriptions created by the user, totaled by status.
+```sh
+planet subscriptions summarize
+```
+
+The second is a summary of _results_ for a specified subscription, totaled by status.
+```sh
+planet subscriptions summarize --subscription-id=cb817760-1f07-4ee7-bba6-bcac5346343f
+```

planet/cli/subscriptions.py

@@ -526,3 +526,24 @@ def item_types(ctx):
     click.echo("Valid item types:")
     for it in get_item_types():
         click.echo(f"- {it}")
+
+
+@subscriptions.command()  # type: ignore
+@click.option(
+    '--subscription-id',
+    default=None,
+    help="""Optionally supply a subscription ID to summarize result counts
+    by status. If omitted, the summary will be generated for all
+    subscriptions the requester has created by status.""")
+@pretty
+@click.pass_context
+@translate_exceptions
+@coro
+async def summarize(ctx, subscription_id, pretty):
+    """Summarize the status of all subscriptions or the status of results for a single subscription"""
+    async with subscriptions_client(ctx) as client:
+        if subscription_id:
+            summary = await client.get_subscription_summary(subscription_id)
+        else:
+            summary = await client.get_summary()
+        echo_json(summary, pretty)

planet/clients/subscriptions.py

@@ -407,3 +407,57 @@ async def get_results_csv(
         async with self._session.stream('GET', url, params=params) as response:
             async for line in response.aiter_lines():
                 yield line
+
+    async def get_summary(self) -> dict:
+        """Summarize the status of all subscriptions via GET.
+
+        Returns:
+            dict: subscription totals by status.
+
+        Raises:
+            APIError: on an API server error.
+            ClientError: on a client error.
+        """
+        url = f'{self._base_url}/summary'
+
+        try:
+            resp = await self._session.request(method='GET', url=url)
+        # 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:
+            summary = resp.json()
+            return summary
+
+    async def get_subscription_summary(
+        self,
+        subscription_id: str,
+    ) -> dict:
+        """Summarize the status of results for a single subscription via GET.
+
+        Args
+            subscription_id (str): ID of the subscription to summarize.
+
+        Returns:
+            dict: result totals for the provided subscription by status.
+
+        Raises:
+            APIError: on an API server error.
+            ClientError: on a client error.
+        """
+        url = f'{self._base_url}/{subscription_id}/summary'
+
+        try:
+            resp = await self._session.request(method='GET', url=url)
+        # 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:
+            summary = resp.json()
+            return summary

planet/sync/subscriptions.py

@@ -280,3 +280,31 @@ def get_results_csv(
                 yield self._client._call_sync(results.__anext__())
         except StopAsyncIteration:
             pass
+
+    def get_summary(self) -> Dict[str, Any]:
+        """Summarize the status of all subscriptions via GET.
+
+        Returns:
+            dict: subscription totals by status.
+
+        Raises:
+            APIError: on an API server error.
+            ClientError: on a client error.
+        """
+        return self._client._call_sync(self._client.get_summary())
+
+    def get_subscription_summary(self, subscription_id: str) -> Dict[str, Any]:
+        """Summarize the status of results for a single subscription via GET.
+
+        Args
+            subscription_id (str): ID of the subscription to summarize.
+
+        Returns:
+            dict: result totals for the provided subscription by status.
+
+        Raises:
+            APIError: on an API server error.
+            ClientError: on a client error.
+        """
+        return self._client._call_sync(
+            self._client.get_subscription_summary(subscription_id))

tests/integration/test_subscriptions_api.py

@@ -146,6 +146,40 @@ def modify_response(request):
                                                  'source': 'test'
                                              }))
 
+summary_mock = respx.mock()
+summary_mock.route(
+    M(url=f'{TEST_URL}/summary'),
+    method='GET').mock(return_value=Response(200,
+                                             json={
+                                                 "subscriptions": {
+                                                     "preparing": 0,
+                                                     "pending": 0,
+                                                     "running": 0,
+                                                     "completed": 0,
+                                                     "cancelled": 0,
+                                                     "suspended": 0,
+                                                     "failed": 0
+                                                 }
+                                             }))
+
+sub_summary_mock = respx.mock()
+sub_summary_mock.route(
+    M(url=f'{TEST_URL}/test/summary'),
+    method='GET').mock(return_value=Response(200,
+                                             json={
+                                                 "results": {
+                                                     "created": 0,
+                                                     "queued": 0,
+                                                     "processing": 0,
+                                                     "failed": 0,
+                                                     "cancelled": 0,
+                                                     "success": 0
+                                                 },
+                                                 "subscription": {
+                                                     "status": "pending"
+                                                 }
+                                             }))
+
 
 def result_pages(status=None, size=40):
     """Helper for creating fake result listing pages."""
@@ -526,3 +560,85 @@ async def test_list_subscriptions_cycle_break():
         async with Session() as session:
             client = SubscriptionsClient(session, base_url=TEST_URL)
             _ = [sub async for sub in client.list_subscriptions()]
+
+
+@pytest.mark.anyio
+@summary_mock
+async def test_get_summary():
+    """Summary fetched, has expected totals, async."""
+    async with Session() as session:
+        client = SubscriptionsClient(session, base_url=TEST_URL)
+        summary = await client.get_summary()
+        assert summary == {
+            "subscriptions": {
+                "preparing": 0,
+                "pending": 0,
+                "running": 0,
+                "completed": 0,
+                "cancelled": 0,
+                "suspended": 0,
+                "failed": 0
+            }
+        }
+
+
+@summary_mock
+def test_get_summary_sync():
+    """Summary fetched, has expected totals, sync."""
+    pl = Planet()
+    pl.subscriptions._client._base_url = TEST_URL
+    summary = pl.subscriptions.get_summary()
+    assert summary == {
+        "subscriptions": {
+            "preparing": 0,
+            "pending": 0,
+            "running": 0,
+            "completed": 0,
+            "cancelled": 0,
+            "suspended": 0,
+            "failed": 0
+        }
+    }
+
+
+@pytest.mark.anyio
+@sub_summary_mock
+async def test_get_sub_summary():
+    """Subscription summary fetched, has expected totals, async."""
+    async with Session() as session:
+        client = SubscriptionsClient(session, base_url=TEST_URL)
+        summary = await client.get_subscription_summary("test")
+        assert summary == {
+            "results": {
+                "created": 0,
+                "queued": 0,
+                "processing": 0,
+                "failed": 0,
+                "cancelled": 0,
+                "success": 0
+            },
+            "subscription": {
+                "status": "pending"
+            }
+        }
+
+
+@sub_summary_mock
+def test_get_sub_summary_sync():
+    """Subscription summary fetched, has expected totals, sync."""
+    pl = Planet()
+    pl.subscriptions._client._base_url = TEST_URL
+    summary = pl.subscriptions.get_subscription_summary("test")
+    assert summary == {
+        "results": {
+            "created": 0,
+            "queued": 0,
+            "processing": 0,
+            "failed": 0,
+            "cancelled": 0,
+            "success": 0
+        },
+        "subscription": {
+            "status": "pending"
+        }
+    }

tests/integration/test_subscriptions_cli.py

@@ -29,6 +29,8 @@
                                     get_mock,
                                     patch_mock,
                                     res_api_mock,
+                                    sub_summary_mock,
+                                    summary_mock,
                                     update_mock,
                                     TEST_URL)
 
@@ -523,3 +525,43 @@ def test_item_types(invoke, mock_bundles):
     for item_type in expected_item_types:
         assert item_type in result.output
     assert result.exit_code == 0
+
+
+@summary_mock
+def test_summarize_subs(invoke):
+    result = invoke(['summarize'])
+
+    assert result.exit_code == 0  # success.
+    summary = json.loads(result.output)
+    assert summary == {
+        "subscriptions": {
+            "preparing": 0,
+            "pending": 0,
+            "running": 0,
+            "completed": 0,
+            "cancelled": 0,
+            "suspended": 0,
+            "failed": 0
+        }
+    }
+
+
+@sub_summary_mock
+def test_summarize_results(invoke):
+    result = invoke(['summarize', '--subscription-id=test'])
+
+    assert result.exit_code == 0  # success.
+    summary = json.loads(result.output)
+    assert summary == {
+        "results": {
+            "created": 0,
+            "queued": 0,
+            "processing": 0,
+            "failed": 0,
+            "cancelled": 0,
+            "success": 0
+        },
+        "subscription": {
+            "status": "pending"
+        }
+    }