Merge branch 'main' into carl/oauth-via-plauth-lib

Author: carl-adams-planet

CHANGES.txt

@@ -1,3 +1,19 @@
+2.13.0 (2024-12-18)
+- Add Planet class (`from planet import Planet`)
+  - Planet is a client that uses sync methods. Users do not have 
+    to interact with asyncio to use the sync client.
+  - the Planet class is implemented by calling out to the async methods.
+    This should be transparent to users. Depending on uptake and feedback,
+    the underlying implementation may change in the future (but we will commit
+    to semantic versioning when it comes to breaking changes in the API).
+
+2.12.0 (2024-12-09)
+- Add parameters to the subscriptions list command: --source-type, --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.
+- Remove the unused limit parameter of SubscriptionsClient.get_results_csv
+
 2.11.0 (2024-10-21)
 
 Added:
@@ -448,4 +464,4 @@ package is coming soon. The highlights are
 
 0.0.1 (2015-07-17)
 ------------------
-- Initial release
+- Initial release

CONTRIBUTING.md

@@ -141,15 +141,15 @@ These commands can be performed on the entire repository, when run from the repo
 and
 
 ```console
-    $ yapf --diff -r .
+    $ yapf --in-place -r .
 ```
 The configuration for YAPF is given in `setup.cfg` and `.yapfignore`.
 See the YAPF link above for advanced usage.
 
 ##### Alternative to YAPF
 
 YAPF is not required to follow the style and formatting guidelines. You can
-perform all formatting on your own using the linting output as a guild. Painful,
+perform all formatting on your own using the linting output as a guide. Painful,
 maybe, but possible!
 
 ## Testing

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