Merge pull request #1079 from planetlabs/DND-1610_new_orders_and_subs_params

Add filtering/sorting parameters to the subscriptions & orders list commands

Author: HenryW95

CHANGES.txt

@@ -1,3 +1,9 @@
+2.12.0 (2024-12-06)
+- Add parameters to the subscriptions list command: --created, --start-time,
+  --end-time, --updated, --hosting, --name, --name-contains, and --sort-by.
+- Add parameters to the orders list command: --source-type, --name,
+  --name-contains, --created-on, --last-modified, --hosting, and --sort-by.
+
 2.11.0 (2024-10-21)
 
 Added:

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 order state. Options include `queued`, `failed`, `success`, `partial` and `cancelled`.
+* `--source-type`: Filter by source type. 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

docs/cli/cli-subscriptions.md

@@ -117,8 +117,7 @@ To create a new subscription with the CLI, use the `create` command and the json
 planet subscriptions create my-subscription.json
 ```
 
-!!!note "Note"
-    The above command assumes that you’ve saved the subscriptions JSON as `my-subscription.json` and that you’ve replaced the delivery information with your own bucket and credentials.
+**Note:** The above command assumes that you’ve saved the subscriptions JSON as `my-subscription.json` and that you’ve replaced the delivery information with your own bucket and credentials.
 
 ### List Subscriptions
 
@@ -134,23 +133,62 @@ parameter higher, or you can set it to 0 and there will be no limit.
 You can get nicer formatting with `--pretty` or pipe it into `jq`, just like the other Planet
 CLI’s.
 
-The `list` command supports filtering by the status of the subscription:
-
+#### Filtering
+
+The `list` command supports filtering on a variety of fields:
+* `--created`: Filter on the subscription creation time or an interval of creation times.
+* `--end-time`: Filter on the subscription end time or an interval of end times.
+* `--hosting`: Filter on subscriptions containing a hosting location (e.g. SentinelHub). Accepted values are `true` or `false`.
+* `--name-contains`: Filter on subscriptions with a name that contains the provided string.
+* `--name`: Filter on subscriptions with a specific name
+* `--source-type`: Filter by the source type of the subscription. For the full list of available source types, see [Subscription Source Types](https://developers.planet.com/docs/subscriptions/source/#subscription-source-types). Multiple source type args are allowed.
+* `--start-time`: Filter on the subscription start time or an interval of start times.
+* `--status`: Filter on the status of the subscription. Status options include `running`, `cancelled`, `preparing`, `pending`, `completed`, `suspended`, and `failed`. Multiple status args are allowed.
+* `--updated`: Filter on the subscription update time or an interval of updated times.
+
+Datetime args (`--created`, `end-time`, `--start-time`, and `--updated`) 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 currently active subscriptions:
 ```sh
 planet subscriptions list --status running
 ```
 
-gives you just the currently active subscriptions. The other available statuses are:
-`cancelled`, `preparing`, `pending`, `completed`, `suspended`, and `failed`.
+To list subscriptions with the `catalog` source type:
+```sh
+planet subscriptions list --source-type catalog
+```
 
-The `list` command also supports filtering by the source type of the subscription:
+To list subscriptions that were created in 2024:
+```sh
+planet subscriptions list --created 2024-01-01T00:00:00Z/2025-01-01T00:00:00Z
+```
 
+To list subscriptions with an end time after Jan 1, 2025:
 ```sh
-planet subscriptions list --source-type catalog
+planet subscriptions list --end-time 2025-01-01T00:00:00Z/..
 ```
 
-only gives you subscriptions with the `catalog` source type. For the full list of available source types, 
-see [Subscription Source Types](https://developers.planet.com/docs/subscriptions/source/#subscription-source-types).
+To list subscriptions with a hosting location:
+```sh
+planet subscriptions list --hosting true
+```
+
+#### Sorting
+
+The `list` command also supports sorting the subscriptions on one or more fields: `name`, `created`, `updated`, `start_time`, and `end_time`. 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 subscriptions by name alphabetically.
+* `--sort-by "created DESC"`: sorts subscriptions by most recently created.
+* `--sort-by "updated DESC"`: sorts subscriptions by most recently updated.
+* `--sort-by "start_time ASC"`: sorts subscriptions by start time (earliest to latest)
+* `--sort-by "end_time DESC"`: sorts subscriptions by end time (latest to earliest)
+* `--sort-by "name,start_time DESC"`: sorts subscriptions by name ascending first, and start time descending second.
 
 ### Get Subscription
 

planet/cli/orders.py

@@ -54,22 +54,72 @@ def orders(ctx, base_url):
 @translate_exceptions
 @coro
 @click.option('--state',
-              help='Filter orders to given state.',
+              help='Filter by state.',
               type=click.Choice(planet.clients.orders.ORDER_STATE_SEQUENCE,
                                 case_sensitive=False))
+@click.option(
+    '--source-type',
+    default="all",
+    help="""Filter by source type. 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)
 
 

planet/cli/subscriptions.py

@@ -64,6 +64,32 @@ def subscriptions(ctx, base_url):
 # command function as "list_subscriptions".
 @subscriptions.command(name="list")  # type: ignore
 @pretty
+@click.option(
+    '--created',
+    help="""Filter subscriptions by creation time or interval. See documentation
+    for examples.""")
+@click.option(
+    '--end-time',
+    help="""Filter subscriptions by end time or interval. See documentation
+    for examples.""")
+@click.option(
+    '--hosting',
+    type=click.BOOL,
+    help="""Filter subscriptions by presence of hosting block (e.g. SentinelHub
+    hosting).""")
+@click.option(
+    '--name-contains',
+    help="""only return subscriptions with a name that contains the provided
+    string.""")
+@click.option('--name', help="filter by name")
+@click.option(
+    '--source-type',
+    help="""Filter subscriptions by source type. See documentation for all
+    available types. Default is all.""")
+@click.option(
+    '--start-time',
+    help="""Filter subscriptions by start time or interval. See documentation
+    for examples.""")
 @click.option(
     '--status',
     type=click.Choice([
@@ -76,23 +102,52 @@ def subscriptions(ctx, base_url):
         "failed"
     ]),
     multiple=True,
-    default=None,
     help="Select subscriptions in one or more states. Default is all.")
-@click.option(
-    '--source-type',
-    default=None,
-    help="Filter subscriptions by source type. See documentation for all "
-    "available types. Default is all.")
+@click.option('--sort-by',
+              help="""fields to sort subscriptions 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, updated, start_time, end_time].
+
+    Example: 'name ASC,created DESC'""")
+@click.option('--updated',
+              help="""Filter subscriptions by update time or interval. See
+    documentation
+    for examples.""")
 @limit
 @click.pass_context
 @translate_exceptions
 @coro
-async def list_subscriptions_cmd(ctx, status, source_type, limit, pretty):
+async def list_subscriptions_cmd(ctx,
+                                 created,
+                                 end_time,
+                                 hosting,
+                                 name_contains,
+                                 name,
+                                 source_type,
+                                 start_time,
+                                 status,
+                                 sort_by,
+                                 updated,
+                                 limit,
+                                 pretty):
     """Prints a sequence of JSON-encoded Subscription descriptions."""
     async with subscriptions_client(ctx) as client:
-        async for sub in client.list_subscriptions(status=status,
-                                                   source_type=source_type,
-                                                   limit=limit):
+        async for sub in client.list_subscriptions(
+                created=created,
+                end_time=end_time,
+                hosting=hosting,
+                name__contains=name_contains,
+                name=name,
+                source_type=source_type,
+                start_time=start_time,
+                status=status,
+                sort_by=sort_by,
+                updated=updated,
+                limit=limit):
             echo_json(sub, pretty)