Merge pull request #864 from planetlabs/data-asset-download-507

Implement CLI commands: planet data asset-get, download, activate, wait

Author: kevinlacaille

docs/cli/cli-data.md

@@ -326,6 +326,25 @@ that are of standard (aka not test) quality. Therefore, these filters can be eas
 planet data filter --permission --std-quality --asset ortho_analytic_8b_sr | planet data search PSScene --filter -
 ```
 
+## `data asset` command basics
+
+To activate an asset for download three commands must be queried, in sequence:
+1. `asset-activate` - activate an asset
+2. `asset-wait` - wait for an asset to be activated
+3. `asset-download` - download an activated asset
+
+For example, if we want to download a `basic_udm2` asset from item ID 
+`20221003_002705_38_2461`, a `PSScene` item type:
+
+```
+planet data asset-activate PSScene 20221003_002705_38_2461 basic_udm2 && \
+planet data asset-wait PSScene 20221003_002705_38_2461 basic_udm2 && \
+planet data asset-download PSScene 20221003_002705_38_2461 basic_udm2 --directory /path/to/data/
+00:00 - order my asset - state: active
+{'_links': {'_self': 'https://api.planet.com/data/v1/assets/eyJpIjogIjIwMjIxMDAzXzAwMjcwNV8zOF8yNDYxIiwgImMiOiAiUFNTY2VuZSIsICJ0IjogImJhc2ljX3VkbTIiLCAiY3QiOiAiaXRlbS10eXBlIn0', 'activate': 'https://api.planet.com/data/v1/assets/eyJpIjogIjIwMjIxMDAzXzAwMjcwNV8zOF8yNDYxIiwgImMiOiAiUFNTY2VuZSIsICJ0IjogImJhc2ljX3VkbTIiLCAiY3QiOiAiaXRlbS10eXBlIn0/activate', 'type': 'https://api.planet.com/data/v1/asset-types/basic_udm2'}, '_permissions': ['download'], 'expires_at': '2023-03-02T19:30:48.942718', 'location': 'https://api.planet.com/data/v1/download?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJQYWtGNHZuUEs3WXRmSFNGUklHY2I3YTNXT3piaTlaam4zWUpZMmxnd0x5cVlFMVBRSHU5QXNCcjR5Q3FxSjBNbl9yN3VwVEFQYUI1ZzhYNUJmcDhmUT09IiwiZXhwIjoxNjc3Nzg1NDQ4LCJ0b2tlbl90eXBlIjoidHlwZWQtaXRlbSIsIml0ZW1fdHlwZV9pZCI6IlBTU2NlbmUiLCJpdGVtX2lkIjoiMjAyMjEwMDNfMDAyNzA1XzM4XzI0NjEiLCJhc3NldF90eXBlIjoiYmFzaWNfdWRtMiJ9.Dd0opDjW3bBS6qLLZoNiJkfBsO2n5Xz9pM5apEUz_K6viDPFexhJiy6bMbaySbby8W0YvuATdb1uYXS2FkweDg', 'md5_digest': '3a9f7dd1ce500f699d0a96afdd0e3aa2', 'status': 'active', 'type': 'basic_udm2'}
+/path/to/data/20221003_002705_38_2461_1A_udm2.tif: 100%|██████████████████████████████████| 3.16k/3.16k [00:00<00:00, 32.0MB/s]
+```
+
 ## Stats
 
 TODO

planet/cli/data.py

@@ -14,17 +14,20 @@
 """The Planet Data CLI."""
 from typing import List, Optional
 from contextlib import asynccontextmanager
+from pathlib import Path
 
 import click
 
+from planet.reporting import StateBar
 from planet import data_filter, DataClient, exceptions
-from planet.clients.data import (LIST_SEARCH_TYPE,
+from planet.clients.data import (SEARCH_SORT,
+                                 LIST_SEARCH_TYPE,
                                  LIST_SEARCH_TYPE_DEFAULT,
                                  LIST_SORT_ORDER,
                                  LIST_SORT_DEFAULT,
-                                 SEARCH_SORT,
                                  SEARCH_SORT_DEFAULT,
                                  STATS_INTERVAL)
+
 from planet.specs import (get_item_types,
                           validate_item_type,
                           SpecificationException)
@@ -68,8 +71,8 @@ def assets_to_filter(ctx, param, assets: List[str]) -> Optional[dict]:
 
 
 def check_item_types(ctx, param, item_types) -> Optional[List[dict]]:
-    '''Validates the item type by comparing the inputted item type to all
-    supported item types.'''
+    '''Validates each item types provided by comparing them to all supported
+    item types.'''
     try:
         for item_type in item_types:
             validate_item_type(item_type)
@@ -78,6 +81,17 @@ def check_item_types(ctx, param, item_types) -> Optional[List[dict]]:
         raise click.BadParameter(str(e))
 
 
+def check_item_type(ctx, param, item_type) -> Optional[List[dict]]:
+    '''Validates the item type provided by comparing it to all supported
+    item types.'''
+    try:
+        validate_item_type(item_type)
+    except SpecificationException as e:
+        raise click.BadParameter(str(e))
+
+    return item_type
+
+
 def check_search_id(ctx, param, search_id) -> str:
     '''Ensure search id is a valix hex string'''
     try:
@@ -480,8 +494,128 @@ async def search_update(ctx,
         echo_json(items, pretty)
 
 
+@data.command()
+@click.pass_context
+@translate_exceptions
+@coro
+@click.argument("item_type", type=str, callback=check_item_type)
+@click.argument("item_id")
+@click.argument("asset_type")
+@click.option('--directory',
+              default='.',
+              help=('Base directory for file download.'),
+              type=click.Path(exists=True,
+                              resolve_path=True,
+                              writable=True,
+                              file_okay=False))
+@click.option('--filename',
+              default=None,
+              help=('Custom name to assign to downloaded file.'),
+              type=str)
+@click.option('--overwrite',
+              is_flag=True,
+              default=False,
+              help=('Overwrite files if they already exist.'))
+@click.option('--checksum',
+              is_flag=True,
+              default=None,
+              help=('Verify that checksums match.'))
+async def asset_download(ctx,
+                         item_type,
+                         item_id,
+                         asset_type,
+                         directory,
+                         filename,
+                         overwrite,
+                         checksum):
+    """Download an activated asset.
+
+    This function will fail if the asset state is not activated. Consider
+    calling `asset-wait` before this command to ensure the asset is activated.
+
+    If --checksum is provided, the associated checksums given in the manifest
+    are compared against the downloaded files to verify that they match.
+
+    If --checksum is provided, files are already downloaded, and --overwrite is
+    not specified, this will simply validate the checksums of the files against
+    the manifest.
+
+    Output:
+    The full path of the downloaded file. If the quiet flag is not set, this
+    also provides ANSI download status reporting.
+    """
+    quiet = ctx.obj['QUIET']
+    async with data_client(ctx) as cl:
+        asset = await cl.get_asset(item_type, item_id, asset_type)
+        path = await cl.download_asset(asset=asset,
+                                       filename=filename,
+                                       directory=Path(directory),
+                                       overwrite=overwrite,
+                                       progress_bar=not quiet)
+        if checksum:
+            cl.validate_checksum(asset, path)
+
+
+@data.command()
+@click.pass_context
+@translate_exceptions
+@coro
+@click.argument("item_type", type=str, callback=check_item_type)
+@click.argument("item_id")
+@click.argument("asset_type")
+async def asset_activate(ctx, item_type, item_id, asset_type):
+    '''Activate an asset.'''
+    async with data_client(ctx) as cl:
+        asset = await cl.get_asset(item_type, item_id, asset_type)
+        await cl.activate_asset(asset)
+
+
+@data.command()
+@click.pass_context
+@translate_exceptions
+@coro
+@click.argument("item_type", type=str, callback=check_item_type)
+@click.argument("item_id")
+@click.argument("asset_type")
+@click.option('--delay',
+              type=int,
+              default=5,
+              help='Time (in seconds) between polls.')
+@click.option('--max-attempts',
+              type=int,
+              default=200,
+              show_default=True,
+              help='Maximum number of polls. Set to zero for no limit.')
+async def asset_wait(ctx, item_type, item_id, asset_type, delay, max_attempts):
+    '''Wait for an asset to be activated.
+
+    Returns when the asset state has reached "activated" and the asset is
+    available.
+    '''
+    quiet = ctx.obj['QUIET']
+    async with data_client(ctx) as cl:
+        asset = await cl.get_asset(item_type, item_id, asset_type)
+        with StateBar(order_id="my asset", disable=quiet) as bar:
+            state = await cl.wait_asset(asset,
+                                        delay,
+                                        max_attempts,
+                                        callback=bar.update_state)
+    click.echo(state)
+
+
+# @data.command()
+# @click.pass_context
+# @translate_exceptions
+# @coro
+# @click.argument("item_type")
+# @click.argument("item_id")
+# @click.argument("asset_type_id")
+# @pretty
+# async def asset_get(ctx, item_type, item_id, asset_type_id, pretty):
+#     '''Get an item asset.'''
+#     async with data_client(ctx) as cl:
+#         asset = await cl.get_asset(item_type, item_id, asset_type_id)
+#     echo_json(asset, pretty)
+
 # TODO: search_run()".
 # TODO: item_get()".
-# TODO: asset_activate()".
-# TODO: asset_wait()".
-# TODO: asset_download()".