Merge pull request #897 from planetlabs/rc3dev-fixes

merge rc3dev-fixes into main and continue dev in main so docs can be built

Author: jreiberkyle

CHANGES.txt

@@ -1,3 +1,9 @@
+2.0.0-rc.3 (TBD)
+
+Changed:
+- Session class unit tests are marked to be run within an event loop and are
+  no longer skipped (#881).
+
 2.0.0-rc.2 (2023-03-15)
 
 Added:

docs/cli/cli-intro.md

@@ -173,7 +173,7 @@ represent GeoJSON features, the JSON blob is a GeoJSON FeatureCollection.
 Otherwise, the JSON blob is a list of the individual results.
 
 ```console
-$ planet data search PSScene | planet collect -
+planet data search PSScene | planet collect -
 ```
 
 This gives you a fully compliant GeoJSON FeatureCollection, which is 

docs/cli/cli-orders.md

@@ -36,7 +36,7 @@ You can also filter orders by their `state`, which can be useful to just see ord
 progress:
 
 ```console
-planet orders --state running
+planet orders list --state running
 ```
 
 The other options are queued, failed, success, partial and cancelled.
@@ -100,7 +100,7 @@ To create an order you need a name, a [bundle](https://developers.planet.com/api
 First lets get the ID of an item you have download access to, using the Data API: 
 
 ```
-planet data filter | planet data search PSScene --limit 1 - | jq -r .id
+planet data filter | planet data search PSScene --limit 1 --filter - | jq -r .id 
 ```
 
 If you don't have access to PlanetScope data then replace PSScene with SkySatCollect.
@@ -515,7 +515,7 @@ One cool little trick is that you can even stream in the JSON directly with `cur
 
 ```console
 curl -s https://raw.githubusercontent.com/planetlabs/planet-client-python/main/docs/cli/request-json/tools-clip-composite.json \
-| planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Streaming Clip & Composite' \
+| planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Streaming Clip & Composite' --no-stac \
  20220605_124027_64_242b,20220605_124025_34_242b --tools - | planet orders create - 
 ```
 
@@ -550,7 +550,7 @@ STAC metadata by default, as the STAC files are small and often more useful than
 You can easily turn off STAC output request with the `--no-stac` command:
 
 ```
-planet orders request PSScene visual --name 'No STAC' --no-stac --id 20220605_124027_64_242b 
+planet orders request --item-type PSScene --bundle visual --name 'No STAC' --no-stac 20220605_124027_64_242b
 ```
 
 Currently this needs to be done for any 'composite' operation, as STAC output from composites is not yet 
@@ -672,7 +672,7 @@ image that was published:
 
 ```console
 planet orders request --item-type SkySatCollect --bundle analytic --name 'SkySat Latest' \
- `planet data filter | planet data search SkySatCollect --sort 'acquired desc' --limit 1 - | jq -r .id` \
+ `planet data filter | planet data search SkySatCollect --sort 'acquired desc' --limit 1 --filter - | jq -r .id` \
 | planet orders create - 
 ```
 
@@ -681,7 +681,7 @@ Or get the 5 latest cloud free images in an area and create an order that clips
 
 ```console
 ids=`planet data filter --geom geometry.geojson --range clear_percent gt 90 | planet data \
-search PSScene --limit 5 - | jq -r .id | tr '\n' , | sed 's/.$//'`
+search PSScene --limit 5 --filter - | jq -r .id | tr '\n' , | sed 's/.$//'`
 planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Clipped Scenes'  \
  $ids --clip geometry.geojson | planet orders create -
 ```

docs/cli/cli-tips-tricks.md

@@ -301,9 +301,11 @@ planet orders list | jq -rs '.[3] | "\(.id) \(.created_on) \(.name) \(.state)"'
 
 * Use jq to show just orders that have a given item type, like just skysat.
 
-planet orders list | jq -rs '.[] | "\(.id) \(.created_on) \(.state) \(.products[0].item_type)"'  will show the item type
+```console
+planet orders list | jq -rs '.[] | "\(.id) \(.created_on) \(.state) \(.products[0].item_type)"'
+```
 
-https://gist.github.com/ipbastola/2c955d8bf2e96f9b1077b15f995bdae3 has ideas for contains, but haven't got it right yet
+will show the item type https://gist.github.com/ipbastola/2c955d8bf2e96f9b1077b15f995bdae3 has ideas for contains, but haven't got it right yet
 
 * use jq to get the id of the an order by it's name
 

noxfile.py

@@ -42,7 +42,10 @@ def test(session):
     session.install(".[test]")
 
     options = session.posargs
-    session.run('pytest', '--ignore', 'examples/', '-v', *options)
+    # -W=error raises pytest warnings to errors so they are caught by CI
+    # to exclude some warnings, see
+    # https://docs.python.org/3/library/warnings.html#temporarily-suppressing-warnings
+    session.run('pytest', '--ignore', 'examples/', '-v', '-W=error', *options)
 
 
 @nox.session

planet/cli/data.py

@@ -283,7 +283,8 @@ def filter(ctx,
                 callback=check_item_types)
 @click.option('--filter',
               type=types.JSON(),
-              help='Apply specified filter to search.')
+              help="""Apply specified filter to search. Can be a json string,
+              filename, or '-' for stdin.""")
 @limit
 @click.option('--name', type=str, help='Name of the saved search.')
 @click.option('--sort',
@@ -321,32 +322,35 @@ async def search(ctx, item_types, filter, limit, name, sort, pretty):
 @click.pass_context
 @translate_exceptions
 @coro
-@click.argument('name')
 @click.argument("item_types",
                 type=types.CommaSeparatedString(),
                 callback=check_item_types)
-@click.argument("filter", type=types.JSON())
+@click.option(
+    '--filter',
+    type=types.JSON(),
+    required=True,
+    help="""Filter to apply to search. Can be a json string, filename,
+         or '-' for stdin.""")
+@click.option('--name',
+              type=str,
+              required=True,
+              help='Name of the saved search.')
 @click.option('--daily-email',
               is_flag=True,
               help='Send a daily email when new results are added.')
 @pretty
-async def search_create(ctx, name, item_types, filter, daily_email, pretty):
+async def search_create(ctx, item_types, filter, name, daily_email, pretty):
     """Create a new saved structured item search.
 
     This function outputs a full JSON description of the created search,
     optionally pretty-printed.
 
-    NAME is the name to give the search.
-
     ITEM_TYPES is a comma-separated list of item-types to search.
-
-    FILTER must be JSON and can be specified a json string, filename, or '-'
-    for stdin.
     """
     async with data_client(ctx) as cl:
-        items = await cl.create_search(name=name,
-                                       item_types=item_types,
+        items = await cl.create_search(item_types=item_types,
                                        search_filter=filter,
+                                       name=name,
                                        enable_email=daily_email)
         echo_json(items, pretty)
 

planet/clients/data.py

@@ -167,9 +167,9 @@ async def search(self,
             yield i
 
     async def create_search(self,
-                            name: str,
                             item_types: List[str],
                             search_filter: dict,
+                            name: str,
                             enable_email: bool = False) -> dict:
         """Create a new saved structured item search.
 
@@ -190,9 +190,9 @@ async def create_search(self,
 
 
         Parameters:
-            name: The name of the saved search.
             item_types: The item types to include in the search.
             search_filter: Structured search criteria.
+            name: The name of the saved search.
             enable_email: Send a daily email when new results are added.
 
         Returns:

planet/clients/orders.py

@@ -123,10 +123,10 @@ async def create_order(self, request: dict) -> dict:
         >>> from planet.order_request import build_request, product
         >>>
         >>> async def main():
-        ...     image_ids = ['3949357_1454705_2020-12-01_241c']
+        ...     image_ids = ["20200925_161029_69_2223"]
         ...     request = build_request(
         ...         'test_order',
-        ...         [product(image_ids, 'analytic', 'psorthotile')]
+        ...         [product(image_ids, 'analytic_udm2', 'psscene')]
         ...     )
         ...     async with Session() as sess:
         ...         cl = OrdersClient(sess)

planet/order_request.py

@@ -455,3 +455,61 @@ def harmonize_tool(target_sensor: str) -> dict:
         raise ClientError(e)
 
     return _tool('harmonize', {'target_sensor': target_sensor})
+
+
+def band_math_tool(b1: str,
+                   b2: Optional[str] = None,
+                   b3: Optional[str] = None,
+                   b4: Optional[str] = None,
+                   b5: Optional[str] = None,
+                   b6: Optional[str] = None,
+                   b7: Optional[str] = None,
+                   b8: Optional[str] = None,
+                   b9: Optional[str] = None,
+                   b10: Optional[str] = None,
+                   b11: Optional[str] = None,
+                   b12: Optional[str] = None,
+                   b13: Optional[str] = None,
+                   b14: Optional[str] = None,
+                   b15: Optional[str] = None,
+                   pixel_type: str = specs.BAND_MATH_PIXEL_TYPE_DEFAULT):
+    '''Specify an Orders API band math tool.
+
+    The parameters of the bandmath tool define how each output band in the
+    derivative product should be produced, referencing the product inputs’
+    original bands. Band math expressions may not reference neighboring pixels,
+    as non-local operations are not supported. The tool can calculate up to 15
+    bands for an item. Input band parameters may not be skipped. For example,
+    if the b4 parameter is provided, then b1, b2, and b3 parameters are also
+    required.
+
+    For each band expression, the bandmath tool supports normal arithmetic
+    operations and simple math operators offered in the Python numpy package.
+    (For a list of supported mathematical functions, see
+    [Bandmath supported numpy math routines](https://developers.planet.com/apis/orders/bandmath-numpy-routines/)).
+
+    One bandmath imagery output file is produced for each product bundle, with
+    output bands derived from the band math expressions. nodata pixels are
+    processed with the band math equation. These files have “_bandmath”
+    appended to their file names.
+
+    The tool passes through UDM, RPC, and XML files, and does not update values
+    in these files.
+
+    Parameters:
+        b1-b15: An expression defining how the output band should be computed.
+        pixel_type: A value indicating what the output pixel type should be.
+
+    Raises:
+        planet.exceptions.ClientError: If pixel_type is not valid.
+    '''  # noqa
+    try:
+        pixel_type = specs.get_match(pixel_type,
+                                     specs.BAND_MATH_PIXEL_TYPE,
+                                     'pixel_type')
+    except specs.SpecificationException as e:
+        raise ClientError(e)
+
+    # e.g. {"b1": "b1", "b2":"arctan(b1)"} if b1 and b2 are specified
+    parameters = dict((k, v) for k, v in locals().items() if v)
+    return _tool('bandmath', parameters)

planet/specs.py

@@ -20,7 +20,7 @@
 
 PRODUCT_BUNDLE_SPEC_NAME = 'orders_product_bundle_2023-02-24.json'
 SUPPORTED_TOOLS = [
-    'band_math',
+    'bandmath',
     'clip',
     'composite',
     'coregister',
@@ -34,6 +34,8 @@
 SUPPORTED_ARCHIVE_TYPES = ['zip']
 SUPPORTED_FILE_FORMATS = ['COG', 'PL_NITF']
 HARMONIZE_TOOL_TARGET_SENSORS = ('Sentinel-2', 'PS2')
+BAND_MATH_PIXEL_TYPE = ('Auto', '8U', '16U', '16S', '32R')
+BAND_MATH_PIXEL_TYPE_DEFAULT = 'Auto'
 
 LOGGER = logging.getLogger(__name__)