-
Notifications
You must be signed in to change notification settings - Fork 95
Move v2 orders client over to async #240
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 34 commits
b82e55c
8fffc3c
fca5990
fbfb824
377c3b1
1daab03
8cd4828
27590fe
51fe020
3092019
ee0c418
670ca5c
0e45064
e0db54b
ccac3f0
b59b328
534f184
75c8208
8f93139
f87e393
866ca40
710c49f
79b799d
7abfad6
410aee8
88fb4e5
35d2ddd
4fd89a7
a33ac22
69dfa26
e934584
37df69e
61d38ad
018d38a
8307e74
3f117b2
ba19a61
e476019
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,8 +1,8 @@ | ||
language: python | ||
python: | ||
- "3.6" | ||
- "3.7" | ||
- "3.8" | ||
- "3.9" | ||
cache: | ||
directories: | ||
- $HOME/.cache/pip | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,7 +2,7 @@ | |
|
||
[](https://travis-ci.org/planetlabs/planet-client-python) | ||
|
||
Python client library and CLI for Planet's public APIs. | ||
Python client library and Command-Line Interface (CLI) for Planet's APIs. | ||
|
||
The client provides access to the following Planet APIs: | ||
* [analytics](https://developers.planet.com/docs/analytics/) | ||
|
@@ -14,7 +14,7 @@ The client provides access to the following Planet APIs: | |
|
||
### Prerequisites | ||
|
||
* Python version 3.6+ | ||
* Python version 3.7+ | ||
|
||
### Install package | ||
|
||
|
@@ -28,31 +28,161 @@ flag is highly recommended for those new to [pip](https://pip.pypa.io). | |
A PEX executable (Windows not supported) and source releases are | ||
[here](https://github.com/planetlabs/planet-client-python/releases/latest). | ||
|
||
## Documentation | ||
## Authentication | ||
|
||
Online documentation: | ||
https://planetlabs.github.io/planet-client-python/index.html | ||
Planet's APIs require an account for use. | ||
[Sign up here](https://www.planet.com/explorer/?signup). | ||
|
||
Documentation is also provided for download | ||
[here](https://github.com/planetlabs/planet-client-python/releases/latest). | ||
Authentication information can be obtained and stored locally with the CLI | ||
`planet init` command. Both the Python library and CLI will default to using | ||
the stored authentication information, if available (not yet implemented, see | ||
issues #244 and #248). | ||
|
||
Additionally, authentication information can be provided to the CLI by | ||
storing the api key in the environmental variable `PL_API_KEY` or by specifying | ||
sarasafavi marked this conversation as resolved.
Show resolved
Hide resolved
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think "environmental variable" could be confusing as a non-standard term compared to "environment variable". There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. yes, let's use |
||
the api key with the flag `-k` or `--api-key` (TODO: link to cli documentation | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is this a leftover TODO? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. this should also go away with removal of CLI docs |
||
here). | ||
|
||
## Development | ||
## Quick Start | ||
|
||
To contribute or develop with this library, see | ||
[CONTRIBUTING](https://github.com/planetlabs/planet-client-python/CONTRIBUTING.md) | ||
### Python Library Usage | ||
|
||
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. | ||
|
||
```python | ||
import asyncio | ||
import os | ||
|
||
import planet | ||
|
||
API_KEY = os.getenv('PL_API_KEY') | ||
|
||
image_ids = ['3949357_1454705_2020-12-01_241c'] | ||
order_details = planet.OrderDetails( | ||
'test_order', | ||
[planet.Product(image_ids, 'analytic', 'psorthotile')] | ||
) | ||
|
||
async def create_order(order_details): | ||
async with planet.Session(auth=(API_KEY, '')) as ps: | ||
jreiberkyle marked this conversation as resolved.
Show resolved
Hide resolved
|
||
client = planet.OrdersClient(ps) | ||
return await client.create_order(order_details) | ||
|
||
oid = asyncio.run(create_order(order_details)) | ||
print(oid) | ||
``` | ||
|
||
## API Key | ||
Not into async? No problem. Just wrap the library and async operations together | ||
and call from your synchronous code. | ||
|
||
The API requires an account for use. [Signup here](https://www.planet.com/explorer/?signup). | ||
```python | ||
def sync_create_order(order_details): | ||
jreiberkyle marked this conversation as resolved.
Show resolved
Hide resolved
|
||
return asyncio.run(create_order(order_details)) | ||
|
||
This can be provided via the environment variable `PL_API_KEY` or the flag `-k` or `--api-key`. | ||
oid = sync_create_order(order_details) | ||
print(oid) | ||
``` | ||
|
||
Using `planet init` your account credentials (login/password) can be used to obtain the api key. | ||
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 | ||
sarasafavi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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 | ||
[Determine need for synchronous support](https://github.com/planetlabs/planet-client-python/issues/251) | ||
sarasafavi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
|
||
Why async? Because things get *really cool* when you want to work with multiple | ||
orders. Here's 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.) | ||
|
||
|
||
```python | ||
import asyncio | ||
import os | ||
|
||
import planet | ||
|
||
API_KEY = os.getenv('PL_API_KEY') | ||
|
||
iowa_aoi = { | ||
"type": "Polygon", | ||
"coordinates": [[ | ||
[-91.198465, 42.893071], | ||
[-91.121931, 42.893071], | ||
[-91.121931, 42.946205], | ||
[-91.198465, 42.946205], | ||
[-91.198465, 42.893071]]] | ||
} | ||
|
||
iowa_images = [ | ||
'20200925_161029_69_2223', | ||
'20200925_161027_48_2223' | ||
] | ||
iowa_order = planet.OrderDetails( | ||
'iowa_order', | ||
[planet.Product(iowa_images, 'analytic', 'PSScene4Band')], | ||
tools=[planet.Tool('clip', {'aoi': iowa_aoi})] | ||
) | ||
|
||
oregon_aoi = { | ||
"type": "Polygon", | ||
"coordinates": [[ | ||
[-117.558734, 45.229745], | ||
[-117.452447, 45.229745], | ||
[-117.452447, 45.301865], | ||
[-117.558734, 45.301865], | ||
[-117.558734, 45.229745]]] | ||
} | ||
|
||
oregon_images = [ | ||
'20200909_182525_1014', | ||
'20200909_182524_1014' | ||
] | ||
oregon_order = planet.OrderDetails( | ||
'oregon_order', | ||
[planet.Product(oregon_images, 'analytic', 'PSScene4Band')], | ||
tools=[planet.Tool('clip', {'aoi': oregon_aoi})] | ||
) | ||
|
||
|
||
async def create_and_download(order_detail, client): | ||
oid = await client.create_order(order_detail) | ||
print(oid) | ||
state = await client.poll(oid, verbose=True) | ||
print(state) | ||
filenames = await client.download_order(oid, progress_bar=True) | ||
print(f'downloaded {oid}, {len(filenames)} files downloaded.') | ||
|
||
|
||
async def main(): | ||
async with planet.Session(auth=(API_KEY, '')) as ps: | ||
jreiberkyle marked this conversation as resolved.
Show resolved
Hide resolved
|
||
client = planet.OrdersClient(ps) | ||
await asyncio.gather( | ||
create_and_download(iowa_order, client), | ||
create_and_download(oregon_order, client) | ||
) | ||
|
||
asyncio.run(main()) | ||
jreiberkyle marked this conversation as resolved.
Show resolved
Hide resolved
|
||
``` | ||
[Example output](example_output.md) | ||
|
||
|
||
# Example CLI Usage | ||
## CLI Usage (Not yet Implemented) | ||
|
||
**Hint:** autocompletion can be enabled in some shells using: | ||
```console | ||
|
@@ -74,3 +204,16 @@ Specific command help: | |
```console | ||
$ planet data download --help | ||
``` | ||
|
||
## Documentation | ||
|
||
Online documentation: | ||
https://planetlabs.github.io/planet-client-python/index.html | ||
|
||
Documentation is also provided for download | ||
[here](https://github.com/planetlabs/planet-client-python/releases/latest). | ||
|
||
## Development | ||
|
||
To contribute or develop with this library, see | ||
[CONTRIBUTING](https://github.com/planetlabs/planet-client-python/CONTRIBUTING.md) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,66 @@ | ||
``` | ||
a27c63c9-a076-4db2-a2e3-c1ff35655cbd | ||
5d5892b5-3ec0-4df7-9852-a27a40baf0c1 | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: queued | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: queued | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: running | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
order a27c63c9-a076-4db2-a2e3-c1ff35655cbd state: success | ||
success | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: running | ||
./20200909_182525_1014_3B_AnalyticMS_clip.tif: 100%|███████████████████████████████████████████████████████████████████████████████████| 35.8k/35.8k [00:03<00:00, 9.97MB/s] | ||
./20200909_182525_1014_metadata.json: 100%|████████████████████████████████████████████████████████████████████████████████████████████| 0.00k/0.00k [00:00<00:00, 4.08MB/s] | ||
./20200909_182525_1014_3B_AnalyticMS_metadata_clip.xml: 100%|██████████████████████████████████████████████████████████████████████████| 0.01k/0.01k [00:00<00:00, 7.12MB/s] | ||
./20200909_182525_1014_3B_AnalyticMS_DN_udm_clip.tif: 100%|████████████████████████████████████████████████████████████████████████████| 0.06k/0.06k [00:00<00:00, 1.81MB/s] | ||
./20200909_182524_1014_3B_AnalyticMS_clip.tif: 100%|███████████████████████████████████████████████████████████████████████████████████| 33.6k/33.6k [00:02<00:00, 12.2MB/s] | ||
./20200909_182524_1014_3B_AnalyticMS_DN_udm_clip.tif: 100%|████████████████████████████████████████████████████████████████████████████| 0.08k/0.08k [00:00<00:00, 1.78MB/s] | ||
order 5d5892b5-3ec0-4df7-9852-a27a40baf0c1 state: success | ||
success | ||
./20200909_182524_1014_3B_AnalyticMS_metadata_clip.xml: 100%|██████████████████████████████████████████████████████████████████████████| 0.01k/0.01k [00:00<00:00, 9.77MB/s] | ||
./20200909_182524_1014_metadata.json: 100%|████████████████████████████████████████████████████████████████████████████████████████████| 0.00k/0.00k [00:00<00:00, 3.12MB/s] | ||
./manifest.json: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 0.00k/0.00k [00:00<00:00, 8.29MB/s] | ||
downloaded a27c63c9-a076-4db2-a2e3-c1ff35655cbd, 9 files downloaded. | ||
./20200925_161029_69_2223_3B_AnalyticMS_metadata_clip.xml: 100%|███████████████████████████████████████████████████████████████████████| 0.01k/0.01k [00:00<00:00, 8.93MB/s] | ||
./20200925_161029_69_2223_3B_AnalyticMS_clip.tif: 100%|████████████████████████████████████████████████████████████████████████████████| 21.3k/21.3k [00:01<00:00, 12.0MB/s] | ||
./20200925_161029_69_2223_3B_AnalyticMS_DN_udm_clip.tif: 100%|█████████████████████████████████████████████████████████████████████████| 0.07k/0.07k [00:00<00:00, 1.99MB/s] | ||
./20200925_161029_69_2223_metadata.json: 100%|█████████████████████████████████████████████████████████████████████████████████████████| 0.00k/0.00k [00:00<00:00, 1.78MB/s] | ||
./20200925_161027_48_2223_metadata.json: 100%|█████████████████████████████████████████████████████████████████████████████████████████| 0.00k/0.00k [00:00<00:00, 2.24MB/s] | ||
./20200925_161027_48_2223_3B_AnalyticMS_clip.tif: 100%|████████████████████████████████████████████████████████████████████████████████| 33.9k/33.9k [00:02<00:00, 11.9MB/s] | ||
./20200925_161027_48_2223_3B_AnalyticMS_DN_udm_clip.tif: 100%|█████████████████████████████████████████████████████████████████████████| 0.08k/0.08k [00:00<00:00, 1.85MB/s] | ||
./20200925_161027_48_2223_3B_AnalyticMS_metadata_clip.xml: 100%|███████████████████████████████████████████████████████████████████████| 0.01k/0.01k [00:00<00:00, 11.7MB/s] | ||
./manifest.json: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 0.00k/0.00k [00:00<00:00, 8.52MB/s] | ||
downloaded 5d5892b5-3ec0-4df7-9852-a27a40baf0c1, 9 files downloaded. | ||
``` | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -11,3 +11,26 @@ | |
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
# See the License for the specific language governing permissions and | ||
# limitations under the License. | ||
from .api.http import Session | ||
from .api.models import Order | ||
from .api.orders import OrdersClient | ||
from .api.order_details import ( | ||
OrderDetails, Product, Notifications, Delivery, AmazonS3Delivery, | ||
AzureBlobStorageDelivery, GoogleCloudStorageDelivery, | ||
GoogleEarthEngineDelivery, Tool) | ||
from .api.__version__ import __version__ # NOQA | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This import appears unused and can be removed. |
||
|
||
__all__ = [ | ||
Session, | ||
OrdersClient, | ||
Order, | ||
OrderDetails, | ||
Product, | ||
Notifications, | ||
Delivery, | ||
AmazonS3Delivery, | ||
AzureBlobStorageDelivery, | ||
GoogleCloudStorageDelivery, | ||
GoogleEarthEngineDelivery, | ||
Tool | ||
] |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -12,9 +12,11 @@ | |
# See the License for the specific language governing permissions and | ||
# limitations under the License. | ||
|
||
from .http import Session | ||
from .orders import OrdersClient | ||
from .__version__ import __version__ # NOQA | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This looks like it clobbers the module and makes
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This import is also unused and can be removed. |
||
|
||
__all__ = [ | ||
Session, | ||
OrdersClient | ||
] |
This file was deleted.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This documented behavior of
planet init
is not synchronized with the actual behavior in this branch. What are thoughts about getting the behavior and the documentation to play nice?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
agree, this PR doesn't yet implement CLI behavior. @jreiberkyle let's remove all CLI-related documentation from the PR and we can put it back in down the road.