From c4f9dc6de4976714212182f14a62c9cdcb520bde Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 2 May 2022 15:02:43 -0700 Subject: [PATCH 01/12] Replacing python quickstart with a CLI one --- README.md | 101 ++++++++++++++++++++---------------------------------- 1 file changed, 38 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 8c221d600..daf311251 100644 --- a/README.md +++ b/README.md @@ -32,82 +32,57 @@ Full documentation is not yet hosted online but can be built and hosted locally ## Quick Start -The Planet SDK for Python allows Python developers to write software that makes -use of the following Planet APIs: +The Planet SDK includes both a Python API and a command-line interface (CLI) +to make use of the following Planet APIs: * [orders](https://developers.planet.com/docs/orders/) * [data](https://developers.planet.com/docs/data/) (not yet implemented) * [subscriptions](https://developers.planet.com/docs/subscriptions/) (not yet implemented) -The client modules within the Python library are asynchronous, which greatly -speeds up many interactions with Planet's APIs. Support for asynchronous -development is native to Python 3.6+ via the -[`asyncio` module](https://docs.python.org/3/library/asyncio.html). A great -resource for getting started with asynchronous programming in Python is -https://project-awesome.org/timofurrer/awesome-asyncio. The Writings and Talks -sections are particularly helpful in getting oriented. - -Let's start with creating an order with the Orders API: - -```python ->>> import asyncio ->>> import os ->>> import planet ->>> ->>> request = { -... "name": "test_order", -... "products": [ -... { -... "item_ids": [ -... "3949357_1454705_2020-12-01_241c" -... ], -... "item_type": "PSOrthoTile", -... "product_bundle": "analytic" -... } -... ] -... } -... ->>> async def create_order(request): -... async with planet.Session() as ps: -... client = planet.OrdersClient(ps) -... return await client.create_order(request) -... ->>> oid = asyncio.run(create_order(request)) +This quickstart focuses on getting started with the CLI to place an Order. +After you've install the client, as explained in the [installation](#installation) +section below, you first you must initialize the client with your Planet +username and password: + +``` +% planet auth init +Email: +Password: +Initialized ``` -Not into async? No problem. Just wrap the library and async operations together -and call from your synchronous code. +The email address and password you use should be the same as your login to +[Planet Explorer](https://planet.com/explorer). The `auth init` command +will automatically get your API key and store it locally. -```python ->>> def sync_create_order(order_details): -... return asyncio.run(create_order(order_details)) ->>> ->>> oid = sync_create_order(order_details) +Now that you're initialized let's start with creating an order with the +Orders API: ``` +% planet orders create --name my-first-order --id \ + --item-type SkySatCollect --bundle visual +``` + +You should supply a unique name after `--name` for each new order, to help +you identify what oder. The `--id` is one or more scene ids (separated by +commas). These can be obtained from the data API, and you can also grab them +from any search in Planet Explorer. Just be sure the scene id matches the +[item-type](https://developers.planet.com/docs/apis/data/items-assets/#item-types) +to get the right type of image. And then be sure to specify a +[bundle](https://developers.planet.com/docs/orders/product-bundles-reference/). +The most common ones are `visual` and `analytic`. -When using `asyncio.run` to develop synchronous code with the async library, -keep in mind this excerpt from the -[asyncio.run](https://docs.python.org/3/library/asyncio-task.html#asyncio.run) -documentation: - -"*This function always creates a new event loop and closes it at the end. It -should be used as a main entry point for asyncio programs, and should ideally -only be called once.*" - -Do you have a use case where native synchronous support is essential? If so, -please contribute to this -[discussion](https://github.com/planetlabs/planet-client-python/issues/251). - -Why async? Because things get *really cool* when you want to work with multiple -orders. See [orders_create_and_download_multiple_orders.py](examples/orders_create_and_download_multiple_orders.py) for -an example of submitting two orders, waiting for them to complete, and -downloading them. The orders each clip a set of images to a specific area of -interest (AOI), so they cannot be combined into one order. -(hint: [Planet Explorer](https://www.planet.com/explorer/) was used to define -the AOIs and get the image ids.) +This will give you an order response JSON as shown in the 'example response' in +[the docs](https://developers.planet.com/docs/orders/ordering/#basic-ordering). You can +grab the `id` from that response and then use that in a single command to wait for +the order and download it when you are ready: + +``` +% planet orders wait dfdf3088-73a2-478c-a8f6-1bad1c09fa09 && planet orders \ + download dfdf3088-73a2-478c-a8f6-1bad1c09fa09 +``` ## Installation From 39d6b4896b979d692381e4694b52ab094f313fb0 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Tue, 3 May 2022 18:25:06 -0700 Subject: [PATCH 02/12] Capitalization fix Co-authored-by: Jennifer Reiber Kyle --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index daf311251..f141568df 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ to make use of the following Planet APIs: * [subscriptions](https://developers.planet.com/docs/subscriptions/) (not yet implemented) -This quickstart focuses on getting started with the CLI to place an Order. +This quickstart focuses on getting started with the CLI to place an order. After you've install the client, as explained in the [installation](#installation) section below, you first you must initialize the client with your Planet From 1f62b99474827b94755f4ba475b2fea4c4174142 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Tue, 3 May 2022 18:25:52 -0700 Subject: [PATCH 03/12] Update README.md % to $ Co-authored-by: Jennifer Reiber Kyle --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f141568df..e9bb887b8 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ section below, you first you must initialize the client with your Planet username and password: ``` -% planet auth init +$ planet auth init Email: Password: Initialized From aa8570ab19661284d103ccbd4ef7f4f34ae19497 Mon Sep 17 00:00:00 2001 From: Christopher Holmes Date: Sun, 8 May 2022 15:10:29 -0700 Subject: [PATCH 04/12] updates from PR review --- 20220505_172446_09_2435_metadata.json | 1 + README.md | 36 ++++++++++++++++++++++----- manifest.json | 1 + 3 files changed, 32 insertions(+), 6 deletions(-) create mode 100644 20220505_172446_09_2435_metadata.json create mode 100644 manifest.json diff --git a/20220505_172446_09_2435_metadata.json b/20220505_172446_09_2435_metadata.json new file mode 100644 index 000000000..9e75a4e3a --- /dev/null +++ b/20220505_172446_09_2435_metadata.json @@ -0,0 +1 @@ +{"id":"20220505_172446_09_2435","type":"Feature","geometry":{"coordinates":[[[-114.97278709534947,31.834848555620418],[-115.01848342682366,31.647068217995308],[-114.65195264871535,31.58163213917827],[-114.60561222537214,31.768471540991452],[-114.97278709534947,31.834848555620418]]],"type":"Polygon"},"properties":{"acquired":"2022-05-05T17:24:46.094538Z","anomalous_pixels":0,"clear_confidence_percent":92,"clear_percent":90,"cloud_cover":0.01,"cloud_percent":1,"ground_control":true,"gsd":4,"heavy_haze_percent":0,"instrument":"PSB.SD","item_type":"PSScene","light_haze_percent":0,"pixel_resolution":3,"provider":"planetscope","published":"2022-05-06T02:51:49Z","publishing_stage":"finalized","quality_category":"standard","satellite_azimuth":106.2,"satellite_id":"2435","shadow_percent":0,"snow_ice_percent":9,"strip_id":"5617930","sun_azimuth":109.5,"sun_elevation":56.7,"updated":"2022-05-07T19:26:41Z","view_angle":1.1,"visible_confidence_percent":76,"visible_percent":99}} diff --git a/README.md b/README.md index e9bb887b8..508ee7dba 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,8 @@ to make use of the following Planet APIs: yet implemented) This quickstart focuses on getting started with the CLI to place an order. +For information on the Python API see the +[documentation](https://planet-sdk-for-python.readthedocs.io/en/latest/) After you've install the client, as explained in the [installation](#installation) section below, you first you must initialize the client with your Planet @@ -61,8 +63,8 @@ Now that you're initialized let's start with creating an order with the Orders API: ``` -% planet orders create --name my-first-order --id \ - --item-type SkySatCollect --bundle visual +$ planet orders create --name my-first-order --id \ + --item-type PSScene --bundle visual ``` You should supply a unique name after `--name` for each new order, to help @@ -75,15 +77,37 @@ to get the right type of image. And then be sure to specify a The most common ones are `visual` and `analytic`. This will give you an order response JSON as shown in the 'example response' in -[the docs](https://developers.planet.com/docs/orders/ordering/#basic-ordering). You can -grab the `id` from that response and then use that in a single command to wait for -the order and download it when you are ready: +[the Order API docs](https://developers.planet.com/docs/orders/ordering/#basic-ordering). +You can grab the `id` from that response, which will look something like +`dfdf3088-73a2-478c-a8f6-1bad1c09fa09`. You can then use that in a single +command to wait for the order and download it when you are ready: ``` -% planet orders wait dfdf3088-73a2-478c-a8f6-1bad1c09fa09 && planet orders \ +$ planet orders wait dfdf3088-73a2-478c-a8f6-1bad1c09fa09 && planet orders \ download dfdf3088-73a2-478c-a8f6-1bad1c09fa09 ``` +This usually takes at least a few minutes, and can be longer if it is a large request +(lots of items or big items like SkySatCollect). The default `wait` will last about +15 minutes, but can easily be extended. + +You can also just wait to download until the order is fulfilled. To check on its status +just use: + +``` +$ planet orders get dfdf3088-73a2-478c-a8f6-1bad1c09fa09 +``` + +And then use `planet download ` when the order is ready. + +There are many more options in the command-line interface. One of the best ways +to explore is to just use `--help` after any command to see the options. There is +also lots of good information in the docs, in the +[User Guide](https://planet-sdk-for-python.readthedocs.io/en/latest/guide/#cli) +and the [CLI Reference](https://planet-sdk-for-python.readthedocs.io/en/latest/cli/). + + + ## Installation Install with [pip](https://pip.pypa.io): diff --git a/manifest.json b/manifest.json new file mode 100644 index 000000000..00f5e4998 --- /dev/null +++ b/manifest.json @@ -0,0 +1 @@ +{"name":"","files":[{"path":"PSScene/20220505_172446_09_2435_metadata.json","media_type":"application/json","size":980,"digests":{"md5":"e205084e6770218f9ccdfee88ed81fc2","sha256":"d52c8b69fcca58847e35b49b9927e40c5d023c341c1ae11cf5bb941bdd5fce84"},"annotations":{"planet/item_id":"20220505_172446_09_2435","planet/item_type":"PSScene"}},{"path":"PSScene/20220505_172446_09_2435_3B_Visual.tif","media_type":"image/tiff","size":191395964,"digests":{"md5":"d8764f391d0b95f4c48cf767ebec882d","sha256":"589885497bf22f8c11cfbde1d7acf4bca436f72ce51288060f6fd68f9b448b61"},"annotations":{"planet/asset_type":"ortho_visual","planet/bundle_type":"visual","planet/item_id":"20220505_172446_09_2435","planet/item_type":"PSScene"}}]} \ No newline at end of file From 14c72b8f59a31c7d60af67386c55f9f79ef5fa3f Mon Sep 17 00:00:00 2001 From: Christopher Holmes Date: Mon, 9 May 2022 10:27:21 -0700 Subject: [PATCH 05/12] removed mistakenly committed files --- 20220505_172446_09_2435_metadata.json | 1 - manifest.json | 1 - 2 files changed, 2 deletions(-) delete mode 100644 20220505_172446_09_2435_metadata.json delete mode 100644 manifest.json diff --git a/20220505_172446_09_2435_metadata.json b/20220505_172446_09_2435_metadata.json deleted file mode 100644 index 9e75a4e3a..000000000 --- a/20220505_172446_09_2435_metadata.json +++ /dev/null @@ -1 +0,0 @@ -{"id":"20220505_172446_09_2435","type":"Feature","geometry":{"coordinates":[[[-114.97278709534947,31.834848555620418],[-115.01848342682366,31.647068217995308],[-114.65195264871535,31.58163213917827],[-114.60561222537214,31.768471540991452],[-114.97278709534947,31.834848555620418]]],"type":"Polygon"},"properties":{"acquired":"2022-05-05T17:24:46.094538Z","anomalous_pixels":0,"clear_confidence_percent":92,"clear_percent":90,"cloud_cover":0.01,"cloud_percent":1,"ground_control":true,"gsd":4,"heavy_haze_percent":0,"instrument":"PSB.SD","item_type":"PSScene","light_haze_percent":0,"pixel_resolution":3,"provider":"planetscope","published":"2022-05-06T02:51:49Z","publishing_stage":"finalized","quality_category":"standard","satellite_azimuth":106.2,"satellite_id":"2435","shadow_percent":0,"snow_ice_percent":9,"strip_id":"5617930","sun_azimuth":109.5,"sun_elevation":56.7,"updated":"2022-05-07T19:26:41Z","view_angle":1.1,"visible_confidence_percent":76,"visible_percent":99}} diff --git a/manifest.json b/manifest.json deleted file mode 100644 index 00f5e4998..000000000 --- a/manifest.json +++ /dev/null @@ -1 +0,0 @@ -{"name":"","files":[{"path":"PSScene/20220505_172446_09_2435_metadata.json","media_type":"application/json","size":980,"digests":{"md5":"e205084e6770218f9ccdfee88ed81fc2","sha256":"d52c8b69fcca58847e35b49b9927e40c5d023c341c1ae11cf5bb941bdd5fce84"},"annotations":{"planet/item_id":"20220505_172446_09_2435","planet/item_type":"PSScene"}},{"path":"PSScene/20220505_172446_09_2435_3B_Visual.tif","media_type":"image/tiff","size":191395964,"digests":{"md5":"d8764f391d0b95f4c48cf767ebec882d","sha256":"589885497bf22f8c11cfbde1d7acf4bca436f72ce51288060f6fd68f9b448b61"},"annotations":{"planet/asset_type":"ortho_visual","planet/bundle_type":"visual","planet/item_id":"20220505_172446_09_2435","planet/item_type":"PSScene"}}]} \ No newline at end of file From b31ed8700d289bf20b13dd35c578eef9b26ee3ee Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 9 May 2022 10:27:58 -0700 Subject: [PATCH 06/12] added console formatting Co-authored-by: Jennifer Reiber Kyle --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 508ee7dba..2581be6b1 100644 --- a/README.md +++ b/README.md @@ -94,8 +94,8 @@ This usually takes at least a few minutes, and can be longer if it is a large re You can also just wait to download until the order is fulfilled. To check on its status just use: -``` -$ planet orders get dfdf3088-73a2-478c-a8f6-1bad1c09fa09 +```console +$ planet orders get ``` And then use `planet download ` when the order is ready. From facf79bd25bb4f8c652d56c994564ceafbeb051e Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 9 May 2022 10:28:15 -0700 Subject: [PATCH 07/12] Explained how to extend time Co-authored-by: Jennifer Reiber Kyle --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2581be6b1..07673a28d 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ $ planet orders wait dfdf3088-73a2-478c-a8f6-1bad1c09fa09 && planet orders \ This usually takes at least a few minutes, and can be longer if it is a large request (lots of items or big items like SkySatCollect). The default `wait` will last about -15 minutes, but can easily be extended. +15 minutes, but can easily be extended with the `--max-attempts` option. You can also just wait to download until the order is fulfilled. To check on its status just use: From e986c9c501c90e35bf85da5671f40e138ed9d0ad Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 9 May 2022 10:28:23 -0700 Subject: [PATCH 08/12] added console formatting Co-authored-by: Jennifer Reiber Kyle --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 07673a28d..b97ce53fd 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ After you've install the client, as explained in the [installation](#installatio section below, you first you must initialize the client with your Planet username and password: -``` +```console $ planet auth init Email: Password: From 2a676e9f1cbe8b0d5951d0ee4d7e95a251ef8a55 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 9 May 2022 10:28:33 -0700 Subject: [PATCH 09/12] added console formatting Co-authored-by: Jennifer Reiber Kyle --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b97ce53fd..149362434 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ will automatically get your API key and store it locally. Now that you're initialized let's start with creating an order with the Orders API: -``` +```console $ planet orders create --name my-first-order --id \ --item-type PSScene --bundle visual ``` From 231f29a55714d5e7b0ae31192ae1a4ff129cea75 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 9 May 2022 10:28:40 -0700 Subject: [PATCH 10/12] Update README.md Co-authored-by: Jennifer Reiber Kyle --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 149362434..ee71d8175 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ Orders API: ```console $ planet orders create --name my-first-order --id \ - --item-type PSScene --bundle visual + --item-type PSScene --bundle visual ``` You should supply a unique name after `--name` for each new order, to help From 8e1bbe3592b914db6de47465c2056148cb230664 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 9 May 2022 10:28:46 -0700 Subject: [PATCH 11/12] added console formatting Co-authored-by: Jennifer Reiber Kyle --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ee71d8175..fe89cb077 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ You can grab the `id` from that response, which will look something like `dfdf3088-73a2-478c-a8f6-1bad1c09fa09`. You can then use that in a single command to wait for the order and download it when you are ready: -``` +```console $ planet orders wait dfdf3088-73a2-478c-a8f6-1bad1c09fa09 && planet orders \ download dfdf3088-73a2-478c-a8f6-1bad1c09fa09 ``` From 6bf5e24bb3f5bd49b55b1b98ebc69e05325cac97 Mon Sep 17 00:00:00 2001 From: Christopher Holmes Date: Mon, 9 May 2022 11:32:35 -0700 Subject: [PATCH 12/12] updates from pr review --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index fe89cb077..dfc2f8ede 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ Now that you're initialized let's start with creating an order with the Orders API: ```console -$ planet orders create --name my-first-order --id \ +$ planet orders create --name my-first-order --id \ --item-type PSScene --bundle visual ``` @@ -79,12 +79,11 @@ The most common ones are `visual` and `analytic`. This will give you an order response JSON as shown in the 'example response' in [the Order API docs](https://developers.planet.com/docs/orders/ordering/#basic-ordering). You can grab the `id` from that response, which will look something like -`dfdf3088-73a2-478c-a8f6-1bad1c09fa09`. You can then use that in a single -command to wait for the order and download it when you are ready: +`dfdf3088-73a2-478c-a8f6-1bad1c09fa09`. You can then use that order-id in a +single command to wait for the order and download it when you are ready: ```console -$ planet orders wait dfdf3088-73a2-478c-a8f6-1bad1c09fa09 && planet orders \ - download dfdf3088-73a2-478c-a8f6-1bad1c09fa09 +$ planet orders wait && planet orders download ``` This usually takes at least a few minutes, and can be longer if it is a large request