planetlabs · jreiberkyle · Mar 23, 2021 · Jan 26, 2021 · Jan 27, 2021 · Jan 27, 2021
diff --git a/.travis.yml b/.travis.yml
@@ -1,8 +1,8 @@
 language: python
 python:
-  - "3.6"
   - "3.7"
   - "3.8"
+  - "3.9"
 cache:
   directories:
     - $HOME/.cache/pip

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 [![Build Status](https://travis-ci.org/planetlabs/planet-client-python.svg?branch=master)](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
+the api key with the flag `-k` or `--api-key` (TODO: link to cli documentation
+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:
+        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):
+    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
+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)
+
+
+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:
+        client = planet.OrdersClient(ps)
+        await asyncio.gather(
+            create_and_download(iowa_order, client),
+            create_and_download(oregon_order, client)
+        )
+
+asyncio.run(main())
+```
+[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)
diff --git a/example_output.md b/example_output.md
@@ -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.
+```
+
diff --git a/planet/__init__.py b/planet/__init__.py
@@ -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
+
+__all__ = [
+    Session,
+    OrdersClient,
+    Order,
+    OrderDetails,
+    Product,
+    Notifications,
+    Delivery,
+    AmazonS3Delivery,
+    AzureBlobStorageDelivery,
+    GoogleCloudStorageDelivery,
+    GoogleEarthEngineDelivery,
+    Tool
+]
diff --git a/planet/api/__init__.py b/planet/api/__init__.py
@@ -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
 
 __all__ = [
+    Session,
     OrdersClient
 ]
diff --git a/planet/api/auth.py b/planet/api/auth.py