Merge pull request #585 from planetlabs/cli_data_stats_#488

CLI data stats #488

Author: mkshah605

design-docs/CLI-Data.md

@@ -726,9 +726,6 @@ ITEM_TYPES - string. Comma-separated item type identifier(s).
 INTERVAL - string. The size of the histogram buckets (<hour, day, week, month, year>)
 FILTER - string. A full JSON description filter. Supports file and stdin.
 
-Options:
---utc-offset - string. A "ISO 8601 UTC offset" (e.g. +01:00 or -08:00) that can be used to adjust the buckets to a users time zone.
-
 Output:
 A full JSON description of the returned statistics result.
 ```

planet/cli/data.py

@@ -18,7 +18,7 @@
 import click
 
 from planet import data_filter, DataClient
-from planet.clients.data import SEARCH_SORT, SEARCH_SORT_DEFAULT
+from planet.clients.data import SEARCH_SORT, SEARCH_SORT_DEFAULT, STATS_INTERVAL
 
 from . import types
 from .cmds import coro, translate_exceptions
@@ -48,6 +48,7 @@ def data(ctx, base_url):
     ctx.obj['BASE_URL'] = base_url
 
 
+# TODO: filter().
 def geom_to_filter(ctx, param, value: Optional[dict]) -> Optional[dict]:
     return data_filter.geometry_filter(value) if value else None
 
@@ -295,6 +296,27 @@ async def search_create(ctx, name, item_types, filter, daily_email, pretty):
         echo_json(items, pretty)
 
 
+@data.command()
+@click.pass_context
+@translate_exceptions
+@coro
+@click.argument("item_types", type=types.CommaSeparatedString())
+@click.argument('interval', type=click.Choice(STATS_INTERVAL))
+@click.argument("filter", type=types.JSON(), default="-", required=False)
+async def stats(ctx, item_types, interval, filter):
+    """Get a bucketed histogram of items matching the filter.
+
+    This function returns a bucketed histogram of results based on the
+    item_types, interval, and json filter specified (using file or stdin).
+
+    """
+    async with data_client(ctx) as cl:
+        items = await cl.get_stats(item_types=item_types,
+                                   interval=interval,
+                                   search_filter=filter)
+        echo_json(items)
+
+
 @data.command()
 @click.pass_context
 @translate_exceptions
@@ -319,4 +341,3 @@ async def search_get(ctx, search_id, pretty):
 # TODO: asset_activate()".
 # TODO: asset_wait()".
 # TODO: asset_download()".
-# TODO: stats()".

planet/clients/data.py

@@ -336,7 +336,7 @@ async def get_stats(self,
             interval: The size of the histogram date buckets.
 
         Returns:
-            Returns a date bucketed histogram of items matching the filter.
+            A full JSON description of the returned statistics result histogram.
 
         Raises:
             planet.exceptions.APIError: On API error.
@@ -348,11 +348,13 @@ async def get_stats(self,
                 f'{interval} must be one of {STATS_INTERVAL}')
 
         url = f'{self._base_url}{STATS_PATH}'
+
         request_json = {
             'interval': interval,
             'filter': search_filter,
             'item_types': item_types
         }
+
         request = self._request(url, method='POST', json=request_json)
         response = await self._do_request(request)
         return response.json()

tests/integration/test_data_api.py

@@ -229,7 +229,6 @@ async def test_get_search_success(search_id, search_result, session):
     get_url = f'{TEST_SEARCHES_URL}/{search_id}'
     mock_resp = httpx.Response(HTTPStatus.OK, json=search_result)
     respx.get(get_url).return_value = mock_resp
-
     cl = DataClient(session, base_url=TEST_URL)
     search = await cl.get_search(search_id)
     assert search_result == search
@@ -246,7 +245,6 @@ async def test_get_search_id_doesnt_exist(search_id, session):
     }
     mock_resp = httpx.Response(404, json=resp)
     respx.get(get_url).return_value = mock_resp
-
     cl = DataClient(session, base_url=TEST_URL)
 
     with pytest.raises(exceptions.MissingResource):

tests/integration/test_data_cli.py

@@ -29,6 +29,7 @@
 TEST_URL = 'https://api.planet.com/data/v1'
 TEST_QUICKSEARCH_URL = f'{TEST_URL}/quick-search'
 TEST_SEARCHES_URL = f'{TEST_URL}/searches'
+TEST_STATS_URL = f'{TEST_URL}/stats'
 
 
 @pytest.fixture
@@ -581,6 +582,80 @@ def test_search_create_daily_email(invoke, search_result):
     assert json.loads(result.output) == search_result
 
 
+@respx.mock
+@pytest.mark.asyncio
+@pytest.mark.parametrize("filter", ['{1:1}', '{"foo"}'])
+def test_data_stats_invalid_filter(invoke, filter):
+    """Test for planet data stats. Test with multiple item_types.
+    Test should fail as filter does not contain valid JSON."""
+    mock_resp = httpx.Response(HTTPStatus.OK,
+                               json={'features': [{
+                                   "key": "value"
+                               }]})
+    respx.post(TEST_STATS_URL).return_value = mock_resp
+    interval = "hour"
+    item_type = 'PSScene'
+    runner = CliRunner()
+    result = invoke(["stats", item_type, interval, filter], runner=runner)
+    assert result.exit_code == 2
+
+
+@respx.mock
+@pytest.mark.parametrize(
+    "item_types", ['PSScene', 'SkySatScene', ('PSScene', 'SkySatScene')])
+@pytest.mark.parametrize("interval, exit_code", [(None, 1), ('hou', 2),
+                                                 ('hour', 0)])
+def test_data_stats_invalid_interval(invoke, item_types, interval, exit_code):
+    """Test for planet data stats. Test with multiple item_types.
+    Test should succeed with valid interval, and fail with invalid interval."""
+    filter = {
+        "type": "DateRangeFilter",
+        "field_name": "acquired",
+        "config": {
+            "gt": "2019-12-31T00:00:00Z", "lte": "2020-01-31T00:00:00Z"
+        }
+    }
+
+    mock_resp = httpx.Response(HTTPStatus.OK,
+                               json={'features': [{
+                                   "key": "value"
+                               }]})
+    respx.post(TEST_STATS_URL).return_value = mock_resp
+
+    runner = CliRunner()
+    result = invoke(["stats", item_types, interval, json.dumps(filter)],
+                    runner=runner)
+
+    assert result.exit_code == exit_code
+
+
+@respx.mock
+@pytest.mark.parametrize(
+    "item_types", ['PSScene', 'SkySatScene', ('PSScene', 'SkySatScene')])
+@pytest.mark.parametrize("interval", ['hour', 'day', 'week', 'month', 'year'])
+def test_data_stats_success(invoke, item_types, interval):
+    """Test for planet data stats. Test with multiple item_types.
+    Test should succeed as filter contains valid JSON, item_types, and intervals."""
+    filter = {
+        "type": "DateRangeFilter",
+        "field_name": "acquired",
+        "config": {
+            "gt": "2019-12-31T00:00:00Z", "lte": "2020-01-31T00:00:00Z"
+        }
+    }
+
+    mock_resp = httpx.Response(HTTPStatus.OK,
+                               json={'features': [{
+                                   "key": "value"
+                               }]})
+    respx.post(TEST_STATS_URL).return_value = mock_resp
+
+    runner = CliRunner()
+    result = invoke(["stats", item_types, interval, json.dumps(filter)],
+                    runner=runner)
+    assert result.exit_code == 0
+
+
 # TODO: basic test for "planet data filter".