Repository: planetlabs/planet-client-python

Issue:
Update cancel order to report the details of the cancelled order
Currently, when an order is cancelled, the CLI reports 'Cancelled' and the python API returns nothing. However, when an order is cancelled, the Orders API [returns the order details](https://developers.planet.com/docs/orders/reference/#operation/cancelOrder). To align with the api, change these both to return the details of the cancelled order. 

Also, update the SDK and CLI documentation accordingly.

CLI documentation:
```
async def cancel(ctx, order_id, pretty):
    """Cancel order.

    This command outputs the cancelled order details, optionally
    pretty-printed.
    """
```

Blocked by #362 

Discussion:

Patch:
diff --git a/planet/cli/orders.py b/planet/cli/orders.py
index 4caf843..01f677e 100644
--- a/planet/cli/orders.py
+++ b/planet/cli/orders.py
@@ -94,11 +94,15 @@ async def get(ctx, order_id, pretty):
 @coro
 @click.argument('order_id', type=click.UUID)
 async def cancel(ctx, order_id):
-    '''Cancel order by order ID.'''
+    '''Cancel order by order ID.
+
+    This command cancels a queued order and outputs the cancelled order
+    details.
+    '''
     async with orders_client(ctx) as cl:
-        await cl.cancel_order(str(order_id))
+        json_resp = await cl.cancel_order(str(order_id))
 
-    click.echo('Cancelled')
+    click.echo(json_resp)
 
 
 def split_list_arg(ctx, param, value):
diff --git a/planet/clients/orders.py b/planet/clients/orders.py
index 318a82e..dfa7ffb 100644
--- a/planet/clients/orders.py
+++ b/planet/clients/orders.py
@@ -177,18 +177,14 @@ class OrdersClient():
         order = Order(resp.json())
         return order
 
-    async def cancel_order(self, order_id: str) -> Response:
+    async def cancel_order(self, order_id: str) -> dict:
         '''Cancel a queued order.
 
-        **Note:** According to the API docs, cancel order should return the
-        cancelled order details. But testing reveals that an empty response is
-        returned upon success.
-
         Parameters:
             order_id: The ID of the order
 
         Returns:
-            Empty response
+            Results of the cancel request
 
         Raises:
             planet.exceptions.ClientError: If order_id is not a valid UUID.
@@ -198,8 +194,8 @@ class OrdersClient():
         url = f'{self._orders_url()}/{order_id}'
 
         req = self._request(url, method='PUT')
-
-        await self._do_request(req)
+        resp = await self._do_request(req)
+        return resp.json()
 
     async def cancel_orders(self, order_ids: typing.List[str] = None) -> dict:
         '''Cancel queued orders in bulk.


Test patch:
diff --git a/tests/integration/test_orders_api.py b/tests/integration/test_orders_api.py
index 03bf270..53f991d 100644
--- a/tests/integration/test_orders_api.py
+++ b/tests/integration/test_orders_api.py
@@ -291,12 +291,12 @@ async def test_cancel_order(oid, order_description, session):
     cancel_url = f'{TEST_ORDERS_URL}/{oid}'
     order_description['state'] = 'cancelled'
     mock_resp = httpx.Response(HTTPStatus.OK, json=order_description)
+    example_resp = mock_resp.json()
     respx.put(cancel_url).return_value = mock_resp
 
-    # TODO: the api says cancel order returns the order details but as
-    # far as I can test thus far, it returns nothing. follow up on this
     cl = OrdersClient(session, base_url=TEST_URL)
-    await cl.cancel_order(oid)
+    json_resp = await cl.cancel_order(oid)
+    assert json_resp == example_resp
 
 
 @pytest.mark.asyncio
diff --git a/tests/integration/test_orders_cli.py b/tests/integration/test_orders_cli.py
index 506c89e..9d22d7a 100644
--- a/tests/integration/test_orders_cli.py
+++ b/tests/integration/test_orders_cli.py
@@ -177,7 +177,7 @@ def test_cli_orders_cancel(invoke, oid, order_description):
 
     result = invoke(['cancel', oid])
     assert not result.exception
-    assert 'Cancelled\n' == result.output
+    assert str(mock_resp.json()) + '\n' == result.output
 
 
 @respx.mock