Planet Software Development Kit (SDK) for Python.
The default branch (main) of this repo is for the Planet SDK for Python, a complete rewrite and upgrade from the original Planet Python Client. If you are looking for the source code to that library see the v1 branch.
The Planet SDK for Python is in 'pre-release' stages, working towards an initial release around July. Active development is tracked in the Planet SDK for Python Project. The initial release will support Orders, Data and Subscription API's in the command-line interface, with corresponding Python libraries. We expect 'beta' milestones to be released in some form for each of the API's. After the initial July release there will be additional work to support the remaining Planet API's (analytics, basemaps and tasking).
Full documentation is not yet hosted online but can be built and hosted locally
(see CONTRIBUTING.md) or can be read from source in the
[docs](docs/) directory.
The Planet SDK for Python allows Python developers to write software that makes use of the following Planet APIs:
- orders
- data (not yet implemented)
- 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. 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:
>>> 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))Not into async? No problem. Just wrap the library and async operations together and call from your synchronous code.
>>> def sync_create_order(order_details):
... return asyncio.run(create_order(order_details))
>>>
>>> oid = sync_create_order(order_details)When using asyncio.run to develop synchronous code with the async library,
keep in mind this excerpt from the
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.
Why async? Because things get really cool when you want to work with multiple orders. See 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 was used to define the AOIs and get the image ids.)
Install with pip:
$ python -m pip install . The --user flag is highly recommended for those new to pip.
The Planet SDK for Python requires Python 3.7+.
Planet's APIs require an account for use. Sign up here.
To contribute or develop with this library, see CONTRIBUTING.md.