Features client (planetlabs#1073)

* WIP Features client: list_collections, create_collection, list_features, create_features

* Apply suggestions from code review

* added docstrings for features methods

* updates to methods, tests, docs and sync client

* fix typo in features client docstring

* features cli and tests

* make sure create tests are post requests

* update cli commands

* add compact mode to collections list

* add get_feature functionality

* use items instead of "features"

* combine cli decorators, remove geojson from docs

* update yapf config and yapf everything

* yapf everything for new rule

* fix top level values

* use Union instead of union operator

* update orders formatting

* fix formatting with yapf v0.43.0

* pin yapf to 0.43.0

* don't use a session fixture for features tests

* explicitly set API Key for test sessions

* split out collections and items into subgroups

* lint fixes

* add limit to list functions

* remove geojson from docs

* add limit to sync features client

* format

* update help text

* add Features API to sdk guides

* update actions/cache gh action

* refactor decorator stack

* remove geom type handling, additions to sdk guide

* lint fix

* add note about collection_id

* add note about reservations

* link to features API docs

* assertion no longer always true

* put back Geometry > Feature upgrade

* lint

---------

Co-authored-by: Steve Hillier <steve.hillier@planet.com>

Author: tbarsballe

.github/workflows/autopublish-testpypi.yml

@@ -19,7 +19,7 @@ jobs:
           python-version: 3.12
 
       - name: Pip cache
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: ~/.cache/pip
           key: ${{ runner.os }}-pip

.github/workflows/publish-pypi.yml

@@ -17,7 +17,7 @@ jobs:
           python-version: 3.12
 
       - name: Pip cache
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: ~/.cache/pip
           key: ${{ runner.os }}-pip

.github/workflows/test.yml

@@ -14,7 +14,7 @@ jobs:
       with:
         python-version: 3.12
     - name: Pip cache
-      uses: actions/cache@v2
+      uses: actions/cache@v4
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip
@@ -36,7 +36,7 @@ jobs:
       with:
         python-version: 3.12
     - name: Pip cache
-      uses: actions/cache@v2
+      uses: actions/cache@v4
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip
@@ -64,7 +64,7 @@ jobs:
         python-version: ${{ matrix.python-version }}
         allow-prereleases: true
     - name: Pip cache
-      uses: actions/cache@v2
+      uses: actions/cache@v4
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip
@@ -86,7 +86,7 @@ jobs:
       with:
         python-version: 3.12
     - name: Pip cache
-      uses: actions/cache@v2
+      uses: actions/cache@v4
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip
@@ -108,7 +108,7 @@ jobs:
       with:
         python-version: 3.12
     - name: Pip cache
-      uses: actions/cache@v2
+      uses: actions/cache@v4
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip

docs/python/async-sdk-guide.md

@@ -458,6 +458,59 @@ async def download_and_validate():
         cl.validate_checksum(asset, path)
 ```
 
+### Features API Collections and Features
+
+The Python SDK now supports Features API Collections and Features (note: in the SDK and API, Features are often referred to as items in a collection).
+
+Collections and Features/items that you create in in the SDK will be visible in Features API and Features Manager.
+
+#### Creating a collection
+
+You can use the Python SDK to create Features API collections. 
+
+```python
+async with Session() as sess:
+  client = FeaturesClient(sess)
+  new_collection = await client.create_collection(title="my collection", description="a new collection")
+```
+
+#### Listing collections
+
+```python
+async with Session() as sess:
+  client = FeaturesClient(sess)
+  collections = client.list_collections()
+  async for collection in collections:
+    print(collection)
+```
+
+#### Listing features/items in a collection
+
+```python
+async with Session() as sess:
+  client = FeaturesClient(sess)
+  items = client.list_items(collection_id)
+  async for item in items:
+    print(items)
+```
+
+#### Using items as geometries for other methods
+
+You can pass collection items/features directly to other SDK methods. Any method that requires a geometry will accept
+a Features API Feature.
+
+```python
+async with Session() as sess:
+  client = FeaturesClient(sess)
+  items = client.list_items(collection_id)
+  example_feature = await anext(items)
+
+  data_client = DataClient(sess)
+  results = data_client.search(["PSScene"], geometry=example_feature, limit=1)
+  async for result in results:
+    print(result)
+```
+
 ## API Exceptions
 
 When errors occur, the Planet SDK for Python exception hierarchy is as follows:

docs/python/sdk-guide.md

@@ -264,6 +264,56 @@ delivery = amazon_s3(ACCESS_KEY_ID, SECRET_ACCESS_KEY, "test", "us-east-1")
 subscription = pl.subscriptions.create_subscription(request)
 ```
 
+### Features API Collections and Features
+
+The Python SDK now supports [Features API](https://developers.planet.com/docs/apis/features/) Collections and Features (note: in the SDK and API, Features are often referred to as items in a collection).
+
+Collections and Features/items that you create in in the SDK will be visible in Features API and Features Manager.
+
+#### Creating a collection
+
+You can use the Python SDK to create feature collections in the Features API. 
+
+```python
+new_collection = pl.features.create_collection(title="my collection", description="a new collection")
+```
+
+#### Listing collections
+
+```python
+collections = pl.features.list_collections()
+for collection in collections:
+  print(collection)
+```
+
+#### Listing features/items in a collection
+
+```python
+items = pl.features.list_items(collection_id)
+for item in items:
+  print(item)
+
+```
+
+#### Using items as geometries for other methods
+
+You can pass collection items/features directly to other SDK methods. Any method that requires a geometry will accept
+a Features API Feature.
+
+!!!note
+  When passing a Features API Feature to other methods, the [feature ref](https://developers.planet.com/docs/apis/features/feature-references/) will be used. This means any searches or subscriptions you create will be linked to your feature.
+
+```python
+# collection_id: the ID of a collection in Features API
+
+items = pl.features.list_items(collection_id)
+example_feature = next(items)
+results = pl.data.search(["PSScene"], geometry=example_feature)
+```
+
+!!!note
+Reserving quota for features is currently not supported in the SDK. However, you may create features within the SDK and then use [Features Manager](https://planet.com/features) to reserve quota.
+
 ## API Exceptions
 
 When errors occur, the Planet SDK for Python exception hierarchy is as follows:

examples/orders_create_and_download_multiple_orders.py

@@ -33,8 +33,7 @@ def create_requests():
     # The Orders API will be asked to mask, or clip, results to
     # this area of interest.
     iowa_aoi = {
-        "type":
-        "Polygon",
+        "type": "Polygon",
         "coordinates": [[[-91.198465, 42.893071], [-91.121931, 42.893071],
                          [-91.121931, 42.946205], [-91.198465, 42.946205],
                          [-91.198465, 42.893071]]]
@@ -54,8 +53,7 @@ def create_requests():
         tools=[planet.order_request.clip_tool(aoi=iowa_aoi)])
 
     oregon_aoi = {
-        "type":
-        "Polygon",
+        "type": "Polygon",
         "coordinates": [[[-117.558734, 45.229745], [-117.452447, 45.229745],
                          [-117.452447, 45.301865], [-117.558734, 45.301865],
                          [-117.558734, 45.229745]]]

planet/__init__.py

@@ -16,7 +16,7 @@
 from . import data_filter, order_request, reporting, subscription_request
 from .__version__ import __version__  # NOQA
 from .auth import Auth
-from .clients import DataClient, OrdersClient, SubscriptionsClient  # NOQA
+from .clients import DataClient, FeaturesClient, OrdersClient, SubscriptionsClient  # NOQA
 from .io import collect
 from .sync import Planet
 
@@ -25,6 +25,7 @@
     'collect',
     'DataClient',
     'data_filter',
+    'FeaturesClient',
     'OrdersClient',
     'order_request',
     'Planet',

planet/auth.py

@@ -187,7 +187,7 @@ def decode_response(response):
         return jwt.decode(token, options={'verify_signature': False})
 
 
-class APIKeyAuthException(Exception):
+class APIKeyAuthException(AuthException):
     """exceptions thrown by APIKeyAuth"""
     pass
 

planet/cli/cli.py

@@ -20,7 +20,7 @@
 
 import planet
 
-from . import auth, collect, data, orders, subscriptions
+from . import auth, collect, data, orders, subscriptions, features
 
 LOGGER = logging.getLogger(__name__)
 
@@ -78,3 +78,4 @@ def _configure_logging(verbosity):
 main.add_command(orders.orders)  # type: ignore
 main.add_command(subscriptions.subscriptions)  # type: ignore
 main.add_command(collect.collect)  # type: ignore
+main.add_command(features.features)

planet/cli/cmds.py

@@ -14,10 +14,71 @@
 """Decorators for Click commands"""
 import asyncio
 from functools import wraps
+from typing import Callable, Optional
 
 import click
 
 from planet import exceptions
+from planet.cli.options import pretty
+
+
+def command(group: click.Group,
+            name: Optional[str] = None,
+            extra_args: list[Callable] = []):
+    """a decorator that adds common utilities/options to a click command
+
+    usage:
+
+    @command(features)  # pass a group created with @click.group
+    def my_command():
+        ...
+
+    this single decorator replaces a list of decorators we would otherwise
+    add to every function e.g.:
+
+    @features.command
+    @coro
+    @translate_exceptions
+    @click.pass_context
+    def my_command():
+        ...
+    """
+
+    # the decorators to add to the function **when the function is run**
+    # (as opposed to when the function is registered as a click command)
+    decorators = [
+        coro,
+        translate_exceptions,
+        click.pass_context,
+        pretty,
+    ] + extra_args
+
+    # since we want to use `command` as a function with an arg: `@command(group)`,
+    # we need to create and return an "real" decorator that takes the function as its
+    # arg.
+    def decorator(f):
+
+        # run any click-specific registration decorators
+        for fn in decorators:
+            f = fn(f)
+
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            cmd = f
+
+            # wrap cmd with all the default decorators
+            for d in decorators:
+                cmd = d(f)
+
+            return cmd(*args, **kwargs)
+
+        # register the whole thing as a Click command.
+        # Doing this last (outside the wrapper) allows click to
+        # pick up the options/arguments added to the command by e.g.
+        # `@click.option()`
+        return group.command(name=name)(wrapper)
+
+    return decorator
 
 
 # https://github.com/pallets/click/issues/85#issuecomment-503464628
@@ -60,6 +121,6 @@ def wrapper(*args, **kwargs):
                 'Auth information does not exist or is corrupted. Initialize '
                 'with `planet auth init`.')
         except exceptions.PlanetError as ex:
-            raise click.ClickException(ex)
+            raise click.ClickException(str(ex))
 
     return wrapper

planet/cli/data.py

@@ -52,7 +52,7 @@ async def data_client(ctx):
 @click.option('-u',
               '--base-url',
               default=None,
-              help='Assign custom base Orders API URL.')
+              help='Assign custom base Data API URL.')
 def data(ctx, base_url):
     """Commands for interacting with the Data API"""
     ctx.obj['BASE_URL'] = base_url