v2: add cli for orders api

docs/cli.md

@@ -0,0 +1,9 @@
+# CLI Reference
+
+This page provides documentation for our command line tools.
+
+::: mkdocs-click
+    :module: planet.scripts.cli
+    :command: cli
+    :prog_name: planet
+    :depth: 1

docs/guide.md

@@ -1,6 +1,7 @@
 # User Guide
 
-## Session
+## API
+### Session
 
 Communication with the Planet services is provided with the `Session` class.
 The recommended way to use a `Session` is as a context manager. This will
@@ -32,7 +33,7 @@ Alternatively, use `await Session.aclose()` to close a `Session` explicitly:
 
 ```
 
-## Authentication
+### Authentication
 
 There are two steps to managing authentication information, obtaining the
 authentication information from Planet and then managing it for local retrieval
@@ -87,7 +88,7 @@ environment variable:
 
 ```
 
-## Orders Client
+### Orders Client
 
 The Orders Client mostly mirrors the
 [Orders API](https://developers.planet.com/docs/orders/reference/#tag/Orders),
@@ -106,7 +107,7 @@ order is completed and to download an entire order.
 
 ```
 
-### Creating an Order
+#### Creating an Order
 
 When creating an order, the order details must be provided to the API. There
 are two ways to specify the order details, a `JSON` blob and an `OrderDetails`
@@ -154,3 +155,122 @@ the context of a `Session` with the `OrdersClient`:
 >>> asyncio.run(main())
 
 ```
+
+## CLI
+
+### Authentication
+
+The `auth` command allows the CLI to authenticate with Planet servers. Before
+any other command is run, the CLI authentication should be initiated with
+
+```console
+$ planet auth init
+```
+
+To store the authentication information in an environment variable, e.g.
+for passing into a Docker instance:
+
+```console
+$ export PL_API_KEY=$(planet auth value)
+```
+
+### Orders API
+
+Most `orders` cli commands are simple wrappers around the
+[Planet Orders API](https://developers.planet.com/docs/orders/reference/#tag/Orders)
+commands.
+
+
+#### Create Order File Inputs
+
+Creating an order supports JSON files as inputs and these need to follow certain
+formats.
+
+
+##### --cloudconfig
+The file given with the `--cloudconfig` option should contain JSON that follows
+the options and format given in
+[Delivery to Cloud Storage](https://developers.planet.com/docs/orders/delivery/#delivery-to-cloud-storage).
+
+An example would be:
+
+Example: `cloudconfig.json`
+```
+{
+    "amazon_s3": {
+        "aws_access_key_id": "aws_access_key_id",
+        "aws_secret_access_key": "aws_secret_access_key",
+        "bucket": "bucket",
+        "aws_region": "aws_region"
+    },
+    "archive_type": "zip"
+}
+```
+
+##### --clip
+The file given with the `--clip` option should contain valid [GeoJSON](https://geojson.org/).
+It can be a Polygon geometry, a Feature, or a FeatureClass. If it is a FeatureClass,
+only the first Feature is used for the clip geometry.
+
+Example: `aoi.geojson`
+```
+{
+    "type": "Polygon",
+    "coordinates": [
+        [
+            [
+                37.791595458984375,
+                14.84923123791421
+            ],
+            [
+                37.90214538574219,
+                14.84923123791421
+            ],
+            [
+                37.90214538574219,
+                14.945448293647944
+            ],
+            [
+                37.791595458984375,
+                14.945448293647944
+            ],
+            [
+                37.791595458984375,
+                14.84923123791421
+            ]
+        ]
+    ]
+}
+```
+
+##### --tools
+The file given with the `--tools` option should contain JSON that follows the
+format for a toolchain, the "tools" section of an order. The toolchain options
+and format are given in
+[Creating Toolchains](https://developers.planet.com/docs/orders/tools-toolchains/#creating-toolchains).
+
+Example: `tools.json`
+```
+[
+    {
+        "toar": {
+            "scale_factor": 10000
+        }
+    },
+    {
+        "reproject": {
+            "projection": "WGS84",
+            "kernel": "cubic"
+        }
+    },
+    {
+        "tile": {
+            "tile_size": 1232,
+            "origin_x": -180,
+            "origin_y": -90,
+            "pixel_size": 2.7056277056e-05,
+            "name_template": "C1232_30_30_{tilex:04d}_{tiley:04d}"
+        }
+    }
+```
+

mkdocs.yml

@@ -31,8 +31,10 @@ nav:
     - User Guide: 'guide.md'
     - Upgrading: 'upgrading.md'
     - API Reference: 'api.md'
+    - CLI Reference: 'cli.md'
 
 markdown_extensions:
   - pymdownx.highlight
   - pymdownx.superfences
+  - mkdocs-click
 

planet/__init__.py

@@ -17,7 +17,7 @@
 from .api.order_details import (
     OrderDetails, Product, Notifications, Delivery, AmazonS3Delivery,
     AzureBlobStorageDelivery, GoogleCloudStorageDelivery,
-    GoogleEarthEngineDelivery, Tool)
+    GoogleEarthEngineDelivery, Tool, ClipTool)
 from .api.__version__ import __version__  # NOQA
 from .auth import Auth
 
@@ -34,6 +34,7 @@
     AzureBlobStorageDelivery,
     GoogleCloudStorageDelivery,
     GoogleEarthEngineDelivery,
+    ClipTool,
     Tool,
-    Auth
+    Auth,
 ]

planet/api/http.py

@@ -51,8 +51,8 @@ def _log_response(response):
             f'{request.method} {request.url} - '
             f'Status {response.status_code}')
 
-    @staticmethod
-    def _raise_for_status(response):
+    @classmethod
+    def _raise_for_status(cls, response):
         # TODO: consider using http_response.reason_phrase
         status = response.status_code
 
@@ -69,17 +69,48 @@ def _raise_for_status(response):
             HTTPStatus.INTERNAL_SERVER_ERROR: exceptions.ServerError
         }.get(status, None)
 
-        msg = response.text
+        LOGGER.debug(f"Exception type: {exception}")
+        LOGGER.debug(f"Response text: {response.text}")
+
+        if exception == exceptions.TooManyRequests:
+            # differentiate between over quota and rate-limiting
+            if 'quota' in response.text.lower():
+                exception = exceptions.OverQuota
 
-        # differentiate between over quota and rate-limiting
-        if status == 429 and 'quota' in msg.lower():
-            exception = exceptions.OverQuota
+        try:
+            msg = cls._parse_message(response)
+        except Exception:
+            msg = response.text
 
         if exception:
             raise exception(msg)
 
         raise exceptions.APIException(f'{status}: {msg}')
 
+    @staticmethod
+    def _parse_message(response):
+        msg = response.json()
+        LOGGER.debug(f'Raw response message: {msg}')
+
+        try:
+            msg = msg['message']
+        except KeyError:
+            try:
+                new_msg = msg['general'][0]['message']
+                try:
+                    msg_field = msg['field']
+                    key = list(msg_field.keys())[0]
+                    LOGGER.debug(f'key: {key}')
+                    new_msg = (new_msg + ' - ' + msg_field[key][0]['message'])
+                except Exception:
+                    pass
+                msg = new_msg
+            except Exception:
+                pass
+
+        LOGGER.debug(f'Processed response message: {msg}')
+        return msg
+
 
 class Session(BaseSession):
     '''Context manager for asynchronous communication with the Planet service.
@@ -244,6 +275,15 @@ def request(self, request):
         http_resp = self._client.send(request.http_request)
         return models.Response(request, http_resp)
 
+    @classmethod
+    def _raise_for_status(cls, response):
+        try:
+            super()._raise_for_status(response)
+        except exceptions.BadQuery:
+            raise exceptions.APIException('Not a valid email address.')
+        except exceptions.InvalidAPIKey:
+            raise exceptions.APIException('Incorrect email or password.')
+
 
 class Stream():
     '''Context manager for asynchronous response stream from Planet server.'''

planet/api/models.py

@@ -397,6 +397,10 @@ def id(self):
         '''
         return self.data['id']
 
+    @property
+    def json(self):
+        return self.data
+
 
 class Orders(Paged):
     '''Asynchronous iterator over Orders from a paged response describing