Add filtering and sorting parameters to the orders list command

whipps · whipps · commit 28b5e065382e · 2024-12-05T16:27:47.000-07:00
diff --git a/docs/cli/cli-orders.md b/docs/cli/cli-orders.md
@@ -15,9 +15,10 @@ then check out our [CLI Concepts](cli-intro.md) guide.
 
 ## Core Workflows
 
-### See Recent Orders
+### List Orders
 
-You can use the `list` command to show your recent orders:
+You can use the `list` command to see details of existing orders. By default they will be sorted
+by most recently created.
 
 ```sh
 planet orders list
@@ -26,24 +27,10 @@ planet orders list
 If you’ve not placed any orders with Explorer, the CLI or the API directly, then the results
 of this call will be blank, so you may want to try out some of the create order commands below.
 
-Sometimes that list gets too long, so you can put a limit on how many are returned:
+Sometimes that list gets too long, so you can put a limit on how many are returned using the
+`--limit` parameter.
 
-```sh
-planet orders list --limit 5
-```
-
-You can also filter orders by their `state`, which can be useful to just see orders in 
-progress:
-
-```sh
-planet orders list --state running
-```
-
-The other options are queued, failed, success, partial and cancelled.
-
-Note you can also get a nice list online as well, at https://www.planet.com/account/#/orders
-
-### Recent Orders with Formatting
+#### Formatting
 
 You can also print the list of orders more nicely:
 
@@ -71,10 +58,13 @@ planet orders list | jq -rs '.[] | "\(.id) \(.created_on) \(.state) \(.name)"'
 
 You can customize which fields you want to show by changing the values.
 
-### Number of recent orders
+A list of your orders can also be viewed in a UI at https://www.planet.com/account/#/orders
 
-You can use jq to process the output for more insight, like 
-get a count of how many recent orders you’ve done. 
+#### Number of existing orders
+
+You can use jq to process the output for more insight, like get a count of how many existing
+orders you have. Orders are automatically deleted 90 days after completion, so this number
+roughly is equivalent to the number of orders created in the last 90 days.
 
 ```sh
 planet orders list | jq -s length
@@ -83,6 +73,65 @@ planet orders list | jq -s length
 This uses `-s` to collect the output into a single array, and `length` then tells the
 length of the array.
 
+#### Filtering
+
+The `list` command supports filtering on a variety of fields:
+* `--state`: Filter by one or more states. Options include `queued`, `failed`, `success`, `partial` and `cancelled`.
+* `--source-type`: Filter by one or more source types. Options include `scenes`, `basemaps`, or `all`. The default is `all`.
+* `--name`: Filter by name.
+* `--name-contains`: Only return orders with a name that contains the provided string.
+* `--created-on`: Filter on the order creation time or an interval of creation times.
+* `--last-modified`: Filter on the order's last modified time or an interval of last modified times.
+* `--hosting`: Filter on orders containing a hosting location (e.g. SentinelHub). Accepted values are `true` or `false`.
+
+Datetime args (`--created-on` and `--last-modified`) can either be a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.
+* A date-time: `2018-02-12T23:20:50Z`
+* A closed interval: `2018-02-12T00:00:00Z/2018-03-18T12:31:12Z`
+* Open intervals: `2018-02-12T00:00:00Z/..` or `../2018-03-18T12:31:12Z`
+
+To list orders in progress:
+```sh
+planet orders list --state running
+```
+
+To list orders with the `scenes` source type:
+```sh
+planet orders list --source-type scenes
+```
+
+To list orders that were created in 2024:
+```sh
+planet orders list --created-on 2024-01-01T00:00:00Z/2025-01-01T00:00:00Z
+```
+
+To list orders with a hosting location:
+```sh
+planet orders list --hosting true
+```
+
+To list orders with the name `my location xyz`:
+```sh
+planet orders list --name "my location xyz"
+```
+
+To list orders with a name containing `xyz`:
+```sh
+planet orders list --name-contains xyz
+```
+
+#### Sorting
+
+The `list` command also supports sorting the orders on one or more fields: `name`, `created_on`, `state`, and `last_modified`. The sort direction can be specified by appending ` ASC` or ` DESC` to the field name (default is ascending).
+
+When multiple fields are specified, the sort order is applied in the order the fields are listed.
+
+Sorting examples:
+* `--sort-by name`: sorts orders by name alphabetically.
+* `--sort-by "created_on DESC"`: sorts orders by most recently created.
+* `--sort-by "last_modified DESC"`: sorts subscriptions by most recently modified.
+* `--sort-by "state ASC"`: sorts orders by state alphabetically.
+* `--sort-by "name,last_modified DESC"`: sorts subscriptions by name first, and most recently modified second.
+
 ### Info on an Order
 
 For a bit more information about an order, including the location of any downloads, use
diff --git a/planet/cli/orders.py b/planet/cli/orders.py
@@ -54,22 +54,74 @@ def orders(ctx, base_url):
 @translate_exceptions
 @coro
 @click.option('--state',
-              help='Filter orders to given state.',
+              help='Filter by one or more states.',
+              multiple=True,
               type=click.Choice(planet.clients.orders.ORDER_STATE_SEQUENCE,
                                 case_sensitive=False))
+@click.option(
+    '--source-type',
+    default=["all"],
+    multiple=True,
+    help="""Filter by one or more source types. See documentation for all
+    available types. Default is all.""")
+@click.option('--name', help="filter by name")
+@click.option(
+    '--name-contains',
+    help="only return orders with a name that contains the provided string.")
+@click.option(
+    '--created-on',
+    help="Filter by creation time or interval. See documentation for examples."
+)
+@click.option(
+    '--last-modified',
+    help="Filter by creation time or interval. See documentation for examples."
+)
+@click.option(
+    '--hosting',
+    type=click.BOOL,
+    help="Filter by presence of hosting block (e.g. SentinelHub hosting).")
+@click.option(
+    '--sort-by',
+    help="""fields to sort orders by. Multiple fields can be specified,
+    separated by commas. The sort direction can be specified by appending
+    ' ASC' or ' DESC' to the field name. The default sort direction is
+    ascending. When multiple fields are specified, the sort order is applied
+    in the order the fields are listed.
+
+    Supported fields: [name, created_on, state, last_modified].
+
+    Example: 'name ASC,created_on DESC'""")
 @limit
 @pretty
-async def list(ctx, state, limit, pretty):
+async def list(ctx,
+               state,
+               source_type,
+               name,
+               name_contains,
+               created_on,
+               last_modified,
+               hosting,
+               sort_by,
+               limit,
+               pretty):
     """List orders
 
     This command prints a sequence of the returned order descriptions,
     optionally pretty-printed.
 
-    Order descriptions are sorted by creation date with the last created order
+    By default, order descriptions are sorted by creation date with the last created order
     returned first.
     """
     async with orders_client(ctx) as cl:
-        async for o in cl.list_orders(state=state, limit=limit):
+        async for o in cl.list_orders(state=state,
+                                      source_type=source_type,
+                                      name=name,
+                                      name__contains=name_contains,
+                                      created_on=created_on,
+                                      last_modified=last_modified,
+                                      hosting=hosting,
+                                      sort_by=sort_by,
+                                      limit=limit):
             echo_json(o, pretty)
 
 
diff --git a/planet/clients/orders.py b/planet/clients/orders.py
@@ -16,7 +16,7 @@
 import asyncio
 import logging
 import time
-from typing import AsyncIterator, Callable, List, Optional
+from typing import AsyncIterator, Callable, List, Optional, Sequence
 import uuid
 import json
 import hashlib
@@ -463,11 +463,18 @@ async def wait(self,
         return current_state
 
     async def list_orders(self,
-                          state: Optional[str] = None,
+                          state: Optional[Sequence[str]] = None,
+                          source_type: Optional[Sequence[str]] = None,
+                          name: Optional[str] = None,
+                          name__contains: Optional[str] = None,
+                          created_on: Optional[str] = None,
+                          last_modified: Optional[str] = None,
+                          hosting: Optional[bool] = None,
+                          sort_by: Optional[str] = None,
                           limit: int = 100) -> AsyncIterator[dict]:
         """Iterate over the list of stored orders.
 
-        Order descriptions are sorted by creation date with the last created
+        By default, order descriptions are sorted by creation date with the last created
         order returned first.
 
         Note:
@@ -476,10 +483,38 @@ async def list_orders(self,
             single result description or return a list of descriptions.
 
         Parameters:
-            state: Filter orders to given state.
-            limit: Maximum number of results to return. When set to 0, no
+            state (Set[str]): include orders with a state in this set.
+            source_type (Set[str]): include orders with a source type in this set.
+            name (str): filter by name.
+            name__contains (str): only include orders with names containing this string.
+            created_on (str): filter by creation date-time or interval.
+            last_modified (str): filter by last modified date-time or interval.
+            hosting (bool): only return orders that contain a hosting block
+                (e.g. SentinelHub hosting).
+            sort_by (str): fields to sort orders by. Multiple fields can be specified,
+                separated by commas. The sort direction can be specified by appending
+                ' ASC' or ' DESC' to the field name. The default sort direction is
+                ascending. When multiple fields are specified, the sort order is applied
+                in the order the fields are listed.
+
+                Supported fields: name, created_on, state, last_modified
+
+                Examples:
+                 * "name"
+                 * "name DESC"
+                 * "name,state DESC,last_modified"
+            limit (int): maximum number of results to return. When set to 0, no
                 maximum is applied.
 
+        Datetime args (created_on and last_modified) can either be a date-time or an
+        interval, open or closed. Date and time expressions adhere to RFC 3339. Open
+        intervals are expressed using double-dots.
+
+        Examples:
+            * A date-time: "2018-02-12T23:20:50Z"
+            * A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
+            * Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
+
         Yields:
             Description of an order.
 
@@ -488,14 +523,30 @@ async def list_orders(self,
             planet.exceptions.ClientError: If state is not valid.
         """
         url = self._orders_url()
-        params = {"source_type": "all"}
-
+        params = {}
+        if source_type is not None:
+            params["source_type"] = [val for val in source_type]
+        else:
+            params["source_type"] = "all"
+        if name is not None:
+            params["name"] = name
+        if name__contains is not None:
+            params["name__contains"] = name__contains
+        if created_on is not None:
+            params["created_on"] = created_on
+        if last_modified is not None:
+            params["last_modified"] = last_modified
+        if hosting is not None:
+            params["hosting"] = hosting
+        if sort_by is not None:
+            params["sort_by"] = sort_by
         if state:
-            if state not in ORDER_STATE_SEQUENCE:
-                raise exceptions.ClientError(
-                    f'Order state ({state}) is not a valid state. '
-                    f'Valid states are {ORDER_STATE_SEQUENCE}')
-            params['state'] = state
+            for s in state:
+                if s not in ORDER_STATE_SEQUENCE:
+                    raise exceptions.ClientError(
+                        f'Order state ({s}) is not a valid state. '
+                        f'Valid states are {ORDER_STATE_SEQUENCE}')
+            params['state'] = [val for val in state]
 
         response = await self._session.request(method='GET',
                                                url=url,
