From 826ecf5be75eebcd1ed846a092f25e25a5ba1978 Mon Sep 17 00:00:00 2001 From: JuLee Burdekin Date: Sun, 20 Nov 2022 20:56:41 -0800 Subject: [PATCH 1/7] Created Upgrade Content 784 --- docs/get-started/upgrading.md | 74 +++++++++++++++++++++++++++++------ 1 file changed, 61 insertions(+), 13 deletions(-) diff --git a/docs/get-started/upgrading.md b/docs/get-started/upgrading.md index b1793b8a7..e915e88ab 100644 --- a/docs/get-started/upgrading.md +++ b/docs/get-started/upgrading.md @@ -2,19 +2,67 @@ title: Upgrading from V1 to V2 --- -The Planet SDK for Python is Version 2 of what was previously referred to as -the Planet API client. +The Planet SDK for Python is Version 2 of what was previously referred to as the Planet API client. This V2 is a major update of the V1 SDK. As such, there are major structural changes to how it operates. However, many aspects are still quite similar to V1. Follow this migration guide to upgrade an application developed with v1 of the SDK to V2 with minimal fuss. -Version 2 is essentially a complete rewrite and brings with it big changes to -the Python library. +## Imports + +The V2 SDK has a flatter code structure. Everything of note previously found under `planet.api` is now available from the `planet` module. So, `import planet` should give you everything you need. + +If you are migrating from V1, and were using the Data API filter builder (from `planet.api import filters`), we do recommend also including `from planet import data_filter as filters` in your imports for an easy migration from the old filter module to the new one. + +## Authentication In Version 1, a single client was created for all APIs, -`client=api.ClientV1(api_key=API_KEY)`. With this client, all commumication was -synchronous. Asynchronous bulk support was provided with the `downloader` -module. There was no built-in support for polling when an order was -ready to download or tracking when an order was downloaded. - -In Version 2, a `Session` is used to manage all communication with the Planet -APIs. This provides for multiple asynchronous connections. An API-specific -client is created. This client manages polling and downloading, along with -any other capabilities provided by the API. +`client=api.ClientV1(api_key=API_KEY)`. To authenticate automatically in V2, use an API key stored in the `PL_API_KEY` environment variable by adding `planet.Auth.from_env(`PL_API_KEY`).write()` to the first line of your script. For other methods for authenticating against the SDK, check out [Authenticate with the Planet server](quick-start-guide/#authenticate-with-the-planet-server). + +## Session for all communication + +In Version 2, sessions are used to manage all communication with the Planet APIs. This provides for multiple asynchronous connections. An API-specific client is created. This client manages polling and downloading, along with any other capabilities provided by the API. + +Each client now requires a `Session` object, which stores connection information and authentication. + +The best way of doing this is wrapping any code that invokes a client class in a block like so: + +```python +async with Session() as session: + client = OrdersClient(session) + result = await client.create_order(order) +# Process result +``` + +For more information about Session, refer to the [SDK user guide](../../python/sdk-guide/#session). + +# Asynchronous Methods + +With the V1 client, all commumication was synchronous. Asynchronous bulk support was provided with the `downloader` module. There was no built-in support for polling when an order was ready to download or tracking when an order was downloaded. + +In V2, all `*Client` methods (for example, `DataClient().quick_search`, `OrderClient().create_order`) are asynchronous. Any functions that call such methods must include `async` in their definition. To invoke asynchronous methods from synchronous code, you can wrap the async method calls in `asyncio.run()`. + +For more details on interacting with the asynchronous portions of the SDK, refer to the [SDK user guide](../../python/sdk-guide/#session). + +# Data API +The Data API portion of SDK V2 is quite similar to V1, although some filters have been renamed for consistency (also reference the note on imports): + +* `date_range` to `date_range_filter` +* `geom_filter` to `geometry_filter` +* `and_filter` and `or_filter` now takes a list of filters instead of multiple arguments, so just wrap the contents in `[]` +* `permissions_filter` is now split into `permissions_filter` and `asset_filter`, reflecting a recent change in API structure. If you were using this previously, you’ll want to convert the old `permissions_filter` into an `asset_filter` (this also involves changing the filter values, e.g. `assets.ortho_analytic_8b_sr:download` will become `ortho_analytic_8b_sr`) and adding an empty `permissions_filter`. + +`filters.build_seach_request` no longer exists, and has instead been integrated into the replacement for `client.quick_seach`. For example: + +```console +planet.api.ClientV1().quick_search(filters.build_search_request(all_filters, ["PSScene"])) +``` + +Is now + +```console +async with Session() as session: +planet.DataClient(session).quick_search(["PSScene"], all_filters) +``` + +# Orders API + +The Orders API capabilities in V1 were quite primitive, but those that did exist have been retained in much the same form; `ClientV1().create_order` becomes `OrderClient(session).create_order`. (As with the `DataClient`, you must also use `async` and `Session` with `OrderClient`.) + +Additionally, there is now also an order builder in `planet.order_request`, similar to the preexisting search filter builder. For more details on this, refer to the [Creating an Order](../../python/sdk-guide/#creating-an-order). From de19b60de4693ce17bbbf7873f181193c17084b9 Mon Sep 17 00:00:00 2001 From: JuLee Burdekin Date: Sun, 20 Nov 2022 20:56:54 -0800 Subject: [PATCH 2/7] Created Upgrade Content 784 --- docs/get-started/upgrading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-started/upgrading.md b/docs/get-started/upgrading.md index e915e88ab..e0ad3fae2 100644 --- a/docs/get-started/upgrading.md +++ b/docs/get-started/upgrading.md @@ -1,5 +1,5 @@ --- -title: Upgrading from V1 to V2 +title: Upgrade from Version 1 to Version 2 --- The Planet SDK for Python is Version 2 of what was previously referred to as the Planet API client. This V2 is a major update of the V1 SDK. As such, there are major structural changes to how it operates. However, many aspects are still quite similar to V1. Follow this migration guide to upgrade an application developed with v1 of the SDK to V2 with minimal fuss. From 4a9c73342dc20cd4394f714a4ad19055fb8de841 Mon Sep 17 00:00:00 2001 From: JuLee Burdekin Date: Sun, 20 Nov 2022 21:12:05 -0800 Subject: [PATCH 3/7] typo fixes --- docs/get-started/upgrading.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/get-started/upgrading.md b/docs/get-started/upgrading.md index e0ad3fae2..c29c1229e 100644 --- a/docs/get-started/upgrading.md +++ b/docs/get-started/upgrading.md @@ -8,12 +8,12 @@ The Planet SDK for Python is Version 2 of what was previously referred to as the The V2 SDK has a flatter code structure. Everything of note previously found under `planet.api` is now available from the `planet` module. So, `import planet` should give you everything you need. -If you are migrating from V1, and were using the Data API filter builder (from `planet.api import filters`), we do recommend also including `from planet import data_filter as filters` in your imports for an easy migration from the old filter module to the new one. +If you are migrating from V1, and are using the Data API filter builder (from `planet.api import filters`), we do recommend also including `from planet import data_filter as filters` in your imports for an easy migration from the old filter module to the new one. ## Authentication In Version 1, a single client was created for all APIs, -`client=api.ClientV1(api_key=API_KEY)`. To authenticate automatically in V2, use an API key stored in the `PL_API_KEY` environment variable by adding `planet.Auth.from_env(`PL_API_KEY`).write()` to the first line of your script. For other methods for authenticating against the SDK, check out [Authenticate with the Planet server](quick-start-guide/#authenticate-with-the-planet-server). +`client=api.ClientV1(api_key=API_KEY)`. To authenticate automatically in V2, use an API key stored in the `PL_API_KEY` environment variable by adding `planet.Auth.from_env(PL_API_KEY).write()` to the first line of your script. For other methods for authenticating against the SDK, check out [Authenticate with the Planet server](quick-start-guide/#authenticate-with-the-planet-server). ## Session for all communication @@ -32,15 +32,15 @@ async with Session() as session: For more information about Session, refer to the [SDK user guide](../../python/sdk-guide/#session). -# Asynchronous Methods +## Asynchronous Methods -With the V1 client, all commumication was synchronous. Asynchronous bulk support was provided with the `downloader` module. There was no built-in support for polling when an order was ready to download or tracking when an order was downloaded. +With the V1 client, all communication was synchronous. Asynchronous bulk support was provided with the `downloader` module. There was no built-in support for polling when an order was ready to download or tracking when an order was downloaded. In V2, all `*Client` methods (for example, `DataClient().quick_search`, `OrderClient().create_order`) are asynchronous. Any functions that call such methods must include `async` in their definition. To invoke asynchronous methods from synchronous code, you can wrap the async method calls in `asyncio.run()`. For more details on interacting with the asynchronous portions of the SDK, refer to the [SDK user guide](../../python/sdk-guide/#session). -# Data API +## Data API The Data API portion of SDK V2 is quite similar to V1, although some filters have been renamed for consistency (also reference the note on imports): * `date_range` to `date_range_filter` @@ -61,7 +61,7 @@ async with Session() as session: planet.DataClient(session).quick_search(["PSScene"], all_filters) ``` -# Orders API +## Orders API The Orders API capabilities in V1 were quite primitive, but those that did exist have been retained in much the same form; `ClientV1().create_order` becomes `OrderClient(session).create_order`. (As with the `DataClient`, you must also use `async` and `Session` with `OrderClient`.) From 18baa5af63ede566c5a7c61d4ab0bd9ab70042d9 Mon Sep 17 00:00:00 2001 From: JuLee Burdekin Date: Mon, 21 Nov 2022 10:49:04 -0800 Subject: [PATCH 4/7] updated based on Torben's feedback --- docs/get-started/upgrading.md | 35 ++++++++++++++++++++++++++--------- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/docs/get-started/upgrading.md b/docs/get-started/upgrading.md index c29c1229e..5eb7d4dcb 100644 --- a/docs/get-started/upgrading.md +++ b/docs/get-started/upgrading.md @@ -2,7 +2,7 @@ title: Upgrade from Version 1 to Version 2 --- -The Planet SDK for Python is Version 2 of what was previously referred to as the Planet API client. This V2 is a major update of the V1 SDK. As such, there are major structural changes to how it operates. However, many aspects are still quite similar to V1. Follow this migration guide to upgrade an application developed with v1 of the SDK to V2 with minimal fuss. +The Planet SDK for Python is Version 2 of what was previously referred to as the Planet API client. This V2 is a major update of the V1 SDK. As such, there are major structural changes to how it operates. However, many aspects are still quite similar to V1. Follow this migration guide to upgrade an application developed with V1 of the SDK to V2 with minimal fuss. ## Imports @@ -12,12 +12,11 @@ If you are migrating from V1, and are using the Data API filter builder (from `p ## Authentication -In Version 1, a single client was created for all APIs, -`client=api.ClientV1(api_key=API_KEY)`. To authenticate automatically in V2, use an API key stored in the `PL_API_KEY` environment variable by adding `planet.Auth.from_env(PL_API_KEY).write()` to the first line of your script. For other methods for authenticating against the SDK, check out [Authenticate with the Planet server](quick-start-guide/#authenticate-with-the-planet-server). +If you have your API key stored in the `PL_API_KEY` environment variable you will be automatically authenticated to the V2 API, similar to how V1 worked. For other methods for authenticating against the V2 SDK, check out [Authenticate with the Planet server](quick-start-guide/#authenticate-with-the-planet-server). ## Session for all communication -In Version 2, sessions are used to manage all communication with the Planet APIs. This provides for multiple asynchronous connections. An API-specific client is created. This client manages polling and downloading, along with any other capabilities provided by the API. +In Version 2, sessions are used to manage all communication with the Planet APIs. This provides for multiple asynchronous connections. For each API, there is a specific client object. This client manages polling and downloading, along with any other capabilities provided by the API. Each client now requires a `Session` object, which stores connection information and authentication. @@ -25,20 +24,38 @@ The best way of doing this is wrapping any code that invokes a client class in a ```python async with Session() as session: - client = OrdersClient(session) - result = await client.create_order(order) + client = OrdersClient(session) + result = await client.create_order(order) # Process result ``` -For more information about Session, refer to the [SDK user guide](../../python/sdk-guide/#session). +For more information about Session, refer to the [Python SDK User Guide](../../python/sdk-guide/#session). ## Asynchronous Methods With the V1 client, all communication was synchronous. Asynchronous bulk support was provided with the `downloader` module. There was no built-in support for polling when an order was ready to download or tracking when an order was downloaded. -In V2, all `*Client` methods (for example, `DataClient().quick_search`, `OrderClient().create_order`) are asynchronous. Any functions that call such methods must include `async` in their definition. To invoke asynchronous methods from synchronous code, you can wrap the async method calls in `asyncio.run()`. +In V2, all `*Client` methods (for example, `DataClient().quick_search`, `OrderClient().create_order`) are asynchronous. Any functions that call such methods must include `async` in their definition. To invoke asynchronous methods from synchronous code, you can wrap the async method calls in `asyncio.run()`. The following is an example of using async with session. -For more details on interacting with the asynchronous portions of the SDK, refer to the [SDK user guide](../../python/sdk-guide/#session). +```python +import asyncio +from datetime import datetime +from planet import Session, DataClient +from planet import data_filter as filters + +async def do_search(): + async with Session() as session: + client = DataClient(session) + date_filter = filters.date_range_filter('acquired', gte=datetime.fromisoformat("2022-11-18"), lte=datetime.fromisoformat("2022-11-21")) + cloud_filter = filters.range_filter('cloud_cover', lte=0.1) + download_filter = filters.permission_filter() + search_results = await client.search(["PSScene"], filters.and_filter([date_filter, cloud_filter, download_filter])) + return [item async for item in search_results] + +items = asyncio.run(do_search()) +``` + +For more details on interacting with the asynchronous portions of the SDK, refer to the [Python SDK User Guide](../../python/sdk-guide/#session). ## Data API The Data API portion of SDK V2 is quite similar to V1, although some filters have been renamed for consistency (also reference the note on imports): From c7e4a77badc4c08f3d818f2a2150830ff7409b69 Mon Sep 17 00:00:00 2001 From: JuLee Burdekin <91982271+JuLeeAtPlanet@users.noreply.github.com> Date: Mon, 28 Nov 2022 14:51:50 -0800 Subject: [PATCH 5/7] Update docs/get-started/upgrading.md Co-authored-by: Jennifer Reiber Kyle --- docs/get-started/upgrading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-started/upgrading.md b/docs/get-started/upgrading.md index 5eb7d4dcb..1ae545ec4 100644 --- a/docs/get-started/upgrading.md +++ b/docs/get-started/upgrading.md @@ -35,7 +35,7 @@ For more information about Session, refer to the [Python SDK User Guide](../../p With the V1 client, all communication was synchronous. Asynchronous bulk support was provided with the `downloader` module. There was no built-in support for polling when an order was ready to download or tracking when an order was downloaded. -In V2, all `*Client` methods (for example, `DataClient().quick_search`, `OrderClient().create_order`) are asynchronous. Any functions that call such methods must include `async` in their definition. To invoke asynchronous methods from synchronous code, you can wrap the async method calls in `asyncio.run()`. The following is an example of using async with session. +In V2, all `*Client` methods (for example, `DataClient().search_aiter`, `OrderClient().create_order`) are asynchronous. Any functions that call such methods must include `async` in their definition. To invoke asynchronous methods from synchronous code, you can wrap the async method calls in `asyncio.run()`. The following is an example of using async with session. ```python import asyncio From 322da8ccb438f363f0a8180b4f282fafff2125b1 Mon Sep 17 00:00:00 2001 From: JuLee Burdekin <91982271+JuLeeAtPlanet@users.noreply.github.com> Date: Mon, 28 Nov 2022 14:52:00 -0800 Subject: [PATCH 6/7] Update docs/get-started/upgrading.md Co-authored-by: Jennifer Reiber Kyle --- docs/get-started/upgrading.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/get-started/upgrading.md b/docs/get-started/upgrading.md index 1ae545ec4..f5af5d9a6 100644 --- a/docs/get-started/upgrading.md +++ b/docs/get-started/upgrading.md @@ -73,10 +73,9 @@ planet.api.ClientV1().quick_search(filters.build_search_request(all_filters, ["P Is now -```console +```python async with Session() as session: -planet.DataClient(session).quick_search(["PSScene"], all_filters) -``` + items_aiter = planet.DataClient(session).search_aiter(["PSScene"], all_filters) ## Orders API From 93d184f899f1b4f019877ff5943d6a25062f54a4 Mon Sep 17 00:00:00 2001 From: JuLee Burdekin <91982271+JuLeeAtPlanet@users.noreply.github.com> Date: Mon, 28 Nov 2022 14:52:08 -0800 Subject: [PATCH 7/7] Update docs/get-started/upgrading.md Co-authored-by: Jennifer Reiber Kyle --- docs/get-started/upgrading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-started/upgrading.md b/docs/get-started/upgrading.md index f5af5d9a6..f65de2623 100644 --- a/docs/get-started/upgrading.md +++ b/docs/get-started/upgrading.md @@ -67,7 +67,7 @@ The Data API portion of SDK V2 is quite similar to V1, although some filters hav `filters.build_seach_request` no longer exists, and has instead been integrated into the replacement for `client.quick_seach`. For example: -```console +```python planet.api.ClientV1().quick_search(filters.build_search_request(all_filters, ["PSScene"])) ```